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

.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 | 完成后移除重复专项资料 |