auto-sync: 2026-05-14 11:09:56

docs/design/architecture-v2.md

@@ -2046,6 +2046,70 @@ Agent 不需要“订阅”事件流，而是在被调用时通过 read 文件
   → 不需要等步骤“完成”才发现问题
 ```
 
+#### 3.12.7 实现注意事项（司马懿第四轮评审反馈，v2.4 补充）
+
+> 司马懿判定：v2.4 设计方向正确，可进入实现。以下为实现时必须注意的 5 个细节。
+
+**1. Agent 自主的真实边界**
+
+Agent 在执行开始时获取全局快照（read status.json + observations/），**执行过程中不感知变化**。
+并行执行场景下，如果需要运行时感知，由庞统通过 steer 触发。
+不在文件监控或实时推送上过度承诺。
+
+**2. Observation 通知机制**
+
+不依赖 inotify/fswatch（macOS 可靠性存疑，SMB 挂载不工作）。
+改为：**Agent 写入 observation 后主动 POST `/api/observations` 通知 daemon**，daemon 再通知庞统。
+更简单、更可靠、不依赖文件系统事件。
+
+**3. daemon vs 庞统的角色透明化**
+
+不要把 daemon 的确定性决策包装成"庞统定方向"。
+
+| 决策类型 | 执行者 | 性质 |
+|---------|-------|------|
+| Agent 选择算法 | daemon (selector.py) | 确定性 |
+| 状态流转规则 | daemon (orchestrator.py) | 确定性 |
+| 超时检测 | daemon (watchdog.py) | 确定性 |
+| 产出验证 | daemon (validator.py) | 确定性 + 可选 AI |
+| Phase 2 规划 | **庞统 AI** | AI 决策 |
+| Phase 3 异常裁决 | **庞统 AI** | AI 决策 |
+| 计划调整审批 | **庞统 AI** | AI 决策 |
+| 用户意图一致性检查 | **庞统 AI** | AI 决策 |
+
+**4. 文件系统可靠性细节**
+
+- `status.json` 更新必须使用 `atomic_write`（tmp → rename），复用 Section 2.1.4 的实现
+- observations 文件命名改为 `{agent}-{timestamp}-{uuid短}.md`，避免命名冲突
+- artifacts 目录在本地文件系统（Mac mini SSD），不写在 SMB 挂载上
+
+**5. Observation 写入标准与频率限制**
+
+task-bootstrap Skill 中必须明确写入标准：
+```
+observation 写入条件（必须满足至少一条）：
+- 发现了可能影响后续步骤的问题
+- 有能提升最终产出质量的建议
+- 遇到了专业外需要上报的问题
+禁止写入：进度报告、正常状态确认、无关细节
+```
+
+频率限制：每个步骤每个 Agent 最多 3 个 observation，超过由 daemon 丢弃并记录 warning。
+
+**6. 庞统上下文管理**
+
+每次被触发时，不把历史推理过程带入上下文，只带入当前状态快照。
+类似"每次被唤醒都是全新视角"——避免庞统 session 的上下文膨胀。
+
+**7. B1 贯穿性：用户意图一致性检查**
+
+当用户在执行中途改方向时（steer），庞统不只重新规划，还应先评估影响并帮用户决策：
+- "改成周线意味着数据量减少到 1/5，统计显著性可能不够。你确定吗？"
+- "增加止损条件会导致策略复杂度上升，回测时间可能翻倍。要继续吗？"
+
+这是 PRD B1（AI 帮用户想清楚要什么）的全程贯穿，不限于 Phase 1。
+在庞统的 prompt 中加入"用户意图一致性检查"规则。
+
 ---
 
 ## 4. 已决策（全部）