ks-zl/SKILL.md

name, description

name	description
ks-zl	Use when 用户输入 /ks-ai 或 /ks-zl，要求把项目功能、当前会话中的需求/方案/业务规则，或简短功能描述蒸馏成可复用、可交付给 AI 还原功能的标准化文档。

ks-zl

定位

把功能、需求、边界、业务规则、方案和参考材料蒸馏成标准化文档资产，目标是让后续 AI 能基于文档尽量 1:1 还原功能。

本 skill 自带最小写入规范、模板和校验脚本，不依赖固定蒸馏库。它只负责沉淀文档资产，不实现源项目功能，不修改源项目业务代码。

核心原则：蒸馏结果以功能为中心，不以来源项目或技术栈为中心。Java admin、Go service、Python app、前端页面、数据库表和接口路径都只能作为来源证据或参考材料；需求本体必须描述跨技术栈可还原的业务能力。

短文档原则：默认产物是“功能规格卡片”，不是 PRD、设计文档或项目说明书。只写功能、流程、表、字段、字典、规则、验收和必要来源；不写长篇背景、价值论证、技术选型、实现调用链或泛化说明。

默认输出位置

1. 用户明确给出输出路径时，写入该路径。
2. 用户未给出输出路径时，优先写入当前工作区。
3. 当前工作区不是合适的落点，且无法从上下文判断目标位置时，再询问用户。

如果输出路径已有自己的 AGENTS.md、README.md、templates/ 或校验脚本，先读取它们以理解目录、索引、历史模板和可用校验；写入规范默认仍以本 skill 为准。

本地优先级判定：

• 本地 AGENTS.md 或 README.md 明确声明“写入使用 ks-zl”或“不维护独立写入规范”时，按本 skill 写入；本地 templates/、scripts/ 只作为辅助资产按需使用。
• 只有本地规则明确要求某个模板、章节、路径或校验脚本时，才覆盖本 skill 的默认写入规范。
• 仅存在 templates/ 或校验脚本，不等于本地写入规范优先；不要因为历史模板存在就反向覆盖本 skill 的需求包结构。

来源类型

源项目功能提取

用户示例：

/ks-ai 帮我把 xxx 功能蒸馏到 C:\path\to\output

处理方式：

• 在当前源项目中定位 xxx 功能相关代码、文档、配置、数据库、API、页面、任务、权限、异常和测试。
• 只读取必要文件；先通过文件名、路由、模块名、接口名、菜单名、表名、关键词缩小范围。
• 提取功能目标、角色和权限、业务流程、输入输出、状态流转、边界、异常、依赖、验收方式和可复用业务规则。
• 将 Java、Spring、MyBatis、Gin、Django、SQL、接口路径、代码目录等实现细节放入 来源依据 或 references/；除非用户明确要求且它本身就是业务约束，不得写成确定需求。
• 如果没有可读取的源项目上下文，只根据用户描述创建需求草稿，并把缺失信息写入 待确认 或 decisions.md 的 待确认事项。
• 将强依赖参考材料复制或整理到需求包 references/，不要只保留源项目绝对路径。

当前会话蒸馏

用户示例：

/ks-ai 蒸馏当前会话到 C:\path\to\output

处理方式：

• 汇总当前会话中已经明确的功能需求、方案、业务规则、边界、决策和未确认事项。
• 只把用户确认或对话中明确成立的内容写成确定规则。
• 模糊、冲突或未确认内容写入 待确认 或 decisions.md 的 待确认事项。
• 不要求存在源项目。

简短描述蒸馏

用户示例：

/ks-ai xxx 功能需要 xxxx

处理方式：

• 把用户描述作为需求初稿。
• 不编造缺失业务规则。
• 能确定的写入主需求；不能确定的写入待确认事项。
• 不要求存在源项目。

输出类型选择

优先使用需求包

当目标是“以后在新项目中让 AI 根据文档 1:1 还原功能”时，创建或更新需求包，而不是单篇解决方案文档。

默认需求包结构：

<output-root>/<capability-domain>/requirement-packages/<slug>/
  requirement.md
  decisions.md
  acceptance.md
  references/

capability-domain 默认从功能领域判断，例如 access-control、workflow、inventory、reporting、billing、content-management、notification、integration、admin-operations。不要用来源项目名、语言、框架或技术层目录作为需求包主目录。slug 使用小写英文、数字和连字符。若输出路径已有 skill-requirements 或 feature-requirements 需求包目录，沿用既有命名；不要创建并行规范。

