# v3.0 vs HEAD 背靠背 Review — 庞统

**日期**: 2026-06-11
**范围**: v3.0 tag → HEAD（6 commits, Step 2-5 Task 五层架构重构）
**对比**: `git diff v3.0..HEAD` + 安装目录代码验证

---

## Part A: v3.0 逻辑丢失检查

### 方法论
v3.0 → HEAD 的重构将 `_mail_*` 硬编码逻辑统一为 handler 架构（TaskTypeRegistry + BaseTaskHandler）。核心变更：
- dispatcher.py: `_mail_on_checks_passed` / `_mail_on_complete` → `_handler_on_checks_passed` / `_handler_on_complete`
- spawner.py: `_build_mail_prompt` → handler.build_prompt
- ticker.py: `_mail_check_reply` → handler.check_completion, `_mail` 硬编码 → `TaskTypeRegistry.virtual_projects()`

### 检查结果

| # | 文件 | v3.0 逻辑 | 当前状态 | 严重度 | 说明 |
|---|------|----------|---------|--------|------|
| 1 | dispatcher.py | `_legacy_on_complete` 中 review verdict 处理（approved→done, 非 approved→@mention assignee） | **缺失** | 🔴 | 新版 `_legacy_on_complete` 在 `_is_review=True` 时只有 crash rollback，**没有 verdict 判断逻辑**。review agent 完成后任务永远不会从 review→done。**仅影响非 handler 项目（_general）**。handler 项目（_mail/_toolchain）的 review 由 TaskHandler.post_complete 正确处理 |
| 2 | dispatcher.py | `_mail_auto_working` / `_mail_auto_complete` / `_mail_revert_to_pending` 方法 | 保留但主流程不再调用 | 🟢 | 方法体仍存在（标记为 deprecated），主流程改走 handler.pre_spawn / handler.post_complete。正常的重构 |
| 3 | dispatcher.py | spawn 失败回退 `working→pending` | **逻辑改进** | 🟢 | v3.0 用 `_mail_revert_to_pending`（只处理 _mail），新版用通用 DB 操作处理所有 handler 项目 |
| 4 | spawner.py | `_build_mail_prompt` 精简模板 | **替换为 handler.build_prompt** | 🟢 | MailHandler 使用 PromptSection 组装，功能更完整 |
| 5 | spawner.py | `_build_api_section` 中 mail 直接 done | **替换为 handler.target_success_status** | 🟢 | 等价实现 |
| 6 | ticker.py | `_mail` 硬编码虚拟项目 | **替换为 TaskTypeRegistry.virtual_projects()** | 🟢 | 正常重构，可扩展 |
| 7 | ticker.py | `_mail_check_reply` 兜底（超时检查） | **替换为 handler.check_completion** | 🟢 | 等价实现，缩进正确 |
| 8 | ticker.py | `_dispatch_reviews` 跳过 `_mail` | **替换为 handler 检查** | 🟢 | 等价 |

### 🔴 严重问题 #1 详解

**位置**: `dispatcher.py` L250-260 `_legacy_on_complete`

**v3.0 逻辑**（已删除）:
```python
if _is_review:
    if _task_db and outcome in ("completed", "session_revived"):
        # 读 verdict
        if verdict == "approved":
            _dispatcher._mark_task_status(_task_db, _task_id, "done")
        else:
            # @mention assignee + 保持 review
            bb.add_comment(_task_id, "daemon", f"@{assignee} 审查结论: {verdict_str}")
```

**当前逻辑**:
```python
def _legacy_on_complete(aid, outcome):
    if outcome in ROLLBACK_CURRENT_AGENT_OUTCOMES and _task_db:
        _dispatcher._rollback_current_agent(_task_db, _task_id, aid)
    if not _is_review:  # ← review 时什么都不做
        _dispatcher._task_auto_complete(_task_id, _task_db)
```

