style(readme): 修正插件章节间距

.agents/plugins/marketplace.json

@@ -63,6 +63,42 @@
         "authentication": "ON_INSTALL"
       },
       "category": "Productivity"
+    },
+    {
+      "name": "profile",
+      "source": {
+        "source": "local",
+        "path": "./plugins/profile"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    },
+    {
+      "name": "java",
+      "source": {
+        "source": "local",
+        "path": "./plugins/java"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    },
+    {
+      "name": "python",
+      "source": {
+        "source": "local",
+        "path": "./plugins/python"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
     }
   ]
 }

.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,894 @@
+---
+reviewStatus: pending
+reviewedAt: null
+replacedBy: null
+---
+
+# 多语言插件架构设计与实施方案
+
+## 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 修改。
+- 未确认精确版本时不能默认最新版本，也不能跨主版本混用规则。
+
+### 2.4 已验证的平台能力
+
+本设计基于本机 Codex CLI 0.130.0、内置 `plugin-creator` 和 `skill-creator` 规范进行验证，结论如下：
+
+- 插件清单可以暴露插件内的 Skill 目录。
+- `agents/openai.yaml` 当前只支持声明 MCP 工具依赖，没有 Skill 依赖声明。
+- 当前没有标准接口让一个 Skill 在运行时枚举其他已安装插件、读取其物理目录或像函数一样调用另一个 Skill。
+- 当前会话可用 Skill 由 Codex 在会话开始时发现；新增或更新插件需要后续安装组合和新会话验证。
+
+因此，本文中的“请求能力”是 Agent 协作语义，不是 RPC 或函数调用。消费者根据当前会话已发现的提供方 Skill 获取专项资料；提供方读取自身资料并返回标准能力上下文。Profile 插件维护契约、匹配规则和校验器，不承担运行时扫描插件缓存。
+
+### 2.5 待验证边界
+
+- Repo marketplace 安装后，三个新插件能否在新会话中按名称稳定发现。
+- 多个版本的同一提供方同时存在时，Codex 暴露哪个版本。
+- 缺少提供方时，消费者对通用工作流的真实行为是否符合设计。
+- 提供方 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` 是契约和解析规则入口。消费者可在该 Skill 已发现时使用其匹配规则，但不能假设它能枚举或调用其他插件。它承担以下职责：
+
+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 负责读取自身资料，消费者不拼接用户缓存目录或其他插件安装路径。
+
+### 5.6 能力发现协议
+
+1. 消费者从当前会话公开的 Skill 清单判断提供方是否可用。
+2. 已发现对应提供方时，由 Agent 使用其 Profile Skill 获取能力上下文。
+3. 未发现提供方时返回 `missing`，继续执行核心通用流程。
+4. 提供方只读取自身 `references/manifest.json` 和资料，不读取其他插件目录。
+5. Profile 契约校验器在仓库开发和发布阶段校验提供方，不充当运行时注册中心。
+6. 逻辑标识出现在诊断结果中时，同时携带提供方、Skill 和资料用途；消费者不得把它转换为本机绝对路径。
+
+该协议避免核心插件依赖缓存目录，也避免把 Agent 的 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": ["Python"],
+    "frameworks": [
+      {
+        "name": "fastapi",
+        "version": "0.115.0",
+        "profile": "python/fastapi-0"
+      }
+    ],
+    "buildTools": [],
+    "databases": []
+  },
+  "modules": [
+    {
+      "id": "api",
+      "root": ".",
+      "kind": "backend",
+      "technology": {
+        "languages": [
+          {
+            "name": "python",
+            "version": "3.12",
+            "evidence": ["pyproject.toml"]
+          }
+        ],
+        "frameworks": [
+          {
+            "name": "fastapi",
+            "version": "0.115.0",
+            "evidence": ["uv.lock"]
+          }
+        ],
+        "preferredProfiles": ["python/default", "python/fastapi-0"]
+      }
+    }
+  ],
+  "commands": {
+    "build": [],
+    "test": ["uv run pytest"],
+    "check": ["uv run ruff check ."]
+  }
+}
+```
+
+### 6.2 字段规则
+
+- 顶层 `technology` 保持 Schema 1 的字段类型，作为旧消费者可读取的仓库概要。
+- `modules[].technology` 记录模块级语言、框架、精确版本、证据和 Profile 偏好。
+- `modules` 描述多模块仓库中的技术边界；单模块项目仍生成一个根模块。
+- `modules[].preferredProfiles` 记录项目确认的 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` 版本路由 | 按目标模块读取当前会话已发现的提供方 | 旧文档改为契约说明入口 |
+| `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,60 @@
+---
+reviewStatus: pending
+reviewedAt: null
+replacedBy: null
+---
+
+# 多语言插件架构改造计划
+
+## 1. 文档职责
+
+本文只跟踪多语言插件架构的实施批次、前置依赖、验证门禁和完成状态。架构、契约、项目画像及运行机制以[《多语言插件架构设计与实施方案》](MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-DESIGN.md)为唯一依据。
+
+详细执行记录位于 `.craftkit/local/tasks/multi-language-plugin/`，不在本文复制过程步骤。
+
+## 2. 当前决策
+
+- 首期建立 `profile`、`java` 和 `python` 独立插件骨架，但在安装组合通过前不声明可独立交付。
+- Profile 插件维护静态契约、匹配规则和校验器，不扫描插件缓存，也不把 Skill 协作描述为函数调用。
+- 消费者从当前会话已发现的提供方 Skill 获取专项能力；提供方缺失时执行通用回退。
+- `knowledge:init` 是项目画像的唯一写入者，`guidance` 是项目规则与公共规则的合并入口。
+- Schema 2 先由消费者双读，再由初始化入口写入。
+- 插件安装状态不进入共享项目画像。
+
+## 3. 实施批次
+
+| 批次 | 目标 | 前置依赖 | 核心产物 | 状态 |
+| --- | --- | --- | --- | --- |
+| P0 | 收敛文档并验证平台机制 | 无 | 架构决策、最小插件骨架、验证记录 | 已完成（运行时验证转 P6） |
+| P1 | 建立 Profile 静态契约 | P0 | JSON Schema、解析规则、校验器 | 已完成 |
+| P2 | 建立 Java/Python 最小提供方 | P1 | 双提供方 manifest 和专项资料 | 已完成静态实现 |
+| P3 | 接入首个核心消费者 | P2 | `design-backend` 双语言路由 | 已完成实现，待新会话验证 |
+| P4 | 建立 Schema 1/2 双读 | P3 | 模块级画像、迁移与回滚规则 | 已完成实现 |
+| P5 | 逐个接入核心消费者 | P4 | 设计、实现、测试、审查闭环 | 已完成实现，待新会话验证 |
+| P6 | 验证独立安装和发布 | P5 | 安装矩阵、兼容矩阵、发布材料 | 部分完成，运行时验证待处理 |
+| P7 | 按需求扩展框架和前端 | P6 | 可独立验证的增量能力 | 待执行 |
+
+## 4. 阶段门禁
+
+每个批次必须分别记录：
+
+1. 实际修改范围。
+2. 静态校验结果。
+3. 真实或最小可运行场景验证结果。
+4. 未验证边界。
+5. 停止条件检查。
+6. 是否允许进入下一批次。
+
+静态清单或脚本校验通过不代表 Codex 运行时行为已经验证。跨插件发现、Skill 激活和缺失回退必须在安装后的新会话中验证。
+
+## 5. 总体验收
+
+- Java 与 Python 提供方遵循同一契约。
+- 核心 Skill 不复制语言专属工作流。
+- Schema 1 和 Schema 2 均可读取。
+- 多模块仓库按目标路径解析技术栈。
+- 缺少提供方、版本未知和版本不兼容都有确定回退。
+- 项目规范覆盖公共 Profile 时保留双方来源。
+- Spring Boot 和 FastAPI 完成同一请求的端到端对照。
+- 核心、Profile、Java 和 Python 的安装组合全部验证。
+- 现有 Java 与通用工作流没有回归。

.craftkit/knowledge/index.md

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

.craftkit/project.json

@@ -30,7 +30,10 @@
       "plugins/doc",
       "plugins/git",
       "plugins/knowledge",
-      "plugins/skill"
+      "plugins/skill",
+      "plugins/profile",
+      "plugins/java",
+      "plugins/python"
     ]
   },
   "dependencies": {
@@ -49,8 +52,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,37 @@
 
 ## [Unreleased]
 
+### Added
+
+- `knowledge:document-output` 增加 `register` 与 `close` 模式，使用 `workRoot/<task>/task.json` 记录任务状态、文件归属、可见性和关闭处置。
+- 增加“保留、沉淀、归档、删除、延后”五类关闭清单，以及共享文件逐项评审、断链检查和精确路径删除门禁。
+- 增加长期文档 `pending`、`approved`、`outdated` 审核状态，以及项目级文档持续维护规范。
+- 增加 `profile`、`java` 和 `python` 插件骨架，以统一契约提供多语言技术能力。
+- 增加 Profile manifest、版本范围、能力状态、引用安全规则和标准库校验器。
+- 增加 `python:review-python`，按项目版本审查类型、异常、资源、异步、事务和测试隔离问题。
+
 ### Planned
 
 - 建设 Skill 评测基线，支持固定场景、验收规则和更新前后回归比较。
+- 保持 `dev` 插件的通用设计、实现、测试和审查核心，不按 Java、Python、React 或 Vue 复制整套工作流；仅当专项能力具备独立安装、发布或维护需求时再评估拆分插件。
+- 补充前端工程质量专项支持，增加 `test-frontend` 和 `review-typescript`，分别覆盖单元、组件与集成测试，以及 TypeScript 类型安全与模块契约。
+- 增加命令环境探测与指令适配辅助 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 清理按任务状态联动。
+- 需求与设计 Skill 优先更新已有权威文档；实现、升级和代码审核流程检查留存文档是否因代码或契约变化而需要同步。
+- `task.json` 使用 `created`、`updated`、`referenced` 区分任务关系，关联旧文档不转移所有权，也不产生删除权限。
+- README 的 Skill 说明同步覆盖文档创建、审核、持续更新、历史归档和关闭职责。
+- `design-backend`、`implement-backend`、`test-backend` 和 `review-java` 接入可选语言 Profile，并在提供方缺失时保留通用回退。
+- 项目画像模板升级到 Schema 2，保留顶层兼容概要并支持模块级技术栈；插件安装状态不写入共享画像。
+- 多语言架构文档收敛为单一设计依据和阶段跟踪计划，并记录 Codex 当前没有 Skill 运行时依赖接口的约束。
 
 ## [1.3.0] - 2026-08-31
 

README.md

@@ -13,6 +13,12 @@ CraftKit 是面向 Codex 的通用插件工具集，覆盖软件开发、文档
 - [新项目初始化与应用拆分工作流](NEW-PROJECT-INITIALIZATION-AND-APPLICATION-SPLIT.md)：适用于空目录、新仓库或尚未形成有效源码结构的项目。
 - [已有项目初始化与应用拆分工作流](EXISTING-PROJECT-INITIALIZATION-AND-APPLICATION-SPLIT.md)：适用于已有源码、数据、接口和部署形态，需要基于现状渐进拆分的项目。
 
+## 文档维护流程
+
+CraftKit 按“初始化约定 → 创建或更新 → 审核生效 → 随实现持续维护 → 关闭时分类处置”管理项目文档。过程材料默认保存在本地任务目录；正式需求、生效设计、项目规范和长期知识保存审核状态，后续任务优先更新已有权威文档。
+
+长期文档使用 `pending`、`approved`、`outdated` 表示待审核、当前有效和已知过期。任务关闭不结束文档维护；实现、接口、数据模型或业务行为变化时，需要检查并同步相关留存文档。详细规则由项目 `.craftkit/standards/document-maintenance.md` 维护。
+
 ## 插件组成
 
 | 插件 | 用途 |
@@ -22,6 +28,9 @@ CraftKit 是面向 Codex 的通用插件工具集，覆盖软件开发、文档
 | `git` | 分支、提交、变更提取、集成与发布准备 |
 | `knowledge` | 项目初始化、任务交接、问题复盘与经验维护 |
 | `skill` | 项目规范检索、维护与 Skill 辅助工具 |
+| `profile` | 多语言技术能力契约、匹配规则与静态校验 |
+| `java` | Java、构建工具与 Spring 技术能力资料 |
+| `python` | Python、包管理、FastAPI、测试与专项审查资料 |
 
 ## Skill 介绍
 
@@ -31,20 +40,20 @@ CraftKit 是面向 Codex 的通用插件工具集，覆盖软件开发、文档
 
 | Skill | 用途 |
 | --- | --- |
-| `plan-change` | 分析需求或问题的影响范围、依赖、风险和验证方式，形成可执行的变更计划。 |
+| `plan-change` | 分析影响范围并创建或更新可执行的变更计划，登记关联文档。 |
-| `design-backend` | 设计后端模块边界、服务职责、事务、错误处理及数据影响。 |
+| `design-backend` | 创建或更新后端设计，覆盖模块边界、事务、错误处理及数据影响。 |
-| `design-frontend` | 设计前端页面、路由、状态、交互、组件组合和数据流。 |
+| `design-frontend` | 创建或更新前端设计，覆盖页面、路由、状态、交互和数据流。 |
-| `design-api` | 设计或评审 HTTP API 的资源、方法、状态码和请求响应契约。 |
+| `design-api` | 创建、更新或评审 HTTP API 契约，并维护其审核状态。 |
-| `design-db` | 设计或评审数据库表、约束、索引及变更与回滚方案。 |
+| `design-db` | 创建、更新或评审数据设计及变更与回滚方案。 |
 | `design-frontend-data` | 设计前端请求边界、视图模型、状态所有权、缓存和并发处理。 |
 | `design-workflow` | 设计业务流程的任务、状态转换、权限、回退、撤回和审计规则。 |
 | `prepare-api` | 整理前后端接口清单、字段映射、类型转换、缺失项和联调风险。 |
 | `component` | 根据项目依赖和现有用法选择组件，查证 props、events 和 slots。 |
 | `form` | 设计或检查表单分组、布局、条件字段、错误展示和可访问性。 |
 | `style` | 根据项目视觉基线设计颜色、排版、间距、主题和响应式样式。 |
-| `implement-backend` | 按项目语言、框架和规范编写或修改后端代码。 |
+| `implement-backend` | 修改后端代码，并同步检查受影响的需求、设计、规范和知识。 |
-| `implement-frontend` | 按项目框架、组件契约和请求封装编写或修改前端代码。 |
+| `implement-frontend` | 修改前端代码，并同步检查受影响的需求、设计、规范和知识。 |
-| `review-code` | 审查工作区、提交或分支变更中的正确性、兼容、安全、性能和测试问题。 |
+| `review-code` | 审查代码质量，以及实现与当前有效文档的一致性。 |
 | `review-java` | 专项评审 Java 代码的资源管理、并发、异常和可维护性。 |
 | `review-mybatis` | 专项评审 Mapper、动态 SQL、参数映射、事务边界和查询性能。 |
 | `review-frontend` | 专项评审前端组件边界、状态、渲染、交互、可访问性和性能。 |
@@ -64,8 +73,8 @@ CraftKit 是面向 Codex 的通用插件工具集，覆盖软件开发、文档
 | `md-to-docx` | 将 Markdown 转换为可编辑的 Word `.docx` 文档。 |
 | `xlsx-to-md` | 将 Excel `.xlsx` 工作簿按工作表转换为 Markdown 表格。 |
 | `format-md` | 修正 Markdown 的标题、空行、列表、代码块、表格和链接格式。 |
-| `archive` | 按明确规则复制、重命名、清理或拆分项目文档并生成报告。 |
+| `archive` | 按明确规则归档历史快照，保留勘误和当前版本链接。 |
-| `requirements` | 将技术说明、会议材料或问题描述整理成可确认的需求说明。 |
+| `requirements` | 创建或更新可审核的需求说明，避免产生冲突的平行文档。 |
 | `report` | 根据事实、Git 记录和任务状态撰写工作汇报或阶段总结。 |
 | `message` | 根据事件、受众和行动要求起草通知、提醒、确认或故障沟通消息。 |
 
@@ -88,10 +97,11 @@ CraftKit 是面向 Codex 的通用插件工具集，覆盖软件开发、文档
 
 | Skill | 用途 |
 | --- | --- |
-| `init` | 初始化或更新项目的 `AGENTS.md` 与 `.craftkit/` 项目资料。 |
+| `init` | 初始化或更新项目上下文、文档目录和持续维护约定。 |
+| `document-output` | 管理文档落盘、任务关联、审核状态、持续更新和关闭处置。 |
 | `handoff` | 生成可持续更新的任务交接文档和新任务接续提示词。 |
-| `distill` | 从任务证据中提炼可复用结论、决策和问题经验。 |
+| `distill` | 从任务证据提炼知识，并更新、替代或标记已有结论。 |
-| `lessons` | 初始化、维护和审计项目问题经验库。 |
+| `lessons` | 初始化、修订、标记过时和审计项目问题经验库。 |
 | `trace` | 复盘 Agent 的偏离、漏读或规则失效，并提出改进建议。 |
 | `worklog` | 根据指定日期、时区和作者的 Git 提交生成工作日志。 |
 
@@ -101,9 +111,18 @@ CraftKit 是面向 Codex 的通用插件工具集，覆盖软件开发、文档
 
 | Skill | 用途 |
 | --- | --- |
-| `guidance` | 检索项目协作说明、项目资料和公共基线，返回可追溯的规则、冲突与缺口。 |
+| `guidance` | 检索当前有效的项目规则和知识，区分待审核、过时与历史材料。 |
 | `guidance-edit` | 建立、检查和维护 `.craftkit/standards/` 规范索引。 |
 
+### Profile、Java 与 Python
+
+- `profile:resolve`：根据目标模块、项目事实和当前会话已发现的提供方解析技术能力；缺失时返回明确回退。
+- `java:profile`：提供 Java、Maven/Gradle、Spring 设计、命令和审查资料。
+- `python:profile`：提供 Python、包管理、FastAPI、实现、测试和审查资料。
+- `python:review-python`：按项目版本专项审查 Python 类型、异常、资源、异步、事务和测试隔离问题。
+
+跨插件逻辑标识只用于诊断。各提供方读取自身资料，核心 Skill 不扫描用户插件缓存；项目规范仍由 `guidance` 合并。
+
 ## 目录结构
 
 ```text
@@ -123,7 +142,10 @@ CraftKit/
 │  ├─ doc/
 │  ├─ git/
 │  ├─ knowledge/
-│  └─ skill/
+│  ├─ skill/
+│  ├─ profile/
+│  ├─ java/
+│  └─ python/
 └─ README.md
 ```
 
@@ -137,6 +159,6 @@ CraftKit/
 
 ## 本地使用
 
-本仓库提供仓库级 marketplace。将仓库注册为本地 marketplace 后，可按需安装 `dev`、`doc`、`git`、`knowledge` 或 `skill` 插件。
+本仓库提供仓库级 marketplace。将仓库注册为本地 marketplace 后，可按需安装 `dev`、`doc`、`git`、`knowledge`、`skill`、`profile`、`java` 或 `python` 插件。
 
 正式公开发布前，还需补充许可证、公开仓库地址、作者信息、隐私政策和市场素材。

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 后输出最终交付报告 |
 
 阶段不得仅凭名称跳过。确实不适用时，应记录“不适用”的证据和原因，再继续推进。
 
@@ -163,17 +163,17 @@
 
 1. 确定项目根目录和需求材料范围。
 2. 读取所有适用的 `AGENTS.md`。
-3. 检查 `.craftkit/project.json`、规范索引、构建文件、依赖锁文件和主要源码目录。
+3. 检查 `.craftkit/project.json`、规范索引、文档维护规范、构建文件、依赖锁文件和主要源码目录。
 4. 使用 `guidance` 获取本任务适用的项目规则，并区分明确规则、公共建议和代码现状。
 5. 执行只读 Git 检查，记录当前分支、HEAD、工作树状态、远程引用现状和 worktree 占用情况。
 6. 若项目上下文缺失，只在确有必要时提出 `init`；初始化写入仍遵守该 Skill 的确认步骤。
 7. 建立任务台账，至少记录任务编号、当前状态、输入、产物、审批记录、风险和下一动作。
 
-推荐将本次任务的本地运行状态保存到 `.craftkit/local/`；除非用户明确要求共享，不把运行状态写入可提交目录。
+推荐将本次任务的本地运行状态保存到 `documents.workRoot/<task>/task.json`；除非用户明确要求共享，不把运行状态写入可提交目录。任务记录至少登记状态、过程或共享产物、可见性、用途和关闭处置。
 
 ### S1：需求归集与落表
 
-使用 `requirements` 处理原始需求。输入可以是完整需求文档，也可以是聊天记录、口头描述转写、邮件、会议纪要、Bug 描述、截图文字或零散技术说明。
+使用 `requirements` 处理原始需求。先检索同主题的现有需求并更新权威文档；只有不存在可维护的当前文档时才新建。输入可以是完整需求文档，也可以是聊天记录、口头描述转写、邮件、会议纪要、Bug 描述、截图文字或零散技术说明。
 
 需求文档至少包含：
 
@@ -227,7 +227,9 @@
 
 设计产物应使用 `REQ-*` 关联需求，并为关键方案使用 `DES-*` 编号。数据库、API、前端和后端设计相互引用，不能产生字段、枚举、状态或错误语义冲突。
 
-若现有项目没有明确文档目录，智能体应在 G2 前提出建议路径并取得确认，不能自行制造固定目录约定。
+设计前检索相关已有文档，优先更新当前权威设计。共享长期文档的新建或实质修改应进入 `pending`；G2 批准可作为审核依据，将其更新为 `approved`。旧文档被替代时同步索引、引用和替代关系。
+
+落盘前读取 `.craftkit/project.json` 的 `documents`：开发中的需求、计划、设计和验证记录使用 `workRoot`，用户明确要求共享或正式交付时使用 `designRoot`。缺少 `workRoot` 时回退到 `.craftkit/local/tasks/`；共享目录缺失或规则冲突时，在 G2 前提出建议路径并取得确认。`archiveRoot` 只用于另行授权的归档。
 
 ### S4：创建开发分支
 
@@ -250,6 +252,7 @@
 - 延续现有目录、命名、注释、异常、日志、事务、组件、请求和测试风格；
 - 追踪真实入口、调用方和数据落点；
 - 只实现批准范围内的最小完整变更；
+- 检查接口、数据模型、业务行为和验证结论变化是否影响已有需求、设计、规范或知识，同步更新受影响的权威文档；
 - 在代码和测试映射中引用相关 `REQ-*`、`DES-*`，但不为追踪编号制造不符合项目风格的代码注释；
 - 不虚构内部依赖、组件属性、接口、数据库行为或业务校验；
 - 不修改凭据、部署参数和生产配置；
@@ -288,6 +291,7 @@
 - 正确性、兼容、安全、性能、并发、事务、权限和数据风险；
 - 测试充分性和未验证边界；
 - staged、unstaged 和 untracked 的准确区分。
+- 实现与当前有效文档的一致性，以及本次影响的长期文档是否已经同步；待审核、过时和历史材料不能冒充当前基线。
 
 对于审核发现：
 
@@ -313,12 +317,14 @@ G5 批准后：
 4. 确认无敏感文件、缓存、本地配置和无关改动；
 5. 使用批准的提交信息创建本地提交；
 6. 验证提交哈希、提交内容、当前分支和提交后工作区状态；
-7. 如果本次使用独立 Worktree，确认开发、验证和本地交付已完成，检查 Worktree 干净、无进行中的 Git 操作且 HEAD 已被本地分支引用；
+7. 将任务状态更新为 `ready_to_close`，使用 `document-output close` 生成“保留、沉淀、归档、删除、延后”清单；默认只预览，删除只处理用户确认的精确文件；
-8. 展示准确清理路径、分支、HEAD 和 `git worktree remove` 命令，取得独立确认后使用 `branch close` 移除额外 Worktree；
+8. 执行已确认的知识沉淀和文档归档，校验目标及引用，再完成已授权清理；存在延后项时保持未关闭状态并说明原因；
-9. 验证 Worktree 目录和占用记录已移除、分支与提交仍存在、主工作区未变化；
+9. 如果本次使用独立 Worktree，确认文档任务已经 `closed`，再检查 Worktree 干净、无进行中的 Git 操作且 HEAD 已被本地分支引用；
-10. 输出最终交付报告。
+10. 展示准确清理路径、分支、HEAD 和 `git worktree remove` 命令，取得独立确认后使用 `branch close` 移除额外 Worktree；
+11. 验证 Worktree 目录和占用记录已移除、分支与提交仍存在、主工作区未变化；
+12. 输出最终交付报告。
 
-最终报告至少包含：需求与设计产物路径、分支、提交哈希、实现摘要、验证结果、审核结论、未提交文件、未验证边界和后续建议。
+最终报告至少包含：需求与设计产物路径、分支、提交哈希、实现摘要、验证结果、审核结论、文档关闭状态、未提交文件、未验证边界和后续建议。
 
 ## 7. 阻塞与回退规则
 
@@ -439,6 +445,8 @@ G5 批准后：
 - 代码效果已通过 G4；
 - 提交范围与信息已通过 G5；
 - 本地提交已创建并核对内容；
+- 本次影响的长期文档已同步，需要作为当前依据的文档审核状态为 `approved`；
+- 任务文档已生成关闭预览；已确认的沉淀、归档和删除均已验证，延后项已明确记录；
 - 使用独立 Worktree 时，其生命周期已经结束并安全移除；若用户明确要求保留现场，则任务状态应说明生命周期尚未结束及分支占用路径；
 - 未发生未经授权的 push、合并、发布、生产操作或历史改写。
 

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

@@ -1,6 +1,6 @@
 {
   "name": "dev",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "通用软件设计、编码、审查与测试工作流。",
   "author": {
     "name": "CraftKit"
@@ -9,7 +9,7 @@
   "interface": {
     "displayName": "Dev",
     "shortDescription": "软件设计、编码、审查与测试工具",
-    "longDescription": "提供基于项目实际技术栈的设计、实现、审查、测试、升级与估算工作流。",
+    "longDescription": "提供基于项目实际技术栈的设计、实现、文档同步、审查、测试、升级与估算工作流。",
     "developerName": "CraftKit",
     "category": "Productivity",
     "capabilities": ["Read", "Write"],

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

@@ -7,4 +7,6 @@ description: 分析 CSV、表格或结构化 Bug 清单，规范化字段、去
 
 以原始数据为证据，先识别编码、分隔符、字段含义和缺失值，再建立不改变原始文件的规范化视图。
 
-输出总量、状态、严重度、模块、时间和重复项统计，并区分数据事实、合理推断和待确认项。分类规则和时间范围必须透明；样本不足时不外推。默认只生成对话报告，用户要求落盘时确认格式与路径；不得自动修改 Bug 状态、分派人员或修复代码。
+输出总量、状态、严重度、模块、时间和重复项统计，并区分数据事实、合理推断和待确认项。分类规则和时间范围必须透明；样本不足时不外推。默认只生成对话报告；用户要求保存时读取 `.craftkit/project.json` 的 `documents` 配置，过程报告使用 `workRoot`，共享报告使用 `designRoot`。不得自动修改 Bug 状态、分派人员或修复代码。
+
+落盘前检索同主题的需求、设计、规范或知识，优先更新已有权威文档。共享长期文档新建或实质修改后按 `.craftkit/standards/document-maintenance.md` 更新审核状态；排版和错字修正不改变状态。`r`n`r`n写入后在 `workRoot/<task>/task.json` 登记本次创建、更新或引用的文档及 `relationship`；已有记录时保守合并。关联旧文档不转移所有权，也不产生删除权限；不修改项目级默认配置。

plugins/dev/skills/component/SKILL.md

@@ -13,7 +13,7 @@ description: 根据当前项目的真实依赖、已有用法和可验证契约
 2. 按 [选型规则](references/selection.md) 比较复用、扩展和新建方案。
 3. 按 [证据规则](references/evidence.md) 查证组件契约及版本兼容性。
 4. 输出推荐组件、适用理由、契约摘要、替代方案、缺口和风险。
-5. 用户需要持续复用扫描结果时，按 [组件索引](references/index.md) 展示拟新增或更新内容；确认后写入 `.craftkit/standards/frontend/components.md`。
+5. 用户需要持续复用扫描结果时，按 [组件索引](references/index.md) 展示拟新增或更新内容；确认后更新已有 `.craftkit/standards/frontend/components.md`，并按项目文档维护规范处理审核状态。
 6. 如证据不足，说明缺少的材料并询问用户，不代替后续页面实现 Skill 编写完整页面。
 
 项目没有 `.craftkit/project.json` 时，继续检查真实依赖和现有代码；只有缺失信息会改变结论时才询问用户。

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`，不改变接口自身的路径设计。
+
+落盘前检索同主题的需求、设计、规范或知识，优先更新已有权威文档。共享长期文档新建或实质修改后按 `.craftkit/standards/document-maintenance.md` 更新审核状态；排版和错字修正不改变状态。`r`n`r`n写入后在 `workRoot/<task>/task.json` 登记本次创建、更新或引用的文档及 `relationship`；已有记录时保守合并。关联旧文档不转移所有权，也不产生删除权限；不修改项目级默认配置。
+6. 未确认的业务规则和框架封装列为待确认，不生成实现代码。
 
 项目规则高于公共建议；不得默认最新 OpenAPI 版本或把内部接口模式写成通用规则。

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

@@ -10,15 +10,21 @@ description: 基于需求、现有后端代码和项目规范设计模块边界
 ## 工作流
 
 1. 读取需求、项目元数据、适用规范、依赖清单和相关后端实现，确认语言、框架及精确版本。
-2. 按 [范围分析](references/scope.md) 明确现状、边界、参与者和约束。
+2. 按 [Profile 消费规则](references/profile-consumption.md) 确定目标模块和 `backend-design` 能力；提供方缺失时继续使用中性流程并报告缺口。
-3. 设计模块职责、调用关系、数据所有权、事务边界、并发策略、错误语义、权限和可观测性。
+3. 按 [范围分析](references/scope.md) 明确现状、边界、参与者和约束。
-4. 数据库或 HTTP 契约需要详细设计时，记录输入和待决项，交由相应专项 Skill；本 Skill 保持整体一致性。
+4. 设计模块职责、调用关系、数据所有权、事务边界、并发策略、错误语义、权限和可观测性。
-5. 按 [设计输出](references/output.md) 展示方案、备选项和风险，并用 [评审清单](references/review.md) 自检。
+5. 数据库或 HTTP 契约需要详细设计时，记录输入和待决项，交由相应专项 Skill；本 Skill 保持整体一致性。
-6. 默认在对话中输出；用户要求落盘时，先确认项目约定路径并保守写入。
+6. 按 [设计输出](references/output.md) 展示方案、备选项和风险，并用 [评审清单](references/review.md) 自检。
+7. 默认在对话中输出；用户要求落盘时读取 `.craftkit/project.json` 的 `documents` 配置，过程设计使用 `workRoot`，共享设计使用 `designRoot`，并保守写入。
+
+落盘前检索同主题的需求、设计、规范或知识，优先更新已有权威文档。共享长期文档新建或实质修改后按 `.craftkit/standards/document-maintenance.md` 更新审核状态；排版和错字修正不改变状态。
+
+写入后在 `workRoot/<task>/task.json` 登记本次创建、更新或引用的文档及 `relationship`；已有记录时保守合并。关联旧文档不转移所有权，也不产生删除权限；不修改项目级默认配置。
 
 ## 边界
 
 - 已安装 `guidance` 时用它获取项目规则；未安装时按“目标目录适用的 `AGENTS.md` → `.craftkit/agents/index.md` → `.craftkit/standards/index.md` → 命中正文”的顺序手工读取。不存在的规范、框架能力和依赖接口不得猜测。
 - 版本从 `.craftkit/project.json`、构建文件、锁文件或源码证据确认，不默认最新版本。
+- 当前会话没有发现语言提供方时，不扫描插件缓存或猜测物理路径。
 - 对现有系统的设计先追踪真实调用链和数据流，区分已验证事实与建议。
 - 不把接口示例、表结构草案或伪代码视为已实施行为。

plugins/dev/skills/design-backend/references/profile-consumption.md

@@ -0,0 +1,10 @@
+# Profile 消费规则
+
+1. 使用目标路径匹配项目画像中的模块；Schema 1 或没有模块时，将顶层技术栈作为根模块候选。
+2. 从项目画像、构建文件和锁文件确认语言、框架及精确版本。
+3. 当前会话发现对应语言的 Profile Skill 时，请求 `backend-design` 能力，由提供方读取自身资料。
+4. 没有发现提供方时，将能力标记为 `missing`，继续执行中性后端设计流程。
+5. Profile 逻辑资料标识只用于诊断，不转换为用户插件缓存路径。
+6. 项目规则由 `guidance` 合并；Profile 只提供公共技术资料。
+
+输出中报告目标模块、版本证据、提供方、能力状态、项目覆盖和未覆盖范围。版本不匹配时不得加载冲突资料。

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

@@ -13,6 +13,9 @@ description: 根据业务数据、访问模式和目标数据库版本设计或
 2. 设计实体、关系、主键、约束、类型、索引和数据生命周期。
 3. 按 [官方来源](references/sources.md) 核实目标版本语法及行为，不跨数据库复制 DDL。
 4. 输出结构、约束、索引依据、迁移顺序、兼容、回滚和验证查询。
-5. 默认只给方案；执行 DDL、迁移存量数据或连接数据库需要单独授权。
+5. 用户要求保存设计说明时，读取 `.craftkit/project.json` 的 `documents` 配置选择过程或共享目录；先检索并更新已有权威数据设计，实质修改共享文档后按项目文档维护规范更新审核状态。
+6. 默认只给方案；执行 DDL、迁移存量数据或连接数据库需要单独授权。
+
+写入后在 `workRoot/<task>/task.json` 登记创建、更新或引用关系。已有文档属于其他任务时只登记关联，不取得删除权限；可执行迁移文件仍沿用项目迁移工具约定。
 
 未知容量、并发和查询模式应标为假设，不凭惯例制造审计字段或业务枚举。

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`。
+
+落盘前检索同主题的需求、设计、规范或知识，优先更新已有权威文档。共享长期文档新建或实质修改后按 `.craftkit/standards/document-maintenance.md` 更新审核状态；排版和错字修正不改变状态。`r`n`r`n写入后在 `workRoot/<task>/task.json` 登记本次创建、更新或引用的文档及 `relationship`；已有记录时保守合并。关联旧文档不转移所有权，也不产生删除权限；不修改项目级默认配置。
 
 具体 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`。
+
+落盘前检索同主题的需求、设计、规范或知识，优先更新已有权威文档。共享长期文档新建或实质修改后按 `.craftkit/standards/document-maintenance.md` 更新审核状态；排版和错字修正不改变状态。`r`n`r`n写入后在 `workRoot/<task>/task.json` 登记本次创建、更新或引用的文档及 `relationship`；已有记录时保守合并。关联旧文档不转移所有权，也不产生删除权限；不修改项目级默认配置。
 
 ## 边界
 

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

@@ -14,3 +14,6 @@ description: 基于项目现有流程引擎契约、业务状态和用户输入
 3. 设计业务事务与流程事务边界、幂等键、审计、通知和失败恢复。
 4. 需要过程建模时可参考 [官方来源](references/sources.md)，但必须映射回项目真实引擎能力。
 5. 输出状态转换表、时序、异常路径、接口需求、数据需求和验收场景；未确认规则列为待确认。
+6. 用户要求保存设计文档时，读取 `.craftkit/project.json` 的 `documents` 配置选择过程或共享目录；先检索并更新已有权威流程设计，实质修改共享文档后按项目文档维护规范更新审核状态。
+
+写入后在 `workRoot/<task>/task.json` 登记创建、更新或引用关系。已有文档属于其他任务时只登记关联，不取得删除权限；业务流程配置和脚本沿用项目源码约定。

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

@@ -11,9 +11,11 @@ description: 按当前项目真实语言、框架版本、规范和现有实现
 
 1. 检查 Git 状态，保留用户已有改动；确认目标、范围和不可修改项。
 2. 读取 `AGENTS.md`、`.craftkit/project.json`，从构建文件确认真实版本。已安装 `guidance` 时用它检索规范；未安装时按“目标目录适用的 `AGENTS.md` → `.craftkit/agents/index.md` → `.craftkit/standards/index.md` → 命中正文”的顺序手工读取，不因缺少另一插件中断实现。
-3. 追踪入口、调用链、数据流、测试和相邻稳定实现；设计不足时先补最小决策，不套用固定模板。
+3. 按目标模块请求 `backend-implementation` 和 `command-resolution`；当前会话未发现语言提供方时继续使用通用实现流程并报告缺口，不扫描插件缓存。
-4. 实施最小完整变更，保持项目目录、依赖、异常、事务、日志和测试风格。
+4. 追踪入口、调用链、数据流、测试和相邻稳定实现；检索相关需求、设计、规范和知识，设计不足时先补最小决策，不套用固定模板。
-5. 执行项目已有的编译、静态检查和相关测试，分别报告未执行的真实环境验证。
+5. 实施最小完整变更，保持项目目录、依赖、异常、事务、日志和测试风格。
+6. 检查本次接口、数据模型、业务行为和验证结论是否使长期文档过期；更新受影响的权威文档并登记到当前 `task.json`，不能完成时标为 `outdated` 并列入待办。
+7. 执行项目已有的编译、静态检查和相关测试，分别报告未执行的真实环境验证。
 
 ## 安全边界
 

plugins/dev/skills/implement-backend/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "后端实现（dev:implement-backend）"
-  short_description: "按项目版本与规范实现后端代码变更"
+  short_description: "实现后端变更并同步受影响的长期文档"
-  default_prompt: "使用 $implement-backend 实现并验证当前后端需求。"
+  default_prompt: "使用 $implement-backend 实现并验证当前后端需求，同时检查并更新受影响的长期文档。"

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

@@ -11,9 +11,10 @@ description: 按当前项目框架版本、组件契约、设计令牌和请求
 
 1. 检查 Git 状态并确认目标文件；从项目元数据、依赖和锁文件识别框架、构建工具及精确版本。
 2. 已安装 `guidance` 时用它检索规范；未安装时按“目标目录适用的 `AGENTS.md` → `.craftkit/agents/index.md` → `.craftkit/standards/index.md` → 命中正文”的顺序手工读取。随后检查相邻页面和公共封装；组件、样式、表单分别消费 `component`、`style`、`form` 的证据。
-3. 有设计与接口映射时消费 `design-frontend` 和 `prepare-api`；没有时只补当前实现必需的最小决策。
+3. 检索相关需求、设计、规范和知识；有设计与接口映射时消费 `design-frontend` 和 `prepare-api`，没有时只补当前实现必需的最小决策。
 4. 修改页面、路由、状态和 API 层，保持项目现有契约，不虚构组件、props、事件、接口或业务校验。
-5. 执行已有格式化、类型检查、测试和构建；未进行真实渲染或浏览器验证时明确说明。
+5. 检查本次页面行为、接口字段、路由、状态和验证结论是否使长期文档过期；更新受影响的权威文档并登记到当前 `task.json`，不能完成时标为 `outdated` 并列入待办。
+6. 执行已有格式化、类型检查、测试和构建；未进行真实渲染或浏览器验证时明确说明。
 
 ## 安全边界
 

plugins/dev/skills/implement-frontend/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "前端实现（dev:implement-frontend）"
-  short_description: "按项目框架与组件契约实现前端变更"
+  short_description: "实现前端变更并同步受影响的长期文档"
-  default_prompt: "使用 $implement-frontend 实现并验证当前前端需求。"
+  default_prompt: "使用 $implement-frontend 实现并验证当前前端需求，同时检查并更新受影响的长期文档。"

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`，后续设计沿用同一任务目录。
+
+落盘前检索同主题的需求、设计、规范或知识，优先更新已有权威文档。共享长期文档新建或实质修改后按 `.craftkit/standards/document-maintenance.md` 更新审核状态；排版和错字修正不改变状态。`r`n`r`n写入后在 `workRoot/<task>/task.json` 登记本次创建、更新或引用的文档及 `relationship`；已有记录时保守合并。关联旧文档不转移所有权，也不产生删除权限；不修改项目级默认配置。
 
 ## 边界
 
-- 不使用固定模块编码、固定文档目录或不存在的下游 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`。
+
+落盘前检索同主题的需求、设计、规范或知识，优先更新已有权威文档。共享长期文档新建或实质修改后按 `.craftkit/standards/document-maintenance.md` 更新审核状态；排版和错字修正不改变状态。`r`n`r`n写入后在 `workRoot/<task>/task.json` 登记本次创建、更新或引用的文档及 `relationship`；已有记录时保守合并。关联旧文档不转移所有权，也不产生删除权限；不修改项目级默认配置。
 
 ## 边界
 

plugins/dev/skills/review-code/SKILL.md

@@ -5,7 +5,7 @@ description: 审查工作区、提交或分支中的代码变更，基于项目
 
 # 代码审查
 
-默认只读。先确认基线和范围，再读取差异、调用方、测试与适用规范；不得只凭补丁片段猜测运行行为。
+默认只读。先确认基线和范围，再读取差异、调用方、测试、适用规范及本次关联的需求和设计；不得只凭补丁片段猜测运行行为。
 
 ## 模式
 
@@ -13,4 +13,6 @@ description: 审查工作区、提交或分支中的代码变更，基于项目
 - 提交：审查指定提交及其父提交差异。
 - 分支：使用明确基线审查提交范围和最终差异。
 
-按严重度输出可操作问题，每项包含文件、位置、触发条件、影响和最小修复方向。没有问题时说明检查范围和未验证边界。审查不自动修复、暂存、提交或推送；静态审查不等同于测试和真实环境验收。
+按严重度输出可操作问题，每项包含文件、位置、触发条件、影响和最小修复方向。审核实现与当前有效文档是否一致，并检查本次变更影响的长期文档是否已更新；`pending`、`outdated`、缺少状态和历史归档分别如实报告，不能把历史材料当作当前依据。
+
+没有问题时说明检查范围和未验证边界。审查不自动修改文档、代码、审核状态、暂存、提交或推送；静态审查不等同于测试、文档批准和真实环境验收。

plugins/dev/skills/review-code/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "代码审查（dev:review-code）"
-  short_description: "审查工作区、提交或分支的代码变更"
+  short_description: "审查代码质量及实现与有效文档的一致性"
-  default_prompt: "使用 $review-code 审查当前代码变更并按严重度报告问题。"
+  default_prompt: "使用 $review-code 审查当前代码变更、相关文档同步情况，并按严重度报告问题。"

plugins/dev/skills/review-java/SKILL.md

@@ -10,7 +10,8 @@ description: 按项目 Java 版本、框架、规范和真实调用上下文评
 ## 工作流
 
 1. 确认审查范围、版本、框架、编译选项和相关测试。
-2. 检查类型与空值、异常边界、资源关闭、集合、并发、序列化和公开契约。
+2. 当前会话发现 `java:profile` 时请求 `language-review`，由提供方读取自身资料；未发现时继续使用本 Skill 的最小基线并报告缺口。
-3. 语言结论按 [官方来源](references/sources.md) 路由到当前版本；预览特性不得视为默认可用。
+3. 检查类型与空值、异常边界、资源关闭、集合、并发、序列化和公开契约。
-4. 只报告可复现、有代码证据且影响明确的问题，按严重度给出最小修复建议。
+4. 语言结论按 [官方来源](references/sources.md) 路由到当前版本；预览特性不得视为默认可用。
-5. 未运行编译或测试时明确说明，不自动修改代码。
+5. 只报告可复现、有代码证据且影响明确的问题，按严重度给出最小修复建议。
+6. 未运行编译或测试时明确说明，不自动修改代码。

plugins/dev/skills/style/SKILL.md

@@ -13,7 +13,7 @@ description: 基于当前项目的设计令牌、主题、页面和用户参考
 2. 按 [来源优先级](references/sources.md) 确定现有设计权威与用户参考的关系。
 3. 识别需要继承、补充或覆盖的颜色、排版、间距、圆角、阴影、断点和交互状态。
 4. 按 [输出约定](references/output.md) 给出规范或样式修改，并说明未验证风险。
-5. 需要写入 `.craftkit/standards/frontend/design.md` 时，先展示拟写内容和合并策略，经用户确认后再修改。
+5. 需要写入 `.craftkit/standards/frontend/design.md` 时，先读取原文并展示拟写内容和合并策略，经用户确认后更新；实质修改按项目文档维护规范重新审核。
 
 如果项目没有视觉基线，先询问用户是否有设计稿、截图或参考项目；输入仍不足时只给出待确认项，不擅自确定品牌风格。
 

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

@@ -5,6 +5,8 @@ description: 按当前项目测试框架为后端代码设计、生成、修改
 
 # 后端测试
 
-从构建文件和现有测试确认框架、版本、目录和运行方式。优先选择不启动完整应用即可验证业务规则的最小测试层级；只有集成边界确实需要时才加载框架上下文。
+从构建文件和现有测试确认框架、版本、目录和运行方式。按目标模块请求 `backend-testing` 和 `command-resolution`；当前会话未发现语言提供方时使用通用测试原则并报告缺口，不扫描插件缓存。优先选择不启动完整应用即可验证业务规则的最小测试层级；只有集成边界确实需要时才加载框架上下文。
 
 测试应覆盖可观察行为，不绑定私有实现；外部依赖使用项目已有隔离方式，不连接真实生产资源。运行聚焦测试后分别报告通过、失败、未执行和环境阻塞。新增依赖、修改业务代码、删除既有测试或运行需要真实服务的测试必须先说明并取得相应授权。
+
+Profile 返回的命令只是候选。只有项目脚本、构建文件、CI 配置或用户确认支持时才执行；不得因公共 Profile 自动新增测试依赖。

plugins/dev/skills/upgrade/SKILL.md

@@ -7,4 +7,4 @@ description: 规划并实施前端、后端或依赖的大版本升级，基于
 
 升级前必须确认当前版本、目标版本、支持矩阵、运行环境、锁文件和回滚要求。只读取对应产品的官方迁移指南、发行说明和弃用清单，并记录访问日期；不得使用来源插件的内部升级矩阵。
 
-先输出依赖差异、破坏性变化、代码与配置影响、数据或构建迁移、验证矩阵和回滚点。用户确认实施后分小步修改，每步运行项目已有检查。新增依赖下载或访问网络按环境授权执行。环境配置、生产数据、部署、提交、标签和推送均不在默认授权内。
+先输出依赖差异、破坏性变化、代码与配置影响、数据或构建迁移、验证矩阵和回滚点，并检索会被版本变化影响的长期设计、规范和知识。用户确认实施后分小步修改，每步运行项目已有检查，同步更新受影响的权威文档并按项目文档维护规范重新审核；不能完成时标为 `outdated`。新增依赖下载或访问网络按环境授权执行。环境配置、生产数据、部署、提交、标签和推送均不在默认授权内。

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: "将技术输入整理为可确认的需求说明"
+  short_description: "创建或更新可审核的需求说明"
-  default_prompt: "使用 $requirements 将这些材料整理成需求和疑问清单。"
+  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/java/.codex-plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "java",
+  "version": "0.1.0",
+  "description": "Java、JDK、构建工具和 Spring 技术能力资料。",
+  "author": { "name": "CraftKit" },
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Java",
+    "shortDescription": "Java 与 Spring 技术能力资料",
+    "longDescription": "按项目 Java、构建工具和 Spring 版本提供设计、命令与专项审查资料。",
+    "developerName": "CraftKit",
+    "category": "Productivity",
+    "capabilities": ["Read"],
+    "defaultPrompt": ["帮我按当前项目版本获取 Java 技术约束。"]
+  }
+}

plugins/java/skills/profile/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: profile
+description: 根据项目中的 Java、JDK、Maven、Gradle 和 Spring 证据提供版本匹配的设计、命令和专项审查资料。适用于核心工作流请求 Java 技术能力；通用业务实现或无法确认 Java 项目时不应触发。
+---
+
+# Java Profile
+
+读取自身[能力清单](references/manifest.json)，根据目标模块的构建文件和项目画像返回匹配能力。
+
+## 工作流
+
+1. 从 `pom.xml`、Gradle 文件、Wrapper、工具链配置和 `.craftkit/project.json` 提取 Java 与 Spring 版本证据。
+2. 只选择版本范围匹配的 Profile；版本未知时只使用 `java/default`。
+3. 按请求能力读取对应资料，返回逻辑资料标识、适用版本和证据。
+4. 项目已有命令优先于[命令规则](references/commands/index.md)。
+5. 缺失能力或版本不匹配时返回明确状态，不写项目文件。
+
+## 边界
+
+- 不默认最新 JDK、Spring 或构建插件版本。
+- 不安装 JDK、Maven、Gradle 或项目依赖。
+- 不调用 `dev`，最终设计、实现和审查由核心 Skill 负责。

plugins/java/skills/profile/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Java Profile（java:profile）"
+  short_description: "按项目版本提供 Java 与 Spring 技术资料"
+  default_prompt: "使用 $profile 获取当前项目适用的 Java 技术能力。"

plugins/java/skills/profile/references/backend/design.md

@@ -0,0 +1,7 @@
+# Java 后端设计资料
+
+- 先从构建文件确认 Java、Spring 和持久化框架精确版本。
+- 领域服务、协议入口和持久化实现保持明确边界，事务范围围绕业务一致性定义。
+- Spring 代理、事务传播和异步边界必须以当前项目版本及真实调用路径为依据。
+- DTO、领域对象和持久化对象分别承担各自边界，转换位置遵循项目现有结构。
+- 并发、幂等和失败恢复必须说明数据库约束、条件更新或锁的真实落点。

plugins/java/skills/profile/references/commands/index.md

@@ -0,0 +1,6 @@
+# Java 命令选择
+
+1. 优先使用仓库中的 Maven Wrapper 或 Gradle Wrapper。
+2. 其次使用项目文档和 CI 中已经验证的命令。
+3. 没有 Wrapper 或项目命令时只给出待确认建议，不假定全局工具存在。
+4. Profile 返回命令建议不代表已经获得执行、安装或修改依赖的授权。

plugins/java/skills/profile/references/fallback.md

@@ -0,0 +1,3 @@
+# Java 回退
+
+版本未知时只使用 Java 版本中性的设计和审查原则。Spring 或构建工具无法确认时不加载对应专属规则，并说明缺少的证据。

plugins/java/skills/profile/references/manifest.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": 1,
+  "provider": { "id": "java", "kind": "language", "displayName": "Java" },
+  "profiles": [
+    {
+      "id": "java/default",
+      "version": { "scheme": "java-feature", "range": "*" },
+      "priority": 10,
+      "detect": { "manifests": ["pom.xml", "build.gradle", "build.gradle.kts"], "wrappers": ["mvnw", "gradlew"] },
+      "capabilities": {
+        "backend-design": "references/backend/design.md",
+        "language-review": "references/review/index.md",
+        "command-resolution": "references/commands/index.md"
+      },
+      "fallback": "references/fallback.md"
+    }
+  ]
+}

plugins/java/skills/profile/references/review/index.md

@@ -0,0 +1,6 @@
+# Java 专项审查资料
+
+- 检查 Java 版本、编译选项和预览特性是否匹配。
+- 检查资源关闭、异常传播、空值、泛型、并发可见性和序列化边界。
+- Spring 项目额外检查代理失效、事务边界、Bean 生命周期和线程上下文。
+- 只报告有调用上下文和明确影响的问题，避免把个人风格作为缺陷。

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

@@ -1,6 +1,6 @@
 {
   "name": "knowledge",
-  "version": "0.3.1",
+  "version": "0.6.0",
   "description": "项目初始化、任务交接、复盘与知识沉淀工作流。",
   "author": {
     "name": "CraftKit"
@@ -8,8 +8,8 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "Knowledge",
-    "shortDescription": "项目初始化与知识沉淀工具",
+    "shortDescription": "项目初始化与文档知识生命周期工具",
-    "longDescription": "提供项目初始化、任务交接、Agent 复盘、知识提炼、问题经验维护和 Git 工作日志。",
+    "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

@@ -5,7 +5,7 @@ description: 初始化或更新项目的 AGENTS.md 与 .craftkit 项目资料；
 
 # 项目初始化
 
-建立可持续维护的项目上下文，使后续 Agent 能识别项目用途、技术栈、代码边界、内部依赖标识和适用规范。只初始化 Agent 与知识资料，不默认生成业务代码。
+建立可持续维护的项目上下文，使后续 Agent 能识别项目用途、模块级技术栈、代码边界、内部依赖标识和适用规范。只初始化 Agent 与知识资料，不默认生成业务代码。
 
 ## 选择模式
 
@@ -21,20 +21,22 @@ description: 初始化或更新项目的 AGENTS.md 与 .craftkit 项目资料；
 
 1. 确认项目根目录、初始化模式和参考材料范围。
 2. 扫描当前项目；只在用户授权的路径中扫描参考项目。
-3. 展示自动识别的信息、证据、冲突和待确认项。
+3. 展示自动识别的信息、证据、冲突和待确认项；读取已有画像时兼容 Schema 1 和 Schema 2。
 4. 通过简短提问补齐无法可靠推断的项目用途、包名、框架、精确版本、公共 profile、内部依赖和约束；前端项目还需确认组件库、组件根、文档入口及参考项目范围。禁止默认最新版本。
-5. 展示拟创建或修改的文件及关键内容，取得确认后再写入。
+5. 展示拟创建或修改的文件及关键内容，取得确认后再写入；Schema 1 升级必须展示完整字段差异。
-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`，否则保留为空并记录待确认事项。
+Schema 1 的框架版本继续从 `technology.frameworks` 读取。Schema 2 保留顶层兼容概要，并把精确语言、框架、版本和证据写入 `modules[].technology`。`preferredProfiles` 只记录用户确认的项目偏好，不表示当前机器已经安装插件；运行时发现结果不得写入共享画像。
 
 前端组件信息写入 `frontend`。成熟项目从依赖清单、锁文件、组件目录、类型和现有调用提取；空项目根据用户已确认的技术选型或授权参考提议填写。未知组件库或版本保持为空，不根据框架名称自行猜测。
 
 ## 安全边界
 
+初始化或更新 `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

@@ -1,9 +1,10 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "initialization": { "mode": "new", "references": [] },
   "project": { "name": "", "description": "", "type": "other" },
   "technology": { "languages": [], "frameworks": [], "buildTools": [], "databases": [] },
   "code": { "sourceRoots": [], "packageRoots": [], "modules": [] },
+  "modules": [],
   "dependencies": { "internal": [], "public": [] },
   "frontend": {
     "framework": "",
@@ -12,7 +13,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,43 @@
 - `dependencies.internal` 只记录用户确认可在当前仓库共享的依赖标识和用途。
 - `frontend` 记录前端框架、组件库、组件根和文档入口；路径必须是项目相对路径，版本必须有依赖清单、锁文件或用户确认作为证据。
 - `commands` 只记录经过项目文件或用户确认的命令。
-- `documents.archiveRoot` 记录可共享的文档归档根；`documents.archiveRules` 记录项目确认的匹配、目标模板、转换和校验规则，不写入公司固定目录或外部系统凭据。
+- `documents` 区分过程文档、共享设计和归档目录，字段及回退行为见下方“文档目录”；归档规则不写入公司固定目录或外部系统凭据。
 - `guidance` 指向 `.craftkit/` 内的索引入口。
 - `initialization.references` 记录参考项目名称、用途、允许提炼范围和可共享的相对位置。
 
+## Schema 兼容
+
+- Schema 1 没有顶层 `modules` 时，将顶层技术栈和 `code` 边界作为根模块候选，不自动改写文件。
+- Schema 2 保留顶层 `technology` 原有字段类型，增加 `modules[].technology` 表达模块级精确信息。
+- `modules[].technology.preferredProfiles` 是项目确认的偏好，不表示当前机器已安装对应插件。
+- 插件发现、匹配状态和本机路径属于运行时信息，只存在于任务上下文或 `.craftkit/local/`。
+- 所有读取方完成 Schema 1/2 双读后，`init` 才能在用户确认差异后写入 Schema 2。
+
+模块根使用项目相对正斜线路径。目标路径命中多个模块时采用最长根；同长度重复根视为配置冲突。
+
+## 文档目录
+
+| 字段 | 默认值 | 用途 |
+| --- | --- | --- |
+| `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/profile/.codex-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "profile",
+  "version": "0.1.0",
+  "description": "技术能力 Profile 契约、匹配规则与静态校验工具。",
+  "author": {
+    "name": "CraftKit"
+  },
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Profile",
+    "shortDescription": "技术能力契约、匹配和静态校验",
+    "longDescription": "提供多语言技术能力清单契约、版本匹配规则、缺失回退和确定性静态校验。",
+    "developerName": "CraftKit",
+    "category": "Productivity",
+    "capabilities": ["Read"],
+    "defaultPrompt": ["帮我解析当前项目需要的技术 Profile，并说明能力缺口。"]
+  }
+}

plugins/profile/skills/resolve/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: resolve
+description: 根据目标模块、项目技术事实和当前会话已发现的技术提供方解析 Profile 能力，返回匹配结果、资料入口和缺口。适用于多语言项目的能力选择与诊断；项目初始化、业务设计或直接实现不应触发。
+---
+
+# Profile 解析
+
+根据项目证据选择技术能力，不扫描用户插件缓存，也不写入项目画像。
+
+## 工作流
+
+1. 读取目标路径、所需能力和 `.craftkit/project.json`；项目画像缺失时只使用构建文件、锁文件和源码中的可验证事实。
+2. 按模块根最长匹配规则确定目标模块；同长度命中多个模块时返回 `ambiguous`。
+3. 从当前会话可用 Skill 判断提供方是否已被发现，不推断未暴露插件的安装状态。
+4. 已发现提供方时，由对应 Profile Skill 读取自身清单并返回候选；本 Skill 不拼接其他插件物理路径。
+5. 按[解析规则](references/resolution.md)选择候选，并按[回退规则](references/fallback.md)处理缺失、未知和冲突。
+6. 返回标准能力上下文，区分事实、选择、逻辑资料标识、项目覆盖入口和缺口。
+
+详细字段和能力枚举见[契约](references/contract.md)，提供方发现边界见[发现协议](references/discovery.md)。
+
+## 边界
+
+- Profile 提供的命令只是选择建议，不构成执行授权。
+- 项目规范的合并和覆盖由 `guidance` 负责。
+- 稳定项目事实只有在用户要求初始化或更新画像时才由 `knowledge:init` 写入。
+- 逻辑资料标识只用于诊断；消费者不能将其转换成用户目录绝对路径。

plugins/profile/skills/resolve/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Profile Resolver（profile:resolve）"
+  short_description: "按项目事实匹配技术能力并报告缺口"
+  default_prompt: "使用 $resolve 解析当前目标模块需要的技术 Profile。"

plugins/profile/skills/resolve/references/contract.md

@@ -0,0 +1,22 @@
+# Profile 契约
+
+每个提供方以 `references/manifest.json` 声明能力。清单只包含路由元数据，规则正文保存在同一 Skill 的 Markdown 文件中。
+
+必需字段包括 `schemaVersion`、`provider` 和 `profiles`。Profile 必须声明稳定 ID、版本体系、版本范围、优先级、探测证据、能力资料入口和回退入口。
+
+首期能力标识：
+
+- `project-detection`
+- `knowledge-routing`
+- `backend-design`
+- `backend-implementation`
+- `backend-testing`
+- `language-review`
+- `framework-review`
+- `command-resolution`
+
+缺少能力表示提供方不提供该能力，不能使用空文件占位。
+
+首期版本范围只支持 `*`、精确数字版本，以及用逗号连接的 `>=`、`>`、`<=`、`<`、`==` 条件。不支持并集、排除、预发布标签和生态专属通配表达式。
+
+诊断结果使用 `<plugin>:<skill>/<skill 内相对路径>` 逻辑标识。该值不能被消费者拼接为物理路径。

plugins/profile/skills/resolve/references/discovery.md

@@ -0,0 +1,9 @@
+# 提供方发现协议
+
+1. 当前会话的 Skill 清单是提供方是否可用的唯一运行时依据。
+2. 消费者请求已发现的 `<provider>:profile`，由提供方读取自己的清单和资料。
+3. 没有发现对应 Skill 时返回 `missing`，不扫描用户插件缓存。
+4. Profile 插件不维护运行时注册表，不读取其他插件目录。
+5. 新增或更新插件后的真实发现行为必须在安装后的新会话验证。
+
+仓库静态校验只能证明声明有效，不能证明插件已经安装或当前会话已经加载。

plugins/profile/skills/resolve/references/fallback.md

@@ -0,0 +1,12 @@
+# Profile 回退规则
+
+| 状态 | 条件 | 消费者行为 |
+| --- | --- | --- |
+| `available` | 提供方已发现、版本匹配且资料有效 | 加载专项资料 |
+| `generic` | 只有版本中性资料 | 使用通用资料并说明适用范围 |
+| `missing` | 提供方或能力未发现 | 继续核心通用流程并报告缺口 |
+| `incompatible` | 项目版本不在支持范围 | 禁止加载冲突资料 |
+| `ambiguous` | 模块或候选无法唯一确定 | 展示候选并请求最小必要信息 |
+| `invalid` | 清单或引用未通过校验 | 隔离该提供方并报告错误 |
+
+回退结果必须说明核心工作流仍可完成的范围，不能把缺少增强能力描述为项目缺陷。

plugins/profile/skills/resolve/references/manifest.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://craftkit.local/schemas/profile-manifest-v1.json",
+  "title": "CraftKit Profile Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "provider", "profiles"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "provider": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "displayName"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+        "kind": { "enum": ["language", "framework", "toolchain"] },
+        "displayName": { "type": "string", "minLength": 1 }
+      }
+    },
+    "profiles": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "version", "priority", "detect", "capabilities", "fallback"]
+      }
+    }
+  }
+}

