aif-distillation

蒸馏

将源材料转化为实用的技能。输出不是摘要的堆砌，而是一套可操作的技能，提炼材料中的最佳实践、决策规则、工作流、检查项和示例。

步骤 0：加载配置和技能上下文

首先： 如果 .ai-factory/config.yaml 存在，请读取它，以确定：

• language.ui：用于提示、问题、进度更新和最终摘要的语言
• language.artifacts：用于生成的技能包内容（SKILL.md、references/、examples/）的语言
• language.technical_terms：用于翻译后的产物；缺省时设为 keep

如果 config.yaml 不存在，则使用默认值：

• language.ui：en
• language.artifacts：与 language.ui 相同
• language.technical_terms：keep

读取 .ai-factory/skill-context/aif-distillation/SKILL.md——如果该文件存在，则必须读取。

将技能上下文规则视为本技能的项目级覆盖规则。这些规则适用于所有生成的技能文件、参考资料、示例、源映射策略和最终报告。

输入

接受 $ARGUMENTS，可包含一项或多项：

• 本地文件
• 本地目录
• URL
• 可选的 --name <skill-name>
• 可选的 --path <directory>，用于将生成的技能包目录保存到自定义输出根目录，而非 {{skills_dir}}
• 可选的 --update，用于改进现有技能，而不是创建重复技能
• 可选的 --redact-source-map，用于完全跳过生成源映射文件和相关章节，避免将确切的源标题、URL、本地路径、仓库路径和链接引用定义写入输出
• 可选的 --split，用于根据一组材料创建多个聚焦的技能
• 可选的 --split-by <strategy>，用于选择拆分策略：
  • auto（默认）：根据用户目标、触发条件、工作流、源主题和用例推断技能边界
  • goal：按用户目标或待完成的工作拆分，无论所属领域如何
  • topic：按主要源主题或章节拆分
  • workflow：按 Agent 执行的重复操作拆分
  • audience：按不同的用户角色或实施场景拆分

如果缺少目标技能名称，则根据材料主题或用户目标生成简洁、通用的小写连字符名称，例如 clean-code-style、api-design-rules、decision-making、writing-feedback 或 meeting-facilitation。

写入任何内容之前，验证最终目标技能名称：

• 必须匹配 ^[a-z0-9]+(?:-[a-z0-9]+)*$。
• 拒绝空名称、过长名称、.、..、含点名称、路径分隔符（/ 或 \）、绝对路径、Windows 驱动器路径和隐藏名称。
• 除非用户明确说明正在开发 AI Factory 本身，否则拒绝保留名称 aif-*。
• 确定输出根目录：如果存在 --path <directory>，则使用该目录；否则使用 {{skills_dir}}。
• 将相对 --path 值视为相对于当前工作目录的路径。如果输出根目录不存在，则创建它；如果它解析为现有文件，则拒绝使用。
• 解析最终目标路径，并在创建或更新文件前确认该路径位于已解析的输出根目录之内。

单技能模式的默认目标路径：<output-root>/<skill-name>/，其中 <output-root> 为 {{skills_dir}}，除非指定了 --path。

拆分模式的默认目标路径：为每个生成的子技能创建 <output-root>/<prefix>-<child-scope>/。所有拆分出的子技能名称必须使用同一个命名空间前缀，以避免与现有技能冲突。如果指定了 --name，优先将其用作前缀；否则，根据书名或主要材料标题生成简洁前缀。如果指定了 --redact-source-map，且不应公开确切的源标题，则使用 --name 作为公开命名空间，或生成中性主题前缀。

除非用户明确表示正在开发 AI Factory 本身，否则不要将提炼后的技能保存到包的 skills/ 目录中。

工作流

1. 准备源材料。

   • 对于普通文本、Markdown、JSON、YAML、HTML 或代码文件，直接读取。
   • 对于大型文件夹或 PDF，仅在有可用的 Python 3 解释器时使用 {{skills_dir}}/aif-distillation/scripts/material-prep.py。依次通过 python3 --version、python --version、py -3 --version，然后 py --version 检测；使用第一个成功退出且报告 Python 主版本为 3 的命令。
   • 调用辅助脚本时，将选定的解释器展开为具体命令形式，例如 python3 ...material-prep.py 或 py -3 ...material-prep.py。不要运行任意 Python 负载；预先批准的工具约定仅涵盖版本探测和执行 material-prep.py。
   • 如果没有 Python 3，不要调用辅助脚本。继续使用 Read/Glob/Grep/find/wc 直接抽样可访问的文本文件；对于 PDF 或非常大的源材料，请用户提供文本/Markdown 导出，并明确说明覆盖范围有所缩减。
   • 对于 URL，获取源材料以及理解主题所需的关键链接页面。

2. 提炼，而非照搬。

   • 提取可迁移的原则、工作流、启发式方法、检查清单、术语和失败模式。
   • 决定输出结构前，先盘点源材料中的示例，尤其是代码片段。
   • 按主题对源材料示例分组，以便后续检查覆盖情况。
   • 仅在必要时保留简短的源材料摘录。优先转述并注明来源。
   • 将叙述性建议转化为 Agent 可执行的指令，并将源材料示例改写为原创且可复用的示例。

