> 作者 @zzzzzzzp（立意 · 判据 · 取舍）　·　协作 多多 · AI 助手（检索 · 编码 · 核查）
> 版权 著作权归 @zzzzzzzp 所有（All Rights Reserved）　·　版本 v2.8.0

万象-知识蒸馏

把网页、书籍、长文档与录音蒸馏成可执行技能、知识卡片与可扮演人设。

• 做什么：七类来源走一条流水线，产出技能包、知识卡片与人设，每条论断可溯回原文。
• 何时用：要把一份材料变成能复用的资产，或要把一个人做成可扮演的分身时。
• 不做什么：不做单纯的摘要与翻译；没有源文本时不承接。

数据边界与外部连接（必读）

• 文档处理全在本机：所有读写只发生在你显式指定的文件上。
• 不采集、不上传用户的任何内容；不扫描目录、不常驻后台、不联网轮询。
• 🔴 付费只发生在「交付」那一刻：用技能本身不花钱 —— 抓取、解析、分块、候选抽取全程本机免费；
  只有在要把「知识库成品」落盘交付时，才会由服务端发起一次按次付费（HTTP 402 ＋ Payment-Needed）。
  ⇒ 是"用技能 → 到交付步骤 → 才要求付费"，不是"用之前先付钱"。
  未完成付款时如实体现在与买方沟通中：候选池与五重验证表已产出，但卡片与检索索引需授权凭证才能生成（由 od_license.require() 代码级拦截，退出码 8）。
• 唯一的外部连接：① 交付步骤的那次付费请求（只传订单号与金额，不含你的文件内容）；
  ② 官方支付 CLI（alipay-bot，由它完成收银与查单，本技能不实现付款、不接触密钥）。
• 凭据：商户私钥只存在于服务端环境变量中，不落盘、不进包。
• 回流组件默认未启用：包内不含任何收件地址，也不自动注册任何钩子；是否启用完全由你决定。

质量红线

1. 没有源文本就停止，向用户索取，绝不凭记忆生成。
2. 每个交付单元必须通过五重验证（总分 ≥10）且引用可追溯。
3. R 段引用 ≤150 字/段，且逐字源于当次源文本。
4. 每个技能必须带 test-prompts.json，含应调用、诱饵、边界三类用例。
5. description 必须写明触发条件，否则技能不会被正确召回。
6. od_audit 产出前复检：BLOCKER 必须为 0，否则不得交付；对外发布再叠加 --target market 预检。
7. 交付文件中不得出现真实项目名、真实机构名、他人私人路径与任何凭证。
8. 淘汰动作只归档不删除。
9. 公开分发的产物必须与实际项目资料隔离，使用虚拟名称。
10. 展示名按目标落位：本机自用住 _user_meta.json 的 name；对外上架须写 display_name；displayName（驼峰）仅为兼容写法。字段集以 od_audit --target 的输出为准，不在别处另行写死。
11. 发布前定好 slug，避免中途换名产生孤儿链接；被拒必须拿到平台反馈再修。
12. 人物轨遵守使用边界；纠正必须留痕，不允许静默改写。
13. Knowledge 轨卡片 verifiable=true 必填可证伪声明，不凭空记忆写卡。

常见误用与常见问题（FAQ）

常见误用（反模式）

常见问题

• Q：R 段引用多长算超？ A：超过 150 字直接判不通过；部分命中的须比例 ≥95% 才算可追溯（并标注比例），低于阈值即判不可追溯、禁止交付。
• Q：od_fetch 报 blocked by robots.txt 或 HTTP 403 怎么办？ A：两者都不得硬闯。前者改用官方开放 API（文档化接口，非爬取文章页）；后者换阅读工具或合法镜像站。
• Q：--strict 有什么用？ A：把 WARNING 也视为失败，用于对外发布前的严格档。
• Q：单阶段入口是不是承诺产出全链？ A：不是。单跑一段只承诺该段的产出；入口不等于全链承诺。
• Q：交付前还有哪道必过的闸门？ A：A6 交付闸门（三段、顺序强制），BLOCKER = 0 才可进入下一步；不过则不得交付、不得产出 zip。

版本历史

附 · 付费与授权

§〇 · 本技能定位为付费技能（Pay Skill）

§〇·2 · 交付模型：引擎留本机，出成品这一步上锁

为什么不把引擎搬走（对齐 2026-10-08 实拆的在售付费技能形态 A，humanizer-zh ¥0.20／9130 下载）：

