From 7075d863c26c441d5eeb48c9868a39fc2b612355 Mon Sep 17 00:00:00 2001 From: sunlei Date: Thu, 18 Jun 2026 18:45:20 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=A2=9E=E5=8A=A0NapCat=E8=AE=BE?= =?UTF-8?q?=E5=A4=87=E7=94=BB=E5=83=8F=E6=A3=80=E6=9F=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 4 ++ package.json | 1 + src/core/constants.ts | 1 + src/registerTools.ts | 20 +++++++- src/selfTest.ts | 13 ++++- src/server.ts | 3 ++ src/tools/testing.ts | 117 +++++++++++++++++++++++++++++++++++++++++- src/types.ts | 4 ++ 8 files changed, 160 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c764606..613685d 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,7 @@ - 生成页面测试用例：内置“先写用例、可视化证据、事不过三”的测试闭环。 - 生成接口测试计划：接口改动后输出真实调用命令和统一返回结构断言。 - 生成业务链路测试计划：固化 Admin 登录、博客 CRUD、QQBot 扫码/自动回复、更新登录 SSE、FFLogs 命令、系统日志可视化、Web/Playground 回跳。 +- 静态检查 NapCat 设备身份护栏：确认 API 仍保留 QQNT 可见 hostname、稳定 `02:42:*` MAC、QQNT `machine-info` 写入、持久化 runtime dir 和 `DB_TIMEZONE` 默认值。 - 生成卡点固化记录：把超时、卡进程、远程命令误写、重复失败整理成“问题点 / 稳定解法 / 后续入口 / 验证证据”，避免原样重试。 - 生成改动文档同步计划：按变更文件自动提示需要同步的 README、API、AGENTS、docs、Obsidian、skill 和 ktWorkflow 入口。 - 生成多仓库提交/推送计划：按仓库分组、建议提交信息、列出提交和推送前检查。 @@ -39,6 +40,7 @@ pnpm run obsidian-context -- --module ktWorkflow pnpm run obsidian-validate pnpm run obsidian-sync pnpm run workstream-closeout -- --title "发布闭环" --verification "Jenkins SUCCESS" --doc-sync "无需文档更新" --cleanup "cleanup-history dry-run deleted=0" --cleanup-final-deleted 0 --review "global-review findings=0" --superpowers-review "Superpowers reviewer completed; no Critical/Important findings" --problem "无新卡点" --solution "无新增稳定解法" +pnpm run napcat-device-profile-check pnpm run cleanup-history -- --dry-run pnpm run cleanup-history -- --execute pnpm run deploy-observation -- --project api --job KT-Template/KT-Template-API/main --namespace kt-prod --deployment kt-template-online-api --container api --health-url http://127.0.0.1:48085/health/runtime --smoke "curl -fsS --max-time 8 http://127.0.0.1:48085/health/runtime" @@ -93,6 +95,7 @@ pnpm run admin-login -- --url http://127.0.0.1:5999/#/auth/login | `kt_commit_plan` | 生成多仓库提交计划、建议 commit message 和检查项 | | `kt_push_plan` | 生成多仓库推送计划和远程异常提醒 | | `kt_business_test_plan` | 生成固化业务链路测试计划，包含 QQBot SSE、FFLogs 和系统日志 | +| `kt_napcat_device_profile_check` | 静态检查 API NapCat 设备身份护栏，覆盖 hostname、MAC、`machine-info`、runtime dir 和 DB timezone | | `kt_blocker_resolution` | 生成或写入卡点固化记录，提醒停止原样重试 | | `kt_remote_health_check` | 生成或执行远程只读健康检查命令 | | `kt_deploy_observation` | 生成或执行 API 发布后的部署观测，汇总 Jenkins SCM revision、K8s、Pod、`/health/runtime` 和任务 smoke 证据 | @@ -110,6 +113,7 @@ pnpm run admin-login -- --url http://127.0.0.1:5999/#/auth/login | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pnpm run admin-login` | 使用可见 Edge 打开 Admin 登录页，填写账号密码，拖动滑块，保存登录态和截图。默认账号来自初始化数据 `admin/123456`，生产或个人账号用 `KT_ADMIN_USERNAME` / `KT_ADMIN_PASSWORD` 或 CLI 参数覆盖。 | | `pnpm run global-review` | 对 KT 全部子仓库做只读全局 CodeReview 扫描，默认仅对变更文件做内容深扫，输出 JSON 复审报告，并校验 `TASKS.md` 最近记录只保留范围、关键词、验证字段、NapCat `latest` 漂移、QQBot 重型服务单测导入风险、QQBot 插件 registry/controller smoke 未 mock 具体插件实现风险、OneBot/QQ 登录态边界、NapCat 密码登录验证码 wait 阶段、日志窗口锚点、验证码状态早于日志 URL 的短轮询、验证码 pending 被状态轮询误清理、API Pod SSH 日志读取超时及清理前 pending 回归，以及普通处理中状态误吃旧验证码日志回归；明显测试占位 token 不报凭据风险，确认误报时优先升级 `src/tools/review.ts`，不要把误报沉积到上下文。 | +| `pnpm run napcat-device-profile-check` | 静态检查 API NapCat 设备身份护栏，防止回退到未知设备风险配置。 | | `pnpm run deploy-observation` | 默认 dry-run 输出只读 NAS 观测命令；传 `--execute` 时执行 Jenkins/K8s/health/smoke 观测并写入 `.kt-workspace/test-artifacts/deploy-observation`。 | | `pnpm run obsidian-context` | 输出 Obsidian 索引上下文；可传 `--module Admin`、`--query QQBot`、`--max-documents 10`。 | | `pnpm run obsidian-validate` | 校验 KT Obsidian vault 结构和链接；默认 warning 不让脚本失败，需要严格模式时传 `--fail-on-warnings`。 | diff --git a/package.json b/package.json index f34e1b1..3b24262 100644 --- a/package.json +++ b/package.json @@ -9,6 +9,7 @@ "cleanup-history": "node --import ./node_modules/tsx/dist/loader.mjs src/server.ts --cleanup-history", "deploy-observation": "node --import ./node_modules/tsx/dist/loader.mjs src/server.ts --deploy-observation", "global-review": "node --import ./node_modules/tsx/dist/loader.mjs src/server.ts --global-review", + "napcat-device-profile-check": "node --import ./node_modules/tsx/dist/loader.mjs src/server.ts --napcat-device-profile-check", "obsidian-context": "node --import ./node_modules/tsx/dist/loader.mjs src/server.ts --obsidian-context", "obsidian-sync": "node --import ./node_modules/tsx/dist/loader.mjs src/server.ts --obsidian-sync", "obsidian-validate": "node --import ./node_modules/tsx/dist/loader.mjs src/server.ts --obsidian-validate", diff --git a/src/core/constants.ts b/src/core/constants.ts index 3474c3c..dec1985 100644 --- a/src/core/constants.ts +++ b/src/core/constants.ts @@ -69,6 +69,7 @@ export const registeredToolNames = [ 'kt_commit_plan', 'kt_push_plan', 'kt_business_test_plan', + 'kt_napcat_device_profile_check', 'kt_blocker_resolution', 'kt_remote_health_check', 'kt_deploy_observation', diff --git a/src/registerTools.ts b/src/registerTools.ts index 574055d..62fdabb 100644 --- a/src/registerTools.ts +++ b/src/registerTools.ts @@ -12,7 +12,12 @@ import { buildWorkflowLoopAudit } from './tools/loop.js'; import { readObsidianContext, syncObsidianWorkflow, validateObsidianVault } from './tools/obsidian.js'; import { buildGlobalCodeReview, defaultReviewProjects } from './tools/review.js'; import { appendTaskRecord, createCommitChecklist, prepareTask, readWorkflowContext } from './tools/task.js'; -import { buildBusinessTestPlan, createApiTestPlan, createPageTestCase } from './tools/testing.js'; +import { + buildBusinessTestPlan, + buildNapcatDeviceProfileCheck, + createApiTestPlan, + createPageTestCase, +} from './tools/testing.js'; import { buildVerificationPlan } from './tools/verification.js'; import { buildWorkstreamCloseout } from './tools/closeout.js'; import { buildChangeDocSync } from './tools/docSync.js'; @@ -365,6 +370,19 @@ export function registerTools(server: McpServer): void { async (input) => response(buildBusinessTestPlan(input)), ); + server.registerTool( + 'kt_napcat_device_profile_check', + { + description: + '静态检查 API NapCat 设备身份护栏：QQNT 可见 hostname、02:42 MAC、machine-info、runtime dir 和 DB_TIMEZONE。', + inputSchema: { + project: z.string().default('api'), + }, + title: 'KT NapCat Device Profile Check', + }, + async (input) => response(buildNapcatDeviceProfileCheck(input)), + ); + server.registerTool( 'kt_blocker_resolution', { diff --git a/src/selfTest.ts b/src/selfTest.ts index f8bdcad..6c215e2 100644 --- a/src/selfTest.ts +++ b/src/selfTest.ts @@ -35,7 +35,10 @@ import { findTaskRecordGovernanceFindings, isBenignCredentialReviewValue, } from "./tools/review.js"; -import { buildBusinessTestPlan } from "./tools/testing.js"; +import { + buildBusinessTestPlan, + buildNapcatDeviceProfileCheck, +} from "./tools/testing.js"; import { buildVerificationPlan } from "./tools/verification.js"; import { buildWorkstreamCloseout } from "./tools/closeout.js"; import { @@ -1211,6 +1214,13 @@ export async function runSelfTest(): Promise { throw new Error("DB sync plan safety self-check failed"); } + const napcatDeviceProfileCheck = buildNapcatDeviceProfileCheck({ + project: "api", + }); + if ((napcatDeviceProfileCheck.ok as boolean) !== true) { + throw new Error("NapCat device profile guardrail self-check failed"); + } + const data = { context: readWorkflowContext({ taskRecordCount: 2 }), guardrails: buildGuardrails({ @@ -1251,6 +1261,7 @@ export async function runSelfTest(): Promise { businessTestPlan: buildBusinessTestPlan({ flow: "system-log-visualization", }), + napcatDeviceProfileCheck, closeoutComplete, closeoutNeedsUpgrade, obsidianContext, diff --git a/src/server.ts b/src/server.ts index 24a41c2..ee0719d 100644 --- a/src/server.ts +++ b/src/server.ts @@ -17,6 +17,7 @@ import { readObsidianContext, syncObsidianWorkflow, validateObsidianVault } from import { buildGlobalCodeReview } from './tools/review.js'; import { registerTools } from './registerTools.js'; import { runSelfTest } from './selfTest.js'; +import { buildNapcatDeviceProfileCheck } from './tools/testing.js'; if (process.argv.includes('--cleanup-history')) { console.log(JSON.stringify(cleanupHistoryArtifacts(parseCliCleanupArgs(process.argv)), null, 2)); @@ -46,6 +47,8 @@ if (process.argv.includes('--cleanup-history')) { await runSelfTest(); } else if (process.argv.includes('--workstream-closeout')) { console.log(JSON.stringify(buildWorkstreamCloseout(parseWorkstreamCloseoutCliArgs(process.argv)), null, 2)); +} else if (process.argv.includes('--napcat-device-profile-check')) { + console.log(JSON.stringify(buildNapcatDeviceProfileCheck({ project: 'api' }), null, 2)); } else { const server = new McpServer({ name: 'kt-workflow', diff --git a/src/tools/testing.ts b/src/tools/testing.ts index 0534f21..14c5cd1 100644 --- a/src/tools/testing.ts +++ b/src/tools/testing.ts @@ -1,5 +1,120 @@ -import type { ApiTestPlanInput, BusinessFlow, BusinessTestPlanInput, PageTestCaseInput, PageTestCaseResult } from '../types.js'; +import { existsSync, readFileSync } from 'node:fs'; +import path from 'node:path'; + +import type { + ApiTestPlanInput, + BusinessFlow, + BusinessTestPlanInput, + NapcatDeviceProfileCheckInput, + PageTestCaseInput, + PageTestCaseResult, +} from '../types.js'; import { resolveProject } from '../core/workspace.js'; + +/** + * Reads a project-relative source file for static NapCat device profile checks. + * @param projectPath - Absolute project path returned by `resolveProject()`. + * @param relativePath - File path inside the API project. + * @returns UTF-8 file content, or an empty string when the file is absent. + */ +function readProjectFile(projectPath: string, relativePath: string): string { + const filePath = path.join(projectPath, relativePath); + return existsSync(filePath) ? readFileSync(filePath, 'utf8') : ''; +} + +/** + * Builds a boolean static check with a human-readable recovery hint. + * @param name - Stable check identifier for reports and self-test output. + * @param passed - Whether the source text still contains the expected guardrail. + * @param evidence - Short description of the expected code-level evidence. + * @returns Check result consumed by `buildNapcatDeviceProfileCheck()`. + */ +function createNapcatCheck( + name: string, + passed: boolean, + evidence: string, +): Record { + return { + evidence, + name, + passed, + }; +} + +/** + * Checks that the API project still contains the NapCat device-profile guardrails needed to avoid unknown QQ devices. + * @param input - Project alias or path to scan; defaults to the API backend. + * @returns Static guardrail report covering hostname, MAC, machine-info, runtime dir, and DB timezone. + */ +export function buildNapcatDeviceProfileCheck( + input: NapcatDeviceProfileCheckInput = {}, +): Record { + const project = resolveProject(input.project || 'api'); + const deviceIdentity = readProjectFile( + project.path, + 'src/modules/qqbot/napcat/infrastructure/integration/device/napcat-device-identity.service.ts', + ); + const dockerOptions = readProjectFile( + project.path, + 'src/modules/qqbot/napcat/infrastructure/integration/container/napcat-docker-device-options.ts', + ); + const containerService = readProjectFile( + project.path, + 'src/modules/qqbot/napcat/infrastructure/integration/container/qqbot-napcat-container.service.ts', + ); + const appModule = readProjectFile(project.path, 'src/app.module.ts'); + const runtimeConfig = readProjectFile( + project.path, + 'src/runtime/config/runtime-config.service.ts', + ); + const checks = [ + createNapcatCheck( + 'hostname-strategy', + deviceIdentity.includes('qqnt-visible-hostname-v1') && + deviceIdentity.includes('pc-') && + deviceIdentity.includes('hash.slice(0, 8)'), + 'device identity uses qqnt-visible-hostname-v1 and pc-<8hex>', + ), + createNapcatCheck( + 'docker-bridge-mac-strategy', + deviceIdentity.includes('docker-bridge-mac-v1') && + deviceIdentity.includes('02:42:'), + 'device identity uses docker-bridge-mac-v1 and stable 02:42:* MACs', + ), + createNapcatCheck( + 'machine-info-options', + dockerOptions.includes('machineInfoPath') && + dockerOptions.includes('macAddressHyphen'), + 'docker device options carry machineInfoPath and hyphenated MAC', + ), + createNapcatCheck( + 'machine-info-script', + containerService.includes('MACHINE_INFO_PATH') && + containerService.includes('NAPCAT_MAC_HYPHEN') && + containerService.includes("tr 'A-Za-z' 'N-ZA-Mn-za-m'") && + containerService.includes("printf '\\\\000\\\\000\\\\000\\\\021'"), + 'remote create script writes QQNT machine-info using ROT13 MAC format', + ), + createNapcatCheck( + 'runtime-dir-mount', + containerService.includes('$DATA_DIR/runtime:/tmp/runtime-napcat'), + 'remote create script persists XDG_RUNTIME_DIR under the account data dir', + ), + createNapcatCheck( + 'db-timezone', + appModule.includes('DB_TIMEZONE') && + appModule.includes("'+08:00'") && + runtimeConfig.includes('DB_TIMEZONE'), + 'TypeORM and runtime config expose DB_TIMEZONE with +08:00 default', + ), + ]; + + return { + checks, + ok: checks.every((item) => item.passed === true), + project, + }; +} export function createPageTestCase(input: PageTestCaseInput): PageTestCaseResult { const project = resolveProject(input.project); const title = input.title || `${project.label} 页面级测试`; diff --git a/src/types.ts b/src/types.ts index 9b0711c..8dd0c18 100644 --- a/src/types.ts +++ b/src/types.ts @@ -185,6 +185,10 @@ export interface BusinessTestPlanInput { flow?: BusinessFlow | 'all'; } +export interface NapcatDeviceProfileCheckInput { + project?: string; +} + export interface BlockerResolutionInput { attempts?: number; command?: string;