feat(doc): 新增文档转换与规则化归档 Skill

2026-08-25 15:32:12 +08:00
parent dbc2f65154
commit d255bdd524
20 changed files with 735 additions and 20 deletions
@@ -0,0 +1,39 @@
+---
+name: archive
+description: 按显式配置将项目文档复制、重命名、清理 Frontmatter 或抽取 Markdown 章节到归档目录，并生成操作报告。适用于需要可重复文档归档规则的项目；删除来源、猜测业务目录或隐式查询内部系统不应触发本 Skill。
+---
+
+# 文档归档
+
+使用 `scripts/archive.py` 执行中性的规则化归档。规则由当前项目维护，不携带固定组织目录、业务名称、数据库表或包结构。
+
+## 两阶段执行
+
+1. 读取 `.craftkit/project.json` 的 `documents` 配置，或使用用户指定的规则文件。
+2. 检查每条规则的来源、目标模板、转换和校验条件。
+3. 不带 `--apply` 执行预演，向用户展示复制、跳过、冲突和失败项。
+4. 用户确认后使用相同参数加 `--apply` 执行。
+5. 检查 JSON 报告和目标文件，并确认来源文件仍然存在。
+
+```text
+python scripts/archive.py --root <project> --config <rules.json> [--report <report.json>]
+python scripts/archive.py --root <project> --config <rules.json> --apply [--report <report.json>]
+```
+
+## 中性平替原则
+
+- 固定公司目录改为 `archiveRoot` 与规则级 `target` 模板。
+- 固定业务文件名改为 `{name}`、`{stem}`、`{suffix}`、`{relative}` 占位符。
+- 专有文档拆分逻辑改为通用 Markdown 标题章节抽取。
+- 内部数据库或服务校验改为显式 `requiredText` 内容校验；需要外部事实时由用户先提供结果，不隐式连接系统。
+- 来源专属元数据清理改为可选 `stripFrontmatter`，不会默认删除内容。
+
+## 安全边界
+
+- 默认只预演；`--apply` 才写入。
+- 永不删除或移动来源文件。
+- 来源必须位于项目根内，目标必须位于归档根内；拒绝绝对路径和 `..` 逃逸。
+- 冲突策略仅允许 `skip`、`overwrite`、`append`，默认 `skip`。覆盖或追加必须在用户确认的配置中明确出现。
+- 规则不执行 Shell、SQL、模板代码或网络请求。
+
+完整配置见 `references/config.md`。