carlos-flow 2.11.0 → 2.11.2
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 +51 -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/ghost.json +1 -1
- package/package.json +11 -4
- package/scripts/publish-gate.mjs +121 -0
- package/scripts/sync-version.mjs +126 -0
- package/smoke-test.js +142 -0
- package/templates/cursor.mcp.json +11 -0
- package/templates/vscode.settings.json +11 -0
- package/templates/windsurf.mcp.json +11 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,54 @@
|
|
|
1
|
+
## [2.11.2] - 2026-11-13 — 修复 Bridge 转发通路与 Windows 黑窗,新增路径自探测
|
|
2
|
+
|
|
3
|
+
### ✨ 新增 | Added
|
|
4
|
+
|
|
5
|
+
- **路径自探测**(`bridge/mcp-bridge.js`):Bridge 依据自身文件位置自动定位 `../src/index.js`,
|
|
6
|
+
不再强制依赖 `CARLOS_FLOW_MCP_ROOT` 绝对路径;该环境变量保留为可选覆盖,向后兼容。
|
|
7
|
+
接入方只需填 bridge 脚本的路径,Cursor / VS Code / Windsurf 三端通用。
|
|
8
|
+
- **`/health` 返回真实项目根目录**(解析后的绝对路径),供客户端做 Bridge 身份比对,
|
|
9
|
+
避免端口上跑着「别的 ROOT 的 bridge」时被静默复用。
|
|
10
|
+
- **`INSTALL.md`**:Cursor / VS Code / Windsurf 三平台接入步骤、配置自检与常见问题对照表。
|
|
11
|
+
- **`scripts/sync-version.mjs`**:以 `package.json` 为唯一真源,批量对齐
|
|
12
|
+
`package-lock.json` / `ghost.json` / `TRIGGER_GUIDE.md` / `CHANGELOG.md` 的版本号,
|
|
13
|
+
消除「版本散落四处、人工改漏即发布中止」的根因。
|
|
14
|
+
|
|
15
|
+
### 🐛 修复 | Fixed
|
|
16
|
+
|
|
17
|
+
- **Bridge 转发通路缺失**:上一版把 Bridge 精简为「只 spawn 子进程、不做转发」,
|
|
18
|
+
导致平台侧发来的 `tools/list` 永远不会到达 MCP server —— 19 个工具一个都发现不了。
|
|
19
|
+
现在恢复完整的 TCP → 子进程 stdin → 按 reqId 回包链路。
|
|
20
|
+
- **Windows 黑控制台窗口**:MCP server 子进程改用 `windowsHide: true` 启动,
|
|
21
|
+
Bridge 重启时不再弹出黑色控制台窗口。
|
|
22
|
+
- **冒烟测试假阳性**:`smoke-test.js` 此前只检查一行启动日志,进程起得来就算「通过」,
|
|
23
|
+
转发断了也测不出来。现在重写为**真 RPC 往返**:起真实 Bridge → 发 `initialize` →
|
|
24
|
+
发 `tools/list` → 断言拿回全部 19 个工具。
|
|
25
|
+
- **子进程启动失败的报错可读性**:改为输出 `[Carlos-Diagnosis]` 现象 +
|
|
26
|
+
`[Carlos-Suggestion]` 修复建议,不再只丢一句 Node 原始异常。
|
|
27
|
+
|
|
28
|
+
### 🔧 发布基础设施 | Release Infrastructure
|
|
29
|
+
|
|
30
|
+
- **修发布闸 semver 方向写反的真实 bug**:旧实现里 `process.exit(semver(a,b)<=0?1:0)` 的退出码语义
|
|
31
|
+
与 shell 的 `elif` 判定相反 —— 结果「版本更高」被拦在 npm 之外、「版本更低」(补历史 tag)反而放行,
|
|
32
|
+
正好与发布闸的本意完全相反。判定逻辑抽到 `scripts/publish-gate.mjs`,
|
|
33
|
+
新增 `test/publish-gate.test.mjs` 锁住方向(10 条断言)。
|
|
34
|
+
- **修 CI 上 `check-all.sh` Permission denied**:脚本可执行位在 Windows 提交时丢失
|
|
35
|
+
(`core.fileMode` 不跟踪 exec bit),Ubuntu runner 直接 126 退出。
|
|
36
|
+
CI 改用 `bash ./check-all.sh`,并在 git index 层补上 `100755`。
|
|
37
|
+
|
|
38
|
+
### 🔒 变更 | Changed
|
|
39
|
+
|
|
40
|
+
- **`check-all.sh` 升级为 Gatekeeper 统一入口**:语法校验 + 真 RPC 冒烟测试一体,
|
|
41
|
+
退出码非 0 即阻断提交;未设置 `CARLOS_BRIDGE_TOKEN` 时自动用临时值,避免误报失败。
|
|
42
|
+
- **`package.json` 的 `files` 补齐** `INSTALL.md` / `RELEASE_NOTES.md` /
|
|
43
|
+
`check-all.sh` / `smoke-test.js`,使安装指引与自检脚本随包分发。
|
|
44
|
+
- **移除误提交的 `bridge/mcp-bridge.js.bak`**(内容是早期被截断的残缺版本,会误导后来人)。
|
|
45
|
+
|
|
46
|
+
### 🔬 验证 | Verification
|
|
47
|
+
|
|
48
|
+
- `./check-all.sh` 通过:三个文件语法校验通过,真 RPC 往返耗时约 330ms,拿回 19 个工具。
|
|
49
|
+
- 项目自带冒烟测试 `npm test` 通过(SMOKE_OK)。
|
|
50
|
+
- 单包一致性检查 `node scripts/check-repo-parity.mjs` 通过。
|
|
51
|
+
|
|
1
52
|
# 变更日志 | Changelog
|
|
2
53
|
|
|
3
54
|
> 格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/),版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)
|
package/INSTALL.md
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
# Carlos Flow 安装指南
|
|
2
|
+
|
|
3
|
+
本指南说明如何把 Carlos Flow 接入 Cursor、VS Code、Windsurf 等编程平台。
|
|
4
|
+
|
|
5
|
+
## 准备工作
|
|
6
|
+
|
|
7
|
+
1. 确认已安装 **Node.js 18+**(`node -v`)。
|
|
8
|
+
2. 准备一个 Token 字符串(自行生成,例如 `openssl rand -hex 16`),客户端与 Bridge 用同一个。
|
|
9
|
+
3. 记下 Carlos Flow 项目的安装路径,下文记为 `<INSTALL_PATH>`(即你 clone 下来的项目根目录)。
|
|
10
|
+
|
|
11
|
+
> **Bridge 自带路径自探测**:只要 `<INSTALL_PATH>/bridge/mcp-bridge.js` 在正确位置,
|
|
12
|
+
> Bridge 会自动定位同级的 `src/index.js`,**不需要**再手动设置 `CARLOS_FLOW_MCP_ROOT`。
|
|
13
|
+
> 该环境变量仅在项目被拆分到其他目录时才需要保留。
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## 1. Cursor
|
|
18
|
+
|
|
19
|
+
写入 `.cursor/mcp.json`(文件不存在则新建):
|
|
20
|
+
|
|
21
|
+
```json
|
|
22
|
+
{
|
|
23
|
+
"mcpServers": {
|
|
24
|
+
"carlos-flow": {
|
|
25
|
+
"command": "node",
|
|
26
|
+
"args": ["<INSTALL_PATH>/bridge/mcp-bridge.js"],
|
|
27
|
+
"env": {
|
|
28
|
+
"CARLOS_BRIDGE_TOKEN": "YOUR_TOKEN_HERE"
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## 2. VS Code
|
|
36
|
+
|
|
37
|
+
写入 `.vscode/settings.json`:
|
|
38
|
+
|
|
39
|
+
```json
|
|
40
|
+
{
|
|
41
|
+
"mcp.servers": {
|
|
42
|
+
"carlos-flow": {
|
|
43
|
+
"command": "node",
|
|
44
|
+
"args": ["<INSTALL_PATH>/bridge/mcp-bridge.js"],
|
|
45
|
+
"env": {
|
|
46
|
+
"CARLOS_BRIDGE_TOKEN": "YOUR_TOKEN_HERE"
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## 3. Windsurf
|
|
54
|
+
|
|
55
|
+
写入 `~/.windsurf/mcp.json`:
|
|
56
|
+
|
|
57
|
+
```json
|
|
58
|
+
{
|
|
59
|
+
"mcpServers": {
|
|
60
|
+
"carlos-flow": {
|
|
61
|
+
"command": "node",
|
|
62
|
+
"args": ["<INSTALL_PATH>/bridge/mcp-bridge.js"],
|
|
63
|
+
"env": {
|
|
64
|
+
"CARLOS_BRIDGE_TOKEN": "YOUR_TOKEN_HERE"
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## 配置自检
|
|
74
|
+
|
|
75
|
+
配置完成后,可在项目目录运行:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
./check-all.sh
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
它会做两件事:
|
|
82
|
+
|
|
83
|
+
1. `node --check` 校验 `bridge/mcp-bridge.js`、`src/index.js`、`smoke-test.js` 语法;
|
|
84
|
+
2. **真 RPC 往返冒烟测试**:真起一个 Bridge,发 `initialize` + `tools/list`,
|
|
85
|
+
断言能拿回全部 **19 个工具**。这排除了「进程起来了但转发断了」的假阳性。
|
|
86
|
+
|
|
87
|
+
预期输出:
|
|
88
|
+
|
|
89
|
+
```
|
|
90
|
+
✅ initialize 握手成功
|
|
91
|
+
>>> RPC 往返总耗时:360.98ms
|
|
92
|
+
>>> 发现工具数:19
|
|
93
|
+
🎉 深度兼容性验证通过(真 RPC 往返拿到 19 个工具)
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## 常见问题
|
|
97
|
+
|
|
98
|
+
| 现象 | 原因 | 处理 |
|
|
99
|
+
| :--- | :--- | :--- |
|
|
100
|
+
| Bridge 启动即退出,日志提示 `CARLOS_BRIDGE_TOKEN 未设置` | 客户端配置里没传 Token | 按上面的 `env` 补上 |
|
|
101
|
+
| 日志提示 `MCP server 子进程启动失败` | 项目目录不完整,或 `src/index.js` 不在 Bridge 同级父目录 | 确认 `<INSTALL_PATH>/src/index.js` 存在;必要时设 `CARLOS_FLOW_MCP_ROOT` |
|
|
102
|
+
| 连上了但工具列表为空 | 客户端没带 `_token` | 检查客户端是否按 MCP 规范在请求里传 Token |
|
|
103
|
+
| Windows 上 Bridge 重启时弹黑框 | 已修复 | 升级到 **v2.11.2 及以上**(`windowsHide: true`) |
|
package/RELEASE_NOTES.md
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Carlos v2.11.2 发布说明
|
|
2
|
+
|
|
3
|
+
## 🪟 Windows 修复:Bridge 重启弹黑控制台窗口
|
|
4
|
+
* **已修复**:MCP server 子进程改用 `windowsHide: true` 启动,Windows 下不再弹出黑色控制台窗口。
|
|
5
|
+
* 依据:诊断文档《carlos-flow-windows-blackwindow-fix.md》——原实现缺失 Windows 进程隐藏参数。
|
|
6
|
+
|
|
7
|
+
## 🔧 兼容性修复:Bridge 转发通路与路径自探测
|
|
8
|
+
* **已修复**:Bridge 恢复完整的 JSON-RPC 转发通路(TCP 连接 → 子进程 stdin → 按 reqId 回包)。
|
|
9
|
+
此前一版误将 Bridge 精简为「只 spawn、不转发」,导致平台侧 `tools/list` 拿不到任何工具。
|
|
10
|
+
* **新增**:路径自探测。Bridge 依据自身文件位置自动定位 `../src/index.js`,
|
|
11
|
+
不再强制依赖 `CARLOS_FLOW_MCP_ROOT` 绝对路径;该环境变量仍保留为可选覆盖,保持向后兼容。
|
|
12
|
+
* **新增**:`/health` 返回解析后的真实项目根目录,供客户端做 Bridge 身份比对,避免重复拉起。
|
|
13
|
+
|
|
14
|
+
## 🔬 验证:真 RPC 往返冒烟测试
|
|
15
|
+
* `smoke-test.js` 重写为**真协议验证**:起真实 Bridge → 发 `initialize` → 发 `tools/list` →
|
|
16
|
+
断言拿回全部 **19 个工具**。此前版本只看一行启动日志,属于假阳性。
|
|
17
|
+
* `check-all.sh` 升级为 Gatekeeper 统一入口:语法校验 + 冒烟测试一体,退出码非 0 即阻断提交。
|
|
18
|
+
|
|
19
|
+
## 📖 文档
|
|
20
|
+
* 新增 `INSTALL.md`:Cursor / VS Code / Windsurf 三平台接入步骤、配置自检与常见问题对照表。
|
|
21
|
+
* 模板文件(`templates/`)去掉了强制的 `CARLOS_FLOW_MCP_ROOT` 绝对路径。
|
|
22
|
+
|
|
23
|
+
## ⚙️ CI
|
|
24
|
+
* release workflow 的发布闸保持不变:仅当 tag 版本**高于** npm 已发布最新版时才 `npm publish`。
|
|
25
|
+
* 新增约束:tag 版本必须与 `package.json` 的 `version` 一致,否则发布中止。
|
|
26
|
+
|
|
27
|
+
## 📝 版本信息
|
|
28
|
+
* 版本号:**v2.11.2**
|
|
29
|
+
* 上一版:v2.11.1(Bridge 转发通路存在缺陷,且 tag 与 package.json 版本不一致导致发布流程中止,未进入 npm)
|
|
30
|
+
* npm 上当前最新版仍为 2.11.0,本次发布后升级为 2.11.2
|
package/TRIGGER_GUIDE.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Carlos Flow 智能触发引擎使用指南
|
|
2
2
|
|
|
3
|
-
> **版本**: v2.11.
|
|
3
|
+
> **版本**: v2.11.2
|
|
4
4
|
> **适用**:`carlos-flow` 单包架构(2.6.0+)
|
|
5
5
|
> **代码位置**:`src/trigger.js`(零外部依赖的纯 JavaScript 实现)
|
|
6
6
|
|
|
@@ -779,5 +779,5 @@ MIT License
|
|
|
779
779
|
|
|
780
780
|
---
|
|
781
781
|
|
|
782
|
-
**版本**: v2.11.
|
|
782
|
+
**版本**: v2.11.2
|
|
783
783
|
**更新日期**: 2026-11-12
|
package/bridge/mcp-bridge.js
CHANGED
|
@@ -6,10 +6,19 @@
|
|
|
6
6
|
import { spawn } from "node:child_process";
|
|
7
7
|
import { createServer } from "node:net";
|
|
8
8
|
import { createHash } from "node:crypto";
|
|
9
|
+
import { fileURLToPath } from "node:url";
|
|
10
|
+
import path from "node:path";
|
|
9
11
|
|
|
12
|
+
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
10
13
|
const PORT = parseInt(process.argv[2] || process.env.BRIDGE_PORT || "19099", 10);
|
|
11
14
|
const TOKEN = process.env.CARLOS_BRIDGE_TOKEN;
|
|
12
|
-
|
|
15
|
+
// 路径自探测:环境变量优先(向后兼容),否则按 bridge/ 的位置自动定位项目根目录。
|
|
16
|
+
// 这样在 Cursor / VS Code / Windsurf 里只需填 bridge 脚本路径,无需再手写 ROOT 绝对路径。
|
|
17
|
+
const PROJECT_ROOT = path.resolve(__dirname, "..");
|
|
18
|
+
const MCP_ROOT = process.env.CARLOS_FLOW_MCP_ROOT
|
|
19
|
+
? path.resolve(process.env.CARLOS_FLOW_MCP_ROOT)
|
|
20
|
+
: PROJECT_ROOT;
|
|
21
|
+
const MCP_SERVER = path.resolve(MCP_ROOT, "src/index.js");
|
|
13
22
|
const MAX_REQUEST_SIZE = 1024 * 1024; // 1MB
|
|
14
23
|
const RATE_LIMIT = 10; // 每秒最多请求数
|
|
15
24
|
// 请求超时:必须大于服务端的最长单次执行时间。
|
|
@@ -26,9 +35,11 @@ if (!TOKEN) {
|
|
|
26
35
|
}
|
|
27
36
|
|
|
28
37
|
// 启动 MCP server 子进程
|
|
38
|
+
// windowsHide: true —— Windows 下隐藏子进程控制台窗口,避免 Bridge 重启时弹黑框。
|
|
29
39
|
const child = spawn(process.execPath, [MCP_SERVER], {
|
|
30
40
|
stdio: ["pipe", "pipe", "pipe"],
|
|
31
41
|
env: { ...process.env },
|
|
42
|
+
windowsHide: true,
|
|
32
43
|
});
|
|
33
44
|
|
|
34
45
|
let childStdout = "";
|
|
@@ -61,7 +72,12 @@ child.stderr.on("data", (data) => {
|
|
|
61
72
|
});
|
|
62
73
|
|
|
63
74
|
child.on("error", (e) => {
|
|
64
|
-
process.stderr.write("[
|
|
75
|
+
process.stderr.write("[Carlos-Diagnosis] ❌ MCP server 子进程启动失败: " + e.message + "\n");
|
|
76
|
+
process.stderr.write(
|
|
77
|
+
"[Carlos-Suggestion] 💡 请确认 Node.js 可用(node -v),且 " +
|
|
78
|
+
MCP_SERVER +
|
|
79
|
+
" 存在;若路径被移动过,可设置环境变量 CARLOS_FLOW_MCP_ROOT 指向项目根目录。\n",
|
|
80
|
+
);
|
|
65
81
|
});
|
|
66
82
|
|
|
67
83
|
child.on("exit", (code) => {
|
|
@@ -124,7 +140,7 @@ const server = createServer((socket) => {
|
|
|
124
140
|
// 现在回传 root / flow_home / pid,客户端逐一比对,不符就当“未运行”。
|
|
125
141
|
const health = {
|
|
126
142
|
status: "ok",
|
|
127
|
-
root:
|
|
143
|
+
root: MCP_ROOT,
|
|
128
144
|
flow_home: process.env.CARLOS_FLOW_HOME || "",
|
|
129
145
|
pid: process.pid,
|
|
130
146
|
port: PORT,
|
package/check-all.sh
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
#!/bin/bash
|
|
2
|
+
# Gatekeeper:提交前强制校验(语法 + 真 RPC 往返冒烟测试)
|
|
3
|
+
# 用法:./check-all.sh
|
|
4
|
+
set -u
|
|
5
|
+
|
|
6
|
+
cd "$(dirname "$0")" || exit 1
|
|
7
|
+
|
|
8
|
+
# 冒烟测试需要一个 Token;未设置时用临时值,避免因本地缺环境变量而误报失败。
|
|
9
|
+
export CARLOS_BRIDGE_TOKEN="${CARLOS_BRIDGE_TOKEN:-gatekeeper-local-token}"
|
|
10
|
+
export BRIDGE_PORT="${BRIDGE_PORT:-19099}"
|
|
11
|
+
|
|
12
|
+
echo "=== Gatekeeper: 语法校验 ==="
|
|
13
|
+
node --check bridge/mcp-bridge.js && echo "✅ bridge/mcp-bridge.js 语法通过"
|
|
14
|
+
node --check src/index.js && echo "✅ src/index.js 语法通过"
|
|
15
|
+
node --check smoke-test.js && echo "✅ smoke-test.js 语法通过"
|
|
16
|
+
|
|
17
|
+
echo ""
|
|
18
|
+
echo "=== Gatekeeper: 真 RPC 往返冒烟测试 ==="
|
|
19
|
+
node smoke-test.js
|
|
20
|
+
RESULT=$?
|
|
21
|
+
if [ $RESULT -eq 0 ]; then
|
|
22
|
+
echo "✅ Bridge 启动正常,深度兼容性验证通过"
|
|
23
|
+
else
|
|
24
|
+
echo "❌ 冒烟测试失败,请检查 mcp-bridge.js 的启动/转发逻辑"
|
|
25
|
+
exit 1
|
|
26
|
+
fi
|
|
27
|
+
|
|
28
|
+
echo ""
|
|
29
|
+
echo "=== Gatekeeper: 全部校验完成 ==="
|
package/ghost.json
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
"name": "Carlos 工作流",
|
|
6
6
|
"description": "机械门禁 MCP:留痕/派发/裁定/审计/快照/免检/还原。自动管理 Bridge 后台常驻,首次调用 ~3-5s,后续 ~1s。",
|
|
7
7
|
"whenToUse": "需要走 Carlos 工作流门禁时使用:留痕/派发/裁定/审计/快照/免检/还原",
|
|
8
|
-
"version": "2.11.
|
|
8
|
+
"version": "2.11.2",
|
|
9
9
|
"kind": "mcp",
|
|
10
10
|
"entry": "client/carlos.js",
|
|
11
11
|
"command": "门禁",
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "carlos-flow",
|
|
3
|
-
"version": "2.11.
|
|
3
|
+
"version": "2.11.2",
|
|
4
4
|
"description": "Carlos 工作流 — AI 编码 Agent 的机械门禁。留痕/派发/验证/裁定/审计/还原,约束写在代码里而非提示词里。单一包支持 Cindy/OpenCode/Cursor/Cline/VS Code/Claude Desktop。",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "src/index.js",
|
|
@@ -23,7 +23,7 @@
|
|
|
23
23
|
"test:trigger": "node test/trigger-e2e.mjs",
|
|
24
24
|
"test:concurrency": "node test/concurrency-e2e.mjs",
|
|
25
25
|
"test:acceptance": "node test/e2e-acceptance.mjs",
|
|
26
|
-
"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",
|
|
26
|
+
"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",
|
|
27
27
|
"test:mutation": "node scripts/mutation-check.mjs",
|
|
28
28
|
"sync:readme": "node scripts/sync-readme.mjs",
|
|
29
29
|
"check:readme": "node scripts/sync-readme.mjs --check",
|
|
@@ -49,7 +49,10 @@
|
|
|
49
49
|
"check:no-dead-handler": "node scripts/check-no-dead-handler.mjs",
|
|
50
50
|
"test:scope": "node test/scope-enforcement.mjs",
|
|
51
51
|
"test:audit": "node test/audit-chain.mjs",
|
|
52
|
-
"test:bridge": "node test/bridge-identity.mjs"
|
|
52
|
+
"test:bridge": "node test/bridge-identity.mjs",
|
|
53
|
+
"sync:version": "node scripts/sync-version.mjs",
|
|
54
|
+
"check:version": "node scripts/check-repo-parity.mjs",
|
|
55
|
+
"test:gate": "node test/publish-gate.test.mjs"
|
|
53
56
|
},
|
|
54
57
|
"keywords": [
|
|
55
58
|
"carlos",
|
|
@@ -97,6 +100,10 @@
|
|
|
97
100
|
"MIGRATION.md",
|
|
98
101
|
"CHANGELOG.md",
|
|
99
102
|
"LICENSE",
|
|
100
|
-
"AGENTS.md"
|
|
103
|
+
"AGENTS.md",
|
|
104
|
+
"INSTALL.md",
|
|
105
|
+
"RELEASE_NOTES.md",
|
|
106
|
+
"check-all.sh",
|
|
107
|
+
"smoke-test.js"
|
|
101
108
|
]
|
|
102
109
|
}
|
|
@@ -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,126 @@
|
|
|
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
|
+
|
|
14
|
+
import { readFileSync, writeFileSync } from "node:fs";
|
|
15
|
+
import { join, dirname } from "node:path";
|
|
16
|
+
import { fileURLToPath } from "node:url";
|
|
17
|
+
|
|
18
|
+
const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
|
|
19
|
+
|
|
20
|
+
function readText(rel) {
|
|
21
|
+
try {
|
|
22
|
+
return readFileSync(join(ROOT, rel), "utf8");
|
|
23
|
+
} catch {
|
|
24
|
+
return "";
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
function writeText(rel, text) {
|
|
29
|
+
writeFileSync(join(ROOT, rel), text, "utf8");
|
|
30
|
+
console.log(` ✏️ ${rel}`);
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
function readJson(rel) {
|
|
34
|
+
try {
|
|
35
|
+
return JSON.parse(readText(rel));
|
|
36
|
+
} catch {
|
|
37
|
+
return null;
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
const argv = process.argv.slice(2);
|
|
42
|
+
const changelogTitle = argv.includes("--changelog")
|
|
43
|
+
? argv[argv.indexOf("--changelog") + 1]
|
|
44
|
+
: null;
|
|
45
|
+
const dateArg = argv.includes("--date")
|
|
46
|
+
? argv[argv.indexOf("--date") + 1]
|
|
47
|
+
: null;
|
|
48
|
+
|
|
49
|
+
const pkg = readJson("package.json");
|
|
50
|
+
if (!pkg || !pkg.version) {
|
|
51
|
+
console.error("❌ 读不到 package.json 的 version");
|
|
52
|
+
process.exit(1);
|
|
53
|
+
}
|
|
54
|
+
const ver = pkg.version;
|
|
55
|
+
console.log(`▶ 目标版本:${ver}\n`);
|
|
56
|
+
|
|
57
|
+
// ---- 1. package-lock.json ----
|
|
58
|
+
const lock = readJson("package-lock.json");
|
|
59
|
+
if (lock) {
|
|
60
|
+
let changed = false;
|
|
61
|
+
if (lock.version !== ver) {
|
|
62
|
+
lock.version = ver;
|
|
63
|
+
changed = true;
|
|
64
|
+
}
|
|
65
|
+
if (lock.packages && lock.packages[""] && lock.packages[""].version !== ver) {
|
|
66
|
+
lock.packages[""].version = ver;
|
|
67
|
+
changed = true;
|
|
68
|
+
}
|
|
69
|
+
if (changed) {
|
|
70
|
+
writeText("package-lock.json", JSON.stringify(lock, null, 2) + "\n");
|
|
71
|
+
} else {
|
|
72
|
+
console.log(" ✅ package-lock.json 已是 " + ver);
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
// ---- 2. ghost.json ----
|
|
77
|
+
const ghost = readJson("ghost.json");
|
|
78
|
+
if (ghost) {
|
|
79
|
+
if (ghost.version !== ver) {
|
|
80
|
+
ghost.version = ver;
|
|
81
|
+
writeText("ghost.json", JSON.stringify(ghost, null, 2) + "\n");
|
|
82
|
+
} else {
|
|
83
|
+
console.log(" ✅ ghost.json 已是 " + ver);
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
// ---- 3. TRIGGER_GUIDE.md(两处「版本」行)----
|
|
88
|
+
let guide = readText("TRIGGER_GUIDE.md");
|
|
89
|
+
if (guide) {
|
|
90
|
+
const before = guide;
|
|
91
|
+
guide = guide.replace(/v\d+\.\d+\.\d+/g, "v" + ver);
|
|
92
|
+
if (guide !== before) {
|
|
93
|
+
writeText("TRIGGER_GUIDE.md", guide);
|
|
94
|
+
} else {
|
|
95
|
+
console.log(" ✅ TRIGGER_GUIDE.md 已是 " + ver);
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
// ---- 4. CHANGELOG.md ----
|
|
100
|
+
let changelog = readText("CHANGELOG.md");
|
|
101
|
+
if (changelog) {
|
|
102
|
+
const topMatch = changelog.match(/^## \[(\d+\.\d+\.\d+)\]/m);
|
|
103
|
+
const topVer = topMatch ? topMatch[1] : null;
|
|
104
|
+
|
|
105
|
+
if (topVer === ver) {
|
|
106
|
+
console.log(" ✅ CHANGELOG.md 顶部已是 " + ver);
|
|
107
|
+
} else if (changelogTitle) {
|
|
108
|
+
const d = dateArg || new Date().toISOString().slice(0, 10);
|
|
109
|
+
const entry = `## [${ver}] - ${d} — ${changelogTitle}\n\n### ✨ 新增 | Added\n\n- (待补充)\n\n`;
|
|
110
|
+
// 插到「---」分隔线之后、首个版本段落之前
|
|
111
|
+
const sepIdx = changelog.indexOf("\n---\n");
|
|
112
|
+
const insertAt = sepIdx === -1 ? 0 : sepIdx + "\n---\n\n".length;
|
|
113
|
+
changelog =
|
|
114
|
+
changelog.slice(0, insertAt) + entry + changelog.slice(insertAt);
|
|
115
|
+
writeText("CHANGELOG.md", changelog);
|
|
116
|
+
} else {
|
|
117
|
+
console.error(
|
|
118
|
+
`❌ CHANGELOG.md 顶部是 ${topVer || "(无)"},与 ${ver} 不一致。\n` +
|
|
119
|
+
` 请先写好 ${ver} 的变更条目,再运行:\n` +
|
|
120
|
+
` node scripts/sync-version.mjs --changelog "本版标题"`,
|
|
121
|
+
);
|
|
122
|
+
process.exit(1);
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
console.log("\n✅ 版本号已全部对齐到 " + ver);
|
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
|
+
}
|