**影响**: `_dispatch_reviews` (ticker.py:1307) 对非 handler 项目会 dispatch review agent。review agent 完成后走 `_legacy_on_complete`，但 `_is_review=True` 时逻辑为空。任务永远停在 `review` 状态。

**修复方案**: 在 `_legacy_on_complete` 中补充 review verdict 处理逻辑，或让非 handler 项目也走 TaskHandler（注册 `_general` 到 TaskTypeRegistry）。

---

## Part B: 专题 01-13 设计编码一致性

### 专题 01: 四相循环（不参考实现，只检查设计遗漏）

| # | 设计描述 | 代码状态 | 一致性 | 说明 |
|---|---------|---------|--------|------|
| 1 | §3.3 Spawn Prompt 框架（任务+约束+API+准则+完成标准） | ✅ BootstrapBuilder + PromptSection 实现 | ✅ | |
| 2 | §3.4 @mention 通知机制 | ✅ `_process_mentions` + `mention_queue` | ✅ | |
| 3 | §4 庞统 Review 机制（三问） | ✅ review agent + verdict 处理 | ✅ | |

**设计遗漏**: 无明显遗漏。

### 专题 02: Main Session + Delegation

| # | 设计描述 | 代码状态 | 一致性 | 说明 |
|---|---------|---------|--------|------|
| 1 | 3.1 投递到 Main Session | ✅ `use_main_session=True` 参数 | ✅ | |
| 2 | 3.2 Delegation（subagent-delegation skill） | ✅ 外部 skill，不在此代码库 | ✅ | |
| 3 | 3.3 续杯机制 | ✅ `use_main_session=True` + session 复用 | ✅ | |
| 4 | 4.1 投递消息格式 | ✅ dispatcher 构建 | ✅ | |
| 5 | 4.3 消息优先级与中断策略 | ❌ 无优先级队列 | ⚠️ | 设计描述了优先级但未实现，非关键 |
| 6 | 4.4 Subagent 背压控制 | ❌ 无显式背压 | ⚠️ | 靠 counter 间接控制 |

### 专题 03: Prompt 进化

| # | 设计描述 | 代码状态 | 一致性 | 说明 |
|---|---------|---------|--------|------|
| 1 | 3.1 广播认领模板改写 | ✅ PromptSection 组装 | ✅ | |
| 2 | P4 群体智能（Boids） | ✅ agent 自主决策 | ✅ | 设计原则，非具体代码 |
| 3 | P6 反静默降级 | ❌ 无 scope reduction detection 自动机制 | ⚠️ | 设计原则，未自动实现 |
| 4 | P7 经验闭环 | ❌ 无 IMPROVE 阶段自动触发 | ⚠️ | P4 级待实现 |

### 专题 04: 黑板协作模型

| # | 设计描述 | 代码状态 | 一致性 | 说明 |
|---|---------|---------|--------|------|
| 1 | 3.1 assignee 降级为显示字段，路由走 @mention | 🟡 assignee 仍做直接路由 | ⚠️ | router.py L160-166 仍有 assignee 快速路径。设计说 Phase 1 双轨并行，当前停在 Phase 1。未迁移到 Phase 2 |
| 2 | 3.2 @mention 语义增强（mention_queue + comment_type） | ✅ 已实现 | ✅ | |
| 3 | 3.3 多人协作模式（co_assignees） | ❌ 无 co_assignees 字段 | ❌ | 数据库无此列 |
| 4 | 3.4 信息关联模型（output↔comment link） | ❌ 无关联字段 | ❌ | outputs 表无 comment_id 列 |
| 5 | 3.5 层级查询 API | ✅ parent_task 支持 | ✅ | |

**总结**: 3.3 和 3.4 设计了但未实现。3.1 停在 Phase 1。

### 专题 05: 上下文四层架构

