# 四层知识体系整合改造方案

> 日期：2026-05-27
> 状态：方案，待主公确认
> 目标：将蒸馏经验整合进 moziplus v2.0 现有四层架构，不是叠加而是融合

---

## 1. 现状诊断

### 现有四层架构（技术设计 v2.6）

```
L0 铁律层（~500 tokens） → Hook 注入，不占 bootstrap
L1 角色层（~2000 tokens） → SOUL.md / IDENTITY.md（Agent 自带）
L2 引擎注入层（~1500 tokens）→ prompt_templates 按 role 拼装
    ① 操作规范（executor.md / reviewer.md / planner.md）
    ② 项目背景（project_context.yaml）
    ③ 任务上下文（黑板数据）
    ④ 前序信息（depends_on 产出摘要）
    ⑤ Guardrail 规则（guardrails.yaml，仅执行者）
    ⑥ 审查协议（review_protocols/，仅审查者）
    ⑦ 经验注入（experiences 表按 tag 匹配）
L3 被动参考层（按需加载）→ Skill description 四要素
```

### 问题：蒸馏产出与现有体系的关系

| 蒸馏产出 | 当前位置 | 问题 |
|---------|---------|------|
| gate-flow.yaml | `guardrails/`（新目录） | 与 `config/guardrails.yaml` 重叠——后者是**安全红线**（实盘/删除/配置），前者是**流程铁律**。两套 guardrail 容易混淆 |
| no-circle-jerking.yaml | `guardrails/`（新目录） | 同上。且"不绕圈子"不是安全红线，更像行为规范 |
| design-confirmation.md | `prompt_templates/`（新目录） | `bootstrap.py` 按 role 加载模板（executor.md/reviewer.md），没有 design-confirmation.md 的加载逻辑。放进去不会被读取 |
| role-match-check.md | `prompt_templates/`（新目录） | 同上。没有对应的 bootstrap 拼装入口 |
| inform-lightweight.md | `prompt_templates/`（新目录） | 同上 |
| 4 个 Skill .md | `skills/` | `skill_system.py` 只加载 `.json` 格式的 skill 定义，不识别 `.md`。且 description 字段需要注册到 registry |
| 119 条 experiences | JSON 文件 | 应该写入黑板 experiences 表，不是文件 |

**结论：蒸馏产出全部是"孤儿文件"——放进了目录但没有对应的加载逻辑。**

---

## 2. 整合改造方案

### 原则

1. **不新增目录**——用现有的 `config/`、`prompt_templates/`、`skills/`
2. **不新增加载逻辑**——用现有的 `guardrails.yaml`、`bootstrap.py`、`skill_system.py`
3. **按层级归位**——每条经验去它该去的层

### 改造清单

#### 改造 1：合并 guardrails.yaml（L0）

**现状**：`config/guardrails.yaml` 有 6 条安全红线
**问题**：蒸馏的 2 条铁律（GATE 流程、不绕圈子）不是安全红线，放一起会导致概念混乱

**方案**：在 guardrails.yaml 中增加 `behavior_rules` 区（与 `rules` 并列）

```yaml
# config/guardrails.yaml

rules:  # 安全红线（原有 6 条不变）
  - id: live_trading
    ...
  - id: data_deletion
    ...

# 新增：行为铁律（从蒸馏经验提炼，每次 turn 强制注入）
behavior_rules:
  - id: gate_flow
    name: GATE 流程门控
    severity: high
    frequency: 33  # 历史纠正次数
    trigger: "非平凡任务启动时"
    rule: |
      需求不清不动手 — 列出假设让用户确认
      根因不明不修复 — 先查清再改
      方案未定不实现 — 先出方案等确认
      评估过影响范围才动手
      L1 小改动（<50行，做错代价低）可跳过

  - id: no_circle
    name: 不绕圈子
    severity: high
    frequency: 20
    trigger: "用户已明确方向后"
    rule: |
      用户已明确方向后，不再质疑前提
      用户给出条件假设时，按最坏情况设计
      用户说"别绕了"= 立刻停止，直接给方案

# 全局设置（原有不变）
settings:
  enabled: true
  ...
```

**代码改动**：`guardrail.py` 读取 `behavior_rules` 并拼入 L0 Hook 注入

**删除**：`guardrails/gate-flow.yaml` 和 `guardrails/no-circle-jerking.yaml`（孤儿文件）

#### 改造 2：扩充 prompt_templates/（L2）

**现状**：`prompt_templates/` 目录只有蒸馏新增的 3 个文件，`bootstrap.py` 按角色名加载（executor.md/reviewer.md），这 3 个不会自动加载
**方案**：

1. 将蒸馏的 3 个场景模板合并进对应角色模板（作为 section）
2. 补全缺失的角色模板

```
prompt_templates/
├── executor.md       # 执行者操作规范（补全：含设计确认+角色匹配检查）
├── reviewer.md       # 审查者操作规范（补全：含评审质量协议）
├── planner.md        # 规划者操作规范（补全：含调研落地映射）
├── pangtong.md       # 庞统操作规范（新增：含一键三连闭环标准）
└── mail-handler.md   # 邮件处理规范（新增：含 inform 轻量处理）
```

**executor.md 示例**（合并后）：
```markdown
# 执行者操作规范

## 任务执行纪律
1. 先确认当前设计再改——不确定时问用户确认
2. 认领任务前检查角色匹配——评审者不认领编码任务
3. 发现实现与预期不符时，先理解当前设计逻辑

## 沟通规范
1. 回答问题要直接，先给答案再解释
2. 用户说"先不要改"时必须立即停下
...
```

