@njuptlzf/agent-chat-server 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -4,36 +4,72 @@
4
4
  *
5
5
  * 设计约束(改动前先读):
6
6
  * ① 零第三方依赖:只用 Node 内置模块,不 import `yaml`,不 import 平台 `.ts` 源码。
7
- * 装进产品仓 node_modules 后仍能独立运行;模板全部内嵌为字符串。
7
+ * 装进产品仓 node_modules 后仍能独立运行;模板与能力注册表全部内嵌。
8
8
  * ② 产品无关:脚本正文与生成物不含任何具体产品名 / 私有词 / 业务断言。
9
- * ③ 平台只守契约:`check` 只对形状契约报 FAIL;业务 UT / 接口 / UI 用例缺失
10
- * 只出 WARN + 建议,绝不产生非零退出。
9
+ * ③ 平台守两类门禁:契约形状(FAIL)+ 能力声明与准出(capabilities / 四脚本 / 真跑)。
10
+ * 测试内容**不由平台预制**——每个产品用法不同,用例由产品(或其 AI)按能力注册表
11
+ * 现场生成;check 只验「声明完整、脚本齐、跑绿」,不解析测试写了什么断言。
11
12
  * ④ 完整口径不复制:AppDef 的 20 条动态契约由产品 vite.config.ts 的 appDefGuard
12
- * (复用 @njuptlzf/agent-chat-web/app-def-check)把关,这里只查声明存在性。
13
+ * (复用 @njuptlzf/agent-chat-web/app-def-check)把关,这里只查声明存在性;
14
+ * 能力的准出要求全文以 docs/specs/能力注册表.md 为人读权威,CLI 内嵌机读最小集
15
+ * (id/中文名/触发声明),单测钉两侧 ID 集合一致。
13
16
  */
14
17
  import fs from "node:fs";
15
18
  import path from "node:path";
16
19
  import { createRequire } from "node:module";
17
20
  import { spawnSync } from "node:child_process";
18
- import { pathToFileURL } from "node:url";
19
21
  import process from "node:process";
20
22
 
21
- const CLI_VERSION = "0.1.2";
22
- const MIN_SERVER = "0.1.1";
23
+ const CLI_VERSION = "0.2.0";
24
+ const MIN_SERVER = "0.2.0";
23
25
  const PKG = {
24
26
  protocol: "@njuptlzf/agent-chat-protocol",
25
27
  server: "@njuptlzf/agent-chat-server",
26
28
  web: "@njuptlzf/agent-chat-web",
27
29
  };
28
30
  const ID_RE = /^[a-z0-9][a-z0-9-]*$/;
29
- const PLACEHOLDERS = ["<PROVIDER>", "<MODEL_ID>", "<产品标题>", "<组名>"];
30
- const VALUE_FLAGS = new Set(["--dir", "--id", "--title", "--provider", "--model"]);
31
+ const PLACEHOLDERS = ["<PROVIDER>", "<MODEL_ID>", "<产品标题>"];
32
+ const VALUE_FLAGS = new Set(["--dir", "--id", "--title", "--provider", "--model", "--timeout"]);
33
+
34
+ /**
35
+ * 能力注册表(机读最小集;人读权威 = docs/specs/能力注册表.md,一致性由 CLI 单测钉住)。
36
+ * always = 恒开能力,任何产品都在用,**不写进 capabilities**(写了判 FAIL);
37
+ * optIn = 声明式能力,用了必须声明;trigger 为人读触发声明摘要。
38
+ */
39
+ const CAP_ALWAYS = [
40
+ { id: "chat", name: "对话与流式事件、会话历史" },
41
+ { id: "auth-quota", name: "鉴权与日额度" },
42
+ { id: "branding", name: "品牌与人格文案下发" },
43
+ { id: "audit", name: "审计哈希链" },
44
+ { id: "admin-plane", name: "管理面配置与用量报表" },
45
+ ];
46
+ const CAP_OPT_IN = [
47
+ { id: "product-routes", name: "产品业务路由", trigger: "manifest `server.routes`" },
48
+ { id: "product-admin-routes", name: "产品管理面路由", trigger: "代码出现 ProductAdminRoute" },
49
+ { id: "inline-tools", name: "内联工具", trigger: "manifest `tools.inline`" },
50
+ { id: "mcp-tools", name: "MCP 工具", trigger: "manifest `mcp`" },
51
+ { id: "tool-confirm", name: "工具确认", trigger: "manifest `confirmTools`" },
52
+ { id: "personas", name: "多人格", trigger: "manifest `agent.personas`" },
53
+ { id: "skills", name: "技能目录", trigger: "manifest `agent.skills`" },
54
+ { id: "extensions", name: "pi 扩展加载", trigger: "manifest `agent.extensions`" },
55
+ { id: "scoped-memory", name: "作用域记忆", trigger: "manifest 未写 `agent.memory: false` 即默认开启" },
56
+ { id: "tiers", name: "质量档位", trigger: "manifest `agent.tiers`" },
57
+ { id: "billing", name: "计费 / 订单 / 套餐 / 充值", trigger: "manifest `billing` 或代码调 /api/orders、/api/recharge" },
58
+ { id: "authz-seed", name: "权限种子策略", trigger: "manifest `agent.authz.seedPolicies`" },
59
+ { id: "quals", name: "多资格内容组织", trigger: "manifest `quals`" },
60
+ { id: "appdef-extensions", name: "前端扩展点", trigger: "app-def/entry 用 navAlias/cardRenderer/guard/footer/extras 或代码调 sendToChat" },
61
+ { id: "feedback", name: "反馈通道", trigger: "代码调 /api/feedback 或 ctx.createFeedback" },
62
+ { id: "attachments", name: "附件图片", trigger: "代码调 /api/attachments、/api/images" },
63
+ ];
64
+ const CAP_IDS = new Set(CAP_OPT_IN.map((c) => c.id));
65
+ const ALWAYS_IDS = new Set(CAP_ALWAYS.map((c) => c.id));
31
66
 
