diff --git a/.craftkit/designs/multi-language-plugin/MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-DESIGN.md b/.craftkit/designs/multi-language-plugin/MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-DESIGN.md index 840c61e..f0cad96 100644 --- a/.craftkit/designs/multi-language-plugin/MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-DESIGN.md +++ b/.craftkit/designs/multi-language-plugin/MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-DESIGN.md @@ -1,10 +1,16 @@ +--- +reviewStatus: pending +reviewedAt: null +replacedBy: null +--- + # 多语言插件架构设计与实施方案 ## 1. 设计目标 本设计将 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 修改。 - 未确认精确版本时不能默认最新版本，也不能跨主版本混用规则。 +### 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 负责“执行业务工作流”。项目知识库提供当前项目的覆盖规则。 @@ -129,12 +155,12 @@ plugins/profile/ └─ validate_profile.py ``` -`profile:resolve` 是唯一工厂入口，承担以下职责： +`profile:resolve` 是契约和解析规则入口。消费者可在该 Skill 已发现时使用其匹配规则，但不能假设它能枚举或调用其他插件。它承担以下职责： 1. 接收目标目录、任务所需能力和项目画像。 2. 确认目标属于哪个模块。 3. 从项目文件识别语言、框架、版本和工具证据。 -4. 根据能力提供方返回的信息完成匹配。 +4. 根据当前会话已经发现的能力提供方返回信息完成匹配。 5. 合并项目覆盖规则并输出标准能力上下文。 6. 在缺失、冲突或版本不匹配时返回明确的回退结果。 @@ -328,7 +354,18 @@ gaps: [] 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. 项目画像设计 @@ -351,20 +388,12 @@ python:profile/references/testing/index.md "type": "multi-module" }, "technology": { - "languages": [ - { - "name": "python", - "version": "3.12", - "profile": "python/default", - "evidence": ["pyproject.toml"] - } - ], + "languages": ["Python"], "frameworks": [ { "name": "fastapi", "version": "0.115.0", - "profile": "python/fastapi-0", - "evidence": ["uv.lock"] + "profile": "python/fastapi-0" } ], "buildTools": [], @@ -375,7 +404,23 @@ python:profile/references/testing/index.md "id": "api", "root": ".", "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": { @@ -388,10 +433,10 @@ python:profile/references/testing/index.md ### 6.2 字段规则 -- `technology.languages` 从字符串数组兼容扩展为对象数组，记录版本、Profile 和证据。 -- `technology.frameworks` 延续已有对象语义，新增 `evidence`。 +- 顶层 `technology` 保持 Schema 1 的字段类型，作为旧消费者可读取的仓库概要。 +- `modules[].technology` 记录模块级语言、框架、精确版本、证据和 Profile 偏好。 - `modules` 描述多模块仓库中的技术边界；单模块项目仍生成一个根模块。 -- `modules[].profiles` 只记录已安装、已匹配且经过初始化确认的 Profile。 +- `modules[].preferredProfiles` 记录项目确认的 Profile 偏好，不代表当前机器已经安装对应插件。 - `commands` 继续记录项目文件或用户确认的真实命令，不由公共 Profile 直接覆盖。 - 识别证据使用项目相对路径；运行时输出和用户机器绝对路径不进入共享画像。 @@ -479,7 +524,7 @@ sequenceDiagram Profile 选择按以下顺序执行： -1. 使用项目画像中已确认且当前已安装的 Profile。 +1. 使用项目画像中已确认的 Profile 偏好，并检查当前会话是否发现对应提供方。 2. Profile 未记录时，根据精确版本匹配唯一候选。 3. 多个候选同时匹配时，优先选择范围更窄且框架证据更具体的候选。 4. 仍不能唯一确定时，不自动选择，返回候选和差异。 @@ -549,7 +594,7 @@ Profile 选择按以下顺序执行： | --- | --- | --- | | `dev:review-java` | 保留入口，改为读取 Java Profile | 稳定后评估迁入 Java 插件 | | `guidance` 公共后端规则 | 保留中性规则 | Java/Python 专项内容迁入对应插件 | -| `guidance` 版本路由 | 扩展为调用 `profile:resolve` | 旧文档改为契约说明入口 | +| `guidance` 版本路由 | 按目标模块读取当前会话已发现的提供方 | 旧文档改为契约说明入口 | | `knowledge:init` 探测规则 | 保留通用扫描 | 技术专项识别由提供方补充 | | `project.json` 模板 | 保留 Schema 1 兼容读取 | 初始化确认后写 Schema 2 | | `dev` 后端 Skill | 逐个接入 Profile | 完成后移除重复专项资料 | diff --git a/.craftkit/designs/multi-language-plugin/MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-PLAN.md b/.craftkit/designs/multi-language-plugin/MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-PLAN.md index 7058c7a..327afa5 100644 --- a/.craftkit/designs/multi-language-plugin/MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-PLAN.md +++ b/.craftkit/designs/multi-language-plugin/MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-PLAN.md @@ -1,459 +1,60 @@ +--- +reviewStatus: pending +reviewedAt: null +replacedBy: null +--- + # 多语言插件架构改造计划 -## 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 | +## 1. 文档职责 + +本文只跟踪多语言插件架构的实施批次、前置依赖、验证门禁和完成状态。架构、契约、项目画像及运行机制以[《多语言插件架构设计与实施方案》](MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-DESIGN.md)为唯一依据。 + +详细执行记录位于 `.craftkit/local/tasks/multi-language-plugin/`，不在本文复制过程步骤。 + +## 2. 当前决策 + +- 首期建立 `profile`、`java` 和 `python` 独立插件骨架，但在安装组合通过前不声明可独立交付。 +- Profile 插件维护静态契约、匹配规则和校验器，不扫描插件缓存，也不把 Skill 协作描述为函数调用。 +- 消费者从当前会话已发现的提供方 Skill 获取专项能力；提供方缺失时执行通用回退。 +- `knowledge:init` 是项目画像的唯一写入者，`guidance` 是项目规则与公共规则的合并入口。 +- Schema 2 先由消费者双读，再由初始化入口写入。 +- 插件安装状态不进入共享项目画像。 + +## 3. 实施批次 + +| 批次 | 目标 | 前置依赖 | 核心产物 | 状态 | +| --- | --- | --- | --- | --- | +| P0 | 收敛文档并验证平台机制 | 无 | 架构决策、最小插件骨架、验证记录 | 已完成（运行时验证转 P6） | +| P1 | 建立 Profile 静态契约 | P0 | JSON Schema、解析规则、校验器 | 已完成 | +| P2 | 建立 Java/Python 最小提供方 | P1 | 双提供方 manifest 和专项资料 | 已完成静态实现 | +| P3 | 接入首个核心消费者 | P2 | `design-backend` 双语言路由 | 已完成实现，待新会话验证 | +| P4 | 建立 Schema 1/2 双读 | P3 | 模块级画像、迁移与回滚规则 | 已完成实现 | +| P5 | 逐个接入核心消费者 | P4 | 设计、实现、测试、审查闭环 | 已完成实现，待新会话验证 | +| P6 | 验证独立安装和发布 | P5 | 安装矩阵、兼容矩阵、发布材料 | 部分完成，运行时验证待处理 | +| P7 | 按需求扩展框架和前端 | P6 | 可独立验证的增量能力 | 待执行 | + +## 4. 阶段门禁 + +每个批次必须分别记录： + +1. 实际修改范围。 +2. 静态校验结果。 +3. 真实或最小可运行场景验证结果。 +4. 未验证边界。 +5. 停止条件检查。 +6. 是否允许进入下一批次。 + +静态清单或脚本校验通过不代表 Codex 运行时行为已经验证。跨插件发现、Skill 激活和缺失回退必须在安装后的新会话中验证。 + +## 5. 总体验收 + +- Java 与 Python 提供方遵循同一契约。 +- 核心 Skill 不复制语言专属工作流。 +- Schema 1 和 Schema 2 均可读取。 +- 多模块仓库按目标路径解析技术栈。 +- 缺少提供方、版本未知和版本不兼容都有确定回退。 +- 项目规范覆盖公共 Profile 时保留双方来源。 +- Spring Boot 和 FastAPI 完成同一请求的端到端对照。 +- 核心、Profile、Java 和 Python 的安装组合全部验证。 +- 现有 Java 与通用工作流没有回归。