ADR-007 · /boss 第 3 种模式 · REVIEW · panel 评议现成方案
| 字段 | 值 |
|---|---|
| 状态 | accepted · 2026-05-28 |
| 日期 | 2026-05-28 |
| 决策者 | CTO + 项目主理 |
| 承接 | ADR-001 (multi-anchor) · ADR-004 (HTTP API) |
| 相关 | skills/tian/SKILL.md · skills/tian-judgement-orchestrator/SKILL.md · scripts/run_pipeline_local.py · schemas/case-schema.json |
1. Context
1.1 · 起源 · 用户场景
ADR-006 公仓脱敏落地后, 项目主理 提出新 use case:
"boss 命令可以接受一份文件吗? 不只是议题. 基于这份文件来做判断."
进一步澄清: 不是"给 boss 加 evidence", 而是"给 boss 一份已经包含方案的文档让它评议". 例如:
- 一份内部战略 PRD draft
- 一份外部供应商提案
- 一份团队成员的商业计划书
- 一份咨询机构的报告
用户预期: panel (1 anchor + N 维度评委) 评议这个方案, 给出修订建议.
1.2 · 现状: /boss 只有 2 种模式
| 模式 | trigger | input | 流程 |
|---|---|---|---|
| FRESH | 议题文本, reports/<brand>/ 不存在 | 议题 (文本) | Phase 0 router → Phase 1 PRD 生成 → Phase 2 调研 → Phase 3-5 |
| EVOLUTION | --refresh 或 reports/<brand>/ 已存在 + 新证据 | 议题 + 增量证据 (--diff-only 限范围) | Phase 0-5 重跑, 沿用 v1 unchanged 部分 |
共同假设: 入口是 议题 (open question), boss 从零调研 + 评议.
REVIEW 打破这个假设: 入口是 方案 (claimed answer), boss 不调研, 仅评议.
这是 input 形态的根本变化, 不是 flag 的 mod, 需要新模式. 不要硬塞进 FRESH/EVOLUTION.
1.3 · 为什么 boss 适合做 review
boss 流水线的核心资产是:
- 1 anchor 评委 (锚点视角, 跨议题 doctrine)
- 6 维度评委 (industry/strategic/financial/customer/product/org)
- 5 镜头 (lever_clarity / counter_position / specificity / falsifiability / actionability)
- adversarial_view 3 字段 (counter / null_hypothesis / steel_man)
这套机制天然适合评议, 而不是生成. 评议方案就是: "5 评委每人从自己 doctrine 角度看, 给出打分 + 反方 + 修订建议".
把 review 用 boss 做, 相比走外部 review skill, 优势:
- 复用 panel auto-select (议题类型自动选 4-6 评委)
- 复用 case.json + report.md schema (一致输出)
- 复用 30/90/365 attribution (review 推荐了什么, 半年后看是不是真做了)
- 复用 versions/ 不可变冻结 (review v1 后续可重做 v2)
2. Decision
新增 /boss REVIEW 模式, 与 FRESH / EVOLUTION 并列.
2.1 · 调用形态
# 基本调用
/boss --review docs/strategy-2026Q4.md
# 显式指定 panel (override auto-select)
/boss --review docs/X.md --panel default
# override doc 推断的议题
/boss --review docs/X.md --topic "战略风险"
# override doc 推断的 brand-slug (默认从文件名)
/boss --review docs/X.md --brand strategy-2026q4
# 开 Phase 2 claim verification (默认关)
/boss --review docs/X.md --verify
# 跳 Phase 4 评委 (出 doc digest + synthesis 就停, 用于预审)
/boss --review docs/X.md --no-judges2.2 · Pipeline shape 变化
Phase | FRESH | REVIEW
---------------------|--------------------------------------|----------------------------------------------
0 · Router | 议题 → topic_type → panel auto-select | doc parser (extract claims/decisions/
| | variables/actions) → topic_type → panel
1 · PRD/Context | LLM 生成 5 维 PRD | **跳过** — doc 本身就是 PRD,
| 从 Wiki/raw 装 Background | 仅装 Background from Wiki
2 · Sub-agents | 4-5 dim parallel 调研生成证据 | (默认关) — `--verify` 时:
| | claim verification (wiki cross-check)
3 · Synthesis | 多维度证据合成杠杆/脆弱/矛盾 | doc claims + verification 合成 +
| | identify gaps (doc 没回答的关键问题)
4 · 评委 review | 1 anchor + N dim 独立打分 | **不变** — 同样 5 评委独立打分
| (5 镜头 + adversarial_view) | 但打分对象是"doc 提出的方案"而非"议题"
5 · 合议 | panel_summary + | panel_summary +
| dim_weighted vs anchor_tian | **修订建议清单** (REVIEW 独有)2.3 · 5 个关键设计决策 (lock-down)
决策 1 · 支持的 file type (v1)
选: .md + .txt
- v1.0: 仅 Markdown / 纯文本 (Phase 0 直接 read)
- v1.1: 加
.pdf(pandoc 转 md) +.docx(pandoc) — 延迟 - 拒绝:
.html(语义模糊, structure 不可靠)
理由: V0 期用户主要写 .md (CLAUDE/PRD/ADR 都是). pandoc 桥要装外部依赖, 推到 v1.1.
状态更新 (2026-06-28): PDF/DOCX 已落地, 但未走 pandoc — 改用
pypdf+python-docx直接提取文字 (run_pipeline_local._read_doc_text), 避开 pandoc 系统依赖。.docx连表格文字 一并提取; 扫描件 (无文字层) 与空文档由 Phase 0 "内容过短 < 100 字符" 闸拦下并清晰报错;.doc老二进制仍拒绝, 引导转.docx/PDF。本决策的"延迟"已解除, 实现路径与原设想 (pandoc) 不同。
决策 2 · topic_type 怎么定
默认: doc 全文喂给 LLM (Phase 0 router 已有判断逻辑), 让它推 topic_type. Override: 用户可 --topic "战略风险" 显式指定议题字符串, 走标准 topic_type 判断.
理由: 8 种 topic_type (strategic/customer/organizational/product/brand/financial/cross_domain/unknown) 已有 LLM router, 复用即可.
决策 3 · brand-slug 怎么定
默认: 文件名去扩展名 + slugify. 例 docs/strategy-2026Q4.md → strategy-2026q4. Override: --brand <slug> 显式.
冲突: 如果 reports/<slug>/ 已存在 (说明该 slug 跑过 FRESH/EVOLUTION), 默认拒绝, 要求 --review-into <slug> 显式覆盖. 防误覆盖.
决策 4 · Phase 2 claim verification 默认关
默认: REVIEW 跳 Phase 2 (节省 ~$1-2 / 次 LLM 钱). Opt-in: --verify 跑 Phase 2 — 抽取 doc 里关键 claim, 派 sub-agent 对照 wiki + 外网验证.
理由: 很多 REVIEW 场景下, doc 已经有充分内部证据 (e.g., 战略 PRD 引用了大量内部数据). 再走 wiki 调研冗余. --verify 适合 doc 缺数据支撑、需要补外部佐证的场景.
决策 5 · 输出报告主结构
reports/<brand>/report.md 三段式:
# REVIEW: <doc 标题>
## §A · 原方案摘要 (Phase 0 doc parser 提取)
- 核心 claim (3-5 句)
- 关键 decisions (action list)
- 隐含 variables (核心假设)
- 时间表 / 资源约束
## §B · 5 评委评议 (Phase 4)
- 1 anchor review (锚点视角)
- N dim reviews (industry/strategic/financial/...)
- panel_summary (dim_weighted vs anchor_tian)
- adversarial_view aggregation
## §C · 修订建议清单 (Phase 5 新增)
- 5 评委各自的 "如果是我会改的 3 点"
- 共识修订 (≥3 评委同意)
- 分歧点 (评委之间不同意见)
- 致命脆弱 (anchor 标 "这条没解决前别签")
- 30/90/365 验证 checkpointcase.json 新增 mode: "REVIEW" + variables[i].source = "from-doc" (区分 generated 与 doc 提取).
3. Consequences
3.1 · 优势
| 维度 | 落地后能力 |
|---|---|
| 用户场景扩展 | 从 "问问题" 单一模式 → "问问题 / 评方案" 双模式 |
| panel 资产复用 | 6 维评委 + 锚点 + 5 镜头 在新场景直接复用, 0 额外训练成本 |
| Attribution 价值 | review 推荐的修订, 30 天后看落实情况 (落了几条 / 哪几条没人接) |
| 决策审计 trail | review v1 冻结后, 半年后追溯 "当时 panel 怎么看这份方案" |
| ToB 商业化 contention | review 是 SaaS 友好场景 (给我看一份 PDF 出一份报告), FRESH 更难批量化 |
3.2 · 接受的 tradeoff
- 3 模式带来认知负担: 用户要懂 FRESH / EVOLUTION / REVIEW 何时用哪个. mitigation: SKILL.md 加 "选择 mode 决策树"
- Phase 0 doc parser 是新组件: 要开发 + 测试. 风险: doc parse 失败 (e.g., doc 没明确 decision section). mitigation: 失败时 fallback FRESH 并提示
- REVIEW 报告结构与 FRESH 不同: 下游消费者 (e.g., 飞书 webhook) 需要区分. mitigation:
mode字段在 case.json 明确, 消费者 dispatch - panel_summary 语义微调: REVIEW 下 anchor_delta 不再是"对议题的乐观差", 而是"对方案的乐观差". 含义不同但计算公式一样
3.3 · 不变的承诺
- FRESH / EVOLUTION 行为不变 — REVIEW 是纯加项, 不动现有
- 1 anchor + N dim + 5 镜头 + adversarial_view 不变
- case.json schema 兼容向后 (新加 mode + source 字段, 旧 case 默认 mode="FRESH")
- versions/ 不可变冻结不变
- 30/90/365 attribution 触发逻辑不变
- redact_check + check_public_safe 不变
3.4 · Invariant impact
本变更让以下 invariant 失效:
- inv-old: "/boss 入口是议题文本" → 失效 · REVIEW 入口是 file path
- inv-old: "Phase 1 总是 PRD 生成" → 失效 · REVIEW 跳 Phase 1
- inv-old: "Phase 2 总是 sub-agents 调研" → 失效 · REVIEW 默认跳, opt-in verification
- inv-old: "report.md 结构固定: 议题 → 调研 → 评议 → 合议" → 失效 · REVIEW 加 §A 摘要 + §C 修订建议
- inv-old: "anchor_delta 衡量 anchor 视角 vs panel 视角的乐观差 on 议题" → 语义微调 · REVIEW 下衡量 on 方案
本变更引入以下新 invariant:
- inv-1: REVIEW 必有
case.json.mode == "REVIEW"字段 (与 FRESH/EVOLUTION 区分) - inv-2: REVIEW 的 case.json variables 必须每个标
source: "from-doc"或source: "wiki-verify"(区分来源) - inv-3: REVIEW report.md 必须有三段 §A/§B/§C, smoke_e2e.verify 加 check
- inv-4: Phase 0 doc parser 失败时, 必须 fallback FRESH 并明确告知, 不能静默
- inv-5:
reports/<brand>/已存在时, REVIEW 默认拒绝, 要求--review-into显式覆盖
4. Alternatives Considered
| 方案 | 为什么没选 |
|---|---|
A1 · 用 EVOLUTION + --evidence <doc> 注入 | 语义错 · EVOLUTION 是"v1 不动加新证据 v2", REVIEW 是"doc 就是 v1 输入". 混用导致 case.json 字段意义模糊 |
A2 · 写独立 /doc-review skill 不复用 boss | 错失 panel + 5 镜头 + adversarial + attribution 资产 · doc-review 重写一遍是浪费 |
A3 · /boss <doc-path> 让 boss 自动检测 file vs 议题 | 用户意图模糊 · 文件名长得像议题怎么办? 显式 --review flag 比 implicit detection 更稳 |
| A4 · REVIEW 不要 Phase 2 verification, 永远跳 | 失去差异化 · 有些场景 doc 缺数据, 用户希望 boss 帮补 wiki 交叉. 留 --verify opt-in |
| A5 · REVIEW 报告与 FRESH 同结构 | 错失 "修订建议清单" 这个 REVIEW 核心 deliverable · REVIEW 用户要的是"建议改什么", 不是"评分多少" |
5. Migration Plan
5.1 · Phase 1 · 核心 pipeline (~3-4h)
scripts/run_pipeline_local.py:- 加
--mode REVIEW(或检测--review) 路由分支 - Phase 0 加 doc parser 子函数 (
_parse_review_doc(path) → {claims, decisions, variables, topic_type}) - Phase 1 在 REVIEW 模式跳 PRD 生成, 仅装 Background from Wiki
- Phase 2 默认跳,
--verifyopt-in - Phase 3 合成 prompt 改"对照 doc claims + Wiki 找 gap"
- 加
schemas/case-schema.json:- 加 optional
mode: enum["FRESH", "EVOLUTION", "REVIEW"], 默认 FRESH - 加 optional
variables[i].source: enum["generated", "from-doc", "wiki-verify"]
- 加 optional
5.2 · Phase 2 · 评委 + 报告 (~2h)
- Phase 4 评委 prompt 增 REVIEW 上下文 (告诉评委 "这是一份方案, 评议它")
- Phase 5 合议 prompt 增"修订建议清单"段
reports/<brand>/report.md模板加 §A/§B/§C 三段式- smoke_e2e.verify 加 REVIEW 模式 check (inv-3)
5.3 · Phase 3 · 用户面 (~1h)
skills/tian/SKILL.md(用户面入口):- 加
/boss --review <doc>命令文档 - 加 "选择 mode 决策树" (FRESH / EVOLUTION / REVIEW 何时用哪个)
- 加
skills/tian-judgement-orchestrator/SKILL.md:- 加 REVIEW 模式 Phase 0-5 实现细节
- ADR README 加 ADR-007 一行
- dev-log 复盘
5.4 · Phase 4 · 实战验证 (~1h)
- 拿 ADR-005 本身作 test fixture (
/boss --review www/adr/ADR-005-hybrid-deployment.md) - 验证 case.json + report.md + reviews/ + revision-suggestions.md 全齐
- panel_summary 出来合理 (锚点对 hybrid 评议如何?)
总: ~6-8 h, 一个工作日
6. 关键反共识立场
"REVIEW 就是 FRESH 把 doc 当 raw evidence 喂进去, 不用新模式" — 错.
如果只是把 doc 塞 Phase 1 raw, 后续 4 个变化你都拿不到:
- Phase 1 仍会生成 PRD (浪费 LLM 钱 + 概念冲突 — doc 已经是 PRD-shape)
- Phase 2 仍会调研 (与 doc 已有内容大量重复)
- Phase 4 评委 prompt 不知道"这是一份方案", 仍会用"对议题观点"模板打分
- Phase 5 不会产出修订建议清单 — 但这是 REVIEW 用户最想要的东西
简单"塞进去"丢的不是 ergonomic, 是核心价值. 用户要的是"评议这份方案给我改进建议", 不是"用这份方案做新研究".
"REVIEW 应该跳 panel 直接出 anchor 视角" — 错.
panel (1 anchor + N dim) 评议方案的独立性比 anchor 单看强很多. 一份战略 doc, 锚点可能从经验觉得方向对, 但 financial 评委看数字、product 评委看执行、customer 评委看客户视角, 三方独立后 anchor_delta 暴露盲点. 这是 boss panel 的核心 leverage, REVIEW 必须保留.
"REVIEW 报告结构应跟 FRESH 一样, 给用户一致体验" — 错.
REVIEW 用户要的不一样 — 要的是 "原方案讲了什么 + 你们怎么看 + 我应该改什么". 不是 "你们调研出什么". 报告结构反映价值结构. 强行统一就是 ergonomic 优先压过 value.
7. 何时回看本 ADR
- Phase 4 实战验证 (用 ADR-005 跑 review 一次) 完成时: 验证 inv-1~5 是否真守住
- 任何 REVIEW 失败 case (doc parser 没解析出 decision section): trigger ADR-007 修订
- 5 次 REVIEW 跑下来后: 评估 anchor_delta 在 REVIEW 模式下是否仍有 mirror 价值 (语义微调是否影响 attribution)
- V1 期 (~ 2026-09-30): 评估是否加 v1.1 PDF/docx 支持
ADR-007 · accepted · 2026-05-28 · ADR 体系第 7 个 · /boss 第 3 种模式 · 6-8h 实施预算 · 5 决策 lock-down