cfdaily
690 lines
29 KiB
Markdown
690 lines
29 KiB
Markdown
# #05 上下文四层架构 — 改造方案
|
||
|
||
> 版本: v2.0
|
||
> 日期: 2026-05-30
|
||
> 作者: 庞统（副军师）
|
||
> 状态: 设计中
|
||
> 前置: #02 Main Session + Delegation, #03 Prompt 进化, #04 黑板协作模型
|
||
> 来源: architecture-v3.0.md §10.1, technical-design-v2.6.md §5, v2.8-direction-notes, distill-full-design.md, distill-integration-plan.md, v2.6-research-04
|
||
|
||
---
|
||
|
||
## 一、原始四层定义（对齐设计）
|
||
|
||
```
|
||
L0 铁律层（~500 tokens） → Hook 注入，每轮强制，不占 bootstrap
|
||
L1 角色层（~2000 tokens） → SOUL.md / IDENTITY.md（Agent Workspace 自带）
|
||
L2 引擎注入层（~1500 tokens）→ BootstrapBuilder 按 role 精确拼装
|
||
L3 被动参考层（按需加载）→ SkillRegistry + OpenClaw Skills
|
||
```
|
||
|
||
### 设计初衷（为什么有这四层）
|
||
|
||
| 层 | 解决什么问题 | 核心机制 |
|
||
|---|---|---|
|
||
| **L0** | Agent 需要不可绕过的安全/行为底线 | Hook 每轮注入，不受 compaction 稀释 |
|
||
| **L1** | Agent 需要知道"我是谁、我擅长什么、团队怎么协作" | Workspace 文件由 Gateway 自动注入 |
|
||
| **L2** | 不同角色需要不同上下文——执行者需要 Guardrail，审查者需要 Review Protocol | BootstrapBuilder 按 role 精确拼装，不多不少 |
|
||
| **L3** | Agent 有 42+ 个 Skill，全量注入 token 爆炸 | description 注入列表，Agent 按需 read 全文 |
|
||
|
||
### L2 的 7 个注入组件
|
||
|
||
来源：technical-design-v2.6.md §5, topic4 D4-7
|
||
|
||
| 组件 | 内容 | 角色 |
|
||
|------|------|------|
|
||
| ① 操作规范 | `prompt_templates/{role}.md` — 角色的工作方式声明 | 所有 |
|
||
| ② 项目背景 | `project_context.yaml` | 所有 |
|
||
| ③ 任务上下文 | 黑板任务数据（title/description/must_haves/status） | 所有 |
|
||
| ④ 前序信息 | depends_on 产出摘要 + handoff comment | executor |
|
||
| ⑤ Guardrail 规则 | `guardrails.yaml` 的 rules + behavior_rules | executor |
|
||
| ⑥ 审查协议 | `review_protocols/*.yaml` | reviewer |
|
||
| ⑦ 经验注入 | experiences 表按 tag 匹配（最多 5 条） | executor, reviewer |
|
||
|
||
**精确注入原则**（D4-7）：
|
||
|
||
| 角色 | 注入 | 不注入 |
|
||
|------|------|--------|
|
||
| executor | ①②③④⑤⑦ | ⑥ |
|
||
| reviewer | ①②③⑥⑦ | ④⑤ |
|
||
| planner（庞统） | ①②③ + template_components | ④⑤⑥ |
|
||
| claim | ②③ + 任务列表 | ①④⑤⑥⑦ |
|
||
| mention | ②③ + 相关讨论 | ①④⑤⑥⑦ |
|
||
| review_pangtong | ①②③⑥ + 三问框架 | ④⑤ |
|
||
| review_simayi | ①②③⑥ + 质量检查清单 | ④⑤ |
|
||
|
||
### 两套 Skill 系统
|
||
|
||
| 系统 | 机制 | 内容 | 数量 |
|
||
|------|------|------|------|
|
||
| **OpenClaw 原生** | `extraDirs` 扫描 SKILL.md frontmatter → Agent 按 description 匹配 → `read` 全文 | 通用的 42 个 Skill（plan-act-verify, code-review, quant-backtest 等） | 42 |
|
||
| **moziplus SkillRegistry** | `skill_system.py` 注册 → Daemon 构建 prompt 时匹配注入 description | moziplus 专用 Skill（蒸馏经验、审查协议等） | 4（蒸馏）+ 未来扩展 |
|
||
|
||
**关系**：moziplus 专用为主，但未来可能有重叠（如 superpower 加入、通用 Skill 被 Daemon 注入）。两套系统按职责分工：OpenClaw 管理 Agent 自己发现的 Skill，moziplus 管理 Daemon 注入的 Skill。
|
||
|
||
---
|
||
|
||
## 二、现状 vs 设计 Gap
|
||
|
||
### L0 铁律层
|
||
|
||
| 设计 | 现状 | Gap |
|
||
|------|------|-----|
|
||
| 安全红线（rules）6 条 | ✅ `config/guardrails.yaml` 已有 | 无 |
|
||
| 行为铁律（behavior_rules）2 条 | ❌ 未合并，存在 `guardrails/` 孤儿文件 | 待合并 |
|
||
| GATE 铁律 | ✅ gate-enforcer Hook 已注入 | 无 |
|
||
| Delegation 铁律 | ✅ gate-enforcer Hook 已注入 | 需适配 #02 Main Session |
|
||
| GATE 产出物检查 | ✅ gate-enforcer before_tool_call | 无 |
|
||
|
||
### L1 角色层
|
||
|
||
| 设计 | 现状 | Gap |
|
||
|------|------|-----|
|
||
| SOUL.md 人格 | ✅ 各 Agent 已有 | 缺**专长声明**段 |
|
||
| AGENTS.md 团队规则 | ⚠️ 各 Agent 有，但内容是 v1 mozi 时代的 | 需重写为 **v2 黑板协作指南** |
|
||
| TOOLS.md 工具配置 | ⚠️ 各 Agent 有 | 缺**黑板 API 参考** |
|
||
| IDENTITY.md | ⚠️ 空模板 | 可选，不阻塞 |
|
||
|
||
### L2 引擎注入层
|
||
|
||
| 设计 | 现状 | Gap |
|
||
|------|------|-----|
|
||
| ① 操作规范 `prompt_templates/*.md` | ❌ 目录不存在，5 个角色模板未创建 | **核心 Gap** |
|
||
| ② 项目背景 | ❌ BootstrapBuilder 未实例化 | 同上 |
|
||
| ③ 任务上下文 | ❌ BootstrapBuilder 未实例化 | 同上 |
|
||
| ④ 前序信息 + handoff | ❌ BootstrapBuilder 未实例化 | 同上 |
|
||
| ⑤ Guardrail 规则 | ❌ BootstrapBuilder 未实例化 | 同上 |
|
||
| ⑥ 审查协议 `review_protocols/*.yaml` | ❌ 目录不存在 | 待创建 |
|
||
| ⑦ 经验注入 experiences 表 | ❌ 表不存在，119 条数据未导入 | 待建表 |
|
||
| Daemon prompt 模板 | ⚠️ 6 个模板存在但风格是固定步骤 | 需重写（#03 Prompt 进化） |
|
||
| BootstrapBuilder 实例化 | ❌ `main.py` 中 `bootstrap_builder=None` | **关键：从未启用** |
|
||
|
||
**一句话**：BootstrapBuilder 代码框架完整，但从未被实例化。所有 L2 功能完全未启用。Daemon 的 prompt 构建走的是 spawner/ticker 的硬编码模板。
|
||
|
||
### L3 被动参考层
|
||
|
||
| 设计 | 现状 | Gap |
|
||
|------|------|-----|
|
||
| OpenClaw 原生 Skills（42 个） | ✅ `extraDirs` 已配置，Agent 可 read | 无 |
|
||
| moziplus SkillRegistry | ❌ `skill_system.py` 只认 .json，skills/ 为空 | 需支持 .md + 注册蒸馏 Skill |
|
||
| Skill description 四要素 | ⚠️ 部分 Skill 有，部分没有 | 按需优化（P3） |
|
||
|
||
---
|
||
|
||
## 三、各层改造方案
|
||
|
||
### L0 改造：保持极简，只放通用铁律
|
||
|
||
**改动量**：极小（维持现状，微调 delegation-rule）
|
||
|
||
**原则**：L0 只放跨系统通用的铁律。moziplus v2.0 特有的行为规范（如行为铁律细节、安全红线等）归入 L2 引擎注入层，不污染 L0。
|
||
|
||
#### L0-1：当前 L0 内容（保持不变）
|
||
|
||
- **GATE 铁律**（gate-enforcer prependContext）：需求不清不动手、根因不明不修复、方案未定不实现、评估过影响范围才动手、非平凡任务用 plan-act-verify skill
|
||
- **Delegation 铁律**（gate-enforcer prependContext）：收到 moziplus 投递的独立任务时优先使用 subagent-delegation skill
|
||
- **GATE 产出物检查**（gate-enforcer before_tool_call）：Agent 调 write/edit 前检查 gate.json
|
||
|
||
#### L0-2：微调 delegation-rule 适配 #02
|
||
|
||
当前：`收到 moziplus 投递的编码/文档/调研等独立任务时，优先使用 subagent-delegation skill`
|
||
|
||
改为：
|
||
```
|
||
收到 moziplus 投递的独立任务时：
|
||
- 编码/文档/调研等重活 → sessions_spawn(subagent, cleanup:"delete")
|
||
- 只需决策或确认 → 直接做
|
||
- 需要其他人协作 → 黑板 comment @ 对应 Agent
|
||
- 不懂 → 先在黑板提问，不要猜
|
||
```
|
||
|
||
#### 归入 L2 的内容
|
||
|
||
以下内容不进 L0，归入 L2 引擎注入层（角色模板或 BootstrapBuilder 动态拼装）：
|
||
- 行为铁律（GATE 流程细节、不绕圈子）→ `prompt_templates/executor.md` 的约束段
|
||
- 安全红线（guardrails.yaml rules）→ BootstrapBuilder ⑤Guardrail 组件，仅注入 executor
|
||
- 审查协议（review_protocols/）→ BootstrapBuilder ⑥审查协议组件，仅注入 reviewer
|
||
|
||
---
|
||
|
||
### L1 改造：Workspace 文件重写
|
||
|
||
**改动量**：中等（6 个 Agent × 3 个文件，以文本编辑为主）
|
||
|
||
#### L1-1：SOUL.md 加专长声明
|
||
|
||
每个 Agent 的 SOUL.md 在"我是谁"段后新增：
|
||
|
||
```markdown
|
||
## 我的专长
|
||
- ✅ 擅长：编码、实现、回测脚本、策略编码
|
||
- ❌ 不擅长：风控审核（找关羽）、数据获取（找赵云）、部署（找姜维）
|
||
|
||
只认领和执行符合专长的任务，不适合的不要抢。
|
||
```
|
||
|
||
各 Agent 专长：
|
||
|
||
| Agent | 擅长 | 不擅长 |
|
||
|-------|------|--------|
|
||
| zhangfei-dev | 编码、实现、脚本、策略编码 | 风控、数据、部署 |
|
||
| guanyu-dev | 风控、合规、仓位检查 | 编码实现、数据获取 |
|
||
| zhaoyun-data | 数据获取、清洗、验证 | 编码实现、风控 |
|
||
| jiangwei-infra | 部署、Docker、vnpy、NAS | 策略编码、风控 |
|
||
| simayi-challenger | 审查、质量检查、辩论 | 数据获取、部署 |
|
||
| pangtong-fujunshi | 规划、协调、策略研究 | 不执行具体编码 |
|
||
|
||
**目的**：Agent 从 L1 知道自己擅长什么，L2 的广播认领模板不需要再注入身份。
|
||
|
||
#### L1-2：AGENTS.md 重写为 v2 黑板协作指南
|
||
|
||
移除 v1 编排纪律（`cli.py`、mozi daemon 相关），替换为：
|
||
|
||
```markdown
|
||
## 黑板协作（moziplus v2）
|
||
|
||
黑板是你的工作空间。所有任务、讨论、产出都在黑板上。
|
||
|
||
### 你能做什么
|
||
- 读任务详情: GET http://localhost:8083/api/projects/{pid}/tasks/{id}?expand=all
|
||
- 读活跃任务: GET http://localhost:8083/api/projects/{pid}/tasks?status=working,claimed,review
|
||
- 认领任务: POST .../tasks/{id}/claim body: {"agent": "你的id"}
|
||
- 更新状态: POST .../tasks/{id}/status body: {"status": "working", "agent": "你的id"}
|
||
- 写产出: POST .../tasks/{id}/outputs body: {"agent": "你的id", ...}
|
||
- 写评论: POST .../tasks/{id}/comments body: {"author": "你的id", "body": "..."}
|
||
- 创建子任务: POST .../tasks body: {"title": "...", "parent_task": "父任务id", ...}
|
||
|
||
### 协作规则
|
||
1. **讨论用 comment** — 有疑问、要讨论、给反馈，写在黑板 comment 里
|
||
2. **@ 别人协作** — comment body 中 @zhangfei-dev 会自动通知对方
|
||
3. **不懂就问** — 任务描述不清、验收标准模糊、上下文不够，先在黑板 comment 提问，不要猜
|
||
4. **写交接** — 完成任务时写 comment_type=handoff，告诉下一个人你做了什么
|
||
5. **产出物 > 消息** — 产出写在 output 里，不只是 comment
|
||
6. **只认领符合专长的任务** — 参考 SOUL.md 的专长声明
|
||
|
||
### 状态流转
|
||
pending → claimed → working → review → done
|
||
↘ failed
|
||
↘ blocked
|
||
↘ waiting_human
|
||
|
||
### 对应 Skill
|
||
- 非平凡编码任务 → plan-act-verify skill
|
||
- 代码审查 → code-review skill
|
||
- 数据获取 → data-acquisition skill
|
||
- 部署 → deployment-infra skill
|
||
- 调研分析 → 先出方案等确认
|
||
```
|
||
|
||
#### L1-3：TOOLS.md 加黑板 API 速查
|
||
|
||
```markdown
|
||
## 黑板 API（moziplus v2）
|
||
- 端口: 8083
|
||
- 前端: http://localhost:8083/
|
||
- API Base: http://localhost:8083/api
|
||
- 项目 ID: 通过任务消息中的 project_id 获取
|
||
```
|
||
|
||
---
|
||
|
||
### L2 改造：BootstrapBuilder 启用 + 角色模板 + Prompt 进化
|
||
|
||
**改动量**：核心改造，代码 ~150 行 + 5 个模板文件
|
||
|
||
这是最大也最关键的一层改造。分三个阶段：
|
||
|
||
#### Phase 1：启用 BootstrapBuilder
|
||
|
||
**改动文件**：`src/main.py`（~5 行）
|
||
|
||
```python
|
||
from src.daemon.bootstrap import BootstrapBuilder
|
||
|
||
bootstrap = BootstrapBuilder(
|
||
template_dir=Path("prompt_templates"), # Phase 1 先用文件模板
|
||
max_tokens=4096,
|
||
)
|
||
spawner = AgentSpawner(
|
||
...,
|
||
bootstrap_builder=bootstrap, # 之前是 None
|
||
)
|
||
```
|
||
|
||
**改动文件**：`src/daemon/spawner.py`（~20 行）
|
||
|
||
`build_message()` 方法中，当 `self.bootstrap_builder` 存在时走 BootstrapBuilder 路径：
|
||
|
||
```python
|
||
def build_message(self, agent_id, task, role="executor", **kwargs):
|
||
if self.bootstrap_builder and task is not None:
|
||
# 走 BootstrapBuilder 路径
|
||
return self.bootstrap_builder.build(
|
||
role=role,
|
||
agent_id=agent_id,
|
||
task=task,
|
||
guardrail_rules=self._get_guardrails_for_task(task),
|
||
project_context=self._get_project_context(task),
|
||
experiences=self._get_matching_experiences(task),
|
||
)
|
||
else:
|
||
# fallback（无 task 的场景，如 broadcast）
|
||
return self._build_fallback_message(agent_id, **kwargs)
|
||
```
|
||
|
||
#### Phase 2：创建 5 个角色模板（L2 ①操作规范）
|
||
|
||
**目录**：`prompt_templates/`
|
||
|
||
每个模板遵循 #03 Prompt 进化的设计——**能力 + 约束声明，不写固定步骤**。
|
||
|
||
**executor.md**：
|
||
|
||
```markdown
|
||
# 执行者操作规范
|
||
|
||
## 你的能力
|
||
通过黑板 API（{api_base}）你可以：
|
||
- 读任何任务详情（含依赖、讨论、产出）
|
||
- 读所有活跃任务
|
||
- 写产出（POST outputs）
|
||
- 写评论/交接/提问（POST comments）
|
||
- 更新任务状态（POST status）
|
||
- 创建子任务（POST tasks）
|
||
|
||
## 任务执行纪律
|
||
1. 先确认当前设计再改——不确定时问用户确认
|
||
2. 认领任务前检查角色匹配——评审者不认领编码任务
|
||
3. 发现实现与预期不符时，先理解当前设计逻辑
|
||
|
||
## 约束
|
||
- 完成后必须写产出物（output）并标 review，不能无产出就提交
|
||
- 失败了标 failed 并写明原因
|
||
- 产出物 handoff comment ≥ 50 字符（用于系统验证）
|
||
- 禁止使用 sessions_send 直接发消息（用黑板 comment）
|
||
|
||
## 交接责任
|
||
完成后写交接文档（handoff comment）：
|
||
- 你做了什么决策、为什么这么做
|
||
- 遇到什么问题、怎么解决的
|
||
- 给下一个 Agent 的建议和注意事项
|
||
⚠️ handoff 不超过 500 字，只写决策/权衡/坑/建议
|
||
```
|
||
|
||
**reviewer.md**：
|
||
|
||
```markdown
|
||
# 审查者操作规范
|
||
|
||
## 你的能力
|
||
通过黑板 API（{api_base}）你可以：
|
||
- 读任务详情（含全部产出和讨论）
|
||
- 写审查评论（POST comments, comment_type=review）
|
||
- 写审查结论（POST reviews）
|
||
- 标 approved / rejected / needs_revision
|
||
|
||
## 审查纪律
|
||
1. 审查意见必须具体到行号和修改方向，不做模糊评价
|
||
2. rejected 时必须给出改进建议
|
||
3. 涉及风控/实盘相关，额外关注安全性
|
||
4. 不批准自己写的代码
|
||
|
||
## 审查要点
|
||
- 代码质量：命名、结构、可维护性
|
||
- 正确性：逻辑、边界、异常处理
|
||
- 安全性：注入、越权、硬编码密钥
|
||
- 符合验收标准（must_haves）
|
||
|
||
## 诚实边界
|
||
- 审查者可能遗漏深层逻辑问题
|
||
- 性能问题需要实际测试数据
|
||
```
|
||
|
||
**planner.md**（庞统规划）：
|
||
|
||
```markdown
|
||
# 规划者操作规范
|
||
|
||
## 你的能力
|
||
- 分析需求，拆解为子任务
|
||
- 创建任务（POST tasks）含 must_haves 和 risk_level
|
||
- 委派给合适的 Agent（通过 assignee 或 @mention）
|
||
- 调整计划（增删任务、修改依赖）
|
||
|
||
## 规划纪律
|
||
1. 需求不清时用苏格拉底提问帮用户梳理，不猜
|
||
2. 拆解结果要经过验证——覆盖性、依赖合理性、粒度适当
|
||
3. 计划是活的，执行过程中随时调整
|
||
4. 不懂就问用户，不要静默做决策
|
||
|
||
## 模板组件
|
||
根据需求选择需要的 phases：
|
||
- research（需要调研）
|
||
- design（需要设计）
|
||
- coding（需要编码）+ code_review
|
||
- data（需要数据获取）
|
||
- deploy（需要部署）
|
||
- risk_control（涉及实盘/资金，不可删除）
|
||
- final_review（铁律，不可删除）
|
||
```
|
||
|
||
**review_pangtong.md**（庞统进度 review）：
|
||
|
||
```markdown
|
||
# 庞统 Review 操作规范（多轮迭代）
|
||
|
||
## 三问框架
|
||
1. Goal 还清晰吗？
|
||
2. 成果物覆盖 goal 了吗？
|
||
3. 下一轮需要做什么？
|
||
|
||
## 你的能力
|
||
- 读所有 sub task 的状态和产出
|
||
- 创建新一轮 sub tasks
|
||
- 标 GOAL_ACHIEVED / 调整方向
|
||
- 写 review comment
|
||
|
||
## 约束
|
||
- Round 上限: {MAX_ROUNDS}（当前第 {round_num} 轮）
|
||
- 超过上限时升级用户
|
||
```
|
||
|
||
**review_simayi.md**（司马懿质量 review）：
|
||
|
||
```markdown
|
||
# 司马懿 Review 操作规范
|
||
|
||
## 审查层级
|
||
- high 风险：对抗辩论（正方 vs 反方）
|
||
- standard 风险：单审
|
||
- low 风险：Guardrail 自动
|
||
|
||
## 你的能力
|
||
- 读任务产出和前序讨论
|
||
- 写 review（POST reviews）含 verdict + notes
|
||
- 反驳权：被 rejected 时可以 ACCEPT/REJECT/PARTIAL
|
||
|
||
## 约束
|
||
- 审查意见必须具体，不做模糊评价
|
||
- rejected 必须给改进建议
|
||
- 涉及风控/实盘额外关注安全
|
||
```
|
||
|
||
#### Phase 3：改造 Daemon prompt 模板（#03 Prompt 进化）
|
||
|
||
将现有的 6 个硬编码模板统一归入 BootstrapBuilder。Daemon 的 prompt 构建变成：
|
||
|
||
```
|
||
Spawner.spawn() → BootstrapBuilder.build(role, task, ...) → 拼装后的 message
|
||
```
|
||
|
||
**各场景的 role 映射**：
|
||
|
||
| 场景 | 原模板 | 新 role | BootstrapBuilder 注入 |
|
||
|------|--------|---------|---------------------|
|
||
| 任务执行 | SPAWN_PROMPT_TEMPLATE | executor | executor.md + 任务上下文 + Guardrail + 经验 |
|
||
| 广播认领 | _build_claim_prompt | claim | 任务列表 + API 列表（无角色模板） |
|
||
| @mention | _build_mention_prompt | mention | 相关讨论 + 任务上下文（无角色模板） |
|
||
| 庞统 review | _build_review_prompt | review_pangtong | review_pangtong.md + 产出汇总 |
|
||
| 司马懿 review | 不存在（新增） | review_simayi | review_simayi.md + 产出物 |
|
||
| 庞统委派 | _build_delegate_prompt | delegate | 团队列表 + 任务上下文 |
|
||
| 讨论 | DISCUSSION_PROMPT | discussion | 开放式（保留不变） |
|
||
|
||
**关键变化**：
|
||
- **去掉身份注入** — "你是 {agent_id}，专长: {caps}" 由 L1 SOUL.md 负责
|
||
- **去掉固定步骤** — 不再写"标 working → 干活 → 写产出 → 标 review"
|
||
- **保留能力列表** — API 端点列表在角色模板中，Agent 自己选怎么用
|
||
- **保留约束底线** — 必须写产出、必须标 review 是硬约束
|
||
|
||
#### Phase 4：创建 experiences 表 + 导入
|
||
|
||
**建表 SQL**：
|
||
|
||
```sql
|
||
CREATE TABLE experiences (
|
||
experience_id TEXT PRIMARY KEY,
|
||
source TEXT NOT NULL, -- 'pangtong' | 'simayi' | 'mail'
|
||
category TEXT NOT NULL, -- 'correction' | 'trial_error' | 'success' | 'collaboration' | 'disagreement' | 'declaration'
|
||
summary TEXT NOT NULL, -- 200 字以内
|
||
confidence REAL DEFAULT 0.5,
|
||
status TEXT DEFAULT 'draft', -- 'draft' | 'active' | 'deprecated'
|
||
created_at TEXT NOT NULL,
|
||
created_by TEXT NOT NULL
|
||
);
|
||
|
||
CREATE TABLE experience_tags (
|
||
experience_id TEXT NOT NULL REFERENCES experiences(experience_id),
|
||
tag TEXT NOT NULL,
|
||
PRIMARY KEY (experience_id, tag)
|
||
);
|
||
```
|
||
|
||
**导入**：将 `distill-experiences-collaboration.json`（119 条）导入表。
|
||
|
||
**接入**：`bootstrap.py` 的 `_format_experiences()` 已有从表读取并格式化的逻辑，表存在即可工作。
|
||
|
||
---
|
||
|
||
### L3 改造：SkillRegistry 支持 .md + 注册蒸馏 Skill
|
||
|
||
**改动量**：小（~30 行代码 + 4 个 Skill 文件）
|
||
|
||
#### L3-1：skill_system.py 支持 .md frontmatter
|
||
|
||
```python
|
||
# skill_system.py _load_from_dir 增加 .md 支持
|
||
def _load_from_dir(self, dir_path: Path) -> None:
|
||
# 原有 .json 加载（不变）
|
||
for f in dir_path.glob("*.json"):
|
||
try:
|
||
data = json.loads(f.read_text())
|
||
skill = Skill.from_dict(data)
|
||
self._skills[skill.id] = skill
|
||
except Exception:
|
||
logger.warning("Failed to load skill from %s", f)
|
||
|
||
# 新增：.md frontmatter 加载
|
||
for f in dir_path.glob("*.md"):
|
||
try:
|
||
skill = self._parse_skill_md(f)
|
||
if skill:
|
||
self._skills[skill.id] = skill
|
||
except Exception:
|
||
logger.warning("Failed to load skill from %s", f)
|
||
|
||
def _parse_skill_md(self, path: Path) -> Optional[Skill]:
|
||
"""从 SKILL.md frontmatter 解析 Skill 描述"""
|
||
content = path.read_text(encoding="utf-8")
|
||
if content.startswith("---"):
|
||
_, fm, _ = content.split("---", 2)
|
||
meta = yaml.safe_load(fm)
|
||
return Skill(
|
||
id=meta.get("name", path.stem),
|
||
name=meta.get("name", path.stem),
|
||
description=meta.get("description", ""),
|
||
freedom=SkillFreedom.HIGH.value,
|
||
tags=meta.get("tags", []),
|
||
)
|
||
return None
|
||
```
|
||
|
||
#### L3-2：注册 4 个蒸馏 Skill
|
||
|
||
将 `skills/` 目录下的 4 个蒸馏 Skill 文件注册：
|
||
|
||
| 文件 | 内容 | 来源 |
|
||
|------|------|------|
|
||
| trial-and-error-patterns.md | 6 个试错模式 | 蒸馏扫描② |
|
||
| proven-practices.md | 9 个成功最佳实践 | 蒸馏扫描③ |
|
||
| review-quality.md | 4 个评审质量模式 | 蒸馏扫描②③ |
|
||
| self-reflection-wisdom.md | 3 个自我反思模式 | 蒸馏扫描⑥ |
|
||
|
||
#### L3-3：BootstrapBuilder 接入 SkillRegistry
|
||
|
||
`bootstrap.py` 的 `_format_skills()` 从 SkillRegistry 获取匹配的 Skill description，按 D4-8 的四要素格式注入：
|
||
|
||
```
|
||
Skill: quant-backtest
|
||
When to use: 回测量化策略、验证策略历史表现
|
||
Chinese triggers: 回测、backtest、策略测试
|
||
Proactively suggest when: 用户提到策略实现完成后
|
||
```
|
||
|
||
#### L3-4：两套 Skill 系统的协同
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ OpenClaw 原生 Skills（42 个） │
|
||
│ 来源: ~/.sanguo_projects/sanguo_mozi/skills/ (extraDirs) │
|
||
│ 机制: SKILL.md frontmatter → Agent description 匹配 → read │
|
||
│ 角色: Agent 自主发现和使用 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ moziplus SkillRegistry（4+ 个） │
|
||
│ 来源: skills/ 目录 + skill_system.py 注册 │
|
||
│ 机制: Daemon 构建 prompt 时匹配 → 注入 description │
|
||
│ 角色: Daemon 在 spawn 时注入，确保关键 Skill 不被遗漏 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
|
||
重叠处理：
|
||
- 同一个 Skill 可以同时出现在两套系统中
|
||
- OpenClaw 发现的通用 Skill（如 plan-act-verify）Agent 可以直接 read
|
||
- moziplus SkillRegistry 的专用 Skill（如 review-quality）由 Daemon 确保注入
|
||
- 未来：superpower 等第三方 Skill 通过 extraDirs 进入 OpenClaw 系统
|
||
```
|
||
|
||
---
|
||
|
||
## 四、改造后完整架构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ L0 铁律层（~500 tokens）→ Hook 每轮强制注入 │
|
||
│ ├── gate-enforcer: GATE 铁律 + Delegation 铁律 │
|
||
│ └── gate-enforcer: GATE 产出物检查（before_tool_call） │
|
||
├──────────────────────────────────────────────────────────────────┤
|
||
│ L1 角色层（~2000 tokens）→ Workspace 自动注入 │
|
||
│ ├── SOUL.md: 人格 + 专长声明 │
|
||
│ ├── AGENTS.md: 团队通讯录 + 黑板协作指南 + 协作规则 │
|
||
│ ├── TOOLS.md: 工具配置 + 黑板 API 速查 │
|
||
│ ├── MEMORY.md: 长期记忆 │
|
||
│ └── HEARTBEAT.md: 当前工作状态 │
|
||
├──────────────────────────────────────────────────────────────────┤
|
||
│ L2 引擎注入层（~1500 tokens）→ BootstrapBuilder 按 role 精确拼装 │
|
||
│ ① 操作规范: prompt_templates/{role}.md（5 个角色） │
|
||
│ ② 项目背景: project_context.yaml │
|
||
│ ③ 任务上下文: 黑板任务数据 │
|
||
│ ④ 前序信息: depends_on 产出摘要 + handoff comment │
|
||
│ ⑤ Guardrail: rules + behavior_rules（仅 executor） │
|
||
│ ⑥ 审查协议: review_protocols/*.yaml（仅 reviewer） │
|
||
│ ⑦ 经验注入: experiences 表按 tag 匹配（最多 5 条） │
|
||
│ │
|
||
│ Prompt 风格: 能力 + 约束声明，不写固定步骤 │
|
||
│ 身份注入: 无（由 L1 负责） │
|
||
├──────────────────────────────────────────────────────────────────┤
|
||
│ L3 被动参考层（按需加载） │
|
||
│ ├── OpenClaw Skills: 42 个 SKILL.md（extraDirs, Agent 自主 read）│
|
||
│ └── moziplus Skills: 4+ 个（SkillRegistry, Daemon 注入 desc） │
|
||
└──────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 信息去重检查
|
||
|
||
| 信息 | L0 | L1 | L2 | L3 | 唯一归属 |
|
||
|------|----|----|----|----|---------|
|
||
| GATE 铁律 | ✅ Hook | — | — | — | L0 |
|
||
| Delegation 铁律 | ✅ Hook | — | — | — | L0 |
|
||
| 安全红线 | ✅ guardrails | — | ✅ 注入 executor | — | L0 为主，L2 按需引用 |
|
||
| 行为铁律 | ✅ guardrails | — | — | — | L0 |
|
||
| "你是谁" | — | ✅ SOUL | ~~❌ 删除~~ | — | L1 |
|
||
| "你擅长什么" | — | ✅ SOUL | ~~❌ 删除~~ | — | L1 |
|
||
| 黑板使用教程 | — | ✅ AGENTS | — | — | L1 |
|
||
| 黑板 API | — | ✅ TOOLS | — | — | L1 |
|
||
| 操作规范（能力+约束） | — | — | ✅ 模板 | — | L2 |
|
||
| 任务上下文 | — | — | ✅ 动态 | — | L2 |
|
||
| Guardrail 规则 | — | — | ✅ 动态 | — | L2 |
|
||
| 审查协议 | — | — | ✅ 动态 | — | L2 |
|
||
| 经验注入 | — | — | ✅ 动态 | — | L2 |
|
||
| Skill description | — | — | — | ✅ | L3 |
|
||
|
||
---
|
||
|
||
## 五、实施路线
|
||
|
||
### Step 1：L0 改造（独立，1 小时）
|
||
|
||
1. 合并 guardrails.yaml（新增 behavior_rules）
|
||
2. 更新 gate-enforcer delegation-rule
|
||
3. 清理 guardrails/ 孤儿文件
|
||
4. **验证**：`openclaw plugins doctor` + session 检查 Hook 注入
|
||
|
||
### Step 2：L1 改造（独立，2 小时）
|
||
|
||
1. 6 个 Agent SOUL.md 加专长段
|
||
2. 6 个 Agent AGENTS.md 重写（v1 → v2 黑板协作指南）
|
||
3. 6 个 Agent TOOLS.md 加黑板 API
|
||
4. **验证**：在 Control UI 对话中测试 Agent 是否知道专长和黑板用法
|
||
|
||
### Step 3：L2 Phase 1 — 启用 BootstrapBuilder（依赖 Step 1-2，半天）
|
||
|
||
1. main.py 实例化 BootstrapBuilder
|
||
2. spawner build_message() 走 BootstrapBuilder 路径
|
||
3. 创建 5 个角色模板文件
|
||
4. **验证**：单任务 spawn，检查注入内容
|
||
|
||
### Step 4：L2 Phase 2 — Prompt 模板重写（依赖 Step 3，1 天）
|
||
|
||
1. 重写 Daemon 6 个 prompt 模板为 BootstrapBuilder 路径
|
||
2. 去掉身份注入（L1 已负责）
|
||
3. 去掉固定步骤，改为能力+约束声明
|
||
4. 新增司马懿 review 模板 + ticker 触发逻辑
|
||
5. **验证**：E2E 单任务测试
|
||
|
||
### Step 5：L2 Phase 3 — experiences 表 + L3 改造（依赖 Step 4，1 天）
|
||
|
||
1. 创建 experiences 表 + 导入 119 条数据
|
||
2. skill_system.py 支持 .md
|
||
3. 注册 4 个蒸馏 Skill
|
||
4. BootstrapBuilder 接入 SkillRegistry
|
||
5. **验证**：experiences 注入检查 + Skill description 注入检查
|
||
|
||
### Step 6：E2E 全流程验证（依赖 Step 5，半天）
|
||
|
||
| 测试 | 验证点 |
|
||
|------|--------|
|
||
| E1 广播认领 | Agent 凭 L1 专长自主判断 |
|
||
| E2 任务执行 | 无固定步骤，Agent 自主决策 |
|
||
| E3 多轮迭代 | 庞统 Review 三问框架 |
|
||
| E4 @mention | 黑板讨论协作 |
|
||
| E6 质量审查 | 司马懿 Review |
|
||
| 新 E7 | Agent 主动提问（黑板 comment） |
|
||
|
||
---
|
||
|
||
## 六、风险
|
||
|
||
| 风险 | 概率 | 缓解 |
|
||
|------|------|------|
|
||
| BootstrapBuilder 拼装内容过长 | 低 | max_tokens=4096 限制 + 自动截断 |
|
||
| 去掉固定步骤后 Agent 不知道怎么操作 | 中 | L1 AGENTS.md 有黑板教程 + L2 角色模板有 API 列表 |
|
||
| L1 专长段不够强，Agent 还是乱认领 | 中 | L2 claim 模板保留"只认领符合专长"约束作双保险 |
|
||
| 两套 Skill 系统信息冲突 | 低 | OpenClaw 管理 Agent 自主的，moziplus 管理 Daemon 注入的 |
|
||
| experiences 注入噪音 | 中 | confidence 阈值过滤 + 最多 5 条 |
|
||
|
||
---
|
||
|
||
## 七、来源索引
|
||
|
||
| 设计文档 | 涉及内容 |
|
||
|---------|---------|
|
||
| architecture-v3.0.md §10.1 | L0-L3 四层定义 |
|
||
| technical-design-v2.6.md §5 | BootstrapBuilder 拼装逻辑 |
|
||
| v2.8-direction-notes §一~§三 | Daemon 退化 + Agent 进化 + Prompt 进化方向 |
|
||
| #03-prompt-evolution.md | 固定步骤 → 能力+约束声明 |
|
||
| distill-full-design.md | 蒸馏完整方案 |
|
||
| distill-integration-plan.md | 四层整合改造方案（未确认未执行） |
|
||
| v2.6-research-04 | Skill 三层自由度 + description 四要素 |
|
||
| v2.6-research-06 | SkillRouter 调研 + 三层组合方案 |
|
||
| topic4 D4-7 | L2 精确注入原则 |
|
||
| topic4 D4-8 | L3 Skill description 四要素 |
|
||
| OpenClaw skills-config.md | extraDirs + Skill 发现机制 |
|