plugins/profile/skills/resolve/references/resolution.md

@@ -0,0 +1,19 @@
+# Profile 解析规则
+
+## 模块选择
+
+- 将目标路径和模块根转换为项目相对规范路径。
+- 选择路径前缀最长的模块根。
+- 同一目标命中多个同长度模块时返回 `ambiguous`。
+- 跨模块任务分别解析，不合并为仓库级单一 Profile。
+
+## 候选选择
+
+1. 项目已确认 `preferredProfiles` 时，先检查对应提供方是否被发现。
+2. 没有偏好时按语言、框架、版本和构建证据筛选。
+3. 优先版本范围更窄、探测证据更具体的候选。
+4. 仍有多个候选时按较高 `priority` 选择。
+5. 排序后仍不能唯一确定时返回 `ambiguous`。
+6. 没有版本匹配时，只允许加载 `*` 的版本中性 Profile。
+
+项目事实和清单冲突时保留项目事实，返回 `incompatible`，不能建议自动升级项目依赖。

plugins/profile/skills/resolve/scripts/validate_profile.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""校验 CraftKit 技术 Profile 清单的结构、标识、版本范围和资料引用。"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+CAPABILITIES = {
+    "project-detection",
+    "knowledge-routing",
+    "backend-design",
+    "backend-implementation",
+    "backend-testing",
+    "language-review",
+    "framework-review",
+    "command-resolution",
+}
+KINDS = {"language", "framework", "toolchain"}
+SCHEMES = {"semver", "pep440", "java-feature", "generic"}
+ID_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+PROFILE_PATTERN = re.compile(r"^[a-z0-9-]+/[a-z0-9-]+$")
+VERSION_PATTERN = re.compile(r"^(?:\*|(?:>=|>|<=|<|==)?\d+(?:\.\d+){0,2}(?:,(?:>=|>|<=|<|==)\d+(?:\.\d+){0,2})*)$")
+
+
+def _require_mapping(value: Any, label: str, errors: list[str]) -> dict[str, Any]:
+    """把对象字段收窄为字典，并把类型错误加入统一错误集合。"""
+    if not isinstance(value, dict):
+        errors.append(f"{label} 必须是对象")
+        return {}
+    return value
+
+
+def _validate_reference(skill_root: Path, value: Any, label: str, errors: list[str]) -> None:
+    """保证资料引用为 Skill 内相对文件，阻止绝对路径和目录逃逸。"""
+    if not isinstance(value, str) or not value:
+        errors.append(f"{label} 必须是非空相对路径")
+        return
+    relative = Path(value)
+    if relative.is_absolute() or ".." in relative.parts:
+        errors.append(f"{label} 不能使用绝对路径或目录逃逸: {value}")
+        return
+    target = (skill_root / relative).resolve()
+    try:
+        target.relative_to(skill_root.resolve())
+    except ValueError:
+        errors.append(f"{label} 超出 Skill 目录: {value}")
+        return
+    if not target.is_file():
+        errors.append(f"{label} 引用文件不存在: {value}")
+    elif target.stat().st_size == 0:
+        errors.append(f"{label} 引用文件为空: {value}")
+
+
+def validate_manifest(path: Path) -> list[str]:
+    """返回全部可确定的契约错误，便于一次修复多个问题。"""
+    errors: list[str] = []
+    try:
+        data = json.loads(path.read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return [f"无法读取 JSON: {exc}"]
+
+    root = _require_mapping(data, "根节点", errors)
+    if root.get("schemaVersion") != 1:
+        errors.append("schemaVersion 必须为 1")
+
+    provider = _require_mapping(root.get("provider"), "provider", errors)
+    provider_id = provider.get("id")
+    if not isinstance(provider_id, str) or not ID_PATTERN.fullmatch(provider_id):
+        errors.append("provider.id 必须是小写短横线标识")
+    if provider.get("kind") not in KINDS:
+        errors.append("provider.kind 不受支持")
+    if not isinstance(provider.get("displayName"), str) or not provider.get("displayName"):
+        errors.append("provider.displayName 必须是非空字符串")
+
+    profiles = root.get("profiles")
+    if not isinstance(profiles, list) or not profiles:
+        errors.append("profiles 必须是非空数组")
+        return errors
+
+    seen: set[str] = set()
+    skill_root = path.parent.parent
+    for index, raw_profile in enumerate(profiles):
+        label = f"profiles[{index}]"
+        profile = _require_mapping(raw_profile, label, errors)
+        profile_id = profile.get("id")
+        if not isinstance(profile_id, str) or not PROFILE_PATTERN.fullmatch(profile_id):
+            errors.append(f"{label}.id 格式无效")
+        elif profile_id in seen:
+            errors.append(f"{label}.id 重复: {profile_id}")
+        else:
+            seen.add(profile_id)
+        if isinstance(provider_id, str) and isinstance(profile_id, str) and not profile_id.startswith(provider_id + "/"):
+            errors.append(f"{label}.id 必须使用 provider.id 作为前缀")
+
+        version = _require_mapping(profile.get("version"), f"{label}.version", errors)
+        if version.get("scheme") not in SCHEMES:
+            errors.append(f"{label}.version.scheme 不受支持")
+        version_range = version.get("range")
+        if not isinstance(version_range, str) or not VERSION_PATTERN.fullmatch(version_range):
+            errors.append(f"{label}.version.range 格式无效")
+        if not isinstance(profile.get("priority"), int) or isinstance(profile.get("priority"), bool):
+            errors.append(f"{label}.priority 必须是整数")
+        if not isinstance(profile.get("detect"), dict):
+            errors.append(f"{label}.detect 必须是对象")
+
+        capabilities = _require_mapping(profile.get("capabilities"), f"{label}.capabilities", errors)
+        if not capabilities:
+            errors.append(f"{label}.capabilities 不能为空")
+        for capability, reference in capabilities.items():
+            if capability not in CAPABILITIES:
+                errors.append(f"{label}.capabilities 包含未知能力: {capability}")
+            _validate_reference(skill_root, reference, f"{label}.capabilities.{capability}", errors)
+        _validate_reference(skill_root, profile.get("fallback"), f"{label}.fallback", errors)
+    return errors
+
+
+def main() -> int:
+    """解析命令行参数并以退出码表达校验结果。"""
+    parser = argparse.ArgumentParser(description="校验 CraftKit Profile manifest.json")
+    parser.add_argument("manifests", nargs="+", type=Path, help="一个或多个 manifest.json 路径")
+    args = parser.parse_args()
+    failed = False
+    for manifest in args.manifests:
+        errors = validate_manifest(manifest.resolve())
+        if errors:
+            failed = True
+            print(f"FAIL {manifest}")
+            for error in errors:
+                print(f"  - {error}")
+        else:
+            print(f"PASS {manifest}")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

plugins/python/.codex-plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "python",
+  "version": "0.1.0",
+  "description": "Python、包管理、FastAPI 和测试技术能力资料。",
+  "author": { "name": "CraftKit" },
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Python",
+    "shortDescription": "Python 与 FastAPI 技术能力资料",
+    "longDescription": "按项目 Python、包管理和 FastAPI 版本提供设计、实现、测试与审查资料。",
+    "developerName": "CraftKit",
+    "category": "Productivity",
+    "capabilities": ["Read"],
+    "defaultPrompt": ["帮我按当前项目版本获取 Python 技术约束。"]
+  }
+}

