From 11e5571edeea74d24fd813658039429367a58157 Mon Sep 17 00:00:00 2001 From: cfdaily Date: Wed, 3 Jun 2026 20:28:38 +0800 Subject: [PATCH] auto-sync: 2026-06-03 20:28:38 --- docs/design/11-context-layers-redesign.md | 443 ++++++++++++++++++++++ 1 file changed, 443 insertions(+) create mode 100644 docs/design/11-context-layers-redesign.md diff --git a/docs/design/11-context-layers-redesign.md b/docs/design/11-context-layers-redesign.md new file mode 100644 index 0000000..84309ad --- /dev/null +++ b/docs/design/11-context-layers-redesign.md @@ -0,0 +1,443 @@ +# #11 上下文四层架构重新定位方案 + +> 版本: v1.0 +> 日期: 2026-06-03 +> 作者: 庞统（副军师） +> 状态: **待确认** +> 来源: 用户设计思路 + NAS 知识库调研（ClawTeam/Superpowers/GSD/Hermes/oh-my-claudecode） + +--- + +## 一、调研结论：5 个优秀项目的分层设计对比 + +### 1.1 分层模式对比 + +| 项目 | 分层策略 | L0(铁律) | L1(身份/角色) | L2(引擎/动态) | L3(Skill/参考) | +|------|---------|----------|-------------|-------------|---------------| +| **ClawTeam** | Prompt 构建 + Skill 分离 | 无独立层 | `build_agent_prompt()` 中注入 Identity + Mission + Workspace + Boids + Metacognition | 无（全在 prompt builder 里） | `skills/openclaw/SKILL.md`（CLI 操作手册，Agent 按 read） | +| **Superpowers** | Hook 注入 + Skill 自动触发 | Hook `session-start` 注入 `using-superpowers` bootstrap（铁律级：必须用 Skill、Red Flags 表） | `CLAUDE.md`（项目规则） | 无（靠 Skill 自身描述触发） | 14 个 Skill（brainstorming/debugging/TDD 等），description 关键词匹配自动触发 | +| **GSD** | Agent 角色 + Spec 驱动 | `role` 段（你是 executor） + `project_context` 段（CLAUDE.md 规则） | 每个 agent `.md` 文件定义角色 | `execution_flow` 段（固定步骤，spec 驱动） | Commands（/gsd-*） + references（mandatory-initial-read 等） | +| **Hermes** | Prompt 拼装 + Skill 生命周期 | `DEFAULT_AGENT_IDENTITY` + `MEMORY_GUIDANCE` | `SOUL.md` + `.hermes.md`（项目级） | `prompt_builder.py` 动态拼 context files + skills index | Skills 目录（frontmatter description 匹配）+ 自我改进闭环（从经验创建 Skill） | +| **oh-my-claudecode** | Agent Catalog + Skill 触发 | `operating_principles` + `delegation_rules`（写入 CLAUDE.md） | `agent_catalog` 19 个角色 | `team_pipeline`（plan→prd→exec→verify→fix loop） | Skills（autopilot/ralph/ultrawork 等）+ keyword triggers | + +### 1.2 关键发现 + +#### 发现 1：没有一个项目做了严格的四层分离 + +大部分项目是**两层**： +- **固定层**：Hook / System Prompt / CLAUDE.md（身份 + 铁律 + 项目规则） +- **动态层**：Skill / Command / Agent prompt（按需加载） + +"引擎注入层"(L2) 这个概念是我们的独创，其他项目要么把它放进 Prompt Builder（ClawTeam），要么放进 Agent 角色（GSD），要么不存在（Superpowers）。 + +#### 发现 2：Superpowers 的 Skill 自动触发是最优雅的设计 + +- **不靠引擎注入 Skill**，靠 Skill 的 description + 触发词匹配 +- Agent 收到 `using-superpowers` bootstrap 后知道"有 Skill 要用" +- 每条 Skill 的 frontmatter description 定义了"When to use" +- Agent 在处理任何消息前先检查"有没有 Skill 匹配" +- Red Flags 表防止 Agent 合理化跳过 Skill + +**启示**：OpenClaw 的 `extraDirs` 机制天然支持这种模式——Skill header（name + description）自动加载到 Agent，Agent 自主决定是否 read 全文。 + +#### 发现 3：ClawTeam 的 Prompt 构建最接近我们的 L2 设计 + +``` +Identity → Mission(Auftragstaktik: intent/end_state/constraints) → Workspace → +Shared Memory → Boids Rules(仅 team>1) → Task → Context → Coordination Protocol → Metacognition +``` + +关键设计决策： +- **协调知识在 Skill 里，不在 prompt 里**（`skills/openclaw/SKILL.md`） +- **Boids 规则只在多 Agent 时注入**（条件注入） +- **身份和任务是分离的**（Identity 段和 Task 段） + +**启示**：Prompt 只放"你是什么、要做什么、约束是什么"，操作手册放 Skill。 + +#### 发现 4：Hermes 有最完整的 Skill 生命周期 + +- Agent 完成复杂任务后自动创建 Skill（procedural memory） +- Skill 在使用中自我改进（遇到新情况更新 Skill） +- FTS5 全文检索历史对话（cross-session recall） +- `agentskills.io` 开放标准（Skill 可跨平台共享） + +**启示**：经验沉淀可以变成"创建/改进 Skill"，而不是单独的 experiences 表。 + +#### 发现 5：GSD 的 Scope Reduction Detection 值得借鉴 + +- 不是靠新机制，而是靠 Agent prompt 中的显式检查指令 +- executor 自检 + reviewer 复检，双重保险 +- 简单有效，不需要额外的系统组件 + +### 1.3 各项目缺点 + +| 项目 | 缺点 | +|------|------| +| ClawTeam | 身份注入在 prompt 里而非 workspace 文件，换角色要改代码 | +| Superpowers | 零引擎层，完全靠 Skill 自触发，不适合需要确定性流转的场景 | +| GSD | Agent prompt 太重（executor.md 有 200+ 行固定步骤），context 消耗大 | +| Hermes | Skill 目录结构扁平，无分层组织（全平铺） | +| oh-my-claudecode | Agent catalog 硬编码在 CLAUDE.md，加角色要改文件 | + +--- + +## 二、我们的四层重新定位 + +基于用户设计思路 + 调研结论，重新定义四层： + +### 2.0 总原则 + +> **L0 做极简（通用铁律），L1 做身份（谁、擅长什么、怎么协作），L2 做薄（引擎流转规则），L3 做厚（Skill + 经验 + 知识，全部靠 extraDirs 动态加载）** + +### 2.1 L0 铁律层 — "不可绕过的通用行为底线" + +**定位**：只放跨系统通用的、和 moziplus 无关的行为铁律。每个 Agent 的每次 turn 都会注入。 + +**来源**：Gateway Hook（`prependContext`）或 Agent workspace 根文件。 + +**不放什么**： +- ❌ moziplus 特有规则（黑板协作、@mention 等）→ L2 或 L3 +- ❌ 角色专长声明 → L1 +- ❌ 任务执行步骤 → L3 Skill + +**放什么**： +- ✅ GATE 门控铁律（需求不清不动手、根因不明不修复、方案未定不实现） +- ✅ Delegation 执行原则（main session 做决策、执行委派 sub-agent） +- ✅ 通用安全底线（不虚构、不作恶、不越权） + +**token 预算**：≤ 500 tokens + +**实际承载**： +- 当前已有：`gate-rules`（GATE 铁律 5 条）+ `delegation-rule`（Delegation 5 条） +- 这些已经是通用铁律，不依赖 moziplus，**无需改动** + +### 2.2 L1 角色层 — "你是谁、你擅长什么、团队怎么协作" + +**定位**：Agent workspace 文件，由 Gateway 自动注入，每轮都在。定义 Agent 的静态身份。 + +**来源**：每个 Agent 的 workspace 目录（`~/.openclaw/workspace-{agent}/`）。 + +**放什么**： +- ✅ `SOUL.md`：人格 + 专长声明（✅擅长 / ❌不擅长）+ 工作原则 +- ✅ `AGENTS.md`：团队通讯录 + 通用协作规则（黑板 API、@mention、状态流转）+ 飞鸽传书用法 +- ✅ `TOOLS.md`：工具配置 + 黑板 API 速查 + 关键路径 +- ✅ `MEMORY.md`：长期记忆（用户偏好、项目上下文、经验教训） +- ✅ `HEARTBEAT.md`：当前工作状态 + +**不放什么**： +- ❌ 任务执行步骤/规范 → L3 Skill（如 `plan-act-verify`、`code-review`） +- ❌ 引擎流转规则（状态机约束、产出物要求等）→ L2 +- ❌ 审查协议/审查要点 → L3 Skill（如 `review-quality`） +- ❌ 蒸馏经验/试错模式 → L3 Skill（如 `trial-and-error-patterns`） +- ❌ 项目背景上下文（moziplus 特有的）→ L2 动态注入 + +**token 预算**：≤ 3000 tokens（SOUL ~500 + AGENTS ~1000 + TOOLS ~300 + MEMORY ~500 + HEARTBEAT ~300） + +**与当前设计的核心变化**： +- AGENTS.md 中的"对应 Skill"映射表 → **删除**（Skill discovery 靠 L3 的 description 匹配，不靠映射表） +- AGENTS.md 中的详细协作规则 → **保留核心**，但操作手册级的细节移到 L3 Skill + +### 2.3 L2 引擎注入层 — "引擎流转所需的最小规则集" + +**定位**：只放**引擎需要注入才能让任务正常流转**的规则和约束。这是 Daemon/Spawner 在 spawn Agent 时动态拼装的，按场景精确注入。 + +**来源**：`BootstrapBuilder` 代码 + `prompt_templates/` 目录。 + +**放什么**： +| 组件 | 内容 | 注入条件 | +|------|------|---------| +| ① 任务上下文 | 黑板任务数据（title/description/must_haves/status） | 所有 spawn | +| ② 项目背景 | project_context.yaml | 所有 spawn | +| ③ 状态流转约束 | "完成后必须标 review"、"产出物不能空"、"handoff ≥ 50 字" | executor | +| ④ 前序信息 | depends_on 产出摘要 + handoff comment | executor（有依赖时） | +| ⑤ Guardrail 安全红线摘要 | 当前任务的 guardrail 检查结果 | executor（有红线触发时） | +| ⑥ 广播认领规则 | 三级响应（claim/observe/NO_REPLY）+ API 端点 | broadcast 场景 | +| ⑦ 审查流转规则 | review verdict 类型、rebuttal 流程 | reviewer 场景 | + +**不放什么**： +- ❌ 角色身份（"你是张飞，擅长编码"）→ L1 SOUL.md +- ❌ 操作手册（"先读黑板、再动手、写产出、标 review"）→ L3 Skill（`blackboard-executor`） +- ❌ 审查方法论（"挑战者思维"、"先理解目标再判断"）→ L3 Skill（`review-quality`） +- ❌ 规划方法论（"理解需求→拆解→动态调整"）→ L3 Skill（`task-planning`） +- ❌ 经验/知识 → L3 Skill（`trial-and-error-patterns` 等） +- ❌ Boids 协作规则 → L3 Skill（`team-collaboration`） +- ❌ 元认知自评 → L3 Skill（`metacognition`）或 L0 铁律 + +**核心变化（相比 05-context-layers.md）**： +- **砍掉"操作规范"组件**（prompt_templates/{role}.md 整个角色模板）→ 移到 L3 Skill +- **砍掉"审查协议"组件**（review_protocols/）→ 移到 L3 Skill +- **砍掉"经验注入"组件**（experiences 表）→ 移到 L3 Skill +- **L2 只留流转必须的结构化数据**：任务上下文 + 项目背景 + 状态约束 + API 端点 + +**token 预算**：≤ 800 tokens（极简，只放数据+约束，不放方法论） + +**设计理由**： +1. **和 ClawTeam 对齐**：ClawTeam 的 prompt 只放 Identity + Mission(intent/end_state/constraints) + Workspace + Task + Coordination Protocol，方法论在 Skill 里 +2. **L2 越薄越稳定**：引擎代码改动频率 > Skill 改动频率。L2 薄意味着引擎代码改动少 +3. **L3 可以随时更新**：extraDirs 重启即生效，不需要改代码 +4. **用户原话**："L2 只放和引擎相关的内容，比如如何让引擎能够正常流转的各种规则和约束" + +### 2.4 L3 被动参考层 — "所有 Skill + 经验 + 知识" + +**定位**：所有和任务执行相关的内容都在这一层。通过 OpenClaw 的 `extraDirs` 机制，Skill header（name + description）自动加载到 Agent，Agent 根据任务需要自主 `read` 全文。 + +**来源**：`~/.sanguo_projects/sanguo_mozi/skills/`（extraDirs 配置）+ moziplus 专用 Skill 目录。 + +**放什么**： + +#### A. 操作规范型 Skill（从 L2 角色模板降级） + +| Skill | 来源 | 说明 | +|-------|------|------| +| `blackboard-executor` | 原 `prompt_templates/executor.md` | 执行者操作规范：能力列表、执行纪律、交接责任、产出标准 | +| `blackboard-reviewer` | 原 `prompt_templates/reviewer.md` | 审查者操作规范：审查思维、Scope Reduction Detection、诚实边界 | +| `blackboard-reviewer-simayi` | 原 `prompt_templates/review_simayi.md` | 司马懿特化：挑战者思维、审查层级、反驳权 | +| `blackboard-reviewer-pangtong` | 原 `prompt_templates/review_pangtong.md` | 庞统 Review：三问框架、目标漂移检测 | +| `blackboard-planner` | 原 `prompt_templates/planner.md` | 规划者：规划思维、终态定义 | +| `blackboard-claim` | 原 `_build_claim_prompt` 三级响应 | 广播认领：三级响应（claim/observe/NO_REPLY）| + +#### B. 方法论型 Skill（从设计文档提升） + +| Skill | 来源 | 说明 | +|-------|------|------| +| `team-collaboration` | 03-prompt-evolution Boids 规则 | Separation/Alignment/Cohesion/Boundary + 共享意识 | +| `metacognition` | ClawTeam METACOGNITION_BLOCK | 置信度自评 + 升级机制 | +| `scope-reduction-detection` | 03-prompt-evolution §8.2 | 反静默降级检查（executor 自检 + reviewer 复检）| +| `plan-approval-workflow` | 03-prompt-evolution §8.3 | 复杂任务先计划后执行 + 5分钟异议窗口 | + +#### C. 审查协议型 Skill（从 L2 review_protocols 提升） + +| Skill | 来源 | 说明 | +|-------|------|------| +| `review-quality` | 蒸馏扫描②③ | 4 个评审质量模式 | +| `code-review` | 已有 Skill | 代码审查完整流程 | + +#### D. 经验型 Skill（从 experiences 表提升） + +| Skill | 来源 | 说明 | +|-------|------|------| +| `trial-and-error-patterns` | 蒸馏扫描② | 6 个试错模式 | +| `proven-practices` | 蒸馏扫描③ | 9 个成功最佳实践 | +| `self-reflection-wisdom` | 蒸馏扫描⑥ | 3 个自我反思模式 | + +#### E. 任务执行型 Skill（已有） + +| Skill | 说明 | +|-------|------| +| `plan-act-verify` | 非平凡任务执行流程 | +| `code-review` | 代码审查 | +| `data-acquisition` | 数据获取 | +| `deployment-infra` | 部署 | +| `quant-backtest` | 量化回测 | +| `subagent-delegation` | 任务委派 | +| ...（42 个现有 Skill） | | + +#### F. 知识注入型 Skill（新增） + +| Skill | 说明 | +|-------|------| +| `wiki-knowledge-{domain}` | 按领域注入 wiki-vault 知识（如量化策略、vnpy 框架等）| + +**Skill Header 格式**（遵循 OpenClaw SKILL.md frontmatter）： + +```yaml +--- +name: blackboard-executor +description: | + 黑板执行者操作规范。当 Agent 通过黑板执行任务时使用。 + 包含：能力列表、执行纪律、产出标准、交接责任。 + 触发词：executor、执行、黑板执行、task execution、blackboard executor。 + 触发条件：收到 moziplus 投递的执行任务时。 +--- +``` + +**设计理由**： +1. **用户原话**："所有和任务执行相关的所需的技能都放在这一层，因为 openclaw 有关键词动态加载的机制" +2. **和 Superpowers 对齐**：Superpowers 的 14 个 Skill 全部是这种模式——Skill header 定义触发条件，Agent 自主匹配 +3. **经验沉淀变成 Skill**（和 Hermes 对齐）：不是单独的 experiences 表，而是提炼成 Skill。"trial-and-error-patterns" 比 "119 条 experiences 按 tag 匹配" 更实用 +4. **重启即生效**（用户原话）："这一层是 extra dir 的形式补充 L1 的，所以可以随时重启来加载" + +**不放什么**： +- ❌ 铁律（GATE 规则）→ L0 +- ❌ 身份（我是谁）→ L1 SOUL.md +- ❌ 引擎流转数据（任务上下文、状态约束）→ L2 + +--- + +## 三、各层内容归属表 + +把之前的"剩余项"全部重新归类： + +| 原始编号 | 内容 | 新归属 | 理由 | +|---------|------|--------|------| +| L0-1 | delegation-rule 适配 #02 | **L0 保留** | 通用铁律，不依赖 moziplus | +| L0-2 | guardrails 孤儿文件 | **L0 微调** | 通用安全底线 | +| L1-1 | SOUL.md 加专长声明 | **L1** | 身份定义 | +| L1-2 | AGENTS.md 重写 v2 黑板指南 | **L1 精简** | 只保留核心 API + 协作规则，详细操作移到 L3 Skill | +| L1-3 | TOOLS.md 加黑板 API | **L1** | 工具配置 | +| L2-1 | BootstrapBuilder 启用 | **L2 保留但瘦身后启用** | 引擎注入 | +| L2-2 | 5 个角色模板文件 | **→ L3** 作为 `blackboard-{role}` Skill | 操作规范不是引擎流转规则 | +| L2-3 | Daemon prompt 迁移 | **L2 瘦身版** | 只保留任务上下文+状态约束，角色身份和操作步骤剥离 | +| L2-4 | experiences 表 | **→ L3** 作为经验型 Skill | 经验不是引擎流转规则 | +| L2-5 | review_protocols/ | **→ L3** 作为 `review-quality` Skill | 审查协议不是引擎流转规则 | +| L2-6 | handoff.schema.json | **→ L3** 作为 `blackboard-executor` Skill 的一部分 |交接规范是操作手册不是引擎规则 | +| L2-7 | 前序信息注入 | **L2 保留** | 引擎需要注入依赖任务的产出 | +| L2-8 | 经验注入 | **→ L3** | 同 L2-4 | +| L3-1 | skill_system.py 支持 .md | **L3（已有机制）** | OpenClaw extraDirs 已支持 .md | +| L3-2 | 4 个蒸馏 Skill 注册 | **L3** | 经验型 Skill | +| L3-3 | BootstrapBuilder 接 SkillRegistry | **不再需要** | Skill 靠 extraDirs 自动发现，不需要引擎注入 | +| L3-4 | 知识注入 | **L3** | wiki-knowledge Skill | +| P-Ev1 | 广播三级响应 | **→ L3** 作为 `blackboard-claim` Skill | 操作规范 | +| P-Ev2~6 | 各角色模板重写 | **→ L3** 作为 `blackboard-{role}` Skill | 操作规范 | +| EXP-1 | "💡 经验:" 标记 | **→ L3** 写入 `blackboard-executor` Skill | 执行规范的一部分 | +| EXP-2 | 119 条蒸馏数据导入 | **→ L3** 提炼为 Skill | 经验 → Skill | +| EXP-3 | 经验 draft→active 流程 | **→ L3** Skill 改进流程 | Skill 生命周期 | + +--- + +## 四、新架构总览 + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ L0 铁律层（≤500 tokens）→ Hook 每轮强制注入 │ +│ ├── GATE 门控铁律（5 条） │ +│ ├── Delegation 执行原则（5 条） │ +│ └── 通用安全底线（不虚构/不作恶/不越权） │ +│ ⚠️ 只放跨系统通用的，不放 moziplus 特有的 │ +├──────────────────────────────────────────────────────────────────┤ +│ L1 角色层（≤3000 tokens）→ Workspace 文件自动注入 │ +│ ├── SOUL.md: 人格 + 专长声明（✅/❌）+ 工作原则 │ +│ ├── AGENTS.md: 通讯录 + 黑板 API 概要 + 协作规则要点 │ +│ │ （详细操作规范 → L3 Skill） │ +│ ├── TOOLS.md: 工具配置 + 路径 + API 端点速查 │ +│ ├── MEMORY.md: 长期记忆 │ +│ └── HEARTBEAT.md: 当前工作状态 │ +├──────────────────────────────────────────────────────────────────┤ +│ L2 引擎注入层（≤800 tokens）→ BootstrapBuilder 按场景精确拼装 │ +│ ├── ① 任务上下文：黑板任务数据（title/desc/must_haves/status） │ +│ ├── ② 项目背景：project_context.yaml │ +│ ├── ③ 状态流转约束：完成后标 review、产出物非空、handoff ≥ 50字 │ +│ ├── ④ 前序信息：depends_on 产出摘要 + handoff comment │ +│ ├── ⑤ Guardrail 安全红线摘要（有触发时注入） │ +│ ├── ⑥ 广播 API 端点列表（broadcast 场景） │ +│ └── ⑦ 审查流转规则（reviewer 场景） │ +│ ⚠️ 只放引擎流转必须的数据+约束，不放方法论/操作手册 │ +├──────────────────────────────────────────────────────────────────┤ +│ L3 被动参考层（按需 read）→ extraDirs 自动加载 header │ +│ │ │ +│ ├── 操作规范型：blackboard-executor/reviewer/planner/claim... │ +│ ├── 方法论型：team-collaboration/metacognition/ │ +│ │ scope-reduction-detection/plan-approval-workflow │ +│ ├── 审查协议型：review-quality/code-review │ +│ ├── 经验型：trial-and-error-patterns/proven-practices/ │ +│ │ self-reflection-wisdom │ +│ ├── 任务执行型：plan-act-verify/quant-backtest/...（42 个现有） │ +│ └── 知识注入型：wiki-knowledge-{domain} │ +│ ⚠️ 全部靠 description 触发，Agent 自主 read 全文 │ +│ ⚠️ 重启 Gateway 即生效，不需要改代码 │ +└──────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 五、关键设计决策 + +### D1: 操作规范从 L2 降级到 L3 + +**旧设计**（05-context-layers.md）：`prompt_templates/executor.md` 是 L2 引擎注入组件，BootstrapBuilder 拼 Agent prompt 时自动注入。 + +**新设计**：操作规范变成 L3 Skill（`blackboard-executor`），Agent 收到任务后根据 L2 的任务上下文 + L1 的身份，自主决定 read `blackboard-executor` Skill。 + +**理由**： +1. 操作规范不是引擎流转必须——引擎只需要任务数据+状态约束 +2. Skill 可以随时更新，不需要改 BootstrapBuilder 代码 +3. Agent 不是每次都需要完整的操作规范（简单任务不需要） +4. **Superpowers 验证**：14 个 Skill 全部靠 description 触发，不靠引擎注入，效果优秀 + +**风险**：Agent 可能不 read Skill。缓解：L2 注入"约束"段加一句"参照 `blackboard-executor` Skill 执行"。 + +### D2: 经验从 experiences 表变成 Skill + +**旧设计**（05-context-layers.md）：建 experiences 表，导入 119 条数据，BootstrapBuilder 按 tag 匹配注入最多 5 条。 + +**新设计**：蒸馏经验提炼为 Skill（如 `trial-and-error-patterns`），Agent 按 description 匹配自主 read。 + +**理由**： +1. experiences 表 + tag 匹配 + 最多 5 条 → 过于复杂，且需要 BootstrapBuilder 代码改动 +2. 提炼为 Skill 后，经验是结构化的、可维护的、可迭代的 +3. **Hermes 验证**：Hermes 从经验创建 Skill（procedural memory），比原始经验数据更实用 +4. 119 条经验 → 提炼为 4 个 Skill（每个 ~10 条精炼模式），质量更高 + +### D3: L2 瘦身到极致 + +**旧设计** L2 有 7 个组件（操作规范、项目背景、任务上下文、前序信息、Guardrail、审查协议、经验注入），token 预算 ~1500。 + +**新设计** L2 只保留 7 个组件中的 4 个（任务上下文、项目背景、前序信息、Guardrail 摘要）+ 状态约束 + API 端点，token 预算 ≤ 800。 + +**理由**： +1. 用户明确说"L2 只放引擎流转规则" +2. **ClawTeam 验证**：prompt 只放 Identity + Mission(intent/end_state/constraints) + Task + Protocol，方法论全在 Skill +3. L2 越薄 → BootstrapBuilder 代码越简单 → bug 越少 → 越稳定 + +### D4: Skill Discovery 靠 description 匹配，不靠引擎注入 + +**旧设计**：`skill_system.py` 注册 → Daemon 构建 prompt 时匹配注入 description → L3a/L3b。 + +**新设计**：完全依赖 OpenClaw 原生的 extraDirs 机制。Skill header（name + description）自动加载到 Agent，Agent 自主决定是否 read。 + +**理由**： +1. 不需要维护两套 Skill 系统（moziplus SkillRegistry + OpenClaw extraDirs） +2. **Superpowers 验证**：这种模式运行良好，94% PR 拒绝率的项目选的就是这种模式 +3. 减少代码量（砍掉 `skill_system.py` + `SkillRegistry`） + +--- + +## 六、实施路线 + +### Phase 1: L0/L1 整理（独立，1-2 天） +1. L0 确认无需改动（当前铁律已经是通用的） +2. L1 AGENTS.md 精简（移除详细操作规范，只保留 API 概要 + 协作规则要点） +3. L1 SOUL.md 加专长声明 +4. L1 TOOLS.md 加黑板 API +5. **验证**：Agent 对话中测试身份认知 + +### Phase 2: L3 Skill 创建（独立，2-3 天） +1. 创建 `blackboard-executor` 等 6 个操作规范型 Skill +2. 创建 `team-collaboration` 等 4 个方法论型 Skill +3. 创建 `trial-and-error-patterns` 等 4 个经验型 Skill（从蒸馏数据提炼） +4. 创建 `review-quality` 审查协议型 Skill +5. **验证**：Skill description 触发测试 + +### Phase 3: L2 BootstrapBuilder 瘦身启用（依赖 Phase 1-2，1 天） +1. main.py 实例化 BootstrapBuilder（只注入任务上下文+状态约束+API端点） +2. spawner build_message() 走 BootstrapBuilder 路径 +3. 砍掉 prompt_templates/{role}.md（已移到 L3） +4. 砍掉 experiences 表（已提炼到 L3 Skill） +5. **验证**：单任务 spawn，检查注入内容精简 + +### Phase 4: E2E 全流程验证（依赖 Phase 3，半天） + +--- + +## 七、风险 + +| 风险 | 概率 | 缓解 | +|------|------|------| +| Agent 不主动 read Skill | 中 | L2 约束段加"参照 {skill-name} Skill 执行"引导 | +| 操作规范移到 L3 后 Agent 不知道怎么执行 | 中 | L1 AGENTS.md 保留协作规则要点 + L2 注入 API 端点 | +| Skill 数量膨胀后 description 匹配不准 | 低 | 定期 audit Skill description 质量 | +| 经验提炼为 Skill 的质量不够 | 中 | 先用蒸馏数据已有的 4 个分类，人工审核 | + +--- + +## 八、与旧设计(05-context-layers.md)的差异 + +| 维度 | 旧设计(05) | 新设计(11) | 变化 | +|------|-----------|-----------|------| +| L2 定位 | 引擎注入 + 角色模板 + 操作规范 + 审查协议 + 经验 | 只放引擎流转数据+约束 | **大幅瘦身** | +| 操作规范位置 | L2 prompt_templates/{role}.md | L3 blackboard-{role} Skill | **降级到 L3** | +| 经验机制 | experiences 表 + tag 匹配 | L3 经验型 Skill | **简化** | +| Skill 发现 | 两套（OpenClaw + SkillRegistry） | 一套（OpenClaw extraDirs） | **统一** | +| BootstrapBuilder 复杂度 | 7 个组件 | 4 个组件 + 状态约束 | **减半** | +| L2 token 预算 | ~1500 | ≤800 | **减半** | +| 总 Skill 数量 | 42（现有）+ 4（蒸馏）| 42 + ~15（新增操作规范+方法论+经验）| **+15 个 Skill** |