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/designs/multi-language-plugin/MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-DESIGN.md

@@ -1,10 +1,16 @@
+---
+reviewStatus: pending
+reviewedAt: null
+replacedBy: null
+---
+
 # 多语言插件架构设计与实施方案
 
 ## 1. 设计目标
 
 本设计将 CraftKit 建设为可扩展的多语言插件体系。现有 `dev`、`knowledge` 和 `skill` 插件继续提供通用工作流，新增 Profile 工厂和技术能力插件，使初始化、规范检索、后端设计、实现、测试和审查能够按项目真实技术栈加载 Java、Python 或前端专项知识。
 
-本设计细化[《多语言插件架构改造计划》](MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-PLAN.md)，作为后续编码、迁移、测试和发布的实施依据。原计划将物理拆分放在契约验证之后；本设计根据用户确认的工厂化方向，改为首期建立独立插件骨架、保留旧 Skill 入口兼容，实施边界以本文为准。
+本文是多语言插件架构的唯一设计依据。[《多语言插件架构改造计划》](MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-PLAN.md)只跟踪实施批次、依赖和验证状态，不重复定义架构。首期建立独立插件骨架并保留旧 Skill 入口，但只有经过安装组合验证后才声明插件可独立交付。
 
 首期交付范围：
 
@@ -55,6 +61,26 @@
 - 公共插件不能直接写入业务项目；项目文件统一由当前获得授权的核心 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 负责“执行业务工作流”。项目知识库提供当前项目的覆盖规则。
@@ -129,12 +155,12 @@ plugins/profile/
          └─ validate_profile.py
 ```
 
-`profile:resolve` 是唯一工厂入口，承担以下职责：
+`profile:resolve` 是契约和解析规则入口。消费者可在该 Skill 已发现时使用其匹配规则，但不能假设它能枚举或调用其他插件。它承担以下职责：
 
 1. 接收目标目录、任务所需能力和项目画像。
 2. 确认目标属于哪个模块。
 3. 从项目文件识别语言、框架、版本和工具证据。
-4. 根据能力提供方返回的信息完成匹配。
+4. 根据当前会话已经发现的能力提供方返回信息完成匹配。
 5. 合并项目覆盖规则并输出标准能力上下文。
 6. 在缺失、冲突或版本不匹配时返回明确的回退结果。
 
@@ -328,7 +354,18 @@ gaps: []
 python:profile/references/testing/index.md
 ```
 
-该标识用于说明应激活的插件能力和资料入口，不拼接用户缓存目录。提供方 Skill 负责读取自身资料，消费者不直接假设磁盘安装位置。
+该标识只用于诊断和交接，不能作为可直接打开的物理路径。提供方 Skill 负责读取自身资料，消费者不拼接用户缓存目录或其他插件安装路径。
+
+### 5.6 能力发现协议
+
+1. 消费者从当前会话公开的 Skill 清单判断提供方是否可用。
+2. 已发现对应提供方时，由 Agent 使用其 Profile Skill 获取能力上下文。
+3. 未发现提供方时返回 `missing`，继续执行核心通用流程。
+4. 提供方只读取自身 `references/manifest.json` 和资料，不读取其他插件目录。
+5. Profile 契约校验器在仓库开发和发布阶段校验提供方，不充当运行时注册中心。
+6. 逻辑标识出现在诊断结果中时，同时携带提供方、Skill 和资料用途；消费者不得把它转换为本机绝对路径。
+
+该协议避免核心插件依赖缓存目录，也避免把 Agent 的 Skill 选择描述成确定性代码调用。
 
 ## 6. 项目画像设计
 
