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

.craftkit/README.md

@@ -2,12 +2,14 @@
 
 本目录保存当前项目可供 Agent 使用的配置、规范、知识和交接内容。
 
-- `project.json`：项目类型、技术栈、代码边界、依赖标识和命令。
+- `project.json`：项目类型、技术栈、代码边界、依赖标识、命令和文档生命周期默认策略。
 - `agents/`：项目对 Agent 的补充指令。
 - `standards/`：项目自身的开发、测试、文档与 Git 规范。
+- `standards/document-maintenance.md`：长期文档的审核、持续更新、替代和关闭约定。
 - `knowledge/`：经过验证的技术决策和可复用经验。
+- `designs/`：用户明确要求共享或正式交付的设计文档。
 - `handoff/`：用户明确选择共享的任务交接。
-- `local/`：当前工作副本的本地上下文，不进入 Git。
+- `local/`：当前工作副本的过程文档、任务记录和本地上下文，不进入 Git；其中个人配置不属于任务清理范围。
 - `cache/`：可重新生成的缓存，不进入 Git。
 
 共享资料不得包含凭据、个人机器绝对路径或无必要的业务数据。

.craftkit/designs/multi-language-plugin/MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-DESIGN.md

@@ -0,0 +1,849 @@
+# 多语言插件架构设计与实施方案
+
+## 1. 设计目标
+
+本设计将 CraftKit 建设为可扩展的多语言插件体系。现有 `dev`、`knowledge` 和 `skill` 插件继续提供通用工作流，新增 Profile 工厂和技术能力插件，使初始化、规范检索、后端设计、实现、测试和审查能够按项目真实技术栈加载 Java、Python 或前端专项知识。
+
+本设计细化[《多语言插件架构改造计划》](MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-PLAN.md)，作为后续编码、迁移、测试和发布的实施依据。原计划将物理拆分放在契约验证之后；本设计根据用户确认的工厂化方向，改为首期建立独立插件骨架、保留旧 Skill 入口兼容，实施边界以本文为准。
+
+首期交付范围：
+
+- 建立统一的 Profile 能力契约。
+- 新增 Profile 工厂插件。
+- 新增 Java 和 Python 技术能力插件。
+- 改造项目初始化和规范检索入口。
+- 让 `design-backend`、`implement-backend`、`test-backend` 和专项审查接入 Profile。
+- 使用 Spring Boot 与 FastAPI 项目验证完整路由。
+
+首期不包含：
+
+- 自动安装 JDK、Python、Maven、uv 或项目依赖。
+- 自动修改业务项目的依赖版本。
+- 数据库、HTTP 和前端详细设计规则的全面重写。
+- Go、Rust、C# 等后续语言能力包。
+- 运行时插件下载、动态代码加载或远程配置中心。
+
+## 2. 现状与约束
+
+### 2.1 已有能力
+
+| 能力 | 当前入口 | 可复用内容 |
+| --- | --- | --- |
+| 项目初始化 | `knowledge:init` | 构建文件探测、项目画像、保守合并和安全边界 |
+| 项目画像 | `.craftkit/project.json` | 技术栈、代码边界、命令和知识入口 |
+| 规范检索 | `skill:guidance` | 来源优先级、渐进加载和版本 Profile 路由 |
+| 后端设计 | `dev:design-backend` | 中性设计流程和统一设计输出 |
+| 后端实现 | `dev:implement-backend` | 基于项目证据实施和验证 |
+| 后端测试 | `dev:test-backend` | 按项目测试框架选择测试层级 |
+| Java 审查 | `dev:review-java` | Java 语言专项审查基线 |
+| 插件市场 | `.agents/plugins/marketplace.json` | 独立插件注册和安装入口 |
+
+### 2.2 主要缺口
+
+- `profile` 只有概念和路由原则，没有机器可检查的统一契约。
+- 公共语言知识缺少独立插件边界，难以单独安装、发布和维护。
+- 初始化 Skill 同时承担通用扫描和技术识别，继续扩展会形成语言条件分支集合。
+- 核心 Skill 只能手工寻找资料，无法稳定判断能力是否安装、版本是否匹配。
+- `.craftkit/project.json` 只能给框架记录单个 `profile` 字符串，不能表达模块级语言和多个能力提供方。
+- 跨插件相对路径会受到安装位置和插件版本目录影响，不能作为稳定依赖接口。
+
+### 2.3 平台约束
+
+- Skill 是由 Agent 按描述和指令选择的能力，不假设存在传统依赖注入容器。
+- 插件可以独立安装，核心工作流必须在语言插件缺失时继续执行通用部分。
+- 不依赖用户目录中的固定插件缓存路径。
+- 公共插件不能直接写入业务项目；项目文件统一由当前获得授权的核心 Skill 修改。
+- 未确认精确版本时不能默认最新版本，也不能跨主版本混用规则。
+
+## 3. 总体设计
+
+Profile 工厂负责“识别需求并选择能力”，技术插件负责“提供能力”，核心 Skill 负责“执行业务工作流”。项目知识库提供当前项目的覆盖规则。
+
+```mermaid
+flowchart TB
+    U[用户任务] --> C[核心 Skill]
+    C --> PJ[读取 project.json]
+    PJ --> R[profile:resolve]
+    R --> M{目标模块技术栈}
+    M -->|Java| J[java:profile]
+    M -->|Python| P[python:profile]
+    M -->|Frontend| F[frontend:profile]
+    J --> B[标准能力上下文]
+    P --> B
+    F --> B
+    K[项目 standards 与 knowledge] --> B
+    B --> C
+    C --> O[统一产物]
+```
+
+### 3.1 插件职责
+
+| 插件 | 类型 | 职责 |
+| --- | --- | --- |
+| `profile` | 工厂 | 技术栈基础探测、目标模块选择、能力匹配、冲突检查和回退决策 |
+| `java` | 提供方 | Java、JDK、Maven、Gradle、Spring、测试和审查知识 |
+| `python` | 提供方 | Python、包管理、FastAPI、Django、Flask、测试和审查知识 |
+| `frontend` | 提供方 | TypeScript、React、Vue、Next.js、Nuxt、构建和测试知识 |
+| `knowledge` | 核心消费者 | 初始化并维护项目画像和项目知识入口 |
+| `skill` | 核心消费者 | 按优先级检索项目规则和公共技术知识 |
+| `dev` | 核心消费者 | 执行通用设计、实现、测试和审查工作流 |
+
+`doc` 和 `git` 首期不接入语言 Profile。后续只有在命令、生成物或发布规则确实依赖技术栈时，才通过 `command-resolution` 能力读取 Profile。
+
+### 3.2 依赖方向
+
+```text
+dev ──────────┐
+knowledge ────┼──> profile contract <── java
+skill ────────┘                       <── python
+                                      <── frontend
+
+项目 standards/knowledge ──> 覆盖公共 Profile
+```
+
+依赖必须保持单向：
+
+- 核心插件依赖 Profile 契约，不依赖技术插件内部目录。
+- 技术插件实现契约，不反向调用 `dev` 或修改项目画像。
+- Profile 工厂只做解析，不执行设计、编码、测试或审查任务。
+- 技术插件之间不能相互引用内部资料；跨技术协作通过统一契约完成。
+
+## 4. 插件和目录设计
+
+### 4.1 Profile 工厂插件
+
+```text
+plugins/profile/
+├─ .codex-plugin/
+│  └─ plugin.json
+└─ skills/
+   └─ resolve/
+      ├─ SKILL.md
+      ├─ agents/openai.yaml
+      ├─ references/
+      │  ├─ contract.md
+      │  ├─ detection.md
+      │  ├─ resolution.md
+      │  └─ fallback.md
+      └─ scripts/
+         └─ validate_profile.py
+```
+
+`profile:resolve` 是唯一工厂入口，承担以下职责：
+
+1. 接收目标目录、任务所需能力和项目画像。
+2. 确认目标属于哪个模块。
+3. 从项目文件识别语言、框架、版本和工具证据。
+4. 根据能力提供方返回的信息完成匹配。
+5. 合并项目覆盖规则并输出标准能力上下文。
+6. 在缺失、冲突或版本不匹配时返回明确的回退结果。
+
+`validate_profile.py` 只校验确定性的契约结构、标识、版本范围格式和引用文件存在性，不负责执行 Agent 路由。
+
+### 4.2 Java 技术插件
+
+```text
+plugins/java/
+├─ .codex-plugin/
+│  └─ plugin.json
+└─ skills/
+   └─ profile/
+      ├─ SKILL.md
+      ├─ agents/openai.yaml
+      └─ references/
+         ├─ manifest.json
+         ├─ index.md
+         ├─ language/
+         ├─ build/
+         ├─ frameworks/
+         │  └─ spring/
+         ├─ persistence/
+         ├─ testing/
+         └─ review/
+```
+
+Java 插件首期吸收现有 `review-java` 的公共资料，但 `dev:review-java` 的入口暂时保留。它通过 `java:profile` 获取专项知识，避免首期同时引入用户入口迁移。
+
+### 4.3 Python 技术插件
+
+```text
+plugins/python/
+├─ .codex-plugin/
+│  └─ plugin.json
+└─ skills/
+   ├─ profile/
+   │  ├─ SKILL.md
+   │  ├─ agents/openai.yaml
+   │  └─ references/
+   │     ├─ manifest.json
+   │     ├─ index.md
+   │     ├─ language/
+   │     ├─ packaging/
+   │     ├─ frameworks/
+   │     │  ├─ fastapi/
+   │     │  ├─ django/
+   │     │  └─ flask/
+   │     ├─ persistence/
+   │     ├─ testing/
+   │     └─ review/
+   └─ review-python/
+      ├─ SKILL.md
+      └─ agents/openai.yaml
+```
+
+`python:profile` 提供公共知识和能力上下文，`python:review-python` 执行 Python 专项审查。专项审查保持独立，是因为语言问题、触发边界和输出证据与通用代码审查存在明确差异。
+
+### 4.4 Frontend 技术插件
+
+Frontend 插件在 Java/Python 闭环稳定后实施。它遵循同一契约，不把前端框架内容放入 Java 或 Python 插件。
+
+```text
+plugins/frontend/
+├─ .codex-plugin/plugin.json
+└─ skills/
+   ├─ profile/
+   ├─ review-typescript/
+   └─ test-frontend/
+```
+
+## 5. Profile 契约设计
+
+### 5.1 提供方清单
+
+每个技术插件以 `references/manifest.json` 作为能力清单的唯一权威来源。清单只记录路由元数据，详细规则通过相对路径指向同一插件内的 Markdown 资料。JSON 可由 Python 标准库直接校验，不为契约校验器增加第三方 YAML 解析依赖。
+
+```json
+{
+  "schemaVersion": 1,
+  "provider": {
+    "id": "python",
+    "kind": "language",
+    "displayName": "Python"
+  },
+  "profiles": [
+    {
+      "id": "python/default",
+      "versionRange": "*",
+      "detect": {
+        "manifests": ["pyproject.toml", "requirements.txt"],
+        "lockFiles": ["uv.lock", "poetry.lock", "pdm.lock", "Pipfile.lock"]
+      },
+      "capabilities": {
+        "backend-design": "references/backend/design.md",
+        "backend-implementation": "references/backend/implementation.md",
+        "backend-testing": "references/testing/index.md",
+        "language-review": "references/review/index.md",
+        "command-resolution": "references/packaging/commands.md"
+      },
+      "fallback": "references/fallback.md"
+    }
+  ]
+}
+```
+
+清单规则：
+
+- `schemaVersion` 控制契约结构兼容性，与插件版本分开管理。
+- `provider.id` 与插件标识一致，不能使用项目名或公司名。
+- `profile.id` 使用 `<provider>/<variant>` 格式，并在发布后保持稳定。
+- `versionRange` 必须显式声明；无法确定时只提供版本中性 Profile。
+- `detect` 只声明非敏感、可验证的项目证据。
+- `capabilities` 的键来自统一能力表，值只能引用当前插件内文件。
+- 缺少某项能力表示“不提供”，不能用空文件占位。
+
+### 5.2 能力标识
+
+| 能力标识 | 消费者 | 输出用途 |
+| --- | --- | --- |
+| `project-detection` | `knowledge:init` | 补充语言、框架和工具识别规则 |
+| `knowledge-routing` | `skill:guidance` | 提供公共知识索引入口 |
+| `backend-design` | `dev:design-backend` | 提供语言与框架设计约束 |
+| `backend-implementation` | `dev:implement-backend` | 提供实现结构和验证规则 |
+| `backend-testing` | `dev:test-backend` | 提供测试层级、工具和命令规则 |
+| `language-review` | 专项审查 Skill | 提供语言问题分类和证据要求 |
+| `framework-review` | 专项或通用审查 | 提供框架生命周期、事务等规则 |
+| `command-resolution` | 实现、测试及后续系统插件 | 提供项目工具命令选择规则 |
+
+能力标识首期使用固定枚举。新增标识必须先更新契约，再由提供方实现，不能由单个技术插件私自扩展相近名称。
+
+### 5.3 标准能力请求
+
+核心 Skill 向 Profile 工厂提供以下语义输入：
+
+```yaml
+target: services/order
+capabilities:
+  - backend-design
+task: 为订单服务设计幂等创建流程
+projectProfile: .craftkit/project.json
+```
+
+这不是外部 HTTP 接口。它定义 Skill 协作时必须具备的信息，实际内容由 Agent 从用户任务和项目文件构造。
+
+### 5.4 标准能力上下文
+
+Profile 工厂返回的结果必须区分事实、选择结果、规则入口和缺口：
+
+```yaml
+schemaVersion: 1
+targetModule: order-service
+detected:
+  language:
+    name: python
+    version: "3.12"
+    evidence: pyproject.toml
+  framework:
+    name: fastapi
+    version: "0.115.0"
+    evidence: uv.lock
+resolvedProfiles:
+  - id: python/default
+    provider: python
+  - id: python/fastapi-0
+    provider: python
+capabilities:
+  backend-design:
+    status: available
+    references:
+      - python:profile/references/backend/design.md
+      - python:profile/references/frameworks/fastapi/design.md
+overrides:
+  - .craftkit/standards/backend/index.md
+gaps: []
+```
+
+标准能力上下文默认只存在于当前任务上下文中，不写入项目文件。只有初始化或用户明确要求更新项目画像时，才持久化稳定的识别结果。
+
+### 5.5 路径标识
+
+跨插件引用使用逻辑标识：
+
+```text
+<plugin>:<skill>/<skill 内相对路径>
+```
+
+例如：
+
+```text
+python:profile/references/testing/index.md
+```
+
+该标识用于说明应激活的插件能力和资料入口，不拼接用户缓存目录。提供方 Skill 负责读取自身资料，消费者不直接假设磁盘安装位置。
+
+## 6. 项目画像设计
+
+### 6.1 Schema 版本
+
+`.craftkit/project.json` 从 `schemaVersion: 1` 兼容演进至 `schemaVersion: 2`。版本 2 增加模块级技术栈和 Profile 绑定，保留版本 1 的顶层字段。
+
+建议结构：
+
+```json
+{
+  "schemaVersion": 2,
+  "initialization": {
+    "mode": "existing",
+    "references": []
+  },
+  "project": {
+    "name": "sample",
+    "description": "",
+    "type": "multi-module"
+  },
+  "technology": {
+    "languages": [
+      {
+        "name": "python",
+        "version": "3.12",
+        "profile": "python/default",
+        "evidence": ["pyproject.toml"]
+      }
+    ],
+    "frameworks": [
+      {
+        "name": "fastapi",
+        "version": "0.115.0",
+        "profile": "python/fastapi-0",
+        "evidence": ["uv.lock"]
+      }
+    ],
+    "buildTools": [],
+    "databases": []
+  },
+  "modules": [
+    {
+      "id": "api",
+      "root": ".",
+      "kind": "backend",
+      "profiles": ["python/default", "python/fastapi-0"]
+    }
+  ],
+  "commands": {
+    "build": [],
+    "test": ["uv run pytest"],
+    "check": ["uv run ruff check ."]
+  }
+}
+```
+
+### 6.2 字段规则
+
+- `technology.languages` 从字符串数组兼容扩展为对象数组，记录版本、Profile 和证据。
+- `technology.frameworks` 延续已有对象语义，新增 `evidence`。
+- `modules` 描述多模块仓库中的技术边界；单模块项目仍生成一个根模块。
+- `modules[].profiles` 只记录已安装、已匹配且经过初始化确认的 Profile。
+- `commands` 继续记录项目文件或用户确认的真实命令，不由公共 Profile 直接覆盖。
+- 识别证据使用项目相对路径；运行时输出和用户机器绝对路径不进入共享画像。
+
+### 6.3 兼容读取
+
+| 输入状态 | 读取行为 |
+| --- | --- |
+| `schemaVersion: 1` | 将顶层技术栈视为根模块候选，不自动改写文件 |
+| 语言仍是字符串 | 解析名称，版本和 Profile 保持未知 |
+| 没有 `modules` | 根据代码根和目标路径临时推导根模块 |
+| Profile 不存在 | 保留技术事实，将 Profile 标记为未解析 |
+| 新旧证据冲突 | 保留原值并展示差异，确认后更新 |
+
+Schema 升级只由 `knowledge:init` 或后续明确的迁移能力执行。普通设计、实现和审查 Skill 不修改项目画像。
+
+## 7. 核心流程设计
+
+### 7.1 初始化流程
+
+```mermaid
+sequenceDiagram
+    participant U as 用户
+    participant I as knowledge:init
+    participant R as profile:resolve
+    participant P as 技术能力提供方
+    participant J as project.json
+
+    I->>I: 通用扫描项目文件与模块
+    I->>R: 请求 project-detection
+    R->>P: 按证据匹配已安装提供方
+    P-->>R: 返回探测规则与候选 Profile
+    R-->>I: 返回已识别、冲突和待确认项
+    I-->>U: 展示证据与拟写入内容
+    U-->>I: 确认或修正
+    I->>J: 保守合并项目画像
+    I->>R: 验证持久化后的解析结果
+    R-->>I: 返回验证结果
+```
+
+状态变化：
+
+- 写入前：项目扫描结果只存在于任务上下文。
+- 用户确认后：`knowledge:init` 单点写入或合并 `.craftkit/project.json`。
+- 写入失败：保留原文件，不允许语言插件继续部分写入。
+- 验证失败：报告已写入内容和失败原因，由初始化 Skill决定回滚或修正。
+
+### 7.2 后端设计流程
+
+`dev:design-backend` 接入后执行以下步骤：
+
+1. 读取需求、目标模块、项目画像和现有实现。
+2. 请求 `backend-design` 能力。
+3. Profile 工厂解析语言、框架、版本和项目覆盖规则。
+4. 技术插件提供当前版本适用的设计资料入口。
+5. `design-backend` 合并通用边界与专项约束。
+6. 输出统一的模块、依赖、数据、事务、错误、权限和测试设计。
+7. 输出中标明使用的 Profile、项目覆盖规则和未覆盖能力。
+
+语言插件不生成最终设计文档。最终责任仍属于 `design-backend`，从而保证不同语言的设计产物结构一致。
+
+### 7.3 实现和测试流程
+
+- `implement-backend` 请求 `backend-implementation` 和 `command-resolution`。
+- `test-backend` 请求 `backend-testing` 和 `command-resolution`。
+- Profile 提供命令选择规则，最终命令必须由项目文件或用户确认支持。
+- 写代码和测试的权限、范围控制及 Git 边界继续由原核心 Skill 负责。
+- 技术插件不能因提供某种工具规则而自动安装工具或新增项目依赖。
+
+### 7.4 知识检索流程
+
+`skill:guidance` 保留现有来源优先级，并在公共基线之前增加 Profile 解析：
+
+1. 用户要求与目标目录 `AGENTS.md`。
+2. `.craftkit/project.json` 和目标模块。
+3. 项目 `.craftkit/standards/` 与 `.craftkit/knowledge/`。
+4. 已解析技术 Profile 的 `knowledge-routing` 入口。
+5. CraftKit 中性公共基线。
+6. 现有代码观察结果。
+
+项目规则与 Profile 冲突时采用项目规则，并在输出中同时给出两者来源。
+
+## 8. 版本与冲突处理
+
+### 8.1 Profile 选择
+
+Profile 选择按以下顺序执行：
+
+1. 使用项目画像中已确认且当前已安装的 Profile。
+2. Profile 未记录时，根据精确版本匹配唯一候选。
+3. 多个候选同时匹配时，优先选择范围更窄且框架证据更具体的候选。
+4. 仍不能唯一确定时，不自动选择，返回候选和差异。
+5. 没有版本匹配时，只加载版本中性资料。
+
+### 8.2 多模块仓库
+
+- 先用目标路径匹配 `modules[].root`，最长路径匹配优先。
+- 同一目标同时命中多个同长度模块时视为配置冲突。
+- 跨模块任务分别解析各模块 Profile，不合并为单一技术栈。
+- 前后端联调通过 API 契约协作，不将后端语言规则加载到前端实现。
+
+### 8.3 能力状态
+
+| 状态 | 含义 | 消费者行为 |
+| --- | --- | --- |
+| `available` | 已安装、版本匹配且资料完整 | 正常加载 |
+| `generic` | 只有版本中性资料 | 使用通用规则并说明范围 |
+| `missing` | 提供方或能力不存在 | 核心流程继续，报告缺口 |
+| `incompatible` | Profile 与项目版本不匹配 | 禁止加载冲突资料 |
+| `ambiguous` | 多个候选无法唯一选择 | 请求最小必要确认 |
+| `invalid` | 清单或引用校验失败 | 隔离该提供方并报告错误 |
+
+## 9. 可靠性、安全与可观测性
+
+### 9.1 一致性
+
+- 只有 `knowledge:init` 可以在初始化流程中写项目画像，防止多个提供方并发覆盖。
+- Profile 解析是只读、可重复执行的过程，相同项目事实和能力版本应得到相同结果。
+- 写入项目画像前保留原内容，采用完整 JSON 校验后再替换目标文件。
+- 数组按语义标识去重，不能因路径分隔符或大小写产生重复模块和证据。
+
+### 9.2 安全边界
+
+- 探测器只读取依赖名称、版本、脚本和非敏感元数据。
+- `.env`、凭据文件、令牌、私钥和完整仓库认证信息不作为 Profile 证据。
+- 公共能力包不得保存内部包源码、公司规范或业务项目内容。
+- Profile 提供的命令是选择规则，不构成执行授权。
+- 实现、测试、提交和发布仍遵循对应核心 Skill 的权限规则。
+
+### 9.3 诊断输出
+
+每次 Profile 解析至少能够报告：
+
+- 目标模块及匹配依据。
+- 语言、框架、版本和证据路径。
+- 命中的 Profile 与能力状态。
+- 项目规则覆盖情况。
+- 缺失、冲突、无效和版本不匹配项。
+- 当前核心 Skill 可以继续执行的范围。
+
+诊断信息默认在任务中输出，不在项目中生成运行日志。
+
+## 10. 迁移设计
+
+### 10.1 迁移原则
+
+- 先增加契约和提供方，再改造消费者。
+- 先逻辑分层，再迁移目录和用户入口。
+- 每个消费者独立接入并验证，不一次修改所有 Skill。
+- 旧项目画像只读兼容，新字段在明确初始化或迁移时写入。
+- 旧 Skill 入口至少保留一个兼容发布周期，避免用户已保存的调用失效。
+
+### 10.2 存量内容迁移
+
+| 存量内容 | 首期处理 | 后续处理 |
+| --- | --- | --- |
+| `dev:review-java` | 保留入口，改为读取 Java Profile | 稳定后评估迁入 Java 插件 |
+| `guidance` 公共后端规则 | 保留中性规则 | Java/Python 专项内容迁入对应插件 |
+| `guidance` 版本路由 | 扩展为调用 `profile:resolve` | 旧文档改为契约说明入口 |
+| `knowledge:init` 探测规则 | 保留通用扫描 | 技术专项识别由提供方补充 |
+| `project.json` 模板 | 保留 Schema 1 兼容读取 | 初始化确认后写 Schema 2 |
+| `dev` 后端 Skill | 逐个接入 Profile | 完成后移除重复专项资料 |
+
+### 10.3 回滚
+
+- 新插件尚未发布时，删除 marketplace 新增项即可恢复原安装集合。
+- 消费者接入必须保留“未找到 Profile 时执行原通用流程”的分支。
+- Schema 2 画像不能直接降级覆盖为 Schema 1；回滚核心插件时保留文件，并按已知顶层字段读取。
+- 技术资料迁移前保留 Git 历史，完成所有消费者切换后才能删除原位置。
+
+## 11. 实施方案
+
+### 11.1 批次 A：Profile 契约和工厂骨架
+
+**新增文件**
+
+```text
+plugins/profile/.codex-plugin/plugin.json
+plugins/profile/skills/resolve/SKILL.md
+plugins/profile/skills/resolve/agents/openai.yaml
+plugins/profile/skills/resolve/references/contract.md
+plugins/profile/skills/resolve/references/detection.md
+plugins/profile/skills/resolve/references/resolution.md
+plugins/profile/skills/resolve/references/fallback.md
+plugins/profile/skills/resolve/scripts/validate_profile.py
+```
+
+**修改文件**
+
+```text
+.agents/plugins/marketplace.json
+README.md
+CHANGELOG.md
+```
+
+**任务**
+
+1. 定义提供方清单和标准能力上下文。
+2. 实现契约静态校验器。
+3. 编写模块匹配、版本选择、能力状态和回退规则。
+4. 注册 `profile` 插件并补充安装说明。
+
+**验收**
+
+- 有效、缺字段、重复标识、无效版本范围和失效引用五类样例均有确定结果。
+- `profile` 单独安装时能够解释缺少技术提供方并返回 `missing`。
+
+### 11.2 批次 B：Java 基准提供方
+
+**新增文件**
+
+```text
+plugins/java/.codex-plugin/plugin.json
+plugins/java/skills/profile/SKILL.md
+plugins/java/skills/profile/agents/openai.yaml
+plugins/java/skills/profile/references/manifest.json
+plugins/java/skills/profile/references/index.md
+plugins/java/skills/profile/references/language/index.md
+plugins/java/skills/profile/references/build/index.md
+plugins/java/skills/profile/references/frameworks/spring/index.md
+plugins/java/skills/profile/references/testing/index.md
+plugins/java/skills/profile/references/review/index.md
+```
+
+**修改文件**
+
+```text
+.agents/plugins/marketplace.json
+plugins/dev/skills/review-java/SKILL.md
+plugins/dev/skills/review-java/references/sources.md
+README.md
+CHANGELOG.md
+```
+
+**任务**
+
+1. 将现有 Java 规则映射到能力清单。
+2. 建立 JDK、Maven/Gradle 和 Spring 的渐进加载入口。
+3. 让 `dev:review-java` 读取 Java Profile；未安装时使用现有最小基线。
+4. 使用现有 Java 项目验证路由和回退。
+
+**验收**
+
+- Java 版本和构建工具有项目证据。
+- Spring 资料只在依赖和版本匹配时加载。
+- `review-java` 的现有触发范围和审查输出不退化。
+
+### 11.3 批次 C：Python 最小提供方
+
+**新增文件**
+
+```text
+plugins/python/.codex-plugin/plugin.json
+plugins/python/skills/profile/SKILL.md
+plugins/python/skills/profile/agents/openai.yaml
+plugins/python/skills/profile/references/manifest.json
+plugins/python/skills/profile/references/index.md
+plugins/python/skills/profile/references/language/index.md
+plugins/python/skills/profile/references/packaging/index.md
+plugins/python/skills/profile/references/frameworks/fastapi/index.md
+plugins/python/skills/profile/references/persistence/index.md
+plugins/python/skills/profile/references/testing/index.md
+plugins/python/skills/profile/references/review/index.md
+plugins/python/skills/review-python/SKILL.md
+plugins/python/skills/review-python/agents/openai.yaml
+```
+
+**修改文件**
+
+```text
+.agents/plugins/marketplace.json
+README.md
+CHANGELOG.md
+```
+
+**任务**
+
+1. 支持 `pyproject.toml`、依赖文件、锁文件和 Python 版本证据。
+2. 支持 pip、uv、Poetry、PDM 和 Pipenv 的项目内选择。
+3. 建立 Python 通用、FastAPI、pytest、Ruff 和类型检查资料入口。
+4. 新增 Python 专项审查 Skill。
+5. 使用 FastAPI 项目验证语言、框架、测试和审查能力。
+
+**验收**
+
+- 不配置 Ruff、mypy 或 pyright 的项目不会被假定具备对应命令。
+- 同步与异步规则按真实代码和框架配置选择。
+- Python 版本未知时不输出版本专属语法升级建议。
+
+### 11.4 批次 D：初始化和画像 Schema 2
+
+**修改文件**
+
+```text
+plugins/knowledge/skills/init/SKILL.md
+plugins/knowledge/skills/init/references/existing.md
+plugins/knowledge/skills/init/references/new.md
+plugins/knowledge/skills/init/references/project-config.md
+plugins/knowledge/skills/init/assets/project.json
+plugins/knowledge/skills/init/assets/AGENTS.md
+```
+
+**新增文件**
+
+```text
+plugins/knowledge/skills/init/references/profile-resolution.md
+plugins/knowledge/skills/init/references/project-schema-v2.md
+```
+
+**任务**
+
+1. 将通用扫描与技术提供方探测分离。
+2. 增加模块级技术栈和识别证据。
+3. 定义 Schema 1 到 Schema 2 的保守合并规则。
+4. 初始化结束后调用 Profile 解析做一致性验证。
+
+**验收**
+
+- Java、Python、前后端混合和旧版画像四类项目均能完成初始化。
+- 未安装语言插件时仍能记录技术事实，但 Profile 保持未解析。
+- 已有未知字段和用户章节不会被删除。
+
+### 11.5 批次 E：规范检索和核心后端消费者
+
+**修改文件**
+
+```text
+plugins/skill/skills/guidance/SKILL.md
+plugins/skill/skills/guidance/references/profile-routing.md
+plugins/dev/skills/design-backend/SKILL.md
+plugins/dev/skills/implement-backend/SKILL.md
+plugins/dev/skills/test-backend/SKILL.md
+```
+
+**任务**
+
+1. `guidance` 将 Profile 知识入口纳入渐进加载顺序。
+2. `design-backend` 请求 `backend-design` 能力。
+3. `implement-backend` 请求 `backend-implementation` 和 `command-resolution`。
+4. `test-backend` 请求 `backend-testing` 和 `command-resolution`。
+5. 三个核心 Skill 统一报告命中 Profile、覆盖规则和能力缺口。
+
+**验收**
+
+- 相同后端需求在 Spring Boot 和 FastAPI 项目中使用不同专项知识，但输出结构一致。
+- 目标模块技术栈不明确时不会加载仓库中其他模块的 Profile。
+- 语言插件缺失时核心 Skill 可按原中性流程完成可确认部分。
+
+### 11.6 批次 F：框架补全和前端接入
+
+**任务**
+
+- 补充 Django、Flask、SQLAlchemy、Alembic 和 Django ORM。
+- 建立 Frontend Profile、`review-typescript` 和 `test-frontend`。
+- 通过 `design-api` 与 `prepare-api` 验证不同后端语言到前端的统一契约。
+- 根据实际维护成本决定是否迁移 `review-java` 到 Java 插件。
+
+**验收**
+
+- 框架 Profile 可以独立演进，不修改核心工作流步骤。
+- 前端消费者只读取 API 契约和前端 Profile，不加载后端语言实现规则。
+
+## 12. 测试方案
+
+### 12.1 静态校验
+
+- 校验插件目录、`plugin.json`、Skill frontmatter 和 `agents/openai.yaml`。
+- 校验 Profile 清单 Schema、能力枚举、版本范围和引用路径。
+- 扫描跨插件物理路径和用户缓存绝对路径。
+- 检查空资料、占位符、重复 Profile 标识和失效链接。
+
+### 12.2 路由场景
+
+| 编号 | 场景 | 预期能力状态 |
+| --- | --- | --- |
+| R1 | Java 17、Spring Boot 3、Maven Wrapper | Java 与 Spring `available` |
+| R2 | Python 3.12、FastAPI、uv | Python 与 FastAPI `available` |
+| R3 | Python 项目无质量工具 | 语言能力可用，未配置工具不进入命令 |
+| R4 | Python 版本未知 | Python `generic`，版本专属规则不加载 |
+| R5 | 项目版本超出 Profile 范围 | 对应能力 `incompatible` |
+| R6 | 未安装 Python 插件 | Python 专项能力 `missing`，核心流程继续 |
+| R7 | Java/Python 混合仓库 | 根据目标模块分别解析 |
+| R8 | 两个同长度模块同时匹配 | 解析结果 `ambiguous` |
+| R9 | Profile 引用文件缺失 | 提供方 `invalid` 并被隔离 |
+| R10 | 项目规范覆盖公共规则 | 返回覆盖来源并采用项目规则 |
+
+### 12.3 端到端场景
+
+分别准备一个最小 Spring Boot 项目和一个最小 FastAPI 项目，对两者执行相同任务：
+
+1. 初始化项目画像。
+2. 查询后端规范。
+3. 设计一个包含事务和外部调用的后端功能。
+4. 给出最小实现变更。
+5. 生成并运行聚焦测试。
+6. 执行语言专项审查。
+
+验证重点：
+
+- 每一步使用了正确模块和 Profile。
+- 项目已有命令优先于公共建议。
+- 设计产物结构一致，语言实现规则不同。
+- 缺失工具不会被隐式安装或写入项目。
+- 失败结果能够区分项目缺陷、环境问题和 Profile 缺口。
+
+## 13. 发布方案
+
+### 13.1 发布顺序
+
+1. 发布 `profile` 插件及契约。
+2. 发布 Java 基准插件。
+3. 发布 Python 最小插件。
+4. 发布接入新版契约的 `knowledge` 和 `skill` 插件。
+5. 发布接入新版契约的 `dev` 插件。
+6. 完成一轮双语言端到端回归后，再补充 Frontend 插件。
+
+### 13.2 版本影响
+
+- 新增独立插件使用 `0.1.0` 起始版本。
+- 核心插件新增可回退的 Profile 增强时升级次版本。
+- 删除或移动已有 Skill 入口属于不兼容变更，必须单独规划主版本。
+- `.craftkit/project.json` Schema 2 在保留 Schema 1 读取能力时属于向后兼容能力；停止读取 Schema 1 才属于不兼容变化。
+
+### 13.3 安装组合
+
+| 使用场景 | 建议安装 |
+| --- | --- |
+| 通用项目管理 | `knowledge`、`skill`、`profile` |
+| Java 后端 | 通用组合 + `dev` + `java` |
+| Python 后端 | 通用组合 + `dev` + `python` |
+| 前后端项目 | 对应后端组合 + `frontend` |
+| 仅使用通用开发流程 | `dev`，Profile 缺失时按中性流程回退 |
+
+## 14. 实现交接清单
+
+编码按以下已定口径执行：
+
+- Profile 清单采用 JSON，校验器仅依赖 Python 标准库。
+- 插件之间不要求平台提供可选依赖声明，通过能力契约、安装说明和回退状态协作。
+- `.craftkit/project.json` 采用兼容的 Schema 2，对 Schema 1 保持只读兼容。
+- `dev:review-java` 首期保留一个兼容发布周期，只把公共知识来源切换到 Java Profile。
+- Python 先提供版本中性 Profile；版本专项 Profile 必须依据纳入支持范围的真实项目和官方资料另行建立。
+- 双语言验证优先使用仓库内无业务数据的最小夹具；引入外部项目时另行确认扫描范围和命令。
+
+实施按 A 到 F 顺序进行。每个批次独立提交、独立验证；前一批次契约或回退未通过时，不进入下一个消费者改造批次。
+
+## 15. 设计自检结论
+
+- 职责明确：工厂只解析，技术插件只提供能力，核心 Skill 负责最终工作流。
+- 依赖单向：消费者依赖契约，不依赖技术插件物理目录。
+- 数据所有权明确：项目画像由 `knowledge:init` 写入，技术插件只读。
+- 失败状态明确：缺失、不兼容、歧义和无效清单均有独立状态和回退。
+- 兼容策略明确：保留 Schema 1 读取、现有 Skill 入口和无 Profile 通用流程。
+- 安全边界明确：Profile 探测不读取凭据，命令建议不构成执行授权。
+- 验证完整：覆盖静态契约、路由组合和 Java/Python 端到端场景。
+- 实施可拆分：六个批次均有文件范围、任务和验收标准。

