feat(knowledge): 接入文档持续维护约定

2026-09-03 15:54:12 +08:00
parent 0eaccca7cf
commit 9060fe5222
18 changed files with 61 additions and 19 deletions
@@ -1,6 +1,6 @@
 {
  "name": "doc",
-  "version": "0.3.3",
+  "version": "0.4.0",
  "description": "通用文档转换、表格提取、规则化归档与写作工具。",
  "author": {
    "name": "CraftKit"
@@ -27,6 +27,7 @@ python scripts/archive.py --root <project> --config <rules.json> --apply [--repo
 - 专有文档拆分逻辑改为通用 Markdown 标题章节抽取。
 - 内部数据库或服务校验改为显式 `requiredText` 内容校验；需要外部事实时由用户先提供结果，不隐式连接系统。
 - 来源专属元数据清理改为可选 `stripFrontmatter`，不会默认删除内容。
+- 历史归档保留当时快照并标明归档用途；它不作为当前有效依据。发现错误时增加勘误或当前版本链接，不静默改写历史内容。

 ## 安全边界

@@ -1,4 +1,4 @@
 interface:
  display_name: "Archive Documents（doc:archive）"
-  short_description: "按项目规则安全预演并归档文档"
+  short_description: "归档历史快照并关联当前有效版本"
  default_prompt: "使用 $archive 根据项目规则预演文档归档，确认后再执行写入。"
@@ -9,4 +9,4 @@ description: 将技术说明、问题描述、会议材料或现有实现整理

 技术实现细节只有在构成真实约束时才保留；不能从代码结构反推业务意图。冲突、模糊词、缺失规则和不可测试表述进入疑问清单。默认在对话中展示；用户要求保存时先展示待确认内容，再读取 `.craftkit/project.json` 的 `documents` 配置，过程需求使用 `workRoot`，共享需求使用 `designRoot`。

-写入后在 `workRoot/<task>/task.json` 登记本次过程或共享文档；已有记录时保守合并，只更新本任务拥有的文件。登记结构遵循 `knowledge:document-output` 的生命周期规则，不修改项目级默认配置。
+落盘前检索同主题的需求、设计、规范或知识，优先更新已有权威文档。共享长期文档新建或实质修改后按 `.craftkit/standards/document-maintenance.md` 更新审核状态；排版和错字修正不改变状态。`r`n`r`n写入后在 `workRoot/<task>/task.json` 登记本次创建、更新或引用的文档及 `relationship`；已有记录时保守合并。关联旧文档不转移所有权，也不产生删除权限；不修改项目级默认配置。
@@ -1,4 +1,4 @@
 interface:
  display_name: "需求整理（doc:requirements）"
-  short_description: "将技术输入整理为可确认的需求说明"
-  default_prompt: "使用 $requirements 将这些材料整理成需求和疑问清单。"
+  short_description: "创建或更新可审核的需求说明"
+  default_prompt: "使用 $requirements 查找并更新已有需求，或将这些材料整理成新的需求和疑问清单。"
@@ -1,6 +1,6 @@
 {
  "name": "knowledge",
-  "version": "0.4.0",
+  "version": "0.5.0",
  "description": "项目初始化、任务交接、复盘与知识沉淀工作流。",
  "author": {
    "name": "CraftKit"
@@ -8,8 +8,8 @@
  "skills": "./skills/",
  "interface": {
    "displayName": "Knowledge",
-    "shortDescription": "项目初始化与知识沉淀工具",
-    "longDescription": "提供项目初始化、文档落盘与生命周期管理、任务交接、Agent 复盘、知识提炼、问题经验维护和 Git 工作日志。",
+    "shortDescription": "项目初始化与文档知识生命周期工具",
+    "longDescription": "提供项目初始化、文档落盘、审核与持续维护、任务交接、Agent 复盘、知识提炼、问题经验维护和 Git 工作日志。",
    "developerName": "CraftKit",
    "category": "Productivity",
    "capabilities": ["Read", "Write"],
@@ -23,6 +23,7 @@ description: 从当前任务和项目证据中提炼可复用结论、决策与
 - 使用项目相对路径，不记录凭据、个人信息和无必要的内部地址。
 - 指向源码或文档位置，不复制大段源码、日志或对话。
 - 新证据与既有结论冲突时暂停，交由 `lessons` 的维护规则处理，不能静默覆盖。
+- 写入前检索已有权威知识，优先修订原文。实质修改后按项目文档维护规范更新审核状态；替代旧内容时同步索引和 `replacedBy`。
 - 完成后报告实际写入、未采纳和未写入内容；Git 提交需要独立授权。

 当提炼由任务关闭流程触发时，读取对应 `task.json`，只处理标记为 `distill` 的文件。目标知识写入并校验后，将来源交回关闭流程重新分类；提炼失败或证据不足时改为 `defer`，不得直接把来源标记为删除。
@@ -24,9 +24,9 @@ description: 初始化或更新项目的 AGENTS.md 与 .craftkit 项目资料；
 3. 展示自动识别的信息、证据、冲突和待确认项。
 4. 通过简短提问补齐无法可靠推断的项目用途、包名、框架、精确版本、公共 profile、内部依赖和约束；前端项目还需确认组件库、组件根、文档入口及参考项目范围。禁止默认最新版本。
 5. 展示拟创建或修改的文件及关键内容，取得确认后再写入。
-6. 从 [assets](assets/project.json) 中选择模板，生成或合并 `AGENTS.md`、`.craftkit/project.json`、目录说明、嵌套忽略规则和必要索引；存在前端能力时同时准备 `.craftkit/standards/frontend/components.md` 的最小索引。
+6. 从 [assets](assets/project.json) 中选择模板，生成或合并 `AGENTS.md`、`.craftkit/project.json`、目录说明、嵌套忽略规则、必要索引和 `.craftkit/standards/document-maintenance.md`；存在前端能力时同时准备 `.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`，否则保留为空并记录待确认事项。
@@ -1,4 +1,4 @@
 interface:
  display_name: "Project Init（knowledge:init）"
-  short_description: "按成熟或空项目模式初始化 Agent 上下文与项目资料"
+  short_description: "初始化 Agent 上下文、项目资料和文档维护约定"
  default_prompt: "使用 $init 初始化当前项目，先判断成熟项目或空项目，并询问我是否有参考项目。"
@@ -17,6 +17,7 @@
 - 项目规范：`.craftkit/standards/index.md`
 - 可复用知识：`.craftkit/knowledge/index.md`
 - 共享设计文档：`.craftkit/designs/`；开发中过程文档使用 `.craftkit/project.json` 配置的 `documents.workRoot`。
+- 文档维护规则：`.craftkit/standards/document-maintenance.md`；修改实现时检查并同步受影响的长期文档。

 ## 工作约束

@@ -2,14 +2,15 @@

 本目录保存当前项目可供 Agent 使用的配置、规范、知识和交接内容。

- `project.json`：项目类型、技术栈、代码边界、依赖标识和命令。
+- `project.json`：项目类型、技术栈、代码边界、依赖标识、命令和文档生命周期默认策略。
 - `agents/`：项目对 Agent 的补充指令。
 - `standards/`：项目自身的开发、测试、文档与 Git 规范。
+- `standards/document-maintenance.md`：长期文档的审核、持续更新、替代和关闭约定。
 - `standards/frontend/components.md`：经确认的前端组件来源、版本和契约证据索引。
 - `knowledge/`：经过验证的技术决策和可复用经验。
 - `designs/`：用户明确要求共享或正式交付的设计文档。
 - `handoff/`：用户明确选择共享的任务交接。
- `local/`：当前工作副本的过程文档和本地上下文，不进入 Git。
+- `local/`：当前工作副本的过程文档、任务记录和本地上下文，不进入 Git。
 - `cache/`：可重新生成的缓存，不进入 Git。

 共享资料不得包含凭据、个人机器绝对路径或无必要的业务数据。
@@ -0,0 +1,31 @@
+---
+reviewStatus: pending
+reviewedAt: null
+replacedBy: null
+---
+
+# 文档维护规范
+
+## 适用范围
+
+本规范适用于项目正式需求、生效设计、项目规范和长期知识。过程草稿按任务需要维护，不强制逐份审核；历史归档保留当时快照，不作为当前依据。
+
+## 创建与更新
+
+- 任务开始时查找相关已有文档，优先更新现有权威内容，不创建同义平行版本。
+- 新建或实质修改长期文档后，将文档自身的 `reviewStatus` 标为 `pending`。
+- 项目已有审批结果可以直接作为审核依据；通过后标为 `approved`。
+- 已知文档与需求、实现或新证据不一致时标为 `outdated`；更新后回到 `pending` 并重新审核。
+- 排版、错字、链接修复和不改变含义的调整不改变审核状态。
+
+## 状态与替代
+
+项目没有既有元数据格式时，在文档 Frontmatter 使用 `reviewStatus`、`reviewedAt` 和 `replacedBy`。旧文档缺少状态时视为尚未确认，只在实际使用或修改时补齐。
+
+新版替代旧版时更新索引和引用，并通过 `replacedBy` 指向当前版本。旧版根据历史价值归档或删除；归档发现错误时补充勘误和新版链接，不改写历史事实。
+
+## 任务关联与关闭
+
+本地 `task.json` 记录本次创建、更新或引用的文档。关联旧文档不转移所有权，也不产生删除权限。
+
+任务关闭前检查本次实现影响的长期文档已经同步。需要作为当前依据的文档必须为 `approved`；`pending` 或 `outdated` 文档应完成处理，无法处理时列入延后清单并说明影响。
@@ -2,6 +2,8 @@

 当前没有已验证的项目知识。只收录有证据、适用范围明确且能够复用的技术决策与经验。

+长期知识按 `.craftkit/standards/document-maintenance.md` 保存审核状态并持续更新；过时或历史材料不得作为当前有效依据。
+
 - 问题经验按需建立在 `pitfalls/`，不预建空分类。
 - 重要技术决策按需建立在 `decisions/`。
 - 其他长期知识应优先并入已有主题，避免同义平行文档。
@@ -1,3 +1,5 @@
 # 项目规范索引

-当前没有项目专属规范。新增规范时记录主题、适用范围、规则文件和优先级；未覆盖主题可由 `guidance` 查询中性公共基线。
+- [文档维护规范](document-maintenance.md)：正式需求、设计、规范和长期知识的创建、审核、更新、替代及任务关闭规则。
+
+新增规范时记录主题、适用范围、规则文件和优先级；未覆盖主题可由 `guidance` 查询中性公共基线。
@@ -21,6 +21,8 @@ description: 初始化和维护 .craftkit 问题经验库，并按已确认的
 - 先读取适用的 `AGENTS.md`、`.craftkit/README.md`、知识索引和已有经验，不建立第二套经验目录。
 - 不预建空分类；条目较少时保持扁平，只有检索确有困难时才提议分类。
 - 已有条目、索引和用户章节保守合并，不整文件覆盖。
+- 新证据影响已有经验时更新原条目：未完成核实时标为 `outdated`，完成修订后按项目文档维护规范重新审核；不要另建冲突条目。
+- 条目被替代时更新知识索引和 `replacedBy`；历史价值需要保留时归档并指向当前条目。
 - 重命名、合并、删除、纠正和移动条目前展示影响并取得确认。
 - 不记录凭据、个人信息、机器绝对路径或大段源码与日志。
 - 写入完成后报告实际文件和未采纳建议；不自动暂存、提交或推送。
@@ -1,6 +1,6 @@
 {
  "name": "skill",
-  "version": "0.2.1",
+  "version": "0.2.2",
  "description": "项目规范检索与维护工具。",
  "author": {
    "name": "CraftKit"
@@ -9,7 +9,7 @@
  "interface": {
    "displayName": "Skill",
    "shortDescription": "项目规范与 Skill 维护工具",
-    "longDescription": "提供项目规范的渐进检索、冲突识别、缺口分析与索引维护工作流。",
+    "longDescription": "提供当前有效项目规范与知识的渐进检索、状态识别、冲突分析和索引维护工作流。",
    "developerName": "CraftKit",
    "category": "Productivity",
    "capabilities": ["Read", "Write"],
@@ -13,7 +13,7 @@ description: 检索当前项目的 AGENTS.md、.craftkit 项目资料和 CraftKi
 2. 读取从项目根到目标目录沿途适用的 `AGENTS.md`，距离目标更近的文件约束更具体。
 3. 若存在 `.craftkit/project.json`，读取其中的项目类型、技术栈、代码边界和规范入口。
 4. 涉及框架时按[版本 Profile 路由](references/profile-routing.md)确定当前项目版本；普通开发只加载当前 profile，升级或版本比较才加载源、目标两个 profile。
-5. 按需读取 `.craftkit/agents/index.md`、`.craftkit/standards/index.md`、`.craftkit/knowledge/index.md`；只继续读取索引命中的域、路由和正文。
+5. 按需读取 `.craftkit/agents/index.md`、`.craftkit/standards/index.md`、`.craftkit/knowledge/index.md`；涉及需求、设计、规范或知识时同时读取命中的文档维护规则，只继续读取索引命中的域、路由和正文。
 6. 项目资料未覆盖主题时，读取[公共基线索引](references/guidance/index.md)，只加载当前任务需要的规则。
 7. 索引缺失或没有命中时，才在相应目录做受控关键词搜索；不得先递归加载整个知识库。

@@ -36,5 +36,6 @@ description: 检索当前项目的 AGENTS.md、.craftkit 项目资料和 CraftKi
 - `.craftkit/local/` 与 `.craftkit/cache/` 默认不是共享规范来源，除非用户明确要求读取其中的本地上下文。
 - 不读取凭据、环境密钥、数据库连接信息或与问题无关的业务数据。
 - 项目尚未初始化或关键索引缺失时，说明缺口并建议使用 `knowledge` 插件的 `init`；不得在检索过程中隐式初始化。
+- 长期文档缺少审核状态时报告为“尚未确认”；`outdated` 和历史归档只能作为背景，不得作为当前有效规则返回。
 - 项目未声明且无法从构建清单确定框架版本时，必须询问用户；禁止默认最新版本或跨版本混用推荐写法。
 - 用户要求新增、整理或修复规范索引时，应交由后续的规范维护 Skill，不在本 Skill 中写文件。
@@ -1,4 +1,4 @@
 interface:
  display_name: "Project Guidance（skill:guidance）"
-  short_description: "按索引渐进检索项目规范、中性公共基线及冲突依据"
-  default_prompt: "使用 $guidance 查找当前任务适用的项目规范，并给出可追溯依据。"
+  short_description: "检索当前有效规则并识别过时与历史材料"
+  default_prompt: "使用 $guidance 查找当前任务适用且有效的项目规范与知识，并给出可追溯依据。"