carlos-flow 2.11.0 → 2.11.3
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/CHANGELOG.md +95 -0
- package/INSTALL.md +103 -0
- package/RELEASE_NOTES.md +30 -0
- package/TRIGGER_GUIDE.md +2 -2
- package/bridge/mcp-bridge.js +19 -3
- package/check-all.sh +29 -0
- package/client/carlos.js +20 -6
- package/ghost.json +1 -1
- package/package.json +15 -4
- package/scripts/check-templates.mjs +126 -0
- package/scripts/install-hooks.mjs +153 -0
- package/scripts/publish-gate.mjs +121 -0
- package/scripts/sync-version.mjs +155 -0
- package/smoke-test.js +142 -0
- package/src/index.js +66 -1
- package/src/state.js +117 -6
- package/templates/cursor.mcp.json +11 -0
- package/templates/vscode.settings.json +11 -0
- package/templates/windsurf.mcp.json +11 -0
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
// 推 tag 前置钩子安装器
|
|
2
|
+
//
|
|
3
|
+
// 为什么需要:
|
|
4
|
+
// 1. 2026-11-13 的 v2.11.1 —— 一个**没跑过任何验证**的提交被打上 tag 并推上远端,
|
|
5
|
+
// 里面包含一个语法错误的冒烟测试和一个只有 23 行的残缺 bridge。
|
|
6
|
+
// 2. 推 `v*` tag **等于**触发 npm 自动发布 —— 推错 tag 的代价远大于推错分支。
|
|
7
|
+
//
|
|
8
|
+
// 装上之后,`git push` 只要涉及 tag,就会自动跑:
|
|
9
|
+
// - `./check-all.sh`(语法校验 + 真 RPC 往返冒烟测试)
|
|
10
|
+
// - `npm run sync:version` 的等价校验(版本号在 4 处是否一致)
|
|
11
|
+
// - tag 重名检查
|
|
12
|
+
// 任何一项不过,**推送被阻断**,远端不会出现带缺陷的 tag。
|
|
13
|
+
//
|
|
14
|
+
// 用法:
|
|
15
|
+
// node scripts/install-hooks.mjs # 安装
|
|
16
|
+
// node scripts/install-hooks.mjs --check # 只检查装没装 / 是否最新
|
|
17
|
+
|
|
18
|
+
import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from "node:fs";
|
|
19
|
+
import { join, dirname } from "node:path";
|
|
20
|
+
import { fileURLToPath } from "node:url";
|
|
21
|
+
import { execFileSync } from "node:child_process";
|
|
22
|
+
|
|
23
|
+
const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
|
|
24
|
+
const HOOKS_DIR = join(ROOT, ".git", "hooks");
|
|
25
|
+
const HOOK_PATH = join(HOOKS_DIR, "pre-push");
|
|
26
|
+
|
|
27
|
+
// 钩子正文。用 bash 写(Git for Windows 自带 bash)。
|
|
28
|
+
// 关键:只对 **tag** 推送生效,普通分支推送不受影响。
|
|
29
|
+
const HOOK = `#!/bin/bash
|
|
30
|
+
# ============================================================
|
|
31
|
+
# Carlos Flow —— 推 tag 前置门禁(由 scripts/install-hooks.mjs 生成)
|
|
32
|
+
#
|
|
33
|
+
# 背景:推 v* tag 会触发 GitHub Actions 自动 npm publish。
|
|
34
|
+
# 没有这道门禁时,v2.11.1 那样「没跑过验证」的提交会被打 tag 推上远端。
|
|
35
|
+
#
|
|
36
|
+
# 规则:只对 **tag 推送** 生效;分支推送直接放行。
|
|
37
|
+
# ============================================================
|
|
38
|
+
|
|
39
|
+
set -u
|
|
40
|
+
|
|
41
|
+
# 钩子位于 .git/hooks/ —— 仓库根是它的 ../..(不是 ..,那是 .git 目录本身)
|
|
42
|
+
REPO_ROOT="$(cd "$(dirname "\${BASH_SOURCE[0]}")/../.." && pwd)"
|
|
43
|
+
[ -f "$REPO_ROOT/package.json" ] || REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
|
|
44
|
+
cd "$REPO_ROOT" || exit 1
|
|
45
|
+
[ -f "$REPO_ROOT/package.json" ] || { echo "❌ 找不到仓库根目录(package.json)"; exit 1; }
|
|
46
|
+
|
|
47
|
+
# 从 stdin 读待推送的 ref:<local ref> <local sha> <remote ref> <remote sha>
|
|
48
|
+
PUSHING_TAG=0
|
|
49
|
+
TAG_NAME=""
|
|
50
|
+
while read -r LOCAL_REF LOCAL_SHA REMOTE_REF REMOTE_SHA; do
|
|
51
|
+
if echo "$REMOTE_REF" | grep -q '^refs/tags/'; then
|
|
52
|
+
PUSHING_TAG=1
|
|
53
|
+
TAG_NAME="\${REMOTE_REF#refs/tags/}"
|
|
54
|
+
fi
|
|
55
|
+
done
|
|
56
|
+
|
|
57
|
+
if [ "$PUSHING_TAG" -eq 0 ]; then
|
|
58
|
+
exit 0
|
|
59
|
+
fi
|
|
60
|
+
|
|
61
|
+
echo "=============================================="
|
|
62
|
+
echo "🚧 推 tag 前置门禁:$TAG_NAME"
|
|
63
|
+
echo "=============================================="
|
|
64
|
+
|
|
65
|
+
# --- 1. 版本号单一真源校验(只读) ---
|
|
66
|
+
# 版本号散落 5 处(package.json / package-lock.json / ghost.json / TRIGGER_GUIDE.md / CHANGELOG.md),
|
|
67
|
+
# 漏改任一处 release 的「单包一致性检查」就会红、发布中止。
|
|
68
|
+
# --check 只读不写:有偏差则退出 1。
|
|
69
|
+
if ! node scripts/sync-version.mjs --check >/dev/null 2>&1; then
|
|
70
|
+
echo "❌ 版本号未对齐(package.json / package-lock.json / ghost.json / TRIGGER_GUIDE.md / CHANGELOG.md)"
|
|
71
|
+
echo " 请先运行:npm run sync:version,然后提交改动"
|
|
72
|
+
exit 1
|
|
73
|
+
fi
|
|
74
|
+
# 版本已对齐但还没提交 —— tag 指向的提交里版本与工作区不一致,同样要拦。
|
|
75
|
+
if ! git diff --quiet -- package-lock.json ghost.json TRIGGER_GUIDE.md CHANGELOG.md; then
|
|
76
|
+
echo "❌ 版本相关文件有未提交改动"
|
|
77
|
+
echo " 请先提交这些改动再推 tag(tag 指向的提交必须与工作区一致)"
|
|
78
|
+
exit 1
|
|
79
|
+
fi
|
|
80
|
+
echo "✅ 版本号一致性"
|
|
81
|
+
|
|
82
|
+
# --- 2. 语法校验 + 真 RPC 往返冒烟测试 ---
|
|
83
|
+
if ! bash ./check-all.sh; then
|
|
84
|
+
echo "❌ Gatekeeper 未通过,拒绝推送 tag"
|
|
85
|
+
echo " 修好后再推;这条 gate 存在的意义就是别再推坏版本。"
|
|
86
|
+
exit 1
|
|
87
|
+
fi
|
|
88
|
+
|
|
89
|
+
# --- 3. tag 重名检查(查**远端**,不是本地) ---
|
|
90
|
+
# 正常流程就是「本地先 git tag 再 push」,本地存在是必然的;
|
|
91
|
+
# 真正要拦的是**远端已有同名 tag**(再推要么是空操作,要么需要 force)。
|
|
92
|
+
if git ls-remote --exit-code --tags origin "refs/tags/$TAG_NAME" >/dev/null 2>&1; then
|
|
93
|
+
echo "❌ 远端已存在 tag $TAG_NAME"
|
|
94
|
+
echo " 若确需覆盖:git push --force origin $TAG_NAME"
|
|
95
|
+
exit 1
|
|
96
|
+
fi
|
|
97
|
+
echo "✅ tag 名在远端可用"
|
|
98
|
+
|
|
99
|
+
echo ""
|
|
100
|
+
echo "=============================================="
|
|
101
|
+
echo "✅ 全部前置门禁通过,可以推 tag:$TAG_NAME"
|
|
102
|
+
echo " ⚠️ 提醒:推 v* tag 会触发 npm 自动发布"
|
|
103
|
+
echo "=============================================="
|
|
104
|
+
exit 0
|
|
105
|
+
`;
|
|
106
|
+
|
|
107
|
+
function main() {
|
|
108
|
+
const checkOnly = process.argv.includes("--check");
|
|
109
|
+
|
|
110
|
+
if (checkOnly) {
|
|
111
|
+
if (!existsSync(HOOK_PATH)) {
|
|
112
|
+
console.log("❌ 未安装推 tag 前置钩子");
|
|
113
|
+
process.exit(1);
|
|
114
|
+
}
|
|
115
|
+
const cur = readFileSync(HOOK_PATH, "utf8");
|
|
116
|
+
const ok = cur === HOOK;
|
|
117
|
+
console.log(ok ? "✅ 钩子已安装且为最新" : "⚠️ 钩子已安装但内容不是最新,重新安装即可");
|
|
118
|
+
process.exit(ok ? 0 : 1);
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
if (!existsSync(join(ROOT, ".git"))) {
|
|
122
|
+
console.error("❌ 当前目录不是 git 仓库");
|
|
123
|
+
process.exit(1);
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
mkdirSync(HOOKS_DIR, { recursive: true });
|
|
127
|
+
|
|
128
|
+
// 备份既有钩子(不覆盖别人的东西)
|
|
129
|
+
if (existsSync(HOOK_PATH)) {
|
|
130
|
+
const bak = HOOK_PATH + ".bak-" + Date.now();
|
|
131
|
+
copyFileSync(HOOK_PATH, bak);
|
|
132
|
+
console.log("ℹ️ 已备份原钩子:" + bak);
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
writeFileSync(HOOK_PATH, HOOK, "utf8");
|
|
136
|
+
console.log("✅ 已安装推 tag 前置钩子:" + HOOK_PATH);
|
|
137
|
+
|
|
138
|
+
// Windows 上 git 可能在提交时丢掉可执行位,这里直接修回 100755
|
|
139
|
+
try {
|
|
140
|
+
execFileSync("git", ["update-index", "--chmod=+x", ".git/hooks/pre-push"], {
|
|
141
|
+
cwd: ROOT,
|
|
142
|
+
stdio: "ignore",
|
|
143
|
+
});
|
|
144
|
+
} catch {
|
|
145
|
+
// .git/hooks 不在 index 里,这条会失败,属预期,忽略
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
console.log("");
|
|
149
|
+
console.log("生效范围:只拦截 **tag 推送**;普通分支推送不受影响。");
|
|
150
|
+
console.log("自检:node scripts/install-hooks.mjs --check");
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
main();
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
// 发布闸 —— 判断「本次 tag 版本是否值得发到 npm」
|
|
2
|
+
//
|
|
3
|
+
// 为什么单独抽成脚本:
|
|
4
|
+
// 1. 原实现把 semver 比较的**退出码方向写反了**,导致「版本更高」被拦截、
|
|
5
|
+
// 「版本更低」被放行,与发布闸的本意完全相反(补历史 tag 会把 latest 拉回旧版,
|
|
6
|
+
// 正是这道闸要防的事)。抽成脚本后可以写单元测试锁住方向。
|
|
7
|
+
// 2. 判定逻辑必须能离线测试,不能只能在 CI 里用真实 npm registry 验证。
|
|
8
|
+
//
|
|
9
|
+
// 判定规则(唯一真源,workflow 只调用本脚本):
|
|
10
|
+
// registry 没有任何已发布版本 → 允许发布
|
|
11
|
+
// 本次版本 严格大于 registry 的 latest → 允许发布
|
|
12
|
+
// 否则(等于或小于) → 跳过 npm publish,只建 GitHub Release
|
|
13
|
+
//
|
|
14
|
+
// 用法:
|
|
15
|
+
// node scripts/publish-gate.mjs # 读 package.json 版本 + 查 npm
|
|
16
|
+
// node scripts/publish-gate.mjs --version 2.11.2 --latest 2.11.0
|
|
17
|
+
// node scripts/publish-gate.mjs --count 12
|
|
18
|
+
//
|
|
19
|
+
// 输出:向 $GITHUB_OUTPUT 写 publish=true/false(若有该环境变量),并打印人话结论。
|
|
20
|
+
|
|
21
|
+
import { execFileSync } from "node:child_process";
|
|
22
|
+
import { readFileSync, appendFileSync } from "node:fs";
|
|
23
|
+
import { join, dirname } from "node:path";
|
|
24
|
+
import { fileURLToPath, pathToFileURL } from "node:url";
|
|
25
|
+
|
|
26
|
+
const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
|
|
27
|
+
|
|
28
|
+
// 语义化版本比较:a > b 返回正数,a < b 返回负数,相等返回 0
|
|
29
|
+
export function semverCompare(a, b) {
|
|
30
|
+
const pa = String(a).split(/[.-]/).map((x) => Number(x) || 0);
|
|
31
|
+
const pb = String(b).split(/[.-]/).map((x) => Number(x) || 0);
|
|
32
|
+
for (let i = 0; i < 3; i++) {
|
|
33
|
+
const x = pa[i] || 0;
|
|
34
|
+
const y = pb[i] || 0;
|
|
35
|
+
if (x !== y) return x - y;
|
|
36
|
+
}
|
|
37
|
+
return 0;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
// 纯函数:给定版本与 registry 现状,返回是否允许发布
|
|
41
|
+
export function decidePublish({ version, latest, count }) {
|
|
42
|
+
if (!latest || !count || count <= 1) {
|
|
43
|
+
return { publish: true, reason: "registry 暂无已发布版本 —— 允许发布" };
|
|
44
|
+
}
|
|
45
|
+
if (version === latest) {
|
|
46
|
+
return {
|
|
47
|
+
publish: false,
|
|
48
|
+
reason: `本次版本 ${version} 等于已发布最新版 ${latest} —— 跳过 npm publish(仅建 Release)`,
|
|
49
|
+
};
|
|
50
|
+
}
|
|
51
|
+
if (semverCompare(version, latest) > 0) {
|
|
52
|
+
return {
|
|
53
|
+
publish: true,
|
|
54
|
+
reason: `本次版本 ${version} 高于已发布最新版 ${latest} —— 允许发布`,
|
|
55
|
+
};
|
|
56
|
+
}
|
|
57
|
+
return {
|
|
58
|
+
publish: false,
|
|
59
|
+
reason: `本次版本 ${version} 不高于已发布最新版 ${latest} —— 跳过 npm publish(仅建 Release)`,
|
|
60
|
+
};
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
function argOf(name) {
|
|
64
|
+
const i = process.argv.indexOf(name);
|
|
65
|
+
return i === -1 ? null : process.argv[i + 1];
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
function pkgVersion() {
|
|
69
|
+
try {
|
|
70
|
+
return JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version;
|
|
71
|
+
} catch {
|
|
72
|
+
return "";
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
function npmQuery(args) {
|
|
77
|
+
try {
|
|
78
|
+
// Windows 上 npm 是 npm.cmd,必须走 shell 才能执行;
|
|
79
|
+
// 这里查询的全是固定的包名/字段名,不含用户输入,无注入风险。
|
|
80
|
+
return execFileSync("npm", args, {
|
|
81
|
+
encoding: "utf8",
|
|
82
|
+
shell: true,
|
|
83
|
+
stdio: ["ignore", "pipe", "ignore"],
|
|
84
|
+
}).trim();
|
|
85
|
+
} catch {
|
|
86
|
+
return "";
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
function main() {
|
|
91
|
+
const version = argOf("--version") || pkgVersion();
|
|
92
|
+
const latest = argOf("--latest") ?? npmQuery(["view", "carlos-flow", "dist-tags.latest", "--prefer-online"]);
|
|
93
|
+
const countRaw = argOf("--count") ?? npmQuery(["view", "carlos-flow", "versions", "--json", "--prefer-online"]);
|
|
94
|
+
let count = Number(countRaw) || 0;
|
|
95
|
+
if (!count && countRaw) {
|
|
96
|
+
try {
|
|
97
|
+
count = JSON.parse(countRaw).length;
|
|
98
|
+
} catch {
|
|
99
|
+
count = 0;
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
const { publish, reason } = decidePublish({
|
|
104
|
+
version,
|
|
105
|
+
latest: latest || "",
|
|
106
|
+
count,
|
|
107
|
+
});
|
|
108
|
+
|
|
109
|
+
console.log(`▶ 本次版本:${version}|registry latest:${latest || "(无)"}|已发布版本数:${count}`);
|
|
110
|
+
console.log(`${publish ? "✓" : "✗"} ${reason}`);
|
|
111
|
+
|
|
112
|
+
if (process.env.GITHUB_OUTPUT) {
|
|
113
|
+
appendFileSync(process.env.GITHUB_OUTPUT, `publish=${publish}\n`);
|
|
114
|
+
}
|
|
115
|
+
console.log(`publish=${publish}`);
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
// 仅在「直接运行本文件」时执行 main();被 import 时只导出纯函数供测试使用。
|
|
119
|
+
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
|
|
120
|
+
main();
|
|
121
|
+
}
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
// 版本号同步脚本 —— 消除「版本号散落多处」这个根因
|
|
2
|
+
//
|
|
3
|
+
// 为什么需要它:
|
|
4
|
+
// 本项目的版本号同时出现在 4 个地方(package.json / package-lock.json /
|
|
5
|
+
// ghost.json / TRIGGER_GUIDE.md / CHANGELOG.md)。人工改一处漏一处,
|
|
6
|
+
// release.yml 的「单包一致性检查」就会红,发布流程直接中止。
|
|
7
|
+
// 本脚本以 package.json 为唯一真源,把其余位置批量对齐。
|
|
8
|
+
//
|
|
9
|
+
// 用法:
|
|
10
|
+
// node scripts/sync-version.mjs 仅同步并校验(不改 CHANGELOG)
|
|
11
|
+
// node scripts/sync-version.mjs --changelog "标题" 同时在 CHANGELOG 顶部插入新条目
|
|
12
|
+
// node scripts/sync-version.mjs --date 2026-11-13 指定条目日期(默认今天)
|
|
13
|
+
// node scripts/sync-version.mjs --check 只读校验:有偏差则退出码 1 且**不写文件**
|
|
14
|
+
//
|
|
15
|
+
// --check 为什么需要:推 tag 前置钩子要判断「版本号是否已对齐且已提交」。
|
|
16
|
+
// 普通模式会写文件(退出码总是 0),没法用来做只读判定;
|
|
17
|
+
// --check 不写任何文件,有偏差就退出 1。
|
|
18
|
+
|
|
19
|
+
import { readFileSync, writeFileSync } from "node:fs";
|
|
20
|
+
import { join, dirname } from "node:path";
|
|
21
|
+
import { fileURLToPath } from "node:url";
|
|
22
|
+
|
|
23
|
+
const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
|
|
24
|
+
|
|
25
|
+
function readText(rel) {
|
|
26
|
+
try {
|
|
27
|
+
return readFileSync(join(ROOT, rel), "utf8");
|
|
28
|
+
} catch {
|
|
29
|
+
return "";
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
let changedFiles = [];
|
|
34
|
+
|
|
35
|
+
function writeText(rel, text) {
|
|
36
|
+
if (CHECK_ONLY) {
|
|
37
|
+
// --check 模式只记录,不落盘
|
|
38
|
+
if (!changedFiles.includes(rel)) changedFiles.push(rel);
|
|
39
|
+
console.log(" ❌ " + rel + " 需同步");
|
|
40
|
+
return;
|
|
41
|
+
}
|
|
42
|
+
writeFileSync(join(ROOT, rel), text, "utf8");
|
|
43
|
+
console.log(` ✏️ ${rel}`);
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function readJson(rel) {
|
|
47
|
+
try {
|
|
48
|
+
return JSON.parse(readText(rel));
|
|
49
|
+
} catch {
|
|
50
|
+
return null;
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
const argv = process.argv.slice(2);
|
|
55
|
+
const CHECK_ONLY = argv.includes("--check");
|
|
56
|
+
const changelogTitle = argv.includes("--changelog")
|
|
57
|
+
? argv[argv.indexOf("--changelog") + 1]
|
|
58
|
+
: null;
|
|
59
|
+
const dateArg = argv.includes("--date")
|
|
60
|
+
? argv[argv.indexOf("--date") + 1]
|
|
61
|
+
: null;
|
|
62
|
+
|
|
63
|
+
const pkg = readJson("package.json");
|
|
64
|
+
if (!pkg || !pkg.version) {
|
|
65
|
+
console.error("❌ 读不到 package.json 的 version");
|
|
66
|
+
process.exit(1);
|
|
67
|
+
}
|
|
68
|
+
const ver = pkg.version;
|
|
69
|
+
console.log(`▶ 目标版本:${ver}\n`);
|
|
70
|
+
|
|
71
|
+
// ---- 1. package-lock.json ----
|
|
72
|
+
const lock = readJson("package-lock.json");
|
|
73
|
+
if (lock) {
|
|
74
|
+
let changed = false;
|
|
75
|
+
if (lock.version !== ver) {
|
|
76
|
+
lock.version = ver;
|
|
77
|
+
changed = true;
|
|
78
|
+
}
|
|
79
|
+
if (lock.packages && lock.packages[""] && lock.packages[""].version !== ver) {
|
|
80
|
+
lock.packages[""].version = ver;
|
|
81
|
+
changed = true;
|
|
82
|
+
}
|
|
83
|
+
if (changed) {
|
|
84
|
+
writeText("package-lock.json", JSON.stringify(lock, null, 2) + "\n");
|
|
85
|
+
} else {
|
|
86
|
+
console.log(" ✅ package-lock.json 已是 " + ver);
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
// ---- 2. ghost.json ----
|
|
91
|
+
const ghost = readJson("ghost.json");
|
|
92
|
+
if (ghost) {
|
|
93
|
+
if (ghost.version !== ver) {
|
|
94
|
+
ghost.version = ver;
|
|
95
|
+
writeText("ghost.json", JSON.stringify(ghost, null, 2) + "\n");
|
|
96
|
+
} else {
|
|
97
|
+
console.log(" ✅ ghost.json 已是 " + ver);
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
// ---- 3. TRIGGER_GUIDE.md(两处「版本」行)----
|
|
102
|
+
let guide = readText("TRIGGER_GUIDE.md");
|
|
103
|
+
if (guide) {
|
|
104
|
+
const before = guide;
|
|
105
|
+
guide = guide.replace(/v\d+\.\d+\.\d+/g, "v" + ver);
|
|
106
|
+
if (guide !== before) {
|
|
107
|
+
writeText("TRIGGER_GUIDE.md", guide);
|
|
108
|
+
} else {
|
|
109
|
+
console.log(" ✅ TRIGGER_GUIDE.md 已是 " + ver);
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
// ---- 4. CHANGELOG.md ----
|
|
114
|
+
let changelog = readText("CHANGELOG.md");
|
|
115
|
+
if (changelog) {
|
|
116
|
+
const topMatch = changelog.match(/^## \[(\d+\.\d+\.\d+)\]/m);
|
|
117
|
+
const topVer = topMatch ? topMatch[1] : null;
|
|
118
|
+
|
|
119
|
+
if (topVer === ver) {
|
|
120
|
+
console.log(" ✅ CHANGELOG.md 顶部已是 " + ver);
|
|
121
|
+
} else if (changelogTitle) {
|
|
122
|
+
const d = dateArg || new Date().toISOString().slice(0, 10);
|
|
123
|
+
const entry = `## [${ver}] - ${d} — ${changelogTitle}\n\n### ✨ 新增 | Added\n\n- (待补充)\n\n`;
|
|
124
|
+
// 插到「---」分隔线之后、首个版本段落之前
|
|
125
|
+
const sepIdx = changelog.indexOf("\n---\n");
|
|
126
|
+
const insertAt = sepIdx === -1 ? 0 : sepIdx + "\n---\n\n".length;
|
|
127
|
+
changelog =
|
|
128
|
+
changelog.slice(0, insertAt) + entry + changelog.slice(insertAt);
|
|
129
|
+
writeText("CHANGELOG.md", changelog);
|
|
130
|
+
} else if (CHECK_ONLY) {
|
|
131
|
+
// --check 模式:只报告偏差,不退出(最后统一汇总)
|
|
132
|
+
if (!changedFiles.includes("CHANGELOG.md")) changedFiles.push("CHANGELOG.md");
|
|
133
|
+
console.log(" ❌ CHANGELOG.md 顶部需同步");
|
|
134
|
+
} else {
|
|
135
|
+
console.error(
|
|
136
|
+
`❌ CHANGELOG.md 顶部是 ${topVer || "(无)"},与 ${ver} 不一致。\n` +
|
|
137
|
+
` 请先写好 ${ver} 的变更条目,再运行:\n` +
|
|
138
|
+
` node scripts/sync-version.mjs --changelog "本版标题"`,
|
|
139
|
+
);
|
|
140
|
+
process.exit(1);
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
if (CHECK_ONLY) {
|
|
145
|
+
if (changedFiles.length) {
|
|
146
|
+
console.error(
|
|
147
|
+
"\n❌ 版本号未对齐,需同步:" + changedFiles.join("、") +
|
|
148
|
+
"\n 请运行:npm run sync:version(改完记得提交)",
|
|
149
|
+
);
|
|
150
|
+
process.exit(1);
|
|
151
|
+
}
|
|
152
|
+
console.log("\n✅ 版本号已全部对齐到 " + ver);
|
|
153
|
+
} else {
|
|
154
|
+
console.log("\n✅ 版本号已全部对齐到 " + ver);
|
|
155
|
+
}
|
package/smoke-test.js
ADDED
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
// 冒烟测试:真 RPC 往返验证 MCP 深度兼容性
|
|
2
|
+
//
|
|
3
|
+
// 关键约束(来自 bridge/mcp-bridge.js):
|
|
4
|
+
// 1. 每个请求走**独立连接** —— Bridge 响应一个请求后立刻 socket.end()
|
|
5
|
+
// 2. 请求必须带 _token(放在 params._token 或顶层 _token)
|
|
6
|
+
// 3. 速率限制 10 次/秒,本测试仅 2 次
|
|
7
|
+
import { spawn } from "node:child_process";
|
|
8
|
+
import net from "node:net";
|
|
9
|
+
import { performance } from "node:perf_hooks";
|
|
10
|
+
|
|
11
|
+
const PORT = Number(process.env.BRIDGE_PORT || 19099);
|
|
12
|
+
const TOKEN = process.env.CARLOS_BRIDGE_TOKEN || "";
|
|
13
|
+
const EXPECTED_TOOLS_COUNT = 19;
|
|
14
|
+
|
|
15
|
+
// 单次 RPC:一条连接发一个请求,收满响应就返回
|
|
16
|
+
function rpcOnce(request) {
|
|
17
|
+
return new Promise((resolve, reject) => {
|
|
18
|
+
const chunks = [];
|
|
19
|
+
let settled = false;
|
|
20
|
+
|
|
21
|
+
const finish = (fn, arg) => {
|
|
22
|
+
if (settled) return;
|
|
23
|
+
settled = true;
|
|
24
|
+
fn(arg);
|
|
25
|
+
};
|
|
26
|
+
|
|
27
|
+
const socket = net.createConnection(
|
|
28
|
+
{ port: PORT, host: "127.0.0.1" },
|
|
29
|
+
() => {
|
|
30
|
+
socket.write(JSON.stringify(request) + "\n");
|
|
31
|
+
},
|
|
32
|
+
);
|
|
33
|
+
|
|
34
|
+
socket.on("data", (d) => chunks.push(d));
|
|
35
|
+
socket.on("end", () =>
|
|
36
|
+
finish(resolve, Buffer.concat(chunks).toString("utf8")),
|
|
37
|
+
);
|
|
38
|
+
socket.on("close", () =>
|
|
39
|
+
finish(resolve, Buffer.concat(chunks).toString("utf8")),
|
|
40
|
+
);
|
|
41
|
+
socket.on("error", (err) => finish(reject, err));
|
|
42
|
+
|
|
43
|
+
setTimeout(() => {
|
|
44
|
+
socket.destroy();
|
|
45
|
+
finish(reject, new Error("RPC 超时:" + request.method));
|
|
46
|
+
}, 10000);
|
|
47
|
+
});
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
async function main() {
|
|
51
|
+
const start = performance.now();
|
|
52
|
+
|
|
53
|
+
// 第 1 次:initialize
|
|
54
|
+
const initRaw = await rpcOnce({
|
|
55
|
+
jsonrpc: "2.0",
|
|
56
|
+
id: 1,
|
|
57
|
+
method: "initialize",
|
|
58
|
+
params: {
|
|
59
|
+
protocolVersion: "2024-11-05",
|
|
60
|
+
capabilities: {},
|
|
61
|
+
clientInfo: { name: "smoke-test", version: "1.0.0" },
|
|
62
|
+
_token: TOKEN,
|
|
63
|
+
},
|
|
64
|
+
});
|
|
65
|
+
|
|
66
|
+
const initMsg = JSON.parse(initRaw.trim().split("\n").filter(Boolean).pop());
|
|
67
|
+
if (initMsg.error) {
|
|
68
|
+
throw new Error(
|
|
69
|
+
"initialize 被拒:" + JSON.stringify(initMsg.error),
|
|
70
|
+
);
|
|
71
|
+
}
|
|
72
|
+
if (!initMsg.result) {
|
|
73
|
+
throw new Error("initialize 无 result 字段:" + initRaw.trim());
|
|
74
|
+
}
|
|
75
|
+
console.log("✅ initialize 握手成功");
|
|
76
|
+
|
|
77
|
+
// 第 2 次:tools/list(独立连接)
|
|
78
|
+
const listRaw = await rpcOnce({
|
|
79
|
+
jsonrpc: "2.0",
|
|
80
|
+
id: 2,
|
|
81
|
+
method: "tools/list",
|
|
82
|
+
params: { _token: TOKEN },
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
const listMsg = JSON.parse(listRaw.trim().split("\n").filter(Boolean).pop());
|
|
86
|
+
if (listMsg.error) {
|
|
87
|
+
throw new Error("tools/list 被拒:" + JSON.stringify(listMsg.error));
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
const tools = listMsg.result?.tools || [];
|
|
91
|
+
const elapsed = (performance.now() - start).toFixed(2);
|
|
92
|
+
|
|
93
|
+
console.log(">>> RPC 往返总耗时:" + elapsed + "ms");
|
|
94
|
+
console.log(">>> 发现工具数:" + tools.length);
|
|
95
|
+
|
|
96
|
+
if (tools.length !== EXPECTED_TOOLS_COUNT) {
|
|
97
|
+
throw new Error(
|
|
98
|
+
"工具数量不符:期望 " +
|
|
99
|
+
EXPECTED_TOOLS_COUNT +
|
|
100
|
+
",实际 " +
|
|
101
|
+
tools.length,
|
|
102
|
+
);
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
console.log("🎉 深度兼容性验证通过(真 RPC 往返拿到 " + tools.length + " 个工具)");
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
const bridge = spawn(process.execPath, ["bridge/mcp-bridge.js"], {
|
|
109
|
+
stdio: ["ignore", "ignore", "inherit"],
|
|
110
|
+
env: { ...process.env },
|
|
111
|
+
});
|
|
112
|
+
|
|
113
|
+
// 等 Bridge 真正监听端口(最多 8 秒)
|
|
114
|
+
async function waitForPort() {
|
|
115
|
+
const deadline = Date.now() + 8000;
|
|
116
|
+
while (Date.now() < deadline) {
|
|
117
|
+
const ok = await new Promise((resolve) => {
|
|
118
|
+
const s = net.createConnection({ port: PORT, host: "127.0.0.1" });
|
|
119
|
+
s.on("connect", () => {
|
|
120
|
+
s.destroy();
|
|
121
|
+
resolve(true);
|
|
122
|
+
});
|
|
123
|
+
s.on("error", () => resolve(false));
|
|
124
|
+
});
|
|
125
|
+
if (ok) return true;
|
|
126
|
+
await new Promise((r) => setTimeout(r, 200));
|
|
127
|
+
}
|
|
128
|
+
return false;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
try {
|
|
132
|
+
if (!(await waitForPort())) {
|
|
133
|
+
throw new Error("Bridge 未能在 8 秒内监听 " + PORT + " 端口");
|
|
134
|
+
}
|
|
135
|
+
await main();
|
|
136
|
+
process.exitCode = 0;
|
|
137
|
+
} catch (err) {
|
|
138
|
+
console.error("💥 冒烟测试失败:" + err.message);
|
|
139
|
+
process.exitCode = 1;
|
|
140
|
+
} finally {
|
|
141
|
+
bridge.kill();
|
|
142
|
+
}
|
package/src/index.js
CHANGED
|
@@ -9,7 +9,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
|
|
|
9
9
|
import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
|
|
10
10
|
import { PROTOCOL } from "./protocol.js";
|
|
11
11
|
import { parseCard, validateCard, riskTier, isSensitive } from "./card.js";
|
|
12
|
-
import { loadState, saveState, defaultState, audit, readAudit, getUserMessages, writeUserMessage, pathExists, gitHead, isStale, isBypassed, verifyAuditChain, withStateLock, auditHashMode } from "./state.js";
|
|
12
|
+
import { loadState, saveState, defaultState, audit, readAudit, getUserMessages, writeUserMessage, pathExists, gitHead, isStale, isBypassed, verifyAuditChain, withStateLock, auditHashMode, workspaceFingerprint } from "./state.js";
|
|
13
13
|
import { buildContractPrompt, snapshotFiles, readManifest, readManifestAll, writeDispatchPrompt, saveAgentResult, runVerifyCommand, runNegativeControl, computeOutputHash, enforceScope, MAX_DISPATCH } from "./dispatch.js";
|
|
14
14
|
|
|
15
15
|
const log = (msg) => {
|
|
@@ -69,6 +69,36 @@ const verifyPassed = (state) => {
|
|
|
69
69
|
return typeof lv.cmd === "string" && lv.cmd.trim() === want;
|
|
70
70
|
};
|
|
71
71
|
|
|
72
|
+
// 验证状态四态(R4:保持 verify_passed 为 boolean,只**新增**本字段)。
|
|
73
|
+
//
|
|
74
|
+
// not_run —— 没跑过 / 没有对应当前卡片的验证结果
|
|
75
|
+
// fail —— 跑了但没通过
|
|
76
|
+
// stale —— 跑通了,但验证之后代码又变了(指纹不一致)—— 这一态正是 A1 要堵的
|
|
77
|
+
// pass —— 跑通且代码自那以后没动过
|
|
78
|
+
//
|
|
79
|
+
// 指纹不可用时(非 git 目录)按 fail-open 处理:算 pass,但在 fingerprint 字段里
|
|
80
|
+
// 如实标注「不可用」,不装作验证过(A1 R1)。
|
|
81
|
+
const verifyState = (state) => {
|
|
82
|
+
const lv = state && state.last_verify;
|
|
83
|
+
if (!lv || typeof lv !== "object") return { state: "not_run", fingerprint: "unavailable" };
|
|
84
|
+
const want = cardVerifyCmd(state);
|
|
85
|
+
if (!want || typeof lv.cmd !== "string" || lv.cmd.trim() !== want) {
|
|
86
|
+
return { state: "not_run", fingerprint: "unavailable" };
|
|
87
|
+
}
|
|
88
|
+
if (lv.ok !== true) return { state: "fail", fingerprint: "unavailable" };
|
|
89
|
+
|
|
90
|
+
const fpWas = lv.fingerprint;
|
|
91
|
+
if (!fpWas || !fpWas.ok) {
|
|
92
|
+
return { state: "pass", fingerprint: "unavailable" };
|
|
93
|
+
}
|
|
94
|
+
const fpNow = workspaceFingerprint(lv.cwd || process.cwd());
|
|
95
|
+
if (!fpNow.ok) return { state: "pass", fingerprint: "unavailable" };
|
|
96
|
+
if (fpNow.diff_sha256 !== fpWas.diff_sha256) {
|
|
97
|
+
return { state: "stale", fingerprint: fpNow.diff_sha256 };
|
|
98
|
+
}
|
|
99
|
+
return { state: "pass", fingerprint: fpNow.diff_sha256 };
|
|
100
|
+
};
|
|
101
|
+
|
|
72
102
|
// WARN 汇总条数上限:防止 WARN 通胀把返回值灌成噪音,主 Agent 反而开始忽略。
|
|
73
103
|
const WARN_FINDINGS_LIMIT = 20;
|
|
74
104
|
|
|
@@ -715,6 +745,31 @@ const TOOLS = [
|
|
|
715
745
|
"请对当前卡片重新执行 flow_run_verify,再记录裁定。");
|
|
716
746
|
}
|
|
717
747
|
|
|
748
|
+
// 防假闭环之五:验证结果必须绑定当时的**代码状态**(A1)。
|
|
749
|
+
//
|
|
750
|
+
// 前面三道判断只看「验证跑过 / 跑通了 / 命令对得上」,**不看代码变没变**。
|
|
751
|
+
// 于是存在这条绕过路径:
|
|
752
|
+
// 1. flow_run_verify 跑通 → last_verify = {ok:true, cmd:"npm test"}
|
|
753
|
+
// 2. executor 继续改代码(甚至改坏)
|
|
754
|
+
// 3. flow_verdict(PASS) → 三道全过 → 放行
|
|
755
|
+
// 指纹把「验证通过」绑定到一次**可复现的运行**:验证之后再动过代码,指纹就变了。
|
|
756
|
+
//
|
|
757
|
+
// 非 git 目录:fail-open(Carlos Flow 支持非 Git 项目),但要在 flow_status
|
|
758
|
+
// 里如实标注指纹不可用(见 R1)。
|
|
759
|
+
const fpCwd = a.cwd || (state.last_verify && state.last_verify.cwd) || process.cwd();
|
|
760
|
+
const fpWas = lv.fingerprint;
|
|
761
|
+
const fpNow = workspaceFingerprint(fpCwd);
|
|
762
|
+
if (fpWas && fpWas.ok && fpNow.ok && fpNow.diff_sha256 !== fpWas.diff_sha256) {
|
|
763
|
+
audit("decision", sessionId, {
|
|
764
|
+
kind: "verdict_denied",
|
|
765
|
+
reason: "验证结果已过期(代码在验证后被修改)",
|
|
766
|
+
fp_was: fpWas.diff_sha256,
|
|
767
|
+
fp_now: fpNow.diff_sha256,
|
|
768
|
+
});
|
|
769
|
+
return fail("验证结果已过期(STALE):验证通过后代码又被修改,当前 diff 指纹已变化。" +
|
|
770
|
+
"请重新执行 flow_run_verify 再记录裁定。");
|
|
771
|
+
}
|
|
772
|
+
|
|
718
773
|
// 防假闭环之四:越界改动必须被拦住。
|
|
719
774
|
//
|
|
720
775
|
// 「越界直接阻断」的**真实落点**在这里:判定「本次执行有没有改到
|
|
@@ -888,6 +943,9 @@ const TOOLS = [
|
|
|
888
943
|
// verify_passed:真实验证是否通过(last_verify.ok===true 且命令与当前卡片一致)。
|
|
889
944
|
// 注意 verified 只表示「是否已有裁定」,不代表验证通过——两者语义不同,不可混用。
|
|
890
945
|
verify_passed: verifyPassed(state),
|
|
946
|
+
// 四态验证状态:not_run / fail / stale / pass。
|
|
947
|
+
// stale = 验证通过后代码被改过 —— 不阻断(fail-open),但必须如实告知。
|
|
948
|
+
verify_state: verifyState(state).state,
|
|
891
949
|
completed_ok: state.completed_ok === true,
|
|
892
950
|
stale: isStale(state),
|
|
893
951
|
bypass: !!state.bypass,
|
|
@@ -1218,6 +1276,9 @@ const TOOLS = [
|
|
|
1218
1276
|
ok: result.ok,
|
|
1219
1277
|
// 输出指纹:把「验证通过」绑定到一次可复现的运行,而不是「我说过了」。
|
|
1220
1278
|
output_hash: computeOutputHash(result.exitCode, result.stdout, result.stderr),
|
|
1279
|
+
// 代码状态指纹:把「验证通过」绑定到**当时的代码状态**。
|
|
1280
|
+
// 没有它,验证通过后再改坏代码,flow_verdict(PASS) 仍会放行(见 A1)。
|
|
1281
|
+
fingerprint: workspaceFingerprint(workdir || process.cwd()),
|
|
1221
1282
|
};
|
|
1222
1283
|
saveState(sessionId, state2);
|
|
1223
1284
|
|
|
@@ -1279,6 +1340,10 @@ const TOOLS = [
|
|
|
1279
1340
|
exitCode: r.after.exitCode,
|
|
1280
1341
|
ok: r.after.ok,
|
|
1281
1342
|
output_hash: r.after.hash,
|
|
1343
|
+
// 代码状态指纹:负对照同样是一次「验证通过」,
|
|
1344
|
+
// 必须与 flow_run_verify 一样绑定代码状态,
|
|
1345
|
+
// 否则「先负对照、再改代码、再记 PASS」这条路径会绕过 STALE 闸门。
|
|
1346
|
+
fingerprint: workspaceFingerprint(workdir || process.cwd()),
|
|
1282
1347
|
};
|
|
1283
1348
|
saveState(sessionId, state2);
|
|
1284
1349
|
|