| # | 设计描述 | 代码状态 | 一致性 | 说明 |
|---|---------|---------|--------|------|
| 1 | L0 铁律层 | ✅ 通过 workspace 文件注入 | ✅ | |
| 2 | L1 角色层 | ✅ SOUL.md / IDENTITY.md | ✅ | |
| 3 | L2 引擎注入层 | ✅ BootstrapBuilder | ✅ | |
| 4 | L3 被动参考层 | ❌ 无 _inject_wiki_knowledge | ❌ | wiki 知识注入未实现 |

### 专题 06: PM2 Crash 恢复

| # | 设计描述 | 代码状态 | 一致性 | 说明 |
|---|---------|---------|--------|------|
| 1 | 4.1 总体流程（_startup_recover） | ✅ ticker.py:1614 | ✅ | |
| 2 | 4.2 claimed 状态恢复 | ✅ | ✅ | |
| 3 | 4.2 working 状态恢复 | ✅ `_recover_working_task` | ✅ | |
| 4 | 4.2 review 状态恢复 | ✅ `_recover_review_task` | ✅ | |
| 5 | 设计提到 7 个恢复方法 | 🟡 只看到 2 个公开方法 | ⚠️ | 可能在内部逻辑中覆盖，需详细检查 |

### 专题 07: Spawner Acquire-First

| # | 设计描述 | 代码状态 | 一致性 | 说明 |
|---|---------|---------|--------|------|
| 1 | Phase 0: Pre-acquire 修复 | ✅ L499-512 | ✅ | |
| 2 | Phase 1: Counter acquire | ✅ L516-521 | ✅ | |
| 3 | Phase 2: Session check | ✅ L523-568 | ✅ | |
| 4 | Phase 2.5: 假死修复 | ✅ L557-568 | ✅ | |
| 5 | O1: lock PID 死 + running 假死 | ✅ | ✅ | |
| 6 | O4: revive 清理 lock 文件 | ✅ | ✅ | |

### 专题 08: Classify Outcome 优化

| # | 设计描述 | 代码状态 | 一致性 | 说明 |
|---|---------|---------|--------|------|
| 1 | A0-A17 判定树 | ✅ `_classify_outcome` 方法 | ✅ | |
| 2 | A9 api_error 特殊路径 | ✅ api_retry_count | ✅ | |
| 3 | A14-A17 可恢复 retry + cooldown 60s | ✅ cooldown_seconds + set_cooldown | ✅ | |
| 4 | Gateway Watchdog | ✅ 外部脚本 | ✅ | |
| 5 | Registry 逻辑删除 | ✅ | ✅ | |

### 专题 09: Rebuttal + Goal Gate

| # | 设计描述 | 代码状态 | 一致性 | 说明 |
|---|---------|---------|--------|------|
| 1 | 2.1 Rebuttal 自动化（review 非 approved → @mention assignee） | ✅ task_handler.py handle_review_complete + ticker.py _rebuttal_on_complete | ✅ | |
| 2 | 2.1 防止无限循环（max 2 轮） | ✅ RebuttalManager.MAX_ROUNDS | ✅ | |
| 3 | 2.2 目标一致性 Gate | ❌ 无 goal gate 自动检查 | ⚠️ | 设计为 Agent 端行为，非 Daemon 侧 |
| 4 | _task_on_complete 改动（design §2.1 代码改动） | 🟡 已移到 handler | ✅ | 重构后的等价位置 |

### 专题 10: T3 需求探索 + 黑板展示

| # | 设计描述 | 代码状态 | 一致性 | 说明 |
|---|---------|---------|--------|------|
| 1 | A2: 需求探索过程写黑板 comments | ✅ 后端支持 comment_type | ✅ | |
| 2 | A3: TaskModal 实时刷新 | ✅ SSE comment_added/checkpoint_resolved | ✅ | |
| 3 | D1: 砍掉 AI 摘要 | ✅ 黑板直投前端 | ✅ | |
| 4 | D2: SSE 只做通知 | ✅ 前端按需拉数据 | ✅ | |

