auto-sync: 2026-05-27 00:55:29

docs/design/v2.8-direction-notes.md

@@ -2,57 +2,105 @@
 
 **日期**: 2026-05-27  
 **作者**: 庞统  
-**状态**: 方向确认，记录备忘
+**状态**: 方向确认，记录备忘  
+**最后更新**: 2026-05-27 00:54（完整讨论结论）
 
 ---
 
-## 核心方向：Daemon 退化 + Agent 进化
+## 一、核心方向：Daemon 退化 + Agent 进化
 
-业界印证（Claude Code Agent Teams / Hermes Kanban）都在往这个方向走。
+> **黑板是精髓，不是任何单个 Agent。** 所有 Agent 读黑板、想、行动、写回。Daemon 是投递员，不是决策者。
 
-| 当前（v2.7） | 未来（AI Native） |
-|-------------|-------------------|
-| Daemon = 调度器 + 路由器 + 决策者 | Daemon = 投递员 + 看护人 |
-| Agent = 被动执行者（拿到固定步骤 prompt） | Agent = 自主决策者（读黑板→想→干→写回） |
+### 业界印证
+
+| 系统 | 做法 | 关键点 |
+|------|------|--------|
+| **Claude Code Agent Teams** | Agent 自己 flock() claim 任务，Team Lead 只协调 | Agent 自己决定看什么、干什么 |
+| **Hermes Kanban** | Agent 有 kanban_* 工具直接操作黑板 | 工具驱动，不是 prompt 指令驱动 |
+| **PRD v3.0** | "黑板是唯一真相源，所有 Agent 读它、想、行动、写回结果" | 最激进：peer-to-peer 感知 |
+
+### 当前 vs 未来
+
+| 维度 | 当前（v2.7 实现） | 未来（AI Native） |
+|------|------------------|-------------------|
+| Daemon 角色 | 调度器 + 路由器 + 决策者 | 投递员 + 看护人 |
+| Agent 角色 | 被动执行者（固定步骤 prompt） | 自主决策者（读黑板→想→干→写回） |
+| 谁决定执行路径 | Daemon（if/else + YAML） | Agent（根据黑板信息自主判断） |
+| Agent 间通信 | 无（Daemon 中央调度） | 黑板 comment + observation + @mention |
 
 ---
 
-## 不做的事
+## 二、不做的事（明确排除）
 
-1. **不做 Pipeline 框架**（PipelineRouter / SingleStepPipeline / MultiStepPipeline / ParallelPipeline）
-   - 各种执行模式（parallel/loop/saga/interactive）不需要代码层面的 Pipeline 类
-   - Agent 自己根据黑板信息决定执行策略
+### 1. 不做 Pipeline 框架
 
-2. **不做黑板摘要注入**
-   - Agent 已经有 API 能力读黑板全局状态
-   - 让 Agent 自己决定看什么，比系统预注入更 AI native
-   - 当前 prompt 确实需要改，但改的是"告诉 Agent 能做什么"，不是"帮 Agent 把数据准备好"
+PipelineRouter / SingleStepPipeline / MultiStepPipeline / ParallelPipeline —— 不需要。
 
-3. **不做 blackboard_* 工具封装**
-   - 当前 curl + API 方式已经能用
-   - 工具封装是优化项（省 token、降出错率），不是必须项
-   - 优先级低，v2.10 再考虑
+**原因**：各种执行模式（parallel/loop/saga/interactive）是执行路径的选择，不是代码层面的 Pipeline 类。Agent 自己根据黑板信息决定执行策略。
+
+**已归档**：
+- 调研报告：`docs/research/pipeline-architecture-research.md`
+- Pipeline 设计 v1.0~v2.0：`docs/design/v2.8-pipeline-architecture.md`
+- v2.8 task type 设计：`docs/design/v2.8-task-type-pipeline.md`
+
+### 2. 不做黑板摘要注入
+
+**原因**：Agent 已经有 API 能力读黑板全局状态。让 Agent 自己决定看什么，比系统预注入更 AI native。
+
+**结论**：谁决定信息需求 = 谁在决策。注入方式是系统决定信息需求，Agent 自己读是 Agent 决定。后者更 AI native。
+
+### 3. 不做 blackboard_* 工具封装（优先级低）
+
+当前 curl + API 方式已经能用。工具封装是优化项（省 token、降出错率），不是必须项。
 
 ---
 
-## 要做的事
+## 三、要做的事
 
 ### v2.8：Mail 独立（代码整理，不改功能）
 
-当前 46 处 if/_mail 散落在 ticker/dispatcher/spawner 里。Mail 是机械投递，不需要智能，独立出来：
+Mail 是机械投递，不需要智能。当前 46 处 if/_mail 散落在三个文件（ticker 14 + dispatcher 23 + spawner 9），设计很差。
 
+**做法**：
 - 新建 `mail_handler.py`，集中 Mail 投递逻辑
-- ticker/dispatcher/spawner 里的 Mail 方法标注废弃，调用改为 `mail_handler.tick()`
+- ticker/dispatcher/spawner 里的 Mail 方法标注废弃
 - 不新建 Pipeline 框架，不搞 PipelineRouter
+- 改动量：~100 行新建 + ~30 行调用替换
 
 ### v2.9+：Prompt 进化（从固定步骤 → 自主决策）
 
 **当前 prompt 的问题**：把 Agent 限制在固定步骤（标 working → 干活 → 写产出 → 标 review）。
 
