carlos-flow 2.13.0 → 2.14.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.
package/main.js ADDED
@@ -0,0 +1,267 @@
1
+ // main.js —— Carlos 工作流(chip 沙箱入口)
2
+ //
3
+ // 为什么是「两段式目录」(Cindy 插件手册 §3.5):
4
+ // 本插件有 20 个 flow_* 操作,而宿主对 tools 声明有**硬上限 16 项**;
5
+ // 20 个端点级操作塞进去必然被拒装。手册给的解法是只声明两个元工具
6
+ // `list_tools` / `call_tool`,把目录与分发表放在 main.js 里自己维护。
7
+ //
8
+ // 分工(重要,别把职责搞混):
9
+ // · 每个操作的**权威说明与参数 schema**不在这里抄一份 —— 一律向随包 MCP 服务端
10
+ // 取 `tools/list`(单一真源 src/index.js),避免文档与实现漂移;
11
+ // · 这里只维护「操作 → 类目」映射与「该类目调用前必须知道的 RULES」。
12
+ // · scripts/full-audit.mjs 会校验:类目表覆盖服务端全部工具、不多不少。
13
+ //
14
+ // 沙箱约束:本文件跑在无文件、无 Node 的沙箱页里,只有一个全局 `cindy`。
15
+ // 所有真实工作都由 `cindy.node.request` 转给随包 MCP 服务端(node.protocol = mcp-stdio)。
16
+
17
+ // ---- 类目与规则 -----------------------------------------------------------
18
+ //
19
+ // rules 会被**随结果一起下发**(手册要求:只给工具名与说明、把规则留到调用失败
20
+ // 后才说,是不合格的目录)。所以每条都写成「调用前必须知道的一句话」。
21
+ var CATEGORIES = [
22
+ {
23
+ name: 'gate',
24
+ label: '门禁主链',
25
+ summary: '留痕 → 领名额 → 派发 → 裁定',
26
+ rules: [
27
+ '改代码 / 配置 / 文档(T2)之前必须先 flow_submit_requirement 留痕;没卡不许派发、不许裁定。',
28
+ 'PASS 只能由已领取 auditor 角色的会话落下(executor 自批会被拒)。',
29
+ 'scope 为空的卡按 fail-closed 处理:任何文件改动都算越界。',
30
+ '激活占位卡(activation_pending 非空)必须先补齐 scope / acceptance / verify.cmd,否则 claim / dispatch / verdict 全被拒。',
31
+ ],
32
+ members: ['flow_submit_requirement', 'flow_claim', 'flow_dispatch', 'flow_verdict'],
33
+ },
34
+ {
35
+ name: 'verify',
36
+ label: '验证与负对照',
37
+ summary: '跑验证命令 + 证明测试有判别力',
38
+ rules: [
39
+ '验证命令由任务卡的 verify.cmd 指定,executor 不得自选测试项。',
40
+ 'flow_run_verify 通过后代码再改动即失效(STALE),必须重跑。',
41
+ '记 PASS 前必须 flow_falsify:改动前跑必须失败、改动后跑必须通过,否则视为空测试。',
42
+ '负对照会临时把文件改回旧内容;返回值里的 restore.ok=false 表示工作区还原没通过核对,要立刻人工确认。',
43
+ ],
44
+ members: ['flow_run_verify', 'flow_falsify'],
45
+ },
46
+ {
47
+ name: 'audit',
48
+ label: '双轴审查与流水',
49
+ summary: 'Standards / Spec 两轴取证 + 审计流水查询',
50
+ rules: [
51
+ 'PASS 前两轴(standards、spec)都必须有结论,且 card_ts 与当前卡一致(旧卡结论不算数)。',
52
+ '任一轴 FAIL 硬拦;WARN 不硬拦,但会随裁定一起返回(warn_findings),汇报时不能吞。',
53
+ 'flow_audit 只读审计流水,可验证哈希链完整性;它不产生裁定。',
54
+ ],
55
+ members: ['flow_audit_axes', 'flow_audit_submit', 'flow_audit_guard', 'flow_audit'],
56
+ },
57
+ {
58
+ name: 'infra',
59
+ label: '状态·协议·还原',
60
+ summary: '看进度、读协议、免检、还原计划、越界自查',
61
+ rules: [
62
+ 'flow_status 是唯一的进度真源;汇报「做到哪一步」前先读它,别凭记忆答。',
63
+ 'flow_bypass 只能在用户明确说「直接干 / 免检 / 别管流程」时开启,且每次开关都进审计流水。',
64
+ 'flow_revert_plan 只出还原计划,绝不自动执行;真正回滚要人工确认。',
65
+ 'flow_check_scope 不传 paths 时会自己跑 git diff 取当前改动,用来在裁定前自查越界。',
66
+ ],
67
+ members: [
68
+ 'flow_status', 'flow_protocol', 'flow_mode', 'flow_bypass', 'flow_add_user_msg',
69
+ 'flow_save_result', 'flow_revert_plan', 'flow_check_scope', 'flow_diff_hunks',
70
+ ],
71
+ },
72
+ {
73
+ name: 'trigger',
74
+ label: '智能触发',
75
+ summary: '判断这条用户消息是否该启动工作流',
76
+ rules: [
77
+ '由宿主在收到用户消息时调用;达标时会实际激活(写用户原话 + 开占位卡),而不只是打分。',
78
+ '未达阈值只如实返回评分与决策,不做任何写入 —— 不要把它当「无条件开卡」用。',
79
+ ],
80
+ members: ['flow_trigger_check'],
81
+ },
82
+ ];
83
+
84
+ var CATEGORY_BY_TOOL = {};
85
+ CATEGORIES.forEach(function (c) {
86
+ c.members.forEach(function (name) { CATEGORY_BY_TOOL[name] = c; });
87
+ });
88
+
89
+ // 长任务:verify / falsify 可能各跑上百秒,期间按 45s 发心跳续命,
90
+ // 免得主机把这次 tool-call 判成超时(窗口默认 330s)。
91
+ var LONG_RUNNING_TOOLS = { flow_run_verify: true, flow_falsify: true, flow_dispatch: true };
92
+ var HEARTBEAT_MS = 45000;
93
+ // 单次 Node 请求:沉默窗口 120s(宿主上限),总时长放宽到 15 分钟。
94
+ // 负对照要跑两次命令,120s 的沉默窗口对「两次各 60s」仍然够用。
95
+ var NODE_TIMEOUT_MS = 120000;
96
+ var NODE_MAX_TOTAL_MS = 900000;
97
+
98
+ var toolsCache = null;
99
+
100
+ async function loadTools() {
101
+ if (toolsCache) return toolsCache;
102
+ var res = await cindy.node.request({
103
+ method: 'tools/list',
104
+ params: {},
105
+ timeoutMs: NODE_TIMEOUT_MS,
106
+ maxTotalMs: NODE_MAX_TOTAL_MS,
107
+ });
108
+ if (!res || !res.ok) {
109
+ throw new Error('取工具目录失败:' + (res && res.message ? res.message : '未知原因'));
110
+ }
111
+ var list = (res.result && res.result.tools) || [];
112
+ var byName = {};
113
+ list.forEach(function (t) { byName[t.name] = t; });
114
+ toolsCache = { list: list, byName: byName };
115
+ return toolsCache;
116
+ }
117
+
118
+ function fail(msg, errorCode, message, extra) {
119
+ var out = { type: 'tool-result', callId: msg.callId, ok: false, errorCode: errorCode, message: message };
120
+ if (extra) out.result = extra;
121
+ return out;
122
+ }
123
+
124
+ function overview() {
125
+ return {
126
+ ok: true,
127
+ total: CATEGORIES.reduce(function (n, c) { return n + c.members.length; }, 0),
128
+ categories: CATEGORIES.map(function (c) {
129
+ return { name: c.name, label: c.label, count: c.members.length, summary: c.summary };
130
+ }),
131
+ hint: '传 category 取该类目的工具明细与 RULES,再用 call_tool 执行;不传 category 只看概览。',
132
+ };
133
+ }
134
+
135
+ async function listTools(msg) {
136
+ var args = msg.args || {};
137
+ var category = args.category;
138
+
139
+ if (category === undefined || category === null || category === '') {
140
+ return { type: 'tool-result', callId: msg.callId, ok: true, result: overview() };
141
+ }
142
+
143
+ var cat = null;
144
+ for (var i = 0; i < CATEGORIES.length; i++) {
145
+ if (CATEGORIES[i].name === String(category).trim()) { cat = CATEGORIES[i]; break; }
146
+ }
147
+ if (!cat) {
148
+ return fail(msg, 'UNKNOWN_CATEGORY',
149
+ '没有这个类目:' + category + '。可用类目:' + CATEGORIES.map(function (c) { return c.name; }).join(' / ') +
150
+ '(不传 category 可看概览)',
151
+ { categories: CATEGORIES.map(function (c) { return c.name; }) });
152
+ }
153
+
154
+ var catalog = await loadTools();
155
+ var tools = [];
156
+ var missing = [];
157
+ cat.members.forEach(function (name) {
158
+ var t = catalog.byName[name];
159
+ if (!t) { missing.push(name); return; }
160
+ tools.push({ name: t.name, description: t.description, parameters: t.inputSchema || { type: 'object', properties: {} } });
161
+ });
162
+ if (missing.length) {
163
+ return fail(msg, 'CATALOG_DRIFT',
164
+ '服务端缺少类目 ' + cat.name + ' 声明的操作:' + missing.join('、') +
165
+ '。这属于版本不一致(插件清单比服务端新/旧),请重新安装插件或升级 carlos-flow 后再试。',
166
+ { missing: missing });
167
+ }
168
+
169
+ return {
170
+ type: 'tool-result',
171
+ callId: msg.callId,
172
+ ok: true,
173
+ result: { ok: true, category: cat.name, label: cat.label, tool_count: tools.length, rules: cat.rules, tools: tools },
174
+ };
175
+ }
176
+
177
+ async function callToolRequest(msg) {
178
+ var args = msg.args || {};
179
+ var name = args.name;
180
+ var callArgs = args.args;
181
+
182
+ if (typeof name !== 'string' || name.trim() === '') {
183
+ return fail(msg, 'MISSING_NAME',
184
+ 'call_tool 需要 name(操作名)。先调 list_tools 看有哪些操作,再把它返回的 name 原样传进来。',
185
+ { categories: CATEGORIES.map(function (c) { return c.name; }) });
186
+ }
187
+ name = name.trim();
188
+
189
+ var catalog = await loadTools();
190
+ var tool = catalog.byName[name];
191
+ if (!tool) {
192
+ var names = catalog.list.map(function (t) { return t.name; });
193
+ return fail(msg, 'UNKNOWN_TOOL',
194
+ '没有这个操作:' + name + '。可用操作共 ' + names.length + ' 个:' + names.join('、') +
195
+ '。先调 list_tools(category) 取明细(含参数说明与 RULES)再重试。',
196
+ { available_tools: names });
197
+ }
198
+
199
+ if (callArgs !== undefined && callArgs !== null && (typeof callArgs !== 'object' || Array.isArray(callArgs))) {
200
+ return fail(msg, 'INVALID_ARGS',
201
+ 'args 必须是 JSON 对象(键值对)。' + name + ' 的参数 schema 见 result.schema。',
202
+ { schema: tool.inputSchema || { type: 'object', properties: {} }, rules: rulesOf(name) });
203
+ }
204
+ var payload = callArgs || {};
205
+
206
+ // 参数形状自查:只提示,不改写(真正的校验在服务端 validateToolArgs)。
207
+ var lacks = [];
208
+ var required = (tool.inputSchema && tool.inputSchema.required) || [];
209
+ required.forEach(function (k) {
210
+ if (payload[k] === undefined || payload[k] === null || payload[k] === '') lacks.push(k);
211
+ });
212
+ if (lacks.length) {
213
+ return fail(msg, 'MISSING_FIELDS',
214
+ name + ' 缺少必填参数:' + lacks.join('、') + '。参数 schema 与 RULES 见 result,按它补齐后重试。',
215
+ { schema: tool.inputSchema || {}, rules: rulesOf(name), missing: lacks });
216
+ }
217
+
218
+ var heartbeat = null;
219
+ if (LONG_RUNNING_TOOLS[name]) {
220
+ heartbeat = setInterval(function () {
221
+ try { cindy.send({ type: 'tool-progress', callId: msg.callId }); } catch (e) { /* 续命失败不影响主流程 */ }
222
+ }, HEARTBEAT_MS);
223
+ }
224
+
225
+ try {
226
+ var res = await cindy.node.request({
227
+ method: 'tools/call',
228
+ params: { name: name, arguments: payload },
229
+ callId: msg.callId,
230
+ cancelWithCall: true,
231
+ timeoutMs: NODE_TIMEOUT_MS,
232
+ maxTotalMs: NODE_MAX_TOTAL_MS,
233
+ });
234
+ if (!res || !res.ok) {
235
+ return fail(msg, 'NODE_REQUEST_FAILED',
236
+ '执行 ' + name + ' 时随包 Node 服务没有正常回包:' + (res && res.message ? res.message : '未知原因') +
237
+ '。可重试一次;仍失败请检查插件是否被停用或 Node 进程被系统拦截。');
238
+ }
239
+ // 原样透传 MCP 结果:工具自身失败用 isError 表达,宿主会按错误内容展示,
240
+ // 这保证了「直接声明工具」与「经 call_tool 转发」两条路径的语义一致。
241
+ return { type: 'tool-result', callId: msg.callId, ok: true, result: { mcpResult: res.result } };
242
+ } finally {
243
+ if (heartbeat) clearInterval(heartbeat);
244
+ }
245
+ }
246
+
247
+ function rulesOf(toolName) {
248
+ var cat = CATEGORY_BY_TOOL[toolName];
249
+ return cat ? cat.rules : [];
250
+ }
251
+
252
+ cindy.onHostMessage(async function (msg) {
253
+ if (!msg || msg.type !== 'tool-call') return;
254
+ try {
255
+ var out;
256
+ if (msg.tool === 'list_tools') out = await listTools(msg);
257
+ else if (msg.tool === 'call_tool') out = await callToolRequest(msg);
258
+ else {
259
+ out = fail(msg, 'UNKNOWN_META_TOOL',
260
+ '本插件只提供 list_tools 与 call_tool 两个入口;具体门禁操作请走 call_tool(先用 list_tools 取操作名)。');
261
+ }
262
+ cindy.send(out);
263
+ } catch (e) {
264
+ cindy.send(fail(msg, 'INTERNAL',
265
+ '插件内部异常:' + (e && e.message ? e.message : String(e)) + '。可重试一次;持续失败请反馈。'));
266
+ }
267
+ });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "carlos-flow",
3
- "version": "2.13.0",
3
+ "version": "2.14.1",
4
4
  "description": "Carlos 工作流 — AI 编码 Agent 的机械门禁。留痕/派发/验证/裁定/审计/还原,约束写在代码里而非提示词里。单一包支持 Cindy/OpenCode/Cursor/Cline/VS Code/Claude Desktop。",