32
67
  const HELP = `agentchat-integrate ${CLI_VERSION} — AI 产品接入 agentChat 的机械入口
33
68
 
34
69
  用法(在产品仓根目录执行):
35
- npx agentchat-integrate init [选项] 生成产品侧骨架
36
- npx agentchat-integrate check [选项] 输出接入体检报告
70
+ npx agentchat-integrate init [选项] 生成产品侧骨架(不生成测试——测试按能力声明现场写)
71
+ npx agentchat-integrate check [选项] 接入体检:契约形状 + 能力声明对账 + 四脚本真跑
72
+ npx agentchat-integrate capabilities [--json] 打印能力注册表(机读最小集)
37
73
 
38
74
  选项:
39
75
  --dir <path> 产品仓根目录,默认当前工作目录
@@ -43,13 +79,18 @@ const HELP = `agentchat-integrate ${CLI_VERSION} — AI 产品接入 agentChat
43
79
  --model <m> agent.model.id,默认 <MODEL_ID>(待填)
44
80
  --force 覆盖已存在的生成文件(package.json 永远不覆盖)
45
81
  --dry-run 只打印将要生成的文件,不落盘
46
- --json check 输出结构化 JSON
47
- --deep check 额外尝试用产品仓的 tsx 跑一次真实 AppDef 校验(失败只记 INFO)
82
+ --json check / capabilities 输出结构化 JSON
83
+ --deep check 额外用产品仓的 tsx 跑一次真实 AppDef 校验(失败只记 INFO)
84
+ --no-run check 不执行 test:agentchat:* 脚本(只验存在;本地提速用,CI 别用)
85
+ --timeout <秒> 每个测试脚本的执行超时,默认 600
48
86
  --help / --version
49
87
 
50
- 退出码:0 = 无契约违规(WARN/INFO 允许);1 = 存在契约违规;2 = 参数错误 / 平台仓误跑护栏
88
+ 退出码:0 = 无违规(WARN/INFO 允许);1 = 有违规(含能力未声明、缺脚本、脚本跑挂);
89
+ 2 = 参数错误 / 平台仓误跑护栏
51
90
 
52
- 注意:别在 agentChat 平台仓根目录跑 init——那会把骨架生成进平台仓。
91
+ 门禁口径:用了哪些平台能力必须在 manifest 的 capabilities: 显式声明;声明的能力要由
92
+ test:agentchat:unit / :api / :ui 三个脚本承载并跑绿(内容由产品按 docs/specs/能力注册表.md
93
+ 的准出要求自行编写,平台不预制、不代写业务断言)。init 后直接 check 会红是预期——测试还没写。
53
94
  规范见平台仓 docs/specs/产品接入与测试规范.md;AI 执行流程见 agentchat-onboarding Skill。`;
54
95
 
55
96
  // ── 参数 ──────────────────────────────────────────────────────────────────
@@ -66,6 +107,8 @@ function parseArgs(argv) {
66
107
  dryRun: false,
67
108
  json: false,
68
109
  deep: false,
110
+ noRun: false,
111
+ timeout: 600,
69
112
  help: false,
70
113
  version: false,
71
114
  };
@@ -81,6 +124,13 @@ function parseArgs(argv) {
81
124
  else if (a === "--dry-run") opts.dryRun = true;
82
125
  else if (a === "--json") opts.json = true;
83
126
  else if (a === "--deep") opts.deep = true;
127
+ else if (a === "--no-run") opts.noRun = true;
128
+ else if (a === "--timeout") {
129
+ const value = argv[++i];
130
+ const n = Number(value);
131
+ if (value === undefined || !Number.isFinite(n) || n <= 0) return { error: `--timeout 要正整数秒,收到 "${value}"` };
132
+ opts.timeout = n;
133
+ }
84
134
  else if (VALUE_FLAGS.has(a)) {
85
135
  const value = argv[++i];
86
136
  if (value === undefined || value.startsWith("--")) return { error: `${a} 缺少取值` };
@@ -131,6 +181,15 @@ id: ${o.id}
131
181
  branding:
132
182
  title: ${JSON.stringify(o.title)}
133
183
 
184
+ # 准出声明:本产品实际用到的平台能力,用了就必须写在这里(恒开能力 chat/auth-quota/
185
+ # branding/audit/admin-plane 不列——列了 check 判 FAIL)。下面两份是按当前骨架推导的
186
+ # 初始值:声明了 server.routes ⇒ product-routes;未关 agent.memory ⇒ scoped-memory。
187
+ # 每加一项 manifest 字段 / 代码用法,同步增删这里。ID 表与准出要求:
188
+ # 平台仓 docs/specs/能力注册表.md(npx agentchat-integrate capabilities 可查)。
189
+ capabilities:
190
+ - product-routes
191
+ - scoped-memory
192
+
134
193
  agent:
135
194
  systemPrompt: ./prompt.md
136
195
  model:
@@ -156,9 +215,13 @@ function packageTemplate(o) {
156
215
  private: true,
157
216
  type: "module",
158
217
  dependencies: {
159
- [PKG.protocol]: "^0.1.0",
160
- [PKG.server]: "^0.1.1",
161
- [PKG.web]: "^0.1.0",
218
+ [PKG.protocol]: "^0.2.0",
219
+ [PKG.server]: "^0.2.0",
220
+ [PKG.web]: "^0.2.0",
221
+ },
222
+ devDependencies: {
223
+ tsx: "^4.20.0",
224
+ typescript: "^5.9.0",
162
225
  },
163
226
  }, null, 2)}\n`;
