carlos-flow 2.10.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 +99 -0
- package/INSTALL.md +103 -0
- package/README.en.md +5 -3
- package/README.md +5 -3
- package/README.zh.md +5 -3
- 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 +12 -4
- package/scripts/lang-audit.mjs +8 -0
- package/scripts/publish-gate.mjs +121 -0
- package/scripts/sync-version.mjs +126 -0
- package/smoke-test.js +142 -0
- package/src/dispatch.js +71 -4
- package/src/index.js +55 -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/)
|
|
@@ -5,6 +56,54 @@
|
|
|
5
56
|
|
|
6
57
|
---
|
|
7
58
|
|
|
59
|
+
## [2.11.0] - 2026-11-12 — 双轴审查补缺口:坏味道基线内置 + WARN 自动汇总
|
|
60
|
+
|
|
61
|
+
> 本版把「未做项」里两条低优先级增强做实,方案经三轴内审(Standards / Spec / 风险)评审后调整:
|
|
62
|
+
> 清单不硬编码「Fowler 12 种」这类无法核实的数字,改为显式可枚举的自维护基线;
|
|
63
|
+
> WARN 汇总采用「即时派生、零 state 变更」的实现,不引入 schema 迁移。
|
|
64
|
+
|
|
65
|
+
### ✨ 新增 | Added
|
|
66
|
+
|
|
67
|
+
- **坏味道基线内置进 Standards 轴 prompt**(`src/dispatch.js` 的 `SMELL_BASELINE`,18 条)。
|
|
68
|
+
- 以前 prompt 只写了一句「对照仓库规范文件 + Fowler 坏味道基线」,基线内容没给,
|
|
69
|
+
判定质量全看模型自己的记性 —— 不同上下文下结果会漂移。
|
|
70
|
+
- 现在基线**逐条编号内联进 prompt**(审计 subagent 跑在目标仓库,读不到包内文件,
|
|
71
|
+
写成 `docs/xxx.md` 让它去读等于没写)。
|
|
72
|
+
- 出处如实标注:术语对齐 Fowler《Refactoring》第二版第 3 章 Code Smells,
|
|
73
|
+
**但本表由 Carlos 自维护、非原书全表** —— 流传的「Fowler 12 种坏味道」是二手博客
|
|
74
|
+
的说法,不是书里的口径,写进审计权威会把事实错误固化下来。
|
|
75
|
+
- **WARN 自动汇总**(`flow_verdict` / `flow_status` 返回 `warn_count` + `warn_findings`)。
|
|
76
|
+
- 以前 WARN 只躺在 `state.audit_axes` 里,主 Agent 不主动读就看不到,
|
|
77
|
+
「带坏味道通过」在汇报里等于被吞掉。
|
|
78
|
+
- 口径与双轴门禁完全一致:**只收 `card_ts` 与当前卡一致的轴结论**,换卡后旧 WARN 自动失效。
|
|
79
|
+
- 三种裁定(PASS / DIRECTION / LOCAL)都带这份汇总 —— 返工意见恰恰最需要坏味道清单。
|
|
80
|
+
- **零 state 变更**:WARN 数据本就在 `audit_axes` 里,即时派生即可,
|
|
81
|
+
不 bump `schemaVersion`、不写迁移分支。
|
|
82
|
+
- **`test/audit-baseline.mjs`** —— 审计基线守护测试(10 条断言):基线条目齐全、条目名唯一、
|
|
83
|
+
规模下限、每条都有中文说明、判定词表与 `flow_audit_submit` 的 enum 对齐、
|
|
84
|
+
基线不泄漏进 executor 合同、prompt 长度上限、出处标注。
|
|
85
|
+
|
|
86
|
+
### 🐛 修复 | Fixed
|
|
87
|
+
|
|
88
|
+
- **两轴判定词表与 `flow_audit_submit` 的 enum 错位**:prompt 要求输出「通过/违规/坏味道」,
|
|
89
|
+
而 enum 只有 `PASS / WARN / FAIL`。词表不一致时 subagent 输出自然语言、由主 Agent 手工映射,
|
|
90
|
+
而 **FAIL(硬拦)与 WARN(不拦)的差别就在这一步** —— 映射错了硬拦就失效。
|
|
91
|
+
两轴的 `format` 统一改成 `PASS / WARN / FAIL`,并写明各自判定口径。
|
|
92
|
+
|
|
93
|
+
### 🔒 变更 | Changed
|
|
94
|
+
|
|
95
|
+
- **`flow_audit_submit` 写审计事件**(`kind: "audit_axis_submitted"`):轴结论此前只落在
|
|
96
|
+
`state` 里 —— 可被覆盖、不可追溯。现在审计流水能回答「谁在什么时候提交了什么结论」。
|
|
97
|
+
|
|
98
|
+
### 🔬 验证 | Verification
|
|
99
|
+
|
|
100
|
+
- e2e **85/0**(新增 29a–29f 六条:WARN 汇总随裁定返回 / `flow_status` 镜像 /
|
|
101
|
+
两轴全 PASS 不凭空产生 / 换卡后旧 WARN 失效 / DIRECTION 同样带汇总 / 轴结论进审计流水);
|
|
102
|
+
baseline 10/0;p0 22/0;protocol-consistency 5/0;trigger 29/0;concurrency 3/0;
|
|
103
|
+
acceptance 13/0;smoke 通过。
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
8
107
|
## [2.10.0] - 2026-11-12 — 合并 _carlos-flow-remote 分支:verdict_role 落盘 + 协议字段漂移修复
|
|
9
108
|
|
|
10
109
|
> 本版把 `_carlos-flow-remote` 分支上**发布线缺失**的独有内容合并进来(该分支后被
|
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/README.en.md
CHANGED
|
@@ -287,14 +287,14 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
|
|
|
287
287
|
| `flow_claim` | Claim a dispatch slot (executor / auditor) | Rejected while the activation gate is open |
|
|
288
288
|
| `flow_dispatch` | Dispatch a sub-agent per the four-part contract | Auto-snapshots files in scope before dispatch |
|
|
289
289
|
| `flow_audit_axes` | **Dispatch dual-axis audit** (Standards / Spec) | Generates two parallel audit prompts, read-only |
|
|
290
|
-
| `flow_audit_submit` | **Submit one axis's verdict** | Bound to the current `card_ts`; WARN does not hard-block; same axis can be resubmitted |
|
|
290
|
+
| `flow_audit_submit` | **Submit one axis's verdict** | Bound to the current `card_ts`; WARN does not hard-block; same axis can be resubmitted; writes a traceable audit event |
|
|
291
291
|
| `flow_audit_guard` | **Dual-axis gate self-check** | Same criteria as the gate inside `flow_verdict` |
|
|
292
292
|
| `flow_save_result` | Save a sub-agent's result | — |
|
|
293
293
|
| `flow_run_verify` | **Really execute** `verify.cmd` | Returns exitCode / stdout / stderr + `output_hash` |
|
|
294
294
|
| `flow_falsify` | **Negative control**: run `verify.cmd` pre-change (must fail) and post-change (must pass) | Vacuous tests (`|| true`) rejected; required before PASS |
|
|
295
295
|
| `flow_check_scope` | Check whether files are in scope | Empty scope → fail-closed, everything out of scope |
|
|
296
|
-
| `flow_verdict` | Record verdict PASS / DIRECTION / LOCAL | No PASS without dispatch / passing verification / passing negative control / **both audit axes**; any axis FAIL blocks PASS; returns `verdict_role` |
|
|
297
|
-
| `flow_status` | Query gate state | Exposes `activation_pending` / `verify_passed` / `audit_axes` / `axes_ready` / `verdict_role` |
|
|
296
|
+
| `flow_verdict` | Record verdict PASS / DIRECTION / LOCAL | No PASS without dispatch / passing verification / passing negative control / **both audit axes**; any axis FAIL blocks PASS; returns `verdict_role` + `warn_findings` (WARN digest) |
|
|
297
|
+
| `flow_status` | Query gate state | Exposes `activation_pending` / `verify_passed` / `audit_axes` / `axes_ready` / `verdict_role` / `warn_count` |
|
|
298
298
|
| `flow_audit` | Read the audit stream | Includes 6 activation-related event kinds |
|
|
299
299
|
| `flow_diff_hunks` | Parse `git diff -U0` hunk ranges | — |
|
|
300
300
|
| `flow_bypass` | Toggle bypass mode | Requires `confirmed=true`; auto-cleared on dispatch |
|
|
@@ -302,6 +302,8 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
|
|
|
302
302
|
| `flow_trigger_check` | Smart trigger check | Activates on success; honestly reports score otherwise |
|
|
303
303
|
|
|
304
304
|
> **Dual-axis review** (anti-false-closure #6): before `flow_verdict` records PASS, run `flow_audit_axes` to dispatch the Standards axis (does it follow repo conventions / any code smells) and the Spec axis (does it faithfully implement acceptance). Each axis gathers evidence independently via sub-agents, then `flow_audit_submit` records the verdict. The gate sits **after** the negative control and is the last one before PASS is written; both axes are bound to the current `card_ts` (a previous card's audit cannot impersonate a new one), any FAIL hard-blocks, while WARN (code smells and other judgement calls) is annotated but allowed.
|
|
305
|
+
>
|
|
306
|
+
> **WARN digest (v2.11.0)**: WARN used to live only in `state.audit_axes` — unless the main agent went looking, "passed with code smells" was effectively swallowed on the way to the user report. Both `flow_verdict` and `flow_status` now return `warn_count` / `warn_findings` directly, counting only axes whose `card_ts` still matches the current card (a previous card's WARN expires automatically). The Standards axis prompt also inlines an explicit code-smell baseline (18 entries, terminology aligned with Fowler's *Refactoring* 2nd ed. ch. 3 — **not** the book's full table), so verdicts no longer depend on the model's memory.
|
|
305
307
|
|
|
306
308
|
---
|
|
307
309
|
|
package/README.md
CHANGED
|
@@ -293,14 +293,14 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
|
|
|
293
293
|
| `flow_claim` | 领取派发名额(executor / auditor) | 激活闸门未解时拒绝 |
|
|
294
294
|
| `flow_dispatch` | 按四段合同派发子 Agent | 派发前自动快照 scope 内文件 |
|
|
295
295
|
| `flow_audit_axes` | **派发双轴审计**(Standards / Spec) | 生成两段并行审计 prompt,只读不改 |
|
|
296
|
-
| `flow_audit_submit` | **提交某一轴结论** | 按 `card_ts` 绑定当前卡;WARN
|
|
296
|
+
| `flow_audit_submit` | **提交某一轴结论** | 按 `card_ts` 绑定当前卡;WARN 不硬拦;同轴可覆盖;写审计事件可追溯 |
|
|
297
297
|
| `flow_audit_guard` | **两轴门禁自查** | 与 `flow_verdict` 内的门禁同口径 |
|
|
298
298
|
| `flow_save_result` | 保存子 Agent 执行结果 | — |
|
|
299
299
|
| `flow_run_verify` | **真实执行** `verify.cmd` | 返回 exitCode / stdout / stderr + `output_hash` |
|
|
300
300
|
| `flow_falsify` | **负对照**:改动前跑 verify.cmd 必须失败、改动后必须通过 | 空测试(`|| true`)会被拒;记 PASS 前必做 |
|
|
301
301
|
| `flow_check_scope` | 检查文件是否越界 | 空 scope → fail-closed 全部越界 |
|
|
302
|
-
| `flow_verdict` | 记录裁定 PASS / DIRECTION / LOCAL | 未派发 / 验证未过 / 负对照未过 / **双轴未齐**均不许 PASS;任一轴 FAIL 不许 PASS;返回 `verdict_role` |
|
|
303
|
-
| `flow_status` | 查询门禁状态 | 暴露 `activation_pending` / `verify_passed` / `audit_axes` / `axes_ready` / `verdict_role` |
|
|
302
|
+
| `flow_verdict` | 记录裁定 PASS / DIRECTION / LOCAL | 未派发 / 验证未过 / 负对照未过 / **双轴未齐**均不许 PASS;任一轴 FAIL 不许 PASS;返回 `verdict_role` + `warn_findings`(WARN 汇总) |
|
|
303
|
+
| `flow_status` | 查询门禁状态 | 暴露 `activation_pending` / `verify_passed` / `audit_axes` / `axes_ready` / `verdict_role` / `warn_count` |
|
|
304
304
|
| `flow_audit` | 读取审计流水 | 含 6 类激活相关事件 |
|
|
305
305
|
| `flow_diff_hunks` | 解析 `git diff -U0` 的 hunk 范围 | — |
|
|
306
306
|
| `flow_bypass` | 开关免检模式 | 需 `confirmed=true`;派发自动清零 |
|
|
@@ -308,6 +308,8 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
|
|
|
308
308
|
| `flow_trigger_check` | 智能触发检查 | 达标即实际激活;未达标如实返回评分 |
|
|
309
309
|
|
|
310
310
|
> **双轴审查**(防假闭环之六):`flow_verdict` 落 PASS 前,必须先 `flow_audit_axes` 派发 Standards(合不合规范 + 坏味道)与 Spec(忠不忠实实现验收)两轴,由 subagent 独立取证后 `flow_audit_submit` 提交。门禁位于负对照**之后**,是 PASS 落定前的最后一道;两轴证据都绑定当前 `card_ts`(旧卡审查不能冒充新卡),任一轴 FAIL 硬拦,WARN 只标注不拦。
|
|
311
|
+
>
|
|
312
|
+
> **WARN 汇总(v2.11.0)**:WARN(坏味道等 judgement call)以前只存在 `state.audit_axes` 里,主 Agent 不主动读就看不到,「带坏味道通过」在汇报里等于被吞掉。现在 `flow_verdict` 与 `flow_status` 都直接返回 `warn_count` / `warn_findings`(只收 `card_ts` 与当前卡一致的轴结论,换卡后旧 WARN 自动失效)。Standards 轴的 prompt 还内联了一份显式坏味道基线(18 条,术语对齐 Fowler《Refactoring》第二版第 3 章,**非原书全表**)—— 判定不再依赖模型记性。
|
|
311
313
|
|
|
312
314
|
---
|
|
313
315
|
|
package/README.zh.md
CHANGED
|
@@ -293,14 +293,14 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
|
|
|
293
293
|
| `flow_claim` | 领取派发名额(executor / auditor) | 激活闸门未解时拒绝 |
|
|
294
294
|
| `flow_dispatch` | 按四段合同派发子 Agent | 派发前自动快照 scope 内文件 |
|
|
295
295
|
| `flow_audit_axes` | **派发双轴审计**(Standards / Spec) | 生成两段并行审计 prompt,只读不改 |
|
|
296
|
-
| `flow_audit_submit` | **提交某一轴结论** | 按 `card_ts` 绑定当前卡;WARN
|
|
296
|
+
| `flow_audit_submit` | **提交某一轴结论** | 按 `card_ts` 绑定当前卡;WARN 不硬拦;同轴可覆盖;写审计事件可追溯 |
|
|
297
297
|
| `flow_audit_guard` | **两轴门禁自查** | 与 `flow_verdict` 内的门禁同口径 |
|
|
298
298
|
| `flow_save_result` | 保存子 Agent 执行结果 | — |
|
|
299
299
|
| `flow_run_verify` | **真实执行** `verify.cmd` | 返回 exitCode / stdout / stderr + `output_hash` |
|
|
300
300
|
| `flow_falsify` | **负对照**:改动前跑 verify.cmd 必须失败、改动后必须通过 | 空测试(`|| true`)会被拒;记 PASS 前必做 |
|
|
301
301
|
| `flow_check_scope` | 检查文件是否越界 | 空 scope → fail-closed 全部越界 |
|
|
302
|
-
| `flow_verdict` | 记录裁定 PASS / DIRECTION / LOCAL | 未派发 / 验证未过 / 负对照未过 / **双轴未齐**均不许 PASS;任一轴 FAIL 不许 PASS;返回 `verdict_role` |
|
|
303
|
-
| `flow_status` | 查询门禁状态 | 暴露 `activation_pending` / `verify_passed` / `audit_axes` / `axes_ready` / `verdict_role` |
|
|
302
|
+
| `flow_verdict` | 记录裁定 PASS / DIRECTION / LOCAL | 未派发 / 验证未过 / 负对照未过 / **双轴未齐**均不许 PASS;任一轴 FAIL 不许 PASS;返回 `verdict_role` + `warn_findings`(WARN 汇总) |
|
|
303
|
+
| `flow_status` | 查询门禁状态 | 暴露 `activation_pending` / `verify_passed` / `audit_axes` / `axes_ready` / `verdict_role` / `warn_count` |
|
|
304
304
|
| `flow_audit` | 读取审计流水 | 含 6 类激活相关事件 |
|
|
305
305
|
| `flow_diff_hunks` | 解析 `git diff -U0` 的 hunk 范围 | — |
|
|
306
306
|
| `flow_bypass` | 开关免检模式 | 需 `confirmed=true`;派发自动清零 |
|
|
@@ -308,6 +308,8 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
|
|
|
308
308
|
| `flow_trigger_check` | 智能触发检查 | 达标即实际激活;未达标如实返回评分 |
|
|
309
309
|
|
|
310
310
|
> **双轴审查**(防假闭环之六):`flow_verdict` 落 PASS 前,必须先 `flow_audit_axes` 派发 Standards(合不合规范 + 坏味道)与 Spec(忠不忠实实现验收)两轴,由 subagent 独立取证后 `flow_audit_submit` 提交。门禁位于负对照**之后**,是 PASS 落定前的最后一道;两轴证据都绑定当前 `card_ts`(旧卡审查不能冒充新卡),任一轴 FAIL 硬拦,WARN 只标注不拦。
|
|
311
|
+
>
|
|
312
|
+
> **WARN 汇总(v2.11.0)**:WARN(坏味道等 judgement call)以前只存在 `state.audit_axes` 里,主 Agent 不主动读就看不到,「带坏味道通过」在汇报里等于被吞掉。现在 `flow_verdict` 与 `flow_status` 都直接返回 `warn_count` / `warn_findings`(只收 `card_ts` 与当前卡一致的轴结论,换卡后旧 WARN 自动失效)。Standards 轴的 prompt 还内联了一份显式坏味道基线(18 条,术语对齐 Fowler《Refactoring》第二版第 3 章,**非原书全表**)—— 判定不再依赖模型记性。
|
|
311
313
|
|
|
312
314
|
---
|
|
313
315
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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",
|
|
@@ -18,11 +18,12 @@
|
|
|
18
18
|
"scripts": {
|
|
19
19
|
"test": "node test/smoke.js",
|
|
20
20
|
"test:e2e": "node test/e2e-carlos.mjs",
|
|
21
|
+
"test:baseline": "node test/audit-baseline.mjs",
|
|
21
22
|
"test:p0": "node test/p0-gates.mjs",
|
|
22
23
|
"test:trigger": "node test/trigger-e2e.mjs",
|
|
23
24
|
"test:concurrency": "node test/concurrency-e2e.mjs",
|
|
24
25
|
"test:acceptance": "node test/e2e-acceptance.mjs",
|
|
25
|
-
"test:all": "npm run test && 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",
|
|
26
27
|
"test:mutation": "node scripts/mutation-check.mjs",
|
|
27
28
|
"sync:readme": "node scripts/sync-readme.mjs",
|
|
28
29
|
"check:readme": "node scripts/sync-readme.mjs --check",
|
|
@@ -48,7 +49,10 @@
|
|
|
48
49
|
"check:no-dead-handler": "node scripts/check-no-dead-handler.mjs",
|
|
49
50
|
"test:scope": "node test/scope-enforcement.mjs",
|
|
50
51
|
"test:audit": "node test/audit-chain.mjs",
|
|
51
|
-
"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"
|
|
52
56
|
},
|
|
53
57
|
"keywords": [
|
|
54
58
|
"carlos",
|
|
@@ -96,6 +100,10 @@
|
|
|
96
100
|
"MIGRATION.md",
|
|
97
101
|
"CHANGELOG.md",
|
|
98
102
|
"LICENSE",
|
|
99
|
-
"AGENTS.md"
|
|
103
|
+
"AGENTS.md",
|
|
104
|
+
"INSTALL.md",
|
|
105
|
+
"RELEASE_NOTES.md",
|
|
106
|
+
"check-all.sh",
|
|
107
|
+
"smoke-test.js"
|
|
100
108
|
]
|
|
101
109
|
}
|
package/scripts/lang-audit.mjs
CHANGED
|
@@ -61,6 +61,13 @@ const ALLOWED_WORDS = new Set([
|
|
|
61
61
|
const MIN_WORDS = 5; // 连续 5 个以上英文词才判定为「英文叙述」
|
|
62
62
|
const MIN_COMMIT_WORDS = 3; // 提交信息阈值低一点(正文段落更短)
|
|
63
63
|
|
|
64
|
+
// 标准署名 trailer(机器可读的归属标记)豁免中文判定。
|
|
65
|
+
//
|
|
66
|
+
// 理由:这些行是「Token: value」形式的归属信息(谁协助、谁共同署名、谁批准),
|
|
67
|
+
// 不是英文叙述 —— 它们本来就不该写成中文,硬译反而会让工具解析不出来。
|
|
68
|
+
// 豁免范围**只限这三个词**,其他英文行照常判定。
|
|
69
|
+
const TRAILER_RE = /^(Assisted-by|Co-authored-by|Signed-off-by):/i;
|
|
70
|
+
|
|
64
71
|
// 判定规则:**一行里只要有中文字符就算合规**(标识符、报错原文、引用的英文术语
|
|
65
72
|
// 嵌在中文句子里是正常的);只有**整行没有中文**、且英文词达到阈值时才算违规。
|
|
66
73
|
// 之前的写法用「英文词数」直接判,会把
|
|
@@ -112,6 +119,7 @@ try {
|
|
|
112
119
|
if (inCode) continue;
|
|
113
120
|
const t = line.trim();
|
|
114
121
|
if (!t) continue;
|
|
122
|
+
if (TRAILER_RE.test(t)) continue;
|
|
115
123
|
if (!isEnglishNarration(t, MIN_COMMIT_WORDS)) continue;
|
|
116
124
|
report(`提交 ${sha.slice(0, 7)}`, t);
|
|
117
125
|
commitProblems++;
|
|
@@ -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
|
+
}
|
package/src/dispatch.js
CHANGED
|
@@ -7,19 +7,77 @@ import { RUNS_DIR, sanitizeId } from "./state.js";
|
|
|
7
7
|
|
|
8
8
|
export const MAX_DISPATCH = 5;
|
|
9
9
|
|
|
10
|
+
// 通用设计基线(坏味道清单)—— Standards 轴的第二层基线。
|
|
11
|
+
//
|
|
12
|
+
// 出处与边界(重要,不要夸大):
|
|
13
|
+
// · 本表由 Carlos 项目自维护,**术语对齐** Fowler et al.《Refactoring:
|
|
14
|
+
// Improving the Design of Existing Code》第二版第 3 章「Code Smells」;
|
|
15
|
+
// · 但它**不是原书全表**,也不声称逐条等同原书 —— 原书两版条目数不同,
|
|
16
|
+
// 市面上流传的「Fowler 12 种坏味道」是二手博客的说法、不是书里的口径。
|
|
17
|
+
// 把一个无法核实的数字写进审计权威,subagent 就会拿着错的基准去判定。
|
|
18
|
+
// · 显式化清单的价值不在「权威」,在**可枚举、可测试、口径一致**:
|
|
19
|
+
// 判定不再依赖模型记性,测试也能断言基线条目一条都没被静默删掉。
|
|
20
|
+
export const SMELL_BASELINE = [
|
|
21
|
+
{ name: "Duplicated Code", desc: "同一段逻辑重复出现,改一处漏一处" },
|
|
22
|
+
{ name: "Long Method", desc: "函数承担过多职责,应拆分" },
|
|
23
|
+
{ name: "Long Parameter List", desc: "参数过多,应封装成对象" },
|
|
24
|
+
{ name: "Large Class", desc: "类承担过多职责" },
|
|
25
|
+
{ name: "Data Clumps", desc: "同一组字段/参数反复成组出现" },
|
|
26
|
+
{ name: "Primitive Obsession", desc: "用基本类型代替领域对象" },
|
|
27
|
+
{ name: "Feature Envy", desc: "方法比宿主对象更依赖别的对象的数据" },
|
|
28
|
+
{ name: "Message Chains", desc: "过长的链式调用(a.getB().getC().getD())" },
|
|
29
|
+
{ name: "Middle Man", desc: "类/方法只做转发,自己没有职责" },
|
|
30
|
+
{ name: "Divergent Change", desc: "一个类因多种不相关的原因被修改" },
|
|
31
|
+
{ name: "Shotgun Surgery", desc: "一处逻辑改动要同步改多个文件" },
|
|
32
|
+
{ name: "Speculative Generality", desc: "为尚不存在的需求预留扩展点" },
|
|
33
|
+
{ name: "Temporary Field", desc: "字段只在某段流程内有值" },
|
|
34
|
+
{ name: "Refused Bequest", desc: "子类继承父类却拒绝/覆盖其大部分行为" },
|
|
35
|
+
{ name: "Data Class", desc: "只有数据没有行为" },
|
|
36
|
+
{ name: "Lazy Class", desc: "只有方法没有实质职责" },
|
|
37
|
+
{ name: "Comments", desc: "用注释掩盖代码本该表达的东西" },
|
|
38
|
+
{ name: "Dead Code", desc: "永不可达的废弃代码" },
|
|
39
|
+
];
|
|
40
|
+
|
|
41
|
+
// 渲染审计 checklist 段:条目逐条编号,便于 subagent 按项检查、便于测试逐条断言。
|
|
42
|
+
function renderChecklist(checklist) {
|
|
43
|
+
const items = (checklist.items || [])
|
|
44
|
+
.map((it, i) => `${i + 1}. ${it.name} — ${it.desc}`)
|
|
45
|
+
.join("\n");
|
|
46
|
+
return `${checklist.title}(逐条检查,命中即给 file:line 证据):\n${items}\n注:${checklist.note}`;
|
|
47
|
+
}
|
|
48
|
+
|
|
10
49
|
// Dispatcher 配置:双轴审查 prompt 配置表。
|
|
11
50
|
// 新增轴只改这里,不动 buildContractPrompt 的函数体(避免分支膨胀)。
|
|
51
|
+
//
|
|
52
|
+
// 判定词表必须与 flow_audit_submit 的 enum(PASS / WARN / FAIL)对齐:
|
|
53
|
+
// 词表不一致时 subagent 会输出「通过/违规」这类自然语言,由主 Agent 手工映射,
|
|
54
|
+
// 而 FAIL(硬拦)与 WARN(不拦)的差别就在这一步 —— 映射错了硬拦就失效了。
|
|
12
55
|
const AXIS_PROMPTS = {
|
|
13
56
|
standards: {
|
|
14
57
|
objective: "审计:仓库代码规范与坏味道",
|
|
15
|
-
format: "
|
|
16
|
-
guidance:
|
|
58
|
+
format: "判定(PASS / WARN / FAIL) / 规范依据 / file:line 证据 / 是否硬违规",
|
|
59
|
+
guidance:
|
|
60
|
+
"两层基线同时执行:" +
|
|
61
|
+
"① 仓库规范层:先在目标仓库内发现规范文件(eslint 配置、prettier 配置、editorconfig、" +
|
|
62
|
+
"CONTRIBUTING.md、AGENTS.md、tsconfig 的 lint 选项、CI 里的 lint/test 命令)," +
|
|
63
|
+
"把发现的规范文件清单写进报告,再逐条对照;" +
|
|
64
|
+
"② 通用设计层:按下面的「坏味道基线」逐条检查。" +
|
|
65
|
+
"只读取证 git diff,不轻信 executor 自述,每条命中都要给 file:line 证据。" +
|
|
66
|
+
"判定口径:违反仓库明文规范判 FAIL;命中通用设计基线判 WARN。",
|
|
17
67
|
boundaries: "零文件改动,只读取证",
|
|
68
|
+
checklist: {
|
|
69
|
+
title: "坏味道基线",
|
|
70
|
+
items: SMELL_BASELINE,
|
|
71
|
+
note: "本表由 Carlos 自维护,术语对齐 Fowler《Refactoring》第二版第 3 章 Code Smells,非原书全表",
|
|
72
|
+
},
|
|
18
73
|
},
|
|
19
74
|
spec: {
|
|
20
75
|
objective: "审计:任务卡验收标准忠实度",
|
|
21
|
-
format: "
|
|
22
|
-
guidance:
|
|
76
|
+
format: "判定(PASS / WARN / FAIL) / 验收标准逐条核对结果 / 越界改动(file:line)",
|
|
77
|
+
guidance:
|
|
78
|
+
"对照任务卡 goal/acceptance/scope,逐条核对卡上的验收标准,跑 flow_check_scope 校验越界," +
|
|
79
|
+
"独立跑验证命令取证。判定口径:验收标准全部满足且无越界判 PASS;未实现验收或越界改动判 FAIL;" +
|
|
80
|
+
"仅部分存疑判 WARN。",
|
|
23
81
|
boundaries: "零文件改动,只读取证",
|
|
24
82
|
},
|
|
25
83
|
};
|
|
@@ -69,6 +127,15 @@ export function buildContractPrompt(role, card, extra, axis) {
|
|
|
69
127
|
}
|
|
70
128
|
|
|
71
129
|
let prompt = [objective, outputFormat, toolGuidance, taskBoundaries].join("\n");
|
|
130
|
+
|
|
131
|
+
// 轴模式:附上该轴的基线清单(Standards 轴的坏味道基线)。
|
|
132
|
+
// 清单必须内联进 prompt —— 审计 subagent 跑在**目标仓库**里,
|
|
133
|
+
// 读不到 carlos-flow 包内的文件,写成 docs/xxx.md 让它去读等于没写。
|
|
134
|
+
const axisCfg = axis ? AXIS_PROMPTS[axis] : null;
|
|
135
|
+
if (axisCfg && axisCfg.checklist) {
|
|
136
|
+
prompt += "\n\n" + renderChecklist(axisCfg.checklist);
|
|
137
|
+
}
|
|
138
|
+
|
|
72
139
|
if (extra && String(extra) !== "") {
|
|
73
140
|
prompt += "\n\n" + String(extra); // 原样附在末尾
|
|
74
141
|
}
|
package/src/index.js
CHANGED
|
@@ -69,6 +69,39 @@ const verifyPassed = (state) => {
|
|
|
69
69
|
return typeof lv.cmd === "string" && lv.cmd.trim() === want;
|
|
70
70
|
};
|
|
71
71
|
|
|
72
|
+
// WARN 汇总条数上限:防止 WARN 通胀把返回值灌成噪音,主 Agent 反而开始忽略。
|
|
73
|
+
const WARN_FINDINGS_LIMIT = 20;
|
|
74
|
+
|
|
75
|
+
// 汇总两轴的 WARN 结论(坏味道等 judgement call)。
|
|
76
|
+
//
|
|
77
|
+
// 为什么即时派生、而不是再存一份进 state:
|
|
78
|
+
// WARN 数据本来就在 state.audit_axes 里;再落一份进 state 就得 bump
|
|
79
|
+
// schemaVersion 并写迁移分支,而派生是零迁移、零漂移的。
|
|
80
|
+
//
|
|
81
|
+
// 口径与双轴门禁完全一致(复用 axisOk 的 card_ts 绑定):
|
|
82
|
+
// 只认 card_ts 与当前卡一致的轴结论 —— 换卡后旧卡的 WARN 必须失效,
|
|
83
|
+
// 否则「门禁判未齐、汇总却报 WARN」两种口径会打架。
|
|
84
|
+
//
|
|
85
|
+
// 附带回答 DIRECTION/LOCAL 路径:返工意见恰恰最需要坏味道清单,
|
|
86
|
+
// 所以三种裁定都带这份汇总。
|
|
87
|
+
function collectAxisWarnings(state) {
|
|
88
|
+
const ax = state && state.audit_axes;
|
|
89
|
+
if (!ax || typeof ax !== "object") return [];
|
|
90
|
+
const out = [];
|
|
91
|
+
for (const name of ["standards", "spec"]) {
|
|
92
|
+
const a = ax[name];
|
|
93
|
+
if (!a || !a.verdict) continue;
|
|
94
|
+
if (a.card_ts !== state.card_ts) continue; // 旧卡结论不算数
|
|
95
|
+
if (a.verdict !== "WARN") continue;
|
|
96
|
+
const findings = Array.isArray(a.findings) ? a.findings : [];
|
|
97
|
+
for (const f of findings) {
|
|
98
|
+
if (out.length >= WARN_FINDINGS_LIMIT) return out;
|
|
99
|
+
out.push({ axis: name, finding: String(f) });
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
return out;
|
|
103
|
+
}
|
|
104
|
+
|
|
72
105
|
const TOOLS = [
|
|
73
106
|
// 1 -----------------------------------------------------------------------
|
|
74
107
|
{
|
|
@@ -533,6 +566,18 @@ const TOOLS = [
|
|
|
533
566
|
};
|
|
534
567
|
state.audit_axes_ts = Date.now();
|
|
535
568
|
saveState(sid, state);
|
|
569
|
+
|
|
570
|
+
// 审计留痕:轴结论此前只落在 state 里 —— 可被覆盖、不可追溯。
|
|
571
|
+
// 这里补一条审计事件,回答「这条结论是谁在什么时候提交的」。
|
|
572
|
+
// 只记结论与证据摘要,不整段拷贝 evidence(验证输出可能很长)。
|
|
573
|
+
audit("decision", sid, {
|
|
574
|
+
kind: "audit_axis_submitted",
|
|
575
|
+
axis: args.axis,
|
|
576
|
+
verdict: args.verdict,
|
|
577
|
+
findings: Array.isArray(args.findings) ? args.findings : [],
|
|
578
|
+
has_evidence: typeof args.evidence === "string" && args.evidence.trim() !== "",
|
|
579
|
+
card_ts: state.card_ts,
|
|
580
|
+
});
|
|
536
581
|
const stored = [state.audit_axes.standards, state.audit_axes.spec].filter(Boolean).length;
|
|
537
582
|
return ok({ ok: true, axis: args.axis, stored_axes_count: stored });
|
|
538
583
|
} catch (e) { return fail(String(e)); }
|
|
@@ -788,13 +833,19 @@ const TOOLS = [
|
|
|
788
833
|
|
|
789
834
|
audit("resolution", sessionId, { kind: "verdict", verdict, notes: a.notes, role: a.role });
|
|
790
835
|
|
|
836
|
+
const warns = collectAxisWarnings(state);
|
|
791
837
|
const result = {
|
|
792
838
|
ok: true,
|
|
793
839
|
verdict,
|
|
794
840
|
completed_ok: state.completed_ok,
|
|
795
841
|
notes: a.notes,
|
|
796
842
|
verdict_role: state.verdict_role,
|
|
843
|
+
// WARN 汇总:两轴里判 WARN(坏味道等 judgement call)的结论。
|
|
844
|
+
// 以前 WARN 只躺在 state.audit_axes 里,主 Agent 不主动读就看不到,
|
|
845
|
+
// 「带坏味道通过」在汇报里等于被吞掉 —— 现在随裁定一起返回。
|
|
846
|
+
warn_count: warns.length,
|
|
797
847
|
};
|
|
848
|
+
if (warns.length) result.warn_findings = warns;
|
|
798
849
|
if (findings.length) result.findings = findings;
|
|
799
850
|
return ok(result);
|
|
800
851
|
} catch (e) {
|
|
@@ -820,6 +871,7 @@ const TOOLS = [
|
|
|
820
871
|
const a = args || {};
|
|
821
872
|
const sessionId = a.sessionId || "unknown";
|
|
822
873
|
const state = loadState(sessionId);
|
|
874
|
+
const warns = collectAxisWarnings(state);
|
|
823
875
|
|
|
824
876
|
const result = {
|
|
825
877
|
sessionId,
|
|
@@ -852,7 +904,10 @@ const TOOLS = [
|
|
|
852
904
|
return axisOk("standards") && axisOk("spec") &&
|
|
853
905
|
ax.standards.verdict !== "FAIL" && ax.spec.verdict !== "FAIL";
|
|
854
906
|
})(),
|
|
907
|
+
// WARN 汇总(与 flow_verdict 同一份派生口径):只读镜像,供事后复查。
|
|
908
|
+
warn_count: warns.length,
|
|
855
909
|
};
|
|
910
|
+
if (warns.length) result.warn_findings = warns;
|
|
856
911
|
if (state.card && !state.verdict) result.unreviewed = true;
|
|
857
912
|
return ok(result);
|
|
858
913
|
} catch (e) {
|