# 多语言插件架构改造计划

## 1. 文档目标

本计划用于将 CraftKit 从“通用工作流中按需补充技术资料”演进为“核心工作流、技术 Profile 和项目知识分层协作”的多语言插件体系。

首个交付目标是打通 Java 与 Python 两种后端技术栈，使项目初始化、知识检索、后端设计、实现、测试和专项审查能够依据项目真实依赖选择对应能力。后续语言和框架沿用同一契约扩展，不复制整套工作流。

本计划只定义目标架构、职责边界、实施批次和验收口径，不直接调整现有 Skill、插件清单或项目配置格式。

## 2. 建设原则

- 核心工作流保持技术中立：需求、设计、实现、测试和交付流程只定义共同步骤与统一产物。
- 技术差异由能力包维护：语言、框架、构建、测试和审查规则放入可独立演进的技术 Profile。
- 项目事实决定路由：语言、版本、框架和工具必须来自构建文件、锁文件、源码或用户确认。
- 项目规则优先于公共规则：公共 Profile 提供默认能力，项目知识库保存当前项目的补充和覆盖规则。
- 能力按需加载：一个任务只读取当前阶段、语言和框架所需资料，不把所有技术内容装入上下文。
- 缺少增强能力时可回退：未安装语言插件或无法确认版本时，核心 Skill 继续执行通用流程，并明确未覆盖边界。
- 插件按维护价值拆分：首期以 Java、Python 和 Frontend 为能力包边界，不为每个框架创建独立插件。

规则优先级固定为：

1. 用户本次明确要求。
2. 目标目录适用的 `AGENTS.md` 和项目本地规范。
3. `.craftkit/project.json` 中选定的技术 Profile。
4. 已安装语言或框架能力包的公共规则。
5. CraftKit 核心工作流的通用规则。

## 3. 目标架构

路由和回退规则见第 6 节。整体调用关系如下：

```mermaid
flowchart LR
    A[项目初始化] --> B[技术栈探测]
    B --> C[项目画像 project.json]
    C --> D[Profile 解析]
    D --> J[Java 能力包]
    D --> P[Python 能力包]
    D --> F[Frontend 能力包]
    J --> W[核心工作流]
    P --> W
    F --> W
    K[项目规范与知识库] --> W
    W --> O[统一设计、代码、测试与审查产物]
```

### 3.1 分层职责

| 层级 | 核心职责 | 不负责事项 |
| --- | --- | --- |
| 核心工作流 | 定义初始化、设计、实现、测试、审查和交付的共同流程与产物 | 不内置完整语言或框架规则 |
| Profile 解析 | 根据项目画像解析能力、资料入口、命令和版本范围 | 不猜测未确认技术栈，不生成业务产物 |
| 技术能力包 | 提供语言、框架、构建、测试和专项审查知识 | 不保存具体业务项目的专属规则 |
| 项目知识库 | 保存项目规范、技术决策、内部组件和已验证经验 | 不复制公共语言和框架文档 |

### 3.2 建议插件边界

目标插件名称在实施阶段结合市场命名和现有清单最终确认，职责先按以下边界规划：

| 插件 | 主要内容 | 首期范围 |
| --- | --- | --- |
| `core` | 通用设计、实现、测试、审查及 Profile 路由协议 | 由现有 `dev`、`knowledge` 等插件逐步演进，不立即物理合并 |
| `profile` | 技术栈探测、Profile 解析和能力契约校验 | 可先作为现有 `knowledge:init` 的内部能力验证 |
| `java` | Java、JDK、Maven、Gradle、Spring 和 Java 专项审查资料 | 迁移现有 Java 能力，作为契约基准实现 |
| `python` | Python、包管理、FastAPI、Django、Flask、测试和专项审查资料 | 新增最小可用能力包 |
| `frontend` | TypeScript、React、Vue、Next.js、Nuxt 和前端工程质量资料 | 后续按同一契约接入 |

首期不要求立即移动现有目录。先在当前插件结构中验证契约和路由，稳定后再决定是否拆分为独立可安装插件，避免目录迁移与能力改造同时进行。

## 4. Profile 能力契约

每个技术能力包必须提供统一入口，供初始化和核心工作流解析。契约至少包含以下信息：

