carlos-flow 2.6.3 → 2.8.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.
@@ -0,0 +1,88 @@
1
+ #!/usr/bin/env node
2
+ // check-no-dead-handler.mjs — 禁止重复注册同一 request schema
3
+ //
4
+ // 为什么要它:
5
+ // 2026-11-07 的第三方审查发现 src/index.js 里 CallToolRequestSchema
6
+ // **注册了两次**(1132 行与 1213 行)。
7
+ //
8
+ // MCP SDK 的 setRequestHandler 内部是 Map.set → 后注册的覆盖先注册的,
9
+ // 于是先注册的那个(含约 17 行)**永远不会执行** —— 是一段死代码。
10
+ //
11
+ // 当前行为之所以正确,只是因为「带参数校验的那个恰好注册在后面」:
12
+ // · 谁先谁后是一种**隐式约定**,没有任何东西守着它;
13
+ // · 任何一次重排、插入、合并都会静默丢掉参数校验
14
+ // (required 字段 / 类型 / enum 全部失效)—— 而且测试**不会**变红。
15
+ //
16
+ // 所以本门禁把「同一 schema 只能注册一次」变成硬约束。
17
+ //
18
+ // 退出码:0 = 无重复注册;1 = 发现重复(打印位置)
19
+ import { readFileSync } from "node:fs";
20
+ import { resolve, dirname, join } from "node:path";
21
+ import { fileURLToPath } from "node:url";
22
+
23
+ const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
24
+
25
+ let failed = 0;
26
+ const pass = (m) => console.log(` ✅ ${m}`);
27
+ const fail = (m) => { console.log(` ❌ ${m}`); failed++; };
28
+
29
+ console.log("=".repeat(72));
30
+ console.log("Carlos Flow · 重复注册门禁(同一 request schema 只能注册一次)");
31
+ console.log("=".repeat(72));
32
+
33
+ const files = ["src/index.js"];
34
+ for (const f of files) {
35
+ let src = "";
36
+ try { src = readFileSync(join(ROOT, f), "utf8"); } catch { continue; }
37
+
38
+ // 统计 setRequestHandler(X, ...) 的出现,按 schema 分组
39
+ const bySchema = new Map();
40
+ const re = /setRequestHandler\(\s*([A-Za-z_][A-Za-z0-9_]*)/g;
41
+ let m;
42
+ while ((m = re.exec(src)) !== null) {
43
+ const schema = m[1];
44
+ const line = src.slice(0, m.index).split("\n").length;
45
+ if (!bySchema.has(schema)) bySchema.set(schema, []);
46
+ bySchema.get(schema).push(line);
47
+ }
48
+
49
+ console.log(`\n▶ ${f}`);
50
+ for (const [schema, lines] of bySchema) {
51
+ if (lines.length > 1) {
52
+ fail(`${schema} 被注册了 ${lines.length} 次(第 ${lines.join(", ")} 行)—— ` +
53
+ `后注册的会覆盖先注册的,先注册的是永不执行的死代码`);
54
+ } else {
55
+ pass(`${schema} 只注册一次(第 ${lines[0]} 行)`);
56
+ }
57
+ }
58
+ }
59
+
60
+ // ---- 额外:MCP server 装配段的 handler 与工具实现必须对得上 ----
61
+ console.log("\n▶ 工具实现 ↔ handler 装配");
62
+ try {
63
+ const src = readFileSync(join(ROOT, "src/index.js"), "utf8");
64
+ const toolsM = src.match(/const TOOLS = \[([\s\S]*?)\n\];/);
65
+ const declared = toolsM
66
+ ? [...toolsM[1].matchAll(/name:\s*"(flow_[a-z_]+)"/g)].map((x) => x[1])
67
+ : [];
68
+ const hasDispatchLookup = /TOOLS\.find\([\s\S]{0,80}?\.name\s*===/.test(src);
69
+ if (hasDispatchLookup) pass("CallTool handler 通过 TOOLS.find 分发到工具实现");
70
+ else fail("CallTool handler 找不到按 name 分发到工具实现的逻辑");
71
+ const hasValidation = /validateToolArgs\(/.test(src);
72
+ if (hasValidation) pass("CallTool handler 调用了 validateToolArgs(参数校验未丢失)");
73
+ else fail("CallTool handler 没有调用 validateToolArgs —— 参数校验可能已丢失");
74
+ if (declared.length === 16) pass(`TOOLS 声明 ${declared.length} 个工具`);
75
+ else fail(`TOOLS 声明了 ${declared.length} 个工具(期望 16)`);
76
+ } catch (e) {
77
+ fail(`读取 src/index.js 失败:${e.message}`);
78
+ }
79
+
80
+ console.log("\n" + "=".repeat(72));
81
+ if (failed) {
82
+ console.log(`❌ 重复注册检查失败:${failed} 项问题`);
83
+ console.log("=".repeat(72));
84
+ process.exit(1);
85
+ }
86
+ console.log("✅ 重复注册检查全部通过");
87
+ console.log("=".repeat(72));
88
+ process.exit(0);
@@ -0,0 +1,188 @@
1
+ #!/usr/bin/env node
2
+ // check-params.mjs — 「工具参数不得静默失效」门禁
3
+ //
4
+ // 为什么要它:
5
+ // 2026-11-07 的第三方审查发现 flow_audit 的 inputSchema 里声明了 date 参数、
6
+ // 工具描述也写着「可按日期过滤」,但 handler 里算出了 rawDate 却**从未使用**
7
+ // —— 文件路径仍用 localDate()。
8
+ //
9
+ // 这个 bug 的隐蔽之处:它**不报错**、测试也全绿,只是安静地返回错误的数据
10
+ // (传 date=2020-01-01 拿到的是今天的数据)。属于典型的「静默失效」。
11
+ //
12
+ // 本门禁的判定:对每个工具的 inputSchema 声明的每个参数,
13
+ // 断言它在 handler(或该工具直接调用的下游函数)里**真的被读取**。
14
+ //
15
+ // 退出码:0 = 无静默失效;1 = 发现静默失效(逐条打印)
16
+ import { readFileSync } from "node:fs";
17
+ import { resolve, dirname, join } from "node:path";
18
+ import { fileURLToPath } from "node:url";
19
+
20
+ const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
21
+ const read = (p) => { try { return readFileSync(join(ROOT, p), "utf8"); } catch { return null; } };
22
+
23
+ let failed = 0;
24
+ const pass = (m) => console.log(` ✅ ${m}`);
25
+ const fail = (m) => { console.log(` ❌ ${m}`); failed++; };
26
+ const section = (t) => console.log(`\n▶ ${t}`);
27
+
28
+ console.log("=".repeat(72));
29
+ console.log("Carlos Flow · 参数有效性门禁(inputSchema 声明 ↔ handler 实际读取)");
30
+ console.log("=".repeat(72));
31
+
32
+ const indexSrc = read("src/index.js") || "";
33
+ const stateSrc = read("src/state.js") || "";
34
+
35
+ /** 从 src 的第 idx 个字符开始(idx 指向 '{'),返回配对括号内的内容与结束位置 */
36
+ function matchBraces(src, idx) {
37
+ if (src[idx] !== "{") return null;
38
+ let depth = 0;
39
+ for (let i = idx; i < src.length; i++) {
40
+ const c = src[i];
41
+ if (c === "{") depth++;
42
+ else if (c === "}") {
43
+ depth--;
44
+ if (depth === 0) return { body: src.slice(idx + 1, i), end: i };
45
+ }
46
+ }
47
+ return null;
48
+ }
49
+
50
+ /** 抽取 TOOLS 数组内容 */
51
+ function extractTools(src) {
52
+ const arrStart = src.indexOf("const TOOLS = [");
53
+ if (arrStart < 0) return [];
54
+ const arrBody = src.slice(arrStart);
55
+ const end = arrBody.indexOf("\n];");
56
+ const list = arrBody.slice(0, end < 0 ? arrBody.length : end);
57
+
58
+ const tools = [];
59
+ const re = /name:\s*"(flow_[a-z_]+)"/g;
60
+ const marks = [];
61
+ let m;
62
+ while ((m = re.exec(list)) !== null) marks.push({ name: m[1], at: m.index });
63
+ for (let i = 0; i < marks.length; i++) {
64
+ const start = marks[i].at;
65
+ const stop = i + 1 < marks.length ? marks[i + 1].at : list.length;
66
+ const block = list.slice(start, stop);
67
+
68
+ // inputSchema.properties
69
+ const schemaAt = block.indexOf("inputSchema:");
70
+ const schemaOpen = block.indexOf("{", schemaAt);
71
+ const schema = schemaOpen >= 0 ? matchBraces(block, schemaOpen) : null;
72
+ let props = [];
73
+ if (schema) {
74
+ const pAt = schema.body.indexOf("properties:");
75
+ const pOpen = schema.body.indexOf("{", pAt);
76
+ const pBlock = pOpen >= 0 ? matchBraces(schema.body, pOpen) : null;
77
+ if (pBlock) {
78
+ // 只取**顶层**直接子键 —— 嵌套 schema 里的 items / properties / path / line
79
+ // 不是工具参数,误当参数会报一堆假问题。
80
+ props = [];
81
+ const depthOf = (pos) => {
82
+ let d = 0;
83
+ for (let i = 0; i < pos; i++) {
84
+ if (pBlock.body[i] === "{") d++;
85
+ else if (pBlock.body[i] === "}") d--;
86
+ }
87
+ return d;
88
+ };
89
+ const keyRe = /([A-Za-z_][A-Za-z0-9_]*)\s*:\s*\{/g;
90
+ let km;
91
+ while ((km = keyRe.exec(pBlock.body)) !== null) {
92
+ if (depthOf(km.index) === 0) props.push(km[1]);
93
+ }
94
+ }
95
+ }
96
+ // handler 体
97
+ const hAt = block.indexOf("handler:");
98
+ let handler = "";
99
+ if (hAt >= 0) {
100
+ const hOpen = block.indexOf("{", hAt);
101
+ const hBlock = hOpen >= 0 ? matchBraces(block, hOpen) : null;
102
+ handler = hBlock ? hBlock.body : block.slice(hAt);
103
+ }
104
+ tools.push({ name: marks[i].name, props, handler });
105
+ }
106
+ return tools;
107
+ }
108
+
109
+ /** 抽取具名函数的函数体 */
110
+ function extractFunction(src, name) {
111
+ const at = src.indexOf(`function ${name}(`);
112
+ if (at < 0) return null;
113
+ // 跳过参数列表(`opts = {}` 里也有花括号,不能当函数体起点)
114
+ let i = src.indexOf("(", at);
115
+ let depth = 0;
116
+ let open = -1;
117
+ for (; i < src.length; i++) {
118
+ const c = src[i];
119
+ if (c === "(") depth++;
120
+ else if (c === ")") {
121
+ depth--;
122
+ if (depth === 0) { i++; break; }
123
+ }
124
+ }
125
+ while (i < src.length && src[i] !== "{") i++;
126
+ open = i;
127
+ const b = open >= 0 ? matchBraces(src, open) : null;
128
+ return b ? b.body : null;
129
+ }
130
+
131
+ const tools = extractTools(indexSrc);
132
+ section(`共解析到 ${tools.length} 个工具`);
133
+
134
+ // ---- 逐工具逐参数检查 ----
135
+ const IGNORE = new Set(["sessionId", "cwd"]); // 有明确通用处理,但仍确认被读
136
+ for (const t of tools) {
137
+ if (!t.props.length) continue;
138
+ const unused = [];
139
+ for (const p of t.props) {
140
+ const used = new RegExp(`\\b${p}\\b`).test(t.handler);
141
+ if (!used) unused.push(p);
142
+ }
143
+ if (unused.length) {
144
+ fail(`工具 ${t.name}:inputSchema 声明了但 handler 从未读取 → ${unused.join(", ")}`);
145
+ }
146
+ }
147
+ if (!failed) pass("所有工具的 inputSchema 参数都在 handler 里被真实读取");
148
+
149
+ // ---- 专项:state.js 里「算出来却没用」的死变量 ----
150
+ section("死变量检测(算出却从未使用)");
151
+ for (const [file, src] of [["src/state.js", stateSrc], ["src/index.js", indexSrc]]) {
152
+ const deadVars = [];
153
+ const re = /^[ \t]*const\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*=/gm;
154
+ let m;
155
+ while ((m = re.exec(src)) !== null) {
156
+ const name = m[1];
157
+ if (["i", "j", "k", "n", "r", "t", "e", "a", "b", "c", "d", "f", "s", "v", "x", "y"].includes(name)) continue;
158
+ // 取该变量所在语句的结束位置
159
+ let stmtEnd = src.indexOf(";", m.index);
160
+ if (stmtEnd < 0) continue;
161
+ const after = src.slice(stmtEnd + 1);
162
+ if (!new RegExp(`\\b${name}\\b`).test(after)) deadVars.push(name);
163
+ }
164
+ if (deadVars.length) {
165
+ fail(`${file}:存在「算出却从未使用」的死变量 → ${deadVars.join(", ")}`);
166
+ }
167
+ }
168
+ if (!failed) pass("没有「算出却从未使用」的死变量");
169
+
170
+ // ---- 专项:opts.date 必须在下游真的用上 ----
171
+ section("date 参数贯通检查");
172
+ const readAuditBody = extractFunction(stateSrc, "readAudit");
173
+ const verifyBody = extractFunction(stateSrc, "verifyAuditChain");
174
+ const usesDate = (b) => b && /rawDate[}`]*\.jsonl/.test(b);
175
+ if (usesDate(readAuditBody)) pass("readAudit 用 rawDate 构造文件路径");
176
+ else fail("readAudit 没有用 rawDate 构造文件路径(date 参数静默失效)");
177
+ if (usesDate(verifyBody)) pass("verifyAuditChain 用 rawDate 构造文件路径");
178
+ else fail("verifyAuditChain 没有用 rawDate 构造文件路径(date 参数静默失效)");
179
+
180
+ console.log("\n" + "=".repeat(72));
181
+ if (failed) {
182
+ console.log(`❌ 参数有效性检查失败:${failed} 项问题`);
183
+ console.log("=".repeat(72));
184
+ process.exit(1);
185
+ }
186
+ console.log("✅ 参数有效性检查全部通过");
187
+ console.log("=".repeat(72));
188
+ process.exit(0);
@@ -1,53 +1,53 @@
1
- #!/usr/bin/env node
2
- // 清理 README 中被重复注入的「语言栏 + 版本行」(只保留文档头部那一处)。
3
- //
4
- // 背景:早期版本用脚本给每个章节都插入了一行语言切换栏和版本行,
5
- // 结果这些行被粘在 Markdown 表格行尾(如 `| ... |**语言 / Languages:** ...`),
6
- // 破坏表格渲染,也让读者难以阅读。本脚本把它们收回到文档头部一处。
7
- import { readFileSync, writeFileSync } from "node:fs";
8
-
9
- const NOISE = /\*\*语言 \/ Languages:\*\*|\*\*Language \/ Languages:\*\*|\*\*版本 \/ Version:\*\*|\*\*Version:\*\*/;
10
-
11
- const files = process.argv.slice(2);
12
- for (const f of files) {
13
- const text = readFileSync(f, "utf8");
14
- const lines = text.split("\n");
15
- const out = [];
16
- let navSeen = 0;
17
- let verSeen = 0;
18
- let removed = 0;
19
-
20
- for (const line of lines) {
21
- const isNav = /\*\*语言 \/ Languages:\*\*|\*\*Language \/ Languages:\*\*/.test(line);
22
- const isVer = /\*\*版本 \/ Version:\*\*|\*\*Version:\*\*/.test(line);
23
-
24
- if (isNav || isVer) {
25
- const counter = isNav ? "nav" : "ver";
26
- if (counter === "nav") navSeen += 1; else verSeen += 1;
27
- const keepFirst = counter === "nav" ? navSeen === 1 : verSeen === 1;
28
- if (!keepFirst) {
29
- removed += 1;
30
- // 若这一行还粘着表格内容,说明它是被拼到行尾的,把表格内容保留下来
31
- const cleaned = line
32
- .replace(/\*\*语言 \/ Languages:\*\*[^\n]*$/u, "")
33
- .replace(/\*\*Language \/ Languages:\*\*[^\n]*$/u, "")
34
- .replace(/\*\*版本 \/ Version:\*\*[^\n]*$/u, "")
35
- .replace(/\*\*Version:\*\*[^\n]*$/u, "")
36
- .trimEnd();
37
- if (cleaned) out.push(cleaned);
38
- continue;
39
- }
40
- }
41
- out.push(line);
42
- }
43
-
44
- // 折叠 3 个以上连续空行
45
- const text2 = out.join("\n").replace(/\n{3,}/g, "\n\n");
46
-
47
- if (text2 !== text) {
48
- writeFileSync(f, text2, "utf8");
49
- console.log(`cleaned ${f}: removed ${removed} noise line(s)`);
50
- } else {
51
- console.log(`no change ${f}`);
52
- }
53
- }
1
+ #!/usr/bin/env node
2
+ // 清理 README 中被重复注入的「语言栏 + 版本行」(只保留文档头部那一处)。
3
+ //
4
+ // 背景:早期版本用脚本给每个章节都插入了一行语言切换栏和版本行,
5
+ // 结果这些行被粘在 Markdown 表格行尾(如 `| ... |**语言 / Languages:** ...`),
6
+ // 破坏表格渲染,也让读者难以阅读。本脚本把它们收回到文档头部一处。
7
+ import { readFileSync, writeFileSync } from "node:fs";
8
+
9
+ const NOISE = /\*\*语言 \/ Languages:\*\*|\*\*Language \/ Languages:\*\*|\*\*版本 \/ Version:\*\*|\*\*Version:\*\*/;
10
+
11
+ const files = process.argv.slice(2);
12
+ for (const f of files) {
13
+ const text = readFileSync(f, "utf8");
14
+ const lines = text.split("\n");
15
+ const out = [];
16
+ let navSeen = 0;
17
+ let verSeen = 0;
18
+ let removed = 0;
19
+
20
+ for (const line of lines) {
21
+ const isNav = /\*\*语言 \/ Languages:\*\*|\*\*Language \/ Languages:\*\*/.test(line);
22
+ const isVer = /\*\*版本 \/ Version:\*\*|\*\*Version:\*\*/.test(line);
23
+
24
+ if (isNav || isVer) {
25
+ const counter = isNav ? "nav" : "ver";
26
+ if (counter === "nav") navSeen += 1; else verSeen += 1;
27
+ const keepFirst = counter === "nav" ? navSeen === 1 : verSeen === 1;
28
+ if (!keepFirst) {
29
+ removed += 1;
30
+ // 若这一行还粘着表格内容,说明它是被拼到行尾的,把表格内容保留下来
31
+ const cleaned = line
32
+ .replace(/\*\*语言 \/ Languages:\*\*[^\n]*$/u, "")
33
+ .replace(/\*\*Language \/ Languages:\*\*[^\n]*$/u, "")
34
+ .replace(/\*\*版本 \/ Version:\*\*[^\n]*$/u, "")
35
+ .replace(/\*\*Version:\*\*[^\n]*$/u, "")
36
+ .trimEnd();
37
+ if (cleaned) out.push(cleaned);
38
+ continue;
39
+ }
40
+ }
41
+ out.push(line);
42
+ }
43
+
44
+ // 折叠 3 个以上连续空行
45
+ const text2 = out.join("\n").replace(/\n{3,}/g, "\n\n");
46
+
47
+ if (text2 !== text) {
48
+ writeFileSync(f, text2, "utf8");
49
+ console.log(`cleaned ${f}: removed ${removed} noise line(s)`);
50
+ } else {
51
+ console.log(`no change ${f}`);
52
+ }
53
+ }