5
5
  "type": "module",
6
6
  "main": "src/index.js",
@@ -24,7 +24,7 @@
24
24
  "test:concurrency": "node test/concurrency-e2e.mjs",
25
25
  "test:ui": "node test/verify-ui.mjs",
26
26
  "test:acceptance": "node test/e2e-acceptance.mjs",
27
- "test:all": "npm run test && npm run test:baseline && npm run test:e2e && npm run test:p0 && npm run test:trigger && npm run test:concurrency && npm run test:acceptance && npm run test:gate && npm run test:stale && npm run test:scope && npm run test:audit && npm run test:bridge && npm run test:ui",
27
+ "test:all": "npm run test && npm run test:baseline && npm run test:e2e && npm run test:p0 && npm run test:trigger && npm run test:concurrency && npm run test:acceptance && npm run test:gate && npm run test:stale && npm run test:scope && npm run test:audit && npm run test:bridge && npm run test:clean && npm run test:ui && npm run test:sensitive && npm run test:lock && npm run test:falsify && npm run test:mcp && npm run test:dispatch",
28
28
  "test:mutation": "node scripts/mutation-check.mjs",
29
29
  "sync:readme": "node scripts/sync-readme.mjs",
30
30
  "check:readme": "node scripts/sync-readme.mjs --check",
