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.
@@ -1,164 +1,164 @@
1
- #!/usr/bin/env node
2
- // lang-audit.mjs — 产物语言体检(中文合规守卫)
3
- //
4
- // 为什么需要这个守卫:
5
- // 2026-11-07 发生过一次真实事故 —— 同一会话里对话回复全是中文,
6
- // 但**连续 5 个 git 提交信息写成了完整英文段落**,用户当场指为「非常严重的技术事故」。
7
- //
8
- // 根因不是「没看到用户要求」(要求早已写入记忆),而是:
9
- // · 对话语言是合规的,肉眼扫一遍「回复」完全看不出问题;
10
- // · 漏检的全部是**产物**(提交信息、注释、脚本文案、文档正文),
11
- // 而产物会持久化并对外分发(进 GitHub、进 npm 包),影响面远大于一次对话。
12
- //
13
- // 所以「我说的是中文的」不能作为合规判据 —— 必须**单独检查产物**。
14
- // 本脚本把这件事自动化,让它不依赖临场自觉。
15
- //
16
- // 检查范围:
17
- // 1) git 提交信息(标题 + 正文,排除代码块与含中文的行)
18
- // 2) 源码注释(.js/.mjs/.cjs/.sh/.yml/.yaml)
19
- //
20
- // 允许英文的例外(外部接口约束,不算违反):
21
- // 标识符、命令、路径、报错原文、API 字段名、日志原文、技术专有名词、
22
- // 用户自己写的英文、以及被明确要求产出的英文材料(如 README.en.md)。
23
- //
24
- // 退出码:0 = 合规;1 = 发现英文叙述(逐条打印位置)
25
- import { execFileSync } from "node:child_process";
26
- import { readFileSync, readdirSync, statSync } from "node:fs";
27
- import { join, resolve, dirname } from "node:path";
28
- import { fileURLToPath } from "node:url";
29
-
30
- const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
31
-
32
- // 允许出现在中文语境里的英文词(标识符 / 专有名词 / 外部接口名)
33
- // 读文件并按行拆分。
34
- // ⚠️ 必须处理 CRLF:JavaScript 正则的 `.` **不匹配 `\r`**(它是行终止符),
35
- // 所以「按 \n 拆分」在 Windows 上会留下一行尾的 `\r`,
36
- // 导致 `(.+)$` 完全匹配不上 —— 注释扫描会**静默扫不到任何一行**,
37
- // 体检结果就是假绿。
38
- // 这正是 2026-11-07 实际发生的事:本地(CRLF)全部通过,CI(LF)却报出真问题。
39
- const readLines = (file) => {
40
- const raw = readFileSync(file, "utf8");
41
- return raw.split(/\r?\n/);
42
- };
43
- // 注意:必须**按词排除**而不是整行排除 —— 否则
44
- // 「fix(release): add missing shebang to bin entry」
45
- // 里的 fix / release 会让整行被放行,英文叙述就漏检了。
46
- const ALLOWED_WORDS = new Set([
47
- "npm", "mcp", "node", "json", "yaml", "yml", "github", "gitlab", "ci", "carlos",
48
- "readme", "changelog", "trigger", "guide", "migration", "error", "timeout",
49
- "ok", "verify", "scope", "acceptance", "sessionid", "init", "target", "git",
50
- "commit", "release", "docs", "fix", "feat", "chore", "test", "yarn", "npx",
51
- "shell", "stdin", "stdout", "stderr", "http", "https", "api", "url", "repo",
52
- "src", "lib", "bin", "tool", "tools", "service", "server", "client", "bridge",
53
- "plugin", "template", "templates", "license", "mit", "apache", "bsd", "utf",
54
- "linux", "windows", "macos", "opencode", "cursor", "cline", "claude", "copilot",
55
- "version", "semver", "keep", "monorepo", "shim", "shebang", "validatecard",
56
- "tier", "read", "goal", "quote", "cmd", "argv", "env", "pkg", "args",
57
- "opts", "params", "config", "keywordweights", "readonly", "intentwords",
58
- "mutatingactionwords", "flow", "user", "msgs", "state",
59
- ]);
60
-
61
- const MIN_WORDS = 5; // 连续 5 个以上英文词才判定为「英文叙述」
62
- const MIN_COMMIT_WORDS = 3; // 提交信息阈值低一点(正文段落更短)
63
-
64
- // 判定规则:**一行里只要有中文字符就算合规**(标识符、报错原文、引用的英文术语
65
- // 嵌在中文句子里是正常的);只有**整行没有中文**、且英文词达到阈值时才算违规。
66
- // 之前的写法用「英文词数」直接判,会把
67
- // 「exitCode=127(command not found),记 PASS 的前置证据永远拿不到」
68
- // 这类「中文句子 + 引用的英文报错」误判 —— 那是合规的中文注释。
69
- const isEnglishNarration = (text, minWords) => {
70
- if (/[一-鿿]/.test(text)) return false; // 有中文 → 合规
71
-
72
- // 剥离「引用的原文」:中文句子里的英文报错原文、代码块、标识符引用
73
- let s = text
74
- .replace(/[「」『』“”"'‘’`][^「」『』“”"'‘’`]*[「」『』“”"'‘’`]/g, " ")
75
- .replace(/`[^`]*`/g, " ");
76
-
77
- // 命令行 / 路径示例行:含 `--` 参数、以命令前缀开头、或形如 a/b/c
78
- if (/^\s*(\$|>)?\s*(node|npm|npx|yarn|git|bash|sh|python3?|curl|cd|echo|export|carlos-flow|carlos)\b/i.test(s)) return false;
79
- if (/\s--[a-z][\w-]*/i.test(s)) return false;
80
- if (/^[A-Za-z0-9_.\-/]+\s*[=:]/i.test(s.trim()) && !/\s/.test(s.trim())) return false;
81
-
82
- const words = (s.match(/[A-Za-z][A-Za-z'-]{2,}/g) || []).map((w) => w.toLowerCase());
83
- if (words.length < minWords) return false;
84
- // 去掉允许词后仍需达到足够密度,否则整句都是专有名词/标识符
85
- const residual = words.filter((w) => !ALLOWED_WORDS.has(w));
86
- if (residual.length < Math.max(3, Math.ceil(words.length * 0.4))) return false;
87
- return true;
88
- };
89
-
90
- let problems = 0;
91
- const report = (where, text) => {
92
- console.log(` ❌ ${where}`);
93
- console.log(` ${text.slice(0, 110)}`);
94
- problems++;
95
- };
96
-
97
- // ---- 1. 提交信息 ----
98
- console.log("▶ 提交信息");
99
- try {
100
- const raw = execFileSync("git", ["log", "--format=%H%x00%B%x00%x00", "-15"], {
101
- cwd: ROOT,
102
- encoding: "utf8",
103
- });
104
- const parts = raw.split("\u0000").filter((s) => s.trim());
105
- let commitProblems = 0;
106
- for (let i = 0; i < parts.length; i += 2) {
107
- const sha = (parts[i] || "").trim();
108
- const body = parts[i + 1] || "";
109
- let inCode = false;
110
- for (const line of body.split("\n")) {
111
- if (/^\s*```/.test(line)) { inCode = !inCode; continue; }
112
- if (inCode) continue;
113
- const t = line.trim();
114
- if (!t) continue;
115
- if (!isEnglishNarration(t, MIN_COMMIT_WORDS)) continue;
116
- report(`提交 ${sha.slice(0, 7)}`, t);
117
- commitProblems++;
118
- }
119
- }
120
- if (commitProblems === 0) console.log(" ✅ 提交信息均为中文");
121
- } catch (e) {
122
- console.log(" ⏭ 跳过(取不到 git 历史)");
123
- }
124
-
125
- // ---- 2. 源码注释 ----
126
- console.log("\n▶ 源码注释");
127
- const walk = (dir, depth = 0) => {
128
- if (depth > 4) return [];
129
- let out = [];
130
- let entries = [];
131
- try { entries = readdirSync(dir); } catch { return out; }
132
- for (const e of entries) {
133
- if (e === "node_modules" || e === ".git") continue;
134
- const full = join(dir, e);
135
- let st;
136
- try { st = statSync(full); } catch { continue; }
137
- if (st.isDirectory()) out = out.concat(walk(full, depth + 1));
138
- else if (/\.(js|mjs|cjs|sh|yml|yaml)$/.test(e)) out.push(full);
139
- }
140
- return out;
141
- };
142
-
143
- let codeProblems = 0;
144
- for (const f of walk(ROOT)) {
145
- const rel = f.slice(ROOT.length + 1).replace(/\\/g, "/");
146
- const lines = readLines(f);
147
- lines.forEach((line, i) => {
148
- const m = line.match(/^\s*(?:\/\/|#)\s*(.+)$/);
149
- if (!m) return;
150
- const t = m[1].trim();
151
- if (!isEnglishNarration(t, MIN_WORDS)) return;
152
- report(`${rel}:${i + 1}`, t);
153
- codeProblems++;
154
- });
155
- }
156
- if (codeProblems === 0) console.log(" ✅ 源码注释均为中文");
157
-
158
- console.log("");
159
- if (problems > 0) {
160
- console.log(`❌ 产物语言体检失败:发现 ${problems} 处英文叙述`);
161
- console.log(" 修复方式:把对应内容改写为中文(标识符、命令、报错原文可保留原样)");
162
- process.exit(1);
163
- }
164
- console.log("✅ 产物语言体检通过");
1
+ #!/usr/bin/env node
2
+ // lang-audit.mjs — 产物语言体检(中文合规守卫)
3
+ //
4
+ // 为什么需要这个守卫:
5
+ // 2026-11-07 发生过一次真实事故 —— 同一会话里对话回复全是中文,
6
+ // 但**连续 5 个 git 提交信息写成了完整英文段落**,用户当场指为「非常严重的技术事故」。
7
+ //
8
+ // 根因不是「没看到用户要求」(要求早已写入记忆),而是:
9
+ // · 对话语言是合规的,肉眼扫一遍「回复」完全看不出问题;
10
+ // · 漏检的全部是**产物**(提交信息、注释、脚本文案、文档正文),
11
+ // 而产物会持久化并对外分发(进 GitHub、进 npm 包),影响面远大于一次对话。
12
+ //
13
+ // 所以「我说的是中文的」不能作为合规判据 —— 必须**单独检查产物**。
14
+ // 本脚本把这件事自动化,让它不依赖临场自觉。
15
+ //
16
+ // 检查范围:
17
+ // 1) git 提交信息(标题 + 正文,排除代码块与含中文的行)
18
+ // 2) 源码注释(.js/.mjs/.cjs/.sh/.yml/.yaml)
19
+ //
20
+ // 允许英文的例外(外部接口约束,不算违反):
21
+ // 标识符、命令、路径、报错原文、API 字段名、日志原文、技术专有名词、
22
+ // 用户自己写的英文、以及被明确要求产出的英文材料(如 README.en.md)。
23
+ //
24
+ // 退出码:0 = 合规;1 = 发现英文叙述(逐条打印位置)
25
+ import { execFileSync } from "node:child_process";
26
+ import { readFileSync, readdirSync, statSync } from "node:fs";
27
+ import { join, resolve, dirname } from "node:path";
28
+ import { fileURLToPath } from "node:url";
29
+
30
+ const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
31
+
32
+ // 允许出现在中文语境里的英文词(标识符 / 专有名词 / 外部接口名)
33
+ // 读文件并按行拆分。
34
+ // ⚠️ 必须处理 CRLF:JavaScript 正则的 `.` **不匹配 `\r`**(它是行终止符),
35
+ // 所以「按 \n 拆分」在 Windows 上会留下一行尾的 `\r`,
36
+ // 导致 `(.+)$` 完全匹配不上 —— 注释扫描会**静默扫不到任何一行**,
37
+ // 体检结果就是假绿。
38
+ // 这正是 2026-11-07 实际发生的事:本地(CRLF)全部通过,CI(LF)却报出真问题。
39
+ const readLines = (file) => {
40
+ const raw = readFileSync(file, "utf8");
41
+ return raw.split(/\r?\n/);
42
+ };
43
+ // 注意:必须**按词排除**而不是整行排除 —— 否则
44
+ // 「fix(release): add missing shebang to bin entry」
45
+ // 里的 fix / release 会让整行被放行,英文叙述就漏检了。
46
+ const ALLOWED_WORDS = new Set([
47
+ "npm", "mcp", "node", "json", "yaml", "yml", "github", "gitlab", "ci", "carlos",
48
+ "readme", "changelog", "trigger", "guide", "migration", "error", "timeout",
49
+ "ok", "verify", "scope", "acceptance", "sessionid", "init", "target", "git",
50
+ "commit", "release", "docs", "fix", "feat", "chore", "test", "yarn", "npx",
51
+ "shell", "stdin", "stdout", "stderr", "http", "https", "api", "url", "repo",
52
+ "src", "lib", "bin", "tool", "tools", "service", "server", "client", "bridge",
53
+ "plugin", "template", "templates", "license", "mit", "apache", "bsd", "utf",
54
+ "linux", "windows", "macos", "opencode", "cursor", "cline", "claude", "copilot",
55
+ "version", "semver", "keep", "monorepo", "shim", "shebang", "validatecard",
56
+ "tier", "read", "goal", "quote", "cmd", "argv", "env", "pkg", "args",
57
+ "opts", "params", "config", "keywordweights", "readonly", "intentwords",
58
+ "mutatingactionwords", "flow", "user", "msgs", "state",
59
+ ]);
60
+
61
+ const MIN_WORDS = 5; // 连续 5 个以上英文词才判定为「英文叙述」
62
+ const MIN_COMMIT_WORDS = 3; // 提交信息阈值低一点(正文段落更短)
63
+
64
+ // 判定规则:**一行里只要有中文字符就算合规**(标识符、报错原文、引用的英文术语
65
+ // 嵌在中文句子里是正常的);只有**整行没有中文**、且英文词达到阈值时才算违规。
66
+ // 之前的写法用「英文词数」直接判,会把
67
+ // 「exitCode=127(command not found),记 PASS 的前置证据永远拿不到」
68
+ // 这类「中文句子 + 引用的英文报错」误判 —— 那是合规的中文注释。
69
+ const isEnglishNarration = (text, minWords) => {
70
+ if (/[一-鿿]/.test(text)) return false; // 有中文 → 合规
71
+
72
+ // 剥离「引用的原文」:中文句子里的英文报错原文、代码块、标识符引用
73
+ let s = text
74
+ .replace(/[「」『』“”"'‘’`][^「」『』“”"'‘’`]*[「」『』“”"'‘’`]/g, " ")
75
+ .replace(/`[^`]*`/g, " ");
76
+
77
+ // 命令行 / 路径示例行:含 `--` 参数、以命令前缀开头、或形如 a/b/c
78
+ if (/^\s*(\$|>)?\s*(node|npm|npx|yarn|git|bash|sh|python3?|curl|cd|echo|export|carlos-flow|carlos)\b/i.test(s)) return false;
79
+ if (/\s--[a-z][\w-]*/i.test(s)) return false;
80
+ if (/^[A-Za-z0-9_.\-/]+\s*[=:]/i.test(s.trim()) && !/\s/.test(s.trim())) return false;
81
+
82
+ const words = (s.match(/[A-Za-z][A-Za-z'-]{2,}/g) || []).map((w) => w.toLowerCase());
83
+ if (words.length < minWords) return false;
84
+ // 去掉允许词后仍需达到足够密度,否则整句都是专有名词/标识符
85
+ const residual = words.filter((w) => !ALLOWED_WORDS.has(w));
86
+ if (residual.length < Math.max(3, Math.ceil(words.length * 0.4))) return false;
87
+ return true;
88
+ };
89
+
90
+ let problems = 0;
91
+ const report = (where, text) => {
92
+ console.log(` ❌ ${where}`);
93
+ console.log(` ${text.slice(0, 110)}`);
94
+ problems++;
95
+ };
96
+
97
+ // ---- 1. 提交信息 ----
98
+ console.log("▶ 提交信息");
99
+ try {
100
+ const raw = execFileSync("git", ["log", "--format=%H%x00%B%x00%x00", "-15"], {
101
+ cwd: ROOT,
102
+ encoding: "utf8",
103
+ });
104
+ const parts = raw.split("\u0000").filter((s) => s.trim());
105
+ let commitProblems = 0;
106
+ for (let i = 0; i < parts.length; i += 2) {
107
+ const sha = (parts[i] || "").trim();
108
+ const body = parts[i + 1] || "";
109
+ let inCode = false;
110
+ for (const line of body.split("\n")) {
111
+ if (/^\s*```/.test(line)) { inCode = !inCode; continue; }
112
+ if (inCode) continue;
113
+ const t = line.trim();
114
+ if (!t) continue;
115
+ if (!isEnglishNarration(t, MIN_COMMIT_WORDS)) continue;
116
+ report(`提交 ${sha.slice(0, 7)}`, t);
117
+ commitProblems++;
118
+ }
119
+ }
120
+ if (commitProblems === 0) console.log(" ✅ 提交信息均为中文");
121
+ } catch (e) {
122
+ console.log(" ⏭ 跳过(取不到 git 历史)");
123
+ }
124
+
125
+ // ---- 2. 源码注释 ----
126
+ console.log("\n▶ 源码注释");
127
+ const walk = (dir, depth = 0) => {
128
+ if (depth > 4) return [];
129
+ let out = [];
130
+ let entries = [];
131
+ try { entries = readdirSync(dir); } catch { return out; }
132
+ for (const e of entries) {
133
+ if (e === "node_modules" || e === ".git") continue;
134
+ const full = join(dir, e);
135
+ let st;
136
+ try { st = statSync(full); } catch { continue; }
137
+ if (st.isDirectory()) out = out.concat(walk(full, depth + 1));
138
+ else if (/\.(js|mjs|cjs|sh|yml|yaml)$/.test(e)) out.push(full);
139
+ }
140
+ return out;
141
+ };
142
+
143
+ let codeProblems = 0;
144
+ for (const f of walk(ROOT)) {
145
+ const rel = f.slice(ROOT.length + 1).replace(/\\/g, "/");
146
+ const lines = readLines(f);
147
+ lines.forEach((line, i) => {
148
+ const m = line.match(/^\s*(?:\/\/|#)\s*(.+)$/);
149
+ if (!m) return;
150
+ const t = m[1].trim();
151
+ if (!isEnglishNarration(t, MIN_WORDS)) return;
152
+ report(`${rel}:${i + 1}`, t);
153
+ codeProblems++;
154
+ });
155
+ }
156
+ if (codeProblems === 0) console.log(" ✅ 源码注释均为中文");
157
+
158
+ console.log("");
159
+ if (problems > 0) {
160
+ console.log(`❌ 产物语言体检失败:发现 ${problems} 处英文叙述`);
161
+ console.log(" 修复方式:把对应内容改写为中文(标识符、命令、报错原文可保留原样)");
162
+ process.exit(1);
163
+ }
164
+ console.log("✅ 产物语言体检通过");