From aa87b8cf0be84bf8cf7bbf44ab6e47b9fb655ccf Mon Sep 17 00:00:00 2001 From: "zhiye.sun" Date: Thu, 3 Sep 2026 13:30:14 +0800 Subject: [PATCH] =?UTF-8?q?feat(knowledge):=20=E7=BB=9F=E4=B8=80=E7=BB=B4?= =?UTF-8?q?=E6=8A=A4=E9=A1=B9=E7=9B=AE=E6=96=87=E6=A1=A3=E8=90=BD=E7=9B=98?= =?UTF-8?q?=E9=85=8D=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .craftkit/README.md | 3 +- .craftkit/project.json | 2 ++ AGENTS.md | 2 ++ plugins/knowledge/.codex-plugin/plugin.json | 4 +-- .../knowledge/skills/document-output/SKILL.md | 32 +++++++++++++++++++ .../skills/document-output/agents/openai.yaml | 4 +++ plugins/knowledge/skills/init/SKILL.md | 4 ++- .../knowledge/skills/init/assets/AGENTS.md | 1 + .../skills/init/assets/craftkit-README.md | 3 +- .../knowledge/skills/init/assets/project.json | 7 +++- .../skills/init/references/project-config.md | 18 ++++++++++- 11 files changed, 73 insertions(+), 7 deletions(-) create mode 100644 plugins/knowledge/skills/document-output/SKILL.md create mode 100644 plugins/knowledge/skills/document-output/agents/openai.yaml diff --git a/.craftkit/README.md b/.craftkit/README.md index 4e2df44..4c1911f 100644 --- a/.craftkit/README.md +++ b/.craftkit/README.md @@ -6,8 +6,9 @@ - `agents/`：项目对 Agent 的补充指令。 - `standards/`：项目自身的开发、测试、文档与 Git 规范。 - `knowledge/`：经过验证的技术决策和可复用经验。 +- `designs/`：用户明确要求共享或正式交付的设计文档。 - `handoff/`：用户明确选择共享的任务交接。 -- `local/`：当前工作副本的本地上下文，不进入 Git。 +- `local/`：当前工作副本的过程文档和本地上下文，不进入 Git。 - `cache/`：可重新生成的缓存，不进入 Git。 共享资料不得包含凭据、个人机器绝对路径或无必要的业务数据。 diff --git a/.craftkit/project.json b/.craftkit/project.json index 7960752..7b8984b 100644 --- a/.craftkit/project.json +++ b/.craftkit/project.json @@ -49,6 +49,8 @@ "check": [] }, "documents": { + "workRoot": ".craftkit/local/tasks", + "designRoot": ".craftkit/designs", "archiveRoot": "docs/archive", "archiveRules": [] }, diff --git a/AGENTS.md b/AGENTS.md index a3be1ae..cbd2133 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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//skills// - `.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/` 保存项目补充规则。 diff --git a/plugins/knowledge/.codex-plugin/plugin.json b/plugins/knowledge/.codex-plugin/plugin.json index ae781c1..5b65979 100644 --- a/plugins/knowledge/.codex-plugin/plugin.json +++ b/plugins/knowledge/.codex-plugin/plugin.json @@ -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"], diff --git a/plugins/knowledge/skills/document-output/SKILL.md b/plugins/knowledge/skills/document-output/SKILL.md new file mode 100644 index 0000000..ce95776 --- /dev/null +++ b/plugins/knowledge/skills/document-output/SKILL.md @@ -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//`，字段缺失或为空时回退到 `.craftkit/local/tasks//`。 +4. 用户明确要求共享或正式交付时使用 `documents.designRoot//`；字段缺失时先采用项目已明确约定的文档目录，否则建议 `.craftkit/designs//` 并确认共享用途。 +5. 归档只在用户要求时执行，读取 `documents.archiveRoot` 和归档规则；不能把归档根当成草稿输出目录。 + +`` 优先复用本次任务已有目录，否则取简短、稳定的主题名。计划与设计放在同一任务目录，后续阶段复用已有路径。不根据根目录存在 README、WORKFLOW 等说明文件推断过程文档也应放在根目录。 + +## 写入与兼容 + +- 配置路径相对当前项目根解析，使用正斜杠，不接受逃逸项目根的配置。显式用户路径按已有授权和环境权限处理。 +- 已授权保存且用途和路径可确定时，说明实际路径后直接写入，不重复索取路径确认；只有规则冲突、目标已有无关内容或共享用途不明时询问。 +- 更新前读取原文，保留无关内容；只创建实际需要的任务目录。格式和文件名优先延续已有任务文档。 +- 缺少配置时仅使用回退路径，不隐式初始化或补写 `project.json`。 +- 使用默认本地目录时检查 `.craftkit/local/` 的忽略状态；缺少忽略规则时指出缺口并给出最小补齐方案，不能把本地草稿作为普通提交候选。 +- 审批通过不代表共享、归档、提交或移动授权。共享设计不是已验证知识；只有经验证的可复用决策才按知识维护流程进入 `knowledge/decisions/`。 +- 交接仍使用交接 Skill 的 `.craftkit/local/handoff/` 或用户指定路径；不把交接、缓存、规范和设计目录混用。 + +## 结果 + +返回文档用途、项目相对目标路径、选取依据、忽略或共享状态以及冲突。用户要求修改配置时，先展示 `.craftkit/project.json` 的精确差异，确认后保守写入；具体文档仍由获得保存授权的业务 Skill 写入。 diff --git a/plugins/knowledge/skills/document-output/agents/openai.yaml b/plugins/knowledge/skills/document-output/agents/openai.yaml new file mode 100644 index 0000000..9841454 --- /dev/null +++ b/plugins/knowledge/skills/document-output/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "项目文档落盘（knowledge:document-output）" + short_description: "按项目配置选择过程、共享和归档文档目录" + default_prompt: "使用 $document-output 查看或调整当前项目的文档落盘配置。" diff --git a/plugins/knowledge/skills/init/SKILL.md b/plugins/knowledge/skills/init/SKILL.md index aa3d28d..ebc8452 100644 --- a/plugins/knowledge/skills/init/SKILL.md +++ b/plugins/knowledge/skills/init/SKILL.md @@ -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 步的统一预览。目录只按需创建，不因根目录已有说明文档就把根目录配置为过程文档目录。 + - 不读取或保存密码、令牌、私钥、完整数据库连接串和私有仓库认证信息。 - 扫描配置文件时只提取框架、数据库类型、依赖标识等非秘密元数据；疑似凭据只报告位置和风险。 - 参考项目只用于用户指定的结构、依赖、命名、测试、规范或工具范围，不复制业务代码和专属规则正文。 diff --git a/plugins/knowledge/skills/init/assets/AGENTS.md b/plugins/knowledge/skills/init/assets/AGENTS.md index 9be7f89..b38a9b5 100644 --- a/plugins/knowledge/skills/init/assets/AGENTS.md +++ b/plugins/knowledge/skills/init/assets/AGENTS.md @@ -16,6 +16,7 @@ - Agent 补充说明：`.craftkit/agents/index.md` - 项目规范：`.craftkit/standards/index.md` - 可复用知识：`.craftkit/knowledge/index.md` +- 共享设计文档：`.craftkit/designs/`；开发中过程文档使用 `.craftkit/project.json` 配置的 `documents.workRoot`。 ## 工作约束 diff --git a/plugins/knowledge/skills/init/assets/craftkit-README.md b/plugins/knowledge/skills/init/assets/craftkit-README.md index bb4166c..1ba965c 100644 --- a/plugins/knowledge/skills/init/assets/craftkit-README.md +++ b/plugins/knowledge/skills/init/assets/craftkit-README.md @@ -7,8 +7,9 @@ - `standards/`：项目自身的开发、测试、文档与 Git 规范。 - `standards/frontend/components.md`：经确认的前端组件来源、版本和契约证据索引。 - `knowledge/`：经过验证的技术决策和可复用经验。 +- `designs/`：用户明确要求共享或正式交付的设计文档。 - `handoff/`：用户明确选择共享的任务交接。 -- `local/`：当前工作副本的本地上下文，不进入 Git。 +- `local/`：当前工作副本的过程文档和本地上下文，不进入 Git。 - `cache/`：可重新生成的缓存，不进入 Git。 共享资料不得包含凭据、个人机器绝对路径或无必要的业务数据。 diff --git a/plugins/knowledge/skills/init/assets/project.json b/plugins/knowledge/skills/init/assets/project.json index b98eee9..df76699 100644 --- a/plugins/knowledge/skills/init/assets/project.json +++ b/plugins/knowledge/skills/init/assets/project.json @@ -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", diff --git a/plugins/knowledge/skills/init/references/project-config.md b/plugins/knowledge/skills/init/references/project-config.md index 202603a..e5e41d5 100644 --- a/plugins/knowledge/skills/init/references/project-config.md +++ b/plugins/knowledge/skills/init/references/project-config.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` 中已确认的前端框架名称。