plugins/python/skills/profile/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: profile
+description: 根据项目中的 Python、包管理、FastAPI 和测试工具证据提供版本匹配的设计、实现、测试和审查资料。适用于核心工作流请求 Python 技术能力；通用业务实现或无法确认 Python 项目时不应触发。
+---
+
+# Python Profile
+
+读取自身[能力清单](references/manifest.json)，根据目标模块的项目清单、锁文件和项目画像返回匹配能力。
+
+## 工作流
+
+1. 从 `pyproject.toml`、依赖文件、锁文件、版本文件和 `.craftkit/project.json` 提取证据。
+2. 只选择版本范围匹配的 Profile；版本未知时只使用版本中性资料。
+3. Ruff、mypy、pyright、Black 等工具只有在项目配置或依赖中存在时才作为可用命令。
+4. 按请求能力读取对应资料并返回逻辑资料标识、适用版本和证据。
+5. 缺失能力或版本不匹配时返回明确状态，不写项目文件。
+
+## 边界
+
+- 不默认最新 Python、FastAPI 或 Pydantic 版本。
+- 不安装解释器、包管理器、质量工具或项目依赖。
+- 不调用 `dev`，最终设计、实现、测试和审查由核心 Skill 负责。

plugins/python/skills/profile/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Python Profile（python:profile）"
+  short_description: "按项目版本提供 Python 与 FastAPI 技术资料"
+  default_prompt: "使用 $profile 获取当前项目适用的 Python 技术能力。"