**代码改动**：`bootstrap.py` 的 `build()` 方法已有 `_load_template(f"{role}.md")` 逻辑，只要文件名对应即可

**删除**：`prompt_templates/design-confirmation.md`、`role-match-check.md`、`inform-lightweight.md`（合并进角色模板后删除）

#### 改造 3：注册 Skill 到 registry（L3）

**现状**：`skill_system.py` 只加载 `.json` 格式的 skill 定义
**方案**：

1. 将 4 个 `.md` Skill 转为 `.json` 格式注册（保留 .md 作为完整参考，用 .json 做注册索引）
2. 或者：修改 `skill_system.py` 同时支持 `.md` 格式（frontmatter 解析）

**推荐方案 B**（修改 skill_system.py 支持 .md）：

```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"):
        ...
    # 新增：.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")
    # 解析 YAML frontmatter
    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
```

**文件整理**：

```
skills/
├── trial-and-error-patterns.md   # 保留（.md 即注册）
├── proven-practices.md           # 保留
├── review-quality.md             # 保留
├── self-reflection-wisdom.md     # 保留
└── ...（未来新增的 Skill 也放 .md）
```

#### 改造 4：experiences 写入黑板表（Memory）

**现状**：119 条协作经验存在 JSON 文件中
**方案**：

1. 创建黑板 `experiences` 表（课题6 D6-7 已设计）
2. 将 119 条 JSON 数据导入 `experiences` 表
3. `bootstrap.py` 的 `_format_experiences()` 已有从表读取并注入 L2 的逻辑

**SQL**：
```sql
CREATE TABLE experiences (
    experience_id TEXT PRIMARY KEY,
    source TEXT NOT NULL,
    category TEXT NOT NULL,
    summary TEXT NOT NULL,
    confidence REAL DEFAULT 0.5,
    status TEXT DEFAULT 'draft',
    created_at TEXT NOT NULL,
    created_by TEXT NOT NULL,
    ...
);
```

**删除**：`docs/research/distill-experiences-collaboration.json`（导入后删除）

---

## 3. 改造后的完整四层架构

```
L0 铁律层（~600 tokens）→ Hook 注入
    ├── config/guardrails.yaml → rules（安全红线 6 条）
    └── config/guardrails.yaml → behavior_rules（行为铁律 2 条）
    
L1 角色层（~2000 tokens）→ Agent 自带
    └── SOUL.md / IDENTITY.md / TOOLS.md / MEMORY.md

L2 引擎注入层（~1500 tokens）→ prompt_templates 按 role 拼装
    ① 操作规范（executor/reviewer/planner/pangtong/mail-handler.md）
    ② 项目背景
    ③ 任务上下文
    ④ 前序信息
    ⑤ Guardrail 规则（安全红线 + 行为铁律）
    ⑥ 审查协议
    ⑦ 经验注入（experiences 表按 tag 匹配，最多 5 条）

L3 被动参考层（按需加载）
    └── skills/*.md → frontmatter 解析 → Agent 按需读全文
```

---

## 4. 改造步骤

| # | 步骤 | 改动范围 | 说明 |
|---|------|---------|------|
| 1 | 合并 guardrails.yaml | `config/guardrails.yaml` + `guardrail.py` | 新增 behavior_rules 区 + 读取逻辑 |
| 2 | 扩充 prompt_templates | `prompt_templates/` 5 个角色文件 | 合并蒸馏内容 + 补全缺失角色 |
| 3 | 修改 skill_system.py 支持 .md | `skill_system.py` | 新增 frontmatter 解析 |
| 4 | 创建 experiences 表 | 黑板数据库 | 建表 + 导入 119 条数据 |
| 5 | 清理孤儿文件 | guardrails/ 目录删除 | 移除蒸馏产生的孤立文件 |
| 6 | 更新技术设计文档 | `technical-design-v2.6.md` | 更新四层架构说明 |

---

## 5. 与 6 种扫描模式的最终映射

| 扫描模式 | 归宿层 | 具体位置 |
|---------|-------|---------|
| ① 纠正（591） | L0 行为铁律 + L2 角色模板 | guardrails.yaml behavior_rules + executor.md |
| ② 试错（226） | L3 Skill | skills/trial-and-error-patterns.md |
| ③ 成功（200） | L3 Skill | skills/proven-practices.md |
| ④ 协作（873） | 黑板 Memory | experiences 表 |
| ⑤ 决策分歧（1241） | L2 角色模板 | executor.md 设计确认 section |
| ⑥ 经验声明（21） | L3 Skill | skills/self-reflection-wisdom.md + review-quality.md |

---

## 6. 估算工作量

| 步骤 | 工作量 | 风险 |
|------|--------|------|
| 1. guardrails.yaml 合并 | 小（改 1 文件 + 1 Python） | 低 |
| 2. prompt_templates 扩充 | 中（写 5 个角色模板） | 低 |
| 3. skill_system.py 改造 | 小（加 frontmatter 解析） | 中（需要测试） |
| 4. experiences 表创建 | 中（建表 + 导入 + bootstrap 联调） | 中 |
| 5. 清理孤儿文件 | 小（删除） | 无 |
| 6. 更新设计文档 | 小（文档更新） | 无 |

**总计**：约 1-2 天，主要是步骤 2 和 4 的模板编写和联调。

---

主公，你看这个整合方案是否合理？确认后我开始执行。