carlos-flow 2.13.0 → 2.14.1
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/AGENTS.md +27 -2
- package/CHANGELOG.md +26 -0
- package/README.en.md +40 -2
- package/README.md +39 -3
- package/README.zh.md +39 -3
- package/TRIGGER_GUIDE.md +3 -3
- package/bridge/mcp-bridge.js +106 -6
- package/client/carlos.js +187 -4
- package/ghost.json +19 -559
- package/main.js +267 -0
- package/package.json +12 -7
- package/scripts/check-stubs.mjs +1 -1
- package/scripts/check-templates.mjs +42 -3
- package/scripts/full-audit.mjs +66 -6
- package/scripts/lang-audit.mjs +7 -1
- package/scripts/mutation-check.mjs +74 -7
- package/src/dispatch.js +204 -17
- package/src/index.js +208 -74
- package/src/mcp-stdio.mjs +139 -0
- package/src/protocol.js +182 -1
- package/src/state.js +36 -4
package/AGENTS.md
CHANGED
|
@@ -13,11 +13,16 @@
|
|
|
13
13
|
| `src/index.js` 的参数校验 | `scripts/check-params.mjs` 的判定口径 | 工具的 `inputSchema` |
|
|
14
14
|
| `src/state.js` 的状态字段 | `src/state.js` 的 `defaultState()` + `schemaVersion` | 迁移函数 `migrate()` |
|
|
15
15
|
| `src/state.js` 的审计链 | `docs/AUDIT_REVIEW.md` 的威胁模型 | `test/audit-chain.mjs` |
|
|
16
|
+
| `src/state.js` 的 `withStateLock` | `docs/TOOL_CONTRACTS.md` §4.5(排他/回收/退避口径) | `test/state-lock.mjs`、`test/concurrency-e2e.mjs` |
|
|
17
|
+
| `src/protocol.js` 的敏感名单 | `docs/TOOL_CONTRACTS.md` §4.4(只能追加,不许放宽) | `test/sensitive-config.mjs` |
|
|
18
|
+
| `src/dispatch.js` 的负对照还原 | `docs/TOOL_CONTRACTS.md` 的 `flow_falsify` 关键约束 | `test/falsify-restore.mjs` |
|
|
16
19
|
| `src/dispatch.js` 的 scope 判定 | `test/scope-enforcement.mjs` 的用例 | `README.md` 的能力矩阵 |
|
|
17
20
|
| 门禁逻辑(claim / dispatch / verdict) | `test/e2e-carlos.mjs` 的第 15~26 组用例 | 变异体 M1~M6 |
|
|
18
21
|
| `src/trigger.js` 触发引擎 | `TRIGGER_GUIDE.md` + `test/trigger-e2e.mjs` | 触发器配置模板 |
|
|
19
22
|
| 对外工具描述 / README | `scripts/check-claims.mjs`(承诺兑现度门禁) | `npm run check:claims` |
|
|
20
23
|
| `bridge/` 或 `client/` | `test/bridge-identity.mjs`(身份隔离) | `npm run test:bridge` |
|
|
24
|
+
| `ghost.json` 的工具清单 / `main.js` | `docs/TOOL_CONTRACTS.md` §1.3(两段式目录) | `test/cindy-dispatch.mjs`、`npm run check:full` |
|
|
25
|
+
| `src/mcp-stdio.mjs`(协议层) | `docs/TOOL_CONTRACTS.md` §1.3 + MCP stdio 规范 | `npm run test:mcp` |
|
|
21
26
|
| CI / 发布流程 | `.github/workflows/` | `npm run check:full` |
|
|
22
27
|
|
|
23
28
|
---
|
|
@@ -41,11 +46,26 @@
|
|
|
41
46
|
4. **激活占位卡未补齐时不得派发 / 不得裁定**
|
|
42
47
|
- `activation_pending` 非空 → `flow_claim` / `flow_dispatch` / `flow_verdict` 全部拒绝。
|
|
43
48
|
|
|
49
|
+
4.1 **敏感规则只许追加(v2.14.0)**
|
|
50
|
+
- `.carlos.json` 的 `sensitive` 只能**加**规则;`!x` / `-x` 否定式必须被忽略。
|
|
51
|
+
- 配置损坏时退回内置基线,不许因为「配置读不到」而放宽。
|
|
52
|
+
|
|
53
|
+
4.2 **负对照不得让工作区停在改动前(v2.14.0)**
|
|
54
|
+
- 进入临界区前必须写 `journal.json`;`finally` 里还原后必须逐文件核对摘要。
|
|
55
|
+
- 还原失败时**保留备份目录**(下一次调用靠它恢复),不许删了当没事。
|
|
56
|
+
|
|
44
57
|
5. **审计链的 legacy 记录不得重置链起点**
|
|
45
58
|
- 旧格式记录(无 hash)只计入 `legacy` 计数,**保持 `prev` 不变**。
|
|
46
59
|
- 重置会让 v2.5 升级上来的用户审计链长期报红 —— 误报比漏报更伤信任。
|
|
47
60
|
|
|
48
|
-
6.
|
|
61
|
+
6.1 **插件清单只能是 chip,且工具面 ≤16 项(v2.14.1)**
|
|
62
|
+
- Cindy 已移除 `kind:"mcp"`;`tools` 超过 16 项直接拒装。
|
|
63
|
+
- 20 个操作走两段式:`ghost.json` 只声明 `list_tools` / `call_tool`,
|
|
64
|
+
`main.js` 的类目表必须**恰好覆盖**服务端全部操作(`check:full` 守着)。
|
|
65
|
+
- 随包 Node 程序不能依赖 node_modules(Forge 打包会跳过),
|
|
66
|
+
所以协议层是自研的 `src/mcp-stdio.mjs`,不是 SDK。
|
|
67
|
+
|
|
68
|
+
7. **不得引入硬编码密钥 / Token / 路径**
|
|
49
69
|
- 密钥走环境变量;状态目录走 `CARLOS_FLOW_HOME`;路径用 `__ROOT__` 占位符 + `init` 渲染。
|
|
50
70
|
|
|
51
71
|
7. **工具描述与实现必须一致**
|
|
@@ -62,6 +82,11 @@ npm run test:all # 主测试套件(smoke + e2e + p0 + trigger + con
|
|
|
62
82
|
npm run test:scope # 越界拦截真实验证(真实 git 仓库 + 真实改动)
|
|
63
83
|
npm run test:audit # 审计链篡改检测验证(HMAC / plain / legacy / date)
|
|
64
84
|
npm run test:bridge # Bridge 身份隔离(端口上是别人的 bridge 不得复用)
|
|
85
|
+
npm run test:sensitive # 项目级敏感规则:只能追加、否定式无效、坏配置退回基线
|
|
86
|
+
npm run test:lock # 状态锁:退避 / 死锁回收 / fail-closed
|
|
87
|
+
npm run test:falsify # 负对照:还原核对 + 崩溃恢复
|
|
88
|
+
npm run test:mcp # 零依赖 MCP stdio 服务端(握手 / stdout 纯净 / 未知方法)
|
|
89
|
+
npm run test:dispatch # chip 两段式目录(真实服务端 + main.js 端到端)
|
|
65
90
|
npm run test:lang # 产物语言体检的自检
|
|
66
91
|
npm run test:package # 包级端到端(真实 tarball + 干净安装 + 真实 MCP 握手)
|
|
67
92
|
npm run check:full # 对外产物全面体检
|
|
@@ -75,7 +100,7 @@ npm run check:readme # 双语 README 未漂移
|
|
|
75
100
|
变异测试(耗时较长,发布前跑):
|
|
76
101
|
|
|
77
102
|
```bash
|
|
78
|
-
npm run test:mutation #
|
|
103
|
+
npm run test:mutation # 20 类变异体必须 20/20 全部被抓住
|
|
79
104
|
```
|
|
80
105
|
|
|
81
106
|
---
|
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,29 @@
|
|
|
1
|
+
## [2.14.1] - 2026-11-17
|
|
2
|
+
- 装机修复:Cindy 已移除 `kind:"mcp"` 声明,且 chip 的 tools 上限为 16 项 —— 2.14.0 的清单(20 个工具 + mcp)在当前宿主**直接拒装**。本版改为宿主手册 §3.5 的两段式目录:只声明 `list_tools` / `call_tool`,分发表放进新增的 `main.js`(20 个操作全部可达)
|
|
3
|
+
- 零依赖 stdio 服务端:新增 `src/mcp-stdio.mjs` 取代 `@modelcontextprotocol/sdk`(Forge 打包跳过 node_modules、运行期禁止联网装依赖),`node.protocol` 改为 `mcp-stdio`;package.json 运行时依赖清空
|
|
4
|
+
- 目录即自纠:`list_tools` 概览/下钻(5 个类目 gate/verify/audit/infra/trigger),下钻时**同一份结果**下发该类目 RULES;`call_tool` 对未知操作附全部可用操作名、对缺参/非法参数附参数 schema 与 RULES
|
|
5
|
+
- 长任务续命:verify / falsify / dispatch 走 call_tool 时按 45s 发心跳,避免 330s 工具窗口把慢验证判超时
|
|
6
|
+
- 开发路径同步:`carlos init --target cindy` 把包内相对入口(entry / node.entry)渲染成绝对路径,仓库直连安装继续可用
|
|
7
|
+
- 门禁同步:`check-full` / `check-templates` 认识两段式清单(校验 main.js 类目表恰好覆盖服务端全部操作、node.entry 真实存在、不得用 __ROOT__),并新增「直接声明超过 16 项即红」
|
|
8
|
+
- 回归新增:`test:mcp`(18 条,协议握手 / stdout 纯净 / 通知不回包 / 未知方法 -32601)、`test:dispatch`(23 条,真实起服务端 + vm 跑 main.js 的端到端分发)
|
|
9
|
+
|
|
10
|
+
## [2.14.0] - 2026-11-17
|
|
11
|
+
- 项目级敏感路径扩展:仓库根 `.carlos.json` 可追加 `sensitive.names/segments/extensions/prefixes`(只能追加,否定式 `!` `-` 一律忽略;配置损坏自动退回内置基线)
|
|
12
|
+
- 负对照安全性:`flow_falsify` 进入前写还原日志、还原后逐文件核对摘要;被强杀留下的 pending 日志会在下一次调用时先把工作区救回来(返回值如实报告 `restore` / `recovered`)
|
|
13
|
+
- 状态锁:指数退避 + 抖动(固定 15ms 会让多进程同步撞锁),持有者 pid 已死即时回收,超时错误点明持有者 pid
|
|
14
|
+
- 向导模式:占位卡未补齐时直接给出可复制的 `flow_submit_requirement` 补齐骨架(pro 模式行为不变)
|
|
15
|
+
- 裁定闸门注释按 docs/TOOL_CONTRACTS.md 的 9 组对齐(2 无条件 + 7 仅 PASS),修掉「之四/之五各出现两次」的历史错乱
|
|
16
|
+
- bridge:启动时清理 pid 已死的僵尸工牌(只删死进程的),`/health` 增补 `idle_ms` / `idle_for_ms` / `active_sockets`
|
|
17
|
+
- 回归新增:test:sensitive / test:lock / test:falsify 三套真实验证,e2e 第 31 组覆盖占位卡补齐骨架
|
|
18
|
+
|
|
19
|
+
## [2.13.1] - 2026-11-17
|
|
20
|
+
- 轻量化:bridge 空闲退出(默认 30 分钟,CARLOS_BRIDGE_IDLE_MS 可调,0 关闭)+ 子进程死则 bridge 跟退;实测进程 14→5、私有内存 430→95MB
|
|
21
|
+
- 止住测试污染:测试端口改为向系统申请真空闲端口 + /health 校验 flow_home 身份;实测再跑 e2e+p0 向真实目录新增会话 0 个
|
|
22
|
+
- 降门槛:scope 校验统一到 git 仓库根(与 git diff 同基准),不传 cwd 也不再误报「路径不存在」;显式 cwd 仍作为验证执行目录
|
|
23
|
+
- 报错解释层:pro 模式附「为什么被拦」机制说明,guide 模式只留人话(不叠两层)
|
|
24
|
+
- 运维入口:新增 carlos clean(默认只列不删,只动测试前缀会话,永不删审计链);客户端启动自动回收失效 pid 文件
|
|
25
|
+
- 装机清单修正:flow_mode 工具此前在装机清单中缺失,版本号 2.12.0→2.13.1
|
|
26
|
+
|
|
1
27
|
## [2.13.0]
|
|
2
28
|
- CI 全绿:修复 3 个漂移的变异锚点(M2/M3 claim/verdict 闸门、M15 审计链校验),check:anchors 恢复 17/17
|
|
3
29
|
- 工具清单对齐:ghost.json 与 src/index.js 统一为 20 个工具(移除空名称残留)
|
package/README.en.md
CHANGED
|
@@ -100,6 +100,19 @@ A red-team run reproduced 4 state losses in 40 concurrent rounds; now it reports
|
|
|
100
100
|
|
|
101
101
|
---
|
|
102
102
|
|
|
103
|
+
## 🧩 Calling it from Cindy
|
|
104
|
+
|
|
105
|
+
The plugin exposes a **two-level catalogue** (Cindy caps a plugin at 16 declared tools; this one has 20 operations):
|
|
106
|
+
|
|
107
|
+
- `list_tools` — browse first: omit `category` for an overview of the 5 categories
|
|
108
|
+
(gate / verify / audit / infra / trigger); pass it for that category's operations **plus the RULES** you must read first.
|
|
109
|
+
- `call_tool` — then execute: `name` from `list_tools`, `args` per its parameter help.
|
|
110
|
+
An unknown name returns every available operation; missing or invalid args return the schema and rules.
|
|
111
|
+
|
|
112
|
+
On other platforms (OpenCode / Cursor / Cline / VS Code / Claude Desktop) the 20 tools are exposed directly — no extra hop.
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
103
116
|
## 🏗️ Technical Architecture
|
|
104
117
|
|
|
105
118
|
### Overview
|
|
@@ -224,6 +237,30 @@ One package, six platforms. The init command generates the right config file for
|
|
|
224
237
|
|
|
225
238
|
---
|
|
226
239
|
|
|
240
|
+
## 🔧 Per-project configuration (optional)
|
|
241
|
+
|
|
242
|
+
Drop a `.carlos.json` at your repo root to teach the gate about **your own** sensitive
|
|
243
|
+
files (anything beyond the built-in list):
|
|
244
|
+
|
|
245
|
+
```json
|
|
246
|
+
{
|
|
247
|
+
"sensitive": {
|
|
248
|
+
"names": ["pay_api_key.txt"],
|
|
249
|
+
"segments": ["ledger"],
|
|
250
|
+
"extensions": [".vault"],
|
|
251
|
+
"prefixes": ["billing/ledger/"]
|
|
252
|
+
}
|
|
253
|
+
}
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
- **Append-only, never relax**: entries starting with `!` or `-` are ignored; the built-in
|
|
257
|
+
list (`.env`, private keys, lock files, `migrations/`, …) always applies.
|
|
258
|
+
- **A broken config cannot loosen the gate**: on parse failure the built-in list is used.
|
|
259
|
+
- The engine walks up from the working directory (max 12 levels) to the nearest `.carlos.json`.
|
|
260
|
+
- Matched paths are treated as sensitive when submitting a task card, so they require `confirmed: true`.
|
|
261
|
+
|
|
262
|
+
---
|
|
263
|
+
|
|
227
264
|
## 📦 Version Consistency Convention (Dev Environment)
|
|
228
265
|
|
|
229
266
|
When you configure Carlos Flow for your AI, there are three conventions worth knowing:
|
|
@@ -486,8 +523,9 @@ npm pack
|
|
|
486
523
|
| [TRIGGER_GUIDE.md](./TRIGGER_GUIDE.md) | Deep guide to the Smart Trigger Engine (config, scoring, activation, feedback learning) |
|
|
487
524
|
| [CHANGELOG.md](./CHANGELOG.md) | Version history (Keep a Changelog + SemVer) |
|
|
488
525
|
| [MIGRATION.md](./MIGRATION.md) | Migrating from `carlos-flow-cindy` / `carlos-flow-opencode` |
|
|
489
|
-
| [
|
|
490
|
-
| [
|
|
526
|
+
| [Release Notes v2.13.0](./docs/RELEASE_v2.13.0.md) | Latest release status, CI results and regression numbers |
|
|
527
|
+
| [QA Report (historical snapshot)](./docs/QA_REPORT_v2.5.5.md) | Third-party read-only audit, valid for v2.5.5 only |
|
|
528
|
+
| [Mutation Report (historical snapshot)](./docs/MUTATION_REPORT_v2.5.5.md) | Mutation injection details, valid for v2.5.5 only |
|
|
491
529
|
|
|
492
530
|
---
|
|
493
531
|
|
package/README.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Carlos 工作流 (Carlos-Flow)
|
|
2
2
|
|
|
3
3
|
[](https://github.com/skyer-now/carlos-flow)
|
|
4
|
-
[](https://www.npmjs.com/package/carlos-flow)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
|
|
7
7
|
[中文](README.zh.md) | [English Version](README.en.md)
|
|
@@ -29,6 +29,19 @@
|
|
|
29
29
|
|
|
30
30
|
---
|
|
31
31
|
|
|
32
|
+
## 🧩 在 Cindy 里怎么调用
|
|
33
|
+
|
|
34
|
+
插件的工具面是**两段式目录**(Cindy 对单个插件的工具声明有 16 项上限,本插件有 20 个操作):
|
|
35
|
+
|
|
36
|
+
- `list_tools` —— 先看目录:不传 `category` 给 5 个类目概览(gate / verify / audit / infra / trigger),
|
|
37
|
+
传了给该类目的操作明细 + **调用前必读的 RULES**。
|
|
38
|
+
- `call_tool` —— 再执行:`name` 用 `list_tools` 返回的操作名,`args` 照它的参数说明填。
|
|
39
|
+
传错名字会附全部可用操作名;少填参数会附参数 schema 与规则,照着改就能过。
|
|
40
|
+
|
|
41
|
+
其它平台(OpenCode / Cursor / Cline / VS Code / Claude Desktop)仍然直接暴露 20 个工具,不需要这一步。
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
32
45
|
## ⚙️ 工作原理
|
|
33
46
|
|
|
34
47
|
Carlos 工作流的核心逻辑是“闭环质检”:
|
|
@@ -39,6 +52,28 @@ Carlos 工作流的核心逻辑是“闭环质检”:
|
|
|
39
52
|
|
|
40
53
|
---
|
|
41
54
|
|
|
55
|
+
## 🔧 项目级配置(可选)
|
|
56
|
+
|
|
57
|
+
在仓库根放一个 `.carlos.json`,就能让门禁认识**你项目自己**的敏感文件(内置名单之外的):
|
|
58
|
+
|
|
59
|
+
```json
|
|
60
|
+
{
|
|
61
|
+
"sensitive": {
|
|
62
|
+
"names": ["pay_api_key.txt"],
|
|
63
|
+
"segments": ["ledger"],
|
|
64
|
+
"extensions": [".vault"],
|
|
65
|
+
"prefixes": ["billing/ledger/"]
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
- **只能追加,不能放宽**:以 `!` 或 `-` 开头的条目一律被忽略;内置名单(`.env`、私钥、锁文件、`migrations` 目录等)永远生效。
|
|
71
|
+
- **写坏了也不会放宽**:配置解析失败时自动退回内置名单,不会静默放行。
|
|
72
|
+
- 引擎从调用的工作目录向上找最近的 `.carlos.json`(最多 12 层),所以在大仓的子目录里调用也能命中。
|
|
73
|
+
- 命中的路径在提交任务卡时会被判为敏感路径,需要 `confirmed: true` 才能继续。
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
42
77
|
## ❓ 常见问题 (FAQ)
|
|
43
78
|
|
|
44
79
|
**Q:我用的是 OpenCode / Claude Code,能装吗?**
|
|
@@ -88,8 +123,9 @@ git log --oneline origin/main -1
|
|
|
88
123
|
| [TRIGGER_GUIDE.md](./TRIGGER_GUIDE.md) | 智能触发引擎深度指南(配置、评分、激活、反馈学习) |
|
|
89
124
|
| [CHANGELOG.md](./CHANGELOG.md) | 版本历史(遵循 Keep a Changelog + SemVer) |
|
|
90
125
|
| [MIGRATION.md](./MIGRATION.md) | 从 `carlos-flow-cindy` / `carlos-flow-opencode` 迁移 |
|
|
91
|
-
| [
|
|
92
|
-
| [
|
|
126
|
+
| [发布说明 v2.13.0](./docs/RELEASE_v2.13.0.md) | 最新发布状态、CI 结论与回归数字 |
|
|
127
|
+
| [QA 报告(历史快照)](./docs/QA_REPORT_v2.5.5.md) | 第三方只读审计,仅对 v2.5.5 负责 |
|
|
128
|
+
| [变异报告(历史快照)](./docs/MUTATION_REPORT_v2.5.5.md) | 变异注入详情,仅对 v2.5.5 负责 |
|
|
93
129
|
|
|
94
130
|
## 🚀 准备好开始了吗?
|
|
95
131
|
只需几行命令,为你的 AI 加上这层保护罩。
|
package/README.zh.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Carlos 工作流 (Carlos-Flow)
|
|
2
2
|
|
|
3
3
|
[](https://github.com/skyer-now/carlos-flow)
|
|
4
|
-
[](https://www.npmjs.com/package/carlos-flow)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
|
|
7
7
|
[中文](README.zh.md) | [English Version](README.en.md)
|
|
@@ -29,6 +29,19 @@
|
|
|
29
29
|
|
|
30
30
|
---
|
|
31
31
|
|
|
32
|
+
## 🧩 在 Cindy 里怎么调用
|
|
33
|
+
|
|
34
|
+
插件的工具面是**两段式目录**(Cindy 对单个插件的工具声明有 16 项上限,本插件有 20 个操作):
|
|
35
|
+
|
|
36
|
+
- `list_tools` —— 先看目录:不传 `category` 给 5 个类目概览(gate / verify / audit / infra / trigger),
|
|
37
|
+
传了给该类目的操作明细 + **调用前必读的 RULES**。
|
|
38
|
+
- `call_tool` —— 再执行:`name` 用 `list_tools` 返回的操作名,`args` 照它的参数说明填。
|
|
39
|
+
传错名字会附全部可用操作名;少填参数会附参数 schema 与规则,照着改就能过。
|
|
40
|
+
|
|
41
|
+
其它平台(OpenCode / Cursor / Cline / VS Code / Claude Desktop)仍然直接暴露 20 个工具,不需要这一步。
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
32
45
|
## ⚙️ 工作原理
|
|
33
46
|
|
|
34
47
|
Carlos 工作流的核心逻辑是“闭环质检”:
|
|
@@ -39,6 +52,28 @@ Carlos 工作流的核心逻辑是“闭环质检”:
|
|
|
39
52
|
|
|
40
53
|
---
|
|
41
54
|
|
|
55
|
+
## 🔧 项目级配置(可选)
|
|
56
|
+
|
|
57
|
+
在仓库根放一个 `.carlos.json`,就能让门禁认识**你项目自己**的敏感文件(内置名单之外的):
|
|
58
|
+
|
|
59
|
+
```json
|
|
60
|
+
{
|
|
61
|
+
"sensitive": {
|
|
62
|
+
"names": ["pay_api_key.txt"],
|
|
63
|
+
"segments": ["ledger"],
|
|
64
|
+
"extensions": [".vault"],
|
|
65
|
+
"prefixes": ["billing/ledger/"]
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
- **只能追加,不能放宽**:以 `!` 或 `-` 开头的条目一律被忽略;内置名单(`.env`、私钥、锁文件、`migrations` 目录等)永远生效。
|
|
71
|
+
- **写坏了也不会放宽**:配置解析失败时自动退回内置名单,不会静默放行。
|
|
72
|
+
- 引擎从调用的工作目录向上找最近的 `.carlos.json`(最多 12 层),所以在大仓的子目录里调用也能命中。
|
|
73
|
+
- 命中的路径在提交任务卡时会被判为敏感路径,需要 `confirmed: true` 才能继续。
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
42
77
|
## ❓ 常见问题 (FAQ)
|
|
43
78
|
|
|
44
79
|
**Q:我用的是 OpenCode / Claude Code,能装吗?**
|
|
@@ -88,8 +123,9 @@ git log --oneline origin/main -1
|
|
|
88
123
|
| [TRIGGER_GUIDE.md](./TRIGGER_GUIDE.md) | 智能触发引擎深度指南(配置、评分、激活、反馈学习) |
|
|
89
124
|
| [CHANGELOG.md](./CHANGELOG.md) | 版本历史(遵循 Keep a Changelog + SemVer) |
|
|
90
125
|
| [MIGRATION.md](./MIGRATION.md) | 从 `carlos-flow-cindy` / `carlos-flow-opencode` 迁移 |
|
|
91
|
-
| [
|
|
92
|
-
| [
|
|
126
|
+
| [发布说明 v2.13.0](./docs/RELEASE_v2.13.0.md) | 最新发布状态、CI 结论与回归数字 |
|
|
127
|
+
| [QA 报告(历史快照)](./docs/QA_REPORT_v2.5.5.md) | 第三方只读审计,仅对 v2.5.5 负责 |
|
|
128
|
+
| [变异报告(历史快照)](./docs/MUTATION_REPORT_v2.5.5.md) | 变异注入详情,仅对 v2.5.5 负责 |
|
|
93
129
|
|
|
94
130
|
## 🚀 准备好开始了吗?
|
|
95
131
|
只需几行命令,为你的 AI 加上这层保护罩。
|
package/TRIGGER_GUIDE.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Carlos Flow 智能触发引擎使用指南
|
|
2
2
|
|
|
3
|
-
> **版本**: v2.
|
|
3
|
+
> **版本**: v2.14.1
|
|
4
4
|
> **适用**:`carlos-flow` 单包架构(2.6.0+)
|
|
5
5
|
> **代码位置**:`src/trigger.js`(零外部依赖的纯 JavaScript 实现)
|
|
6
6
|
|
|
@@ -766,7 +766,7 @@ node client/carlos.js flow_status '{"sessionId":"my-task"}'
|
|
|
766
766
|
## 📚 相关资源
|
|
767
767
|
|
|
768
768
|
- [测试脚本](test/trigger-e2e.mjs) - E2E 测试套件(29 项,含 10 项回归用例)
|
|
769
|
-
- [变异测试](scripts/mutation-check.mjs) - 注入退化验证测试套件真的能抓住(
|
|
769
|
+
- [变异测试](scripts/mutation-check.mjs) - 注入退化验证测试套件真的能抓住(20 类变异)
|
|
770
770
|
- [核心代码](src/trigger.js) - 触发引擎实现
|
|
771
771
|
- [集成示例](client/carlos.js) - 客户端集成代码
|
|
772
772
|
- [完整 README](./README.md) - 项目总览与能力矩阵
|
|
@@ -779,5 +779,5 @@ MIT License
|
|
|
779
779
|
|
|
780
780
|
---
|
|
781
781
|
|
|
782
|
-
**版本**: v2.
|
|
782
|
+
**版本**: v2.14.1
|
|
783
783
|
**更新日期**: 2026-11-12
|
package/bridge/mcp-bridge.js
CHANGED
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
import { spawn } from "node:child_process";
|
|
7
7
|
import { createServer } from "node:net";
|
|
8
8
|
import { createHash } from "node:crypto";
|
|
9
|
+
import { readFileSync, readdirSync, unlinkSync } from "node:fs";
|
|
9
10
|
import { fileURLToPath } from "node:url";
|
|
10
11
|
import path from "node:path";
|
|
11
12
|
|
|
@@ -29,6 +30,57 @@ const RATE_LIMIT = 10; // 每秒最多请求数
|
|
|
29
30
|
// 现在默认 180s(> 服务端 120s 上限),可用 CARLOS_BRIDGE_TIMEOUT_MS 覆盖。
|
|
30
31
|
const REQUEST_TIMEOUT = Number(process.env.CARLOS_BRIDGE_TIMEOUT_MS) || 180000; // 180s
|
|
31
32
|
|
|
33
|
+
// ---- 空闲退出(idle reaper)----
|
|
34
|
+
//
|
|
35
|
+
// 为什么必须有:ghost.json 一直声明着 `"idleTimeoutSeconds": 300` 与
|
|
36
|
+
// `"lifecycle": "on-demand"`,但本文件从来没有任何空闲退出实现。
|
|
37
|
+
// 结果实测(2026-11-17):机器上常驻 14 个进程、私有内存 430MB,
|
|
38
|
+
// 仓库里还堆着 40 个 bridge-*.pid(36 个指向已死进程)。
|
|
39
|
+
//
|
|
40
|
+
// 代价很低:实测 bridge 从启动到 /health 就绪只要 118ms(server 155ms),
|
|
41
|
+
// 所以「用的时候起、闲了就退」几乎无感。默认 30 分钟(不是 5 分钟),
|
|
42
|
+
// 避免短暂休息就触发冷启动。
|
|
43
|
+
// CARLOS_BRIDGE_IDLE_MS=0 可关闭本机制(常驻场景)。
|
|
44
|
+
const IDLE_MS = (() => {
|
|
45
|
+
const raw = process.env.CARLOS_BRIDGE_IDLE_MS;
|
|
46
|
+
if (raw === undefined || raw === "") return 30 * 60 * 1000;
|
|
47
|
+
const n = Number(raw);
|
|
48
|
+
if (!Number.isFinite(n) || n < 0) return 30 * 60 * 1000;
|
|
49
|
+
return n;
|
|
50
|
+
})();
|
|
51
|
+
let lastActivity = Date.now();
|
|
52
|
+
let activeSockets = 0;
|
|
53
|
+
const touch = () => { lastActivity = Date.now(); };
|
|
54
|
+
|
|
55
|
+
// ---- 启动时清理僵尸工牌 ----
|
|
56
|
+
//
|
|
57
|
+
// 背景(2026-11-17 实测):仓库根堆了 40 个 bridge-*.pid,其中 36 个指向已不存在的进程。
|
|
58
|
+
// 这些文件没有任何用处,却会让人「以为 bridge 还在跑」,也让排查端口占用时判断失真。
|
|
59
|
+
// 只删 **pid 已死** 的工牌:活着的一律不动(pid 可能被别的进程复用,误删会掩盖真实占用)。
|
|
60
|
+
function sweepStalePidFiles() {
|
|
61
|
+
let names = [];
|
|
62
|
+
try { names = readdirSync(MCP_ROOT); } catch { return { removed: 0, kept: 0 }; }
|
|
63
|
+
let removed = 0;
|
|
64
|
+
let kept = 0;
|
|
65
|
+
for (const name of names) {
|
|
66
|
+
if (!/^bridge-\d+\.pid$/.test(name)) continue;
|
|
67
|
+
const file = path.join(MCP_ROOT, name);
|
|
68
|
+
let pid = 0;
|
|
69
|
+
try { pid = parseInt(readFileSync(file, "utf8").trim(), 10); } catch { continue; }
|
|
70
|
+
if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid) { kept++; continue; }
|
|
71
|
+
let alive = true;
|
|
72
|
+
try {
|
|
73
|
+
process.kill(pid, 0);
|
|
74
|
+
} catch (e) {
|
|
75
|
+
// ESRCH = 进程不存在;EPERM = 存在但无权发信号 → 按活着处理
|
|
76
|
+
if (e && e.code === "ESRCH") alive = false;
|
|
77
|
+
}
|
|
78
|
+
if (alive) { kept++; continue; }
|
|
79
|
+
try { unlinkSync(file); removed++; } catch { /* 被别的进程删了 */ }
|
|
80
|
+
}
|
|
81
|
+
return { removed, kept };
|
|
82
|
+
}
|
|
83
|
+
|
|
32
84
|
if (!TOKEN) {
|
|
33
85
|
process.stderr.write("[bridge] ❌ CARLOS_BRIDGE_TOKEN 未设置(fail-closed)\n");
|
|
34
86
|
process.exit(1);
|
|
@@ -87,6 +139,10 @@ child.on("exit", (code) => {
|
|
|
87
139
|
try { c.socket.end(); } catch {}
|
|
88
140
|
}
|
|
89
141
|
pendingClients.clear();
|
|
142
|
+
// 子进程没了,这个 bridge 已经没用了:必须跟着退出。
|
|
143
|
+
// 否则会留下「端口活着、服务死了」的僵尸 —— 调用方连得上却永远等不到回包,
|
|
144
|
+
// 只能等到 180s 超时(比进程根本不存要难查得多)。
|
|
145
|
+
shutdown(code === 0 ? 0 : 1);
|
|
90
146
|
});
|
|
91
147
|
|
|
92
148
|
// 速率限制(per-connection sliding window)
|
|
@@ -108,7 +164,13 @@ const server = createServer((socket) => {
|
|
|
108
164
|
let buf = "";
|
|
109
165
|
let size = 0;
|
|
110
166
|
|
|
167
|
+
// 活跃连接计数:只要还有连接就不算空闲(客户端可能正在等长调用)
|
|
168
|
+
activeSockets++;
|
|
169
|
+
touch();
|
|
170
|
+
socket.on("close", () => { activeSockets = Math.max(0, activeSockets - 1); touch(); });
|
|
171
|
+
|
|
111
172
|
socket.on("data", (data) => {
|
|
173
|
+
touch();
|
|
112
174
|
size += data.length;
|
|
113
175
|
if (size > MAX_REQUEST_SIZE) {
|
|
114
176
|
socket.write(JSON.stringify({ error: "413 Payload Too Large" }) + "\n");
|
|
@@ -144,6 +206,11 @@ const server = createServer((socket) => {
|
|
|
144
206
|
flow_home: process.env.CARLOS_FLOW_HOME || "",
|
|
145
207
|
pid: process.pid,
|
|
146
208
|
port: PORT,
|
|
209
|
+
// 空闲策略可观测:排查「为什么它退了 / 为什么它不退」时不用猜配置。
|
|
210
|
+
// 恒为附加字段,客户端只比对 root / flow_home,不受影响。
|
|
211
|
+
idle_ms: IDLE_MS,
|
|
212
|
+
idle_for_ms: Date.now() - lastActivity,
|
|
213
|
+
active_sockets: activeSockets,
|
|
147
214
|
};
|
|
148
215
|
socket.write(JSON.stringify(health) + "\n");
|
|
149
216
|
continue;
|
|
@@ -193,12 +260,45 @@ server.on("error", (e) => {
|
|
|
193
260
|
|
|
194
261
|
server.listen(PORT, "127.0.0.1", () => {
|
|
195
262
|
process.stderr.write(`[bridge] Carlos MCP Bridge listening on 127.0.0.1:${PORT}\n`);
|
|
263
|
+
const swept = sweepStalePidFiles();
|
|
264
|
+
if (swept.removed > 0) {
|
|
265
|
+
process.stderr.write(`[bridge] 已清理 ${swept.removed} 个僵尸 pid 工牌(保留 ${swept.kept} 个活进程的)\n`);
|
|
266
|
+
}
|
|
196
267
|
});
|
|
197
268
|
|
|
269
|
+
let shuttingDown = false;
|
|
270
|
+
function shutdown(code) {
|
|
271
|
+
if (shuttingDown) return;
|
|
272
|
+
shuttingDown = true;
|
|
273
|
+
// 自己把自己的工牌拆下来 —— 否则仓库里会继续堆死 pid 文件
|
|
274
|
+
// (实测 40 个,其中 36 个指向已不存在的进程)。
|
|
275
|
+
// 只删「内容是本进程 pid」的那个,避免两个桥互删工牌。
|
|
276
|
+
try {
|
|
277
|
+
const pidFile = path.join(MCP_ROOT, `bridge-${PORT}.pid`);
|
|
278
|
+
if (parseInt(readFileSync(pidFile, "utf8").trim(), 10) === process.pid) {
|
|
279
|
+
unlinkSync(pidFile);
|
|
280
|
+
}
|
|
281
|
+
} catch { /* 文件不存在 / 已属于别人:忽略 */ }
|
|
282
|
+
try { child.stdin.end(); } catch {}
|
|
283
|
+
try { child.kill("SIGTERM"); } catch {}
|
|
284
|
+
try { server.close(); } catch {}
|
|
285
|
+
setTimeout(() => process.exit(code), 150).unref?.();
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
// 空闲巡检:只有「无活跃连接 + 无待回包请求」才算真空闲
|
|
289
|
+
if (IDLE_MS > 0) {
|
|
290
|
+
const tickMs = Math.min(15000, Math.max(500, Math.floor(IDLE_MS / 4)));
|
|
291
|
+
const timer = setInterval(() => {
|
|
292
|
+
if (activeSockets > 0 || pendingClients.size > 0) { touch(); return; }
|
|
293
|
+
const idleFor = Date.now() - lastActivity;
|
|
294
|
+
if (idleFor < IDLE_MS) return;
|
|
295
|
+
process.stderr.write(`[bridge] 已空闲 ${Math.round(idleFor / 1000)}s,按空闲策略退出(CARLOS_BRIDGE_IDLE_MS=${IDLE_MS})\n`);
|
|
296
|
+
shutdown(0);
|
|
297
|
+
}, tickMs);
|
|
298
|
+
// 定时器本身不能让进程活着(否则空闲退出永远等不到)
|
|
299
|
+
timer.unref?.();
|
|
300
|
+
}
|
|
301
|
+
|
|
198
302
|
// 优雅退出
|
|
199
|
-
process.on("SIGTERM", () =>
|
|
200
|
-
|
|
201
|
-
child.kill("SIGTERM");
|
|
202
|
-
server.close();
|
|
203
|
-
process.exit(0);
|
|
204
|
-
});
|
|
303
|
+
process.on("SIGTERM", () => shutdown(0));
|
|
304
|
+
process.on("SIGINT", () => shutdown(0));
|