新建需求包时，使用 templates/requirement-package/。requirement.md 至少写清：

• 功能
• 流程
• 数据表
• 字典
• 业务规则
• 验收
• 移植说明
• 来源依据
• 待确认
• Related

decisions.md 和 acceptance.md 是审计/补充旁路文件，默认保持简短。能写进 requirement.md 的验收不要在 acceptance.md 重复扩写；只有冲突、覆盖、闭环缺口或用户批准记录需要进入 decisions.md。

使用解决方案文档

只有当内容是故障、根因、排查经验、技术问题或可复用解决办法，而不是完整功能需求时，才使用单篇解决方案文档。

解决方案文档使用 templates/solution-template.md，默认放在：

<output-root>/<domain>/<slug>.md

命名规范

• 目录名和文件名默认使用 ASCII 小写 kebab-case：a-z、0-9、-；不使用中文、空格、下划线、日期前缀或版本号，除非目标路径本地规则明确要求。
• capability-domain 必须是可检索的功能域或能力域，例如 access-control、workflow、inventory、reporting、billing、content-management、notification、integration、admin-operations。
• 禁止用技术层、语言、框架、来源项目名作为需求包主目录，例如 backend、frontend、infra、devops、java、go、python、spring、gin、django、admin-service。
• 需求包目录默认是 requirement-packages；若输出路径已有 skill-requirements 或 feature-requirements，沿用既有目录。
• slug 从功能目标生成，使用 2-6 个英文关键词，优先表达对象和能力，例如 permission-menu-sync；不要使用 new-feature、misc、test 这类泛名。
• 同一主题已存在时更新原包；同名但语义不同且确需新建时，在 slug 末尾追加区分对象，例如 permission-menu-sync-admin。
• 参考材料文件名也使用 kebab-case，按用途命名，例如 api-contract.md、ui-flow.md、source-tree.md、database-schema.md。

查找规范

查找目标路径已有内容时：

• 先读目标路径的 AGENTS.md、README.md、templates/ 和校验脚本，只读取存在且和当前任务相关的文件；区分“读取/定位规则”“辅助资产”和“明确写入规范”。
• 用 rg --files 查找 requirement.md、decisions.md、acceptance.md、status: requirement-draft、status: distilled、候选 slug 和中文/英文关键词。
• 先匹配路径和标题，再读候选包的 功能、流程、数据表、字典、业务规则；目标能力相同则更新原包，不新建。
• 只有目标能力、边界或还原目标明显不同，才创建新需求包。
• 若目标路径有 _indexes/，更新已有索引；没有 _indexes/ 时不创建索引系统。

查找源项目功能时：

• 先用用户给出的功能名、路由、模块名、接口名、菜单名、表名、任务名、权限标识和关键词缩小范围。
• 优先读取入口文件、路由/API 定义、数据模型、配置、测试和最近相关文档；不要默认全仓库扫描。
• 每次扩展阅读范围都要能说明它和目标功能的关系。
• 读取源项目材料后，先抽象成功能概念，再写需求；不要按源码目录、类名、接口路径或表结构组织需求本体。

新增和更新需求工作流

处理任何新增、补充或更新需求时，先完成判断，再写入确定内容：

1. 定位候选需求包：按查找规范找同 slug、同标题、同目标能力、同业务对象或同验收目标的需求包。
2. 判断关系：标记为 new、additive、conflict、replacement 或 split-needed。
3. 检查闭环：确认 功能、流程、数据表、字典、业务规则、验收、移植说明 是否足够让后续 AI 还原；缺失则记录到 闭环检查 和 待确认。
4. 检查冲突：如果新需求与旧需求的已确认规则、边界、验收、数据对象或参考材料冲突，禁止直接覆盖旧内容。
5. 给出方案：对每个冲突或闭环缺口，给用户 2-3 个互斥方案，并明确推荐一个最优方案和推荐理由。
6. 等待确认：涉及覆盖、删除、替换、重解释旧确定规则时，必须先得到用户明确同意，再修改旧规则。
7. 记录决策：把冲突、闭环检查、候选方案、推荐项和用户批准记录写入 decisions.md。
8. 再写文档：只有已确认的内容写入确定章节；未确认内容只写入 待确认事项 或 待确认。

