Files

T

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

2026-09-03 17:11:35 +08:00

34 KiB

Raw Blame History

reviewStatus, reviewedAt, replacedBy

reviewStatus	reviewedAt	replacedBy
pending	null	null

多语言插件架构设计与实施方案

1. 设计目标

本设计将 CraftKit 建设为可扩展的多语言插件体系。现有 dev、knowledge 和 skill 插件继续提供通用工作流，新增 Profile 工厂和技术能力插件，使初始化、规范检索、后端设计、实现、测试和审查能够按项目真实技术栈加载 Java、Python 或前端专项知识。

本文是多语言插件架构的唯一设计依据。《多语言插件架构改造计划》只跟踪实施批次、依赖和验证状态，不重复定义架构。首期建立独立插件骨架并保留旧 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 负责“执行业务工作流”。项目知识库提供当前项目的覆盖规则。

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 依赖方向

dev ──────────┐
knowledge ────┼──> profile contract <── java
skill ────────┘                       <── python
                                      <── frontend

项目 standards/knowledge ──> 覆盖公共 Profile

依赖必须保持单向：

核心插件依赖 Profile 契约，不依赖技术插件内部目录。
技术插件实现契约，不反向调用 dev 或修改项目画像。
Profile 工厂只做解析，不执行设计、编码、测试或审查任务。
技术插件之间不能相互引用内部资料；跨技术协作通过统一契约完成。

4. 插件和目录设计

4.1 Profile 工厂插件

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 已发现时使用其匹配规则，但不能假设它能枚举或调用其他插件。它承担以下职责：

接收目标目录、任务所需能力和项目画像。
确认目标属于哪个模块。
从项目文件识别语言、框架、版本和工具证据。
根据当前会话已经发现的能力提供方返回信息完成匹配。
合并项目覆盖规则并输出标准能力上下文。
在缺失、冲突或版本不匹配时返回明确的回退结果。

validate_profile.py 只校验确定性的契约结构、标识、版本范围格式和引用文件存在性，不负责执行 Agent 路由。

4.2 Java 技术插件

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 技术插件

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 插件。

plugins/frontend/
├─ .codex-plugin/plugin.json
└─ skills/
   ├─ profile/
   ├─ review-typescript/
   └─ test-frontend/

5. Profile 契约设计

5.1 提供方清单

每个技术插件以 references/manifest.json 作为能力清单的唯一权威来源。清单只记录路由元数据，详细规则通过相对路径指向同一插件内的 Markdown 资料。JSON 可由 Python 标准库直接校验，不为契约校验器增加第三方 YAML 解析依赖。