| 字段 | 含义 | 要求 |
| --- | --- | --- |
| `id` | Profile 唯一标识 | 使用稳定的小写标识，不包含项目名称 |
| `kind` | `language`、`framework`、`build` 或 `frontend` | 必填 |
| `versionRange` | 当前资料适用版本范围 | 未声明时不得给出版本专属结论 |
| `detect` | 可验证的识别证据 | 只使用文件、依赖和源码事实 |
| `capabilities` | 支持的工作流能力 | 使用统一能力标识 |
| `references` | 各能力的资料入口 | 使用能力包内相对路径 |
| `commands` | 构建、测试和检查命令的选择规则 | 不能覆盖项目已验证命令 |
| `fallback` | 能力缺失或版本不匹配时的处理 | 必须明确可继续范围和停止条件 |

首期统一能力标识：

```text
project-detection
knowledge-routing
backend-design
backend-implementation
backend-testing
language-review
framework-review
command-resolution
```

契约载体可以使用 JSON、YAML 或 Markdown 索引。第一阶段先确定字段语义和解析规则，再选择最终格式；不得同时维护多份等价清单。

### 4.1 Python 能力包最小契约示例

以下内容仅用于说明字段关系，实施时以最终契约文件为准：

```yaml
id: python
kind: language
versionRange: ">=3.9,<3.14"
detect:
  manifests:
    - pyproject.toml
    - requirements.txt
  lockFiles:
    - uv.lock
    - poetry.lock
    - pdm.lock
    - Pipfile.lock
capabilities:
  - project-detection
  - knowledge-routing
  - backend-design
  - backend-implementation
  - backend-testing
  - language-review
references:
  backend-design: references/backend/index.md
  backend-testing: references/testing/index.md
  language-review: references/review/index.md
fallback: 使用核心工作流，只报告有项目证据支持的通用结论
```

## 5. 项目画像调整

`.craftkit/project.json` 继续作为项目事实入口，不承担公共规则正文。现有 `technology`、`commands` 和 `guidance` 字段保留，后续通过兼容方式补充已解析 Profile 和证据来源。

建议补充的信息如下：

| 信息 | 示例 | 来源 |
| --- | --- | --- |
| 语言及精确版本 | Python 3.12、Java 17 | 版本文件、构建配置、运行时或用户确认 |
| 框架及精确版本 | FastAPI 0.115、Spring Boot 3.3 | 依赖清单和锁文件 |
| 包与构建工具 | uv、Poetry、Maven Wrapper | 项目文件 |
| 质量工具 | pytest、Ruff、mypy、JUnit | 配置和依赖 |
| 数据访问工具 | SQLAlchemy、Alembic、MyBatis | 依赖和源码 |
| Profile 选择 | `python/default`、`fastapi/0.x` | 已安装能力包与版本匹配结果 |
| 识别证据 | `pyproject.toml`、`pom.xml` | 工作区相对路径 |

画像调整必须满足以下兼容规则：

- 现有 `schemaVersion: 1` 项目仍可被读取。
- 新字段缺失时按未知处理，不自动写入默认最新版。
- Profile 标识只有在能力包真实存在且版本匹配时才写入。
- 项目命令优先保存项目已定义的 Wrapper、脚本或任务入口。
- 共享画像不记录用户机器绝对路径、凭据或完整连接信息。

## 6. 初始化、路由与回退流程

### 6.1 初始化流程

1. `knowledge:init` 执行通用只读扫描，识别构建文件、锁文件、源码根和现有 `.craftkit` 内容。
2. Profile 解析器根据已安装能力包匹配语言和框架探测规则。
3. 初始化结果区分“已确认”“从文件识别”“存在冲突”和“待确认”四类信息。
4. 用户确认无法从项目事实确定的版本、框架或命令。
5. 初始化 Skill 合并写入 `.craftkit/project.json`，语言能力包不直接修改项目文件。
6. 初始化完成后分别验证画像格式、Profile 可解析性、知识入口和一个真实项目命令。

### 6.2 工作流路由

核心 Skill 按以下顺序读取能力：

1. 确认目标文件所属模块和 `.craftkit/project.json` 中的技术栈。
2. 根据当前任务解析所需能力标识，例如 `backend-design`。
3. 加载匹配的语言 Profile，再加载框架 Profile。
4. 读取项目本地规范和知识，将其作为公共规则的补充或覆盖。
5. 发生版本冲突时停止使用冲突资料，并列出缺少的确认信息。
6. 按核心 Skill 的统一产物契约输出结果。

