CraftKit/plugins/knowledge/skills/document-output/SKILL.md

name, description

name	description
document-output	查看、解释或维护项目的过程、共享和归档文档落盘配置。适用于初始化文档目录、处理路径冲突或用户明确要求调整落盘规则；普通开发 Skill 已能从 project.json 确定路径时不应触发。

项目文档落盘

本 Skill 维护 .craftkit/project.json 的 documents 配置并处理路径冲突，不代替需求、设计或分析 Skill 生成文档内容，也不把对话输出自动转为文件。初次创建配置由 knowledge:init 完成；本 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/ 或用户指定路径；不把交接、缓存、规范和设计目录混用。

结果

返回文档用途、项目相对目标路径、选取依据、忽略或共享状态以及冲突。用户要求修改配置时，先展示 .craftkit/project.json 的精确差异，确认后保守写入；具体文档仍由获得保存授权的业务 Skill 写入。