auto-sync: 2026-05-28 20:00:57

docs/design/architecture-v3.0.md

@@ -1129,6 +1129,36 @@ SSEEventType:
 
 ---
 
+### 19.5 Mail 模块硬编码问题 ⚠️ TODO（待 v2.8 TaskType Pipeline 统一解决）
+
+**现状**: `_mail` 作为虚拟 Project ID，在 dispatcher、spawner、blackboard_routes 中大量硬编码：
+
+| 文件 | 硬编码位置 | 用途 |
+|------|-----------|------|
+| dispatcher.py L127,186 | `project_id == "_mail"` | 跳过 guardrail、标 working、on_complete |
+| spawner.py L242,251,256 | `project_id == "_mail"` | 精简 prompt、直接 done 不走 review |
+| blackboard_routes.py | `project_id == "_mail"` | 邮件 API 路由 |
+
+**问题**:
+1. 新增 Task 类型时需要到处加 `if project_id == "_xxx"` 分支
+2. Mail 的特殊行为（精简 prompt、不走 review、auto-working）分散在多个文件
+3. 没有统一的 Task 类型配置表
+
+**设计方向**（v2.8 TaskType Pipeline）:
+- 每个 Project 有 `task_type` 配置（mail/general/custom）
+- 行为差异通过策略模式解决：`TaskPipeline.execute(route → pre_spawn → spawn → post_complete → verify)`
+- Mail 特殊逻辑收敛到 `MailPipeline` 类
+
+**参考**: `docs/design/archive-2.0/v2.8-task-type-pipeline.md`（已设计未实施）
+
+**当前 on_checks_passed 方案**（v2.7.3 临时修复）:
+- spawner 新增 `on_checks_passed` 参数，check 通过后、subprocess 前回调
+- dispatcher 传入 `_mail_auto_working` 作为回调
+- subprocess 失败时通过 `_mail_marked_working` flag 决定是否 revert
+- VALID_TRANSITIONS[working] 已加入 pending（正式合法化）
+
+---
+
 ## §20. 技术选型
 
 ### 20.1 核心技术栈 ✅