diff --git a/.craftkit/README.md b/.craftkit/README.md index 4c1911f..31b51b3 100644 --- a/.craftkit/README.md +++ b/.craftkit/README.md @@ -2,13 +2,13 @@ 本目录保存当前项目可供 Agent 使用的配置、规范、知识和交接内容。 -- `project.json`：项目类型、技术栈、代码边界、依赖标识和命令。 +- `project.json`：项目类型、技术栈、代码边界、依赖标识、命令和文档生命周期默认策略。 - `agents/`：项目对 Agent 的补充指令。 - `standards/`：项目自身的开发、测试、文档与 Git 规范。 - `knowledge/`：经过验证的技术决策和可复用经验。 - `designs/`：用户明确要求共享或正式交付的设计文档。 - `handoff/`：用户明确选择共享的任务交接。 -- `local/`：当前工作副本的过程文档和本地上下文，不进入 Git。 +- `local/`：当前工作副本的过程文档、任务记录和本地上下文，不进入 Git；其中个人配置不属于任务清理范围。 - `cache/`：可重新生成的缓存，不进入 Git。 共享资料不得包含凭据、个人机器绝对路径或无必要的业务数据。 diff --git a/.craftkit/project.json b/.craftkit/project.json index 7b8984b..3b2392d 100644 --- a/.craftkit/project.json +++ b/.craftkit/project.json @@ -52,7 +52,13 @@ "workRoot": ".craftkit/local/tasks", "designRoot": ".craftkit/designs", "archiveRoot": "docs/archive", - "archiveRules": [] + "archiveRules": [], + "lifecycle": { + "onTaskComplete": "preview", + "localRetentionDays": 7, + "trackedFiles": "review-required", + "personalConfig": "retain" + } }, "guidance": { "agentIndex": ".craftkit/agents/index.md", diff --git a/README.md b/README.md index eea03ea..07a21d4 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,7 @@ CraftKit 是面向 Codex 的通用插件工具集，覆盖软件开发、文档 | Skill | 用途 | | --- | --- | | `init` | 初始化或更新项目的 `AGENTS.md` 与 `.craftkit/` 项目资料。 | -| `document-output` | 查看、解释或维护项目的过程、共享设计和归档文档配置。 | +| `document-output` | 查看或维护文档配置，登记任务文档，并在完成时预览沉淀、归档与清理。 | | `handoff` | 生成可持续更新的任务交接文档和新任务接续提示词。 | | `distill` | 从任务证据中提炼可复用结论、决策和问题经验。 | | `lessons` | 初始化、维护和审计项目问题经验库。 | diff --git a/plugins/knowledge/.codex-plugin/plugin.json b/plugins/knowledge/.codex-plugin/plugin.json index 5b65979..17aac63 100644 --- a/plugins/knowledge/.codex-plugin/plugin.json +++ b/plugins/knowledge/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "knowledge", - "version": "0.3.2", + "version": "0.4.0", "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/distill/SKILL.md b/plugins/knowledge/skills/distill/SKILL.md index f939650..a7a265e 100644 --- a/plugins/knowledge/skills/distill/SKILL.md +++ b/plugins/knowledge/skills/distill/SKILL.md @@ -25,4 +25,6 @@ description: 从当前任务和项目证据中提炼可复用结论、决策与 - 新证据与既有结论冲突时暂停，交由 `lessons` 的维护规则处理，不能静默覆盖。 - 完成后报告实际写入、未采纳和未写入内容；Git 提交需要独立授权。 +当提炼由任务关闭流程触发时，读取对应 `task.json`，只处理标记为 `distill` 的文件。目标知识写入并校验后，将来源交回关闭流程重新分类；提炼失败或证据不足时改为 `defer`，不得直接把来源标记为删除。 + `distill` 不生成接续提示词、不维护当前任务交接文件；需要继续任务时使用 `handoff`。 diff --git a/plugins/knowledge/skills/document-output/SKILL.md b/plugins/knowledge/skills/document-output/SKILL.md index ce95776..ce053ca 100644 --- a/plugins/knowledge/skills/document-output/SKILL.md +++ b/plugins/knowledge/skills/document-output/SKILL.md @@ -1,11 +1,20 @@ --- name: document-output -description: 查看、解释或维护项目的过程、共享和归档文档落盘配置。适用于初始化文档目录、处理路径冲突或用户明确要求调整落盘规则；普通开发 Skill 已能从 project.json 确定路径时不应触发。 +description: 查看、解释或维护项目文档落盘配置，登记任务文档，并在任务完成时预览和执行文档关闭。适用于调整路径或生命周期规则、确认文档归属、清理过程材料；普通开发 Skill 只需读取 project.json 时不应触发。 --- # 项目文档落盘 -本 Skill 维护 `.craftkit/project.json` 的 `documents` 配置并处理路径冲突，不代替需求、设计或分析 Skill 生成文档内容，也不把对话输出自动转为文件。初次创建配置由 `knowledge:init` 完成；本 Skill 用于后续查询和调整。 +本 Skill 维护 `.craftkit/project.json` 的 `documents` 配置、`workRoot//task.json` 任务记录和关闭门禁，不代替需求、设计或分析 Skill 生成文档内容，也不把对话输出自动转为文件。初次创建配置由 `knowledge:init` 完成。 + +## 选择模式 + +- `view`：解释当前路径、Git 可见性和生命周期策略。 +- `configure`：调整项目级 `documents` 配置。 +- `register`：在业务 Skill 写入任务文档时创建或更新 `task.json`。 +- `close`：任务完成后分类预览、沉淀、归档并清理任务文档。 + +执行 `register` 或 `close` 时读取[文档生命周期](references/lifecycle.md)。普通业务 Skill 可直接读取项目配置并按该引用中的最小字段更新 `task.json`，不需要递归调用本 Skill。 ## 路径选择 @@ -27,6 +36,12 @@ description: 查看、解释或维护项目的过程、共享和归档文档落 - 审批通过不代表共享、归档、提交或移动授权。共享设计不是已验证知识；只有经验证的可复用决策才按知识维护流程进入 `knowledge/decisions/`。 - 交接仍使用交接 Skill 的 `.craftkit/local/handoff/` 或用户指定路径；不把交接、缓存、规范和设计目录混用。 +## 任务关闭 + +`close` 先读取任务记录和实际文件，输出“保留、沉淀、归档、删除、延后”五类清单。完成状态不产生删除授权；只有用户已经明确批准该清单时，才能删除列入“删除”的精确路径。删除后检查任务目录、引用、Git 状态和仍需保留的文件，再把任务状态更新为 `closed`。 + +共享或已跟踪文件必须逐项评审。关闭过程不得删除 `.craftkit/local/config/`、凭据、个人配置、未登记文件或其他任务的文件；不确定归属时标记为“延后”。 + ## 结果 -返回文档用途、项目相对目标路径、选取依据、忽略或共享状态以及冲突。用户要求修改配置时，先展示 `.craftkit/project.json` 的精确差异，确认后保守写入；具体文档仍由获得保存授权的业务 Skill 写入。 +`view`、`configure` 和 `register` 返回用途、目标路径、选取依据、Git 状态及冲突。`close` 返回任务状态、五类清单、已执行动作和剩余文件。用户要求修改配置时，先展示 `.craftkit/project.json` 的精确差异，确认后保守写入；具体文档仍由获得保存授权的业务 Skill 写入。 diff --git a/plugins/knowledge/skills/document-output/references/lifecycle.md b/plugins/knowledge/skills/document-output/references/lifecycle.md new file mode 100644 index 0000000..7dbb710 --- /dev/null +++ b/plugins/knowledge/skills/document-output/references/lifecycle.md @@ -0,0 +1,92 @@ +# 文档生命周期 + +## 分类维度 + +文档同时具有可见性和生命周期，两者独立判断： + +| 可见性 | 位置 | Git 规则 | +| --- | --- | --- | +| 本地 | `workRoot`、`.craftkit/local/handoff/` | 必须被忽略 | +| 共享 | `designRoot`、`.craftkit/knowledge/`、`.craftkit/handoff/` | 可作为普通项目资产评审和提交 | + +| 生命周期 | 典型内容 | 完成时处理 | +| --- | --- | --- | +| 过程 | 调研、计划、草稿、验证记录、临时报告 | 删除、延后或提炼后删除 | +| 长期 | 生效设计、决策、规范、可复用知识 | 保留并维护引用 | +| 归档 | 有审计或历史价值的完成态材料 | 通过 `doc:archive` 复制并验证 | + +共享不等于长期，长期也不等于必须归档。文件按真实用途逐项分类，不能只根据所在目录推断。 + +## 任务记录 + +首次向 `workRoot//` 写入文档时创建 `task.json`；已有记录时保守合并。推荐最小结构： + +```json +{ + "schemaVersion": 1, + "task": "document-lifecycle", + "status": "active", + "createdAt": "2026-09-03", + "updatedAt": "2026-09-03", + "files": [ + { + "path": ".craftkit/local/tasks/document-lifecycle/design.md", + "purpose": "process", + "visibility": "local", + "owner": "document-lifecycle", + "disposition": "review" + } + ] +} +``` + +- `status` 只使用 `active`、`paused`、`ready_to_close`、`closed_pending_cleanup`、`closed`。 +- `purpose` 只使用 `process`、`long-term`、`archive`；`visibility` 只使用 `local`、`shared`。 +- `owner` 使用稳定任务名。一个文件只登记一个主要任务；共同资产使用 `shared`，关闭时不得自动删除。 +- `disposition` 使用 `review`、`keep`、`distill`、`archive`、`delete`、`defer`。 +- 路径使用项目相对正斜杠，必须位于项目根内。`task.json` 本身不加入 `files`。 +- 旧任务没有记录时，可以根据同一任务目录和 Git 状态生成候选清单，但所有归属均标记为待确认。 + +业务 Skill 直接写入过程文档时，只负责创建或更新上述记录，不修改项目级默认策略。共享文档位于 `designRoot` 时也登记在本地任务记录中，使关闭流程能够追踪，但共享文件自身保持正常 Git 可见。 + +## 状态流转 + +```mermaid +stateDiagram-v2 + [*] --> active + active --> paused + paused --> active + active --> ready_to_close + paused --> ready_to_close + ready_to_close --> closed_pending_cleanup + closed_pending_cleanup --> closed + closed_pending_cleanup --> ready_to_close: 清理受阻或范围调整 +``` + +- `ready_to_close` 表示开发和所需验证已经结束，可以生成关闭预览。 +- `closed_pending_cleanup` 表示分类清单已经确认，清理尚未完全验证。 +- `closed` 只表示登记文件已按确认清单处理且剩余引用有效；外部验收未完成时不得借此声称功能已验收。 + +## 关闭流程 + +1. 核对任务完成证据、未完成事项和实际验证，决定是否进入 `ready_to_close`。 +2. 读取 `task.json`、登记文件、任务目录、Git 状态和指向这些文件的项目内引用。 +3. 将每个文件分入“保留、沉淀、归档、删除、延后”，说明依据、目标位置和 Git 影响。 +4. `distill` 只处理经确认且可复用的知识；写入成功并校验后，来源文件才可继续进入删除候选。 +5. `archive` 只处理有历史或审计价值的材料；目标复制与校验成功后，来源文件才可继续进入删除候选。 +6. 更新会因删除失效的索引和链接，检查共享或已跟踪文件的差异。 +7. 展示精确清单。配置为 `preview` 时在此停止；已有明确删除授权时进入 `closed_pending_cleanup` 并处理清单。 +8. 删除仅限已确认的精确文件，不得使用递归通配清理未枚举内容。除 `task.json` 外目录为空且记录无需保留时，才把任务记录作为单独清理项再次确认。 +9. 验证剩余文件、引用、Git 状态、忽略状态和归档目标，再将状态更新为 `closed`；若任务记录也获准删除，先完成状态验证再删除记录和空目录。 + +## 清理保护 + +- `.craftkit/local/config/`、`.craftkit/project.json` 和个人机器配置永久排除在任务清理之外。 +- 未登记文件、归属冲突、未验证知识、归档失败和断链风险一律进入“延后”。 +- `localRetentionDays` 只提示过期候选，不能跳过预览或授权。 +- `trackedFiles` 为 `review-required` 时，删除共享或已跟踪文件必须逐项列出；当前仅支持该值。 +- Git 历史可保留已提交文档的旧版本，但不能代替删除前的当前引用检查。 + +## Worktree 联动 + +移除额外 Worktree 前，除普通 Git 状态外还要检查 `workRoot` 下该任务记录和 ignored 文件。存在 `active`、`paused`、`ready_to_close` 或 `closed_pending_cleanup` 任务，或存在未登记的忽略文件时，Worktree 标记为清理受阻。先执行关闭预览；用户明确选择保留现场时继续保留 Worktree。 diff --git a/plugins/knowledge/skills/handoff/SKILL.md b/plugins/knowledge/skills/handoff/SKILL.md index 19e70fa..712da3c 100644 --- a/plugins/knowledge/skills/handoff/SKILL.md +++ b/plugins/knowledge/skills/handoff/SKILL.md @@ -56,3 +56,5 @@ description: 基于当前任务和项目证据生成可持续更新的本地或 4. 内联最多三条最容易重复踩到的风险；其余内容留在交接文档中。 最后报告写入路径、可见性和主要更新，不执行 `git add`、`git commit` 或 `git push`。共享交接可由用户后续确认提交；本地交接不得交给其他 Git Skill 提交。 + +任务暂停时，若存在 `workRoot//task.json`，将状态更新为 `paused` 并记录交接路径；恢复任务时改回 `active`。任务已经完成且不需要接续时不生成新的交接文档，改用 `knowledge:document-output close` 生成关闭预览。 diff --git a/plugins/knowledge/skills/init/SKILL.md b/plugins/knowledge/skills/init/SKILL.md index ebc8452..c92a443 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 忽略状态；按[文档目录配置](references/project-config.md#文档目录)验证过程、共享设计和归档路径的用途及解析结果，不创建示例文档。 +8. 初始化后验证 JSON、索引链接，以及 `.craftkit/local/`、`.craftkit/cache/` 的 Git 忽略状态；按[文档目录配置](references/project-config.md#文档目录)验证过程、共享设计、归档路径和生命周期策略，不创建示例任务或文档。 9. 使用 `guidance` 对一个真实项目问题执行检索验证；未安装该 Skill 时改用相同的入口顺序手工验证。 框架版本写入 `technology.frameworks`。成熟项目优先从构建清单和锁文件探测；空项目根据用户选择或参考项目建议填写。只有公共 profile 已真实存在且版本范围匹配时才写入 `profile`，否则保留为空并记录待确认事项。 diff --git a/plugins/knowledge/skills/init/assets/project.json b/plugins/knowledge/skills/init/assets/project.json index df76699..1694af2 100644 --- a/plugins/knowledge/skills/init/assets/project.json +++ b/plugins/knowledge/skills/init/assets/project.json @@ -16,7 +16,13 @@ "workRoot": ".craftkit/local/tasks", "designRoot": ".craftkit/designs", "archiveRoot": "docs/archive", - "archiveRules": [] + "archiveRules": [], + "lifecycle": { + "onTaskComplete": "preview", + "localRetentionDays": 7, + "trackedFiles": "review-required", + "personalConfig": "retain" + } }, "guidance": { "agentIndex": ".craftkit/agents/index.md", diff --git a/plugins/knowledge/skills/init/references/project-config.md b/plugins/knowledge/skills/init/references/project-config.md index e5e41d5..47b4dec 100644 --- a/plugins/knowledge/skills/init/references/project-config.md +++ b/plugins/knowledge/skills/init/references/project-config.md @@ -23,12 +23,19 @@ | `designRoot` | `.craftkit/designs` | 用户明确要求共享或正式交付的设计文档 | | `archiveRoot` | `docs/archive` | 用户按归档规则处理的历史或正式归档文档 | | `archiveRules` | `[]` | 归档匹配、目标、转换和校验规则 | +| `lifecycle.onTaskComplete` | `preview` | 任务完成时生成关闭预览，不自动删除文件 | +| `lifecycle.localRetentionDays` | `7` | 本地过程文档建议保留天数，超期仍需进入关闭预览 | +| `lifecycle.trackedFiles` | `review-required` | 已跟踪文档必须逐项评审后才能删除 | +| `lifecycle.personalConfig` | `retain` | 本地个人配置不属于任务清理范围 | - 路径使用项目相对路径和正斜杠，不能包含 `..`、用户目录或其他个人机器绝对路径。 - 初始化只写入配置，不预建空任务目录、设计目录或归档目录。 - 成熟项目已有明确的过程文档或正式设计目录时优先延续，并展示证据；根目录中的 README、CHANGELOG 或总体工作流不能单独证明根目录是任务文档目录。 - 用户未指定共享用途时，Skill 生成的过程文档使用 `workRoot`；用户明确要求共享或正式交付时使用 `designRoot`。 - `archiveRoot` 不作为开发中内容的默认写入位置，归档必须按归档 Skill 的规则另行执行。 +- `workRoot//task.json` 记录任务状态、可见性和文件归属；字段结构及关闭规则由 `knowledge:document-output` 维护。 +- 生命周期配置缺失时按表中默认值解释，不为读取兼容性强制改写旧项目配置。 +- `localRetentionDays` 只用于提示，不构成删除授权；`personalConfig` 当前仅允许 `retain`。 - 旧配置只有 `archiveRoot` 时继续兼容读取；初始化更新时展示新增字段及用途，确认后保守合并。 ## 前端组件信息