@@ -50,14 +50,20 @@
50
50
  "check:no-dead-handler": "node scripts/check-no-dead-handler.mjs",
51
51
  "test:scope": "node test/scope-enforcement.mjs",
52
52
  "test:audit": "node test/audit-chain.mjs",
53
- "test:bridge": "node test/bridge-identity.mjs",
53
+ "test:bridge": "node test/bridge-identity.mjs && node test/bridge-idle.mjs",
54
54
  "sync:version": "node scripts/sync-version.mjs",
55
55
  "check:version": "node scripts/check-repo-parity.mjs",
56
56
  "test:gate": "node test/publish-gate.test.mjs",
57
57
  "install:hooks": "node scripts/install-hooks.mjs",
58
58
  "check:hooks": "node scripts/install-hooks.mjs --check",
59
59
  "test:stale": "node test/verify-stale.test.mjs",
60
- "check:templates": "node scripts/check-templates.mjs"
60
+ "test:sensitive": "node test/sensitive-config.mjs",
61
+ "test:lock": "node test/state-lock.mjs",
62
+ "test:falsify": "node test/falsify-restore.mjs",
63
+ "test:mcp": "node test/mcp-stdio.mjs",
64
+ "test:dispatch": "node test/cindy-dispatch.mjs",
65
+ "check:templates": "node scripts/check-templates.mjs",
66
+ "test:clean": "node test/clean-command.mjs"
61
67
  },
