@njuptlzf/agent-chat-server 0.2.0 → 0.3.0
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.
- package/dist/authz.js +15 -15
- package/dist/branding-ui.d.ts +16 -0
- package/dist/branding-ui.js +119 -0
- package/dist/manifest.js +13 -0
- package/dist/persona-config.js +12 -0
- package/dist/server.d.ts +6 -0
- package/dist/server.js +52 -0
- package/dist/session.js +2 -1
- package/dist/sqlite-stores.js +218 -218
- package/dist/suggestions.d.ts +60 -0
- package/dist/suggestions.js +107 -0
- package/dist/usage-report.js +13 -13
- package/package.json +64 -64
- package/scripts/agentchat-integrate.mjs +329 -84
- package/src/audit.ts +169 -169
- package/src/authz.ts +307 -307
- package/src/branding-ui.ts +126 -0
- package/src/events.ts +206 -206
- package/src/index.ts +26 -26
- package/src/main.ts +142 -142
- package/src/manifest.ts +575 -562
- package/src/mcp-config.ts +385 -385
- package/src/model-config.ts +424 -424
- package/src/model-failover.ts +95 -95
- package/src/models-api.ts +360 -360
- package/src/persona-config.ts +447 -436
- package/src/persona-trial.ts +121 -121
- package/src/product-routes.ts +102 -102
- package/src/server.ts +2705 -2647
- package/src/session.ts +2 -1
- package/src/sqlite-stores.ts +1040 -1040
- package/src/stores.ts +899 -899
- package/src/suggestions.ts +146 -0
- package/src/testing.ts +80 -80
- package/src/trial-grant.ts +62 -62
- package/src/usage-report.ts +86 -86
- package/src/util.ts +6 -6
|
@@ -1,39 +1,75 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
1
|
+
#!/usr/bin/env node
|
|
2
2
|
/**
|
|
3
3
|
* agentchat-integrate —— 「一句话对接 agentChat」的机械入口。
|
|
4
4
|
*
|
|
5
5
|
* 设计约束(改动前先读):
|
|
6
6
|
* ① 零第三方依赖:只用 Node 内置模块,不 import `yaml`,不 import 平台 `.ts` 源码。
|
|
7
|
-
* 装进产品仓 node_modules
|
|
7
|
+
* 装进产品仓 node_modules 后仍能独立运行;模板与能力注册表全部内嵌。
|
|
8
8
|
* ② 产品无关:脚本正文与生成物不含任何具体产品名 / 私有词 / 业务断言。
|
|
9
|
-
* ③
|
|
10
|
-
*
|
|
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.
|
|
22
|
-
const MIN_SERVER = "0.
|
|
23
|
+
const CLI_VERSION = "0.3.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
|
|
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 =
|
|
88
|
+
退出码:0 = 无违规(WARN/INFO 允许);1 = 有违规(含能力未声明、缺脚本、脚本跑挂);
|
|
89
|
+
2 = 参数错误 / 平台仓误跑护栏
|
|
51
90
|
|
|
52
|
-
|
|
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.
|
|
160
|
-
[PKG.server]: "^0.
|
|
161
|
-
[PKG.web]: "^0.
|
|
218
|
+
[PKG.protocol]: "^0.3.0",
|
|
219
|
+
[PKG.server]: "^0.3.0",
|
|
220
|
+
[PKG.web]: "^0.3.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
|
|
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
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
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: [
|
|
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
|
-
|
|
256
|
-
|
|
257
|
-
//
|
|
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
|
-
|
|
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
|
-
|
|
333
|
-
|
|
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.
|
|
411
|
+
`npm i ${PKG.protocol}@^0.3.0 ${PKG.server}@^0.3.0 ${PKG.web}@^0.3.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}
|
|
374
|
-
`npm i ${PKG.server}
|
|
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
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
"
|
|
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
|
-
|
|
498
|
-
|
|
499
|
-
const
|
|
500
|
-
|
|
501
|
-
|
|
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
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
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
|
-
|
|
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
|
|
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()) {
|