164
227
  }
@@ -174,30 +237,31 @@ function routesTemplate(o) {
174
237
  * - init 抛错 = 启动失败(fail-closed),不是首个请求才 500。
175
238
  * core 只认形状,不认任何具体路径——下面的路径全是产品事实,请替换。
176
239
  */
177
- import { sendJson, type ProductAdminRoute, type ProductRoute, type ServerDeps } from "${PKG.server}";
240
+ import { sendJson, type ProductRoute, type ServerDeps } from "${PKG.server}";
178
241
 
179
242
  const itemsRoute: ProductRoute = async ({ req, res, url }) => {
180
243
  if (req.method !== "GET" || url.pathname !== "/api/${o.id}/items") return;
181
244
  sendJson(res, 200, { items: [] });
182
245
  };
183
246
 
184
- const adminRoute: ProductAdminRoute = {
185
- match: (pathname) => pathname === "/api/admin/${o.id}/stats",
186
- group: "<组名>",
187
- handle: async (_deps: ServerDeps, _req, res) => {
188
- sendJson(res, 200, { ok: true });
189
- },
190
- };
247
+ /*
248
+ * 管理面路由样板:真的用它时(import ProductAdminRoute 并取消下面的注释),
249
+ * 要在 manifest 的 capabilities 里声明 product-admin-routes,并给 group 配一条
250
+ * {sub:"admin",obj:"admin-api",act:<group>} 种子(authz-seed 也要声明)。
251
+ *
252
+ * import type { ProductAdminRoute } from "${PKG.server}";
253
+ * const adminRoute: ProductAdminRoute = {
254
+ * match: (pathname) => pathname === "/api/admin/${o.id}/stats",
255
+ * group: "${o.id}-admin",
256
+ * handle: async (_deps: ServerDeps, _req, res) => { sendJson(res, 200, { ok: true }); },
257
+ * };
258
+ */
191
259
 
192
- export function createRoutes(): {
193
- routes: ProductRoute[];
194
- admin: ProductAdminRoute[];
195
- init?(deps: ServerDeps): void;
196
- } {
260
+ export function createRoutes() {
197
261
  return {
198
262
  routes: [itemsRoute],
199
- admin: [adminRoute],
200
- // init(_deps) { /* 启动期装配自己的存储/索引;抛错 = 启动失败 */ },
263
+ admin: [],
264
+ // init(_deps: ServerDeps) { /* 启动期装配自己的存储/索引;抛错 = 启动失败 */ },
201
265
  };
202
266
  }
203
267
  `;
@@ -252,29 +316,11 @@ export function App() {
252
316
  `;
253
317
  }
254
318
 
255
- const TEST_TEMPLATES = {
256
- "test/templates/unit.example.ts": `// 业务 UT 模板 —— 产品仓自己写断言,平台不代判绿。
257
- // 复制成 test/<name>.test.ts 后,换成产品自己的纯逻辑用例;本文件不是用例。
258
- //
259
- // import { test } from "node:test";
260
- // import assert from "node:assert/strict";
261
- // test("示例:某段业务逻辑", () => { assert.equal(1 + 1, 2); });
262
- `,
263
- "test/templates/api.example.ts": `// 业务接口用例模板 —— 产品仓自己写断言,平台不代判绿。
264
- // 建议用 @njuptlzf/agent-chat-server/testing 搭真 server 的依赖,
265
- // 再针对产品自己的路由写请求/响应断言;不要 import 平台 src 深路径。
266
- //
267
- // import { createChatServer } from "@njuptlzf/agent-chat-server/testing";
268
- // import { createRoutes } from "../server/routes.ts";
269
- `,
270
- "test/templates/ui.example.ts": `// 业务 UI 用例模板 —— 产品仓自己写断言,平台不代判绿。
271
- // 产品页面的浏览器验收、截图基线、活体脚本归产品仓维护
272
- // (见产品仓 docs/验收与提交规范.md)。平台 CI 只跑通用壳的样板活体。
273
- `,
274
- };
275
-
319
+ // init 不生成任何测试文件:用例内容由产品的实际用法决定,平台不预制、不代写。
320
+ // 准出测试由产品(或其 AI)按 docs/specs/能力注册表.md 的准出要求现场生成,
321
+ // check 只验「声明完整 + 四脚本齐 + 跑绿」。
276
322
  function buildFiles(o) {
277
- const files = [
323
+ return [
278
324
  ["manifest.yaml", manifestTemplate(o)],
279
325
  ["prompt.md", promptTemplate(o)],
280
326
  ["package.json", packageTemplate(o)],
@@ -282,8 +328,6 @@ function buildFiles(o) {
282
328
  ["web/app-def.tsx", appDefTemplate()],
283
329
  ["web/entry.tsx", entryTemplate()],
284
330
  ];
285
- for (const [rel, content] of Object.entries(TEST_TEMPLATES)) files.push([rel, content]);
286
- return files;
287
331
  }
288
332
 
289
333
  function init(opts, dir) {
@@ -328,9 +372,11 @@ function init(opts, dir) {
328
372
  if (!opts.dryRun) {
329
373
  process.stdout.write(
330
374
  `\n生成 ${written} 个文件、跳过 ${skipped} 个 → ${dir}\n` +
331
- `下一步:填掉 <PROVIDER> / <MODEL_ID> / <产品标题> / <组名> 占位符,` +
332
- `在产品 vite.config.ts 接 appDefGuard,然后跑 npx agentchat-integrate check。\n` +
333
- `业务 UT / 接口 / UI 用例由产品仓按模板自行编写、自跑自判;平台不代判绿。\n`,
375
+ `下一步:填掉 <PROVIDER> / <MODEL_ID> / <产品标题> 占位符;核对 manifest 的 capabilities 声明\n` +
376
+ `(恒开能力不列,ID 表见 npx agentchat-integrate capabilities 或 docs/specs/能力注册表.md)。\n` +
377
+ `然后**按声明的能力现场写 UT / 接口 / UI 测试并写入 package.json 的 test:agentchat{,:unit,:api,:ui} 四脚本**\n` +
378
+ `(平台不预制用例——每个产品用法不同;准出要求逐条参考能力注册表,别把示例抄成断言)。\n` +
379
+ `写完再跑 npx agentchat-integrate check;现在跑会因缺测试/缺脚本判红,这是预期。\n`,
334
380
  );
335
381
  }
336
382
  return 0;
@@ -362,7 +408,7 @@ function checkDeps(add, dir) {
362
408
  const all = { ...(pj.dependencies ?? {}), ...(pj.devDependencies ?? {}) };
363
409
  const missing = Object.values(PKG).filter((n) => !(n in all));
364
410
  if (missing.length) add("FAIL", "deps", `未声明平台依赖:${missing.join("、")}`,
365
- `npm i ${PKG.protocol}@^0.1.0 ${PKG.server}@^0.1.1 ${PKG.web}@^0.1.0`);
411
+ `npm i ${PKG.protocol}@^0.2.0 ${PKG.server}@^0.2.0 ${PKG.web}@^0.2.0`);
366
412
  else add("OK", "deps", "三个平台包依赖已声明");
367
413
 
368
414
  try {
@@ -370,8 +416,8 @@ function checkDeps(add, dir) {
370
416
  const file = req.resolve(`${PKG.server}/package.json`);
371
417
  const v = JSON.parse(fs.readFileSync(file, "utf8")).version;
372
418
  if (versionAtLeast(v, MIN_SERVER)) add("OK", "installed", `已安装 ${PKG.server} ${v}`);
373
- else add("WARN", "installed", `已安装 ${v} < ${MIN_SERVER},可能没有 npx 入口`,
374
- `npm i ${PKG.server}@^0.1.1 刷新 lockfile`);
419
+ else add("WARN", "installed", `已安装 ${v} < ${MIN_SERVER}(能力门禁与准出脚本检查从 ${MIN_SERVER} 起)`,
420
+ `npm i ${PKG.server}@^${MIN_SERVER} 刷新 lockfile`);
375
421
  } catch {
376
422
  add("WARN", "installed", "node_modules 未安装或平台包不可解析", "npm install 后重跑 check");
377
423
  }
@@ -478,6 +524,7 @@ function walkFiles(dir, out = []) {
478
524
  let entries;
479
525
  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return out; }
480
526
  for (const e of entries) {
527
+ if (e.name === "node_modules" || e.name === "dist" || e.name.startsWith(".")) continue;
481
528
  const full = path.join(dir, e.name);
482
529
  if (e.isDirectory()) walkFiles(full, out);
483
530
  else out.push(full);
@@ -485,27 +532,196 @@ function walkFiles(dir, out = []) {
485
532
  return out;
486
533
  }
487
534
 
488
- function checkTests(add, dir) {
489
- const roots = ["test", "tests", "e2e", path.join("web", "test")];
490
- const files = roots.flatMap((r) => walkFiles(path.join(dir, r)));
491
- const real = files.filter((f) => /\.(test|spec)\.(ts|tsx|mjs|js)$/.test(f) && !f.includes(`${path.sep}templates${path.sep}`));
492
- if (real.length) add("OK", "tests", `发现 ${real.length} 个非模板测试文件`);
493
- else add("WARN", "tests", "未发现业务 UT / 接口 / UI 用例(test/templates 只是骨架)",
494
- "按 test/templates/*.example.ts 自行编写并自跑自判;平台不代判绿、此项不阻断");
535
+ // ── 能力声明与对账 ─────────────────────────────────────────────────────────
536
+
537
+ /** 解析 manifest 的 capabilities 段。返回 null=缺失段;{ids}=已声明(可为空列表)。 */
538
+ function capabilitiesOf(text) {
539
+ const inline = text.match(/^capabilities:\s*\[([^\]]*)\]\s*(#.*)?$/m);
540
+ if (inline) {
541
+ const ids = inline[1].split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
542
+ return { ids };
543
+ }
544
+ const m = text.match(/^capabilities:\s*(#.*)?$/m);
545
+ if (!m) return null;
546
+ const ids = [];
547
+ for (const line of text.slice(m.index + m[0].length).split(/\r?\n/)) {
548
+ if (line.trim() === "" || /^\s*#/.test(line)) continue;
549
+ const item = line.match(/^\s+-\s+["']?([A-Za-z0-9_-]+)["']?\s*(#.*)?$/);
550
+ if (!item) break;
551
+ ids.push(item[1]);
552
+ }
553
+ return { ids };
495
554
  }
496
555
 
497
- function checkTooling(add, dir) {
498
- const wf = path.join(dir, ".github", "workflows");
499
- const hasCi = fs.existsSync(wf) && fs.readdirSync(wf).some((f) => /\.ya?ml$/.test(f));
500
- if (hasCi) add("OK", "ci", "存在 CI 工作流");
501
- else add("WARN", "ci", "未发现 .github/workflows/*.yml", "产品仓自己加 CI,至少跑 typecheck / test / build");
556
+ /** manifest 结构化推导(确定性,零误报):字段声明即使用。返回触发中的能力 ID。 */
557
+ function deriveFromManifest(text) {
558
+ const hit = [];
559
+ const t = text;
560
+ if (serverRoutesOf(t)) hit.push("product-routes");
561
+ if (/^\s+inline:\s*["']?\./m.test(t)) hit.push("inline-tools");
562
+ if (/^mcp:/m.test(t)) hit.push("mcp-tools");
563
+ if (/^confirmTools:\s*\S/m.test(t)) hit.push("tool-confirm");
564
+ if (/^\s+personas:/m.test(t)) hit.push("personas");
565
+ if (/^\s+skills:\s*(#.*)?$|^\s+skills:\s*\[/m.test(t)) hit.push("skills");
566
+ if (/^\s+extensions:\s*(#.*)?$|^\s+extensions:\s*\[/m.test(t)) hit.push("extensions");
567
+ if (!/^\s+memory:\s*false\s*(#.*)?$/m.test(t)) hit.push("scoped-memory");
568
+ if (/^\s+tiers:/m.test(t)) hit.push("tiers");
569
+ if (/^billing:/m.test(t)) hit.push("billing");
570
+ if (/^\s+seedPolicies:/m.test(t)) hit.push("authz-seed");
571
+ if (/^quals:/m.test(t)) hit.push("quals");
572
+ return hit;
573
+ }
574
+
575
+ /** 粗剥 JS/TS 注释(启发式,够用于痕迹扫描;字符串里的 // 可能被误剥,但只影响 WARN 级判定)。 */
576
+ function stripComments(s) {
577
+ return s.replace(/\/\*[\s\S]*?\*\//g, " ").split("\n").map((l) => l.replace(/(^|[^:"'`])\/\/[^\r\n]*/, "$1")).join("\n");
578
+ }
579
+
580
+ /** 代码痕迹扫描(启发式,只给 WARN):manifest 无痕迹、代码里真调了端点/类型。 */
581
+ function scanCodeTraces(dir) {
582
+ const hit = new Set();
583
+ const srcFiles = walkFiles(dir).filter((f) => /\.(ts|tsx)$/.test(f));
584
+ const appdefFiles = srcFiles.filter((f) => /[\\/]app-def\.tsx$|[\\/]entry\.tsx$/.test(f));
585
+ for (const f of srcFiles) {
586
+ if (/[\\/](test|tests|e2e)[\\/]/.test(f)) continue; // 测试里的 fetch 不算产品用法
587
+ const text = stripComments(readText(path.dirname(f), path.basename(f)));
588
+ if (!text) continue;
589
+ if (/\bProductAdminRoute\b/.test(text)) hit.add("product-admin-routes");
590
+ if (/\/api\/(orders|recharge)\b/.test(text)) hit.add("billing");
591
+ if (/\/api\/feedback\b|\bcreateFeedback\b/.test(text)) hit.add("feedback");
592
+ if (/\/api\/(attachments|images)\b/.test(text)) hit.add("attachments");
593
+ if (/\bsendToChat\b/.test(text)) hit.add("appdef-extensions");
594
+ }
595
+ // AppDef 可选键只在注册表文件里判——guard/footer 是通用词,全仓扫必误报。
596
+ for (const f of appdefFiles) {
597
+ const text = stripComments(fs.readFileSync(f, "utf8"));
598
+ if (/\b(navAlias|cardRenderer|rewrites)\s*:/.test(text) || /^\s*(guard|footer|extras)\s*[:(]/m.test(text)) {
599
+ hit.add("appdef-extensions");
600
+ }
601
+ }
602
+ return [...hit];
603
+ }
502
604
 
605
+ function checkCapabilities(add, dir) {
606
+ const text = readText(dir, "manifest.yaml");
607
+ if (!text) return null; // manifest 缺失由 checkManifest 报 FAIL,这里不重复
608
+ const caps = capabilitiesOf(text);
609
+ if (caps === null) {
610
+ add("FAIL", "capabilities", "manifest 缺 capabilities 段(空列表 [] 也合法,缺失不合法)",
611
+ "声明本产品用到的平台能力;恒开能力不列;npx agentchat-integrate capabilities 查 ID 表");
612
+ return null;
613
+ }
614
+ const problems = [];
615
+ const unknown = caps.ids.filter((id) => !CAP_IDS.has(id));
616
+ const alwaysOn = caps.ids.filter((id) => ALWAYS_IDS.has(id));
617
+ const dup = caps.ids.filter((id, i) => caps.ids.indexOf(id) !== i);
618
+ if (unknown.length) problems.push(`注册表外的能力 ID:${unknown.join("、")}`);
619
+ if (alwaysOn.length) problems.push(`恒开能力不该写进声明:${alwaysOn.join("、")}`);
620
+ if (dup.length) problems.push(`重复声明:${[...new Set(dup)].join("、")}`);
621
+
622
+ const derived = deriveFromManifest(text);
623
+ const traced = scanCodeTraces(dir);
624
+ const undeclaredDerived = derived.filter((id) => !caps.ids.includes(id));
625
+ const undeclaredTraced = traced.filter((id) => !caps.ids.includes(id) && !undeclaredDerived.includes(id));
626
+ const unused = caps.ids.filter((id) => !derived.includes(id) && !traced.includes(id));
627
+
628
+ if (problems.length) {
629
+ add("FAIL", "capabilities", problems.join(";"), "对照 docs/specs/能力注册表.md 修正声明");
630
+ } else {
631
+ add("OK", "capabilities", `已声明 ${caps.ids.length} 项增量能力:${caps.ids.join("、") || "(无)"}`);
632
+ }
633
+ if (undeclaredDerived.length) {
634
+ add("FAIL", "capabilities-derived",
635
+ `manifest 已触发但未声明:${undeclaredDerived.join("、")}`,
636
+ `加进 capabilities(触发条件见注册表),或删掉对应字段声明`);
637
+ } else if (undeclaredTraced.length) {
638
+ add("WARN", "capabilities-derived",
639
+ `代码痕迹检出但未声明(启发式,可能误报):${undeclaredTraced.join("、")}`,
640
+ "确实用了就声明;没用到的写法删掉;确认误报可忽略本条");
641
+ } else {
642
+ add("OK", "capabilities-derived", `双向对账干净(推导命中 ${derived.length}、痕迹命中 ${traced.length})`);
643
+ }
644
+ if (unused.length) {
645
+ add("WARN", "capabilities-unused", `声明了但 manifest/代码都没检出:${unused.join("、")}`,
646
+ "要么补上用法,要么从 capabilities 删掉");
647
+ }
648
+ return { declared: caps.ids, derived, traced, undeclaredDerived, undeclaredTraced, unused };
649
+ }
650
+
651
+ // ── 准出四脚本:存在 + 真跑 ────────────────────────────────────────────────
652
+
653
+ const TEST_SCRIPTS = ["test:agentchat", "test:agentchat:unit", "test:agentchat:api", "test:agentchat:ui"];
654
+
655
+ function runNpmScript(dir, script, timeoutSec) {
656
+ const r = spawnSync("npm", ["run", script], {
657
+ cwd: dir, encoding: "utf8", timeout: timeoutSec * 1000,
658
+ shell: process.platform === "win32", // Windows 上 npm 是 .cmd,必须走 shell
659
+ });
660
+ if (r.error) {
661
+ const kind = r.error.code === "ETIMEDOUT" ? "timeout" : r.error.code === "ENOENT" ? "no-npm" : "spawn-error";
662
+ return { kind, exitCode: null, output: String(r.error.message ?? "") };
663
+ }
664
+ return {
665
+ kind: r.status === 0 ? "ok" : "fail",
666
+ exitCode: r.status,
667
+ output: `${r.stdout ?? ""}\n${r.stderr ?? ""}`.trim().slice(-1200),
668
+ };
669
+ }
670
+
671
+ function checkTestScripts(add, dir, opts) {
503
672
  let scripts = {};
504
- try { scripts = JSON.parse(readText(dir, "package.json")).scripts ?? {}; } catch { /* 上面已报过 */ }
505
- const liveFiles = walkFiles(path.join(dir, "scripts")).filter((f) => /live|e2e/i.test(path.basename(f)));
506
- const hasLive = Object.keys(scripts).some((s) => /live|e2e/i.test(s)) || liveFiles.length > 0;
507
- if (hasLive) add("OK", "live", "存在活体 / e2e 入口");
508
- else add("WARN", "live", "未发现 live / e2e 入口", "产品页面验收需要真浏览器,入口由产品仓维护");
673
+ try { scripts = JSON.parse(readText(dir, "package.json")).scripts ?? {}; } catch { return; }
674
+ const missing = TEST_SCRIPTS.filter((s) => !scripts[s] || !String(scripts[s]).trim());
675
+ if (missing.length) {
676
+ add("FAIL", "test-scripts", `缺准出脚本:${missing.join("、")}`,
677
+ "按 agentchat-onboarding Skill 生成 UT/接口/UI 三组测试后写入这四个脚本(内容由产品按能力注册表自行编写,平台不预制)");
678
+ return;
679
+ }
680
+ const agg = String(scripts["test:agentchat"]);
681
+ const subs = ["test:agentchat:unit", "test:agentchat:api", "test:agentchat:ui"];
682
+ const notAggregated = subs.filter((s) => !agg.includes(s));
683
+ if (notAggregated.length) {
684
+ add("WARN", "test-scripts", `test:agentchat 未引用:${notAggregated.join("、")}`,
685
+ "汇总脚本应跑全三个子脚本,否则 CI/门禁会漏层");
686
+ } else {
687
+ add("OK", "test-scripts", "准出四脚本齐备且汇总完整");
688
+ }
689
+ if (opts.noRun) {
690
+ add("WARN", "test-run", "--no-run:本次未执行测试脚本", "CI 与验收必须真跑,本地提速才用 --no-run");
691
+ return;
692
+ }
693
+ const runs = [];
694
+ let failed = false;
695
+ for (const s of subs) {
696
+ const r = runNpmScript(dir, s, opts.timeout);
697
+ runs.push({ script: s, ...r });
698
+ if (r.kind === "timeout") {
699
+ add("FAIL", "test-run", `${s} 超时(>${opts.timeout}s)`, `调 --timeout 或拆分用例;报告尾部:${r.output.slice(-300)}`);
700
+ failed = true;
701
+ } else if (r.kind === "no-npm") {
702
+ add("FAIL", "test-run", "npm 不可用,无法执行测试脚本", "确认 PATH 里有 npm");
703
+ failed = true;
704
+ } else if (r.kind !== "ok") {
705
+ const hint = /Cannot find package 'tsx'/.test(r.output) ? "先 npm i -D tsx;" :
706
+ /Cannot find package '@njuptlzf\//.test(r.output) ? "先 npm install;" : "";
707
+ add("FAIL", "test-run", `${s} 未通过(exit ${r.exitCode})`, `${hint}报告尾部:${r.output.slice(-300)}`);
708
+ failed = true;
709
+ }
710
+ }
711
+ if (!failed) add("OK", "test-run", `三组准出脚本真跑通过(unit/api/ui @ ${opts.timeout}s 上限)`);
712
+ return runs;
713
+ }
714
+
715
+ function checkTooling(add, dir) {
716
+ const wf = path.join(dir, ".github", "workflows");
717
+ const wfFiles = fs.existsSync(wf) ? fs.readdirSync(wf).filter((f) => /\.ya?ml$/.test(f)) : [];
718
+ if (wfFiles.length === 0) {
719
+ add("WARN", "ci", "未发现 .github/workflows/*.yml", "产品仓自己加 CI,至少跑 typecheck / test / build");
720
+ } else if (!wfFiles.some((f) => /test:agentchat/.test(fs.readFileSync(path.join(wf, f), "utf8")))) {
721
+ add("WARN", "ci", "CI 存在但未引用 test:agentchat", "把 `npm run test:agentchat` 加进产品仓 CI 的门禁步骤");
722
+ } else {
723
+ add("OK", "ci", "存在 CI 工作流且引用 test:agentchat");
724
+ }
509
725
 
510
726
  const vite = ["vite.config.ts", "vite.config.mts", "vite.config.js", "web/vite.config.ts"]
511
727
  .map((r) => readText(dir, r)).join("\n");
@@ -546,7 +762,8 @@ function check(opts, dir) {
546
762
  checkRoutes(add, dir);
547
763
  checkAppDef(add, dir);
548
764
  checkPlaceholders(add, dir);
549
- checkTests(add, dir);
765
+ const caps = checkCapabilities(add, dir);
766
+ const runs = checkTestScripts(add, dir, opts);
550
767
  checkTooling(add, dir);
551
768
  if (opts.deep) checkDeep(add, dir);
552
769
 
@@ -560,6 +777,15 @@ function check(opts, dir) {
560
777
  warnings: warnings.map((r) => ({ code: r.code, message: r.message })),
561
778
  suggestions,
562
779
  results,
780
+ capabilities: caps && {
781
+ declared: caps.declared,
782
+ detected: [...new Set([...caps.derived, ...caps.traced])],
783
+ undeclaredManifest: caps.undeclaredDerived,
784
+ undeclaredCode: caps.undeclaredTraced,
785
+ unused: caps.unused,
786
+ alwaysRequired: CAP_ALWAYS.map((c) => c.id),
787
+ },
788
+ runs: runs ?? null,
563
789
  };
564
790
  if (opts.json) {
565
791
  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
@@ -569,14 +795,32 @@ function check(opts, dir) {
569
795
  process.stdout.write(`[${r.level.padEnd(4)}] ${r.code.padEnd(14)} ${r.message}\n`);
570
796
  }
571
797
  process.stdout.write(
572
- `---\n结论:契约违规 ${failures.length} 条;建议 ${warnings.length} 条;` +
798
+ `---\n结论:违规 ${failures.length} 条;建议 ${warnings.length} 条;` +
573
799
  `退出码 ${failures.length ? 1 : 0}${failures.length ? "" : "(建议不阻断)"}\n`,
574
800
  );
801
+ if (caps) {
802
+ process.stdout.write(`恒开必测(不写声明):${CAP_ALWAYS.map((c) => `${c.id}(${c.name})`).join("、")}\n`);
803
+ }
575
804
  if (suggestions.length) process.stdout.write(`建议:\n${suggestions.map((s) => ` - ${s}`).join("\n")}\n`);
576
805
  }
577
806
  return failures.length ? 1 : 0;
578
807
  }
579
808
 
809
+ // ── capabilities 子命令 ────────────────────────────────────────────────────
810
+
811
+ function capabilitiesCmd(opts) {
812
+ if (opts.json) {
813
+ process.stdout.write(`${JSON.stringify({ always: CAP_ALWAYS, optIn: CAP_OPT_IN }, null, 2)}\n`);
814
+ return 0;
815
+ }
816
+ process.stdout.write("恒开能力(任何产品都在用,**不写进 capabilities**,准出必测):\n");
817
+ for (const c of CAP_ALWAYS) process.stdout.write(` ${c.id.padEnd(22)} ${c.name}\n`);
818
+ process.stdout.write("\n声明式能力(用了必须写进 manifest capabilities):\n");
819
+ for (const c of CAP_OPT_IN) process.stdout.write(` ${c.id.padEnd(22)} ${c.name} 触发:${c.trigger}\n`);
820
+ process.stdout.write("\n准出要求(UT/接口/UI 各层的断言方向)见平台仓 docs/specs/能力注册表.md。\n");
821
+ return 0;
822
+ }
823
+
580
824
  // ── 入口 ──────────────────────────────────────────────────────────────────
581
825
 
582
826
  function main() {
@@ -589,8 +833,9 @@ function main() {
589
833
  const opts = parsed.opts;
590
834
  if (opts.help) { process.stdout.write(`${HELP}\n`); return 0; }
591
835
  if (opts.version) { process.stdout.write(`${CLI_VERSION}\n`); return 0; }
836
+ if (opts.cmd === "capabilities") return capabilitiesCmd(opts);
592
837
  if (opts.cmd !== "init" && opts.cmd !== "check") {
593
- usageError(opts.cmd ? `未知子命令:${opts.cmd}` : "缺子命令(init / check)");
838
+ usageError(opts.cmd ? `未知子命令:${opts.cmd}` : "缺子命令(init / check / capabilities)");
594
839
  }
595
840
  const dir = path.resolve(opts.dir ?? process.cwd());
596
841
  if (fs.existsSync(dir) && !fs.statSync(dir).isDirectory()) {