3. 选择单技能或拆分技能设计。

   • 默认采用单技能模式，除非存在 --split 或 --split-by。
   • 在拆分模式下，先确定一个共享命名空间前缀，再编写边界映射。存在 --name 时使用它；否则使用规范化后的书籍/材料标题。每个拟定的子项名称都必须以 <prefix>- 开头。
   • 在拆分模式下，编写技能边界映射后再开始写作：拟定的带前缀技能名称、面向用户的任务、触发描述、负责的源材料主题、所需的参考资料/示例，以及重叠风险。
   • 如果材料包含应分别触发的独立目标，例如审查、规划、诊断、改写、教学、决策、测试、引导、审计或故障排查，优先采用拆分模式。
   • 根据用户目标或待完成任务命名拆分后的子项，而不是根据抽象的源材料主题命名。根据材料所属领域选择目标分类：软件领域可以使用 refactoring-review、test-design 或 framework-fit-review；写作领域可以使用 argument-edit 或 style-review；运维领域可以使用 incident-triage 或 runbook-review；管理领域可以使用 decision-brief 或 stakeholder-analysis；学习领域可以使用 concept-coach 或 practice-drill。
   • 避免使用 framework-evolution、principles、philosophy、chapter-4、mindset 或 overview 等含糊的生命周期或章节名称，除非这正是用户要求使用的公开分类。
   • 不要将仅措辞不同的内容拆分成多个细小技能。如果候选技能的触发条件、工作流和参考资料需求大体重叠，则将其合并。
   • 确保生成的每个子技能都能独立发挥作用：包含清晰的前置信息、聚焦的工作流以及相关的参考资料/示例。如果未提供 --redact-source-map，则包含各自的来源映射；如果提供了，则不要创建 references/SOURCE-MAP.md，也不要添加来源映射章节。

4. 设计目标技能包。

   • 让目标 SKILL.md 聚焦于用途、触发条件和工作流。
   • 让生成的技能从目录名称和 frontmatter 中就能清楚说明自身用途。描述必须以动作动词开头，并说明该技能会审查、改进、生成或检查什么。
   • 在每个生成的 SKILL.md 开头附近，用通俗语言说明：该技能的用途、适用场景，以及应生成的输出。用户无需查看源材料，就应能理解该技能为何存在。
   • 将详细知识放入 references/。
   • 将可复用的提示词、案例和转换后的示例放入 examples/。
   • 如果材料通过代码示例讲解编程，请创建或更新示例文件，提供原创的转换前后代码片段或精简的代码模式。不要仅因不适合逐字复制就省略代码示例。
   • 对于书籍级别或范围广泛的代码材料，请为每个主要的代码相关主题提供经过改编的示例，或说明该主题为何不需要示例。如果一个文件会沦为浅尝辄止的汇编，请将示例拆分到多个文件中。
   • 仅当工作流需要可重复处理时才添加脚本。
   • 写入前，根据 --path 或 {{skills_dir}} 确定 <output-root>。将 --path 视为生成技能包的父目录，而非技能包名称。
   • 在单技能模式下，使用选定的简洁名称，将技能包保存到 <output-root>/<skill-name>/。
   • 在拆分模式下，将每个子技能包直接保存到 <output-root>/<prefix>-<child-scope>/。即使子范围本身已足够明确，也不要省略共享前缀。
   • 存在 --redact-source-map 时，不要创建 references/SOURCE-MAP.md，不要在任何生成文件中创建 “Source Map” 章节，并删除起草过程中意外创建的任何空 SOURCE-MAP.md。在 --update 模式下，除非用户明确要求删除或重写，否则保留已有的非空 SOURCE-MAP.md 不变。
   • 生成技能内容时，使用解析后的 language.artifacts，除非源材料或用户明确要求使用其他语言。

5. 写入前检查现有内容。

   • 如果目标技能已有匹配的参考资料或示例，请就地更新。
   • 不要创建名称不同但内容近似重复的文件。
   • 保留有用的现有材料，只添加缺失的内容或提炼得更好的内容。
   • 在拆分模式下，还要检查 <output-root> 下已有的同级技能是否存在匹配的触发条件。如果指定了 --update，请更新匹配的技能，而不是创建近似重复的新子技能。

6. 验证实用性。

   • 技能必须告诉 Agent 应做什么、何时执行、什么样的输出才算优质，以及应避免哪些错误。
   • 名称和描述必须适合直接调用。如果用户还会问“这个技能具体做什么？”，则在完成前重命名或重写触发条件。
   • 参考资料必须内容翔实、易于浏览。
   • 示例必须展示决策或转换过程，而非装饰性填充。
   • 如果源材料包含有意义的代码片段或完整示例，生成的技能必须包含经过改编的示例。缺少改编示例时，必须在完成前补齐。
   • 示例覆盖范围必须与源材料一致：未指定 --redact-source-map 时，请在源映射中记录这一点；指定时，则在内部验证覆盖情况，不要写入源映射文件或章节。
   • 生成的技能在读写项目产物时，必须包含产物归属和配置策略章节。
   • 生成的质量门禁技能必须遵循 /aif-verify 参考资料中的 aif-gate-result 契约。
   • 在拆分模式下，每个子技能都必须有独特的激活触发条件。如果两个子技能会针对同一请求激活，并执行相同工作，则应在完成前合并。

必需的辅助指南

在生成或更新精炼后的技能前，请先阅读以下文件：

• references/DISTILLATION-PROTOCOL.md
• references/OUTPUT-STRUCTURE.md
• references/LARGE-MATERIALS.md

调用方式请参考 examples/REQUESTS.md。

产物所有权

• 主要所有权：位于 <output-root>/<skill-name>/ 下生成或更新的技能包，或在拆分模式下位于 <output-root>/<prefix>-<child-scope>/ 下的多个直接子级技能包。除非用户传入 --path <directory>，否则 <output-root> 为 {{skills_dir}}。
• 只读上下文：.ai-factory/config.yaml、现有 AI Factory 上下文产物，以及除更新模式下选定目标技能以外的现有技能文件。
• 配置策略：仅针对 language.ui、language.artifacts 和 language.technical_terms 读取配置。不要写入 config.yaml。