plugins/python/skills/profile/references/backend/design.md

@@ -0,0 +1,7 @@
+# Python 后端设计资料
+
+- 从项目清单和锁文件确认 Python、框架、Pydantic 与数据访问工具版本。
+- 协议模型、领域输入输出和 ORM 模型保持边界，避免框架对象扩散到核心业务。
+- 同步与异步调用链必须一致；阻塞 I/O 不能未经处理进入异步请求路径。
+- 事务、幂等和外部调用失败恢复需要明确数据库约束与提交顺序。
+- 配置和依赖通过项目已有机制注入，不能在模块导入时连接真实外部资源。

plugins/python/skills/profile/references/backend/implementation.md

@@ -0,0 +1,7 @@
+# Python 后端实现资料
+
+- 遵循项目现有包结构、类型标注和异常边界。
+- 资源使用上下文管理器或项目已有生命周期机制可靠释放。
+- 不混用不兼容的 Pydantic、FastAPI 或 ORM 版本写法。
+- 新增依赖前确认项目包管理工具、锁文件和用户授权。
+- 实现后运行项目已有的聚焦测试与检查命令。

plugins/python/skills/profile/references/commands/index.md

@@ -0,0 +1,6 @@
+# Python 命令选择
+
+1. 从锁文件和 `pyproject.toml` 确定 uv、Poetry、PDM、Pipenv 或 pip。
+2. 优先使用项目脚本、任务入口和 CI 已执行命令。
+3. Ruff、mypy、pyright、Black 只有存在配置或依赖证据时才返回。
+4. Profile 不安装工具，也不把建议命令视为执行授权。