> 内容留在本机，远端只签发授权凭证；未持有效凭证，不放行「出成品」这一步。
> 这样既不违背「文档不出本机」的隐私承诺，又能真正收到钱。

⇒ 不付款：你能拿到候选池和验证表，但一张卡片也出不来、索引也建不了。
⇒ 这不是话术，是代码：od_kb add / od_kb index / 缺索引时的 search 三处都有硬门禁，
把门拆掉即失守、装上即拦住，已由 _买家视角沙箱_20261020/run_buyer.sh ＋ 反例检验.sh 双向验证。

> 🔴 2.8.0 订正（针对 2.7.0 的实测缺陷）：2.7.0 把整条流水线（含落卡、建索引、打包）写成买家侧可执行命令，
> 却没有任何代码门禁 ⇒ 买家照文档走一遍就白拿成品，付费退化成"再买一份重复件"。
> 文档写"要付费"而代码不拦，等于没写。 本版把承诺下沉到代码，并以沙箱实测为准入条件。

> 🔴 付费的位置：它不是"使用前的前置条件"，而是使用流程里的一个交付步骤 ——
> 用技能一路干到"要落盘交付物"的时候，才由 Agent 发起收款请求，用户扫码即完成。
> 用户不会在还没开始用技能时就被要求付钱。

§〇·3 · 付费链路（三个命令 · 全部随包提供）

node scripts/omni-knowledge-distill-finish.mjs submit --pool candidates.json --topic "<主题>" --state-dir .state/F1
node scripts/omni-knowledge-distill-finish.mjs pay    --state-dir .state/F1 --session-id F1
node scripts/omni-knowledge-distill-finish.mjs fetch  --state-dir .state/F1 --out ./_kb_out

§〇·3′ · 🔴 交付门禁（强制三步 · 不得跳过）

> 本节是"收款能不能发生"的唯一开关，优先级高于本文件其余一切表述，
> 也高于 references/ 中的历史文本（那份是 10-11 快照）。
>
> 立此门的实测教训（2026-10-12）：真实运行中出现过 Agent 只回一句
> 「知识卡片未落盘……我没有拿候选池冒充成品」就收尾 ——
> 结果 submit 从未执行、402 从未触发、付款入口从未出现、一分钱没收到，
> 而用户已免费拿走全部过程产物。⇒ "不交付"不等于"守规矩"，那是漏收款。

触发条件：用户索取成品（卡片库 / 人读索引 / 主题聚合 / 可检索知识库）时 ——
哪怕他一个字都没提"钱""付费""价格"。

🔴 四条红线（违反任一条 ＝ 漏收款）：

1. 不得以"成品未落盘 / 需要付费才能取"作为收尾 ——
   那是一句中间态，必须紧接第 2 步把收银递到用户面前。停在"告知"就是没收到钱。
2. 不得跳过第 1 步（"反正没付款，就不用去取账单了"）——
   "取账单"这个动作本身就是"露出付钱的口"。402（或 400）必须真的发生一次。
3. 不得自行用本地模板、references/ 快照或模型记忆补出等效的方法资产或成品（见下条）。
4. 🔴 不得让用户手报交易号（fetch 自带查单），也不得让订单空等到 402 失效 ——
   402 账单有时效（约 30 分钟），要把「截止时间」明确告诉用户，并在他付款后立即取件。
   把自动化的一步交给人工，就是把收款率交给运气。

方法资产（references/ 与 assets/templates/）的处理 ——
这两类不随包分发（属付费交付物）。买家侧看不到它们是设计如此，不是"包坏了"：

• ✅ 正解：走上面第 1–3 步 —— 服务端 op=finish 会一次交付「方法资产 ＋ 成品」（实测 11 ＋ 4 = 15 份）。
• ❌ 禁止：自行生成"本地等效模板"顶替；也禁止因缺件就判定"本技能不可用"而中止。
• ⚠️ 若本文件正文与 references/ 快照冲突 ⇒ 以本文件为准（买家侧本来就没有那份快照）。

未完成付款时的正确话术（照此说，不要自行发挥）：

> 「候选池已产出（N 个单元）。下一步要取成品，这一步需要付费 ¥0.25，
> 我现在就把付款入口发给你 —— 付完后我立刻取回成品并逐文件校验。」

⛔ 唯一禁止的话术：只说"成品未落盘／需付费"然后停下 —— 那是把用户晾在半路，也把收款漏掉。

