33 lines
2.9 KiB
Markdown
33 lines
2.9 KiB
Markdown
---
|
|
name: document-output
|
|
description: 查看、解释或维护项目的过程、共享和归档文档落盘配置。适用于初始化文档目录、处理路径冲突或用户明确要求调整落盘规则；普通开发 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 写入。
|