cfdaily
247 lines
10 KiB
Markdown
247 lines
10 KiB
Markdown
# v2.8 设计方向备忘
|
||
|
||
**日期**: 2026-05-27
|
||
**作者**: 庞统
|
||
**状态**: 持续讨论中，逐步完善
|
||
**最后更新**: 2026-05-27 08:00（第二轮讨论结论更新）
|
||
|
||
---
|
||
|
||
## 一、核心方向：Daemon 退化 + Agent 进化
|
||
|
||
> **黑板是精髓，不是任何单个 Agent。** 所有 Agent 读黑板、想、行动、写回。Daemon 是投递员，不是决策者。
|
||
|
||
### 业界印证
|
||
|
||
| 系统 | 做法 | 关键点 |
|
||
|------|------|--------|
|
||
| **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 自己根据黑板信息决定执行策略。
|
||
|
||
**已归档**：
|
||
- 调研报告：`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、降出错率），不是必须项。
|
||
|
||
### 4. 不做 Skill 集群模板（和 Agent 自主决策矛盾）
|
||
|
||
知识管理体系 v1 设计里的 Skill 集群模板（feature-development / data-acquisition 等预设流程），和"Agent 自主决策"方向矛盾。Agent 应该自己根据黑板信息决定执行策略，不按预设模板走。
|
||
|
||
---
|
||
|
||
## 三、要做的事
|
||
|
||
### v2.8：Mail 独立（代码整理，不改功能）
|
||
|
||
Mail 是机械投递，不需要智能。当前 46 处 if/_mail 散落在三个文件（ticker 14 + dispatcher 23 + spawner 9），设计很差。
|
||
|
||
**做法**：
|
||
- 新建 `mail_handler.py`，集中 Mail 投递逻辑
|
||
- ticker/dispatcher/spawner 里的 Mail 方法标注废弃
|
||
- 不新建 Pipeline 框架，不搞 PipelineRouter
|
||
- 改动量：~100 行新建 + ~30 行调用替换
|
||
|
||
### v2.9：Prompt 进化（从固定步骤 → 自主决策）
|
||
|
||
**当前 prompt 的问题**：把 Agent 限制在固定步骤（标 working → 干活 → 写产出 → 标 review）。
|
||
|
||
**改 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.9 的一部分：知识注入（复用 LLM Wiki）
|
||
|
||
**不需要新建知识库。** LLM Wiki 已有 273 页 wiki-vault + 118 个 practices 页面，就是现成的 L3 知识层。
|
||
|
||
**做法**：Daemon spawn 前用 wiki-query 的检索原语（第 1 级：grep index.md），把匹配到的 summary 注入 prompt。
|
||
|
||
```python
|
||
def _inject_wiki_knowledge(self, task, prompt):
|
||
"""spawn 前从 wiki-vault 检索相关知识，注入 summary"""
|
||
vault_path = Path(self.config.get("wiki_vault_path", ""))
|
||
if not vault_path.exists():
|
||
return prompt
|
||
|
||
keywords = self._extract_keywords(task.title + " " + (task.description or ""))
|
||
related = []
|
||
for kw in keywords[:3]:
|
||
result = subprocess.run(
|
||
["rg", "-i", kw, str(vault_path / "index.md")],
|
||
capture_output=True, text=True, timeout=3
|
||
)
|
||
for line in result.stdout.strip().split("\n")[:2]:
|
||
if not line or "[[" not in line:
|
||
continue
|
||
if "—" in line:
|
||
summary = line.split("—", 1)[1].strip()[:100]
|
||
page_name = line.split("[[")[1].split("]]")[0].split("|")[0]
|
||
related.append(f"- [[{page_name}]] — {summary}")
|
||
|
||
if related:
|
||
prompt += "\n\n## 相关知识（来自 LLM Wiki）\n" + "\n".join(related[:5])
|
||
prompt += "\n（如需详细信息，用 exec rg 读取完整页面）"
|
||
return prompt
|
||
```
|
||
|
||
### v2.10+：Agent 进化
|
||
|
||
- Agent 自主 claim（从 Daemon 分配 → Agent 领活）
|
||
- Agent 间感知（comment + observation + @mention）
|
||
- Daemon 简化为纯投递员
|
||
|
||
---
|
||
|
||
## 四、关键洞察
|
||
|
||
### 1. 两层抽象：业务类型 vs 执行模式
|
||
|
||
| 层 | 定义 | 谁选 | 数量 | 例子 |
|
||
|----|------|------|------|------|
|
||
| **业务类型**（task_type） | 用户视角的"做什么" | 用户创建任务时选 | 无限扩展 | coding, review, data, deploy, research... |
|
||
| **执行模式** | 系统视角的"怎么跑" | Agent 自己决定 | 不需要预定义 | Agent 根据黑板信息自主判断 |
|
||
|
||
**业务类型无限扩展，执行模式不需要预定义。**
|
||
|
||
### 2. Agent 已经有黑板操作能力
|
||
|
||
API 已覆盖：读任务、写状态、写产出、写评论、写决策、写观察、创建任务、claim 任务。
|
||
|
||
**缺的不是工具，是 prompt 从"固定步骤"变成"自主决策"。**
|
||
|
||
### 3. 约束是硬的，执行是软的
|
||
|
||
| 类型 | 说明 | 实现方式 |
|
||
|------|------|---------|
|
||
| **硬约束** | guardrail 拦截、安全红线、审批要求 | Daemon 侧确定性代码 |
|
||
| **软执行** | 执行路径、步骤顺序、异常处理策略 | Agent 自主决策 |
|
||
|
||
### 4. 三个优秀实践的 prompt 结构对比
|
||
|
||
| 系统 | "能做什么"怎么表达 | "全局视角"怎么给 | 自主程度 |
|
||
|------|------------------|-----------------|---------|
|
||
| Claude Code | 工具列表（自动可用） | 文件系统自己读 | 高 |
|
||
| Hermes | kanban_* 工具集（环境变量激活） | kanban_show() 自己读 | 中 |
|
||
| 我们当前 | prompt 里写 curl 命令模板 | 不给全局 | 低 |
|
||
|
||
### 5. LLM Wiki 和知识管理的关系
|
||
|
||
| 知识管理体系 | 和本设计关系 | 说明 |
|
||
|------------|-------------|------|
|
||
| **LLM Wiki 三层架构** | ✅ 直接用 | 就是 L3 知识层，不需要另建 |
|
||
| **wiki-query skill** | ✅ 直接用 | 检索分级原语直接复用 |
|
||
| **wiki-ingest skill** | ✅ 后续用 | 新调研结果可以 ingest 进 wiki |
|
||
| **记忆分区（memory/ 四区）** | ⚠️ 正交 | Agent 自身记忆管理，和 prompt 进化独立 |
|
||
| **Skill 三级约束** | ⚠️ 正交 | 产出格式约束，和执行自主度独立 |
|
||
| **Skill 集群模板** | ❌ 不做 | 和 Agent 自主决策方向矛盾 |
|
||
| **四层加载机制** | ✅ 对齐 | ①固化=SOUL.md ②注册=SKILL.md ③注入=BootstrapBuilder ④检索=wiki-query |
|
||
|
||
---
|
||
|
||
## 五、具体改动清单
|
||
|
||
| # | 事项 | 改动文件 | 改动量 | 依赖 |
|
||
|---|------|---------|--------|------|
|
||
| 1 | Mail 独立 | 新建 `mail_handler.py`，标注废弃 ticker/dispatcher/spawner | ~130 行 | 无 |
|
||
| 2 | Prompt 进化 | `spawner.py` SPAWN_PROMPT_TEMPLATE 重写 | ~50 行 | 无 |
|
||
| 3 | 知识注入 | `spawner.py` 新增 `_inject_wiki_knowledge()` | ~30 行 | NAS 挂载路径修正 |
|
||
| 4 | Bootstrap 增强 | `bootstrap.py` 支持 wiki knowledge 层 | ~20 行 | #3 |
|
||
|
||
### NAS 挂载路径问题
|
||
|
||
当前 `~/.obsidian-wiki/config` 配的是 `/Volumes/KnowledgeBase/wiki-vault/`，实际挂载在 `/Volumes/KnowledgeBase-1/wiki-vault/`。需要修正。
|
||
|
||
---
|
||
|
||
## 六、调研产出归档
|
||
|
||
本次讨论过程中产出的调研报告（不再作为设计依据，但保留参考价值）：
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `docs/research/pipeline-architecture-research.md` | 28场景 + 8业界实践 + 6设计模式调研 |
|
||
| `docs/design/v2.8-pipeline-architecture.md` | Pipeline 架构设计 v1.0~v2.0（已废弃） |
|
||
| `docs/design/v2.8-task-type-pipeline.md` | Task Type Pipeline 设计（已废弃） |
|
||
| `docs/design/v2.7.2-pipeline-refactor.md` | v2.7.2 Pipeline 分离设计（部分已完成） |
|
||
|
||
---
|
||
|
||
## 七、参考文件
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| PRD v3.0 | `docs/PRD-v3.0.md` |
|
||
| architecture-v2.6 | `docs/design/architecture-v2.6.md` |
|
||
| 知识管理方案简述 | `~/.openclaw/sanguo_projects/sanguo_moziplus/docs/research/knowledge-management-brief.md` |
|
||
| 知识管理完整设计 | `~/.openclaw/sanguo_projects/sanguo_moziplus/docs/research/knowledge-management-v2.2.md` |
|
||
| LLM Wiki Skill | `~/.sanguo_projects/sanguo_mozi/skills/wiki/llm-wiki/SKILL.md` |
|
||
| wiki-query Skill | `~/.sanguo_projects/sanguo_mozi/skills/wiki/wiki-query/SKILL.md` |
|
||
| Wiki Vault | `/Volumes/KnowledgeBase-1/wiki-vault/`（273 页，118 practices） |
|
||
|
||
---
|
||
|
||
## 八、下一步
|
||
|
||
1. 🔜 Mail 独立（mail_handler.py）
|
||
2. 🔜 Prompt 进化（改 SPAWN_PROMPT_TEMPLATE）
|
||
3. 🔜 NAS 挂载路径修正
|
||
4. 🔜 知识注入（复用 LLM Wiki index.md 检索）
|
||
5. 🔜 Agent 进化（自主 claim + 间感知）
|
||
6. 🔜 Daemon 简化（退化为投递员）
|