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