114 lines
5.5 KiB
Markdown
114 lines
5.5 KiB
Markdown
---
|
||
name: ks-zl-extract
|
||
description: Use when 用户要求从 ks-zl 蒸馏库、笔记库、规范库、建议库或文档库中，为当前目标项目提取适用的规范、需求摘要、示例或方案，并写入目标项目文档目录。
|
||
---
|
||
|
||
# ks-zl-extract
|
||
|
||
## 定位
|
||
|
||
从 `ks-zl` 维护的 distillation library 中读取资产索引，结合 target project 的项目特征，提取当前项目真正需要的规范、示例、需求摘要或方案到目标项目文档目录。
|
||
|
||
本 skill 不负责沉淀新资产到蒸馏库；蒸馏库资产创建和维护由 `ks-zl` 完成。本 skill 只读蒸馏库，只写目标项目文档目录，不实现业务代码。
|
||
|
||
语言硬规则：本 skill 写入目标项目的导入规范、摘要和 `extraction-report.md` 必须以中文为主体语言；技术术语、产品名、命令、配置键、API 名称、UI 原文、文件路径和代码标识保留英文原文。
|
||
|
||
## 与 ks-zl 的边界
|
||
|
||
- `ks-zl`：在蒸馏库 B 中创建 `standard`、`requirement-package`、`solution`、`example` 等资产，并维护 `_indexes/artifacts-index.json`。
|
||
- `ks-zl-extract`：在项目 A 中读取蒸馏库 B，识别项目 A 的特征，选择适用资产，写入项目 A 的规范目录，并生成 `extraction-report.md`。
|
||
- 如果提取时发现蒸馏库缺少资产或资产元数据不完整，只记录问题；不要在本 skill 中直接改蒸馏库，除非用户明确切换到 `ks-zl` 维护蒸馏库。
|
||
|
||
## 输入识别
|
||
|
||
用户通常会说：
|
||
|
||
```text
|
||
我的蒸馏库在 B，帮我提取当前项目需要的规范到 ./xxxx
|
||
```
|
||
|
||
必须识别：
|
||
- distillation library：用户指定的蒸馏库路径；若未指定则询问。
|
||
- target project：默认当前工作区；用户指定时使用指定路径。
|
||
- output directory：用户指定的 `./xxxx`；未指定时默认写入 `.ai-specs/imported-standards`。
|
||
|
||
## 工作流
|
||
|
||
1. 读取蒸馏库的 `AGENTS.md`、`README.md` 和 `_indexes/artifacts-index.json`。
|
||
2. 如果 `artifacts-index.json` 缺失但存在 `scripts/build-artifact-index.ps1`，先运行该脚本重建索引。
|
||
3. 扫描目标项目特征；优先使用本 skill 的 `scripts/detect-project-signals.ps1`。
|
||
4. 根据用户目标、项目特征和索引中的 `appliesWhen`、`tags`、`domain`、`targetOutputs` 匹配资产；可用 `scripts/select-library-assets.ps1` 先生成候选列表。
|
||
5. 高置信命中可直接提取；命中冲突或候选过多时，先给出候选清单和推荐项，等用户确认。
|
||
6. 使用 `scripts/extract-library-assets.ps1` 写入 `<output-directory>/<domain>.md` 和 `extraction-report.md`；资产的 `targetOutputs` 作为建议目标记录在输出中，不直接覆盖目标项目既有规范。
|
||
7. 生成或更新 `<output-directory>/extraction-report.md`，记录来源、命中原因、写入路径和未提取原因。
|
||
|
||
## 项目信号
|
||
|
||
常用 signals：
|
||
|
||
| Signal | 触发依据 |
|
||
| --- | --- |
|
||
| `project-has-database` | 存在 SQL、迁移脚本、ORM schema、实体模型、数据库配置或 `.ai-specs/doc-sql` |
|
||
| `designing-tables` | 用户要求表设计、字段规范、数据对象、字典或数据库文档 |
|
||
| `data-may-sync-or-recover` | 存在同步、导入、导出、补录、恢复、对账、外部编号等线索 |
|
||
| `has-api-contract` | 存在 OpenAPI、路由、controller、接口文档或 API 网关配置 |
|
||
| `has-frontend-ui` | 存在页面、组件、路由、表单、菜单或前端工程 |
|
||
|
||
信号只是匹配依据，不是确定结论。若信号来自推断，必须在 `extraction-report.md` 中标记为 inferred。
|
||
|
||
## 提取规则
|
||
|
||
- 优先提取 `type: standard` 的规范卡；它们是给跨项目复用设计的。
|
||
- 需求包只提取摘要和链接，不要把完整需求包散写进项目规范，除非用户明确要求。
|
||
- 示例和方案只作为参考材料，不得覆盖目标项目已有规范。
|
||
- 不复制整个蒸馏库；只复制命中资产的必要内容，并保留来源路径。
|
||
- 不覆盖目标项目已有确定规则；冲突时写入 `extraction-report.md` 的冲突记录并询问用户。
|
||
- 脚本生成的文件带 `generated-by: ks-zl-extract` 标记；遇到没有该标记的同名文件时，必须拒绝覆盖，除非用户明确要求 `-Force`。
|
||
|
||
## 输出格式
|
||
|
||
每个提取文件建议包含：
|
||
|
||
```markdown
|
||
# <domain> 提取规范
|
||
|
||
来源蒸馏库：<distillation-library-path>
|
||
提取时间：<YYYY-MM-DD>
|
||
|
||
## <资产标题>
|
||
|
||
来源：<relative-path-in-library>
|
||
命中原因：<signals/tags/query>
|
||
|
||
<整理后的规范正文>
|
||
```
|
||
|
||
`extraction-report.md` 必须包含：
|
||
- 扫描到的 target project signals。
|
||
- 使用的索引路径和查询条件。
|
||
- 已提取资产：来源路径、写入路径、命中原因。
|
||
- 未提取候选：原因。
|
||
- 冲突或待确认事项。
|
||
|
||
## 验证
|
||
|
||
完成前至少检查：
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File <this-skill>\scripts\detect-project-signals.ps1 -Root <target-project>
|
||
```
|
||
|
||
如果蒸馏库提供搜索脚本，优先用选择脚本验证一次命中：
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File <this-skill>\scripts\select-library-assets.ps1 -LibraryRoot <library> -TargetRoot <target-project> -Query "database" -Json
|
||
```
|
||
|
||
执行写入时使用：
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File <this-skill>\scripts\extract-library-assets.ps1 -LibraryRoot <library> -TargetRoot <target-project> -OutputDirectory .ai-specs\imported-standards -Query "database"
|
||
```
|
||
|
||
回复用户时说明写入了哪些文件、每个文件来自蒸馏库哪个资产、还有哪些候选没有提取。
|