diff --git a/docs/research/distill-integration-plan.md b/docs/research/distill-integration-plan.md new file mode 100644 index 0000000..bb93941 --- /dev/null +++ b/docs/research/distill-integration-plan.md @@ -0,0 +1,286 @@ +# 四层知识体系整合改造方案 + +> 日期：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 的模板编写和联调。 + +--- + +主公，你看这个整合方案是否合理？确认后我开始执行。