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
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,98 @@
|
|
|
1
|
+
## [2.11.3] - 2026-11-13 — 多副本治理收敛 + 推 tag 前置门禁 + A1 验证绑代码状态
|
|
2
|
+
|
|
3
|
+
### 🐛 修复 | Fixed
|
|
4
|
+
|
|
5
|
+
- **A1:验证结果绑定代码状态(指纹 + 四态)** —— 研究产物《A1-A2-A3 实施前核验清单》确认的绕过路径:
|
|
6
|
+
`flow_run_verify` 跑通 → executor 继续改代码(甚至改坏)→ `flow_verdict(PASS)` 三道判断全过 → **直接放行**。
|
|
7
|
+
现在 `last_verify` 记录工作区指纹(HEAD + `git diff HEAD` + 全部未跟踪文件),
|
|
8
|
+
PASS 闸门新增第四道判断:指纹不一致即拒绝,错误含「验证结果已过期(STALE)」。
|
|
9
|
+
`flow_status` 新增 `verify_state` 四态(not_run / fail / stale / pass),
|
|
10
|
+
`verify_passed` **仍保持 boolean** 不破坏下游。
|
|
11
|
+
- **负对照路径同样绑定指纹**:`flow_falsify` 写 `last_verify` 时此前**不记指纹**,
|
|
12
|
+
于是「先负对照、再改代码、再记 PASS」这条路径会绕过 STALE 闸门 —— 一并修复。
|
|
13
|
+
- **`init` 在 Windows 上产出非法 JSON**(影响所有 Windows 用户的安装):
|
|
14
|
+
旧写法把 Windows 路径的**原始反斜杠**塞进 JSON 模板,
|
|
15
|
+
产出含 `d` `
|
|
16
|
+
` `` 等非法转义序列的配置文件,解析即报
|
|
17
|
+
「Bad escaped character」,表现为「安装成功但插件不出现」。
|
|
18
|
+
现在 JSON 目标用 JSON 转义、YAML 目标(.mcprc)用正斜杠路径。
|
|
19
|
+
|
|
20
|
+
### 🔒 变更 | Changed
|
|
21
|
+
|
|
22
|
+
- **多副本治理收敛**(本机 5 套副本 → 2 套):
|
|
23
|
+
- 归档 `carlos-flow-cindy` / `carlos-flow-opencode` / `_carlos-flow-remote` 等 7 个目录
|
|
24
|
+
(三个 git 副本的**独有提交实测均为 0**,无内容丢失);保留发布线与线上运行副本两份。
|
|
25
|
+
- 线上运行副本(`D:cindycarlos-flow-mcp`)从 2.8.0 **同步到最新发布版**,
|
|
26
|
+
此前它的 bridge 无 `windowsHide`、无路径自探测 —— 也就是说仓库里修好的黑窗问题**在用户机器上根本没生效**。
|
|
27
|
+
- Cindy **已安装插件**(旧 v1.0.5 架构)两处 spawn 补上 `windowsHide: true` ——
|
|
28
|
+
这才是用户实际看到的黑色控制台窗口的来源。
|
|
29
|
+
- npm 全局安装同步到最新发布版。
|
|
30
|
+
|
|
31
|
+
### 🧪 新增门禁 | Gates
|
|
32
|
+
|
|
33
|
+
- **推 tag 前置钩子**(`scripts/install-hooks.mjs`):只拦截 **tag 推送**,依次校验
|
|
34
|
+
版本号一致性(`sync-version --check`)/ `check-all.sh` 真 RPC 往返 / tag 重名。
|
|
35
|
+
背景:推 `v*` tag **等于**触发 npm 自动发布,此前 v2.11.1 那样没跑过验证的提交被打 tag 推上远端。
|
|
36
|
+
- **`check:templates` 模板渲染门禁**:用真实 Windows 路径渲染全部模板,
|
|
37
|
+
断言产物可解析且路径无损,并校验 `client/carlos.js` 的转义写法与门禁**同源**。
|
|
38
|
+
- **`test:stale` A1 验证测试**:把研究文档里 4 段需要人手敲的命令(V1.1~V1.4)变成 14 条自动化断言。
|
|
39
|
+
|
|
40
|
+
### ✨ 新增 | Added
|
|
41
|
+
|
|
42
|
+
- **`sync-version.mjs --check` 只读模式**:有偏差退出码 1 且不写文件,供推 tag 钩子做精确判定。
|
|
43
|
+
- **`sync-version.mjs` 批量对齐版本号**:以 package.json 为唯一真源,同步 package-lock.json / ghost.json / TRIGGER_GUIDE.md / CHANGELOG.md。
|
|
44
|
+
|
|
45
|
+
## [2.11.2] - 2026-11-13 — 修复 Bridge 转发通路与 Windows 黑窗,新增路径自探测
|
|
46
|
+
|
|
47
|
+
### ✨ 新增 | Added
|
|
48
|
+
|
|
49
|
+
- **路径自探测**(`bridge/mcp-bridge.js`):Bridge 依据自身文件位置自动定位 `../src/index.js`,
|
|
50
|
+
不再强制依赖 `CARLOS_FLOW_MCP_ROOT` 绝对路径;该环境变量保留为可选覆盖,向后兼容。
|
|
51
|
+
接入方只需填 bridge 脚本的路径,Cursor / VS Code / Windsurf 三端通用。
|
|
52
|
+
- **`/health` 返回真实项目根目录**(解析后的绝对路径),供客户端做 Bridge 身份比对,
|
|
53
|
+
避免端口上跑着「别的 ROOT 的 bridge」时被静默复用。
|
|
54
|
+
- **`INSTALL.md`**:Cursor / VS Code / Windsurf 三平台接入步骤、配置自检与常见问题对照表。
|
|
55
|
+
- **`scripts/sync-version.mjs`**:以 `package.json` 为唯一真源,批量对齐
|
|
56
|
+
`package-lock.json` / `ghost.json` / `TRIGGER_GUIDE.md` / `CHANGELOG.md` 的版本号,
|
|
57
|
+
消除「版本散落四处、人工改漏即发布中止」的根因。
|
|
58
|
+
|
|
59
|
+
### 🐛 修复 | Fixed
|
|
60
|
+
|
|
61
|
+
- **Bridge 转发通路缺失**:上一版把 Bridge 精简为「只 spawn 子进程、不做转发」,
|
|
62
|
+
导致平台侧发来的 `tools/list` 永远不会到达 MCP server —— 19 个工具一个都发现不了。
|
|
63
|
+
现在恢复完整的 TCP → 子进程 stdin → 按 reqId 回包链路。
|
|
64
|
+
- **Windows 黑控制台窗口**:MCP server 子进程改用 `windowsHide: true` 启动,
|
|
65
|
+
Bridge 重启时不再弹出黑色控制台窗口。
|
|
66
|
+
- **冒烟测试假阳性**:`smoke-test.js` 此前只检查一行启动日志,进程起得来就算「通过」,
|
|
67
|
+
转发断了也测不出来。现在重写为**真 RPC 往返**:起真实 Bridge → 发 `initialize` →
|
|
68
|
+
发 `tools/list` → 断言拿回全部 19 个工具。
|
|
69
|
+
- **子进程启动失败的报错可读性**:改为输出 `[Carlos-Diagnosis]` 现象 +
|
|
70
|
+
`[Carlos-Suggestion]` 修复建议,不再只丢一句 Node 原始异常。
|
|
71
|
+
|
|
72
|
+
### 🔧 发布基础设施 | Release Infrastructure
|
|
73
|
+
|
|
74
|
+
- **修发布闸 semver 方向写反的真实 bug**:旧实现里 `process.exit(semver(a,b)<=0?1:0)` 的退出码语义
|
|
75
|
+
与 shell 的 `elif` 判定相反 —— 结果「版本更高」被拦在 npm 之外、「版本更低」(补历史 tag)反而放行,
|
|
76
|
+
正好与发布闸的本意完全相反。判定逻辑抽到 `scripts/publish-gate.mjs`,
|
|
77
|
+
新增 `test/publish-gate.test.mjs` 锁住方向(10 条断言)。
|
|
78
|
+
- **修 CI 上 `check-all.sh` Permission denied**:脚本可执行位在 Windows 提交时丢失
|
|
79
|
+
(`core.fileMode` 不跟踪 exec bit),Ubuntu runner 直接 126 退出。
|
|
80
|
+
CI 改用 `bash ./check-all.sh`,并在 git index 层补上 `100755`。
|
|
81
|
+
|
|
82
|
+
### 🔒 变更 | Changed
|
|
83
|
+
|
|
84
|
+
- **`check-all.sh` 升级为 Gatekeeper 统一入口**:语法校验 + 真 RPC 冒烟测试一体,
|
|
85
|
+
退出码非 0 即阻断提交;未设置 `CARLOS_BRIDGE_TOKEN` 时自动用临时值,避免误报失败。
|
|
86
|
+
- **`package.json` 的 `files` 补齐** `INSTALL.md` / `RELEASE_NOTES.md` /
|
|
87
|
+
`check-all.sh` / `smoke-test.js`,使安装指引与自检脚本随包分发。
|
|
88
|
+
- **移除误提交的 `bridge/mcp-bridge.js.bak`**(内容是早期被截断的残缺版本,会误导后来人)。
|
|
89
|
+
|
|
90
|
+
### 🔬 验证 | Verification
|
|
91
|
+
|
|
92
|
+
- `./check-all.sh` 通过:三个文件语法校验通过,真 RPC 往返耗时约 330ms,拿回 19 个工具。
|
|
93
|
+
- 项目自带冒烟测试 `npm test` 通过(SMOKE_OK)。
|
|
94
|
+
- 单包一致性检查 `node scripts/check-repo-parity.mjs` 通过。
|
|
95
|
+
|
|
1
96
|
# 变更日志 | Changelog
|
|
2
97
|
|
|
3
98
|
> 格式遵循 [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.3
|
|
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.3
|
|
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/client/carlos.js
CHANGED
|
@@ -417,14 +417,28 @@ async function runInit(target) {
|
|
|
417
417
|
console.log(`✅ 触发器配置已写入: ${tcPath}`);
|
|
418
418
|
}
|
|
419
419
|
|
|
420
|
+
// --- __ROOT__ 渲染:必须按目标格式转义 ---
|
|
421
|
+
//
|
|
422
|
+
// 背景(2026-11-13 实测):旧实现直接 `.replace(/__ROOT__/g, ROOT_ABS)`,
|
|
423
|
+
// 把 Windows 路径的**原始反斜杠**嵌进 JSON 模板,产出
|
|
424
|
+
// "D:\dev-env\node-v22.23.4-win-x64\node_modules\carlos-flow/bridge/mcp-bridge.js"
|
|
425
|
+
// 其中 `\d` `\n` `\v` 都是**非法 JSON 转义序列** —— 文件根本解析不了,
|
|
426
|
+
// 表现为「安装成功但插件不出现」,而且任何 JSON 解析器都报同一个位置。
|
|
427
|
+
//
|
|
428
|
+
// 两种目标格式要分别处理:
|
|
429
|
+
// - JSON(ghost.json / mcp.json / opencode.json):必须 JSON 转义(反斜杠 → \\)
|
|
430
|
+
// - YAML(.mcprc):Windows 路径一律用正斜杠(反斜杠在 YAML 双引号标量里同样非法)
|
|
431
|
+
const rootJson = JSON.stringify(ROOT_ABS).slice(1, -1);
|
|
432
|
+
const rootYaml = ROOT_ABS.replace(/\\/g, "/");
|
|
433
|
+
|
|
420
434
|
if (target === "cindy") {
|
|
421
435
|
// --- Cindy: 生成 ghost.json 到 ~/.cindy/ghosts/ ---
|
|
422
436
|
const ghostsDir = join(home, ".cindy", "ghosts");
|
|
423
437
|
mkdirSync(ghostsDir, { recursive: true });
|
|
424
438
|
const ghostPath = join(ghostsDir, "carlos-flow.json");
|
|
425
|
-
|
|
439
|
+
|
|
426
440
|
const ghostTemplate = readFileSync(resolve(ROOT_ABS, "ghost.json"), "utf8");
|
|
427
|
-
const ghostContent = ghostTemplate.replace(/__ROOT__/g,
|
|
441
|
+
const ghostContent = ghostTemplate.replace(/__ROOT__/g, rootJson);
|
|
428
442
|
writeFileSync(ghostPath, ghostContent, "utf8");
|
|
429
443
|
console.log(`✅ Cindy ghost 已写入: ${ghostPath}`);
|
|
430
444
|
console.log(` 重启 Cindy 后即可在侧栏看到 "Carlos 工作流" 插件`);
|
|
@@ -435,13 +449,13 @@ async function runInit(target) {
|
|
|
435
449
|
const pluginPath = join(pluginDir, "opencode.json");
|
|
436
450
|
|
|
437
451
|
const pluginTemplate = readFileSync(resolve(ROOT_ABS, "opencode.json.template"), "utf8");
|
|
438
|
-
const pluginContent = pluginTemplate.replace(/__ROOT__/g,
|
|
452
|
+
const pluginContent = pluginTemplate.replace(/__ROOT__/g, rootJson);
|
|
439
453
|
writeFileSync(pluginPath, pluginContent, "utf8");
|
|
440
454
|
console.log(`✅ OpenCode 插件配置已写入: ${pluginPath}`);
|
|
441
455
|
|
|
442
456
|
// 同时生成 .mcprc 到项目根目录(用户可手动复制)
|
|
443
457
|
const mcprcTemplate = readFileSync(resolve(ROOT_ABS, ".mcprc.template"), "utf8");
|
|
444
|
-
const mcprcContent = mcprcTemplate.replace(/__ROOT__/g,
|
|
458
|
+
const mcprcContent = mcprcTemplate.replace(/__ROOT__/g, rootYaml);
|
|
445
459
|
const mcprcPath = join(process.cwd(), ".mcprc");
|
|
446
460
|
writeFileSync(mcprcPath, mcprcContent, "utf8");
|
|
447
461
|
console.log(`✅ MCP 配置模板已写入: ${mcprcPath}`);
|
|
@@ -454,7 +468,7 @@ async function runInit(target) {
|
|
|
454
468
|
|
|
455
469
|
const templatePath = resolve(ROOT_ABS, "templates", target, "mcp.json");
|
|
456
470
|
const template = readFileSync(templatePath, "utf8");
|
|
457
|
-
const content = template.replace(/__ROOT__/g,
|
|
471
|
+
const content = template.replace(/__ROOT__/g, rootJson);
|
|
458
472
|
writeFileSync(configPath, content, "utf8");
|
|
459
473
|
console.log(`✅ ${target.charAt(0).toUpperCase() + target.slice(1)} 配置已写入: ${configPath}`);
|
|
460
474
|
} else if (target === "vscode") {
|
|
@@ -465,7 +479,7 @@ async function runInit(target) {
|
|
|
465
479
|
|
|
466
480
|
const templatePath = resolve(ROOT_ABS, "templates", "vscode", "mcp.json");
|
|
467
481
|
const template = readFileSync(templatePath, "utf8");
|
|
468
|
-
const content = template.replace(/__ROOT__/g,
|
|
482
|
+
const content = template.replace(/__ROOT__/g, rootJson);
|
|
469
483
|
writeFileSync(configPath, content, "utf8");
|
|
470
484
|
console.log(`✅ VS Code (Copilot) 配置已写入: ${configPath}`);
|
|
471
485
|
} else if (target === "claude") {
|
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.3",
|
|
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.3",
|
|
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 && npm run test:stale && npm run test:scope && npm run test:audit && npm run test:bridge",
|
|
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,14 @@
|
|
|
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",
|
|
56
|
+
"install:hooks": "node scripts/install-hooks.mjs",
|
|
57
|
+
"check:hooks": "node scripts/install-hooks.mjs --check",
|
|
58
|
+
"test:stale": "node test/verify-stale.test.mjs",
|
|
59
|
+
"check:templates": "node scripts/check-templates.mjs"
|
|
53
60
|
},
|
|
54
61
|
"keywords": [
|
|
55
62
|
"carlos",
|
|
@@ -97,6 +104,10 @@
|
|
|
97
104
|
"MIGRATION.md",
|
|
98
105
|
"CHANGELOG.md",
|
|
99
106
|
"LICENSE",
|
|
100
|
-
"AGENTS.md"
|
|
107
|
+
"AGENTS.md",
|
|
108
|
+
"INSTALL.md",
|
|
109
|
+
"RELEASE_NOTES.md",
|
|
110
|
+
"check-all.sh",
|
|
111
|
+
"smoke-test.js"
|
|
101
112
|
]
|
|
102
113
|
}
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
// 模板渲染合法性门禁
|
|
2
|
+
//
|
|
3
|
+
// 为什么需要(2026-11-13 实测事故):
|
|
4
|
+
// `carlos-flow init --target <platform>` 曾经用**裸字符串替换**把项目根路径塞进模板,
|
|
5
|
+
// 即不做任何转义地把路径原文替换进 JSON 字符串里。
|
|
6
|
+
// Windows 路径的原始反斜杠因此进了 JSON,产出形如
|
|
7
|
+
// "D:\dev-env\node-v22.23.4-win-x64\node_modules\carlos-flow/bridge/mcp-bridge.js"
|
|
8
|
+
// 其中 \d \n \v 都是**非法 JSON 转义序列** —— 配置文件根本解析不了,
|
|
9
|
+
// 表现为「安装成功但插件不出现」,而且任何解析器都报同一个位置。
|
|
10
|
+
// 现场文件 C:\Users\EDY\.cindy\ghosts\carlos-flow.json 就是这个状态。
|
|
11
|
+
// 正确写法见 client/carlos.js:JSON 目标用 JSON.stringify 转义,YAML 目标用正斜杠。
|
|
12
|
+
//
|
|
13
|
+
// 本门禁做的事:
|
|
14
|
+
// 用**真实的 Windows 路径**渲染全部模板,断言产物能被正确解析,
|
|
15
|
+
// 并且路径里的反斜杠没有丢失、没有变成非法转义。
|
|
16
|
+
//
|
|
17
|
+
// 运行:node scripts/check-templates.mjs
|
|
18
|
+
|
|
19
|
+
import { readFileSync } 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
|
+
let pass = 0;
|
|
26
|
+
let fail = 0;
|
|
27
|
+
|
|
28
|
+
function ok(msg) {
|
|
29
|
+
pass++;
|
|
30
|
+
console.log(" ✅ " + msg);
|
|
31
|
+
}
|
|
32
|
+
function bad(msg) {
|
|
33
|
+
fail++;
|
|
34
|
+
console.log(" ❌ " + msg);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
// 真实的 Windows 路径(含反斜杠、大写、子目录),用来复现事故现场
|
|
38
|
+
const WIN_ROOT = "D:\\dev-env\\node-v22.23.4-win-x64\\node_modules\\carlos-flow";
|
|
39
|
+
|
|
40
|
+
// 与 client/carlos.js 中的渲染逻辑保持一致(这是本门禁的关键:两处必须同源)
|
|
41
|
+
const rootJson = JSON.stringify(WIN_ROOT).slice(1, -1);
|
|
42
|
+
const rootYaml = WIN_ROOT.replace(/\\/g, "/");
|
|
43
|
+
|
|
44
|
+
console.log("▶ JSON 模板:Windows 路径渲染后必须可解析且路径无损");
|
|
45
|
+
|
|
46
|
+
const jsonTemplates = [
|
|
47
|
+
["ghost.json", (t) => t.replace(/__ROOT__/g, rootJson)],
|
|
48
|
+
["opencode.json.template", (t) => t.replace(/__ROOT__/g, rootJson)],
|
|
49
|
+
["templates/cursor/mcp.json", (t) => t.replace(/__ROOT__/g, rootJson)],
|
|
50
|
+
["templates/cline/mcp.json", (t) => t.replace(/__ROOT__/g, rootJson)],
|
|
51
|
+
["templates/vscode/mcp.json", (t) => t.replace(/__ROOT__/g, rootJson)],
|
|
52
|
+
["templates/claude/claude_desktop_config.json", (t) => t.replace(/__ROOT__/g, rootJson)],
|
|
53
|
+
];
|
|
54
|
+
|
|
55
|
+
for (const [rel, render] of jsonTemplates) {
|
|
56
|
+
let raw = "";
|
|
57
|
+
try {
|
|
58
|
+
raw = readFileSync(join(ROOT, rel), "utf8");
|
|
59
|
+
} catch {
|
|
60
|
+
bad(`${rel} 读不到`);
|
|
61
|
+
continue;
|
|
62
|
+
}
|
|
63
|
+
if (!raw.includes("__ROOT__")) {
|
|
64
|
+
bad(`${rel} 里没有 __ROOT__ 占位符 —— 渲染逻辑可能已失效,模板与代码脱节`);
|
|
65
|
+
continue;
|
|
66
|
+
}
|
|
67
|
+
const out = render(raw);
|
|
68
|
+
try {
|
|
69
|
+
const parsed = JSON.parse(out);
|
|
70
|
+
ok(`${rel} 渲染后可解析`);
|
|
71
|
+
// 路径无损检查:反斜杠必须完好,不能变成 \\ 之外的任何形态
|
|
72
|
+
const found = JSON.stringify(parsed).includes("dev-env");
|
|
73
|
+
if (!found) bad(`${rel} 渲染后路径内容丢失`);
|
|
74
|
+
} catch (e) {
|
|
75
|
+
bad(`${rel} 渲染后无法解析:${e.message}`);
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
console.log("▶ YAML 模板:.mcprc 必须用正斜杠(反斜杠在 YAML 双引号里同样非法)");
|
|
80
|
+
|
|
81
|
+
try {
|
|
82
|
+
const raw = readFileSync(join(ROOT, ".mcprc.template"), "utf8");
|
|
83
|
+
const out = raw.replace(/__ROOT__/g, rootYaml);
|
|
84
|
+
if (out.includes("\\\\")) {
|
|
85
|
+
bad(".mcprc.template 渲染后仍含双反斜杠 —— YAML 双引号标量里 \\d \\U 是非法转义");
|
|
86
|
+
} else if (out.includes(rootYaml)) {
|
|
87
|
+
ok(".mcprc.template 渲染后为正斜杠路径");
|
|
88
|
+
} else {
|
|
89
|
+
bad(".mcprc.template 渲染后未找到正斜杠路径");
|
|
90
|
+
}
|
|
91
|
+
} catch (e) {
|
|
92
|
+
bad(".mcprc.template 读不到:" + e.message);
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
console.log("▶ 反例确认:旧的裸替换写法必须确实产出非法 JSON");
|
|
96
|
+
|
|
97
|
+
{
|
|
98
|
+
const raw = readFileSync(join(ROOT, "ghost.json"), "utf8");
|
|
99
|
+
const oldOut = raw.replace(/__ROOT__/g, WIN_ROOT);
|
|
100
|
+
try {
|
|
101
|
+
JSON.parse(oldOut);
|
|
102
|
+
bad("旧的裸替换写法竟然能解析 —— 前提假设已变,门禁需重新评估");
|
|
103
|
+
} catch {
|
|
104
|
+
ok("旧的裸替换写法确实产出非法 JSON(本门禁守的正是这个)");
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
console.log("▶ 源码一致性:client/carlos.js 必须用同样的转义方式");
|
|
109
|
+
|
|
110
|
+
{
|
|
111
|
+
const src = readFileSync(join(ROOT, "client", "carlos.js"), "utf8");
|
|
112
|
+
const usesJsonEscape = /JSON\.stringify\(ROOT_ABS\)\.slice\(1,\s*-1\)/.test(src);
|
|
113
|
+
const usesYamlSlash = /ROOT_ABS\.replace\(\/\\\\\/g,\s*"\/"\)/.test(src);
|
|
114
|
+
if (usesJsonEscape) ok("client/carlos.js 使用 JSON 转义渲染 ROOT");
|
|
115
|
+
else bad("client/carlos.js 未使用 JSON 转义渲染 ROOT —— 与本门禁不同源");
|
|
116
|
+
|
|
117
|
+
if (usesYamlSlash) ok("client/carlos.js 对 YAML 目标使用正斜杠");
|
|
118
|
+
else bad("client/carlos.js 未对 YAML 目标使用正斜杠 —— 与本门禁不同源");
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
console.log("");
|
|
122
|
+
if (fail) {
|
|
123
|
+
console.log(`❌ 模板渲染门禁失败:${pass} 通过 / ${fail} 失败`);
|
|
124
|
+
process.exit(1);
|
|
125
|
+
}
|
|
126
|
+
console.log(`✅ 模板渲染门禁全部通过(${pass} 条)`);
|