diff --git a/docs/design/architecture-v2.md b/docs/design/architecture-v2.md index 3c5e89a..b17f701 100644 --- a/docs/design/architecture-v2.md +++ b/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. 已决策(全部)