.craftkit/designs/multi-language-plugin/MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-PLAN.md

@@ -0,0 +1,459 @@
+# 多语言插件架构改造计划
+
+## 1. 文档目标
+
+本计划用于将 CraftKit 从“通用工作流中按需补充技术资料”演进为“核心工作流、技术 Profile 和项目知识分层协作”的多语言插件体系。
+
+首个交付目标是打通 Java 与 Python 两种后端技术栈，使项目初始化、知识检索、后端设计、实现、测试和专项审查能够依据项目真实依赖选择对应能力。后续语言和框架沿用同一契约扩展，不复制整套工作流。
+
+本计划只定义目标架构、职责边界、实施批次和验收口径，不直接调整现有 Skill、插件清单或项目配置格式。
+
+## 2. 建设原则
+
+- 核心工作流保持技术中立：需求、设计、实现、测试和交付流程只定义共同步骤与统一产物。
+- 技术差异由能力包维护：语言、框架、构建、测试和审查规则放入可独立演进的技术 Profile。
+- 项目事实决定路由：语言、版本、框架和工具必须来自构建文件、锁文件、源码或用户确认。
+- 项目规则优先于公共规则：公共 Profile 提供默认能力，项目知识库保存当前项目的补充和覆盖规则。
+- 能力按需加载：一个任务只读取当前阶段、语言和框架所需资料，不把所有技术内容装入上下文。
+- 缺少增强能力时可回退：未安装语言插件或无法确认版本时，核心 Skill 继续执行通用流程，并明确未覆盖边界。
+- 插件按维护价值拆分：首期以 Java、Python 和 Frontend 为能力包边界，不为每个框架创建独立插件。
+
+规则优先级固定为：
+
+1. 用户本次明确要求。
+2. 目标目录适用的 `AGENTS.md` 和项目本地规范。
+3. `.craftkit/project.json` 中选定的技术 Profile。
+4. 已安装语言或框架能力包的公共规则。
+5. CraftKit 核心工作流的通用规则。
+
+## 3. 目标架构
+
+路由和回退规则见第 6 节。整体调用关系如下：
+
+```mermaid
+flowchart LR
+    A[项目初始化] --> B[技术栈探测]
+    B --> C[项目画像 project.json]
+    C --> D[Profile 解析]
+    D --> J[Java 能力包]
+    D --> P[Python 能力包]
+    D --> F[Frontend 能力包]
+    J --> W[核心工作流]
+    P --> W
+    F --> W
+    K[项目规范与知识库] --> W
+    W --> O[统一设计、代码、测试与审查产物]
+```
+
+### 3.1 分层职责
+
+| 层级 | 核心职责 | 不负责事项 |
+| --- | --- | --- |
+| 核心工作流 | 定义初始化、设计、实现、测试、审查和交付的共同流程与产物 | 不内置完整语言或框架规则 |
+| Profile 解析 | 根据项目画像解析能力、资料入口、命令和版本范围 | 不猜测未确认技术栈，不生成业务产物 |
+| 技术能力包 | 提供语言、框架、构建、测试和专项审查知识 | 不保存具体业务项目的专属规则 |
+| 项目知识库 | 保存项目规范、技术决策、内部组件和已验证经验 | 不复制公共语言和框架文档 |
+
+### 3.2 建议插件边界
+
+目标插件名称在实施阶段结合市场命名和现有清单最终确认，职责先按以下边界规划：
+
+| 插件 | 主要内容 | 首期范围 |
+| --- | --- | --- |
+| `core` | 通用设计、实现、测试、审查及 Profile 路由协议 | 由现有 `dev`、`knowledge` 等插件逐步演进，不立即物理合并 |
+| `profile` | 技术栈探测、Profile 解析和能力契约校验 | 可先作为现有 `knowledge:init` 的内部能力验证 |
+| `java` | Java、JDK、Maven、Gradle、Spring 和 Java 专项审查资料 | 迁移现有 Java 能力，作为契约基准实现 |
+| `python` | Python、包管理、FastAPI、Django、Flask、测试和专项审查资料 | 新增最小可用能力包 |
+| `frontend` | TypeScript、React、Vue、Next.js、Nuxt 和前端工程质量资料 | 后续按同一契约接入 |
+
+首期不要求立即移动现有目录。先在当前插件结构中验证契约和路由，稳定后再决定是否拆分为独立可安装插件，避免目录迁移与能力改造同时进行。
+
+## 4. Profile 能力契约
+
+每个技术能力包必须提供统一入口，供初始化和核心工作流解析。契约至少包含以下信息：
+
+| 字段 | 含义 | 要求 |
+| --- | --- | --- |
+| `id` | Profile 唯一标识 | 使用稳定的小写标识，不包含项目名称 |
+| `kind` | `language`、`framework`、`build` 或 `frontend` | 必填 |
+| `versionRange` | 当前资料适用版本范围 | 未声明时不得给出版本专属结论 |
+| `detect` | 可验证的识别证据 | 只使用文件、依赖和源码事实 |
+| `capabilities` | 支持的工作流能力 | 使用统一能力标识 |
+| `references` | 各能力的资料入口 | 使用能力包内相对路径 |
+| `commands` | 构建、测试和检查命令的选择规则 | 不能覆盖项目已验证命令 |
+| `fallback` | 能力缺失或版本不匹配时的处理 | 必须明确可继续范围和停止条件 |
+
+首期统一能力标识：
+
+```text
+project-detection
+knowledge-routing
+backend-design
+backend-implementation
+backend-testing
+language-review
+framework-review
+command-resolution
+```
+
+契约载体可以使用 JSON、YAML 或 Markdown 索引。第一阶段先确定字段语义和解析规则，再选择最终格式；不得同时维护多份等价清单。
+
+### 4.1 Python 能力包最小契约示例
+
+以下内容仅用于说明字段关系，实施时以最终契约文件为准：
+
+```yaml
+id: python
+kind: language
+versionRange: ">=3.9,<3.14"
+detect:
+  manifests:
+    - pyproject.toml
+    - requirements.txt
+  lockFiles:
+    - uv.lock
+    - poetry.lock
+    - pdm.lock
+    - Pipfile.lock
+capabilities:
+  - project-detection
+  - knowledge-routing
+  - backend-design
+  - backend-implementation
+  - backend-testing
+  - language-review
+references:
+  backend-design: references/backend/index.md
+  backend-testing: references/testing/index.md
+  language-review: references/review/index.md
+fallback: 使用核心工作流，只报告有项目证据支持的通用结论
+```
+
+## 5. 项目画像调整
+
+`.craftkit/project.json` 继续作为项目事实入口，不承担公共规则正文。现有 `technology`、`commands` 和 `guidance` 字段保留，后续通过兼容方式补充已解析 Profile 和证据来源。
+
+建议补充的信息如下：
+
+| 信息 | 示例 | 来源 |
+| --- | --- | --- |
+| 语言及精确版本 | Python 3.12、Java 17 | 版本文件、构建配置、运行时或用户确认 |
+| 框架及精确版本 | FastAPI 0.115、Spring Boot 3.3 | 依赖清单和锁文件 |
+| 包与构建工具 | uv、Poetry、Maven Wrapper | 项目文件 |
+| 质量工具 | pytest、Ruff、mypy、JUnit | 配置和依赖 |
+| 数据访问工具 | SQLAlchemy、Alembic、MyBatis | 依赖和源码 |
+| Profile 选择 | `python/default`、`fastapi/0.x` | 已安装能力包与版本匹配结果 |
+| 识别证据 | `pyproject.toml`、`pom.xml` | 工作区相对路径 |
+
+画像调整必须满足以下兼容规则：
+
+- 现有 `schemaVersion: 1` 项目仍可被读取。
+- 新字段缺失时按未知处理，不自动写入默认最新版。
+- Profile 标识只有在能力包真实存在且版本匹配时才写入。
+- 项目命令优先保存项目已定义的 Wrapper、脚本或任务入口。
+- 共享画像不记录用户机器绝对路径、凭据或完整连接信息。
+
+## 6. 初始化、路由与回退流程
+
+### 6.1 初始化流程
+
+1. `knowledge:init` 执行通用只读扫描，识别构建文件、锁文件、源码根和现有 `.craftkit` 内容。
+2. Profile 解析器根据已安装能力包匹配语言和框架探测规则。
+3. 初始化结果区分“已确认”“从文件识别”“存在冲突”和“待确认”四类信息。
+4. 用户确认无法从项目事实确定的版本、框架或命令。
+5. 初始化 Skill 合并写入 `.craftkit/project.json`，语言能力包不直接修改项目文件。
+6. 初始化完成后分别验证画像格式、Profile 可解析性、知识入口和一个真实项目命令。
+
+### 6.2 工作流路由
+
+核心 Skill 按以下顺序读取能力：
+
+1. 确认目标文件所属模块和 `.craftkit/project.json` 中的技术栈。
+2. 根据当前任务解析所需能力标识，例如 `backend-design`。
+3. 加载匹配的语言 Profile，再加载框架 Profile。
+4. 读取项目本地规范和知识，将其作为公共规则的补充或覆盖。
+5. 发生版本冲突时停止使用冲突资料，并列出缺少的确认信息。
+6. 按核心 Skill 的统一产物契约输出结果。
+
+### 6.3 回退规则
+
+| 场景 | 行为 |
+| --- | --- |
+| 未安装对应语言能力包 | 执行通用工作流，明确语言专项规则未覆盖 |
+| 已安装能力包但版本不匹配 | 不跨版本套用资料，提示需要匹配 Profile 或官方证据 |
+| 项目同时包含多种语言 | 按目标模块分别解析，不选择仓库级单一语言覆盖全部模块 |
+| 无法确认目标模块 | 先展示候选模块和证据，补齐范围后继续 |
+| 项目规则与公共 Profile 冲突 | 采用项目规则，并记录冲突来源和影响 |
+| 框架 Profile 缺失 | 使用语言 Profile 和通用工作流，不猜测框架行为 |
+
+## 7. Java 与 Python 能力范围
+
+### 7.1 Java 基准能力包
+
+Java 能力包优先复用现有 `review-java` 和后端 Skill 已验证规则，用于检验契约能否承载存量能力。
+
+- 探测：`pom.xml`、Maven Wrapper、Gradle 文件、JDK 配置和模块结构。
+- 设计：Spring、事务、依赖注入、DTO、持久化和异步边界。
+- 实现：Java 版本、构建工具、代码结构和项目约定。
+- 测试：JUnit、Mockito、Spring Test 和项目测试命令。
+- 审查：类型、资源、异常、并发、序列化和公开契约。
+
+### 7.2 Python 首期能力包
+
+Python 首期覆盖可形成后端闭环的共同能力：
+
+- 探测：`pyproject.toml`、常见依赖文件、锁文件、Python 版本文件和源码布局。
+- 包管理：pip、uv、Poetry、PDM 和 Pipenv，只选择项目已有工具。
+- 设计：模块边界、Pydantic Schema、依赖注入、事务、异步和配置边界。
+- 实现：类型标注、异常处理、资源管理、同步与异步调用以及依赖约束。
+- 测试：pytest、unittest、pytest-asyncio 和框架测试客户端。
+- 质量：Ruff、mypy、pyright、Black 等工具按项目配置路由。
+- 数据访问：SQLAlchemy、Alembic 和 Django ORM 按真实依赖路由。
+- 框架：首个端到端样例使用 FastAPI，Django 和 Flask 在契约稳定后补齐。
+- 审查：新增 `review-python`，只报告有代码证据和明确影响的问题。
+
+### 7.3 前端协作边界
+
+前端 Skill 不因后端使用 Python 而复制实现。前后端通过统一 API 契约协作：
+
+- Python 能力包负责从路由、Pydantic Schema、序列化器或 OpenAPI 提取后端契约证据。
+- `design-api` 和 `prepare-api` 负责形成统一的请求、响应、错误、分页、鉴权和版本约定。
+- 前端 Profile 根据 TypeScript、React、Vue 等真实技术栈消费契约。
+- 后端语言专属模型不得直接成为前端组件和状态设计的默认依据。
+
+## 8. 项目知识库适配
+
+公共技术知识和项目知识必须分开维护：
+
+| 知识类型 | 维护位置 | 示例 |
+| --- | --- | --- |
+| 语言稳定规则 | 语言能力包 | Python 异步语义、Java 资源管理 |
+| 框架版本规则 | 语言能力包的框架资料 | FastAPI 依赖注入、Spring 事务 |
+| 工具规则 | 对应技术能力包 | pytest、Ruff、Maven、Gradle |
+| 项目开发规范 | `.craftkit/standards/` | 包结构、命名、错误码和测试要求 |
+| 项目技术决策 | `.craftkit/knowledge/decisions/` | 选择 uv、禁用同步数据库访问 |
+| 已验证项目经验 | `.craftkit/knowledge/pitfalls/` | 项目特有故障及复现、规避方法 |
+
+`guidance` 负责统一检索入口。语言能力包提供公共资料索引，项目初始化只登记当前项目实际适用的入口，不复制整套公共知识到项目目录。
+
+## 9. 分阶段实施计划
+
+### 阶段 P0：契约和存量能力盘点
+
+**任务**
+
+- 盘点 `init`、后端设计、实现、测试、审查和 `guidance` 的输入、输出与资料入口。
+- 列出现有 Java、前端和通用规则的实际位置，识别重复和语言耦合内容。
+- 定义 Profile 字段、能力标识、版本匹配、覆盖优先级和回退规则。
+- 确定契约的唯一权威文件及校验方式。
+
+**产物**
+
+- Profile 契约规范。
+- 存量能力映射表。
+- 首期目录和插件边界决策。
+
+**完成标准**
+
+- 同一个核心 Skill 可以通过契约描述 Java 与 Python 两种能力入口。
+- 契约能够表达缺失、版本不匹配、多模块和项目覆盖场景。
+
+### 阶段 P1：Java 基准 Profile
+
+**任务**
+
+- 将现有 Java 专项规则映射到统一能力标识。
+- 建立 Java、JDK、Maven/Gradle 和首个 Spring Profile 入口。
+- 让一个现有后端 Skill 通过 Profile 入口读取 Java 资料。
+- 保持现有 Java Skill 的触发和输出行为兼容。
+
+**产物**
+
+- Java Profile。
+- Java 资料索引。
+- 契约兼容性验证记录。
+
+**完成标准**
+
+- Spring Boot 样例项目可解析语言、版本、构建工具和对应能力。
+- 改造前已有的 Java 审查规则没有丢失或被无关 Profile 覆盖。
+
+### 阶段 P2：Python 最小能力包
+
+**任务**
+
+- 建立 Python 探测规则、版本规则和包管理工具路由。
+- 建立 Python 后端设计、实现、测试和审查资料入口。
+- 新增 `review-python` 专项 Skill。
+- 以 FastAPI、pytest、Ruff 和一种类型检查器形成最小闭环。
+
+**产物**
+
+- Python Profile 与资料索引。
+- `review-python`。
+- FastAPI 示例验证矩阵。
+
+**完成标准**
+
+- 不安装未声明工具，不默认最新版本，不混用同步与异步规则。
+- 能够对一个真实 FastAPI 项目完成设计、实现指导、测试建议和专项审查。
+
+### 阶段 P3：初始化和项目画像接入
+
+**任务**
+
+- 扩展 `knowledge:init` 的技术栈探测和 Profile 解析步骤。
+- 设计 `.craftkit/project.json` 的兼容升级方案。
+- 支持多模块、多语言和冲突证据记录。
+- 验证旧版项目画像的读取和保守合并。
+
+**产物**
+
+- 新版项目画像 Schema 与迁移规则。
+- 初始化 Skill 改造。
+- Java、Python 和混合仓库初始化样例。
+
+**完成标准**
+
+- 初始化能够生成可追溯的 Profile 选择结果。
+- 旧项目无需一次性重写即可继续使用。
+
+### 阶段 P4：核心后端工作流接入
+
+**任务**
+
+- 依次改造 `design-backend`、`implement-backend` 和 `test-backend`。
+- 将语言专属判断替换为能力标识和资料入口解析。
+- 保持设计文档、实现交付和测试报告的统一格式。
+- 增加能力缺失和版本冲突的回退说明。
+
+**产物**
+
+- 支持 Java/Python 路由的三个核心后端 Skill。
+- 两种语言的端到端对照结果。
+
+**完成标准**
+
+- 同一请求在 Java 与 Python 项目中加载不同技术资料，但保持相同工作流阶段。
+- 核心 Skill 中不新增大段按语言复制的条件规则。
+
+### 阶段 P5：知识库和专项框架扩展
+
+**任务**
+
+- 将公共语言资料接入 `guidance` 的统一检索入口。
+- 补充 Django、Flask、SQLAlchemy、Alembic 和 Django ORM 路由。
+- 按真实使用需求补充 Spring 和 Java 工具版本资料。
+- 建立公共资料与项目知识之间的引用和覆盖规则。
+
+**产物**
+
+- Java/Python 知识索引。
+- 框架与工具 Profile。
+- 知识检索验证场景。
+
+**完成标准**
+
+- 查询能够定位到当前项目实际语言、框架和版本的资料。
+- 公共资料没有被重复复制到项目 `.craftkit` 目录。
+
+### 阶段 P6：插件拆分与独立发布评估
+
+**任务**
+
+- 根据前五阶段的真实依赖评估 Java、Python、Frontend 是否拆为独立插件。
+- 明确插件安装依赖、缺失提示、版本兼容和独立发布策略。
+- 更新插件清单、README、CHANGELOG 和版本号。
+- 建立每个能力包的独立静态校验和场景回归。
+
+**产物**
+
+- 最终插件目录。
+- 安装与兼容说明。
+- 发布和回滚方案。
+
+**完成标准**
+
+- 单独安装核心插件仍可执行通用流程。
+- 安装 Java 或 Python 插件后只增强对应技术能力。
+- 一个语言插件升级失败不会破坏其他语言工作流。
+
+## 10. 首个开发迭代
+
+首个迭代只实现“Profile 契约 + Java/Python 双 Profile + 一个核心 Skill 路由”，避免同时改造全部插件。
+
+建议任务顺序：
+
+1. 新增 Profile 契约规范和能力清单。
+2. 选择 `design-backend` 作为首个核心消费者。
+3. 将现有 Java 设计资料映射为 Java Profile。
+4. 创建 Python 基础 Profile 和后端设计资料入口。
+5. 使用一个 Spring Boot 项目和一个 FastAPI 项目执行相同设计请求。
+6. 验证版本识别、资料选择、项目规则覆盖和能力缺失回退。
+7. 契约通过后再进入项目画像和其他 Skill 改造。
+
+本迭代不包含：
+
+- 物理拆分或发布新的 Java、Python 插件。
+- 一次性迁移所有现有资料。
+- Django、Flask 和全部前端框架适配。
+- 自动安装语言工具或修改项目依赖。
+- 改造 Git、文档转换和发布类 Skill。
+
+## 11. 验证矩阵
+
+| 场景 | 预期结果 |
+| --- | --- |
+| Java 17 + Spring Boot 3 + Maven Wrapper | 选择匹配的 Java、Spring 和 Maven 能力，优先使用 Wrapper 命令 |
+| Python 3.12 + FastAPI + uv | 选择 Python、FastAPI 和 uv 能力，只使用项目已声明工具 |
+| Python 项目未配置 Ruff | 不生成必须执行 Ruff 的结论，可将其作为待确认建议 |
+| Python 版本未知 | 使用版本无关规则，版本专属结论标记为待确认 |
+| 单仓库同时包含 Java 和 Python 模块 | 按目标模块分别解析 Profile |
+| 已安装核心插件但未安装 Python 能力包 | 通用后端流程继续，明确 Python 专项能力缺失 |
+| 项目规范覆盖公共 Profile | 采用项目规范并保留来源 |
+| Profile 版本不匹配 | 停止加载冲突资料，不默认升级项目技术栈 |
+| 旧版 `project.json` | 正常读取，缺失字段按未知处理 |
+
+每阶段至少执行以下验证：
+
+- 静态校验：目录、frontmatter、引用路径、插件清单和契约格式。
+- 路由校验：语言、框架、版本、能力和回退选择符合项目证据。
+- 场景校验：使用真实或最小可运行项目执行目标 Skill。
+- 回归校验：现有 Java 和通用工作流的触发、权限及输出边界不退化。
+
+## 12. 风险与控制
+
+| 风险 | 控制措施 |
+| --- | --- |
+| Profile 过细导致安装和维护复杂 | 首期按语言聚合框架资料，有独立维护价值后再拆分 |
+| 核心 Skill 与语言包形成隐式强依赖 | 契约必须定义能力发现和缺失回退 |
+| 同一规则在多个位置重复 | 为契约、公共资料和项目规则分别指定唯一权威入口 |
+| 初始化误判技术栈 | 保存识别证据，冲突和低置信信息交由用户确认 |
+| 不同版本规则混用 | Profile 声明版本范围，未匹配时不加载版本专属结论 |
+| 多语言仓库被单一 Profile 覆盖 | 技术栈和 Profile 支持模块级绑定 |
+| 一次改造范围过大 | 先完成一个核心 Skill 的双语言闭环，再逐项迁移 |
+| 插件拆分破坏已有用户入口 | 先保持逻辑分层，物理拆分放到最后评估 |
+
+## 13. 总体验收标准
+
+- 核心工作流中不复制 Java、Python 等语言的完整流程。
+- Java 与 Python 能力包遵循同一 Profile 契约并可独立维护。
+- 初始化能基于证据选择语言、框架、工具和匹配版本。
+- 后端设计、实现、测试和审查能够读取当前模块对应能力。
+- 前端通过统一 API 契约与不同后端语言协作。
+- 公共技术知识和项目专属知识具有清晰边界及稳定入口。
+- 缺少语言插件、版本未知或能力不匹配时存在明确回退行为。
+- 现有项目画像和 Java 工作流可以兼容迁移。
+- 新增其他语言时只需实现能力契约，不需要复制核心工作流。
+
+## 14. 里程碑
+
+| 里程碑 | 交付结果 | 对应阶段 |
+| --- | --- | --- |
+| M1 契约成立 | Profile 契约通过 Java/Python 静态建模验证 | P0 |
+| M2 基准可用 | Java Profile 接入一个现有核心 Skill | P1 |
+| M3 Python 闭环 | FastAPI 项目完成设计、测试和审查最小链路 | P2 |
+| M4 初始化贯通 | 项目画像可以稳定选择 Java/Python Profile | P3 |
+| M5 工作流贯通 | 三个核心后端 Skill 支持双语言路由 | P4 |
+| M6 知识贯通 | 公共与项目知识可按语言、框架和版本检索 | P5 |
+| M7 可独立交付 | 完成插件拆分评估、回归和发布准备 | P6 |

