carlos-flow 2.9.0 → 2.11.0
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 +86 -0
- package/README.en.md +5 -3
- package/README.md +5 -3
- package/README.zh.md +5 -3
- package/TRIGGER_GUIDE.md +2 -2
- package/ghost.json +1 -1
- package/package.json +3 -2
- package/scripts/lang-audit.mjs +8 -0
- package/src/dispatch.js +71 -4
- package/src/index.js +68 -1
- package/src/protocol.js +11 -2
- package/src/state.js +15 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,92 @@
|
|
|
5
5
|
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
+
## [2.11.0] - 2026-11-12 — 双轴审查补缺口:坏味道基线内置 + WARN 自动汇总
|
|
9
|
+
|
|
10
|
+
> 本版把「未做项」里两条低优先级增强做实,方案经三轴内审(Standards / Spec / 风险)评审后调整:
|
|
11
|
+
> 清单不硬编码「Fowler 12 种」这类无法核实的数字,改为显式可枚举的自维护基线;
|
|
12
|
+
> WARN 汇总采用「即时派生、零 state 变更」的实现,不引入 schema 迁移。
|
|
13
|
+
|
|
14
|
+
### ✨ 新增 | Added
|
|
15
|
+
|
|
16
|
+
- **坏味道基线内置进 Standards 轴 prompt**(`src/dispatch.js` 的 `SMELL_BASELINE`,18 条)。
|
|
17
|
+
- 以前 prompt 只写了一句「对照仓库规范文件 + Fowler 坏味道基线」,基线内容没给,
|
|
18
|
+
判定质量全看模型自己的记性 —— 不同上下文下结果会漂移。
|
|
19
|
+
- 现在基线**逐条编号内联进 prompt**(审计 subagent 跑在目标仓库,读不到包内文件,
|
|
20
|
+
写成 `docs/xxx.md` 让它去读等于没写)。
|
|
21
|
+
- 出处如实标注:术语对齐 Fowler《Refactoring》第二版第 3 章 Code Smells,
|
|
22
|
+
**但本表由 Carlos 自维护、非原书全表** —— 流传的「Fowler 12 种坏味道」是二手博客
|
|
23
|
+
的说法,不是书里的口径,写进审计权威会把事实错误固化下来。
|
|
24
|
+
- **WARN 自动汇总**(`flow_verdict` / `flow_status` 返回 `warn_count` + `warn_findings`)。
|
|
25
|
+
- 以前 WARN 只躺在 `state.audit_axes` 里,主 Agent 不主动读就看不到,
|
|
26
|
+
「带坏味道通过」在汇报里等于被吞掉。
|
|
27
|
+
- 口径与双轴门禁完全一致:**只收 `card_ts` 与当前卡一致的轴结论**,换卡后旧 WARN 自动失效。
|
|
28
|
+
- 三种裁定(PASS / DIRECTION / LOCAL)都带这份汇总 —— 返工意见恰恰最需要坏味道清单。
|
|
29
|
+
- **零 state 变更**:WARN 数据本就在 `audit_axes` 里,即时派生即可,
|
|
30
|
+
不 bump `schemaVersion`、不写迁移分支。
|
|
31
|
+
- **`test/audit-baseline.mjs`** —— 审计基线守护测试(10 条断言):基线条目齐全、条目名唯一、
|
|
32
|
+
规模下限、每条都有中文说明、判定词表与 `flow_audit_submit` 的 enum 对齐、
|
|
33
|
+
基线不泄漏进 executor 合同、prompt 长度上限、出处标注。
|
|
34
|
+
|
|
35
|
+
### 🐛 修复 | Fixed
|
|
36
|
+
|
|
37
|
+
- **两轴判定词表与 `flow_audit_submit` 的 enum 错位**:prompt 要求输出「通过/违规/坏味道」,
|
|
38
|
+
而 enum 只有 `PASS / WARN / FAIL`。词表不一致时 subagent 输出自然语言、由主 Agent 手工映射,
|
|
39
|
+
而 **FAIL(硬拦)与 WARN(不拦)的差别就在这一步** —— 映射错了硬拦就失效。
|
|
40
|
+
两轴的 `format` 统一改成 `PASS / WARN / FAIL`,并写明各自判定口径。
|
|
41
|
+
|
|
42
|
+
### 🔒 变更 | Changed
|
|
43
|
+
|
|
44
|
+
- **`flow_audit_submit` 写审计事件**(`kind: "audit_axis_submitted"`):轴结论此前只落在
|
|
45
|
+
`state` 里 —— 可被覆盖、不可追溯。现在审计流水能回答「谁在什么时候提交了什么结论」。
|
|
46
|
+
|
|
47
|
+
### 🔬 验证 | Verification
|
|
48
|
+
|
|
49
|
+
- e2e **85/0**(新增 29a–29f 六条:WARN 汇总随裁定返回 / `flow_status` 镜像 /
|
|
50
|
+
两轴全 PASS 不凭空产生 / 换卡后旧 WARN 失效 / DIRECTION 同样带汇总 / 轴结论进审计流水);
|
|
51
|
+
baseline 10/0;p0 22/0;protocol-consistency 5/0;trigger 29/0;concurrency 3/0;
|
|
52
|
+
acceptance 13/0;smoke 通过。
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## [2.10.0] - 2026-11-12 — 合并 _carlos-flow-remote 分支:verdict_role 落盘 + 协议字段漂移修复
|
|
57
|
+
|
|
58
|
+
> 本版把 `_carlos-flow-remote` 分支上**发布线缺失**的独有内容合并进来(该分支后被
|
|
59
|
+
> v2.8.0/v2.9.0 取代,其角色门禁实现已被更强的 claimed_role 口径覆盖,故不整支合入)。
|
|
60
|
+
|
|
61
|
+
### ✨ 新增 | Added
|
|
62
|
+
|
|
63
|
+
- **`verdict_role` 字段** —— 持久记录「本条裁定是谁落的」。
|
|
64
|
+
- 与 `claimed_role` 的区别:后者是「会话最近 claim 的角色」(可能已过期),
|
|
65
|
+
前者是「实际写下这条裁定时传进来的 role」,直接回答「这条 PASS 是谁落的」。
|
|
66
|
+
- `flow_verdict` 返回值、`flow_status` 均可读;未显式声明 role 时落 `null`(不谎报)。
|
|
67
|
+
- **`test/protocol-consistency.mjs`** —— 协议一致性守护(5 条断言):
|
|
68
|
+
字段集合、字段默认值、ERROR_LAYERS 含「门禁拒绝」层、实现方式未回退为手写常量。
|
|
69
|
+
|
|
70
|
+
### 🐛 修复 | Fixed
|
|
71
|
+
|
|
72
|
+
- **`protocol.js` 的 `STATE_FIELDS` 与状态结构漂移**:原先是**手写常量**,已漏掉
|
|
73
|
+
**9 个字段**(`claimed` / `claimed_role` / `activation_pending` / `activation_activated` /
|
|
74
|
+
`dispatch_baseline` / `last_falsify` / `audit_axes` / `audit_axes_ts` / `schemaVersion`)。
|
|
75
|
+
Agent 通过 `flow_protocol` 读到过期的字段表,会按错误的字段名做决策。
|
|
76
|
+
改为从 `defaultState()` 生成,并加测试钉死。
|
|
77
|
+
|
|
78
|
+
### 🔒 变更 | Changed
|
|
79
|
+
|
|
80
|
+
- **`ERROR_LAYERS` 新增「门禁拒绝(非错误)」层**:明确告知 Agent 闸门拦不是工具坏了,
|
|
81
|
+
应按错误信息里的下一步修正后重试,**不要重试同一调用**。
|
|
82
|
+
- **状态结构版本 v3 → v4**:`migrate()` 新增 v3→v4 迁移,补全旧状态的 `verdict_role`。
|
|
83
|
+
|
|
84
|
+
### 🔬 验证 | Verification
|
|
85
|
+
|
|
86
|
+
- e2e **79/0**(新增 28a–28c 三条 `verdict_role` 用例);p0 22/0;scope 10/0;
|
|
87
|
+
package-e2e 19/0;audit 23/0;bridge 6/0;trigger 29/0;concurrency 3/0;
|
|
88
|
+
acceptance 13/0;lang 12/0;smoke 通过。
|
|
89
|
+
- `check:full` / `check:parity` / `check:lang` / `check:anchors` 17/17 / `check:readme` /
|
|
90
|
+
`check:params` / `check:claims` / `check:no-dead-handler` 全部通过。
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
8
94
|
## [2.9.0] - 2026-11-12 — 双轴审查门禁:PASS 裁定前必须收齐 Standards / Spec 两轴证据
|
|
9
95
|
|
|
10
96
|
### ✨ 新增 | Added
|
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 |
|
|
297
|
-
| `flow_status` | Query gate state | Exposes `activation_pending` / `verify_passed` / `audit_axes` / `axes_ready` |
|
|
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 |
|
|
303
|
-
| `flow_status` | 查询门禁状态 | 暴露 `activation_pending` / `verify_passed` / `audit_axes` / `axes_ready` |
|
|
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 |
|
|
303
|
-
| `flow_status` | 查询门禁状态 | 暴露 `activation_pending` / `verify_passed` / `audit_axes` / `axes_ready` |
|
|
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/TRIGGER_GUIDE.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Carlos Flow 智能触发引擎使用指南
|
|
2
2
|
|
|
3
|
-
> **版本**: v2.
|
|
3
|
+
> **版本**: v2.11.0
|
|
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.0
|
|
783
783
|
**更新日期**: 2026-11-12
|
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.0",
|
|
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.0",
|
|
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",
|
|
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",
|
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++;
|
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)); }
|
|
@@ -782,11 +827,25 @@ const TOOLS = [
|
|
|
782
827
|
state.verdict = verdict;
|
|
783
828
|
state.completed_ok = verdict === "PASS";
|
|
784
829
|
state.verdict_ts = Date.now();
|
|
830
|
+
// 落盘裁定者角色:审计链据此回溯「这条 PASS 是谁落的」。
|
|
831
|
+
state.verdict_role = a.role === undefined ? null : a.role;
|
|
785
832
|
saveState(sessionId, state);
|
|
786
833
|
|
|
787
834
|
audit("resolution", sessionId, { kind: "verdict", verdict, notes: a.notes, role: a.role });
|
|
788
835
|
|
|
789
|
-
const
|
|
836
|
+
const warns = collectAxisWarnings(state);
|
|
837
|
+
const result = {
|
|
838
|
+
ok: true,
|
|
839
|
+
verdict,
|
|
840
|
+
completed_ok: state.completed_ok,
|
|
841
|
+
notes: a.notes,
|
|
842
|
+
verdict_role: state.verdict_role,
|
|
843
|
+
// WARN 汇总:两轴里判 WARN(坏味道等 judgement call)的结论。
|
|
844
|
+
// 以前 WARN 只躺在 state.audit_axes 里,主 Agent 不主动读就看不到,
|
|
845
|
+
// 「带坏味道通过」在汇报里等于被吞掉 —— 现在随裁定一起返回。
|
|
846
|
+
warn_count: warns.length,
|
|
847
|
+
};
|
|
848
|
+
if (warns.length) result.warn_findings = warns;
|
|
790
849
|
if (findings.length) result.findings = findings;
|
|
791
850
|
return ok(result);
|
|
792
851
|
} catch (e) {
|
|
@@ -812,6 +871,7 @@ const TOOLS = [
|
|
|
812
871
|
const a = args || {};
|
|
813
872
|
const sessionId = a.sessionId || "unknown";
|
|
814
873
|
const state = loadState(sessionId);
|
|
874
|
+
const warns = collectAxisWarnings(state);
|
|
815
875
|
|
|
816
876
|
const result = {
|
|
817
877
|
sessionId,
|
|
@@ -820,6 +880,10 @@ const TOOLS = [
|
|
|
820
880
|
dispatch_count: state.dispatch_count,
|
|
821
881
|
max_dispatch: MAX_DISPATCH,
|
|
822
882
|
verdict: state.verdict,
|
|
883
|
+
// 本条裁定是谁落的("auditor" | "executor" | null)。
|
|
884
|
+
// 与 claimed_role 不同:后者是「会话最近 claim 的角色」,可能已过期;
|
|
885
|
+
// 这个字段直接回答「这条 PASS 是谁落的」。
|
|
886
|
+
verdict_role: state.verdict_role === undefined ? null : state.verdict_role,
|
|
823
887
|
verified: !!state.verdict,
|
|
824
888
|
// verify_passed:真实验证是否通过(last_verify.ok===true 且命令与当前卡片一致)。
|
|
825
889
|
// 注意 verified 只表示「是否已有裁定」,不代表验证通过——两者语义不同,不可混用。
|
|
@@ -840,7 +904,10 @@ const TOOLS = [
|
|
|
840
904
|
return axisOk("standards") && axisOk("spec") &&
|
|
841
905
|
ax.standards.verdict !== "FAIL" && ax.spec.verdict !== "FAIL";
|
|
842
906
|
})(),
|
|
907
|
+
// WARN 汇总(与 flow_verdict 同一份派生口径):只读镜像,供事后复查。
|
|
908
|
+
warn_count: warns.length,
|
|
843
909
|
};
|
|
910
|
+
if (warns.length) result.warn_findings = warns;
|
|
844
911
|
if (state.card && !state.verdict) result.unreviewed = true;
|
|
845
912
|
return ok(result);
|
|
846
913
|
} catch (e) {
|
package/src/protocol.js
CHANGED
|
@@ -1,6 +1,12 @@
|
|
|
1
1
|
// Carlos Flow 协议 — 路由档位 / 四段合同 / 报告规格 / 错误分层 / 状态字段的唯一真源。
|
|
2
2
|
// 被协调器(coordinator)与各角色 Agent 共同引用。
|
|
3
3
|
|
|
4
|
+
// 状态字段从 defaultState() 生成,而不是手写常量 ——
|
|
5
|
+
// 手写副本会漂移(历史上就漏过 claimed / claimed_role / activation_* 等 9 个字段),
|
|
6
|
+
// 而协议是 Agent 运行时读取的权威依据,漂移会让 Agent 按错误的字段名做决策。
|
|
7
|
+
// 代价:protocol.js 依赖 state.js(纯数据模块,无副作用,无循环依赖)。
|
|
8
|
+
import { defaultState } from "./state.js";
|
|
9
|
+
|
|
4
10
|
export const PROTOCOL = {
|
|
5
11
|
ROUTE_TABLE: `| 档 | 场景 | 动作 |
|
|
6
12
|
|---|---|---|
|
|
@@ -23,9 +29,12 @@ auditor 报告 ≤200 字,五段式:裁定 / 失败类型 / scope 标注 /
|
|
|
23
29
|
|---|---|---|
|
|
24
30
|
| 基础设施故障 | 网络抖动、模型不可用、配额耗尽 | 静默降级或改用 Explore / 自读只读验证,不把原始错误喂回 |
|
|
25
31
|
| Agent 故障 | 工具名错、参数错 | 把错误喂回并附恢复指引 |
|
|
26
|
-
| 接管 | 同一子 Agent 连续 2 次失败 | 接管 = 只读验证,不写文件
|
|
32
|
+
| 接管 | 同一子 Agent 连续 2 次失败 | 接管 = 只读验证,不写文件 |
|
|
33
|
+
| 门禁拒绝(非错误) | 闸门拦下当前动作(如 PASS 裁定角色不对、验证未跑通、验证已过期、scope 越界、双轴未齐) | **这不是工具坏了**,是门禁在正常工作。按错误信息里的下一步修正后重试:补齐缺失动作(如先 flow_claim role=auditor)再重试。**不要重试同一调用** |`,
|
|
27
34
|
|
|
28
|
-
|
|
35
|
+
// 从 defaultState() 生成,保证与状态结构永远一致(漂移防护)。
|
|
36
|
+
// 测试 test/protocol-consistency.mjs 会逐字段比对,手工改回常量会红。
|
|
37
|
+
STATE_FIELDS: JSON.stringify(defaultState()),
|
|
29
38
|
|
|
30
39
|
AUDIT_EVENTS: `["run","finding","decision","resolution"]`,
|
|
31
40
|
|
package/src/state.js
CHANGED
|
@@ -93,7 +93,7 @@ export function sanitizeId(s) {
|
|
|
93
93
|
|
|
94
94
|
// 当前状态文件结构版本号。
|
|
95
95
|
// 改动 defaultState() 的**字段结构**时,必须 +1 并在 migrate() 里加一条迁移。
|
|
96
|
-
export const CURRENT_SCHEMA_VERSION =
|
|
96
|
+
export const CURRENT_SCHEMA_VERSION = 4;
|
|
97
97
|
|
|
98
98
|
/**
|
|
99
99
|
* 迁移旧版本的状态文件。
|
|
@@ -111,6 +111,9 @@ export const CURRENT_SCHEMA_VERSION = 3;
|
|
|
111
111
|
* v2 → v3:新增 audit_axes / audit_axes_ts(双轴审查证据)。
|
|
112
112
|
* · 旧状态没有这两个字段 → 补默认结构(两轴均为 null = 尚未审查,裁定会拒绝 PASS)
|
|
113
113
|
* · audit_axes 存在但结构不全时也在此补齐,避免读到半初始化对象
|
|
114
|
+
*
|
|
115
|
+
* v3 → v4:新增 verdict_role(本条 PASS 是谁落的)。
|
|
116
|
+
* · 旧状态没有这个字段 → 补 null(仅影响可观测性,不影响门禁判定)
|
|
114
117
|
*/
|
|
115
118
|
export function migrate(parsed) {
|
|
116
119
|
if (!parsed || typeof parsed !== "object") return parsed;
|
|
@@ -146,6 +149,12 @@ export function migrate(parsed) {
|
|
|
146
149
|
v = 3;
|
|
147
150
|
}
|
|
148
151
|
|
|
152
|
+
if (v < 4) {
|
|
153
|
+
// v3 → v4
|
|
154
|
+
if (out.verdict_role === undefined) out.verdict_role = null;
|
|
155
|
+
v = 4;
|
|
156
|
+
}
|
|
157
|
+
|
|
149
158
|
out.schemaVersion = CURRENT_SCHEMA_VERSION;
|
|
150
159
|
return out;
|
|
151
160
|
}
|
|
@@ -201,6 +210,11 @@ export function defaultState() {
|
|
|
201
210
|
audit_axes: { standards: null, spec: null },
|
|
202
211
|
// 两轴最后提交时间(审计链留痕用;不参与冒充校验,校验看 card_ts)。
|
|
203
212
|
audit_axes_ts: 0,
|
|
213
|
+
// 本条裁定是谁落的("auditor" | "executor" | null)。
|
|
214
|
+
// 与 claimed_role 的区别:claimed_role 是「会话最近 claim 的角色」(可能已过期),
|
|
215
|
+
// verdict_role 是「实际写下这条裁定时传进来的 role」,直接回答「这条 PASS 是谁落的」。
|
|
216
|
+
// 审计流水里也有 role,但那是日志;这是状态层的持久记录,可用 flow_status 直接查。
|
|
217
|
+
verdict_role: null,
|
|
204
218
|
};
|
|
205
219
|
}
|
|
206
220
|
|