plugins/python/skills/profile/references/fallback.md

@@ -0,0 +1,3 @@
+# Python 回退
+
+版本未知时只使用 Python 版本中性规则。FastAPI、Pydantic、测试插件或包管理工具无法确认时不加载其专属写法，并说明缺少的项目证据。

plugins/python/skills/profile/references/manifest.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": 1,
+  "provider": { "id": "python", "kind": "language", "displayName": "Python" },
+  "profiles": [
+    {
+      "id": "python/default",
+      "version": { "scheme": "pep440", "range": ">=3.9,<3.14" },
+      "priority": 10,
+      "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/commands/index.md"
+      },
+      "fallback": "references/fallback.md"
+    }
+  ]
+}

plugins/python/skills/profile/references/review/index.md

@@ -0,0 +1,7 @@
+# Python 专项审查资料
+
+- 检查类型与空值、异常边界、资源生命周期、可变默认值和导入副作用。
+- 检查同步与异步混用、任务泄漏、取消处理和阻塞 I/O。
+- FastAPI 项目检查依赖生命周期、请求模型、响应序列化和后台任务边界。
+- ORM 代码检查事务所有权、会话生命周期、延迟加载和查询数量。
+- 只报告有代码证据和明确影响的问题。

plugins/python/skills/profile/references/testing/index.md