### 6.3 回退规则

| 场景 | 行为 |
| --- | --- |
| 未安装对应语言能力包 | 执行通用工作流，明确语言专项规则未覆盖 |
| 已安装能力包但版本不匹配 | 不跨版本套用资料，提示需要匹配 Profile 或官方证据 |
| 项目同时包含多种语言 | 按目标模块分别解析，不选择仓库级单一语言覆盖全部模块 |
| 无法确认目标模块 | 先展示候选模块和证据，补齐范围后继续 |
| 项目规则与公共 Profile 冲突 | 采用项目规则，并记录冲突来源和影响 |
| 框架 Profile 缺失 | 使用语言 Profile 和通用工作流，不猜测框架行为 |

## 7. Java 与 Python 能力范围

### 7.1 Java 基准能力包

Java 能力包优先复用现有 `review-java` 和后端 Skill 已验证规则，用于检验契约能否承载存量能力。

- 探测：`pom.xml`、Maven Wrapper、Gradle 文件、JDK 配置和模块结构。
- 设计：Spring、事务、依赖注入、DTO、持久化和异步边界。
- 实现：Java 版本、构建工具、代码结构和项目约定。
- 测试：JUnit、Mockito、Spring Test 和项目测试命令。
- 审查：类型、资源、异常、并发、序列化和公开契约。

### 7.2 Python 首期能力包

Python 首期覆盖可形成后端闭环的共同能力：

- 探测：`pyproject.toml`、常见依赖文件、锁文件、Python 版本文件和源码布局。
- 包管理：pip、uv、Poetry、PDM 和 Pipenv，只选择项目已有工具。
- 设计：模块边界、Pydantic Schema、依赖注入、事务、异步和配置边界。
- 实现：类型标注、异常处理、资源管理、同步与异步调用以及依赖约束。
- 测试：pytest、unittest、pytest-asyncio 和框架测试客户端。
- 质量：Ruff、mypy、pyright、Black 等工具按项目配置路由。
- 数据访问：SQLAlchemy、Alembic 和 Django ORM 按真实依赖路由。
- 框架：首个端到端样例使用 FastAPI，Django 和 Flask 在契约稳定后补齐。
- 审查：新增 `review-python`，只报告有代码证据和明确影响的问题。

### 7.3 前端协作边界

前端 Skill 不因后端使用 Python 而复制实现。前后端通过统一 API 契约协作：

- Python 能力包负责从路由、Pydantic Schema、序列化器或 OpenAPI 提取后端契约证据。
- `design-api` 和 `prepare-api` 负责形成统一的请求、响应、错误、分页、鉴权和版本约定。
- 前端 Profile 根据 TypeScript、React、Vue 等真实技术栈消费契约。
- 后端语言专属模型不得直接成为前端组件和状态设计的默认依据。

## 8. 项目知识库适配

公共技术知识和项目知识必须分开维护：

| 知识类型 | 维护位置 | 示例 |
| --- | --- | --- |
| 语言稳定规则 | 语言能力包 | Python 异步语义、Java 资源管理 |
| 框架版本规则 | 语言能力包的框架资料 | FastAPI 依赖注入、Spring 事务 |
| 工具规则 | 对应技术能力包 | pytest、Ruff、Maven、Gradle |
| 项目开发规范 | `.craftkit/standards/` | 包结构、命名、错误码和测试要求 |
| 项目技术决策 | `.craftkit/knowledge/decisions/` | 选择 uv、禁用同步数据库访问 |
| 已验证项目经验 | `.craftkit/knowledge/pitfalls/` | 项目特有故障及复现、规避方法 |

`guidance` 负责统一检索入口。语言能力包提供公共资料索引，项目初始化只登记当前项目实际适用的入口，不复制整套公共知识到项目目录。

## 9. 分阶段实施计划

### 阶段 P0：契约和存量能力盘点

**任务**

- 盘点 `init`、后端设计、实现、测试、审查和 `guidance` 的输入、输出与资料入口。
- 列出现有 Java、前端和通用规则的实际位置，识别重复和语言耦合内容。
- 定义 Profile 字段、能力标识、版本匹配、覆盖优先级和回退规则。
- 确定契约的唯一权威文件及校验方式。

**产物**

- Profile 契约规范。
- 存量能力映射表。
- 首期目录和插件边界决策。

**完成标准**