默认推荐策略：

• 冲突但用户没有明确说新需求取代旧需求：推荐“保留旧确定规则，把新内容作为待确认冲突记录”。
• 用户明确要求新需求覆盖旧需求：推荐“覆盖前先展示差异和影响，获得明确批准后替换”。
• 需求不闭环：推荐“先补齐最小闭环问题，再写确定需求”；如果用户要求先保存，只能保存为 draft，并把缺口写入待确认。
• 多个目标能力混在一起：推荐“拆成多个需求包”，不要把无关能力塞进同一包。

需求写入规范

• 主文档写短规格，默认不超过 120 个非空行；超出时必须拆分功能、裁剪重复内容或把证据移入 references/。
• 禁止新增 背景、价值、目标、技术方案、详细设计、接口设计、架构设计 这类容易扩写的一级章节；必要证据放进 来源依据 或 references/。
• 不写“为了提升体验”“系统需要支持完整能力”这类空泛句；每一条都必须能落到流程、表字段、字典值、规则或验收。
• 功能 只写这个功能做什么、谁触发、产生什么结果，最多 5 条。
• 流程 只写主流程和影响实现/验收的关键分支，不写类名、方法名、调用链或目录结构。
• 数据表 必须写需要新增或复用的逻辑表；每张表只列业务字段、含义、类型/值域、必填和规则。不需要表时写 不新增表，复用：... 或 不涉及表。
• 字典 必须写需要新增或复用的字典和值域；不需要字典时写 不新增字典。
• 业务规则 只写确定规则、边界、异常和禁止行为；不要把来源项目的代码结构写成规则。
• 验收 只写可判断结果的检查项，避免和 流程 重复。
• 移植说明 只写两类内容：跨技术栈必须保留的业务语义、来源实现仅作参考的内容。
• 来源依据 只列关键依据，不复制大段源码或旧文档。
• 待确认 只放会影响功能还原或实现决策的问题；没有则写 无。

参考材料规则

• references/ 是强依赖材料，后续还原功能时必须随需求包一起交给 AI。
• 外部绝对路径只能记录来源，不能作为后续还原时必须读取的唯一依据。
• 复制参考材料前必须脱敏和裁剪：删除真实密码、token、私钥、客户数据、真实公网 IP、内部地址、域名和账号。
• 参考材料过大时，先放结构快照、关键片段、规则摘要和文件清单；不要无差别复制整个项目。
• requirement.md 必须说明每份参考材料的用途。
• Related 只放弱关联知识，不替代 references/。

查找和落点

1. 解析用户指定的输出路径；未指定时使用当前工作区。
2. 读取输出路径的本地规则和辅助资产；只有本地明确规定写入格式时才优先遵守，否则使用本 skill 的写入规范和模板。
3. 需求包按功能域判断落点，例如 access-control、workflow、inventory、reporting；只有单篇技术解决方案文档才按技术问题分类。
4. 先查找输出路径中是否已有相关文档或需求包。
5. 如果已有，更新原文档或原需求包；不要创建重复包。
6. 如果没有，按默认结构创建新文档或新需求包。
7. 如果输出路径有 _indexes/，按本地规则更新索引；没有 _indexes/ 时不强制创建索引。

写入标准

• 中文为主体语言，技术术语保留英文原文。
• 保留可执行的边界和验收，不写空泛总结。
• 不把未确认事项写成确定结论。
• 不把实现细节伪造成业务需求；代码、接口、SQL、页面细节只有在用户或源材料明确时才写，且默认放入证据或参考材料，不作为跨技术栈必须还原的规则。
• 如果从源项目提取功能，必须在 来源依据 和 待确认 中区分“已观察事实”“推断”“待确认”。
• 当前会话和简短描述蒸馏必须能在没有源项目的情况下完成。
• 完成后先运行与当前写入规范匹配的校验：本地规则明确要求本地校验脚本时先运行本地脚本；随后运行本 skill 自带校验作为需求包结构、敏感信息和短规格的基线检查。

powershell -ExecutionPolicy Bypass -File <skill-root>\scripts\validate-distillation-output.ps1 -Root <output-root>

完成反馈

回复用户时说明：

• 创建或更新了哪个文档/需求包路径。
• 提取了哪些核心内容。
• 复制或整理了哪些 references/。
• 校验命令和结果。
• 仍有哪些 待确认 或 pending 决策。