.craftkit/knowledge/index.md

@@ -2,6 +2,8 @@
 
 当前没有已验证的项目知识。只收录有证据、适用范围明确且能够复用的技术决策与经验。
 
+长期知识按 `.craftkit/standards/document-maintenance.md` 保存审核状态并持续更新；过时或历史材料不得作为当前有效依据。
+
 - 问题经验按需建立在 `pitfalls/`，不预建空分类。
 - 重要技术决策按需建立在 `decisions/`。
 - 其他长期知识应优先并入已有主题，避免同义平行文档。

.craftkit/project.json

@@ -49,8 +49,16 @@
     "check": []
   },
   "documents": {
+    "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",

.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` 文档应完成处理，无法处理时列入延后清单并说明影响。

.craftkit/standards/index.md

@@ -1,3 +1,5 @@
 # 项目规范索引
 
-当前没有项目专属规范。新增规范时记录主题、适用范围、规则文件和优先级；未覆盖主题可由 `guidance` 查询中性公共基线。
+- [文档维护规范](document-maintenance.md)：正式需求、设计、规范和长期知识的创建、审核、更新、替代及任务关闭规则。
+
+新增规范时记录主题、适用范围、规则文件和优先级；未覆盖主题可由 `guidance` 查询中性公共基线。

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/<plugin>/skills/<skill>/
 - `.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/` 保存项目补充规则。

CHANGELOG.md

@@ -8,9 +8,29 @@
 
 ## [Unreleased]
 
+### Added
+
+- `knowledge:document-output` 增加 `register` 与 `close` 模式，使用 `workRoot/<task>/task.json` 记录任务状态、文件归属、可见性和关闭处置。
+- 增加“保留、沉淀、归档、删除、延后”五类关闭清单，以及共享文件逐项评审、断链检查和精确路径删除门禁。
+
 ### Planned
 
 - 建设 Skill 评测基线，支持固定场景、验收规则和更新前后回归比较。
+- 保持 `dev` 插件的通用设计、实现、测试和审查核心，不按 Java、Python、React 或 Vue 复制整套工作流；仅当专项能力具备独立安装、发布或维护需求时再评估拆分插件。
+- 补充 Python 专项支持，优先增加 `review-python`，并为现有后端实现与测试 Skill 建立 Python 版本、`pyproject.toml`、pytest、Ruff、mypy/pyright 及 FastAPI、Django、Flask 的按需资料路由。
+- 补充前端工程质量专项支持，增加 `test-frontend` 和 `review-typescript`，分别覆盖单元、组件与集成测试，以及 TypeScript 类型安全与模块契约。
+- 建立按项目真实依赖选择的语言与框架 profile，优先覆盖 Java、Python、React、Vue、Next.js、Nuxt 及相关构建、状态和测试工具；未确认精确版本时不默认最新版本，不跨版本混用规则。
+- 增加命令环境探测与指令适配辅助 Skill：识别操作系统、Shell/终端类型及版本、Codex 可用功能工具、命令行工具来源与版本，生成当前任务的环境能力快照，并按探测结果选择经过验证的默认指令；覆盖 PowerShell、Windows PowerShell、CMD、Bash、Zsh 等环境中的路径、引号、转义、编码、管道、退出码和标准输出/错误流差异。
+- 为 Git 建立版本与仓库状态 profile：根据 Git 版本选择 `checkout`、`switch`、`restore`、Worktree、分支跟踪和安全目录等命令形式，固定参数顺序并兼容含空格或非 ASCII 字符的路径与引用；复合操作按步骤检查退出码，区分“无输出的正常状态”、部分成功和真正失败，避免前置 `fetch` 失败后继续使用陈旧远端引用，也避免后置只读检查的非零退出码掩盖已经成功的写操作。
+- 为 Maven、JDK 和项目构建工具建立版本 profile：优先识别 Maven Wrapper、Maven/JDK 实际版本、`JAVA_HOME`、Toolchains、父 POM、模块结构、激活 profile、`settings.xml` 入口及仓库镜像，再选择全量或 `-pl`/`-am` 等聚焦构建命令；将 Maven 版本不兼容、JDK 不匹配、插件或父 POM 无法解析、缓存问题、编译失败和测试失败分类处理，不用重复执行同一命令代替诊断。
+- 增加私有 Git/Maven 仓库访问诊断与安全降级：区分沙箱或工具权限、VPN/内网、DNS、代理、TLS/证书、HTTP/HTTPS/SSH 协议、凭据助手、仓库镜像和服务端不可用等原因；只读取完成诊断所需的非敏感配置，不输出令牌、密码或完整凭据，访问受限时保留本地证据并明确远端引用或依赖缓存的新鲜度，获得既有授权后在正确执行环境重试。所有命令失败均输出已执行步骤、实际副作用、失败分类、可安全重试点、替代指令和验证结果。
+
+### Changed
+
+- `knowledge` 插件增加项目文档落盘配置能力；项目初始化写入 `documents.workRoot`、`documents.designRoot` 与 `documents.archiveRoot`，区分本地过程文档、共享设计和历史归档。
+- 需求、变更计划、技术设计与 Bug 分析 Skill 统一按项目文档配置选择任务目录；缺少配置时，过程文档回退到 `.craftkit/local/tasks/`，不再根据根目录说明文件推断落点。
+- 项目初始化增加文档生命周期默认策略；本地保留天数只用于提示，任务完成默认生成关闭预览，不自动删除文件。
+- 需求、计划、设计和分析 Skill 写入文档后登记本地任务记录；沉淀、交接、归档和 Worktree 清理按任务状态联动。
 
 ## [1.3.0] - 2026-08-31
 

README.md

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

WORKFLOW.md

@@ -88,7 +88,7 @@
 | S6 验证与自修复 | `test-backend`、`test-ui` | 分层验证记录、失败分类、修复结果 | 自动进入 S7 |
 | S7 代码审核 | `review-code`，按需叠加 `review-java`、`review-mybatis`、`review-frontend` | 审核报告、问题清单、未验证边界 | 自动修复明确问题后复审，进入 G4 |
 | S8 提交准备 | `commit-msg` | 精确文件范围、提交拆分与提交信息 | 进入审批门 G5 |
-| S9 本地提交与收尾 | Git 原生命令、`branch close` | 一个或多个本地提交、提交后状态、Worktree 清理结果 | 释放额外 Worktree 后输出最终交付报告 |
+| S9 本地提交与收尾 | Git 原生命令、`document-output close`、`branch close` | 本地提交、文档关闭清单、Worktree 清理结果 | 完成文档关闭门禁并释放额外 Worktree 后输出最终交付报告 |
 
 阶段不得仅凭名称跳过。确实不适用时，应记录“不适用”的证据和原因，再继续推进。
 
@@ -169,7 +169,7 @@
 6. 若项目上下文缺失，只在确有必要时提出 `init`；初始化写入仍遵守该 Skill 的确认步骤。
 7. 建立任务台账，至少记录任务编号、当前状态、输入、产物、审批记录、风险和下一动作。
 
-推荐将本次任务的本地运行状态保存到 `.craftkit/local/`；除非用户明确要求共享，不把运行状态写入可提交目录。
+推荐将本次任务的本地运行状态保存到 `documents.workRoot/<task>/task.json`；除非用户明确要求共享，不把运行状态写入可提交目录。任务记录至少登记状态、过程或共享产物、可见性、用途和关闭处置。
 
 ### S1：需求归集与落表
 
@@ -227,7 +227,7 @@
 
 设计产物应使用 `REQ-*` 关联需求，并为关键方案使用 `DES-*` 编号。数据库、API、前端和后端设计相互引用，不能产生字段、枚举、状态或错误语义冲突。
 
-若现有项目没有明确文档目录，智能体应在 G2 前提出建议路径并取得确认，不能自行制造固定目录约定。
+落盘前读取 `.craftkit/project.json` 的 `documents`：开发中的需求、计划、设计和验证记录使用 `workRoot`，用户明确要求共享或正式交付时使用 `designRoot`。缺少 `workRoot` 时回退到 `.craftkit/local/tasks/`；共享目录缺失或规则冲突时，在 G2 前提出建议路径并取得确认。`archiveRoot` 只用于另行授权的归档。
 
 ### S4：创建开发分支
 
@@ -313,12 +313,14 @@ G5 批准后：
 4. 确认无敏感文件、缓存、本地配置和无关改动；
 5. 使用批准的提交信息创建本地提交；
 6. 验证提交哈希、提交内容、当前分支和提交后工作区状态；
-7. 如果本次使用独立 Worktree，确认开发、验证和本地交付已完成，检查 Worktree 干净、无进行中的 Git 操作且 HEAD 已被本地分支引用；
-8. 展示准确清理路径、分支、HEAD 和 `git worktree remove` 命令，取得独立确认后使用 `branch close` 移除额外 Worktree；
-9. 验证 Worktree 目录和占用记录已移除、分支与提交仍存在、主工作区未变化；
-10. 输出最终交付报告。
+7. 将任务状态更新为 `ready_to_close`，使用 `document-output close` 生成“保留、沉淀、归档、删除、延后”清单；默认只预览，删除只处理用户确认的精确文件；
+8. 执行已确认的知识沉淀和文档归档，校验目标及引用，再完成已授权清理；存在延后项时保持未关闭状态并说明原因；
+9. 如果本次使用独立 Worktree，确认文档任务已经 `closed`，再检查 Worktree 干净、无进行中的 Git 操作且 HEAD 已被本地分支引用；
+10. 展示准确清理路径、分支、HEAD 和 `git worktree remove` 命令，取得独立确认后使用 `branch close` 移除额外 Worktree；
+11. 验证 Worktree 目录和占用记录已移除、分支与提交仍存在、主工作区未变化；
+12. 输出最终交付报告。
 
-最终报告至少包含：需求与设计产物路径、分支、提交哈希、实现摘要、验证结果、审核结论、未提交文件、未验证边界和后续建议。
+最终报告至少包含：需求与设计产物路径、分支、提交哈希、实现摘要、验证结果、审核结论、文档关闭状态、未提交文件、未验证边界和后续建议。
 
 ## 7. 阻塞与回退规则
 
@@ -439,6 +441,7 @@ G5 批准后：
 - 代码效果已通过 G4；
 - 提交范围与信息已通过 G5；
 - 本地提交已创建并核对内容；
+- 任务文档已生成关闭预览；已确认的沉淀、归档和删除均已验证，延后项已明确记录；
 - 使用独立 Worktree 时，其生命周期已经结束并安全移除；若用户明确要求保留现场，则任务状态应说明生命周期尚未结束及分支占用路径；
 - 未发生未经授权的 push、合并、发布、生产操作或历史改写。
 

plugins/dev/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dev",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "通用软件设计、编码、审查与测试工作流。",
   "author": {
     "name": "CraftKit"

plugins/dev/skills/analyze-bugs/SKILL.md

@@ -7,4 +7,6 @@ description: 分析 CSV、表格或结构化 Bug 清单，规范化字段、去
 
 以原始数据为证据，先识别编码、分隔符、字段含义和缺失值，再建立不改变原始文件的规范化视图。
 
-输出总量、状态、严重度、模块、时间和重复项统计，并区分数据事实、合理推断和待确认项。分类规则和时间范围必须透明；样本不足时不外推。默认只生成对话报告，用户要求落盘时确认格式与路径；不得自动修改 Bug 状态、分派人员或修复代码。
+输出总量、状态、严重度、模块、时间和重复项统计，并区分数据事实、合理推断和待确认项。分类规则和时间范围必须透明；样本不足时不外推。默认只生成对话报告；用户要求保存时读取 `.craftkit/project.json` 的 `documents` 配置，过程报告使用 `workRoot`，共享报告使用 `designRoot`。不得自动修改 Bug 状态、分派人员或修复代码。
+
+写入后在 `workRoot/<task>/task.json` 登记本次过程或共享文档；已有记录时保守合并，只更新本任务拥有的文件。登记结构遵循 `knowledge:document-output` 的生命周期规则，不修改项目级默认配置。

plugins/dev/skills/design-api/SKILL.md

@@ -13,6 +13,9 @@ description: 基于项目需求、现有契约和对应版本官方规范设计
 2. 明确资源、动作、幂等性、认证授权、输入、输出和错误语义。
 3. 方法、状态码、缓存、条件请求和重试语义以 [官方来源](references/sources.md) 及项目版本为依据。
 4. 输出路径与方法、参数位置、请求响应模型、错误、兼容、弃用和测试清单。
-5. 未确认的业务规则和框架封装列为待确认，不生成实现代码。
+5. 默认在对话中输出；用户要求保存设计文档时读取 `.craftkit/project.json` 的 `documents` 配置，过程设计使用 `workRoot`，共享设计使用 `designRoot`，不改变接口自身的路径设计。
+
+写入后在 `workRoot/<task>/task.json` 登记本次过程或共享文档；已有记录时保守合并，只更新本任务拥有的文件。登记结构遵循 `knowledge:document-output` 的生命周期规则，不修改项目级默认配置。
+6. 未确认的业务规则和框架封装列为待确认，不生成实现代码。
 
 项目规则高于公共建议；不得默认最新 OpenAPI 版本或把内部接口模式写成通用规则。

plugins/dev/skills/design-backend/SKILL.md

@@ -14,7 +14,9 @@ description: 基于需求、现有后端代码和项目规范设计模块边界
 3. 设计模块职责、调用关系、数据所有权、事务边界、并发策略、错误语义、权限和可观测性。
 4. 数据库或 HTTP 契约需要详细设计时，记录输入和待决项，交由相应专项 Skill；本 Skill 保持整体一致性。
 5. 按 [设计输出](references/output.md) 展示方案、备选项和风险，并用 [评审清单](references/review.md) 自检。
-6. 默认在对话中输出；用户要求落盘时，先确认项目约定路径并保守写入。
+6. 默认在对话中输出；用户要求落盘时读取 `.craftkit/project.json` 的 `documents` 配置，过程设计使用 `workRoot`，共享设计使用 `designRoot`，并保守写入。
+
+写入后在 `workRoot/<task>/task.json` 登记本次过程或共享文档；已有记录时保守合并，只更新本任务拥有的文件。登记结构遵循 `knowledge:document-output` 的生命周期规则，不修改项目级默认配置。
 
 ## 边界
 

plugins/dev/skills/design-db/SKILL.md

@@ -13,6 +13,7 @@ description: 根据业务数据、访问模式和目标数据库版本设计或
 2. 设计实体、关系、主键、约束、类型、索引和数据生命周期。
 3. 按 [官方来源](references/sources.md) 核实目标版本语法及行为，不跨数据库复制 DDL。
 4. 输出结构、约束、索引依据、迁移顺序、兼容、回滚和验证查询。
-5. 默认只给方案；执行 DDL、迁移存量数据或连接数据库需要单独授权。
+5. 用户要求保存设计说明时，读取 `.craftkit/project.json` 的 `documents` 配置选择过程或共享目录；可执行迁移文件仍沿用项目迁移工具约定。
+6. 默认只给方案；执行 DDL、迁移存量数据或连接数据库需要单独授权。
 
 未知容量、并发和查询模式应标为假设，不凭惯例制造审计字段或业务枚举。

plugins/dev/skills/design-frontend-data/SKILL.md

@@ -14,5 +14,8 @@ description: 设计前端请求边界、视图模型、状态所有权、缓存
 3. 设计加载、成功、空、错误、取消、重试、竞态、缓存失效和乐观更新行为。
 4. 按 [官方来源](references/sources.md) 核实浏览器请求和框架状态语义。
 5. 输出数据流、所有权、转换边界、并发策略、错误策略和测试点，不预设字段或请求封装。
+6. 用户要求保存设计文档时读取 `.craftkit/project.json` 的 `documents` 配置，过程设计使用 `workRoot`，共享设计使用 `designRoot`。
+
+写入后在 `workRoot/<task>/task.json` 登记本次过程或共享文档；已有记录时保守合并，只更新本任务拥有的文件。登记结构遵循 `knowledge:document-output` 的生命周期规则，不修改项目级默认配置。
 
 具体 API 字段映射交由 `prepare-api`，页面组合交由 `design-frontend`。

plugins/dev/skills/design-frontend/SKILL.md

@@ -14,7 +14,9 @@ description: 基于需求、现有前端代码和项目规范设计页面清单
 3. 按 [数据设计](references/data.md) 设计视图模型、状态所有权、加载与提交转换、错误和权限呈现。
 4. 组件、样式和表单结构分别复用 `component`、`style`、`form` 的证据与结论；本 Skill 负责页面级组合。
 5. API 契约需要映射时交由 `prepare-api`，并在设计中记录所需接口、字段和未决项。
-6. 按 [设计输出](references/output.md) 展示方案和风险；用户要求落盘时，先确认项目约定路径。
+6. 按 [设计输出](references/output.md) 展示方案和风险；用户要求落盘时读取 `.craftkit/project.json` 的 `documents` 配置，过程设计使用 `workRoot`，共享设计使用 `designRoot`。
+
+写入后在 `workRoot/<task>/task.json` 登记本次过程或共享文档；已有记录时保守合并，只更新本任务拥有的文件。登记结构遵循 `knowledge:document-output` 的生命周期规则，不修改项目级默认配置。
 
 ## 边界
 

plugins/dev/skills/design-workflow/SKILL.md

@@ -14,3 +14,4 @@ description: 基于项目现有流程引擎契约、业务状态和用户输入
 3. 设计业务事务与流程事务边界、幂等键、审计、通知和失败恢复。
 4. 需要过程建模时可参考 [官方来源](references/sources.md)，但必须映射回项目真实引擎能力。
 5. 输出状态转换表、时序、异常路径、接口需求、数据需求和验收场景；未确认规则列为待确认。
+6. 用户要求保存设计文档时，读取 `.craftkit/project.json` 的 `documents` 配置选择过程或共享目录；业务流程配置和脚本沿用项目源码约定。

plugins/dev/skills/plan-change/SKILL.md

@@ -14,11 +14,13 @@ description: 分析软件需求或问题的现状、影响范围、依赖顺序
 3. 确认当前行为、目标行为、范围外事项、依赖、兼容要求和验收标准。
 4. 根据任务类型读取 [新功能](references/feature.md)、[现有变更](references/change.md) 或 [缺陷与重构](references/fix.md)。
 5. 输出按依赖排序的步骤，每步包含目标、证据、修改范围、输入、产物、验证和停止条件。
-6. 默认在对话中展示；用户要求保存时，先确认项目约定的路径再写入。
+6. 默认在对话中展示；用户要求保存时读取 `.craftkit/project.json` 的 `documents` 配置，过程计划使用 `workRoot`，共享计划使用 `designRoot`，后续设计沿用同一任务目录。
+
+写入后在 `workRoot/<task>/task.json` 登记本次过程或共享文档；已有记录时保守合并，只更新本任务拥有的文件。登记结构遵循 `knowledge:document-output` 的生命周期规则，不修改项目级默认配置。
 
 ## 边界
 
-- 不使用固定模块编码、固定文档目录或不存在的下游 Skill 名称。
+- 不使用固定模块编码或不存在的下游 Skill 名称；文档默认落点允许由用户路径和项目配置覆盖。
 - 无法从源码确认的运行行为标为待验证，不把推断写成事实。
 - 计划应保护现有工作区，并把外部环境、数据迁移和发布验证与本地代码验证分开。
 - 用户要求直接实施且任务简单明确时，不额外制造计划文档。

plugins/dev/skills/prepare-api/SKILL.md

@@ -14,7 +14,9 @@ description: 对照前端需求或设计与现有 API 契约，整理接口清
 3. 按 [映射规则](references/mapping.md) 建立接口、请求、响应和双向类型转换映射。
 4. 分别列出已匹配、未匹配、冲突、缺失接口和需要后端或产品确认的事项。
 5. 按 [评审清单](references/review.md) 检查错误、分页、精度、时间、空值、权限和兼容风险。
-6. 默认在对话中输出；用户要求保存时，先确认项目约定路径再写入。
+6. 默认在对话中输出；用户要求保存时读取 `.craftkit/project.json` 的 `documents` 配置，过程映射使用 `workRoot`，共享映射使用 `designRoot`。
+
+写入后在 `workRoot/<task>/task.json` 登记本次过程或共享文档；已有记录时保守合并，只更新本任务拥有的文件。登记结构遵循 `knowledge:document-output` 的生命周期规则，不修改项目级默认配置。
 
 ## 边界
 

plugins/doc/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "doc",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "通用文档转换、表格提取、规则化归档与写作工具。",
   "author": {
     "name": "CraftKit"

plugins/doc/skills/archive/SKILL.md

@@ -27,6 +27,7 @@ python scripts/archive.py --root <project> --config <rules.json> --apply [--repo
 - 专有文档拆分逻辑改为通用 Markdown 标题章节抽取。
 - 内部数据库或服务校验改为显式 `requiredText` 内容校验；需要外部事实时由用户先提供结果，不隐式连接系统。
 - 来源专属元数据清理改为可选 `stripFrontmatter`，不会默认删除内容。
+- 历史归档保留当时快照并标明归档用途；它不作为当前有效依据。发现错误时增加勘误或当前版本链接，不静默改写历史内容。
 
 ## 安全边界
 
@@ -37,3 +38,5 @@ python scripts/archive.py --root <project> --config <rules.json> --apply [--repo
 - 规则不执行 Shell、SQL、模板代码或网络请求。
 
 完整配置见 `references/config.md`。
+
+当归档由任务关闭流程触发时，只复制 `task.json` 中标记为 `archive` 的文件。归档成功后将来源交回关闭流程重新分类；本 Skill 仍不删除来源，也不直接把来源标记为删除，实际删除只能由 `knowledge:document-output close` 按已确认清单执行。

plugins/doc/skills/archive/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Archive Documents（doc:archive）"
-  short_description: "按项目规则安全预演并归档文档"
+  short_description: "归档历史快照并关联当前有效版本"
   default_prompt: "使用 $archive 根据项目规则预演文档归档，确认后再执行写入。"

plugins/doc/skills/requirements/SKILL.md

@@ -7,4 +7,6 @@ description: 将技术说明、问题描述、会议材料或现有实现整理
 
 保留输入事实与来源，区分当前行为、期望行为、建议和待确认项。先识别角色、场景、触发条件、主流程、异常流程、数据、权限、兼容和范围外事项，再生成可测试的验收标准。
 
-技术实现细节只有在构成真实约束时才保留；不能从代码结构反推业务意图。冲突、模糊词、缺失规则和不可测试表述进入疑问清单。默认在对话中展示，用户确认后才写入项目文档。
+技术实现细节只有在构成真实约束时才保留；不能从代码结构反推业务意图。冲突、模糊词、缺失规则和不可测试表述进入疑问清单。默认在对话中展示；用户要求保存时先展示待确认内容，再读取 `.craftkit/project.json` 的 `documents` 配置，过程需求使用 `workRoot`，共享需求使用 `designRoot`。
+
+落盘前检索同主题的需求、设计、规范或知识，优先更新已有权威文档。共享长期文档新建或实质修改后按 `.craftkit/standards/document-maintenance.md` 更新审核状态；排版和错字修正不改变状态。`r`n`r`n写入后在 `workRoot/<task>/task.json` 登记本次创建、更新或引用的文档及 `relationship`；已有记录时保守合并。关联旧文档不转移所有权，也不产生删除权限；不修改项目级默认配置。

plugins/doc/skills/requirements/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "需求整理（doc:requirements）"
-  short_description: "将技术输入整理为可确认的需求说明"
-  default_prompt: "使用 $requirements 将这些材料整理成需求和疑问清单。"
+  short_description: "创建或更新可审核的需求说明"
+  default_prompt: "使用 $requirements 查找并更新已有需求，或将这些材料整理成新的需求和疑问清单。"

plugins/git/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "git",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "安全、可复核的通用 Git 工作流。",
   "author": {
     "name": "CraftKit"

plugins/git/skills/branch/references/worktree-branch.md

@@ -34,6 +34,8 @@ git worktree add -b "<branch>" "<absolute-worktree-path>" "<base>"
 - 当前 HEAD 已被预期本地分支引用；
 - 主仓库、worktree 路径、分支和 HEAD 均已准确确认。
 
+还要读取 `.craftkit/project.json` 的 `documents.workRoot`，检查该 Worktree 中与本分支任务对应的 `task.json` 和 ignored 文件。任务状态未到 `closed`、存在未登记的忽略文件或关闭清单尚未处理时，先执行 `knowledge:document-output close` 预览；用户要求保留现场时不得移除 Worktree。
+
 展示检查结果、移除后保留的分支和唯一清理命令，取得用户确认后执行：
 
 ```text

plugins/git/skills/integrate/references/worktree-lifecycle.md

@@ -56,6 +56,8 @@ git log --first-parent --oneline -20
 - 当前 HEAD 已被预期本地分支引用；
 - 用户不再要求保留现场。
 
+同时读取 `.craftkit/project.json` 的 `documents.workRoot`，检查与预集成任务对应的 `task.json` 和 ignored 文件。任务状态未到 `closed`、存在未登记的忽略文件或关闭清单尚未处理时，标记为 `cleanup-blocked`，先执行 `knowledge:document-output close` 预览。
+
 用户要求保留现场时标记为 `delivery-ready`，明确说明生命周期尚未结束以及分支仍被该 worktree 占用。
 
 ## 清理门禁

plugins/knowledge/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "knowledge",
-  "version": "0.3.1",
+  "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"],

