feat(knowledge): 统一维护项目文档落盘配置

2026-09-03 13:30:14 +08:00
parent a6bd0fddcf
commit aa87b8cf0b
11 changed files with 73 additions and 7 deletions
@@ -6,8 +6,9 @@
 - `agents/`：项目对 Agent 的补充指令。
 - `standards/`：项目自身的开发、测试、文档与 Git 规范。
 - `knowledge/`：经过验证的技术决策和可复用经验。
+- `designs/`：用户明确要求共享或正式交付的设计文档。
 - `handoff/`：用户明确选择共享的任务交接。
- `local/`：当前工作副本的本地上下文，不进入 Git。
+- `local/`：当前工作副本的过程文档和本地上下文，不进入 Git。
 - `cache/`：可重新生成的缓存，不进入 Git。

 共享资料不得包含凭据、个人机器绝对路径或无必要的业务数据。
@@ -49,6 +49,8 @@
    "check": []
  },
  "documents": {
+    "workRoot": ".craftkit/local/tasks",
+    "designRoot": ".craftkit/designs",
    "archiveRoot": "docs/archive",
    "archiveRules": []
  },
@@ -12,6 +12,7 @@ CraftKit 面向 Codex 插件市场，提供简洁、中性、可独立安装和
 - Agent 补充说明：`.craftkit/agents/index.md`
 - 项目规范索引：`.craftkit/standards/index.md`
 - 项目知识索引：`.craftkit/knowledge/index.md`
+- 文档目录配置：`.craftkit/project.json` 的 `documents`；过程文档、共享设计和归档目录必须分开使用。

 ## 沟通与改动

@@ -75,6 +76,7 @@ plugins/<plugin>/skills/<skill>/
 - `.craftkit/` 是项目级 Agent 配置、规范、知识和运行状态的统一目录，目录名固定为全小写；不能把整个目录视为本地缓存或整体排除。
 - 可共享内容包括 `project.json`、`agents/`、`standards/`、`knowledge/` 和 `handoff/`，可以根据用户确认正常提交和同步。
 - `project.json` 记录项目类型、技术栈、源码与包边界、内部依赖标识、常用命令和规范入口；不得记录凭据、完整连接信息或个人机器绝对路径。
+- 开发中的需求、计划、设计和验证记录默认放入 `documents.workRoot`；用户明确要求共享或正式交付时使用 `documents.designRoot`，历史归档使用 `documents.archiveRoot`。没有字段时分别回退到 `.craftkit/local/tasks/`、`.craftkit/designs/` 和项目已配置的归档根。
 - 成熟项目优先延续已有且有充分证据的风格；空项目根据需求、用户选择和已授权参考建立最小上下文，不自行猜测框架、包名或内部依赖。
 - 引用其他项目时先确认参考范围，只提炼结构、依赖、命名、测试、规范或工具约定；共享配置优先记录相对路径，不能共享的本地位置放入 `local/`。
 - 公共框架版本差异由 CraftKit 公共 profile 维护；项目在 `project.json` 选择实际版本和 profile，并在 `standards/` 保存项目补充规则。