- 同一个核心 Skill 可以通过契约描述 Java 与 Python 两种能力入口。
- 契约能够表达缺失、版本不匹配、多模块和项目覆盖场景。

### 阶段 P1：Java 基准 Profile

**任务**

- 将现有 Java 专项规则映射到统一能力标识。
- 建立 Java、JDK、Maven/Gradle 和首个 Spring Profile 入口。
- 让一个现有后端 Skill 通过 Profile 入口读取 Java 资料。
- 保持现有 Java Skill 的触发和输出行为兼容。

**产物**

- Java Profile。
- Java 资料索引。
- 契约兼容性验证记录。

**完成标准**

- Spring Boot 样例项目可解析语言、版本、构建工具和对应能力。
- 改造前已有的 Java 审查规则没有丢失或被无关 Profile 覆盖。

### 阶段 P2：Python 最小能力包

**任务**

- 建立 Python 探测规则、版本规则和包管理工具路由。
- 建立 Python 后端设计、实现、测试和审查资料入口。
- 新增 `review-python` 专项 Skill。
- 以 FastAPI、pytest、Ruff 和一种类型检查器形成最小闭环。

**产物**

- Python Profile 与资料索引。
- `review-python`。
- FastAPI 示例验证矩阵。

**完成标准**

- 不安装未声明工具，不默认最新版本，不混用同步与异步规则。
- 能够对一个真实 FastAPI 项目完成设计、实现指导、测试建议和专项审查。

### 阶段 P3：初始化和项目画像接入

**任务**

- 扩展 `knowledge:init` 的技术栈探测和 Profile 解析步骤。
- 设计 `.craftkit/project.json` 的兼容升级方案。
- 支持多模块、多语言和冲突证据记录。
- 验证旧版项目画像的读取和保守合并。

**产物**

- 新版项目画像 Schema 与迁移规则。
- 初始化 Skill 改造。
- Java、Python 和混合仓库初始化样例。

**完成标准**

- 初始化能够生成可追溯的 Profile 选择结果。
- 旧项目无需一次性重写即可继续使用。

### 阶段 P4：核心后端工作流接入

**任务**

- 依次改造 `design-backend`、`implement-backend` 和 `test-backend`。
- 将语言专属判断替换为能力标识和资料入口解析。
- 保持设计文档、实现交付和测试报告的统一格式。
- 增加能力缺失和版本冲突的回退说明。

**产物**

- 支持 Java/Python 路由的三个核心后端 Skill。
- 两种语言的端到端对照结果。

**完成标准**

- 同一请求在 Java 与 Python 项目中加载不同技术资料，但保持相同工作流阶段。
- 核心 Skill 中不新增大段按语言复制的条件规则。

### 阶段 P5：知识库和专项框架扩展

**任务**

- 将公共语言资料接入 `guidance` 的统一检索入口。
- 补充 Django、Flask、SQLAlchemy、Alembic 和 Django ORM 路由。
- 按真实使用需求补充 Spring 和 Java 工具版本资料。
- 建立公共资料与项目知识之间的引用和覆盖规则。

**产物**

- Java/Python 知识索引。
- 框架与工具 Profile。
- 知识检索验证场景。

**完成标准**

- 查询能够定位到当前项目实际语言、框架和版本的资料。
- 公共资料没有被重复复制到项目 `.craftkit` 目录。

### 阶段 P6：插件拆分与独立发布评估

**任务**

- 根据前五阶段的真实依赖评估 Java、Python、Frontend 是否拆为独立插件。
- 明确插件安装依赖、缺失提示、版本兼容和独立发布策略。
- 更新插件清单、README、CHANGELOG 和版本号。
- 建立每个能力包的独立静态校验和场景回归。

**产物**

- 最终插件目录。
- 安装与兼容说明。
- 发布和回滚方案。

**完成标准**

- 单独安装核心插件仍可执行通用流程。
- 安装 Java 或 Python 插件后只增强对应技术能力。
- 一个语言插件升级失败不会破坏其他语言工作流。

## 10. 首个开发迭代

首个迭代只实现“Profile 契约 + Java/Python 双 Profile + 一个核心 Skill 路由”，避免同时改造全部插件。

建议任务顺序：

