48 lines
4.1 KiB
Markdown
48 lines
4.1 KiB
Markdown
---
|
|
name: document-output
|
|
description: 查看、解释或维护项目文档落盘配置，登记任务文档，并在任务完成时预览和执行文档关闭。适用于调整路径或生命周期规则、确认文档归属、清理过程材料；普通开发 Skill 只需读取 project.json 时不应触发。
|
|
---
|
|
|
|
# 项目文档落盘
|
|
|
|
本 Skill 维护 `.craftkit/project.json` 的 `documents` 配置、`workRoot/<task>/task.json` 任务记录和关闭门禁，不代替需求、设计或分析 Skill 生成文档内容，也不把对话输出自动转为文件。初次创建配置由 `knowledge:init` 完成。
|
|
|
|
## 选择模式
|
|
|
|
- `view`：解释当前路径、Git 可见性和生命周期策略。
|
|
- `configure`：调整项目级 `documents` 配置。
|
|
- `register`：在业务 Skill 写入任务文档时创建或更新 `task.json`。
|
|
- `close`：任务完成后分类预览、沉淀、归档并清理任务文档。
|
|
|
|
执行 `register` 或 `close` 时读取[文档生命周期](references/lifecycle.md)。普通业务 Skill 可直接读取项目配置并按该引用中的最小字段更新 `task.json`，不需要递归调用本 Skill。
|
|
|
|
## 路径选择
|
|
|
|
1. 优先使用用户明确指定的路径；更新已有文档时延续其位置，不因新增默认值移动文件。
|
|
2. 未指定路径时，读取 `.craftkit/project.json` 的 `documents` 配置及适用项目规范，区分过程文档和共享交付文档。
|
|
3. 过程文档使用 `documents.workRoot/<task>/`，字段缺失或为空时回退到 `.craftkit/local/tasks/<task>/`。
|
|
4. 用户明确要求共享或正式交付时使用 `documents.designRoot/<task>/`；字段缺失时先采用项目已明确约定的文档目录，否则建议 `.craftkit/designs/<task>/` 并确认共享用途。
|
|
5. 归档只在用户要求时执行，读取 `documents.archiveRoot` 和归档规则；不能把归档根当成草稿输出目录。
|
|
|
|
`<task>` 优先复用本次任务已有目录，否则取简短、稳定的主题名。计划与设计放在同一任务目录，后续阶段复用已有路径。不根据根目录存在 README、WORKFLOW 等说明文件推断过程文档也应放在根目录。
|
|
|
|
## 写入与兼容
|
|
|
|
- 配置路径相对当前项目根解析，使用正斜杠，不接受逃逸项目根的配置。显式用户路径按已有授权和环境权限处理。
|
|
- 已授权保存且用途和路径可确定时，说明实际路径后直接写入，不重复索取路径确认；只有规则冲突、目标已有无关内容或共享用途不明时询问。
|
|
- 更新前读取原文，保留无关内容；只创建实际需要的任务目录。格式和文件名优先延续已有任务文档。
|
|
- 缺少配置时仅使用回退路径，不隐式初始化或补写 `project.json`。
|
|
- 使用默认本地目录时检查 `.craftkit/local/` 的忽略状态；缺少忽略规则时指出缺口并给出最小补齐方案，不能把本地草稿作为普通提交候选。
|
|
- 审批通过不代表共享、归档、提交或移动授权。共享设计不是已验证知识；只有经验证的可复用决策才按知识维护流程进入 `knowledge/decisions/`。
|
|
- 交接仍使用交接 Skill 的 `.craftkit/local/handoff/` 或用户指定路径；不把交接、缓存、规范和设计目录混用。
|
|
|
|
## 任务关闭
|
|
|
|
`close` 先读取任务记录和实际文件，输出“保留、沉淀、归档、删除、延后”五类清单。完成状态不产生删除授权；只有用户已经明确批准该清单时，才能删除列入“删除”的精确路径。删除后检查任务目录、引用、Git 状态和仍需保留的文件，再把任务状态更新为 `closed`。
|
|
|
|
共享或已跟踪文件必须逐项评审。关闭过程不得删除 `.craftkit/local/config/`、凭据、个人配置、未登记文件或其他任务的文件；不确定归属时标记为“延后”。
|
|
|
|
## 结果
|
|
|
|
`view`、`configure` 和 `register` 返回用途、目标路径、选取依据、Git 状态及冲突。`close` 返回任务状态、五类清单、已执行动作和剩余文件。用户要求修改配置时，先展示 `.craftkit/project.json` 的精确差异，确认后保守写入；具体文档仍由获得保存授权的业务 Skill 写入。
|