@@ -0,0 +1,6 @@
+# Python 后端测试资料
+
+- 优先使用项目已配置的 pytest 或 unittest，不自行引入测试框架。
+- 异步代码只有在项目已配置对应插件和事件循环策略时使用异步测试写法。
+- 测试客户端、依赖覆盖和数据库隔离方式必须匹配当前 FastAPI 及相关依赖版本。
+- 外部依赖使用项目已有替身或隔离边界，不连接真实生产资源。

plugins/python/skills/review-python/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: review-python
+description: 按项目 Python、框架和工具版本审查类型、异常、资源、异步、生命周期、事务和测试隔离问题。适用于 Python 专项代码审查；通用审查、直接实现或无法确认 Python 项目时不应触发。
+---
+
+# Python 专项审查
+
+先从项目清单、锁文件、源码和 `.craftkit/project.json` 确认 Python、框架及数据访问工具版本。
+
+## 工作流
+
+1. 确认审查范围、目标模块、Python 版本、框架、包管理工具和相关测试。
+2. 请求 `python:profile` 的 `language-review`；当前会话未发现提供方时说明缺口并使用本 Skill 的最小检查项。
+3. 检查类型与空值、异常边界、资源生命周期、可变默认值、导入副作用和公开契约。
+4. 异步代码检查阻塞 I/O、任务生命周期、取消处理及同步/异步边界。
+5. 框架和 ORM 代码按已确认版本检查依赖、请求、会话与事务生命周期。
+6. 只报告可复现、有代码证据且影响明确的问题，按严重度给出最小修复建议。
+7. 未运行静态检查或测试时明确说明，不自动修改代码。
+
+## 边界
+
+- 不默认最新 Python、FastAPI、Pydantic 或 ORM 行为。
+- 项目未配置 Ruff、mypy、pyright 或 Black 时，不把缺少这些工具本身报告为缺陷。
+- 不安装工具、修改依赖或连接真实外部资源。