62
68
  "keywords": [
63
69
  "carlos",
@@ -82,10 +88,9 @@
82
88
  "engines": {
83
89
  "node": ">=22.0.0"
84
90
  },
85
- "dependencies": {
86
- "@modelcontextprotocol/sdk": "^1.29.0"
87
- },
91
+ "dependencies": {},
88
92
  "files": [
93
+ "main.js",
89
94
  "client/",
90
95
  "src/",
91
96
  "bridge/",
@@ -15,7 +15,7 @@ const PURE_DOC_TOOLS = new Set(["flow_protocol"]);
15
15
 
16
16
  // 真实副作用词表(含本项目实际使用的封装函数与 fs 操作)
17
17
  const REAL_WORK =
18
- /\b(await|async|loadState|saveState|readManifest|saveAgentResult|buildRevertPlan|revertPlan|audit|spawn|spawnSync|execFileSync|execSync|readFileSync|writeFileSync|appendFileSync|mkdirSync|unlinkSync|rmSync|renameSync|copyFileSync|withStateLock|gitHead|verifyAuditChain|computeFingerprint|checkScope|enforceScope|parseCard|validateCard|sanitizeSid)\b/;
18
+ /\b(await|async|loadState|saveState|writeUserMessage|getUserMessages|readManifest|saveAgentResult|buildRevertPlan|revertPlan|audit|spawn|spawnSync|execFileSync|execSync|readFileSync|writeFileSync|appendFileSync|mkdirSync|unlinkSync|rmSync|renameSync|copyFileSync|withStateLock|gitHead|verifyAuditChain|computeFingerprint|checkScope|enforceScope|parseCard|validateCard|sanitizeSid)\b/;
19
19
 
20
20
  // 常量返回特征:整段函数体只有一个 return ok({...}) / return {...},无任何其它语句
21
21
  function isConstantReturn(body) {
@@ -16,7 +16,7 @@
16
16
  //
17
17
  // 运行:node scripts/check-templates.mjs
18
18
 
19
- import { readFileSync } from "node:fs";
19
+ import { readFileSync, existsSync } from "node:fs";
20
20
  import { join, dirname } from "node:path";
21
21
  import { fileURLToPath } from "node:url";
22
22
 
@@ -44,7 +44,6 @@ const rootYaml = WIN_ROOT.replace(/\\/g, "/");
44
44
  console.log("▶ JSON 模板:Windows 路径渲染后必须可解析且路径无损");
45
45
 
46
46
  const jsonTemplates = [
47
- ["ghost.json", (t) => t.replace(/__ROOT__/g, rootJson)],
48
47
  ["opencode.json.template", (t) => t.replace(/__ROOT__/g, rootJson)],
49
48
  ["templates/cursor/mcp.json", (t) => t.replace(/__ROOT__/g, rootJson)],
50
49
  ["templates/cline/mcp.json", (t) => t.replace(/__ROOT__/g, rootJson)],
@@ -92,10 +91,50 @@ try {
92
91
  bad(".mcprc.template 读不到:" + e.message);
93
92
  }
94
93
 
94
+ // ---- ghost.json:插件包清单(chip 相对路径 / 老式绝对路径,两形态都要自洽)----
95
+ //
96
+ // chip 形态下 entry / node.entry 是**包内相对路径**(Forge 打包与市场安装要用),
97
+ // 所以不再要求出现 __ROOT__;`init --target cindy` 会把它们渲染成绝对路径
98
+ // (渲染函数在 client/carlos.js 的 renderRelativeEntries)。
99
+ {
100
+ const rel = "ghost.json";
101
+ let raw = "";
102
+ try {
103
+ raw = readFileSync(join(ROOT, rel), "utf8");
104
+ } catch (e) {
105
+ bad(`${rel} 读不到:${e.message}`);
106
+ }
107
+ if (raw) {
108
+ if (raw.includes("__ROOT__")) {
109
+ try {
110
+ JSON.parse(raw.replace(/__ROOT__/g, rootJson));
111
+ ok(`${rel}(含 __ROOT__)渲染后可解析`);
112
+ } catch (e) {
113
+ bad(`${rel} 含 __ROOT__,但渲染后无法解析:${e.message}`);
114
+ }
115
+ } else {
116
+ let parsed = null;
117
+ try {
118
+ parsed = JSON.parse(raw);
119
+ ok(`${rel} 是合法 JSON`);
120
+ } catch (e) {
121
+ bad(`${rel} 不是合法 JSON:${e.message}`);
122
+ }
123
+ if (parsed) {
124
+ const refs = [parsed.entry, parsed.settingsHtml, parsed.icon, parsed.node && parsed.node.entry]
125
+ .filter((x) => typeof x === "string" && x !== "");
126
+ const missing = refs.filter((r) => !/^https?:/.test(r) && !existsSync(join(ROOT, r)));
127
+ if (missing.length) bad(`${rel} 引用的包内文件不存在:${missing.join(", ")}`);
128
+ else ok(`${rel} 引用的包内文件都存在(相对路径包清单)`);
129
+ }
130
+ }
131
+ }
132
+ }
133
+
95
134
  console.log("▶ 反例确认:旧的裸替换写法必须确实产出非法 JSON");
96
135
 
97
136
  {
98
- const raw = readFileSync(join(ROOT, "ghost.json"), "utf8");
137
+ const raw = readFileSync(join(ROOT, "templates", "cursor", "mcp.json"), "utf8");
99
138
  const oldOut = raw.replace(/__ROOT__/g, WIN_ROOT);
100
139
  try {
101
140
  JSON.parse(oldOut);
@@ -59,7 +59,9 @@ const walk = (dir, depth = 0) => {
59
59
  let entries = [];
60
60
  try { entries = readdirSync(dir); } catch { return; }
61
61
  for (const e of entries) {
62
- if (e === "node_modules" || e === ".git" || e === "docs") continue;
62
+ // .mutation-report.md 是 mutation-check 跑完写的**生成产物**(已 gitignore),
63
+ // 它的表头本来就会讲「旧包名」这件事 —— 扫进来只会产生假红。
64
+ if (e === "node_modules" || e === ".git" || e === "docs" || e === ".mutation-report.md") continue;
63
65
  const full = join(dir, e);
64
66
  let st;
65
67
  try { st = statSync(full); } catch { continue; }
@@ -186,10 +188,34 @@ for (const tpl of ["ghost.json", "opencode.json", "templates/cursor/mcp.json", "
186
188
  const mcprc = read(".mcprc.template") || "";
187
189
  if (!mcprc.includes("carlos-flow")) P("模板", ".mcprc.template 未声明 carlos-flow");
188
190
  if (!mcprc.includes("__ROOT__")) P("模板", ".mcprc.template 缺少 __ROOT__ 占位符");
189
- for (const tpl of ["ghost.json", "opencode.json"]) {
191
+ for (const tpl of ["opencode.json"]) {
190
192
  const t = read(tpl) || "";
191
193
  if (!t.includes("__ROOT__")) P("模板", `${tpl} 缺少 __ROOT__ 占位符(init 渲染不到实际路径)`);
192
194
  }
195
+ // ghost.json 是**插件包清单**:chip 形态下 entry / node.entry 都是包内相对路径,
196
+ // 由 client/carlos.js 的 renderRelativeEntries 在 `init --target cindy` 时渲染成绝对路径。
197
+ // 因此它两种形态都合法,但必须自洽:
198
+ // · 有 __ROOT__ → 渲染后必须是合法 JSON(老式绝对路径清单)
199
+ // · 没有 __ROOT__ → 所有引用文件必须真实存在于仓库里(相对路径清单)
200
+ {
201
+ const ghostRaw = read("ghost.json") || "";
202
+ if (ghostRaw.includes("__ROOT__")) {
203
+ const rendered = ghostRaw.replace(/__ROOT__/g, JSON.stringify(process.cwd()).slice(1, -1));
204
+ if (!readJsonText(rendered)) P("模板", "ghost.json 含 __ROOT__,但渲染后不是合法 JSON");
205
+ } else {
206
+ const refs = [];
207
+ const m = ghostRaw.match(/"entry"\s*:\s*"([^"]+)"/g) || [];
208
+ for (const line of m) refs.push(line.replace(/^"entry"\s*:\s*"/, "").replace(/"$/, ""));
209
+ if (ghostRaw.includes('"entry"') && refs.length === 0) P("模板", "ghost.json 的 entry 解析不出来");
210
+ for (const ref of refs) {
211
+ if (/^https?:/.test(ref)) continue;
212
+ if (!read(ref)) P("模板", `ghost.json 引用的文件不存在:${ref}`);
213
+ }
214
+ if (/\.node\.entry|"node"/.test(ghostRaw) && !/"protocol"\s*:\s*"mcp-stdio"/.test(ghostRaw)) {
215
+ N("模板", "ghost.json 的 node.protocol 不是 mcp-stdio(仅在随包 stdio MCP 场景下需要)");
216
+ }
217
+ }
218
+ }
193
219
 
194
220
  // ========== 7. package.json 字段 ==========
195
221
  console.log("▶ 6. package.json 字段");
@@ -221,15 +247,49 @@ if (/carlos-flow-cindy|carlos-flow-opencode/.test(relWf)) P("CI", "release.yml
221
247
 
222
248
  // ========== 9. ghost.json 工具清单 ==========
223
249
  console.log("▶ 8. ghost.json 工具清单");
250
+ const readJsonText = (text) => {
251
+ try { return JSON.parse(text); } catch { return null; }
252
+ };
224
253
  const ghostJson = readJson("ghost.json");
225
254
  const idx = read("src/index.js") || "";
226
255
  const uniqueServer = [...new Set([...idx.matchAll(/name:\s*"(flow_[a-z_]+)"/g)].map((m) => m[1]))];
227
256
  const ghostTools = (ghostJson?.tools || []).map((t) => t.name);
228
- if (ghostTools.length !== uniqueServer.length) {
229
- P("工具清单", `ghost.json 声明 ${ghostTools.length} 个,服务端实际 ${uniqueServer.length} 个`);
257
+
258
+ // 两种合法形态:
259
+ // A. 直接声明:ghost.json 逐条列出全部 flow_*(宿主上限 16,超过直接拒装)
260
+ // B. 两段式目录:只声明 list_tools / call_tool,目录与分发表在 main.js(宿主 §3.5)
261
+ // —— 这种形态下「工具清单」的守卫对象变成 **main.js 的类目表**:
262
+ // 它必须恰好覆盖服务端全部工具,否则某个操作在 Cindy 里根本点不到(静默丢失)。
263
+ const TWO_LEVEL = ghostTools.length === 2 && ghostTools.includes("list_tools") && ghostTools.includes("call_tool");
264
+
265
+ if (TWO_LEVEL) {
266
+ const mainJs = read("main.js") || "";
267
+ const members = [...mainJs.matchAll(/members:\s*\[([^\]]*)\]/gs)]
268
+ .flatMap((m) => [...m[1].matchAll(/'([^']+)'/g)].map((x) => x[1]));
269
+ const uniqMembers = [...new Set(members)];
270
+ if (!mainJs) P("工具清单", "ghost.json 走两段式,但仓库里没有 main.js");
271
+ if (uniqMembers.length !== uniqueServer.length) {
272
+ P("工具清单", `main.js 类目表覆盖 ${uniqMembers.length} 个操作,服务端实际 ${uniqueServer.length} 个`);
273
+ }
274
+ for (const t of uniqueServer) if (!uniqMembers.includes(t)) P("工具清单", `main.js 类目表缺操作 ${t}(Cindy 里将无法调用)`);
275
+ for (const t of uniqMembers) if (!uniqueServer.includes(t)) P("工具清单", `main.js 类目表声明了服务端不存在的操作 ${t}`);
276
+ // 被声明的每个成员都必须落在工具名前缀上,防止把类目名当工具名写进去
277
+ for (const t of uniqMembers) if (!/^flow_/.test(t)) P("工具清单", `main.js 类目表里的 ${t} 不是 flow_* 操作`);
278
+ if (ghostJson?.kind !== "chip") P("工具清单", `两段式插件必须 kind=chip(当前 ${ghostJson?.kind})`);
279
+ if (ghostJson?.entry !== "main.js") P("工具清单", `两段式插件的 entry 必须是 main.js(当前 ${ghostJson?.entry})`);
280
+ const nodeEntry = ghostJson?.node?.entry;
281
+ if (!nodeEntry || !read(nodeEntry)) P("工具清单", `ghost.json 的 node.entry 指向不存在的文件:${nodeEntry}`);
282
+ if (ghostJson?.node?.protocol !== "mcp-stdio") P("工具清单", `两段式 + 随包 MCP 需要 node.protocol=mcp-stdio(当前 ${ghostJson?.node?.protocol})`);
283
+ if (/__ROOT__/.test(String(nodeEntry))) P("工具清单", "chip 的 node.entry 不能是 __ROOT__ 占位符(安装后不会渲染)");
284
+ N("工具清单", `两段式目录:list_tools / call_tool + main.js 类目表覆盖全部 ${uniqueServer.length} 个操作`);
285
+ } else {
286
+ if (ghostTools.length !== uniqueServer.length) {
287
+ P("工具清单", `ghost.json 声明 ${ghostTools.length} 个,服务端实际 ${uniqueServer.length} 个`);
288
+ }
289
+ for (const t of uniqueServer) if (!ghostTools.includes(t)) P("工具清单", `ghost.json 缺工具 ${t}`);
290
+ for (const t of ghostTools) if (!uniqueServer.includes(t)) P("工具清单", `ghost.json 声明了服务端不存在的工具 ${t}`);
291
+ if (ghostTools.length > 16) P("工具清单", `直接声明的工具 ${ghostTools.length} 个,超过宿主上限 16 —— 必须改两段式目录`);
230
292
  }
231
- for (const t of uniqueServer) if (!ghostTools.includes(t)) P("工具清单", `ghost.json 缺工具 ${t}`);
232
- for (const t of ghostTools) if (!uniqueServer.includes(t)) P("工具清单", `ghost.json 声明了服务端不存在的工具 ${t}`);
233
293
 
234
294
  // ---- 输出 ----
235
295
  console.log("\n" + "=".repeat(72));
@@ -73,8 +73,14 @@ const TRAILER_RE = /^(Assisted-by|Co-authored-by|Signed-off-by):/i;
73
73
  // 之前的写法用「英文词数」直接判,会把
74
74
  // 「exitCode=127(command not found),记 PASS 的前置证据永远拿不到」
75
75
  // 这类「中文句子 + 引用的英文报错」误判 —— 那是合规的中文注释。
76
+ // 「有中文」的判定必须包含**中文标点**(、。,「」();:…)+ 全角区。
77
+ // 背景(2026-11-18 实测):提交正文的中文长句会跨行折断,断开后的续行可能
78
+ // 只剩列举项(如「check:anchors 17/17、check:params、check:full、」)——
79
+ // 这类行里没有任何汉字,只有顿号,却被判成英文叙述,属于**假阳性**。
80
+ // 加入标点区后仍然抓得到真正的英文段落(英文句子不会带顿号与全角括号)。
81
+ const CJK_RE = /[一-鿿 -〿＀-￯‘-‟…]/;
76
82
  const isEnglishNarration = (text, minWords) => {
77
- if (/[一-鿿]/.test(text)) return false; // 有中文 → 合规
83
+ if (CJK_RE.test(text)) return false; // 有中文(含中文标点)→ 合规
78
84
 
79
85
  // 剥离「引用的原文」:中文句子里的英文报错原文、代码块、标识符引用
80
86
  let s = text