{
  "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 工厂提供以下语义输入：

target: services/order
capabilities:
  - backend-design
task: 为订单服务设计幂等创建流程
projectProfile: .craftkit/project.json

这不是外部 HTTP 接口。它定义 Skill 协作时必须具备的信息，实际内容由 Agent 从用户任务和项目文件构造。

5.4 标准能力上下文

Profile 工厂返回的结果必须区分事实、选择结果、规则入口和缺口：

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 路径标识

跨插件引用使用逻辑标识：

<plugin>:<skill>/<skill 内相对路径>

例如：

python:profile/references/testing/index.md

该标识只用于诊断和交接，不能作为可直接打开的物理路径。提供方 Skill 负责读取自身资料，消费者不拼接用户缓存目录或其他插件安装路径。

5.6 能力发现协议

消费者从当前会话公开的 Skill 清单判断提供方是否可用。
已发现对应提供方时，由 Agent 使用其 Profile Skill 获取能力上下文。
未发现提供方时返回 missing，继续执行核心通用流程。
提供方只读取自身 references/manifest.json 和资料，不读取其他插件目录。
Profile 契约校验器在仓库开发和发布阶段校验提供方，不充当运行时注册中心。
逻辑标识出现在诊断结果中时，同时携带提供方、Skill 和资料用途；消费者不得把它转换为本机绝对路径。

该协议避免核心插件依赖缓存目录，也避免把 Agent 的 Skill 选择描述成确定性代码调用。

6. 项目画像设计

6.1 Schema 版本

.craftkit/project.json 从 schemaVersion: 1 兼容演进至 schemaVersion: 2。版本 2 增加模块级技术栈和 Profile 绑定，保留版本 1 的顶层字段。

建议结构：

{
  "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 初始化流程

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 接入后执行以下步骤：

读取需求、目标模块、项目画像和现有实现。
请求 backend-design 能力。
Profile 工厂解析语言、框架、版本和项目覆盖规则。
技术插件提供当前版本适用的设计资料入口。
design-backend 合并通用边界与专项约束。
输出统一的模块、依赖、数据、事务、错误、权限和测试设计。
输出中标明使用的 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 解析：

用户要求与目标目录 AGENTS.md。
.craftkit/project.json 和目标模块。
项目 .craftkit/standards/ 与 .craftkit/knowledge/。
已解析技术 Profile 的 knowledge-routing 入口。
CraftKit 中性公共基线。
现有代码观察结果。

项目规则与 Profile 冲突时采用项目规则，并在输出中同时给出两者来源。

8. 版本与冲突处理

8.1 Profile 选择

Profile 选择按以下顺序执行：

使用项目画像中已确认的 Profile 偏好，并检查当前会话是否发现对应提供方。
Profile 未记录时，根据精确版本匹配唯一候选。
多个候选同时匹配时，优先选择范围更窄且框架证据更具体的候选。
仍不能唯一确定时，不自动选择，返回候选和差异。
没有版本匹配时，只加载版本中性资料。

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 契约和工厂骨架

新增文件

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

修改文件

.agents/plugins/marketplace.json
README.md
CHANGELOG.md

任务

定义提供方清单和标准能力上下文。
实现契约静态校验器。
编写模块匹配、版本选择、能力状态和回退规则。
注册 profile 插件并补充安装说明。

验收

有效、缺字段、重复标识、无效版本范围和失效引用五类样例均有确定结果。
profile 单独安装时能够解释缺少技术提供方并返回 missing。

11.2 批次 B：Java 基准提供方

新增文件

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

修改文件

.agents/plugins/marketplace.json
plugins/dev/skills/review-java/SKILL.md
plugins/dev/skills/review-java/references/sources.md
README.md
CHANGELOG.md

任务

将现有 Java 规则映射到能力清单。
建立 JDK、Maven/Gradle 和 Spring 的渐进加载入口。
让 dev:review-java 读取 Java Profile；未安装时使用现有最小基线。
使用现有 Java 项目验证路由和回退。

验收

Java 版本和构建工具有项目证据。
Spring 资料只在依赖和版本匹配时加载。
review-java 的现有触发范围和审查输出不退化。

11.3 批次 C：Python 最小提供方

新增文件

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

修改文件

.agents/plugins/marketplace.json
README.md
CHANGELOG.md

任务

支持 pyproject.toml、依赖文件、锁文件和 Python 版本证据。
支持 pip、uv、Poetry、PDM 和 Pipenv 的项目内选择。
建立 Python 通用、FastAPI、pytest、Ruff 和类型检查资料入口。
新增 Python 专项审查 Skill。
使用 FastAPI 项目验证语言、框架、测试和审查能力。

验收

不配置 Ruff、mypy 或 pyright 的项目不会被假定具备对应命令。
同步与异步规则按真实代码和框架配置选择。
Python 版本未知时不输出版本专属语法升级建议。

11.4 批次 D：初始化和画像 Schema 2

修改文件

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

新增文件

plugins/knowledge/skills/init/references/profile-resolution.md
plugins/knowledge/skills/init/references/project-schema-v2.md

任务

将通用扫描与技术提供方探测分离。
增加模块级技术栈和识别证据。
定义 Schema 1 到 Schema 2 的保守合并规则。
初始化结束后调用 Profile 解析做一致性验证。

验收

Java、Python、前后端混合和旧版画像四类项目均能完成初始化。
未安装语言插件时仍能记录技术事实，但 Profile 保持未解析。
已有未知字段和用户章节不会被删除。

11.5 批次 E：规范检索和核心后端消费者

修改文件

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

任务

guidance 将 Profile 知识入口纳入渐进加载顺序。
design-backend 请求 backend-design 能力。
implement-backend 请求 backend-implementation 和 command-resolution。
test-backend 请求 backend-testing 和 command-resolution。
三个核心 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 项目，对两者执行相同任务：

初始化项目画像。
查询后端规范。
设计一个包含事务和外部调用的后端功能。
给出最小实现变更。
生成并运行聚焦测试。
执行语言专项审查。

验证重点：

每一步使用了正确模块和 Profile。
项目已有命令优先于公共建议。
设计产物结构一致，语言实现规则不同。
缺失工具不会被隐式安装或写入项目。
失败结果能够区分项目缺陷、环境问题和 Profile 缺口。

13. 发布方案

13.1 发布顺序

发布 profile 插件及契约。
发布 Java 基准插件。
发布 Python 最小插件。
发布接入新版契约的 knowledge 和 skill 插件。
发布接入新版契约的 dev 插件。
完成一轮双语言端到端回归后，再补充 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 端到端场景。
实施可拆分：六个批次均有文件范围、任务和验收标准。

34 KiB Raw Blame History Unescape Escape

多语言插件架构设计与实施方案

1. 设计目标

2. 现状与约束

2.1 已有能力

2.2 主要缺口

2.3 平台约束

2.4 已验证的平台能力

2.5 待验证边界

3. 总体设计

3.1 插件职责

3.2 依赖方向

4. 插件和目录设计

4.1 Profile 工厂插件

4.2 Java 技术插件

4.3 Python 技术插件

4.4 Frontend 技术插件

5. Profile 契约设计

5.1 提供方清单

5.2 能力标识

5.3 标准能力请求

5.4 标准能力上下文

5.5 路径标识

5.6 能力发现协议

6. 项目画像设计

6.1 Schema 版本

6.2 字段规则

6.3 兼容读取

7. 核心流程设计

7.1 初始化流程

7.2 后端设计流程

7.3 实现和测试流程

7.4 知识检索流程

8. 版本与冲突处理

8.1 Profile 选择

8.2 多模块仓库

8.3 能力状态

9. 可靠性、安全与可观测性

9.1 一致性

9.2 安全边界

9.3 诊断输出

10. 迁移设计

10.1 迁移原则

10.2 存量内容迁移

10.3 回滚

11. 实施方案

11.1 批次 A：Profile 契约和工厂骨架

11.2 批次 B：Java 基准提供方

11.3 批次 C：Python 最小提供方

11.4 批次 D：初始化和画像 Schema 2

11.5 批次 E：规范检索和核心后端消费者

11.6 批次 F：框架补全和前端接入

12. 测试方案

12.1 静态校验

12.2 路由场景

12.3 端到端场景

13. 发布方案

13.1 发布顺序

13.2 版本影响

13.3 安装组合

14. 实现交接清单

15. 设计自检结论

34 KiB

Raw Blame History