@@ -351,20 +388,12 @@ python:profile/references/testing/index.md
     "type": "multi-module"
   },
   "technology": {
-    "languages": [
+    "languages": ["Python"],
-      {
-        "name": "python",
-        "version": "3.12",
-        "profile": "python/default",
-        "evidence": ["pyproject.toml"]
-      }
-    ],
     "frameworks": [
       {
         "name": "fastapi",
         "version": "0.115.0",
-        "profile": "python/fastapi-0",
+        "profile": "python/fastapi-0"
-        "evidence": ["uv.lock"]
       }
     ],
     "buildTools": [],
@@ -375,7 +404,23 @@ python:profile/references/testing/index.md
       "id": "api",
       "root": ".",
       "kind": "backend",
-      "profiles": ["python/default", "python/fastapi-0"]
+      "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": {
@@ -388,10 +433,10 @@ python:profile/references/testing/index.md
 
 ### 6.2 字段规则
 
-- `technology.languages` 从字符串数组兼容扩展为对象数组，记录版本、Profile 和证据。
+- 顶层 `technology` 保持 Schema 1 的字段类型，作为旧消费者可读取的仓库概要。
-- `technology.frameworks` 延续已有对象语义，新增 `evidence`。
+- `modules[].technology` 记录模块级语言、框架、精确版本、证据和 Profile 偏好。
 - `modules` 描述多模块仓库中的技术边界；单模块项目仍生成一个根模块。
-- `modules[].profiles` 只记录已安装、已匹配且经过初始化确认的 Profile。
+- `modules[].preferredProfiles` 记录项目确认的 Profile 偏好，不代表当前机器已经安装对应插件。
 - `commands` 继续记录项目文件或用户确认的真实命令，不由公共 Profile 直接覆盖。
 - 识别证据使用项目相对路径；运行时输出和用户机器绝对路径不进入共享画像。
 
@@ -479,7 +524,7 @@ sequenceDiagram
 
 Profile 选择按以下顺序执行：
 
-1. 使用项目画像中已确认且当前已安装的 Profile。
+1. 使用项目画像中已确认的 Profile 偏好，并检查当前会话是否发现对应提供方。
 2. Profile 未记录时，根据精确版本匹配唯一候选。
 3. 多个候选同时匹配时，优先选择范围更窄且框架证据更具体的候选。
 4. 仍不能唯一确定时，不自动选择，返回候选和差异。
@@ -549,7 +594,7 @@ Profile 选择按以下顺序执行：
 | --- | --- | --- |
 | `dev:review-java` | 保留入口，改为读取 Java Profile | 稳定后评估迁入 Java 插件 |
 | `guidance` 公共后端规则 | 保留中性规则 | Java/Python 专项内容迁入对应插件 |
-| `guidance` 版本路由 | 扩展为调用 `profile:resolve` | 旧文档改为契约说明入口 |
+| `guidance` 版本路由 | 按目标模块读取当前会话已发现的提供方 | 旧文档改为契约说明入口 |
 | `knowledge:init` 探测规则 | 保留通用扫描 | 技术专项识别由提供方补充 |
 | `project.json` 模板 | 保留 Schema 1 兼容读取 | 初始化确认后写 Schema 2 |
 | `dev` 后端 Skill | 逐个接入 Profile | 完成后移除重复专项资料 |

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

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

.craftkit/project.json

@@ -30,7 +30,10 @@
       "plugins/doc",
       "plugins/git",
       "plugins/knowledge",
-      "plugins/skill"
+      "plugins/skill",
+      "plugins/profile",
+      "plugins/java",
+      "plugins/python"
     ]
   },
   "dependencies": {

CHANGELOG.md

@@ -12,14 +12,16 @@
 
 - `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 复制整套工作流；仅当专项能力具备独立安装、发布或维护需求时再评估拆分插件。
-- 补充 Python 专项支持，优先增加 `review-python`，并为现有后端实现与测试 Skill 建立 Python 版本、`pyproject.toml`、pytest、Ruff、mypy/pyright 及 FastAPI、Django、Flask 的按需资料路由。
 - 补充前端工程质量专项支持，增加 `test-frontend` 和 `review-typescript`，分别覆盖单元、组件与集成测试，以及 TypeScript 类型安全与模块契约。
-- 建立按项目真实依赖选择的语言与框架 profile，优先覆盖 Java、Python、React、Vue、Next.js、Nuxt 及相关构建、状态和测试工具；未确认精确版本时不默认最新版本，不跨版本混用规则。
 - 增加命令环境探测与指令适配辅助 Skill：识别操作系统、Shell/终端类型及版本、Codex 可用功能工具、命令行工具来源与版本，生成当前任务的环境能力快照，并按探测结果选择经过验证的默认指令；覆盖 PowerShell、Windows PowerShell、CMD、Bash、Zsh 等环境中的路径、引号、转义、编码、管道、退出码和标准输出/错误流差异。
 - 为 Git 建立版本与仓库状态 profile：根据 Git 版本选择 `checkout`、`switch`、`restore`、Worktree、分支跟踪和安全目录等命令形式，固定参数顺序并兼容含空格或非 ASCII 字符的路径与引用；复合操作按步骤检查退出码，区分“无输出的正常状态”、部分成功和真正失败，避免前置 `fetch` 失败后继续使用陈旧远端引用，也避免后置只读检查的非零退出码掩盖已经成功的写操作。
 - 为 Maven、JDK 和项目构建工具建立版本 profile：优先识别 Maven Wrapper、Maven/JDK 实际版本、`JAVA_HOME`、Toolchains、父 POM、模块结构、激活 profile、`settings.xml` 入口及仓库镜像，再选择全量或 `-pl`/`-am` 等聚焦构建命令；将 Maven 版本不兼容、JDK 不匹配、插件或父 POM 无法解析、缓存问题、编译失败和测试失败分类处理，不用重复执行同一命令代替诊断。
@@ -31,6 +33,12 @@
 - 需求、变更计划、技术设计与 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,11 +97,11 @@ CraftKit 是面向 Codex 的通用插件工具集，覆盖软件开发、文档
 
 | Skill | 用途 |
 | --- | --- |
-| `init` | 初始化或更新项目的 `AGENTS.md` 与 `.craftkit/` 项目资料。 |
+| `init` | 初始化或更新项目上下文、文档目录和持续维护约定。 |
-| `document-output` | 查看或维护文档配置，登记任务文档，并在完成时预览沉淀、归档与清理。 |
+| `document-output` | 管理文档落盘、任务关联、审核状态、持续更新和关闭处置。 |
 | `handoff` | 生成可持续更新的任务交接文档和新任务接续提示词。 |
-| `distill` | 从任务证据中提炼可复用结论、决策和问题经验。 |
+| `distill` | 从任务证据提炼知识，并更新、替代或标记已有结论。 |
-| `lessons` | 初始化、维护和审计项目问题经验库。 |
+| `lessons` | 初始化、修订、标记过时和审计项目问题经验库。 |
 | `trace` | 复盘 Agent 的偏离、漏读或规则失效，并提出改进建议。 |
 | `worklog` | 根据指定日期、时区和作者的 Git 提交生成工作日志。 |
 
@@ -102,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
@@ -124,7 +142,10 @@ CraftKit/
 │  ├─ doc/
 │  ├─ git/
 │  ├─ knowledge/
-│  └─ skill/
+│  ├─ skill/
+│  ├─ profile/
+│  ├─ java/
+│  └─ python/
 └─ README.md
 ```
 
@@ -138,6 +159,6 @@ CraftKit/
 
 ## 本地使用
 
-本仓库提供仓库级 marketplace。将仓库注册为本地 marketplace 后，可按需安装 `dev`、`doc`、`git`、`knowledge` 或 `skill` 插件。
+本仓库提供仓库级 marketplace。将仓库注册为本地 marketplace 后，可按需安装 `dev`、`doc`、`git`、`knowledge`、`skill`、`profile`、`java` 或 `python` 插件。
 
 正式公开发布前，还需补充许可证、公开仓库地址、作者信息、隐私政策和市场素材。

WORKFLOW.md

@@ -163,7 +163,7 @@
 
 1. 确定项目根目录和需求材料范围。
 2. 读取所有适用的 `AGENTS.md`。
-3. 检查 `.craftkit/project.json`、规范索引、构建文件、依赖锁文件和主要源码目录。
+3. 检查 `.craftkit/project.json`、规范索引、文档维护规范、构建文件、依赖锁文件和主要源码目录。
 4. 使用 `guidance` 获取本任务适用的项目规则，并区分明确规则、公共建议和代码现状。
 5. 执行只读 Git 检查，记录当前分支、HEAD、工作树状态、远程引用现状和 worktree 占用情况。
 6. 若项目上下文缺失，只在确有必要时提出 `init`；初始化写入仍遵守该 Skill 的确认步骤。
@@ -173,7 +173,7 @@
 
 ### S1：需求归集与落表
 
-使用 `requirements` 处理原始需求。输入可以是完整需求文档，也可以是聊天记录、口头描述转写、邮件、会议纪要、Bug 描述、截图文字或零散技术说明。
+使用 `requirements` 处理原始需求。先检索同主题的现有需求并更新权威文档；只有不存在可维护的当前文档时才新建。输入可以是完整需求文档，也可以是聊天记录、口头描述转写、邮件、会议纪要、Bug 描述、截图文字或零散技术说明。
 
 需求文档至少包含：
 
@@ -227,6 +227,8 @@
 
 设计产物应使用 `REQ-*` 关联需求，并为关键方案使用 `DES-*` 编号。数据库、API、前端和后端设计相互引用，不能产生字段、枚举、状态或错误语义冲突。
 
+设计前检索相关已有文档，优先更新当前权威设计。共享长期文档的新建或实质修改应进入 `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 的准确区分。
+- 实现与当前有效文档的一致性，以及本次影响的长期文档是否已经同步；待审核、过时和历史材料不能冒充当前基线。
 
 对于审核发现：
 
@@ -441,6 +445,7 @@ G5 批准后：
 - 代码效果已通过 G4；
 - 提交范围与信息已通过 G5；
 - 本地提交已创建并核对内容；
+- 本次影响的长期文档已同步，需要作为当前依据的文档审核状态为 `approved`；
 - 任务文档已生成关闭预览；已确认的沉淀、归档和删除均已验证，延后项已明确记录；
 - 使用独立 Worktree 时，其生命周期已经结束并安全移除；若用户明确要求保留现场，则任务状态应说明生命周期尚未结束及分支占用路径；
 - 未发生未经授权的 push、合并、发布、生产操作或历史改写。

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

@@ -1,6 +1,6 @@
 {
   "name": "dev",
-  "version": "0.4.3",
+  "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

@@ -9,4 +9,4 @@ description: 分析 CSV、表格或结构化 Bug 清单，规范化字段、去
 
 输出总量、状态、严重度、模块、时间和重复项统计，并区分数据事实、合理推断和待确认项。分类规则和时间范围必须透明；样本不足时不外推。默认只生成对话报告；用户要求保存时读取 `.craftkit/project.json` 的 `documents` 配置，过程报告使用 `workRoot`，共享报告使用 `designRoot`。不得自动修改 Bug 状态、分派人员或修复代码。
 
-写入后在 `workRoot/<task>/task.json` 登记本次过程或共享文档；已有记录时保守合并，只更新本任务拥有的文件。登记结构遵循 `knowledge:document-output` 的生命周期规则，不修改项目级默认配置。
+落盘前检索同主题的需求、设计、规范或知识，优先更新已有权威文档。共享长期文档新建或实质修改后按 `.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

@@ -15,7 +15,7 @@ description: 基于项目需求、现有契约和对应版本官方规范设计
 4. 输出路径与方法、参数位置、请求响应模型、错误、兼容、弃用和测试清单。
 5. 默认在对话中输出；用户要求保存设计文档时读取 `.craftkit/project.json` 的 `documents` 配置，过程设计使用 `workRoot`，共享设计使用 `designRoot`，不改变接口自身的路径设计。
 
-写入后在 `workRoot/<task>/task.json` 登记本次过程或共享文档；已有记录时保守合并，只更新本任务拥有的文件。登记结构遵循 `knowledge:document-output` 的生命周期规则，不修改项目级默认配置。
+落盘前检索同主题的需求、设计、规范或知识，优先更新已有权威文档。共享长期文档新建或实质修改后按 `.craftkit/standards/document-maintenance.md` 更新审核状态；排版和错字修正不改变状态。`r`n`r`n写入后在 `workRoot/<task>/task.json` 登记本次创建、更新或引用的文档及 `relationship`；已有记录时保守合并。关联旧文档不转移所有权，也不产生删除权限；不修改项目级默认配置。
 6. 未确认的业务规则和框架封装列为待确认，不生成实现代码。
 
 项目规则高于公共建议；不得默认最新 OpenAPI 版本或把内部接口模式写成通用规则。

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

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

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

@@ -16,6 +16,6 @@ description: 设计前端请求边界、视图模型、状态所有权、缓存
 5. 输出数据流、所有权、转换边界、并发策略、错误策略和测试点，不预设字段或请求封装。
 6. 用户要求保存设计文档时读取 `.craftkit/project.json` 的 `documents` 配置，过程设计使用 `workRoot`，共享设计使用 `designRoot`。
 
-写入后在 `workRoot/<task>/task.json` 登记本次过程或共享文档；已有记录时保守合并，只更新本任务拥有的文件。登记结构遵循 `knowledge:document-output` 的生命周期规则，不修改项目级默认配置。
+落盘前检索同主题的需求、设计、规范或知识，优先更新已有权威文档。共享长期文档新建或实质修改后按 `.craftkit/standards/document-maintenance.md` 更新审核状态；排版和错字修正不改变状态。`r`n`r`n写入后在 `workRoot/<task>/task.json` 登记本次创建、更新或引用的文档及 `relationship`；已有记录时保守合并。关联旧文档不转移所有权，也不产生删除权限；不修改项目级默认配置。
 
 具体 API 字段映射交由 `prepare-api`，页面组合交由 `design-frontend`。

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

@@ -16,7 +16,7 @@ description: 基于需求、现有前端代码和项目规范设计页面清单
 5. API 契约需要映射时交由 `prepare-api`，并在设计中记录所需接口、字段和未决项。
 6. 按 [设计输出](references/output.md) 展示方案和风险；用户要求落盘时读取 `.craftkit/project.json` 的 `documents` 配置，过程设计使用 `workRoot`，共享设计使用 `designRoot`。
 
-写入后在 `workRoot/<task>/task.json` 登记本次过程或共享文档；已有记录时保守合并，只更新本任务拥有的文件。登记结构遵循 `knowledge:document-output` 的生命周期规则，不修改项目级默认配置。
+落盘前检索同主题的需求、设计、规范或知识，优先更新已有权威文档。共享长期文档新建或实质修改后按 `.craftkit/standards/document-maintenance.md` 更新审核状态；排版和错字修正不改变状态。`r`n`r`n写入后在 `workRoot/<task>/task.json` 登记本次创建、更新或引用的文档及 `relationship`；已有记录时保守合并。关联旧文档不转移所有权，也不产生删除权限；不修改项目级默认配置。
 
 ## 边界
 

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

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

@@ -16,7 +16,7 @@ description: 分析软件需求或问题的现状、影响范围、依赖顺序
 5. 输出按依赖排序的步骤，每步包含目标、证据、修改范围、输入、产物、验证和停止条件。
 6. 默认在对话中展示；用户要求保存时读取 `.craftkit/project.json` 的 `documents` 配置，过程计划使用 `workRoot`，共享计划使用 `designRoot`，后续设计沿用同一任务目录。
 
-写入后在 `workRoot/<task>/task.json` 登记本次过程或共享文档；已有记录时保守合并，只更新本任务拥有的文件。登记结构遵循 `knowledge:document-output` 的生命周期规则，不修改项目级默认配置。
+落盘前检索同主题的需求、设计、规范或知识，优先更新已有权威文档。共享长期文档新建或实质修改后按 `.craftkit/standards/document-maintenance.md` 更新审核状态；排版和错字修正不改变状态。`r`n`r`n写入后在 `workRoot/<task>/task.json` 登记本次创建、更新或引用的文档及 `relationship`；已有记录时保守合并。关联旧文档不转移所有权，也不产生删除权限；不修改项目级默认配置。
 
 ## 边界
 

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

@@ -16,7 +16,7 @@ description: 对照前端需求或设计与现有 API 契约，整理接口清
 5. 按 [评审清单](references/review.md) 检查错误、分页、精度、时间、空值、权限和兼容风险。
 6. 默认在对话中输出；用户要求保存时读取 `.craftkit/project.json` 的 `documents` 配置，过程映射使用 `workRoot`，共享映射使用 `designRoot`。
 
-写入后在 `workRoot/<task>/task.json` 登记本次过程或共享文档；已有记录时保守合并，只更新本任务拥有的文件。登记结构遵循 `knowledge:document-output` 的生命周期规则，不修改项目级默认配置。
+落盘前检索同主题的需求、设计、规范或知识，优先更新已有权威文档。共享长期文档新建或实质修改后按 `.craftkit/standards/document-maintenance.md` 更新审核状态；排版和错字修正不改变状态。`r`n`r`n写入后在 `workRoot/<task>/task.json` 登记本次创建、更新或引用的文档及 `relationship`；已有记录时保守合并。关联旧文档不转移所有权，也不产生删除权限；不修改项目级默认配置。
 
 ## 边界
 

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/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.5.0",
+  "version": "0.6.0",
   "description": "项目初始化、任务交接、复盘与知识沉淀工作流。",
   "author": {
     "name": "CraftKit"

plugins/knowledge/skills/init/SKILL.md

@@ -5,7 +5,7 @@ description: 初始化或更新项目的 AGENTS.md 与 .craftkit 项目资料；
 
 # 项目初始化
 
-建立可持续维护的项目上下文，使后续 Agent 能识别项目用途、技术栈、代码边界、内部依赖标识和适用规范。只初始化 Agent 与知识资料，不默认生成业务代码。
+建立可持续维护的项目上下文，使后续 Agent 能识别项目用途、模块级技术栈、代码边界、内部依赖标识和适用规范。只初始化 Agent 与知识资料，不默认生成业务代码。
 
 ## 选择模式
 
@@ -21,15 +21,15 @@ 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/document-maintenance.md`；存在前端能力时同时准备 `.craftkit/standards/frontend/components.md` 的最小索引。
 7. 已有文件必须先完整读取并做保守合并；不明确的用户章节和字段原样保留，不直接覆盖。
 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`。成熟项目从依赖清单、锁文件、组件目录、类型和现有调用提取；空项目根据用户已确认的技术选型或授权参考提议填写。未知组件库或版本保持为空，不根据框架名称自行猜测。
 

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

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

@@ -15,6 +15,16 @@
 - `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。
+
+模块根使用项目相对正斜线路径。目标路径命中多个模块时采用最长根；同长度重复根视为配置冲突。
+
 ## 文档目录
 
 | 字段 | 默认值 | 用途 |

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.2",
+  "version": "0.3.0",
   "description": "项目规范检索与维护工具。",
   "author": {
     "name": "CraftKit"

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`；涉及需求、设计、规范或知识时同时读取命中的文档维护规则，只继续读取索引命中的域、路由和正文。
-6. 项目资料未覆盖主题时，读取[公共基线索引](references/guidance/index.md)，只加载当前任务需要的规则。
+6. 当前会话发现对应语言提供方时，由提供方读取自身 Profile 资料；未发现时报告 `missing`，不扫描插件缓存。
-7. 索引缺失或没有命中时，才在相应目录做受控关键词搜索；不得先递归加载整个知识库。
+7. 项目资料和已发现的技术提供方均未覆盖主题时，读取[公共基线索引](references/guidance/index.md)，只加载当前任务需要的规则。
+8. 索引缺失或没有命中时，才在相应目录做受控关键词搜索；不得先递归加载整个知识库。
 
 目录布局和优先级的详细说明见[检索布局](references/layout.md)。