40 lines
2.0 KiB
Markdown
40 lines
2.0 KiB
Markdown
---
|
|
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`。
|