auto-sync: 2026-05-28 22:38:12

docs/design/architecture-v3.0.md

@@ -757,6 +757,92 @@ route(task_info, action_type):
 
 **实现**: BootstrapBuilder 支持 `_load_template()` 加载模板文件，但实际的 prompt template 文件未完整创建。
 
+### 10.4 Prompt 进化（固定步骤 → 自主决策）📋
+
+> 来源：v2.8-direction-notes §三(2)，2026-05-27 讨论
+
+**问题**：当前 spawner 的 spawn prompt 把 Agent 限制在固定步骤（标 working → 干活 → 写产出 → 标 review），不够 AI Native。
+
+**设计方向**：从"固定步骤指令"变成"身份 + 目标 + 能做什么 + 约束 + 交接责任"：
+
+```markdown
+# 你的身份
+你是 {agent_name}，{agent_role}。擅长 {agent_capabilities}。
+
+# 你的任务
+{task_title}: {task_description}
+类型: {task_type} | 风险: {risk_level}
+必要条件: {must_haves}
+
+# 你能做什么
+通过 API 操作黑板（{api_base}）:
+- 读任何任务详情: GET /api/projects/{pid}/tasks/{id}?expand=all
+- 读所有活跃任务: GET /api/projects/{pid}/tasks
+- 写产出: POST /api/projects/{pid}/tasks/{id}/outputs
+- 写评论: POST /api/projects/{pid}/tasks/{id}/comments
+- 更新状态: POST /api/projects/{pid}/tasks/{id}/status
+- 创建子任务: POST /api/projects/{pid}/tasks
+
+# 约束
+- 完成后必须写产出 + 标 review
+- 安全红线: {guardrails_summary}
+- 超时: {timeout} 分钟
+```
+
+**核心变化**：
+1. Agent 自己根据黑板信息决定执行策略，不按固定步骤走
+2. 给 Agent 黑板 API 完整能力列表，让 Agent 自主选择
+3. 对齐 v3.0 "Daemon 退化 + Agent 进化"方向
+
+**涉及文件**: `src/daemon/spawner.py`（spawn prompt 构建）、`prompt_templates/executor.md`（新建）
+
+**状态**: ❌ 方向已定，prompt 模板未重写
+
+### 10.5 Handoff 上下文（Agent 间交接）📋
+
+> 来源：v2.8-direction-notes §三(3)，2026-05-27 讨论
+
+**问题**：Agent 完成任务后没有结构化的交接文档，下一个 Agent 缺少上下文。当前 handoff comment_type 已支持（§7.4），但无 Schema 约束和自动注入。
+
+**设计方向**：
+1. 新建 `schemas/handoff.schema.json` — 定义 handoff comment 的结构化格式
+2. `bootstrap.py` 增强 — spawn 时读取上一个 Agent 的 handoff comment 注入 prompt
+3. Review 流程增加 handoff 检查 — 无 handoff comment 则提醒
+4. `GET /comments?comment_type=handoff` API 已实现（§7.4），无需改动
+
+**灵感来源**: MattPocock Handoff（Agent 主动写交接文档传递上下文）
+
+**涉及文件**: `schemas/handoff.schema.json`（新建）、`src/daemon/bootstrap.py`、`src/daemon/review.py`
+
+**状态**: ❌ Schema 未创建，bootstrap 未增强
+
+### 10.6 知识注入（L3 Wiki 知识 → Agent Prompt）📋
+
+> 来源：v2.8-direction-notes §三(4) + §六，2026-05-27 讨论
+
+**问题**：Agent prompt 缺少领域知识，决策质量依赖 prompt 中的硬编码信息。当前 L3 层（§10.1）设计为"项目知识"，但注入机制未实现。
+
+**设计方向**：
+1. `spawner.py` 新增 `_inject_wiki_knowledge()` — 含 rg 检索 + grep fallback
+2. `bootstrap.py` 内部调用 wiki knowledge 层
+3. LLM Wiki 三层架构直接复用，不另建
+4. 知识检索日志记录（什么知识被注入了，效果如何）
+
+**调研结论**（来自 v2.8-direction-notes §六）：
+
+| 方案 | 评估 | 结论 |
+|------|------|------|
+| Ripgrep 直接检索 | ✅ 最简单有效 | 采纳，作为主方案 |
+| CodeGraph AST 索引 | ❌ 对知识文档无用 | 不采纳 |
+| Understand Anything | ⚠️ 适合人工探索 | 不用于运行时注入 |
+| MattPocock Handoff | ✅ Agent 交接 | 已采纳为 §10.5 |
+
+**前置条件**: NAS `/Volumes/KnowledgeBase` 挂载路径问题需先解决（当前 `/Volumes/KnowledgeBase-1`）
+
+**涉及文件**: `src/daemon/spawner.py`、`src/daemon/bootstrap.py`
+
+**状态**: ❌ 未实施
+
 ---
 
 ## §11. 前端

src/daemon/spawner.py

@@ -390,8 +390,15 @@ curl -X POST http://{self.api_host}:{self.api_port}/api/projects/{project_id}/ta
             await self.counter.acquire(agent_id, _sid_key)
 
         # 3.5 on_checks_passed: 所有检查通过后的回调（session + counter）
+        # 注意：如果回调抛异常，counter 已 acquire 但 subprocess 未启动，
+        # wrapped_on_complete 不会执行。需在此 try/except 中手动 release。
         if on_checks_passed:
-            on_checks_passed()
+            try:
+                on_checks_passed()
+            except Exception:
+                if self.counter:
+                    self.counter.release(agent_id, _sid_key)
+                raise
 
         if self.dry_run:
             logger.info("[DRY RUN] Would spawn agent %s (session=%s)", agent_id, _sid_key)