From c6c88b8beefe1d71c9abcbfb37d1db3e67eeeb50 Mon Sep 17 00:00:00 2001 From: "zhiye.sun" Date: Thu, 3 Sep 2026 13:30:44 +0800 Subject: [PATCH] =?UTF-8?q?docs(architecture):=20=E6=95=B4=E7=90=86?= =?UTF-8?q?=E5=A4=9A=E8=AF=AD=E8=A8=80=E6=96=B9=E6=A1=88=E4=B8=8E=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E7=AE=A1=E7=90=86=E7=BA=A6=E5=AE=9A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...LTI-LANGUAGE-PLUGIN-ARCHITECTURE-DESIGN.md | 849 ++++++++++++++++++ ...MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-PLAN.md | 459 ++++++++++ CHANGELOG.md | 5 + README.md | 1 + WORKFLOW.md | 2 +- 5 files changed, 1315 insertions(+), 1 deletion(-) create mode 100644 .craftkit/designs/multi-language-plugin/MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-DESIGN.md create mode 100644 .craftkit/designs/multi-language-plugin/MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-PLAN.md 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 new file mode 100644 index 0000000..840c61e --- /dev/null +++ b/.craftkit/designs/multi-language-plugin/MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-DESIGN.md @@ -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` 使用 `/` 格式，并在发布后保持稳定。 +- `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 +:/ +``` + +例如： + +```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 端到端场景。 +- 实施可拆分：六个批次均有文件范围、任务和验收标准。 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 new file mode 100644 index 0000000..7058c7a --- /dev/null +++ b/.craftkit/designs/multi-language-plugin/MULTI-LANGUAGE-PLUGIN-ARCHITECTURE-PLAN.md @@ -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 | diff --git a/CHANGELOG.md b/CHANGELOG.md index 51f4732..bf3bac5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/README.md b/README.md index d5ef1df..eea03ea 100644 --- a/README.md +++ b/README.md @@ -89,6 +89,7 @@ CraftKit 是面向 Codex 的通用插件工具集，覆盖软件开发、文档 | Skill | 用途 | | --- | --- | | `init` | 初始化或更新项目的 `AGENTS.md` 与 `.craftkit/` 项目资料。 | +| `document-output` | 查看、解释或维护项目的过程、共享设计和归档文档配置。 | | `handoff` | 生成可持续更新的任务交接文档和新任务接续提示词。 | | `distill` | 从任务证据中提炼可复用结论、决策和问题经验。 | | `lessons` | 初始化、维护和审计项目问题经验库。 | diff --git a/WORKFLOW.md b/WORKFLOW.md index cc0eb99..9c9f55f 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -227,7 +227,7 @@ 设计产物应使用 `REQ-*` 关联需求，并为关键方案使用 `DES-*` 编号。数据库、API、前端和后端设计相互引用，不能产生字段、枚举、状态或错误语义冲突。 -若现有项目没有明确文档目录，智能体应在 G2 前提出建议路径并取得确认，不能自行制造固定目录约定。 +落盘前读取 `.craftkit/project.json` 的 `documents`：开发中的需求、计划、设计和验证记录使用 `workRoot`，用户明确要求共享或正式交付时使用 `designRoot`。缺少 `workRoot` 时回退到 `.craftkit/local/tasks/`；共享目录缺失或规则冲突时，在 G2 前提出建议路径并取得确认。`archiveRoot` 只用于另行授权的归档。 ### S4：创建开发分支