4.4 KiB
name, description
| name | description |
|---|---|
| document-output | 查看、解释或维护项目文档落盘配置，登记任务文档，并在任务完成时预览和执行文档关闭。适用于调整路径或生命周期规则、确认文档归属、清理过程材料；普通开发 Skill 只需读取 project.json 时不应触发。 |
项目文档落盘
本 Skill 维护 .craftkit/project.json 的 documents 配置、workRoot/<task>/task.json 任务记录和关闭门禁，不代替需求、设计或分析 Skill 生成文档内容，也不把对话输出自动转为文件。初次创建配置由 knowledge:init 完成。
选择模式
view：解释当前路径、Git 可见性和生命周期策略。configure：调整项目级documents配置。register：创建或更新task.json，登记本次新建、更新或引用的文档。close：任务完成后分类预览、沉淀、归档并清理任务文档。
执行 register 或 close 时读取文档生命周期。普通业务 Skill 可直接读取项目配置并按该引用中的最小字段更新 task.json，不需要递归调用本 Skill。
长期文档的审核状态保存在文档自身；task.json 只记录当前任务关系。修改文档前先读取 .craftkit/standards/document-maintenance.md；项目尚未初始化时使用生命周期引用中的默认规则。
路径选择
- 优先使用用户明确指定的路径；更新已有文档时延续其位置，不因新增默认值移动文件。
- 未指定路径时，读取
.craftkit/project.json的documents配置及适用项目规范，区分过程文档和共享交付文档。 - 过程文档使用
documents.workRoot/<task>/，字段缺失或为空时回退到.craftkit/local/tasks/<task>/。 - 用户明确要求共享或正式交付时使用
documents.designRoot/<task>/；字段缺失时先采用项目已明确约定的文档目录，否则建议.craftkit/designs/<task>/并确认共享用途。 - 归档只在用户要求时执行，读取
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 写入。