---
name: ks-zl
description: 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 的需求包结构。

## 来源类型

### 源项目功能提取

用户示例：

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

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

### 当前会话蒸馏

用户示例：

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

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

### 简短描述蒸馏

用户示例：

```text
/ks-ai xxx 功能需要 xxxx
```

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

## 输出类型选择

### 优先使用需求包

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

默认需求包结构：

```text
<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`，默认放在：

```text
<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
powershell -ExecutionPolicy Bypass -File <skill-root>\scripts\validate-distillation-output.ps1 -Root <output-root>
```

## 完成反馈

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