-**改 prompt**：
-- 告诉 Agent 它能做什么（API 列表 + 能力说明）
-- 不告诉它具体步骤（让 Agent 自己决定）
-- 告诉它约束（安全红线、完成标准）
+**改 prompt 结构**：从"固定步骤指令"变成"身份 + 目标 + 能做什么 + 约束"：
+
+```markdown
+# 你的身份
+你是张飞，编码先锋。擅长快速实现策略代码、回测脚本。
+
+# 你的任务
+{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}/observations
+- 更新状态: POST /api/projects/{pid}/tasks/{id}/status
+- 创建子任务: POST /api/projects/{pid}/tasks
+
+# 约束
+- 完成后必须写产出 + 标 review
+- 失败了标 failed 并写明原因
+- 遇到阻塞标 blocked
+- 涉及数据删除/实盘交易 → 标 waiting_human 等人确认
+- {guardrail_rules}
+```
+
+**不告诉它具体步骤，只告诉它目标、工具、约束。Agent 自己决定怎么干。**
 
 ### v2.10+：Agent 进化
 
@@ -62,21 +110,69 @@
 
 ---
 
-## 场景覆盖方式
+## 四、关键洞察
 
-28 个场景不需要 28 种 Pipeline。Agent 自己根据黑板信息决定执行策略：
+### 1. 两层抽象：业务类型 vs 执行模式
 
-- 批量回测？张飞读黑板，看到多组参数，自己决定怎么拆
-- Saga 链？Agent 自己决定步骤链和补偿
-- 审议循环？司马懿自己决定是否通过，不通过就在黑板写驳回
+| 层 | 定义 | 谁选 | 数量 | 例子 |
+|----|------|------|------|------|
+| **业务类型**（task_type） | 用户视角的"做什么" | 用户创建任务时选 | 无限扩展 | coding, review, data, deploy, research... |
+| **执行模式** | 系统视角的"怎么跑" | Agent 自己决定 | 不需要预定义 | Agent 根据黑板信息自主判断 |
 
-**约束是硬的**（guardrail 拦截、成本上限、审批要求），执行是软的（Agent 自主决策）。
+**业务类型无限扩展，执行模式不需要预定义。** Agent 自己根据黑板信息决定是单步还是多步、要不要循环、要不要补偿。
+
+### 2. Agent 已经有黑板操作能力
+
+API 已覆盖：读任务、写状态、写产出、写评论、写决策、写观察、创建任务、claim 任务。
+
+**缺的不是工具，是 prompt 从"固定步骤"变成"自主决策"。**
+
+### 3. 约束是硬的，执行是软的
+
+| 类型 | 说明 | 实现方式 |
+|------|------|---------|
+| **硬约束** | guardrail 拦截、安全红线、审批要求 | Daemon 侧确定性代码 |
+| **软执行** | 执行路径、步骤顺序、异常处理策略 | Agent 自主决策 |
+
+### 4. 三个优秀实践的 prompt 结构对比
+
+| 系统 | "能做什么"怎么表达 | "全局视角"怎么给 | 自主程度 |
+|------|------------------|-----------------|---------|
+| Claude Code | 工具列表（自动可用） | 文件系统自己读 | 高 |
+| Hermes | kanban_* 工具集（环境变量激活） | kanban_show() 自己读 | 中 |
+| 我们当前 | prompt 里写 curl 命令模板 | 不给全局 | 低 |
 
 ---
 
-## 参考
+## 五、28 个场景在未来系统里怎么跑
 
-- PRD v3.0：`docs/PRD-v3.0.md`
-- architecture-v2.6：`docs/design/architecture-v2.6.md`
-- Pipeline 调研报告（归档）：`docs/research/pipeline-architecture-research.md`
-- v2.8 Pipeline 设计（归档，已被本方向替代）：`docs/design/v2.8-pipeline-architecture.md`
+**不需要为每种场景设计 Pipeline。Agent 自己根据黑板信息决定。**
+
+| 场景 | 谁 decides 怎么做 | Daemon 做什么 |
+|------|------------------|--------------|
+| B1 定时数据采集 | 赵云读黑板，自己决定下载什么、怎么验证 | cron 触发 → 创建任务 → spawn 赵云 |
+| B3 批量回测 | 张飞读黑板，看到多组参数，自己决定怎么拆 | 创建任务 → spawn 张飞 |
+| C2 Saga 链 | Agent 自己决定步骤链和补偿 | 创建任务 → spawn Agent |
+| E1 审议循环 | 司马懿自己决定是否通过，不通过写驳回 | spawn 司马懿 |
+| E4 自愈 | Agent 读黑板，自己诊断修复 | 事件触发 → spawn Agent |
+
+---
+
+## 六、参考文件
+
+| 文件 | 说明 |
+|------|------|
+| PRD v3.0 | `docs/PRD-v3.0.md` |
+| architecture-v2.6 | `docs/design/architecture-v2.6.md` |
+| 方向备忘（本文件） | `docs/design/v2.8-direction-notes.md` |
+| Pipeline 调研报告（归档） | `docs/research/pipeline-architecture-research.md` |
+| Pipeline 设计 v2.0（归档） | `docs/design/v2.8-pipeline-architecture.md` |
+
+---
+
+## 七、下一步
+
+1. ✅ Mail 独立（mail_handler.py）
+2. ✅ Prompt 进化（改 SPAWN_PROMPT_TEMPLATE）
+3. 🔜 Agent 进化（自主 claim + 间感知）
+4. 🔜 Daemon 简化（退化为投递员）