plugins/knowledge/skills/distill/SKILL.md

@@ -23,6 +23,9 @@ description: 从当前任务和项目证据中提炼可复用结论、决策与
 - 使用项目相对路径，不记录凭据、个人信息和无必要的内部地址。
 - 指向源码或文档位置，不复制大段源码、日志或对话。
 - 新证据与既有结论冲突时暂停，交由 `lessons` 的维护规则处理，不能静默覆盖。
+- 写入前检索已有权威知识，优先修订原文。实质修改后按项目文档维护规范更新审核状态；替代旧内容时同步索引和 `replacedBy`。
 - 完成后报告实际写入、未采纳和未写入内容；Git 提交需要独立授权。
 
+当提炼由任务关闭流程触发时，读取对应 `task.json`，只处理标记为 `distill` 的文件。目标知识写入并校验后，将来源交回关闭流程重新分类；提炼失败或证据不足时改为 `defer`，不得直接把来源标记为删除。
+
 `distill` 不生成接续提示词、不维护当前任务交接文件；需要继续任务时使用 `handoff`。

plugins/knowledge/skills/document-output/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: document-output
+description: 查看、解释或维护项目文档落盘配置，登记任务文档，并在任务完成时预览和执行文档关闭。适用于调整路径或生命周期规则、确认文档归属、清理过程材料；普通开发 Skill 只需读取 project.json 时不应触发。
+---
+
+# 项目文档落盘
+
+本 Skill 维护 `.craftkit/project.json` 的 `documents` 配置、`workRoot/<task>/task.json` 任务记录和关闭门禁，不代替需求、设计或分析 Skill 生成文档内容，也不把对话输出自动转为文件。初次创建配置由 `knowledge:init` 完成。
+
+## 选择模式
+
+- `view`：解释当前路径、Git 可见性和生命周期策略。
+- `configure`：调整项目级 `documents` 配置。
+- `register`：创建或更新 `task.json`，登记本次新建、更新或引用的文档。
+- `close`：任务完成后分类预览、沉淀、归档并清理任务文档。
+
+执行 `register` 或 `close` 时读取[文档生命周期](references/lifecycle.md)。普通业务 Skill 可直接读取项目配置并按该引用中的最小字段更新 `task.json`，不需要递归调用本 Skill。
+
+长期文档的审核状态保存在文档自身；`task.json` 只记录当前任务关系。修改文档前先读取 `.craftkit/standards/document-maintenance.md`；项目尚未初始化时使用生命周期引用中的默认规则。
+
+## 路径选择
+
+1. 优先使用用户明确指定的路径；更新已有文档时延续其位置，不因新增默认值移动文件。
+2. 未指定路径时，读取 `.craftkit/project.json` 的 `documents` 配置及适用项目规范，区分过程文档和共享交付文档。
+3. 过程文档使用 `documents.workRoot/<task>/`，字段缺失或为空时回退到 `.craftkit/local/tasks/<task>/`。
+4. 用户明确要求共享或正式交付时使用 `documents.designRoot/<task>/`；字段缺失时先采用项目已明确约定的文档目录，否则建议 `.craftkit/designs/<task>/` 并确认共享用途。
+5. 归档只在用户要求时执行，读取 `documents.archiveRoot` 和归档规则；不能把归档根当成草稿输出目录。
+
+`<task>` 优先复用本次任务已有目录，否则取简短、稳定的主题名。计划与设计放在同一任务目录，后续阶段复用已有路径。不根据根目录存在 README、WORKFLOW 等说明文件推断过程文档也应放在根目录。
+
+## 写入与兼容
+
+- 配置路径相对当前项目根解析，使用正斜杠，不接受逃逸项目根的配置。显式用户路径按已有授权和环境权限处理。
+- 已授权保存且用途和路径可确定时，说明实际路径后直接写入，不重复索取路径确认；只有规则冲突、目标已有无关内容或共享用途不明时询问。
+- 更新前读取原文，保留无关内容；只创建实际需要的任务目录。格式和文件名优先延续已有任务文档。
+- 缺少配置时仅使用回退路径，不隐式初始化或补写 `project.json`。
+- 使用默认本地目录时检查 `.craftkit/local/` 的忽略状态；缺少忽略规则时指出缺口并给出最小补齐方案，不能把本地草稿作为普通提交候选。
+- 审批通过不代表共享、归档、提交或移动授权。共享设计不是已验证知识；只有经验证的可复用决策才按知识维护流程进入 `knowledge/decisions/`。
+- 交接仍使用交接 Skill 的 `.craftkit/local/handoff/` 或用户指定路径；不把交接、缓存、规范和设计目录混用。
+
+## 任务关闭
+
+`close` 先读取任务记录和实际文件，核对受影响长期文档的更新与审核状态，再输出“保留、沉淀、归档、删除、延后”五类清单。完成状态不产生删除授权；只有用户已经明确批准该清单时，才能删除列入“删除”的精确路径。删除后检查任务目录、引用、Git 状态和仍需保留的文件，再把任务状态更新为 `closed`。
+
+共享或已跟踪文件必须逐项评审。关闭过程不得删除 `.craftkit/local/config/`、凭据、个人配置、未登记文件或其他任务的文件；不确定归属时标记为“延后”。
+
+## 结果
+
+`view`、`configure` 和 `register` 返回用途、目标路径、选取依据、Git 状态及冲突。`close` 返回任务状态、五类清单、已执行动作和剩余文件。用户要求修改配置时，先展示 `.craftkit/project.json` 的精确差异，确认后保守写入；具体文档仍由获得保存授权的业务 Skill 写入。