1. 新增 Profile 契约规范和能力清单。
2. 选择 `design-backend` 作为首个核心消费者。
3. 将现有 Java 设计资料映射为 Java Profile。
4. 创建 Python 基础 Profile 和后端设计资料入口。
5. 使用一个 Spring Boot 项目和一个 FastAPI 项目执行相同设计请求。
6. 验证版本识别、资料选择、项目规则覆盖和能力缺失回退。
7. 契约通过后再进入项目画像和其他 Skill 改造。

本迭代不包含：

- 物理拆分或发布新的 Java、Python 插件。
- 一次性迁移所有现有资料。
- Django、Flask 和全部前端框架适配。
- 自动安装语言工具或修改项目依赖。
- 改造 Git、文档转换和发布类 Skill。

## 11. 验证矩阵

| 场景 | 预期结果 |
| --- | --- |
| Java 17 + Spring Boot 3 + Maven Wrapper | 选择匹配的 Java、Spring 和 Maven 能力，优先使用 Wrapper 命令 |
| Python 3.12 + FastAPI + uv | 选择 Python、FastAPI 和 uv 能力，只使用项目已声明工具 |
| Python 项目未配置 Ruff | 不生成必须执行 Ruff 的结论，可将其作为待确认建议 |
| Python 版本未知 | 使用版本无关规则，版本专属结论标记为待确认 |
| 单仓库同时包含 Java 和 Python 模块 | 按目标模块分别解析 Profile |
| 已安装核心插件但未安装 Python 能力包 | 通用后端流程继续，明确 Python 专项能力缺失 |
| 项目规范覆盖公共 Profile | 采用项目规范并保留来源 |
| Profile 版本不匹配 | 停止加载冲突资料，不默认升级项目技术栈 |
| 旧版 `project.json` | 正常读取，缺失字段按未知处理 |

每阶段至少执行以下验证：

- 静态校验：目录、frontmatter、引用路径、插件清单和契约格式。
- 路由校验：语言、框架、版本、能力和回退选择符合项目证据。
- 场景校验：使用真实或最小可运行项目执行目标 Skill。
- 回归校验：现有 Java 和通用工作流的触发、权限及输出边界不退化。

## 12. 风险与控制

| 风险 | 控制措施 |
| --- | --- |
| Profile 过细导致安装和维护复杂 | 首期按语言聚合框架资料，有独立维护价值后再拆分 |
| 核心 Skill 与语言包形成隐式强依赖 | 契约必须定义能力发现和缺失回退 |
| 同一规则在多个位置重复 | 为契约、公共资料和项目规则分别指定唯一权威入口 |
| 初始化误判技术栈 | 保存识别证据，冲突和低置信信息交由用户确认 |
| 不同版本规则混用 | Profile 声明版本范围，未匹配时不加载版本专属结论 |
| 多语言仓库被单一 Profile 覆盖 | 技术栈和 Profile 支持模块级绑定 |
| 一次改造范围过大 | 先完成一个核心 Skill 的双语言闭环，再逐项迁移 |
| 插件拆分破坏已有用户入口 | 先保持逻辑分层，物理拆分放到最后评估 |

## 13. 总体验收标准

- 核心工作流中不复制 Java、Python 等语言的完整流程。
- Java 与 Python 能力包遵循同一 Profile 契约并可独立维护。
- 初始化能基于证据选择语言、框架、工具和匹配版本。
- 后端设计、实现、测试和审查能够读取当前模块对应能力。
- 前端通过统一 API 契约与不同后端语言协作。
- 公共技术知识和项目专属知识具有清晰边界及稳定入口。
- 缺少语言插件、版本未知或能力不匹配时存在明确回退行为。
- 现有项目画像和 Java 工作流可以兼容迁移。
- 新增其他语言时只需实现能力契约，不需要复制核心工作流。

## 14. 里程碑

| 里程碑 | 交付结果 | 对应阶段 |
| --- | --- | --- |
| M1 契约成立 | Profile 契约通过 Java/Python 静态建模验证 | P0 |
| M2 基准可用 | Java Profile 接入一个现有核心 Skill | P1 |
| M3 Python 闭环 | FastAPI 项目完成设计、测试和审查最小链路 | P2 |
| M4 初始化贯通 | 项目画像可以稳定选择 Java/Python Profile | P3 |
| M5 工作流贯通 | 三个核心后端 Skill 支持双语言路由 | P4 |
| M6 知识贯通 | 公共与项目知识可按语言、框架和版本检索 | P5 |
| M7 可独立交付 | 完成插件拆分评估、回归和发布准备 | P6 |