carlos-flow 2.8.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 +121 -0
- package/README.en.md +12 -5
- package/README.md +11 -4
- package/README.zh.md +11 -4
- package/TRIGGER_GUIDE.md +3 -3
- package/ghost.json +72 -1
- package/package.json +3 -2
- package/scripts/check-no-dead-handler.mjs +2 -2
- package/scripts/lang-audit.mjs +8 -0
- package/src/dispatch.js +116 -19
- package/src/index.js +212 -2
- package/src/protocol.js +11 -2
- package/src/state.js +43 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,127 @@
|
|
|
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
|
+
|
|
94
|
+
## [2.9.0] - 2026-11-12 — 双轴审查门禁:PASS 裁定前必须收齐 Standards / Spec 两轴证据
|
|
95
|
+
|
|
96
|
+
### ✨ 新增 | Added
|
|
97
|
+
|
|
98
|
+
- **`flow_audit_axes`** —— 派发两个并行审计 subagent(Standards 轴 / Spec 轴),各生成一段中文审计合同 prompt。
|
|
99
|
+
- **`flow_audit_submit`** —— 保存某一审计轴的结论与证据,按 `card_ts` 绑定当前卡(同轴可重复提交、后者覆盖)。
|
|
100
|
+
- **`flow_audit_guard`** —— 两轴门禁自查,与 `flow_verdict` 内的门禁同口径;给主 Agent 一个「落 PASS 前先自查」的显式工具。
|
|
101
|
+
- **`flow_status` 暴露双轴状态** —— 新增 `audit_axes` / `audit_axes_ts` / `axes_ready`,主 Agent 落 PASS 前可读。
|
|
102
|
+
|
|
103
|
+
### 🔒 变更 | Changed
|
|
104
|
+
|
|
105
|
+
- **`flow_verdict` 新增双轴门禁**(防假闭环之六):落 `PASS` 前必须两轴证据齐全且无轴 FAIL。
|
|
106
|
+
- **位置**:在负对照门禁**之后**,是 PASS 落定前的最后一道。六道门各自独立、互不掩盖;
|
|
107
|
+
若前置会让「未验证 / 未派发 / 未做负对照」这些更基础的问题被双轴错误信息掩盖。
|
|
108
|
+
- **判定**:任一轴 FAIL 硬拦;WARN(坏味道等 judgement call)只标注不拦。
|
|
109
|
+
- **防冒充**:两轴证据均绑定 `card_ts`,旧卡的审查结果不能冒充新卡(也堵住「卡A的 standards + 卡B的 spec」跨卡拼接)。
|
|
110
|
+
- `DIRECTION` / `LOCAL` 不受限制(返工意见不构成完成)。
|
|
111
|
+
- **状态结构版本 v2 → v3**:`migrate()` 新增 v2→v3 迁移,补全旧状态的 `audit_axes` / `audit_axes_ts`。
|
|
112
|
+
|
|
113
|
+
### 🔧 实现 | Implementation
|
|
114
|
+
|
|
115
|
+
- `src/dispatch.js`:新增 `AXIS_PROMPTS` 配置表,`buildContractPrompt` 加第 4 参 `axis`(可缺省,旧调用不变);加新轴只改配置表,不动函数体。
|
|
116
|
+
- `src/state.js`:`defaultState()` 新增两字段;`migrate()` 加 v2→v3。
|
|
117
|
+
- `src/index.js`:新增 3 工具;`flow_verdict` 加门禁;`flow_status` 暴露双轴状态。
|
|
118
|
+
- `ghost.json`:工具清单 16 → 19,与服务端逐一对齐。
|
|
119
|
+
|
|
120
|
+
### 🔬 验证 | Verification
|
|
121
|
+
|
|
122
|
+
- 新增 11 条双轴专项用例(27a–27k):未齐拦截 / 单轴拦截 / 双轴 FAIL 对称拦截 / WARN 放行 / DIRECTION 兼容 / 旧卡防冒充 / guard 三种状态 / `flow_status` 暴露。
|
|
123
|
+
- 既有正向 PASS 用例全部补上双轴前置(e2e-carlos / package-e2e / scope-enforcement),负向用例不受影响。
|
|
124
|
+
- 主测试 **76/0** 通过(e2e);p0 22/0;scope-enforcement 10/0;package-e2e 19/0;trigger 29/0;concurrency 3/0;acceptance 13/0;lang 12/0;smoke 通过。
|
|
125
|
+
- `check:full` / `check:lang` / `check:anchors` / `check:parity` / `check:readme` 全部通过。
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
8
129
|
## [2.8.0] - 2026-11-08 — 角色门禁绑定会话 claimed_role + auditor 复核流程 + CI 修复
|
|
9
130
|
|
|
10
131
|
- flow_verdict PASS 现在必须由已 claim "auditor" 角色的会话落下(claimed_role 绑定会话 ID,而非调用方自述字符串)。
|
package/README.en.md
CHANGED
|
@@ -118,7 +118,7 @@ flowchart TB
|
|
|
118
118
|
Plugin["plugins/carlos-flow-trigger.js<br/>chat.message hook"]
|
|
119
119
|
end
|
|
120
120
|
|
|
121
|
-
subgraph Core["Core MCP Server (src/index.js) —
|
|
121
|
+
subgraph Core["Core MCP Server (src/index.js) — 19 tools"]
|
|
122
122
|
Protocol["flow_protocol"]
|
|
123
123
|
Submit["flow_submit_requirement"]
|
|
124
124
|
Dispatch["flow_claim / flow_dispatch"]
|
|
@@ -158,7 +158,7 @@ flowchart TB
|
|
|
158
158
|
|-------|----------|----------------|-------------------|
|
|
159
159
|
| **Host adapter** | `ghost.json` / `plugins/` / `templates/` | Discovery, launch, config, lifecycle | ⚠️ The **only** platform-specific layer |
|
|
160
160
|
| **Client** | `client/carlos.js` / `bridge/` | CLI, trigger check, Bridge daemon | Bridge is Cindy-only |
|
|
161
|
-
| **Protocol** | `src/index.js` |
|
|
161
|
+
| **Protocol** | `src/index.js` | 19 MCP tools + validation + gate semantics | ✅ Zero coupling, pure standard MCP |
|
|
162
162
|
| **Engine** | `src/trigger.js` / `src/card.js` / `src/state.js` | Trigger scoring, card validation, state/audit | ✅ Zero coupling, pure JS, no deps |
|
|
163
163
|
| **Persistence** | `~/.carlos-flow/` | State, audit chain, snapshots, trigger history | ✅ Cross-platform path convention |
|
|
164
164
|
|
|
@@ -277,7 +277,7 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
|
|
|
277
277
|
|
|
278
278
|
---
|
|
279
279
|
|
|
280
|
-
## 🔧 MCP Tool Reference (
|
|
280
|
+
## 🔧 MCP Tool Reference (19 tools)
|
|
281
281
|
|
|
282
282
|
| Tool | Purpose | Key constraint |
|
|
283
283
|
|------|---------|----------------|
|
|
@@ -286,18 +286,25 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
|
|
|
286
286
|
| `flow_submit_requirement` | Submit / replace the task card | Required fields enforced per risk tier; fake fillers rejected |
|
|
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
|
+
| `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; writes a traceable audit event |
|
|
291
|
+
| `flow_audit_guard` | **Dual-axis gate self-check** | Same criteria as the gate inside `flow_verdict` |
|
|
289
292
|
| `flow_save_result` | Save a sub-agent's result | — |
|
|
290
293
|
| `flow_run_verify` | **Really execute** `verify.cmd` | Returns exitCode / stdout / stderr + `output_hash` |
|
|
291
294
|
| `flow_falsify` | **Negative control**: run `verify.cmd` pre-change (must fail) and post-change (must pass) | Vacuous tests (`|| true`) rejected; required before PASS |
|
|
292
295
|
| `flow_check_scope` | Check whether files are in scope | Empty scope → fail-closed, everything out of scope |
|
|
293
|
-
| `flow_verdict` | Record verdict PASS / DIRECTION / LOCAL | No PASS without dispatch
|
|
294
|
-
| `flow_status` | Query gate state | Exposes `activation_pending` / `verify_passed` |
|
|
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` |
|
|
295
298
|
| `flow_audit` | Read the audit stream | Includes 6 activation-related event kinds |
|
|
296
299
|
| `flow_diff_hunks` | Parse `git diff -U0` hunk ranges | — |
|
|
297
300
|
| `flow_bypass` | Toggle bypass mode | Requires `confirmed=true`; auto-cleared on dispatch |
|
|
298
301
|
| `flow_revert_plan` | Generate an atomic restore plan | Returns a plan only, never executes |
|
|
299
302
|
| `flow_trigger_check` | Smart trigger check | Activates on success; honestly reports score otherwise |
|
|
300
303
|
|
|
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.
|
|
307
|
+
|
|
301
308
|
---
|
|
302
309
|
|
|
303
310
|
## ⚙️ Configuration
|
package/README.md
CHANGED
|
@@ -123,7 +123,7 @@ flowchart TB
|
|
|
123
123
|
Plugin["plugins/carlos-flow-trigger.js<br/>chat.message 钩子"]
|
|
124
124
|
end
|
|
125
125
|
|
|
126
|
-
subgraph Core["核心 MCP Server (src/index.js) —
|
|
126
|
+
subgraph Core["核心 MCP Server (src/index.js) — 19 个工具"]
|
|
127
127
|
Protocol["flow_protocol"]
|
|
128
128
|
Submit["flow_submit_requirement"]
|
|
129
129
|
Dispatch["flow_claim / flow_dispatch"]
|
|
@@ -283,7 +283,7 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
|
|
|
283
283
|
|
|
284
284
|
---
|
|
285
285
|
|
|
286
|
-
## 🔧 MCP 工具参考(
|
|
286
|
+
## 🔧 MCP 工具参考(19 个)
|
|
287
287
|
|
|
288
288
|
| 工具 | 作用 | 关键约束 |
|
|
289
289
|
|------|------|---------|
|
|
@@ -292,18 +292,25 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
|
|
|
292
292
|
| `flow_submit_requirement` | 提交/替换任务卡 | 按风险档强制必填项;伪填充被拒 |
|
|
293
293
|
| `flow_claim` | 领取派发名额(executor / auditor) | 激活闸门未解时拒绝 |
|
|
294
294
|
| `flow_dispatch` | 按四段合同派发子 Agent | 派发前自动快照 scope 内文件 |
|
|
295
|
+
| `flow_audit_axes` | **派发双轴审计**(Standards / Spec) | 生成两段并行审计 prompt,只读不改 |
|
|
296
|
+
| `flow_audit_submit` | **提交某一轴结论** | 按 `card_ts` 绑定当前卡;WARN 不硬拦;同轴可覆盖;写审计事件可追溯 |
|
|
297
|
+
| `flow_audit_guard` | **两轴门禁自查** | 与 `flow_verdict` 内的门禁同口径 |
|
|
295
298
|
| `flow_save_result` | 保存子 Agent 执行结果 | — |
|
|
296
299
|
| `flow_run_verify` | **真实执行** `verify.cmd` | 返回 exitCode / stdout / stderr + `output_hash` |
|
|
297
300
|
| `flow_falsify` | **负对照**:改动前跑 verify.cmd 必须失败、改动后必须通过 | 空测试(`|| true`)会被拒;记 PASS 前必做 |
|
|
298
301
|
| `flow_check_scope` | 检查文件是否越界 | 空 scope → fail-closed 全部越界 |
|
|
299
|
-
| `flow_verdict` | 记录裁定 PASS / DIRECTION / LOCAL |
|
|
300
|
-
| `flow_status` | 查询门禁状态 | 暴露 `activation_pending` / `verify_passed` |
|
|
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` |
|
|
301
304
|
| `flow_audit` | 读取审计流水 | 含 6 类激活相关事件 |
|
|
302
305
|
| `flow_diff_hunks` | 解析 `git diff -U0` 的 hunk 范围 | — |
|
|
303
306
|
| `flow_bypass` | 开关免检模式 | 需 `confirmed=true`;派发自动清零 |
|
|
304
307
|
| `flow_revert_plan` | 生成原子还原计划 | 只返回计划,不自动执行 |
|
|
305
308
|
| `flow_trigger_check` | 智能触发检查 | 达标即实际激活;未达标如实返回评分 |
|
|
306
309
|
|
|
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 章,**非原书全表**)—— 判定不再依赖模型记性。
|
|
313
|
+
|
|
307
314
|
---
|
|
308
315
|
|
|
309
316
|
## ⚙️ 配置
|
package/README.zh.md
CHANGED
|
@@ -123,7 +123,7 @@ flowchart TB
|
|
|
123
123
|
Plugin["plugins/carlos-flow-trigger.js<br/>chat.message 钩子"]
|
|
124
124
|
end
|
|
125
125
|
|
|
126
|
-
subgraph Core["核心 MCP Server (src/index.js) —
|
|
126
|
+
subgraph Core["核心 MCP Server (src/index.js) — 19 个工具"]
|
|
127
127
|
Protocol["flow_protocol"]
|
|
128
128
|
Submit["flow_submit_requirement"]
|
|
129
129
|
Dispatch["flow_claim / flow_dispatch"]
|
|
@@ -283,7 +283,7 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
|
|
|
283
283
|
|
|
284
284
|
---
|
|
285
285
|
|
|
286
|
-
## 🔧 MCP 工具参考(
|
|
286
|
+
## 🔧 MCP 工具参考(19 个)
|
|
287
287
|
|
|
288
288
|
| 工具 | 作用 | 关键约束 |
|
|
289
289
|
|------|------|---------|
|
|
@@ -292,18 +292,25 @@ node client/carlos.js flow_verdict '{"sessionId":"demo","verdict":"PASS","notes"
|
|
|
292
292
|
| `flow_submit_requirement` | 提交/替换任务卡 | 按风险档强制必填项;伪填充被拒 |
|
|
293
293
|
| `flow_claim` | 领取派发名额(executor / auditor) | 激活闸门未解时拒绝 |
|
|
294
294
|
| `flow_dispatch` | 按四段合同派发子 Agent | 派发前自动快照 scope 内文件 |
|
|
295
|
+
| `flow_audit_axes` | **派发双轴审计**(Standards / Spec) | 生成两段并行审计 prompt,只读不改 |
|
|
296
|
+
| `flow_audit_submit` | **提交某一轴结论** | 按 `card_ts` 绑定当前卡;WARN 不硬拦;同轴可覆盖;写审计事件可追溯 |
|
|
297
|
+
| `flow_audit_guard` | **两轴门禁自查** | 与 `flow_verdict` 内的门禁同口径 |
|
|
295
298
|
| `flow_save_result` | 保存子 Agent 执行结果 | — |
|
|
296
299
|
| `flow_run_verify` | **真实执行** `verify.cmd` | 返回 exitCode / stdout / stderr + `output_hash` |
|
|
297
300
|
| `flow_falsify` | **负对照**:改动前跑 verify.cmd 必须失败、改动后必须通过 | 空测试(`|| true`)会被拒;记 PASS 前必做 |
|
|
298
301
|
| `flow_check_scope` | 检查文件是否越界 | 空 scope → fail-closed 全部越界 |
|
|
299
|
-
| `flow_verdict` | 记录裁定 PASS / DIRECTION / LOCAL |
|
|
300
|
-
| `flow_status` | 查询门禁状态 | 暴露 `activation_pending` / `verify_passed` |
|
|
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` |
|
|
301
304
|
| `flow_audit` | 读取审计流水 | 含 6 类激活相关事件 |
|
|
302
305
|
| `flow_diff_hunks` | 解析 `git diff -U0` 的 hunk 范围 | — |
|
|
303
306
|
| `flow_bypass` | 开关免检模式 | 需 `confirmed=true`;派发自动清零 |
|
|
304
307
|
| `flow_revert_plan` | 生成原子还原计划 | 只返回计划,不自动执行 |
|
|
305
308
|
| `flow_trigger_check` | 智能触发检查 | 达标即实际激活;未达标如实返回评分 |
|
|
306
309
|
|
|
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 章,**非原书全表**)—— 判定不再依赖模型记性。
|
|
313
|
+
|
|
307
314
|
---
|
|
308
315
|
|
|
309
316
|
## ⚙️ 配置
|
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.
|
|
783
|
-
**更新日期**: 2026-11-
|
|
782
|
+
**版本**: v2.11.0
|
|
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": "门禁",
|
|
@@ -196,6 +196,77 @@
|
|
|
196
196
|
]
|
|
197
197
|
}
|
|
198
198
|
},
|
|
199
|
+
{
|
|
200
|
+
"name": "flow_audit_axes",
|
|
201
|
+
"description": "派发两个并行审计 subagent(Standards 轴 / Spec 轴),生成两段审计合同 prompt。executor 改动通过 flow_run_verify 与负对照后、落 PASS 裁定前必须先调用本工具。",
|
|
202
|
+
"parameters": {
|
|
203
|
+
"type": "object",
|
|
204
|
+
"properties": {
|
|
205
|
+
"sessionId": {
|
|
206
|
+
"type": "string",
|
|
207
|
+
"description": "会话 ID"
|
|
208
|
+
},
|
|
209
|
+
"cwd": {
|
|
210
|
+
"type": "string",
|
|
211
|
+
"description": "仓库工作目录,默认 process.cwd()"
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
},
|
|
216
|
+
{
|
|
217
|
+
"name": "flow_audit_submit",
|
|
218
|
+
"description": "保存某一审计轴(standards|spec)的结论与证据到会话状态。PASS 裁定前必须两轴都提交,且各自绑定的 card_ts 与当前卡一致。同轴可重复提交(后者覆盖)。",
|
|
219
|
+
"parameters": {
|
|
220
|
+
"type": "object",
|
|
221
|
+
"properties": {
|
|
222
|
+
"sessionId": {
|
|
223
|
+
"type": "string",
|
|
224
|
+
"description": "会话 ID"
|
|
225
|
+
},
|
|
226
|
+
"axis": {
|
|
227
|
+
"type": "string",
|
|
228
|
+
"enum": [
|
|
229
|
+
"standards",
|
|
230
|
+
"spec"
|
|
231
|
+
],
|
|
232
|
+
"description": "审计轴"
|
|
233
|
+
},
|
|
234
|
+
"verdict": {
|
|
235
|
+
"type": "string",
|
|
236
|
+
"enum": [
|
|
237
|
+
"PASS",
|
|
238
|
+
"FAIL",
|
|
239
|
+
"WARN"
|
|
240
|
+
],
|
|
241
|
+
"description": "轴判定;WARN=坏味道等 judgement call,不硬拦"
|
|
242
|
+
},
|
|
243
|
+
"findings": {
|
|
244
|
+
"type": "array",
|
|
245
|
+
"items": {
|
|
246
|
+
"type": "string"
|
|
247
|
+
},
|
|
248
|
+
"description": "每条含 file:line 或证据"
|
|
249
|
+
},
|
|
250
|
+
"evidence": {
|
|
251
|
+
"type": "string",
|
|
252
|
+
"description": "实跑命令输出 / diff 摘录"
|
|
253
|
+
}
|
|
254
|
+
}
|
|
255
|
+
}
|
|
256
|
+
},
|
|
257
|
+
{
|
|
258
|
+
"name": "flow_audit_guard",
|
|
259
|
+
"description": "校验两轴是否已通过且证据齐全(与 flow_verdict 内的双轴门禁同口径)。主 Agent 落 PASS 前可主动自查;flow_verdict 不受此调用影响,仍会再拦一道。",
|
|
260
|
+
"parameters": {
|
|
261
|
+
"type": "object",
|
|
262
|
+
"properties": {
|
|
263
|
+
"sessionId": {
|
|
264
|
+
"type": "string",
|
|
265
|
+
"description": "会话 ID"
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
},
|
|
199
270
|
{
|
|
200
271
|
"name": "flow_verdict",
|
|
201
272
|
"description": "记录 auditor 的裁定结果(PASS / DIRECTION / LOCAL)。只有 PASS 会把 completed_ok 置为 true。",
|
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",
|
|
@@ -71,8 +71,8 @@ try {
|
|
|
71
71
|
const hasValidation = /validateToolArgs\(/.test(src);
|
|
72
72
|
if (hasValidation) pass("CallTool handler 调用了 validateToolArgs(参数校验未丢失)");
|
|
73
73
|
else fail("CallTool handler 没有调用 validateToolArgs —— 参数校验可能已丢失");
|
|
74
|
-
if (declared.length ===
|
|
75
|
-
else fail(`TOOLS 声明了 ${declared.length} 个工具(期望
|
|
74
|
+
if (declared.length === 19) pass(`TOOLS 声明 ${declared.length} 个工具`);
|
|
75
|
+
else fail(`TOOLS 声明了 ${declared.length} 个工具(期望 19)`);
|
|
76
76
|
} catch (e) {
|
|
77
77
|
fail(`读取 src/index.js 失败:${e.message}`);
|
|
78
78
|
}
|
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,38 +7,135 @@ 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
|
+
|
|
49
|
+
// Dispatcher 配置:双轴审查 prompt 配置表。
|
|
50
|
+
// 新增轴只改这里,不动 buildContractPrompt 的函数体(避免分支膨胀)。
|
|
51
|
+
//
|
|
52
|
+
// 判定词表必须与 flow_audit_submit 的 enum(PASS / WARN / FAIL)对齐:
|
|
53
|
+
// 词表不一致时 subagent 会输出「通过/违规」这类自然语言,由主 Agent 手工映射,
|
|
54
|
+
// 而 FAIL(硬拦)与 WARN(不拦)的差别就在这一步 —— 映射错了硬拦就失效了。
|
|
55
|
+
const AXIS_PROMPTS = {
|
|
56
|
+
standards: {
|
|
57
|
+
objective: "审计:仓库代码规范与坏味道",
|
|
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。",
|
|
67
|
+
boundaries: "零文件改动,只读取证",
|
|
68
|
+
checklist: {
|
|
69
|
+
title: "坏味道基线",
|
|
70
|
+
items: SMELL_BASELINE,
|
|
71
|
+
note: "本表由 Carlos 自维护,术语对齐 Fowler《Refactoring》第二版第 3 章 Code Smells,非原书全表",
|
|
72
|
+
},
|
|
73
|
+
},
|
|
74
|
+
spec: {
|
|
75
|
+
objective: "审计:任务卡验收标准忠实度",
|
|
76
|
+
format: "判定(PASS / WARN / FAIL) / 验收标准逐条核对结果 / 越界改动(file:line)",
|
|
77
|
+
guidance:
|
|
78
|
+
"对照任务卡 goal/acceptance/scope,逐条核对卡上的验收标准,跑 flow_check_scope 校验越界," +
|
|
79
|
+
"独立跑验证命令取证。判定口径:验收标准全部满足且无越界判 PASS;未实现验收或越界改动判 FAIL;" +
|
|
80
|
+
"仅部分存疑判 WARN。",
|
|
81
|
+
boundaries: "零文件改动,只读取证",
|
|
82
|
+
},
|
|
83
|
+
};
|
|
84
|
+
|
|
10
85
|
// role ∈ "executor" | "auditor"
|
|
11
|
-
|
|
86
|
+
// axis ∈ undefined(默认四段合同) | "standards" | "spec"(双轴审计模式)
|
|
87
|
+
export function buildContractPrompt(role, card, extra, axis) {
|
|
12
88
|
const isAuditor = role === "auditor";
|
|
13
89
|
const isExecutor = role === "executor";
|
|
14
90
|
if (!isAuditor && !isExecutor) {
|
|
15
91
|
throw new Error(`buildContractPrompt: 未知 role "${role}"(仅支持 executor/auditor)`);
|
|
16
92
|
}
|
|
17
|
-
const c = card && typeof card === "object" ? card : {};
|
|
18
93
|
|
|
19
|
-
|
|
94
|
+
// 模式注入:指定了 axis 就走配置表(覆盖式),否则走原有逻辑
|
|
95
|
+
let objective, outputFormat, toolGuidance, taskBoundaries;
|
|
20
96
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
97
|
+
if (axis && AXIS_PROMPTS[axis]) {
|
|
98
|
+
const cfg = AXIS_PROMPTS[axis];
|
|
99
|
+
objective = `objective: ${cfg.objective}`;
|
|
100
|
+
outputFormat = `output format: ${cfg.format}`;
|
|
101
|
+
toolGuidance = `tool guidance: ${cfg.guidance}`;
|
|
102
|
+
taskBoundaries = `task boundaries: ${cfg.boundaries}`;
|
|
103
|
+
} else {
|
|
104
|
+
const c = card && typeof card === "object" ? card : {};
|
|
24
105
|
|
|
25
|
-
|
|
26
|
-
let guidance = verifyCmd || "未指定验证命令,用只读取证";
|
|
27
|
-
if (isAuditor) {
|
|
28
|
-
guidance += ";独立跑 git status --porcelain 与 git diff 取证,不轻信 executor 自述";
|
|
29
|
-
}
|
|
30
|
-
const toolGuidance = `tool guidance: ${guidance}`;
|
|
106
|
+
objective = `objective: ${c.goal || ""}`;
|
|
31
107
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
108
|
+
outputFormat = isExecutor
|
|
109
|
+
? "output format: 报告 ≤300 字,四段:结论(一句话,做完/没做完) / 改动(file:line 逐条列出,没改写“无”) / 验证(命令 → 结果摘要,未跑写“未验证”) / 遗留风险"
|
|
110
|
+
: "output format: 报告 ≤200 字,五段:裁定(通过/不通过) / 失败类型(操作错误/环境问题/卡片问题) / scope 标注(是否越界改动) / 证据(file:line 或实跑命令输出) / 附注";
|
|
111
|
+
|
|
112
|
+
const verifyCmd = c.verify && c.verify.cmd ? String(c.verify.cmd) : "";
|
|
113
|
+
let guidance = verifyCmd || "未指定验证命令,用只读取证";
|
|
114
|
+
if (isAuditor) {
|
|
115
|
+
guidance += ";独立跑 git status --porcelain 与 git diff 取证,不轻信 executor 自述";
|
|
116
|
+
}
|
|
117
|
+
toolGuidance = `tool guidance: ${guidance}`;
|
|
118
|
+
|
|
119
|
+
const scopeArr = Array.isArray(c.scope) ? c.scope.map(String) : [];
|
|
120
|
+
let boundaries;
|
|
121
|
+
if (isAuditor) {
|
|
122
|
+
boundaries = "零文件改动,只读取证";
|
|
123
|
+
} else {
|
|
124
|
+
boundaries = scopeArr.length > 0 ? scopeArr.join(", ") : "无文件可改,只读任务";
|
|
125
|
+
}
|
|
126
|
+
taskBoundaries = `task boundaries: ${boundaries}`;
|
|
38
127
|
}
|
|
39
|
-
const taskBoundaries = `task boundaries: ${boundaries}`;
|
|
40
128
|
|
|
41
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
|
+
|
|
42
139
|
if (extra && String(extra) !== "") {
|
|
43
140
|
prompt += "\n\n" + String(extra); // 原样附在末尾
|
|
44
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
|
{
|
|
@@ -474,11 +507,116 @@ const TOOLS = [
|
|
|
474
507
|
},
|
|
475
508
|
|
|
476
509
|
// 5 -----------------------------------------------------------------------
|
|
510
|
+
{
|
|
511
|
+
name: "flow_audit_axes",
|
|
512
|
+
description:
|
|
513
|
+
"派发两个并行审计 subagent(Standards 轴 / Spec 轴),生成两段审计合同 prompt。" +
|
|
514
|
+
"executor 改动通过 flow_run_verify 与负对照后、落 PASS 裁定前必须先调用本工具。",
|
|
515
|
+
inputSchema: {
|
|
516
|
+
type: "object",
|
|
517
|
+
properties: {
|
|
518
|
+
sessionId: { type: "string", description: "会话 ID" },
|
|
519
|
+
cwd: { type: "string", description: "仓库工作目录,默认 process.cwd()" },
|
|
520
|
+
},
|
|
521
|
+
},
|
|
522
|
+
handler: async (args) => {
|
|
523
|
+
try {
|
|
524
|
+
const sid = args.sessionId || "unknown";
|
|
525
|
+
const state = loadState(sid);
|
|
526
|
+
if (!state.card) return fail("无卡,无法派发审计轴");
|
|
527
|
+
|
|
528
|
+
const cwd = args.cwd || process.cwd();
|
|
529
|
+
const res = { standards: null, spec: null };
|
|
530
|
+
for (const axis of ["standards", "spec"]) {
|
|
531
|
+
const prompt = buildContractPrompt("auditor", state.card, "", axis);
|
|
532
|
+
const { file } = writeDispatchPrompt(sid, "auditor", prompt, cwd);
|
|
533
|
+
res[axis] = { prompt, file };
|
|
534
|
+
}
|
|
535
|
+
return ok({ ok: true, ...res });
|
|
536
|
+
} catch (e) { return fail(String(e)); }
|
|
537
|
+
},
|
|
538
|
+
},
|
|
539
|
+
{
|
|
540
|
+
name: "flow_audit_submit",
|
|
541
|
+
description:
|
|
542
|
+
"保存某一审计轴(standards|spec)的结论与证据到会话状态。" +
|
|
543
|
+
"PASS 裁定前必须两轴都提交,且各自绑定的 card_ts 与当前卡一致。同轴可重复提交(后者覆盖)。",
|
|
544
|
+
inputSchema: {
|
|
545
|
+
type: "object",
|
|
546
|
+
properties: {
|
|
547
|
+
sessionId: { type: "string", description: "会话 ID" },
|
|
548
|
+
axis: { type: "string", enum: ["standards", "spec"], description: "审计轴" },
|
|
549
|
+
verdict: { type: "string", enum: ["PASS", "FAIL", "WARN"], description: "轴判定;WARN=坏味道等 judgement call,不硬拦" },
|
|
550
|
+
findings: { type: "array", items: { type: "string" }, description: "每条含 file:line 或证据" },
|
|
551
|
+
evidence: { type: "string", description: "实跑命令输出 / diff 摘录" },
|
|
552
|
+
},
|
|
553
|
+
},
|
|
554
|
+
handler: async (args) => {
|
|
555
|
+
try {
|
|
556
|
+
const sid = args.sessionId || "unknown";
|
|
557
|
+
const state = loadState(sid);
|
|
558
|
+
if (!state.card) return fail("无卡,无法提交审计轴结论");
|
|
559
|
+
state.audit_axes[args.axis] = {
|
|
560
|
+
verdict: args.verdict,
|
|
561
|
+
findings: args.findings,
|
|
562
|
+
evidence: args.evidence,
|
|
563
|
+
// 绑定提交时的卡片:换卡后该轴证据立即失效,必须重审
|
|
564
|
+
card_ts: state.card_ts,
|
|
565
|
+
ts: Date.now(),
|
|
566
|
+
};
|
|
567
|
+
state.audit_axes_ts = Date.now();
|
|
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
|
+
});
|
|
581
|
+
const stored = [state.audit_axes.standards, state.audit_axes.spec].filter(Boolean).length;
|
|
582
|
+
return ok({ ok: true, axis: args.axis, stored_axes_count: stored });
|
|
583
|
+
} catch (e) { return fail(String(e)); }
|
|
584
|
+
},
|
|
585
|
+
},
|
|
586
|
+
{
|
|
587
|
+
name: "flow_audit_guard",
|
|
588
|
+
description:
|
|
589
|
+
"校验两轴是否已通过且证据齐全(与 flow_verdict 内的双轴门禁同口径)。" +
|
|
590
|
+
"主 Agent 落 PASS 前可主动自查;flow_verdict 不受此调用影响,仍会再拦一道。",
|
|
591
|
+
inputSchema: {
|
|
592
|
+
type: "object",
|
|
593
|
+
properties: { sessionId: { type: "string", description: "会话 ID" } },
|
|
594
|
+
},
|
|
595
|
+
handler: async (args) => {
|
|
596
|
+
try {
|
|
597
|
+
const sid = args.sessionId || "unknown";
|
|
598
|
+
const state = loadState(sid);
|
|
599
|
+
const ax = state.audit_axes;
|
|
600
|
+
// 口径与 flow_verdict 的双轴门禁完全一致:
|
|
601
|
+
// 两轴都有 verdict(不能缺失/空)、card_ts 与当前卡一致、且无轴 FAIL。
|
|
602
|
+
const axisOk = (a) => ax && ax[a] && ax[a].verdict && ax[a].card_ts === state.card_ts;
|
|
603
|
+
if (!axisOk("standards") || !axisOk("spec")) {
|
|
604
|
+
return fail("两轴审计未齐或证据失效(需 flow_audit_axes 派发 + flow_audit_submit 两轴且 card_ts 与当前卡一致)");
|
|
605
|
+
}
|
|
606
|
+
if (ax.standards.verdict === "FAIL" || ax.spec.verdict === "FAIL") {
|
|
607
|
+
return fail("两轴中至少一轴 FAIL(standards=" + ax.standards.verdict +
|
|
608
|
+
", spec=" + ax.spec.verdict + ")。");
|
|
609
|
+
}
|
|
610
|
+
return ok({ ok: true });
|
|
611
|
+
} catch (e) { return fail(String(e)); }
|
|
612
|
+
},
|
|
613
|
+
},
|
|
477
614
|
{
|
|
478
615
|
name: "flow_verdict",
|
|
479
616
|
description:
|
|
480
617
|
"记录 auditor 的裁定结果(PASS / DIRECTION / LOCAL)。只有 PASS 会把 completed_ok 置为 true。" +
|
|
481
|
-
"DIRECTION 表示方向对但需返工,LOCAL 表示问题局限在局部。在向用户汇报完成前必须先落裁定,否则视为未复核。"
|
|
618
|
+
"DIRECTION 表示方向对但需返工,LOCAL 表示问题局限在局部。在向用户汇报完成前必须先落裁定,否则视为未复核。" +
|
|
619
|
+
"【双轴门禁】记 PASS 前必须先 flow_audit_axes 派发 Standards/Spec 两轴、由 subagent 取证后 flow_audit_submit 提交两轴结论;任一轴 FAIL 会被拒,WARN 不硬拦。",
|
|
482
620
|
inputSchema: {
|
|
483
621
|
type: "object",
|
|
484
622
|
properties: {
|
|
@@ -638,6 +776,46 @@ const TOOLS = [
|
|
|
638
776
|
return fail("已有的验证结果与负对照的运行结果不一致,不能记录 PASS 裁定。" +
|
|
639
777
|
"请重新调用 flow_falsify(它会把改动后的运行写为验证证据)。");
|
|
640
778
|
}
|
|
779
|
+
|
|
780
|
+
// 防假闭环之六:双轴审查门禁。
|
|
781
|
+
//
|
|
782
|
+
// 位置说明(重要):必须放在负对照**之后**。语义顺序是
|
|
783
|
+
// 「先证实验证有效 → 再证审查到位」,六道门各自独立、互不掩盖。
|
|
784
|
+
// 若前置,会让「未验证」「未派发」「未做负对照」这些更基础的问题被
|
|
785
|
+
// 双轴错误信息掩盖,调用方拿到的是不可操作的下一步。
|
|
786
|
+
//
|
|
787
|
+
// 判定口径:
|
|
788
|
+
// · 两轴都必须有结论,且 card_ts 与当前卡一致(防旧卡审查结果冒充新卡,
|
|
789
|
+
// 也防两轴跨卡拼接:卡A的 standards + 卡B的 spec 不算数);
|
|
790
|
+
// · FAIL 硬拦(规范硬违规 / 未实现验收);
|
|
791
|
+
// · WARN 不硬拦(坏味道是 judgement call),由主 Agent 读 audit_axes 后标注。
|
|
792
|
+
const ax = state.audit_axes;
|
|
793
|
+
const axisOk = (a) => ax && ax[a] && ax[a].verdict && ax[a].card_ts === state.card_ts;
|
|
794
|
+
const hasStandards = axisOk("standards");
|
|
795
|
+
const hasSpec = axisOk("spec");
|
|
796
|
+
if (!hasStandards || !hasSpec) {
|
|
797
|
+
audit("decision", sessionId, {
|
|
798
|
+
kind: "verdict_denied",
|
|
799
|
+
reason: "两轴审查未齐",
|
|
800
|
+
standards: ax && ax.standards ? ax.standards.verdict : null,
|
|
801
|
+
spec: ax && ax.spec ? ax.spec.verdict : null,
|
|
802
|
+
card_ts: state.card_ts,
|
|
803
|
+
});
|
|
804
|
+
return fail("两轴审查未齐,不能记录 PASS 裁定。请先 flow_audit_axes 派发两轴、" +
|
|
805
|
+
"由 subagent 取证后分别 flow_audit_submit 提交 Standards 与 Spec 两轴结论,再记录裁定。");
|
|
806
|
+
}
|
|
807
|
+
const standardsFail = ax.standards.verdict === "FAIL";
|
|
808
|
+
const specFail = ax.spec.verdict === "FAIL";
|
|
809
|
+
if (standardsFail || specFail) {
|
|
810
|
+
audit("decision", sessionId, {
|
|
811
|
+
kind: "verdict_denied",
|
|
812
|
+
reason: "有轴不通过",
|
|
813
|
+
standards: ax.standards.verdict,
|
|
814
|
+
spec: ax.spec.verdict,
|
|
815
|
+
});
|
|
816
|
+
return fail("PASS 被拒:两轴中至少一轴 FAIL(standards=" + ax.standards.verdict +
|
|
817
|
+
", spec=" + ax.spec.verdict + ")。请修复后重跑验证与审计。");
|
|
818
|
+
}
|
|
641
819
|
}
|
|
642
820
|
|
|
643
821
|
const findings = [];
|
|
@@ -649,11 +827,25 @@ const TOOLS = [
|
|
|
649
827
|
state.verdict = verdict;
|
|
650
828
|
state.completed_ok = verdict === "PASS";
|
|
651
829
|
state.verdict_ts = Date.now();
|
|
830
|
+
// 落盘裁定者角色:审计链据此回溯「这条 PASS 是谁落的」。
|
|
831
|
+
state.verdict_role = a.role === undefined ? null : a.role;
|
|
652
832
|
saveState(sessionId, state);
|
|
653
833
|
|
|
654
834
|
audit("resolution", sessionId, { kind: "verdict", verdict, notes: a.notes, role: a.role });
|
|
655
835
|
|
|
656
|
-
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;
|
|
657
849
|
if (findings.length) result.findings = findings;
|
|
658
850
|
return ok(result);
|
|
659
851
|
} catch (e) {
|
|
@@ -679,6 +871,7 @@ const TOOLS = [
|
|
|
679
871
|
const a = args || {};
|
|
680
872
|
const sessionId = a.sessionId || "unknown";
|
|
681
873
|
const state = loadState(sessionId);
|
|
874
|
+
const warns = collectAxisWarnings(state);
|
|
682
875
|
|
|
683
876
|
const result = {
|
|
684
877
|
sessionId,
|
|
@@ -687,6 +880,10 @@ const TOOLS = [
|
|
|
687
880
|
dispatch_count: state.dispatch_count,
|
|
688
881
|
max_dispatch: MAX_DISPATCH,
|
|
689
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,
|
|
690
887
|
verified: !!state.verdict,
|
|
691
888
|
// verify_passed:真实验证是否通过(last_verify.ok===true 且命令与当前卡片一致)。
|
|
692
889
|
// 注意 verified 只表示「是否已有裁定」,不代表验证通过——两者语义不同,不可混用。
|
|
@@ -697,7 +894,20 @@ const TOOLS = [
|
|
|
697
894
|
card: state.card,
|
|
698
895
|
card_ts: state.card_ts,
|
|
699
896
|
activation_pending: Array.isArray(state.activation_pending) ? state.activation_pending : [],
|
|
897
|
+
// 双轴审查证据:主 Agent 落 PASS 前可读它确认两轴状态与 card_ts 绑定。
|
|
898
|
+
// axes_ready = 两轴都有结论且 card_ts 与当前卡一致且无轴 FAIL。
|
|
899
|
+
audit_axes: state.audit_axes,
|
|
900
|
+
audit_axes_ts: state.audit_axes_ts,
|
|
901
|
+
axes_ready: (() => {
|
|
902
|
+
const ax = state.audit_axes;
|
|
903
|
+
const axisOk = (x) => ax && ax[x] && ax[x].verdict && ax[x].card_ts === state.card_ts;
|
|
904
|
+
return axisOk("standards") && axisOk("spec") &&
|
|
905
|
+
ax.standards.verdict !== "FAIL" && ax.spec.verdict !== "FAIL";
|
|
906
|
+
})(),
|
|
907
|
+
// WARN 汇总(与 flow_verdict 同一份派生口径):只读镜像,供事后复查。
|
|
908
|
+
warn_count: warns.length,
|
|
700
909
|
};
|
|
910
|
+
if (warns.length) result.warn_findings = warns;
|
|
701
911
|
if (state.card && !state.verdict) result.unreviewed = true;
|
|
702
912
|
return ok(result);
|
|
703
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
|
* 迁移旧版本的状态文件。
|
|
@@ -107,6 +107,13 @@ export const CURRENT_SCHEMA_VERSION = 2;
|
|
|
107
107
|
*
|
|
108
108
|
* v1 → v2:新增 last_falsify(负对照记录)。
|
|
109
109
|
* · 旧状态没有这个字段 → 补 null(表示「还没做负对照」,裁定会拒绝 PASS)
|
|
110
|
+
*
|
|
111
|
+
* v2 → v3:新增 audit_axes / audit_axes_ts(双轴审查证据)。
|
|
112
|
+
* · 旧状态没有这两个字段 → 补默认结构(两轴均为 null = 尚未审查,裁定会拒绝 PASS)
|
|
113
|
+
* · audit_axes 存在但结构不全时也在此补齐,避免读到半初始化对象
|
|
114
|
+
*
|
|
115
|
+
* v3 → v4:新增 verdict_role(本条 PASS 是谁落的)。
|
|
116
|
+
* · 旧状态没有这个字段 → 补 null(仅影响可观测性,不影响门禁判定)
|
|
110
117
|
*/
|
|
111
118
|
export function migrate(parsed) {
|
|
112
119
|
if (!parsed || typeof parsed !== "object") return parsed;
|
|
@@ -128,6 +135,26 @@ export function migrate(parsed) {
|
|
|
128
135
|
v = 2;
|
|
129
136
|
}
|
|
130
137
|
|
|
138
|
+
if (v < 3) {
|
|
139
|
+
// v2 → v3
|
|
140
|
+
if (!out.audit_axes || typeof out.audit_axes !== "object") {
|
|
141
|
+
out.audit_axes = { standards: null, spec: null };
|
|
142
|
+
} else {
|
|
143
|
+
out.audit_axes = {
|
|
144
|
+
standards: out.audit_axes.standards || null,
|
|
145
|
+
spec: out.audit_axes.spec || null,
|
|
146
|
+
};
|
|
147
|
+
}
|
|
148
|
+
if (typeof out.audit_axes_ts !== "number") out.audit_axes_ts = 0;
|
|
149
|
+
v = 3;
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
if (v < 4) {
|
|
153
|
+
// v3 → v4
|
|
154
|
+
if (out.verdict_role === undefined) out.verdict_role = null;
|
|
155
|
+
v = 4;
|
|
156
|
+
}
|
|
157
|
+
|
|
131
158
|
out.schemaVersion = CURRENT_SCHEMA_VERSION;
|
|
132
159
|
return out;
|
|
133
160
|
}
|
|
@@ -173,6 +200,21 @@ export function defaultState() {
|
|
|
173
200
|
// 负对照要求:改动前必须失败、改动后必须通过,才证明这个测试真的在测本次改动。
|
|
174
201
|
// null = 还没做负对照(此时 flow_verdict 拒绝 PASS)。
|
|
175
202
|
last_falsify: null,
|
|
203
|
+
// 双轴审查证据(flow_audit_submit 写入)。
|
|
204
|
+
// 结构:{ standards: {verdict,findings,evidence,card_ts,ts} | null, spec: {...} | null }
|
|
205
|
+
//
|
|
206
|
+
// 为什么按轴绑定 card_ts,而不是只用一个全局时间戳:
|
|
207
|
+
// 两轴是**分两次**提交的。卡A提交 standards → 换新卡B → 只补 spec,
|
|
208
|
+
// 此时全局时间戳已被刷新到卡B之后,单看时间戳会放行,而 standards
|
|
209
|
+
// 仍是卡A的结论 —— 「两轴跨卡拼接」。绑定 card_ts 后,换卡即两轴全失效。
|
|
210
|
+
audit_axes: { standards: null, spec: null },
|
|
211
|
+
// 两轴最后提交时间(审计链留痕用;不参与冒充校验,校验看 card_ts)。
|
|
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,
|
|
176
218
|
};
|
|
177
219
|
}
|
|
178
220
|
|