plugins/knowledge/skills/document-output/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "项目文档落盘（knowledge:document-output）"
+  short_description: "管理文档落盘、审核状态、持续更新和任务关闭"
+  default_prompt: "使用 $document-output 查看或调整文档配置，登记任务文档，或检查更新与关闭状态。"

plugins/knowledge/skills/document-output/references/lifecycle.md

@@ -0,0 +1,131 @@
+# 文档生命周期
+
+## 分类维度
+
+文档同时具有可见性和生命周期，两者独立判断：
+
+| 可见性 | 位置 | Git 规则 |
+| --- | --- | --- |
+| 本地 | `workRoot`、`.craftkit/local/handoff/` | 必须被忽略 |
+| 共享 | `designRoot`、`.craftkit/knowledge/`、`.craftkit/handoff/` | 可作为普通项目资产评审和提交 |
+
+| 生命周期 | 典型内容 | 完成时处理 |
+| --- | --- | --- |
+| 过程 | 调研、计划、草稿、验证记录、临时报告 | 删除、延后或提炼后删除 |
+| 长期 | 生效设计、决策、规范、可复用知识 | 保留并维护引用 |
+| 归档 | 有审计或历史价值的完成态材料 | 通过 `doc:archive` 复制并验证 |
+
+共享不等于长期，长期也不等于必须归档。文件按真实用途逐项分类，不能只根据所在目录推断。
+
+## 长期文档状态
+
+正式需求、生效设计、项目规范和长期知识在文档自身保存 `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>/` 写入文档时创建 `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",
+      "relationship": "created",
+      "disposition": "review"
+    }
+  ]
+}
+```
+
+- `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 可见。
+
+## 状态流转
+
+```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. 核对任务完成证据、未完成事项和实际验证，并检查本次影响的长期文档已同步；需要作为当前依据的文档必须为 `approved`，决定是否进入 `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 历史可保留已提交文档的旧版本，但不能代替删除前的当前引用检查。
+- `pending` 或 `outdated` 的长期文档不能作为有效基线直接保留；不能及时处理时进入“延后”。
+
+## 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

@@ -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 忽略状态。
+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 步的统一预览。目录只按需创建，不因根目录已有说明文档就把根目录配置为过程文档目录。
+
 - 不读取或保存密码、令牌、私钥、完整数据库连接串和私有仓库认证信息。
 - 扫描配置文件时只提取框架、数据库类型、依赖标识等非秘密元数据；疑似凭据只报告位置和风险。
 - 参考项目只用于用户指定的结构、依赖、命名、测试、规范或工具范围，不复制业务代码和专属规则正文。

plugins/knowledge/skills/init/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Project Init（knowledge:init）"
-  short_description: "按成熟或空项目模式初始化 Agent 上下文与项目资料"
+  short_description: "初始化 Agent 上下文、项目资料和文档维护约定"
   default_prompt: "使用 $init 初始化当前项目，先判断成熟项目或空项目，并询问我是否有参考项目。"

plugins/knowledge/skills/init/assets/AGENTS.md

@@ -16,6 +16,8 @@
 - Agent 补充说明：`.craftkit/agents/index.md`
 - 项目规范：`.craftkit/standards/index.md`
 - 可复用知识：`.craftkit/knowledge/index.md`
+- 共享设计文档：`.craftkit/designs/`；开发中过程文档使用 `.craftkit/project.json` 配置的 `documents.workRoot`。
+- 文档维护规则：`.craftkit/standards/document-maintenance.md`；修改实现时检查并同步受影响的长期文档。
 
 ## 工作约束
 

plugins/knowledge/skills/init/assets/craftkit-README.md

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

plugins/knowledge/skills/init/assets/document-maintenance.md

@@ -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` 文档应完成处理，无法处理时列入延后清单并说明影响。

