Bruce/CraftKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(architecture): 收敛多语言插件设计与执行计划

Browse Source
This commit is contained in:
zhiye.sun
2026-09-03 17:11:35 +08:00
parent e2d29f6005
commit f7ea0dcd86
2 changed files with 123 additions and 477 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.craftkit/designs/multi-language-plugin/MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-DESIGN.md
+65 -20
View File
@@ -1,10 +1,16 @@
---
reviewStatus: pending
reviewedAt: null
replacedBy: null
---
# 多语言插件架构设计与实施方案 # 多语言插件架构设计与实施方案
## 1. 设计目标 ## 1. 设计目标
本设计将 CraftKit 建设为可扩展的多语言插件体系。现有 `dev`、`knowledge` 和 `skill` 插件继续提供通用工作流，新增 Profile 工厂和技术能力插件，使初始化、规范检索、后端设计、实现、测试和审查能够按项目真实技术栈加载 Java、Python 或前端专项知识。 本设计将 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 修改。 - 公共插件不能直接写入业务项目；项目文件统一由当前获得授权的核心 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. 总体设计 ## 3. 总体设计
Profile 工厂负责“识别需求并选择能力”，技术插件负责“提供能力”，核心 Skill 负责“执行业务工作流”。项目知识库提供当前项目的覆盖规则。 Profile 工厂负责“识别需求并选择能力”，技术插件负责“提供能力”，核心 Skill 负责“执行业务工作流”。项目知识库提供当前项目的覆盖规则。
@@ -129,12 +155,12 @@ plugins/profile/
└─ validate_profile.py └─ validate_profile.py
``` ```
`profile:resolve` 是唯一工厂入口，承担以下职责： `profile:resolve` 是契约和解析规则入口。消费者可在该 Skill 已发现时使用其匹配规则，但不能假设它能枚举或调用其他插件。它承担以下职责：
1. 接收目标目录、任务所需能力和项目画像。 1. 接收目标目录、任务所需能力和项目画像。
2. 确认目标属于哪个模块。 2. 确认目标属于哪个模块。
3. 从项目文件识别语言、框架、版本和工具证据。 3. 从项目文件识别语言、框架、版本和工具证据。
4. 根据能力提供方返回的信息完成匹配。 4. 根据当前会话已经发现的能力提供方返回信息完成匹配。
5. 合并项目覆盖规则并输出标准能力上下文。 5. 合并项目覆盖规则并输出标准能力上下文。
6. 在缺失、冲突或版本不匹配时返回明确的回退结果。 6. 在缺失、冲突或版本不匹配时返回明确的回退结果。
@@ -328,7 +354,18 @@ gaps: []
python:profile/references/testing/index.md 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. 项目画像设计 ## 6. 项目画像设计
@@ -351,20 +388,12 @@ python:profile/references/testing/index.md
"type": "multi-module" "type": "multi-module"
}, },
"technology": { "technology": {
"languages": [ "languages": ["Python"],
{
"name": "python",
"version": "3.12",
"profile": "python/default",
"evidence": ["pyproject.toml"]
}
],
"frameworks": [ "frameworks": [
{ {
"name": "fastapi", "name": "fastapi",
"version": "0.115.0", "version": "0.115.0",
"profile": "python/fastapi-0", "profile": "python/fastapi-0"
"evidence": ["uv.lock"]
} }
], ],
"buildTools": [], "buildTools": [],
@@ -375,7 +404,23 @@ python:profile/references/testing/index.md
"id": "api", "id": "api",
"root": ".", "root": ".",
"kind": "backend", "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": { "commands": {
@@ -388,10 +433,10 @@ python:profile/references/testing/index.md
### 6.2 字段规则 ### 6.2 字段规则
- `technology.languages` 从字符串数组兼容扩展为对象数组，记录版本、Profile 和证据。 - 顶层 `technology` 保持 Schema 1 的字段类型，作为旧消费者可读取的仓库概要。
- `technology.frameworks` 延续已有对象语义，新增 `evidence`。 - `modules[].technology` 记录模块级语言、框架、精确版本、证据和 Profile 偏好。
- `modules` 描述多模块仓库中的技术边界；单模块项目仍生成一个根模块。 - `modules` 描述多模块仓库中的技术边界；单模块项目仍生成一个根模块。
- `modules[].profiles` 只记录已安装、已匹配且经过初始化确认的 Profile。 - `modules[].preferredProfiles` 记录项目确认的 Profile 偏好，不代表当前机器已经安装对应插件。
- `commands` 继续记录项目文件或用户确认的真实命令，不由公共 Profile 直接覆盖。 - `commands` 继续记录项目文件或用户确认的真实命令，不由公共 Profile 直接覆盖。
- 识别证据使用项目相对路径；运行时输出和用户机器绝对路径不进入共享画像。 - 识别证据使用项目相对路径；运行时输出和用户机器绝对路径不进入共享画像。
@@ -479,7 +524,7 @@ sequenceDiagram
Profile 选择按以下顺序执行： Profile 选择按以下顺序执行：
1. 使用项目画像中已确认且当前已安装的 Profile。 1. 使用项目画像中已确认的 Profile 偏好，并检查当前会话是否发现对应提供方。
2. Profile 未记录时，根据精确版本匹配唯一候选。 2. Profile 未记录时，根据精确版本匹配唯一候选。
3. 多个候选同时匹配时，优先选择范围更窄且框架证据更具体的候选。 3. 多个候选同时匹配时，优先选择范围更窄且框架证据更具体的候选。
4. 仍不能唯一确定时，不自动选择，返回候选和差异。 4. 仍不能唯一确定时，不自动选择，返回候选和差异。
@@ -549,7 +594,7 @@ Profile 选择按以下顺序执行：
| --- | --- | --- | | --- | --- | --- |
| `dev:review-java` | 保留入口，改为读取 Java Profile | 稳定后评估迁入 Java 插件 | | `dev:review-java` | 保留入口，改为读取 Java Profile | 稳定后评估迁入 Java 插件 |
| `guidance` 公共后端规则 | 保留中性规则 | Java/Python 专项内容迁入对应插件 | | `guidance` 公共后端规则 | 保留中性规则 | Java/Python 专项内容迁入对应插件 |
| `guidance` 版本路由 | 扩展为调用 `profile:resolve` | 旧文档改为契约说明入口 | | `guidance` 版本路由 | 按目标模块读取当前会话已发现的提供方 | 旧文档改为契约说明入口 |
| `knowledge:init` 探测规则 | 保留通用扫描 | 技术专项识别由提供方补充 | | `knowledge:init` 探测规则 | 保留通用扫描 | 技术专项识别由提供方补充 |
| `project.json` 模板 | 保留 Schema 1 兼容读取 | 初始化确认后写 Schema 2 | | `project.json` 模板 | 保留 Schema 1 兼容读取 | 初始化确认后写 Schema 2 |
| `dev` 后端 Skill | 逐个接入 Profile | 完成后移除重复专项资料 | | `dev` 后端 Skill | 逐个接入 Profile | 完成后移除重复专项资料 |
.craftkit/designs/multi-language-plugin/MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-PLAN.md
+58 -457
View File
@@ -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 |