### 专题 11: 上下文四层重设计

| # | 设计描述 | 代码状态 | 一致性 | 说明 |
|---|---------|---------|--------|------|
| 1 | L2 操作规范型 6 个 skill 全文注入 | ❌ BootstrapBuilder 只注入通用 prompt，无 skill 全文注入 | ❌ | 设计 §2.3 要求将 6 个操作规范型 skill（blackboard-executor, code-review 等）全文注入 L2，bootstrap.py 无此逻辑 |
| 2 | L3 _inject_wiki_knowledge | ❌ 完全未实现 | ❌ | |
| 3 | review_protocols/ 目录 | ❌ 目录不存在 | ❌ | |
| 4 | 2.3 提到的 handoff.schema.json | ❌ 不存在 | ❌ | |

**总结**: 专题 11 大部分 L2/L3 改造未实现。BootstrapBuilder 做了基础框架但缺少 skill 注入和知识注入。

### 专题 12: Pipeline 设计

| # | 设计描述 | 代码状态 | 一致性 | 说明 |
|---|---------|---------|--------|------|
| 1 | §3 Pipeline 注册表（pipeline 字段） | ❌ 无 pipeline 数据结构 | ❌ | |
| 2 | §4 路由逻辑更新（task_type 路由） | ❌ router.py 无 task_type 路由 | ❌ | |
| 3 | §8 Pipeline 引擎 + PipelineRegistry | ❌ 不存在 | ❌ | |
| 4 | §8.2 状态流转校验 | ❌ 无 flow_rules | ❌ | |
| 5 | §9 实施路线标记为 "待实现" | — | — | 设计文档本身就标记为 TODO |

**总结**: Pipeline 整个设计未实施。设计文档 §9 自身标记为待实现。

### 专题 13: 工具链开发工作流（不参考实现，只检查设计遗漏）

| # | 设计描述 | 代码状态 | 一致性 | 说明 |
|---|---------|---------|--------|------|
| 1 | §16 工具链事件中枢 | ✅ toolchain_routes.py + toolchain_handler.py | ✅ | |
| 2 | Gitea webhook 处理 | ✅ 5 模板 + 去重 | ✅ | |
| 3 | CI 前缀 [CI] | ✅ | ✅ | |
| 4 | §5 CI/CD 管道设计 | 🟡 Gitea Actions 为主，非 Daemon 侧 | ✅ | |

**设计遗漏**: 无明显遗漏。

---

## 汇总

### 🔴 严重（需修复）

| # | 问题 | 影响 |
|---|------|------|
| A1 | `_legacy_on_complete` review verdict 处理丢失 | 非 handler 项目（_general）的 review agent 完成后任务永远停在 review 状态 |

### 🟡 中等（设计-代码不一致，可后续处理）

| # | 专题 | 设计描述 | 实际状态 |
|---|------|---------|---------|
| B4-1 | 04 黑板协作 | 3.1 assignee 降级 Phase 2 | 停在 Phase 1 |
| B4-3 | 04 黑板协作 | 3.3 co_assignees 多人协作 | 未实现 |
| B4-4 | 04 黑板协作 | 3.4 output↔comment 关联 | 未实现 |
| B5-4 | 05 上下文层 | L3 wiki 知识注入 | 未实现 |
| B11-1 | 11 上下文重设计 | L2 操作规范型 skill 全文注入 | 未实现 |
| B11-2 | 11 上下文重设计 | handoff.schema.json | 未实现 |
| B11-3 | 11 上下文重设计 | review_protocols/ 目录 | 未实现 |
| B12 | 12 Pipeline | 整个 Pipeline 引擎 | 未实现（设计自标 TODO） |

### 🟢 正常（重构等价或设计已标记待实现）

- _mail_* 方法 deprecated 但保留（平滑迁移）
- handler 架构统一替代硬编码（等价实现）
- 专题 01/02/03/06/07/08/09/10/13 无严重不一致
