dsh-distillation-director 4.6.5

package/manual-history/manual-v2.0.md

@@ -0,0 +1,330 @@
+# 蒸馏操作手册 v2.3（蒸馏 2.3）
+
+> 基于多本书（教育书 + 投资书单）完整蒸馏经验提炼。目标：**省钱、防卡、可复现、有版本**。
+> 2026-09-03 固化，2026-09-10 更新至 v2.3；本工作区所有蒸馏（书/视频/课程/个人经验）一律按本手册执行（AGENTS.md 已登记本手册为权威执行标准）。
+> 版本演进：v2.0（2026-09-03 五阶段+OCR+调度）→ v2.1（+§10 L2.5 档位 +§11 忠实度四道防线）→ v2.2（+§10.5 构造质量内建 rubric 前移 + 质量内建的账）→ **v2.3（+§12 会话纪律与无人值守模式）**
+
+---
+
+## 0. 总纲
+
+### 0.1 触发
+- 「蒸馏 XX / 拆书 / 把 XX 做成 skill」→ 走本手册
+- 「对已有技能体检/完善/优化」→ 走达尔文（评分+修复）
+
+### 0.2 模型分工（现实版）
+| 任务 | 谁做 | 说明 |
+|---|---|---|
+| 主流程调度、OCR、拆分、构造、写文档 | 主会话（flash） | 已验证：主会话全程可交付，且省 2/3 费用 |
+| 阶段0 骨架核验、盲测 judge、关键定稿 | 子代理（pro 默认） | 单发、小任务，不并发 |
+| 大批量提取（>30 万字符书） | 子代理分批（≤4/批） | 每批自包含，卡住即主会话接管 |
+
+### 0.3 费用纪律
+- 先查文本层：文字版 PDF 直接提取（零 OCR 费）——**所有书先跑 pymupdf 检查**
+- 扫描版：150dpi（省 75% token）+ PaddleOCR-VL 快扫（2.5s/页，是 32B 的 20 倍速）
+- 32B 只用于：问题页重跑（乱码/短页/图表页）
+- 避开计价高峰（1-4 点、6-10 点）跑重活（北京时间；**周末/节假日全天按低谷价、无需避时**——2026-09-06 用户澄清，详见 蒸馏讨论记录.md）
+
+---
+
+## 1. 输入决策树
+
+```
+拿到输入 → 判断类型
+├─ PDF：pymupdf 查文本层
+│   ├─ 有文本 → 直接提取（.work/<slug>.txt，含分页标记）【零 OCR 费】
+│   └─ 无文本（扫描版）→ 走 §2 OCR 流程
+├─ 视频/播客 → 先转文字稿（转录/字幕），再按 §3 流程
+├─ 网络文章/长文 → 抓取/复制为 txt
+└─ 个人经验/对话记录 → 走「经验蒸馏」流程（另册：复盘→提取模式→验证→技能化）
+```
+
+---
+
+## 2. OCR 标准流程（扫描版，省钱版）
+
+1. **渲染 150dpi**：pymupdf `fitz.Matrix(150/72,150/72)` → .work/<slug>_pages/page_NNN.png
+2. **PaddleOCR-VL 快扫**：模型 `PaddlePaddle/PaddleOCR-VL-1.5`，6 并发，逐页转写 → dev_ocr.txt + 进度文件
+3. **清洗**（必做）：删 `<|LOC_数字|>` 布局标记
+4. **乱码检测**（必做）：Unicode 块检测（西里尔/希腊/孟加拉/泰米尔/天城体/阿拉伯/泰文/韩文/日文假名）→ 重污染页（>1%）列清单
+5. **32B 精修**：Qwen3-VL-32B，4 并发，重跑重污染页 + 短页（<50 字符）+ 语义受损页（维果茨基节这类）
+6. **复查**：乱码检测再跑一遍，0 残留才算过
+7. **抽查**：每章中段抽 1-2 页人工/32B 复核
+
+### 关键参数（抄作业）
+- PaddleOCR：model=PaddlePaddle/PaddleOCR-VL-1.5, max_tokens=4000, 并发 6（429 限流时降 3）
+- 32B：model=Qwen/Qwen3-VL-32B-Instruct, 并发 4, 每页重试 3 次
+- 断点：进度文件（已处理页码），kill 后重跑自动跳过
+
+---
+
+## 3. 阶段流程（0-5，每阶段有门禁）
+
+### 阶段0 骨架（Adler）
+- 输入：目录/内容提要/前言 + 抽样正文
+- 产出：BOOK_OVERVIEW.md（结构/术语/命题/批判/应用潜力）
+- **门禁**：用户确认骨架（一句话主旨 + 章节结构 + 技能划分）——确认后才进阶段1
+- 省钱：主会话 flash 起草 → 1 个 pro 子代理核验（可选，大书做）
+
+### 阶段1 提取
+- 输入：章节文件（.work/chapters/chXX.txt，按目录页范围拆分，偏移=书页→PDF页）
+- 小书（<15 万字符）：**主会话直接读关键章提取**（已验证 gottman/makestick 可行，省时省钱）
+- 大书（>30 万字符）：5 类提取器子代理分批（每批 ≤4 个，每代理 1-2 章）
+- 产出：candidates/（frameworks/principles/cases/counter-examples/glossary）
+- **门禁**：候选池数量达标（框架≥30/原则≥40/术语≥50 等），不够主会话补写
+
+### 阶段1.5 验证
+- 程序化：按 id 去重合并 → verified.md
+- 主会话复核：候选质量（有原文引用 + 家长价值 + 非常识）
+- **必做盲测**：派 1 个 judge 子代理（单发！）跑 12-15 条路由 prompt，判断命中技能
+- 产出：verified.md + 盲测报告
+
+### 阶段2 构造（RIA++）
+- **主会话直接写**（已验证：六段齐全 + CHECKPOINT + 输出结构，质量过盲测）
+- 每个技能：frontmatter（name/description 含做什么+何时用+触发词）+ R/I/A1/A2/E/B + 🔴CHECKPOINT + 回答输出结构
+- description 写让位规则（与相邻技能消歧）+ 医疗/危机边界
+- **门禁**：frontmatter 校验（name 合法 + description 有触发词）+ 无空话尾巴
+
+### 阶段3 链接
+- INDEX.md（技能总览 + 引用图 + 交叉引用约定）
+- GLOSSARY.md（术语词典，家长版 30 条起）
+
+### 阶段4 测试
+- test-prompts.json：每技能 3 条（应调用/诱饵/跨技能路由），含医疗 none + 危机 + ADHD 路由
+- 主会话自查路由 → **judge 盲测**（单发子代理）→ 修复（hill-climbing）→ 同步
+
+### 阶段5 交付
+- DIGEST.md（精华长文）+ 安装两工作区（家庭教育 + PPT制作）
+- 四件套：SKILL + BOUNDARIES + INDEX + GLOSSARY
+- §7 动态增强协议（BOUNDARIES 内置：先澄清→再核验→后整合）
+- SUPPLEMENT-2025（最新研究层，〔最新·来源〕）
+- 打包插件（可选）：§6
+
+---
+
+## 4. 子代理调度规范（防卡死，血泪教训）
+
+⚠️ **教训：15 个提取器并发卡 13 个、3 个构造器全卡——大并发必卡**
+
+1. **每次最多 3-4 个子代理**，不超 5
+2. 每个任务**自包含**：给全路径、输出文件、明确格式——子代理看不到本会话
+3. 输出路径用绝对路径，写文件用 write 工具
+4. **超时处理**：子代理无产出（约 20-30 分钟）→ send_message 询问一次 → 仍无 → interrupt + 主会话接管
+5. 小任务（单个技能/单章提取）**直接主会话做**，不派子代理
+6. judge 盲测永远单发（1 个），不发批
+
+---
+
+## 5. 验证与版本
+
+### 验证三件套（每个技能必过）
+1. frontmatter 校验（name 正则 + description 有做什么/何时用/触发词）
+2. 路由盲测（judge 单发，≥10 条）
+3. 空话检查（无「灵活应用/视情况而定/建议」等软化措辞）
+
+### git 版本管理
+- books/ 下 `git init`（每本书一个仓库或子目录）
+- 每次修复/升级 commit（「v2 补 CHECKPOINT」「盲测修复×3」）
+- 回滚：git revert / checkout 旧版本（替代手动覆盖）
+
+---
+
+## 6. 打包插件（dsh plugin）
+
+1. 建包：plugin-build/<pkg-name>/（index.js 遍历 skills/ 注册 + package.json + cordis.patch.yml + README）
+2. 打包：tar -czf <pkg>.tgz package/（npm pack 在 Windows 不可靠，用 tar）
+3. 安装：`dsh.cmd plugin --profile web add <tgz>`（dsh.cmd 在 node_modules/.bin/）
+4. **坑**：遇 [ERR_PNPM_IGNORED_BUILDS] → 手动补 profile package.json 的 dsh.profile.bundles
+5. 生效：重启 DSH 服务（告知用户，不擅自重启）
+
+---
+
+## 7. 踩坑对照表（抄作业）
+
+| 坑 | 对策 |
+|---|---|
+| 子代理大并发卡死 | ≤4/批 + 超时接管（§4） |
+| SiliconFlow 32B 慢/500 | 只用 32B 修问题页；PaddleOCR 快扫主体 |
+| PaddleOCR 乱码 + <\|LOC\|> | 清洗标记 + Unicode 乱码检测 + 32B 重跑 |
+| JS 模板字符串转义报错 | 内容用数组 join 或写 python 文件，避免反引号/ASCII 引号 |
+| pwsh here-string 转义 | 长内容用 write 工具写 py 文件再执行 |
+| pnpm 构建脚本报错中断插件安装 | 手动补 bundles |
+| 子代理输出路径错误 | prompt 给绝对路径，写后主会话验证文件存在 |
+| 分类页/图页 OCR 超短 | 32B 复核，标注「图页」或补跑 |
+| 章节拆分偏移错 | 用目录页页码验证（书页=PDF页-偏移） |
+| 忘记录/忘同步 | 每阶段更新 PIPELINE_STATE + 同步两工作区 |
+
+---
+
+## 8. 检查清单
+
+### 开跑前
+- [ ] 已查文本层（文字版？）
+- [ ] 建 books/<slug>/ + PIPELINE_STATE.md
+- [ ] 确认技能目标（几个技能/与现有体系衔接）
+
+### 每阶段后
+- [ ] 更新 PIPELINE_STATE
+- [ ] 门禁通过（用户确认/候选达标/盲测过）
+- [ ] git commit
+
+### 交付前
+- [ ] 四件套齐全（SKILL/BOUNDARIES/INDEX/GLOSSARY）
+- [ ] §7 协议写入 BOUNDARIES
+- [ ] 盲测报告归档
+- [ ] 安装两工作区 + frontmatter 校验
+- [ ] 讨论记录/learnings 更新
+
+---
+
+*蒸馏 2.0 · 2026-09-03 · 基于 4 本书实战经验 · 主会话可独立完成全流程*
+## 9. 版本管理（实机方案）
+
+- 本机未安装 git（2026-09-03 检测）——用快照脚本替代：`.work/snapshot.py`（修复/升级前运行，备份到 books/.snapshots/，保留最近5版）
+- 若日后安装 git：books/ 下 `git init`，每次修复 commit，可 revert 回滚
+
+---
+
+## 10. L2.5 混合档位（2026-09-03 试点验证，承重墙书默认档）
+
+> 背景：双路线对比实验（我的裸流程 vs 仓颉完整线A，3/3 judge）证实——仓颉强在"建体系"（多路提取覆盖+淘汰验证+页码溯源），我强在"快出裁决"（整书裁决链），费用大头是 cacheRead（重复读书）。L2.5 取两者之长：**共享精读笔记把"读 N 遍全书"降为"读 1-2 遍 + N 路审阅"，用 1/2-1/3 成本达 L3 的 85-95% 质量**。
+> 试点实证：《货币放水的尽头》（10章/250页）16 子代理 ¥1.56，6 技能过达尔文 81.4 分基线，34 引文逐字核验一致。
+
+### 10.1 档位选择（书的价值决定档位）
+
+| 档位 | 适用 | 流程 | 单本粗估 | 相对L3 |
+|---|---|---|---|---|
+| L1 速读卡 | 背景书/历史书群 | 摘录卡 + 防线1/3 | ¥1-3 | ~1/5 |
+| **L2.5 体系卡（默认）** | 承重墙书 | §10.2 七步 | ¥2-5 | 1/2-1/3 |
+| L3 旗舰 | 值得反复读的书 | 仓颉完整线A | ¥5-9 | 1x |
+
+### 10.2 L2.5 七步管线
+
+```
+步骤1：PDF→章节文本（.work/chapters 模式）                    [最便宜]
+步骤2：阶段0 BOOK_OVERVIEW + 带页码精读笔记（全书读1-2遍）
+       ——"宁可多不可少"全量摘录（150-450条/本），每条带[pNN]页码
+       这是质量地基，5路提取器共享，勿偷工                    [全书1-2遍=最大单项]
+步骤3：5路提取器（framework/principle/case/counter-example/glossary）
+       ——基于精读笔记审阅+原文抽查，不各自通读全书           [省60-70%读书费]
+步骤4：三重验证(V1/V2/V3) + 目录覆盖检查(防线4)               [轻]
+步骤5：RIA++构造（按主题聚合为N个整书级技能）
+       ——限定语存疑候选必须条件式改写                        [写作成本]
+步骤6：忠实度核验关(防线3)：独立judge带原书核对
+       R段引文逐字 + 核心主张 + 操作层冒充检查 → 修复→复验    [¥0.5-1，必做]
+步骤7：达尔文9维质量关（基线评分，triage用）                  [¥0.5-1]
+```
+
+### 10.3 L2.5 关键纪律（试点血泪）
+
+1. **提取器的"限定语损失"盲区是系统性弱点**：只读笔记会把作者条件句提取得更绝对——靠"步骤4标记存疑 + 步骤5条件式改写 + 步骤6核验独立确认"两级补住，不许省；
+2. **精读笔记宁多勿少**：笔记筛选偏差是最大风险，全量摘录+带页码可回查；
+3. **并行构造 ≤4-6 个/批**（遵守 §4 并发纪律），prompt 给主题关键词让代理自主从 verified.md 选单元（勿手工对齐 id）；
+4. **书体裁影响覆盖**：历史案例体（案例密度高）与信条体（互锁）对提取器压力不同——案例体注意 case 池与主池的边界；
+5. **时代局限必标**：宏观/政策类书写作年代与当前差距大（如 2013 书 vs 2020s），技能 B 段必须诚实标注"已证伪/已改变"处，并给〔需独立取数〕纪律（§10.4）。
+
+### 10.4 家族级交付标准（试点后固化）
+
+- 每个技能补「数据更新指引（2020s）」节：3-5 个可检索更新指标，写明"不得照搬书内旧数据当现状"
+- 每个技能 E 段附 1 个成品输出示例（标注"示例非实时判断"）
+- related_skills 必须回填**实际存在**的兄弟 slug（试点曾出现 5-6 个别名指向不存在目录）
+- 输出形态定位：宏观/政策类技能 = "环境判断+风险认知"，统一拒时点与买卖指令
+
+### 10.5 构造质量内建（2026-09-10 升级：rubric 前移，评分纠错→一次做对）
+
+> 教训：此前流程"构造→评分→修复"，dim4 缺 🔴 标记、dim3 缺 fallback、步骤缺数据兜底等扣分都是评分时才被发现——**评分维度应作为构造时的验收标准，而非等第三方来查**。
+> 实证：静态可自查项占扣分 ~80%（dim1/2/3/4/5/7/9 全是"文件写得规不规范"），第一次就能清零；仅 dim8 运行期实测项（~20%）需真实调用才暴露。
+
+#### 构造代理 prompt 强制嵌入（两步，成本≈0）
+
+**① 9 维自查表（交卷前逐条打勾，不合格不发）**
+- dim1：description ≤1024 字、含"做什么+何时用+何时不用+触发词"、无空话尾巴？
+- dim2：步骤有序号、每步有输入/输出/完成标准？
+- dim3：每个"禁止 X"后面有"→ 那怎么办"的 fallback？有"用户不配合/数据不足→判停后给出路"？
+- dim4：判停是否用 **🔴 判停** 显性标记？（"如果…建议"措辞不算——rubric 明文）
+- dim5：软化词（建议/可以考虑/视情况/灵活把握）是否 ≥3 处？（转介/引文语境不计）
+- dim6：页码/章节/兄弟 slug 引用是否实际可达？
+- dim7：无 AI 腔废话（说白了/换句话说/综上）？无嵌套括号阅读税？
+- dim9：有独立"不要做"黑名单 + 红灯动作单独成节？
+
+**② 自走查（构造完、交付前，用自己 test-prompts dry-run）**
+- 构造代理必须用自己写的 test-prompts 逐条模拟走查一遍
+- 重点测边界输入：用户只给部分信息（缺市值/缺数据/缺上下文）→ 流程是否有"悬挂待补"分支？
+- 走查发现断裂/死锁 → 当场修 → 再走查 → 通过才交付
+
+#### 效果预期
+- 结构维度（59 分）从平均 50.9 → 接近 57-59（自查可清零的扣分不再出现）
+- 首次评分普遍 88-92 起步；评分后修复从"必修 3 项"降为"运行期补测 1-2 项"
+- dim8 仍需 full_test 坐实（dry_run 触发评估失效警告），属流程固有成本，不因内建而消失
+
+#### 质量内建的账（2026-09-10 cost-meter 实测：前端自查 vs 后端返工）
+
+> 结论：**净账是省，不是增**——前端每技能多花几分钱，后端省掉几毛到几块的返工，还省 2-3 轮子代理等待。
+
+**后端返工的真实成本（账本实测）**：过去几本书"评分后发现必修→派修复/复验"的返工条目合计 ¥2.56（10 条目），最贵单次 ¥1.63（80 calls 事实核验修复）；防线3 忠实度核验+修复每次 ¥0.03-0.10。返工是完整闭环（2-3 子代理串行），时间多等 2-3 轮。
+
+**前端自查的成本**：§10.5 的穷举自查 = 构造代理交卷前多做一步（不新增子代理，仅多几百 token output），粗估 +¥0.05-0.15/技能、时间 +几分钟（构造代理本就跑 10-30 分钟，自查并行不拖长）。
+
+| | 构造时自查（前端） | 评分后修复（后端） |
+|---|---|---|
+| 费用 | +¥0.05-0.15/技能 | −¥0.1-1.6/次返工 |
+| 时间 | +几分钟（几乎不感知） | +2-3 轮子代理串行等待 |
+| 效果 | 静态项归零、评分 88+ | 修完需复验、可能再发现 |
+
+**诚实边界**：dim8 full_test（真实带/不带技能对照）省不掉——必须真跑一次（¥0.5-1/本），构造时自查替代不了；但它是"一次性验证"非"返工循环"，跑一次确认达标即可。
+
+**验证方式（下次试点）**：按新流程跑一本，用 cost-meter 实测记录"构造自查花费 vs 评分后修复花费"，用真实数字验证本账，而非估算。
+
+---
+
+
+
+## 11. 内容忠实度保障协议（四道防线，全档位适用）
+
+> 完整文档：投资蒸馏/忠实度保障协议-v1.0.md（用户已确认定稿）
+> 目的：产物"不歪曲原书、不遗漏"——歪曲产物=沙上建塔
+
+| 防线 | 内容 | 成本 | 位置 |
+|---|---|---|---|
+| 1 原文锚 | 无原文引用的主张不进候选池（source_quote≤150字+页码） | ≈0 | 提取器 |
+| 2 转述派生链 | R原文→I自述强制配对；操作层◈标注不冒充书语 | ≈0 | 构造 |
+| 3 忠实度核验关 | 独立judge带原书核对：R引文逐字+核心主张全量+操作层检查→修复→复验 | ¥0.5-1/本 | 交付前门禁 |
+| 4 目录覆盖检查 | 每章零贡献须有理由（纯叙事/案例承载），不许默认放过 | ≈0 | 验证末 |
+
+**执行约定**：L1 至少防线1+3（抽验）；L2.5/L3 全四道；核验judge必须独立于构造者；修复必须复验（改了再核，不许"改了没验证"）。
+
+---
+
+## 12. 会话纪律与无人值守模式（2026-09-10 固化）
+
+> 目的：防"越蒸越慢"（会话上下文无限膨胀的正反馈恶化），并支持用户不在场时批量任务自动完成。
+> 依据：cost-meter + 进程实测——DSH 会话是"越用越重"的容器，长会话 + 多子代理回报 → 每轮变慢；蒸馏是重活，必须管控会话生命周期。
+
+### 12.1 一书一提醒（用户在场时）
+
+1. **一本书 = 一个会话批次**（无论是否批量）；用户在场时每本完成 → 提示开新会话再接下一本
+2. 会话开始前自查：本会话已承载过蒸馏/上下文重 → 先提示用户开新会话，不硬蒸
+3. 子代理回报纪律：任务子代理只回摘要（≤3 行）、全文落文件——防主会话被灌满
+4. 例外：L1 速读卡等轻任务可同会话完成，但书完成即提示换会话
+
+### 12.2 无人值守自动接管（用户不在场时）
+
+> **执行方式 = 主会话主导 + 严格按本手册逐步执行，与正常蒸馏完全一致**——不打包整书 orchestrator 子代理、不发明新流程。唯一区别：步间不等待用户确认，自动续跑直到批量完成。
+
+1. 主会话当主管，按 L2.5 流程逐步推进（阶段2→3→4→5→6→7），该派任务子代理就派，主会话掌握全部中间产物与进度
+2. 步间不等待：手册的用户检查点（阶段0骨架/阶段1.5候选）按既定分组方案自动通过；跑完一步自动下一步
+3. 每本完成必落盘（PIPELINE_STATE + 讨论记录 + 承重墙队列），自动启动队列下一本
+4. 主会话防膨胀：子代理回报收摘要、全文落文件；单批并发 ≤4-6
+5. 异常处理：某步卡死/超时按 §4 接管规则；单本反复失败 → 记状态跳过，继续下一本，结束统一报告
+6. 质量门照常（防线3 忠实度核验 + 达尔文 ≥74，独立 judge 执行不需用户在场）；不达标自动修 2 轮，仍不达标标记遗留
+7. 批量结束：汇总（每本产物路径+质量分+遗留问题）等用户确认
+
+### 12.3 模式关系
+
+- 用户在场 = 12.1（一书一提醒，建议新会话防膨胀）
+- 用户不在场无人操作 = 12.2（主会话在当前会话内自动续跑完成批量）
+- 触发：「蒸馏XX/拆书/批量蒸N本我不在场」→ 会话自查后按对应模式执行
+
+---
+
+*蒸馏 2.3 · 2026-09-10 · 在 v2.2 基础上新增 §12 会话纪律与无人值守模式（一书一提醒 + 主会话主导自动续跑，不打包整书子代理）；v2.2 新增 §10.5 构造质量内建与质量内建的账；v2.1 新增 §10 L2.5 档位 + §11 忠实度四道防线*