sanguo_moziplus_v2/docs/design/archive-3.0/review-v3-vs-head-pangtong.md

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 逻辑（已删除）:

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}")

当前逻辑:

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 无严重不一致