docs(architecture): 整理多语言方案与文档管理约定

2026-09-03 13:30:44 +08:00
parent 9b84ebf036
commit c6c88b8bee
5 changed files with 1315 additions and 1 deletions
@@ -0,0 +1,849 @@
 # 多语言插件架构设计与实施方案
 ## 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 修改。
 - 未确认精确版本时不能默认最新版本，也不能跨主版本混用规则。
 ## 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` 是唯一工厂入口，承担以下职责：
 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 负责读取自身资料，消费者不直接假设磁盘安装位置。
 ## 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": [
      {
        "name": "python",
        "version": "3.12",
        "profile": "python/default",
        "evidence": ["pyproject.toml"]
      }
    ],
    "frameworks": [
      {
        "name": "fastapi",
        "version": "0.115.0",
        "profile": "python/fastapi-0",
        "evidence": ["uv.lock"]
      }
    ],
    "buildTools": [],
    "databases": []
  },
  "modules": [
    {
      "id": "api",
      "root": ".",
      "kind": "backend",
      "profiles": ["python/default", "python/fastapi-0"]
    }
  ],
  "commands": {
    "build": [],
    "test": ["uv run pytest"],
    "check": ["uv run ruff check ."]
  }
 }
 ```
 ### 6.2 字段规则
 - `technology.languages` 从字符串数组兼容扩展为对象数组，记录版本、Profile 和证据。
 - `technology.frameworks` 延续已有对象语义，新增 `evidence`。
 - `modules` 描述多模块仓库中的技术边界；单模块项目仍生成一个根模块。
 - `modules[].profiles` 只记录已安装、已匹配且经过初始化确认的 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` 版本路由 | 扩展为调用 `profile:resolve` | 旧文档改为契约说明入口 |
 | `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 端到端场景。
 - 实施可拆分：六个批次均有文件范围、任务和验收标准。
@@ -0,0 +1,459 @@
 # 多语言插件架构改造计划
 ## 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 |
@@ -20,6 +20,11 @@
 - 为 Maven、JDK 和项目构建工具建立版本 profile：优先识别 Maven Wrapper、Maven/JDK 实际版本、`JAVA_HOME`、Toolchains、父 POM、模块结构、激活 profile、`settings.xml` 入口及仓库镜像，再选择全量或 `-pl`/`-am` 等聚焦构建命令；将 Maven 版本不兼容、JDK 不匹配、插件或父 POM 无法解析、缓存问题、编译失败和测试失败分类处理，不用重复执行同一命令代替诊断。
 - 增加私有 Git/Maven 仓库访问诊断与安全降级：区分沙箱或工具权限、VPN/内网、DNS、代理、TLS/证书、HTTP/HTTPS/SSH 协议、凭据助手、仓库镜像和服务端不可用等原因；只读取完成诊断所需的非敏感配置，不输出令牌、密码或完整凭据，访问受限时保留本地证据并明确远端引用或依赖缓存的新鲜度，获得既有授权后在正确执行环境重试。所有命令失败均输出已执行步骤、实际副作用、失败分类、可安全重试点、替代指令和验证结果。
 ### Changed
 - `knowledge` 插件增加项目文档落盘配置能力；项目初始化写入 `documents.workRoot`、`documents.designRoot` 与 `documents.archiveRoot`，区分本地过程文档、共享设计和历史归档。
 - 需求、变更计划、技术设计与 Bug 分析 Skill 统一按项目文档配置选择任务目录；缺少配置时，过程文档回退到 `.craftkit/local/tasks/`，不再根据根目录说明文件推断落点。
 ## [1.3.0] - 2026-08-31
 ### Added
@@ -89,6 +89,7 @@ CraftKit 是面向 Codex 的通用插件工具集，覆盖软件开发、文档
 | Skill | 用途 |
 | --- | --- |
 | `init` | 初始化或更新项目的 `AGENTS.md` 与 `.craftkit/` 项目资料。 |
 | `document-output` | 查看、解释或维护项目的过程、共享设计和归档文档配置。 |
 | `handoff` | 生成可持续更新的任务交接文档和新任务接续提示词。 |
 | `distill` | 从任务证据中提炼可复用结论、决策和问题经验。 |
 | `lessons` | 初始化、维护和审计项目问题经验库。 |
@@ -227,7 +227,7 @@
 设计产物应使用 `REQ-*` 关联需求，并为关键方案使用 `DES-*` 编号。数据库、API、前端和后端设计相互引用，不能产生字段、枚举、状态或错误语义冲突。
-若现有项目没有明确文档目录，智能体应在 G2 前提出建议路径并取得确认，不能自行制造固定目录约定。
+落盘前读取 `.craftkit/project.json` 的 `documents`：开发中的需求、计划、设计和验证记录使用 `workRoot`，用户明确要求共享或正式交付时使用 `designRoot`。缺少 `workRoot` 时回退到 `.craftkit/local/tasks/`；共享目录缺失或规则冲突时，在 G2 前提出建议路径并取得确认。`archiveRoot` 只用于另行授权的归档。
 ### S4：创建开发分支