@@ -1,6 +1,6 @@
 {
  "name": "knowledge",
-  "version": "0.3.1",
+  "version": "0.3.2",
  "description": "项目初始化、任务交接、复盘与知识沉淀工作流。",
  "author": {
    "name": "CraftKit"
@@ -9,7 +9,7 @@
  "interface": {
    "displayName": "Knowledge",
    "shortDescription": "项目初始化与知识沉淀工具",
-    "longDescription": "提供项目初始化、任务交接、Agent 复盘、知识提炼、问题经验维护和 Git 工作日志。",
+    "longDescription": "提供项目初始化、文档落盘配置、任务交接、Agent 复盘、知识提炼、问题经验维护和 Git 工作日志。",
    "developerName": "CraftKit",
    "category": "Productivity",
    "capabilities": ["Read", "Write"],
@@ -0,0 +1,32 @@
+---
+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 写入。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "项目文档落盘（knowledge:document-output）"
+  short_description: "按项目配置选择过程、共享和归档文档目录"
+  default_prompt: "使用 $document-output 查看或调整当前项目的文档落盘配置。"
@@ -26,7 +26,7 @@ description: 初始化或更新项目的 AGENTS.md 与 .craftkit 项目资料；
 5. 展示拟创建或修改的文件及关键内容，取得确认后再写入。
 6. 从 [assets](assets/project.json) 中选择模板，生成或合并 `AGENTS.md`、`.craftkit/project.json`、目录说明、嵌套忽略规则和必要索引；存在前端能力时同时准备 `.craftkit/standards/frontend/components.md` 的最小索引。
 7. 已有文件必须先完整读取并做保守合并；不明确的用户章节和字段原样保留，不直接覆盖。
-8. 初始化后验证 JSON、索引链接，以及 `.craftkit/local/`、`.craftkit/cache/` 的 Git 忽略状态。
+8. 初始化后验证 JSON、索引链接，以及 `.craftkit/local/`、`.craftkit/cache/` 的 Git 忽略状态；按[文档目录配置](references/project-config.md#文档目录)验证过程、共享设计和归档路径的用途及解析结果，不创建示例文档。
 9. 使用 `guidance` 对一个真实项目问题执行检索验证；未安装该 Skill 时改用相同的入口顺序手工验证。

 框架版本写入 `technology.frameworks`。成熟项目优先从构建清单和锁文件探测；空项目根据用户选择或参考项目建议填写。只有公共 profile 已真实存在且版本范围匹配时才写入 `profile`，否则保留为空并记录待确认事项。
@@ -35,6 +35,8 @@ description: 初始化或更新项目的 AGENTS.md 与 .craftkit 项目资料；

 ## 安全边界

+初始化或更新 `documents` 时，区分过程文档、共享交付文档与归档目标。读取已有值和明确的文档规范；缺失字段按[文档目录配置](references/project-config.md#文档目录)提出默认值，纳入第 5 步的统一预览。目录只按需创建，不因根目录已有说明文档就把根目录配置为过程文档目录。
+
 - 不读取或保存密码、令牌、私钥、完整数据库连接串和私有仓库认证信息。
 - 扫描配置文件时只提取框架、数据库类型、依赖标识等非秘密元数据；疑似凭据只报告位置和风险。
 - 参考项目只用于用户指定的结构、依赖、命名、测试、规范或工具范围，不复制业务代码和专属规则正文。
@@ -16,6 +16,7 @@
 - Agent 补充说明：`.craftkit/agents/index.md`
 - 项目规范：`.craftkit/standards/index.md`
 - 可复用知识：`.craftkit/knowledge/index.md`
+- 共享设计文档：`.craftkit/designs/`；开发中过程文档使用 `.craftkit/project.json` 配置的 `documents.workRoot`。

 ## 工作约束

@@ -7,8 +7,9 @@
 - `standards/`：项目自身的开发、测试、文档与 Git 规范。
 - `standards/frontend/components.md`：经确认的前端组件来源、版本和契约证据索引。
 - `knowledge/`：经过验证的技术决策和可复用经验。
+- `designs/`：用户明确要求共享或正式交付的设计文档。
 - `handoff/`：用户明确选择共享的任务交接。
- `local/`：当前工作副本的本地上下文，不进入 Git。
+- `local/`：当前工作副本的过程文档和本地上下文，不进入 Git。
 - `cache/`：可重新生成的缓存，不进入 Git。

 共享资料不得包含凭据、个人机器绝对路径或无必要的业务数据。
@@ -12,7 +12,12 @@
    "documentation": []
  },
  "commands": { "build": [], "test": [], "check": [] },
-  "documents": { "archiveRoot": "docs/archive", "archiveRules": [] },
+  "documents": {
+    "workRoot": ".craftkit/local/tasks",
+    "designRoot": ".craftkit/designs",
+    "archiveRoot": "docs/archive",
+    "archiveRules": []
+  },
  "guidance": {
    "agentIndex": ".craftkit/agents/index.md",
    "standardsIndex": ".craftkit/standards/index.md",
@@ -11,10 +11,26 @@
 - `dependencies.internal` 只记录用户确认可在当前仓库共享的依赖标识和用途。
 - `frontend` 记录前端框架、组件库、组件根和文档入口；路径必须是项目相对路径，版本必须有依赖清单、锁文件或用户确认作为证据。
 - `commands` 只记录经过项目文件或用户确认的命令。
- `documents.archiveRoot` 记录可共享的文档归档根；`documents.archiveRules` 记录项目确认的匹配、目标模板、转换和校验规则，不写入公司固定目录或外部系统凭据。
+- `documents` 区分过程文档、共享设计和归档目录，字段及回退行为见下方“文档目录”；归档规则不写入公司固定目录或外部系统凭据。
 - `guidance` 指向 `.craftkit/` 内的索引入口。
 - `initialization.references` 记录参考项目名称、用途、允许提炼范围和可共享的相对位置。

+## 文档目录
+
+| 字段 | 默认值 | 用途 |
+| --- | --- | --- |
+| `workRoot` | `.craftkit/local/tasks` | 开发中的需求、计划、设计草稿和验证记录，默认不提交 |
+| `designRoot` | `.craftkit/designs` | 用户明确要求共享或正式交付的设计文档 |
+| `archiveRoot` | `docs/archive` | 用户按归档规则处理的历史或正式归档文档 |
+| `archiveRules` | `[]` | 归档匹配、目标、转换和校验规则 |
+
+- 路径使用项目相对路径和正斜杠，不能包含 `..`、用户目录或其他个人机器绝对路径。
+- 初始化只写入配置，不预建空任务目录、设计目录或归档目录。
+- 成熟项目已有明确的过程文档或正式设计目录时优先延续，并展示证据；根目录中的 README、CHANGELOG 或总体工作流不能单独证明根目录是任务文档目录。
+- 用户未指定共享用途时，Skill 生成的过程文档使用 `workRoot`；用户明确要求共享或正式交付时使用 `designRoot`。
+- `archiveRoot` 不作为开发中内容的默认写入位置，归档必须按归档 Skill 的规则另行执行。
+- 旧配置只有 `archiveRoot` 时继续兼容读取；初始化更新时展示新增字段及用途，确认后保守合并。
+
 ## 前端组件信息

 - `frontend.framework` 引用 `technology.frameworks` 中已确认的前端框架名称。