From 0eaccca7cf59e7c977724403e77d29659bab109d Mon Sep 17 00:00:00 2001 From: "zhiye.sun" Date: Thu, 3 Sep 2026 15:53:52 +0800 Subject: [PATCH] =?UTF-8?q?feat(knowledge):=20=E5=A2=9E=E5=8A=A0=E9=95=BF?= =?UTF-8?q?=E6=9C=9F=E6=96=87=E6=A1=A3=E5=AE=A1=E6=A0=B8=E4=B8=8E=E6=9B=B4?= =?UTF-8?q?=E6=96=B0=E8=A7=84=E5=88=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .craftkit/README.md | 1 + .craftkit/knowledge/index.md | 2 + .craftkit/standards/document-maintenance.md | 31 +++++++++++++ .craftkit/standards/index.md | 4 +- .../knowledge/skills/document-output/SKILL.md | 6 ++- .../skills/document-output/agents/openai.yaml | 4 +- .../document-output/references/lifecycle.md | 43 ++++++++++++++++++- 7 files changed, 84 insertions(+), 7 deletions(-) create mode 100644 .craftkit/standards/document-maintenance.md diff --git a/.craftkit/README.md b/.craftkit/README.md index 31b51b3..c28beca 100644 --- a/.craftkit/README.md +++ b/.craftkit/README.md @@ -5,6 +5,7 @@ - `project.json`：项目类型、技术栈、代码边界、依赖标识、命令和文档生命周期默认策略。 - `agents/`：项目对 Agent 的补充指令。 - `standards/`：项目自身的开发、测试、文档与 Git 规范。 +- `standards/document-maintenance.md`：长期文档的审核、持续更新、替代和关闭约定。 - `knowledge/`：经过验证的技术决策和可复用经验。 - `designs/`：用户明确要求共享或正式交付的设计文档。 - `handoff/`：用户明确选择共享的任务交接。 diff --git a/.craftkit/knowledge/index.md b/.craftkit/knowledge/index.md index 73e76f7..d30ce3e 100644 --- a/.craftkit/knowledge/index.md +++ b/.craftkit/knowledge/index.md @@ -2,6 +2,8 @@ 当前没有已验证的项目知识。只收录有证据、适用范围明确且能够复用的技术决策与经验。 +长期知识按 `.craftkit/standards/document-maintenance.md` 保存审核状态并持续更新；过时或历史材料不得作为当前有效依据。 + - 问题经验按需建立在 `pitfalls/`，不预建空分类。 - 重要技术决策按需建立在 `decisions/`。 - 其他长期知识应优先并入已有主题，避免同义平行文档。 diff --git a/.craftkit/standards/document-maintenance.md b/.craftkit/standards/document-maintenance.md new file mode 100644 index 0000000..1dbb7ce --- /dev/null +++ b/.craftkit/standards/document-maintenance.md @@ -0,0 +1,31 @@ +--- +reviewStatus: approved +reviewedAt: 2026-09-03 +replacedBy: null +--- + +# 文档维护规范 + +## 适用范围 + +本规范适用于项目正式需求、生效设计、项目规范和长期知识。过程草稿按任务需要维护，不强制逐份审核；历史归档保留当时快照，不作为当前依据。 + +## 创建与更新 + +- 任务开始时查找相关已有文档，优先更新现有权威内容，不创建同义平行版本。 +- 新建或实质修改长期文档后，将文档自身的 `reviewStatus` 标为 `pending`。 +- 项目已有审批结果可以直接作为审核依据；通过后标为 `approved`。 +- 已知文档与需求、实现或新证据不一致时标为 `outdated`；更新后回到 `pending` 并重新审核。 +- 排版、错字、链接修复和不改变含义的调整不改变审核状态。 + +## 状态与替代 + +项目没有既有元数据格式时，在文档 Frontmatter 使用 `reviewStatus`、`reviewedAt` 和 `replacedBy`。旧文档缺少状态时视为尚未确认，只在实际使用或修改时补齐。 + +新版替代旧版时更新索引和引用，并通过 `replacedBy` 指向当前版本。旧版根据历史价值归档或删除；归档发现错误时补充勘误和新版链接，不改写历史事实。 + +## 任务关联与关闭 + +本地 `task.json` 记录本次创建、更新或引用的文档。关联旧文档不转移所有权，也不产生删除权限。 + +任务关闭前检查本次实现影响的长期文档已经同步。需要作为当前依据的文档必须为 `approved`；`pending` 或 `outdated` 文档应完成处理，无法处理时列入延后清单并说明影响。 diff --git a/.craftkit/standards/index.md b/.craftkit/standards/index.md index d5a981c..8f4e84b 100644 --- a/.craftkit/standards/index.md +++ b/.craftkit/standards/index.md @@ -1,3 +1,5 @@ # 项目规范索引 -当前没有项目专属规范。新增规范时记录主题、适用范围、规则文件和优先级；未覆盖主题可由 `guidance` 查询中性公共基线。 +- [文档维护规范](document-maintenance.md)：正式需求、设计、规范和长期知识的创建、审核、更新、替代及任务关闭规则。 + +新增规范时记录主题、适用范围、规则文件和优先级；未覆盖主题可由 `guidance` 查询中性公共基线。 diff --git a/plugins/knowledge/skills/document-output/SKILL.md b/plugins/knowledge/skills/document-output/SKILL.md index ce053ca..14d8f4e 100644 --- a/plugins/knowledge/skills/document-output/SKILL.md +++ b/plugins/knowledge/skills/document-output/SKILL.md @@ -11,11 +11,13 @@ description: 查看、解释或维护项目文档落盘配置，登记任务文 - `view`：解释当前路径、Git 可见性和生命周期策略。 - `configure`：调整项目级 `documents` 配置。 -- `register`：在业务 Skill 写入任务文档时创建或更新 `task.json`。 +- `register`：创建或更新 `task.json`，登记本次新建、更新或引用的文档。 - `close`：任务完成后分类预览、沉淀、归档并清理任务文档。 执行 `register` 或 `close` 时读取[文档生命周期](references/lifecycle.md)。普通业务 Skill 可直接读取项目配置并按该引用中的最小字段更新 `task.json`，不需要递归调用本 Skill。 +长期文档的审核状态保存在文档自身；`task.json` 只记录当前任务关系。修改文档前先读取 `.craftkit/standards/document-maintenance.md`；项目尚未初始化时使用生命周期引用中的默认规则。 + ## 路径选择 1. 优先使用用户明确指定的路径；更新已有文档时延续其位置，不因新增默认值移动文件。 @@ -38,7 +40,7 @@ description: 查看、解释或维护项目文档落盘配置，登记任务文 ## 任务关闭 -`close` 先读取任务记录和实际文件，输出“保留、沉淀、归档、删除、延后”五类清单。完成状态不产生删除授权；只有用户已经明确批准该清单时，才能删除列入“删除”的精确路径。删除后检查任务目录、引用、Git 状态和仍需保留的文件，再把任务状态更新为 `closed`。 +`close` 先读取任务记录和实际文件，核对受影响长期文档的更新与审核状态，再输出“保留、沉淀、归档、删除、延后”五类清单。完成状态不产生删除授权；只有用户已经明确批准该清单时，才能删除列入“删除”的精确路径。删除后检查任务目录、引用、Git 状态和仍需保留的文件，再把任务状态更新为 `closed`。 共享或已跟踪文件必须逐项评审。关闭过程不得删除 `.craftkit/local/config/`、凭据、个人配置、未登记文件或其他任务的文件；不确定归属时标记为“延后”。 diff --git a/plugins/knowledge/skills/document-output/agents/openai.yaml b/plugins/knowledge/skills/document-output/agents/openai.yaml index 9841454..c7be81f 100644 --- a/plugins/knowledge/skills/document-output/agents/openai.yaml +++ b/plugins/knowledge/skills/document-output/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "项目文档落盘（knowledge:document-output）" - short_description: "按项目配置选择过程、共享和归档文档目录" - default_prompt: "使用 $document-output 查看或调整当前项目的文档落盘配置。" + short_description: "管理文档落盘、审核状态、持续更新和任务关闭" + default_prompt: "使用 $document-output 查看或调整文档配置，登记任务文档，或检查更新与关闭状态。" diff --git a/plugins/knowledge/skills/document-output/references/lifecycle.md b/plugins/knowledge/skills/document-output/references/lifecycle.md index 7dbb710..4384fc4 100644 --- a/plugins/knowledge/skills/document-output/references/lifecycle.md +++ b/plugins/knowledge/skills/document-output/references/lifecycle.md @@ -17,6 +17,42 @@ 共享不等于长期，长期也不等于必须归档。文件按真实用途逐项分类，不能只根据所在目录推断。 +## 长期文档状态 + +正式需求、生效设计、项目规范和长期知识在文档自身保存 `reviewStatus`，使本地任务记录删除后仍能判断有效性： + +| 状态 | 含义 | 后续动作 | +| --- | --- | --- | +| `pending` | 新建或实质修改后尚未审核 | 继续修改或按项目规则审核 | +| `approved` | 内容已经确认，可作为当前依据 | 持续使用并在变更时复核 | +| `outdated` | 已确认与需求、实现或新证据不一致 | 更新后回到 `pending` | + +项目已有 Frontmatter 或元数据格式时沿用；没有约定时使用最小 Frontmatter： + +```yaml +--- +reviewStatus: pending +reviewedAt: null +replacedBy: null +--- +``` + +- 新建或改变业务含义、外部契约、数据模型、关键流程及结论时设为 `pending`。 +- 已有需求或设计审批可作为审核依据；通过后设为 `approved` 并记录日期，不重复建立审批流程。 +- 排版、错字、链接修复和不改变含义的修订不改变审核状态。 +- 已知内容不再符合事实时设为 `outdated`；更新完成后设为 `pending`，复审通过后恢复 `approved`。 +- 旧文档没有状态时视为“尚未确认”。只在任务实际使用或修改时补齐，不能批量推断为 `approved`。 +- 历史归档不使用 `approved` 冒充当前依据；发现错误时增加勘误或新版链接，保留当时快照。 + +## 持续维护 + +留存不是生命周期终点。每次任务开始时检索相关需求、设计、规范和知识；优先更新已有权威文档，避免创建同义平行版本。实现、接口、数据模型、业务行为或验证结论变化后，检查已关联及检索命中的长期文档： + +- 受到影响的文档纳入当前任务并完成更新，实质修改后重新审核。 +- 暂时无法更新时标为 `outdated`，在任务关闭清单中列为“延后”，说明影响和后续责任。 +- 新版替代旧版时更新索引和引用；旧版按真实价值删除或归档，并使用 `replacedBy` 指向当前版本。 +- 当前任务关联旧文档只表示本次负责检查或更新，不转移文档所有权，也不产生删除权限。 + ## 任务记录 首次向 `workRoot//` 写入文档时创建 `task.json`；已有记录时保守合并。推荐最小结构： @@ -34,6 +70,7 @@ "purpose": "process", "visibility": "local", "owner": "document-lifecycle", + "relationship": "created", "disposition": "review" } ] @@ -43,11 +80,12 @@ - `status` 只使用 `active`、`paused`、`ready_to_close`、`closed_pending_cleanup`、`closed`。 - `purpose` 只使用 `process`、`long-term`、`archive`；`visibility` 只使用 `local`、`shared`。 - `owner` 使用稳定任务名。一个文件只登记一个主要任务；共同资产使用 `shared`，关闭时不得自动删除。 +- `relationship` 使用 `created`、`updated`、`referenced`；关联旧文档通常使用 `updated` 或 `referenced`，不能据此取得删除权限。 - `disposition` 使用 `review`、`keep`、`distill`、`archive`、`delete`、`defer`。 - 路径使用项目相对正斜杠，必须位于项目根内。`task.json` 本身不加入 `files`。 - 旧任务没有记录时，可以根据同一任务目录和 Git 状态生成候选清单，但所有归属均标记为待确认。 -业务 Skill 直接写入过程文档时，只负责创建或更新上述记录，不修改项目级默认策略。共享文档位于 `designRoot` 时也登记在本地任务记录中，使关闭流程能够追踪，但共享文件自身保持正常 Git 可见。 +业务 Skill 直接写入过程文档时，只负责创建或更新上述记录，不修改项目级默认策略。共享文档位于 `designRoot` 时也登记在本地任务记录中，使关闭流程能够追踪，但审核状态保存在共享文档自身，文档保持正常 Git 可见。 ## 状态流转 @@ -69,7 +107,7 @@ stateDiagram-v2 ## 关闭流程 -1. 核对任务完成证据、未完成事项和实际验证，决定是否进入 `ready_to_close`。 +1. 核对任务完成证据、未完成事项和实际验证，并检查本次影响的长期文档已同步；需要作为当前依据的文档必须为 `approved`，决定是否进入 `ready_to_close`。 2. 读取 `task.json`、登记文件、任务目录、Git 状态和指向这些文件的项目内引用。 3. 将每个文件分入“保留、沉淀、归档、删除、延后”，说明依据、目标位置和 Git 影响。 4. `distill` 只处理经确认且可复用的知识；写入成功并校验后，来源文件才可继续进入删除候选。 @@ -86,6 +124,7 @@ stateDiagram-v2 - `localRetentionDays` 只提示过期候选，不能跳过预览或授权。 - `trackedFiles` 为 `review-required` 时，删除共享或已跟踪文件必须逐项列出；当前仅支持该值。 - Git 历史可保留已提交文档的旧版本，但不能代替删除前的当前引用检查。 +- `pending` 或 `outdated` 的长期文档不能作为有效基线直接保留；不能及时处理时进入“延后”。 ## Worktree 联动