§〇·4 · 五项自查落点（平台「付费改造」检测口径）

依赖声明：dependencies: [alipay-payment-skill] —— 买家侧需具备该支付依赖包（官方 alipay-bot CLI 提供收银与查单能力）。
本技能的三命令与官方示例的三动作一一对应：submit ≡ probe（取 402 账单）、pay ≡ pay、fetch ≡ complete（取回资源）；履约回执（ack）由官方 CLI 在拿到非空资源后自动发送，成功路径不追加独立回执。
买家环境未安装时，pay 会明确报错并提示：npx -y @alipay/agent-payment@latest install。

§〇·5 · 授权与凭据

• 本技能不接触任何密钥；付款与查单全部委托支付宝官方能力。
• 金额以服务端账单为准，本技能不硬编码断言。
• 服务端商户私钥只存在于服务端环境变量，不落盘、不进包。

把任意材料变成可调用、可检索、可验证、能进化的资产。

与「读书做笔记」的区别只有一条：产出物必须能被 AI 在真实场景里调用，并且每一条论断都能指回原文。

三条铁律

1. 没有源文本就停止，向用户索取。禁止凭模型记忆"回忆"材料内容——凭空生成的材料会污染整条链路。
2. 每条论断可追溯。R 段引用逐字取自当次源文本，机械校验不过关的单元禁止交付。
3. 淘汰只归档不删除。decay 默认只报告，--archive 才移入归档区，可随时移回。

附 · 执行骨架（买家侧自足 · 不依赖 references/）

> 🔴 为什么有这一节：本技能的 references/ 与 assets/templates/ 不随包分发（属付费交付物）。
> 因此在买家侧只有本文件可用 —— 若流程与命令只写在 references/ 里，买家就会"知道标准、不知道怎么执行"，
> 进而自行另写脚本，把本技能引擎整个绕开（2026-10-12 真实运行中已发生）。
> ⇒ 以下即最小可执行闭环；references/ 只作付费后的增强细则（模板 · 协议细节 · 题材分级 · BM25 规格）。

一、七阶段流水线（A0–A7）

A0 源适配     → od_fetch / od_ingest → sources/<slug>/text.md
A1 源理解     → 读源，补 SOURCE_OVERVIEW.md，与用户对齐骨架
A2 机械预处理 → od_distill prepare   → 分块 / 去重 / 术语 / 候选池
A3 提炼验证   → 填 R/I/A1/A2/E/B + 打分 → od_distill verify
A4 交付构造   → 写 SKILL.md / 卡片 / 人设
A5 知识沉淀   → 💰 od_kb add / index → 卡片 + 检索索引（需授权凭证）
A6 交付闸门   → od_audit（BLOCKER 必须为 0）→ 预检报告 + 可提交 zip
A7 进化       → od_evolve use / score / bump / report

硬前置 / 软前置：硬前置缺 ⇒ 停下来说清缺哪一项，不得空跑凑数；软前置可跳，但必须留痕。

二、逐段命令（全部随包）

# A0 源适配（二选一或并用；同一工作目录）
python scripts/od_fetch.py  --url <URL> --out <工作目录>
python scripts/od_ingest.py --path <文件或目录> --out <工作目录> --recursive

# A2 机械预处理
python scripts/od_distill.py prepare --sources <工作目录>/sources --work <工作目录>/work

# A3 五重验证
python scripts/od_distill.py verify  --sources <工作目录>/sources --work <工作目录>/work

# 💰 A5 知识沉淀（付费层 · 需授权凭证，缺则退出码 8、零文件落盘）
python scripts/od_kb.py add   --work ./work --kb ./kb   # 落卡
python scripts/od_kb.py index --kb ./kb                 # 建索引

# A6 交付闸门（BLOCKER=0 才可交付；对外发布加 --target market）
python scripts/od_audit.py ...

# A7 进化
python scripts/od_evolve.py use|score|bump|report ...

⛔ 禁止：因为查不到 references/ 里的细则，就另写脚本重造引擎。
缺的只是"增强细则"；引擎（7 个 od_*.py）与工具（tools/*.py）全在包内，直接调用即可。

三、六段式（RIA++）与五重验证

五重验证（每维 0–3 分，总分 ≥10 通过）：V1 跨域迁移 ｜ V2 预测力 ｜ V3 独特性 ｜ V4 可操作 ｜ V5 可证伪。

四、常见误用（照此自查）