feat(knowledge): 增加任务文档生命周期

.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。
 
 共享资料不得包含凭据、个人机器绝对路径或无必要的业务数据。

.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",

README.md

@@ -89,7 +89,7 @@ CraftKit 是面向 Codex 的通用插件工具集，覆盖软件开发、文档
 | Skill | 用途 |
 | --- | --- |
 | `init` | 初始化或更新项目的 `AGENTS.md` 与 `.craftkit/` 项目资料。 |
-| `document-output` | 查看、解释或维护项目的过程、共享设计和归档文档配置。 |
+| `document-output` | 查看或维护文档配置，登记任务文档，并在完成时预览沉淀、归档与清理。 |
 | `handoff` | 生成可持续更新的任务交接文档和新任务接续提示词。 |
 | `distill` | 从任务证据中提炼可复用结论、决策和问题经验。 |
 | `lessons` | 初始化、维护和审计项目问题经验库。 |

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"],

plugins/knowledge/skills/distill/SKILL.md

@@ -25,4 +25,6 @@ description: 从当前任务和项目证据中提炼可复用结论、决策与
 - 新证据与既有结论冲突时暂停，交由 `lessons` 的维护规则处理，不能静默覆盖。
 - 完成后报告实际写入、未采纳和未写入内容；Git 提交需要独立授权。
 
+当提炼由任务关闭流程触发时，读取对应 `task.json`，只处理标记为 `distill` 的文件。目标知识写入并校验后，将来源交回关闭流程重新分类；提炼失败或证据不足时改为 `defer`，不得直接把来源标记为删除。
+
 `distill` 不生成接续提示词、不维护当前任务交接文件；需要继续任务时使用 `handoff`。

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>/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 写入。

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>/` 写入文档时创建 `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。

plugins/knowledge/skills/handoff/SKILL.md

@@ -56,3 +56,5 @@ description: 基于当前任务和项目证据生成可持续更新的本地或
 4. 内联最多三条最容易重复踩到的风险；其余内容留在交接文档中。
 
 最后报告写入路径、可见性和主要更新，不执行 `git add`、`git commit` 或 `git push`。共享交接可由用户后续确认提交；本地交接不得交给其他 Git Skill 提交。
+
+任务暂停时，若存在 `workRoot/<task>/task.json`，将状态更新为 `paused` 并记录交接路径；恢复任务时改回 `active`。任务已经完成且不需要接续时不生成新的交接文档，改用 `knowledge:document-output close` 生成关闭预览。

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`，否则保留为空并记录待确认事项。

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",

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>/task.json` 记录任务状态、可见性和文件归属；字段结构及关闭规则由 `knowledge:document-output` 维护。
+- 生命周期配置缺失时按表中默认值解释，不为读取兼容性强制改写旧项目配置。
+- `localRetentionDays` 只用于提示，不构成删除授权；`personalConfig` 当前仅允许 `retain`。
 - 旧配置只有 `archiveRoot` 时继续兼容读取；初始化更新时展示新增字段及用途，确认后保守合并。
 
 ## 前端组件信息