plugins/python/skills/review-python/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Python Review（python:review-python）"
+  short_description: "按项目版本专项审查 Python 代码"
+  default_prompt: "使用 $review-python 按当前项目版本审查这段 Python 代码。"

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

@@ -1,6 +1,6 @@
 {
   "name": "skill",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "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

@@ -12,10 +12,11 @@ description: 检索当前项目的 AGENTS.md、.craftkit 项目资料和 CraftKi
 1. 确定任务涉及的目录、文件类型和主题。
 2. 读取从项目根到目标目录沿途适用的 `AGENTS.md`，距离目标更近的文件约束更具体。
 3. 若存在 `.craftkit/project.json`，读取其中的项目类型、技术栈、代码边界和规范入口。
-4. 涉及框架时按[版本 Profile 路由](references/profile-routing.md)确定当前项目版本；普通开发只加载当前 profile，升级或版本比较才加载源、目标两个 profile。
+4. 涉及技术栈时先按目标路径确定模块，再按[版本 Profile 路由](references/profile-routing.md)确定当前版本；Schema 1 或没有模块时使用顶层技术栈作为根模块候选。
-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)，只加载当前任务需要的规则。
+6. 当前会话发现对应语言提供方时，由提供方读取自身 Profile 资料；未发现时报告 `missing`，不扫描插件缓存。
-7. 索引缺失或没有命中时，才在相应目录做受控关键词搜索；不得先递归加载整个知识库。
+7. 项目资料和已发现的技术提供方均未覆盖主题时，读取[公共基线索引](references/guidance/index.md)，只加载当前任务需要的规则。
+8. 索引缺失或没有命中时，才在相应目录做受控关键词搜索；不得先递归加载整个知识库。
 
 目录布局和优先级的详细说明见[检索布局](references/layout.md)。
 
@@ -36,5 +37,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: "按索引渐进检索项目规范、中性公共基线及冲突依据"
+  short_description: "检索当前有效规则并识别过时与历史材料"
-  default_prompt: "使用 $guidance 查找当前任务适用的项目规范，并给出可追溯依据。"
+  default_prompt: "使用 $guidance 查找当前任务适用且有效的项目规范与知识，并给出可追溯依据。"