---
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`。

当归档由任务关闭流程触发时，只复制 `task.json` 中标记为 `archive` 的文件。归档成功后将来源交回关闭流程重新分类；本 Skill 仍不删除来源，也不直接把来源标记为删除，实际删除只能由 `knowledge:document-output close` 按已确认清单执行。