plugins/knowledge/skills/init/assets/knowledge-index.md

@@ -2,6 +2,8 @@
 
 当前没有已验证的项目知识。只收录有证据、适用范围明确且能够复用的技术决策与经验。
 
+长期知识按 `.craftkit/standards/document-maintenance.md` 保存审核状态并持续更新；过时或历史材料不得作为当前有效依据。
+
 - 问题经验按需建立在 `pitfalls/`，不预建空分类。
 - 重要技术决策按需建立在 `decisions/`。
 - 其他长期知识应优先并入已有主题，避免同义平行文档。

plugins/knowledge/skills/init/assets/project.json

@@ -12,7 +12,18 @@
     "documentation": []
   },
   "commands": { "build": [], "test": [], "check": [] },
-  "documents": { "archiveRoot": "docs/archive", "archiveRules": [] },
+  "documents": {
+    "workRoot": ".craftkit/local/tasks",
+    "designRoot": ".craftkit/designs",
+    "archiveRoot": "docs/archive",
+    "archiveRules": [],
+    "lifecycle": {
+      "onTaskComplete": "preview",
+      "localRetentionDays": 7,
+      "trackedFiles": "review-required",
+      "personalConfig": "retain"
+    }
+  },
   "guidance": {
     "agentIndex": ".craftkit/agents/index.md",
     "standardsIndex": ".craftkit/standards/index.md",

plugins/knowledge/skills/init/assets/standards-index.md

@@ -1,3 +1,5 @@
 # 项目规范索引
 
-当前没有项目专属规范。新增规范时记录主题、适用范围、规则文件和优先级；未覆盖主题可由 `guidance` 查询中性公共基线。
+- [文档维护规范](document-maintenance.md)：正式需求、设计、规范和长期知识的创建、审核、更新、替代及任务关闭规则。
+
+新增规范时记录主题、适用范围、规则文件和优先级；未覆盖主题可由 `guidance` 查询中性公共基线。

plugins/knowledge/skills/init/references/project-config.md

@@ -11,10 +11,33 @@
 - `dependencies.internal` 只记录用户确认可在当前仓库共享的依赖标识和用途。
 - `frontend` 记录前端框架、组件库、组件根和文档入口；路径必须是项目相对路径，版本必须有依赖清单、锁文件或用户确认作为证据。
 - `commands` 只记录经过项目文件或用户确认的命令。
-- `documents.archiveRoot` 记录可共享的文档归档根；`documents.archiveRules` 记录项目确认的匹配、目标模板、转换和校验规则，不写入公司固定目录或外部系统凭据。
+- `documents` 区分过程文档、共享设计和归档目录，字段及回退行为见下方“文档目录”；归档规则不写入公司固定目录或外部系统凭据。
 - `guidance` 指向 `.craftkit/` 内的索引入口。
 - `initialization.references` 记录参考项目名称、用途、允许提炼范围和可共享的相对位置。
 
+## 文档目录
+
+| 字段 | 默认值 | 用途 |
+| --- | --- | --- |
+| `workRoot` | `.craftkit/local/tasks` | 开发中的需求、计划、设计草稿和验证记录，默认不提交 |
+| `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` 时继续兼容读取；初始化更新时展示新增字段及用途，确认后保守合并。
+
 ## 前端组件信息
 
 - `frontend.framework` 引用 `technology.frameworks` 中已确认的前端框架名称。

plugins/knowledge/skills/lessons/SKILL.md

@@ -21,6 +21,8 @@ description: 初始化和维护 .craftkit 问题经验库，并按已确认的
 - 先读取适用的 `AGENTS.md`、`.craftkit/README.md`、知识索引和已有经验，不建立第二套经验目录。
 - 不预建空分类；条目较少时保持扁平，只有检索确有困难时才提议分类。
 - 已有条目、索引和用户章节保守合并，不整文件覆盖。
+- 新证据影响已有经验时更新原条目：未完成核实时标为 `outdated`，完成修订后按项目文档维护规范重新审核；不要另建冲突条目。
+- 条目被替代时更新知识索引和 `replacedBy`；历史价值需要保留时归档并指向当前条目。
 - 重命名、合并、删除、纠正和移动条目前展示影响并取得确认。
 - 不记录凭据、个人信息、机器绝对路径或大段源码与日志。
 - 写入完成后报告实际文件和未采纳建议；不自动暂存、提交或推送。

plugins/skill/.codex-plugin/plugin.json

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

plugins/skill/skills/guidance/SKILL.md

@@ -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 中写文件。

plugins/skill/skills/guidance/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Project Guidance（skill:guidance）"
-  short_description: "按索引渐进检索项目规范、中性公共基线及冲突依据"
-  default_prompt: "使用 $guidance 查找当前任务适用的项目规范，并给出可追溯依据。"
+  short_description: "检索当前有效规则并识别过时与历史材料"
+  default_prompt: "使用 $guidance 查找当前任务适用且有效的项目规范与知识，并给出可追溯依据。"