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

多语言插件架构改造计划

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 节。整体调用关系如下：

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	能力缺失或版本不匹配时的处理	必须明确可继续范围和停止条件

首期统一能力标识：

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

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

4.1 Python 能力包最小契约示例

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

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