---
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 端到端场景。
- 实施可拆分：六个批次均有文件范围、任务和验收标准。