sanguo_moziplus_v2/docs/research/distill-integration-plan.md

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

日期：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 并列）

# 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 示例（合并后）：

# 执行者操作规范

## 任务执行纪律
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）：

# 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：

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 的模板编写和联调。

---

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