feat(dev): 新增开发分析与设计 Skill

2026-08-25 17:39:57 +08:00
parent 6bc3d84018
commit 5b9fa51b6e
25 changed files with 318 additions and 13 deletions
@@ -12,7 +12,7 @@ CraftKit 是一组面向 Codex 插件市场的中性 Skill 工具。项目从通

 | 插件 | 用途 | 当前状态 |
 | --- | --- | --- |
-| `dev` | 软件设计、编码、审查与测试 | 已迁移 `component`、`style`、`form` |
+| `dev` | 软件设计、编码、审查与测试 | 已迁移 `component`、`style`、`form`、`plan-change`、`design-backend`、`design-frontend`、`prepare-api` |
 | `doc` | 文档转换、整理与写作 | 已迁移 `format-md`、`docx-to-md`、`md-to-docx`、`xlsx-to-md`、`archive` |
 | `git` | 分支、提交、变更提取与集成 | 已迁移 `commit-msg`、`branch`、`identity`、`export`、`integrate` |
 | `knowledge` | 项目初始化、交接、复盘与经验 | 已迁移 `handoff`、`init`、`trace`、`distill`、`lessons`、`worklog` |
@@ -121,10 +121,10 @@ plan-change

 建议顺序：

-1. `plan-change`
-2. `design-backend`
-3. `design-frontend`
-4. `prepare-api`
+1. `plan-change`（已完成）
+2. `design-backend`（已完成）
+3. `design-frontend`（已完成）
+4. `prepare-api`（已完成）
 5. `implement-backend`
 6. `implement-frontend`
 7. `review-code`
@@ -239,3 +239,4 @@ plan-change
 - [x] 完成知识管理批次：`trace`、`distill`、`lessons`、`worklog`。
 - [x] 完成前端辅助批次：`component`、`style`、`form`，并以精确触发替代独立路由。
 - [x] 完成项目规范维护能力：`guidance-edit`。
+- [x] 完成开发分析与设计批次：`plan-change`、`design-backend`、`design-frontend`、`prepare-api`。
@@ -20,7 +20,10 @@
    "source-a:1b7843684955ce5a": {
      "sourcePathHash": "1b7843684955ce5a0beb3ef16c6e751c5e9eb5a17409084fed806b74ec0c522f",
      "sourceSha256": "eabf9fabba7b751a0b85547b141d92821f461e8d904f4fb15d5746eca1965769",
-      "status": "pending"
+      "status": "migrated",
+      "target": "plugins/dev/skills/plan-change",
+      "targetVersion": "0.1.0",
+      "reviewedAt": "2026-08-25"
    },
    "source-a:5d76364c580248a5": {
      "sourcePathHash": "5d76364c580248a54449e5ec7ede0079f19df21fef95922d3538fb82c095b181",
@@ -30,12 +33,18 @@
    "source-a:a0b791b6dac96b81": {
      "sourcePathHash": "a0b791b6dac96b8180df558278b5c7ef643b4806cc4e534ffe6395b9236666d3",
      "sourceSha256": "603b4fd6e4b52c9b5d368c5ba6bdff333d32f3e03e9b5393686b0729eb4ffc7c",
-      "status": "pending"
+      "status": "migrated",
+      "target": "plugins/dev/skills/design-backend",
+      "targetVersion": "0.1.0",
+      "reviewedAt": "2026-08-25"
    },
    "source-a:0124493991019160": {
      "sourcePathHash": "0124493991019160a06c65d6200db0a50abb212a79bcefab4be4631be85c07c8",
      "sourceSha256": "eca051fb929c5bd74c34564631872c2d6755b4427a7c4fbb4d6240eeb6331ee3",
-      "status": "pending"
+      "status": "migrated",
+      "target": "plugins/dev/skills/prepare-api",
+      "targetVersion": "0.1.0",
+      "reviewedAt": "2026-08-25"
    },
    "source-a:b80c5913e146321c": {
      "sourcePathHash": "b80c5913e146321ca5efef5e45f11172e79c542855c2ae65478fe253414e66ea",
@@ -45,7 +54,10 @@
    "source-a:cd36505dd718e889": {
      "sourcePathHash": "cd36505dd718e88966ad74421c65e6c7cccd71a1436f2843eb8cfa7a4f1534c5",
      "sourceSha256": "a0137bd615988c49a8967b4e0129618858268b90391ab2ed912cc72f338f41f8",
-      "status": "pending"
+      "status": "migrated",
+      "target": "plugins/dev/skills/design-frontend",
+      "targetVersion": "0.1.0",
+      "reviewedAt": "2026-08-25"
    },
    "source-a:e14c1a3cd3b041f6": {
      "sourcePathHash": "e14c1a3cd3b041f650d71eb5701c71c0de76cb7a909e9a419f1d277159cd763a",
@@ -93,7 +105,11 @@
    "source-b:3f05784a0a86ba5f": {
      "sourcePathHash": "3f05784a0a86ba5fb8f268797ca1ceabe8ca237b3c9d3c4396e622c1ef421cc6",
      "sourceSha256": "9a39cd7af138519fe3de3f7a3cb031ea5da1243ff5779504a13215fa03a5a3c2",
-      "status": "pending"
+      "status": "superseded",
+      "target": "plugins/dev/skills/design-backend",
+      "targetVersion": "0.1.0",
+      "reason": "后端设计能力已与另一来源合并并按项目证据中性重建",
+      "reviewedAt": "2026-08-25"
    },
    "source-b:41934e94a1922a1b": {
      "sourcePathHash": "41934e94a1922a1bbccec4377246e67bd84f1ffbd2b9d1bf4027c1ed15d12260",
@@ -108,7 +124,11 @@
    "source-b:f171b05e239c2e2c": {
      "sourcePathHash": "f171b05e239c2e2c5f2a0c636dfac0c2456b9d3b5215fdaa7fb86a33be1ee188",
      "sourceSha256": "cd16d17204009509e6798badab786b9bd4d3969117b3ad4b9005337b76a4791b",
-      "status": "pending"
+      "status": "superseded",
+      "target": "plugins/dev/skills/plan-change",
+      "targetVersion": "0.1.0",
+      "reason": "开发计划能力已与另一来源合并为通用变更计划",
+      "reviewedAt": "2026-08-25"
    },
    "source-b:3b29e4441f642e65": {
      "sourcePathHash": "3b29e4441f642e65d442fd284f37a45364cebb7a6c53446c354d15c70e532410",
@@ -126,7 +146,11 @@
    "source-b:c49d1db42acd7220": {
      "sourcePathHash": "c49d1db42acd722071d61420be58ba8ccbc54f5370bdf951abfb5981914271cf",
      "sourceSha256": "20875df87fb84c7d5830d6eaaff544c9e32e3f9a2359ed099de5f3a4a36eaa7d",
-      "status": "pending"
+      "status": "superseded",
+      "target": "plugins/dev/skills/design-frontend",
+      "targetVersion": "0.1.0",
+      "reason": "前端设计能力已与另一来源合并并移除内部组件与固定版本约束",
+      "reviewedAt": "2026-08-25"
    },
    "source-b:9a3f3d3c43d9017a": {
      "sourcePathHash": "9a3f3d3c43d9017a080a9832df5b975e6ddd3f8c39947ee768aeb973fc23974e",
@@ -0,0 +1,58 @@
+"""开发分析与设计批次的职责边界测试。"""
+
+from pathlib import Path
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[2]
+SKILLS = ROOT / "plugins" / "dev" / "skills"
+
+
+def read_skill(name: str) -> str:
+    """合并读取 Skill 入口及引用文件。"""
+    folder = SKILLS / name
+    files = [folder / "SKILL.md", *sorted((folder / "references").glob("*.md"))]
+    return "\n".join(path.read_text(encoding="utf-8") for path in files)
+
+
+class DevDesignBatchTest(unittest.TestCase):
+    """验证四个 Skill 的通用化设计和相互边界。"""
+
+    def test_plan_is_evidence_based_and_does_not_implement(self) -> None:
+        content = read_skill("plan-change")
+        self.assertIn("不执行设计或编码", content)
+        self.assertIn("验收标准", content)
+        self.assertIn("运行行为标为待验证", content)
+        self.assertNotIn("docs/{moduleCode}", content)
+
+    def test_backend_design_uses_project_version(self) -> None:
+        content = read_skill("design-backend")
+        self.assertIn("精确版本", content)
+        self.assertIn("guidance", content)
+        self.assertIn("事务边界", content)
+        self.assertIn("不生成业务代码", content)
+
+    def test_frontend_design_composes_existing_helpers(self) -> None:
+        content = read_skill("design-frontend")
+        for helper in ("component", "style", "form", "prepare-api"):
+            self.assertIn(helper, content)
+        self.assertIn("不编造组件", content)
+        self.assertIn("不跨版本混用", content)
+
+    def test_prepare_api_does_not_assume_contract(self) -> None:
+        content = read_skill("prepare-api")
+        self.assertIn("不预设请求客户端", content)
+        self.assertIn("未匹配字段", content)
+        self.assertIn("不发起真实请求", content)
+        self.assertIn("不能反向覆盖", content)
+
+    def test_descriptions_are_distinct(self) -> None:
+        descriptions = []
+        for name in ("plan-change", "design-backend", "design-frontend", "prepare-api"):
+            text = (SKILLS / name / "SKILL.md").read_text(encoding="utf-8")
+            descriptions.append(text.split("---", 2)[1])
+        self.assertEqual(4, len(set(descriptions)))
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -1,6 +1,6 @@
 {
  "name": "dev",
-  "version": "0.2.0",
+  "version": "0.3.0",
  "description": "通用软件设计、编码、审查与测试工作流。",
  "author": {
    "name": "CraftKit"
@@ -0,0 +1,24 @@
+---
+name: design-backend
+description: 基于需求、现有后端代码和项目规范设计模块边界、服务职责、数据影响、事务、错误处理和接口需求。适用于新功能或复杂后端变更的技术设计；直接编码、单纯数据库建模、HTTP 契约细化或前端设计不应触发。
+---
+
+# 后端设计
+
+形成可由实现人员执行和验证的后端设计，不生成业务代码，不内置特定 Java、Spring 或公司框架规则。
+
+## 工作流
+
+1. 读取需求、项目元数据、适用规范、依赖清单和相关后端实现，确认语言、框架及精确版本。
+2. 按 [范围分析](references/scope.md) 明确现状、边界、参与者和约束。
+3. 设计模块职责、调用关系、数据所有权、事务边界、并发策略、错误语义、权限和可观测性。
+4. 数据库或 HTTP 契约需要详细设计时，记录输入和待决项，交由相应专项 Skill；本 Skill 保持整体一致性。
+5. 按 [设计输出](references/output.md) 展示方案、备选项和风险，并用 [评审清单](references/review.md) 自检。
+6. 默认在对话中输出；用户要求落盘时，先确认项目约定路径并保守写入。
+
+## 边界
+
+- 项目规则通过 `guidance` 获取；不存在的规范、框架能力和依赖接口不得猜测。
+- 版本从 `.craftkit/project.json`、构建文件、锁文件或源码证据确认，不默认最新版本。
+- 对现有系统的设计先追踪真实调用链和数据流，区分已验证事实与建议。
+- 不把接口示例、表结构草案或伪代码视为已实施行为。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "后端设计"
+  short_description: "设计后端边界、数据影响和运行约束"
+  default_prompt: "使用 $design-backend 为当前需求制定后端技术设计。"
@@ -0,0 +1,13 @@
+# 后端设计输出
+
+按任务需要包含：
+
+1. 目标、范围外事项和现状证据。
+2. 模块与服务职责、依赖方向及关键时序。
+3. 领域对象、状态变化和数据所有权。
+4. 持久化影响、事务、并发和一致性策略。
+5. 接口需求、错误语义、权限和审计需求。
+6. 兼容、迁移、回滚、监控和测试策略。
+7. 备选方案、取舍、待确认项和实现交接清单。
+
+避免用固定文档模板掩盖缺失信息；简单变更可以缩减为最小充分设计。
@@ -0,0 +1,10 @@
+# 后端设计评审
+
+- 职责和依赖方向是否清晰，是否引入循环或重复所有权。
+- 事务边界是否覆盖真实状态变化，并说明失败后的状态。
+- 并发、幂等、重试、超时和外部调用顺序是否明确。
+- 输入信任边界、权限、敏感数据和审计要求是否覆盖。
+- 数据与接口变化是否具有兼容和迁移方案。
+- 日志、指标、追踪和告警是否围绕关键失败设计。
+- 测试是否覆盖正常、边界、拒绝、并发和恢复路径。
+- 框架版本和依赖能力是否有项目证据。
@@ -0,0 +1,11 @@
+# 后端设计范围
+
+设计前确认：
+
+- 入口、调用者、下游依赖和外部系统边界。
+- 当前模块职责、数据所有权和已有扩展点。
+- 输入、输出、状态变化、失败路径和幂等要求。
+- 事务、一致性、并发、批量规模、性能和安全约束。
+- 数据迁移、兼容期、灰度、回滚和可观测性需求。
+
+只有需求或项目证据支持的内容才能作为约束；产品决策、运行参数和外部契约缺失时列为待确认。
@@ -0,0 +1,24 @@
+---
+name: design-frontend
+description: 基于需求、现有前端代码和项目规范设计页面清单、路由、状态、交互、组件组合和数据流。适用于新页面或复杂前端变更的设计；组件单项选型、纯视觉样式、表单局部布局、接口映射或直接编码不应触发。
+---
+
+# 前端设计
+
+将用户场景转化为可实现的页面级契约，不生成完整前端代码，不绑定固定框架、组件库或页面模板。
+
+## 工作流
+
+1. 读取需求、`.craftkit/project.json`、依赖和锁文件、适用规范及相关页面，确认框架与精确版本。
+2. 按 [页面规划](references/pages.md) 明确场景、页面、路由、复用和状态边界。
+3. 按 [数据设计](references/data.md) 设计视图模型、状态所有权、加载与提交转换、错误和权限呈现。
+4. 组件、样式和表单结构分别复用 `component`、`style`、`form` 的证据与结论；本 Skill 负责页面级组合。
+5. API 契约需要映射时交由 `prepare-api`，并在设计中记录所需接口、字段和未决项。
+6. 按 [设计输出](references/output.md) 展示方案和风险；用户要求落盘时，先确认项目约定路径。
+
+## 边界
+
+- 不从接口字段描述反向改写已确认的用户文案和交互含义。
+- 不编造组件、属性、事件、接口或业务校验；缺少证据时列为待确认。
+- Vue、React 或其他框架的版本差异由当前项目证据决定，不跨版本混用。
+- 未执行真实渲染、浏览器或辅助技术检查时，不宣称交互验收通过。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "前端设计"
+  short_description: "设计页面、交互、状态和组件组合"
+  default_prompt: "使用 $design-frontend 为当前需求制定前端页面设计。"
@@ -0,0 +1,8 @@
+# 前端数据设计
+
+- 区分服务端数据、页面状态、组件局部状态和可派生状态。
+- 记录初始化、查询、编辑、提交和回显所需的双向转换。
+- 明确加载、空、错误、无权限、部分成功和并发更新状态。
+- 字段含义、必填和条件显示来自需求或契约，不从控件类型推断。
+- 标记大整数、金额、日期、枚举、文件和嵌套对象等边界，但具体转换必须依据真实 API 契约。
+- API 缺失或字段无法对应时保留未匹配项，不用 Mock 假定正式接口。
@@ -0,0 +1,13 @@
+# 前端设计输出
+
+按任务需要包含：
+
+1. 目标、用户场景、现状证据和范围外事项。
+2. 页面清单、路由、入口、复用关系和主要交互流程。
+3. 页面结构、组件组合及其证据来源。
+4. 状态所有权、视图模型、校验来源和数据转换。
+5. API 需求、字段需求及与 `prepare-api` 的待映射项。
+6. 响应式、可访问性、权限、错误和加载状态。
+7. 版本约束、备选方案、待确认问题、验证和实现交接。
+
+设计规模应与变更复杂度相称，不为简单页面生成无用章节。
@@ -0,0 +1,7 @@
+# 页面规划
+
+从用户任务出发识别页面、弹窗、嵌入区域和跨页面流程。每项说明入口、用户角色、主要动作、状态、退出方式和异常路径。
+
+评估新增、编辑、查看等场景是否真正共享结构与行为；只有差异可由清晰契约表达时才复用。路由、导航、缓存、返回行为和权限边界应与项目现有模式一致。
+
+组件抽取以稳定复用关系和清晰职责为依据，不用页面数量或代码行数作为唯一阈值。
@@ -0,0 +1,24 @@
+---
+name: plan-change
+description: 分析软件需求或问题的现状、影响范围、依赖顺序、验证方式和风险，形成可执行变更计划。适用于新功能、增量修改、缺陷修复或重构的实施规划；详细技术设计、代码修改和仅需一步完成的简单操作不应触发。
+---
+
+# 变更计划
+
+把目标转化为基于项目证据的实施步骤，不执行设计或编码，也不把尚未确认的方案写成既定事实。
+
+## 工作流
+
+1. 读取需求、适用的 `AGENTS.md`、`.craftkit/project.json`、相关规范和最小必要源码。
+2. 区分新功能、增量修改、缺陷修复或重构；仅在分类影响计划时询问用户。
+3. 确认当前行为、目标行为、范围外事项、依赖、兼容要求和验收标准。
+4. 根据任务类型读取 [新功能](references/feature.md)、[现有变更](references/change.md) 或 [缺陷与重构](references/fix.md)。
+5. 输出按依赖排序的步骤，每步包含目标、证据、修改范围、输入、产物、验证和停止条件。
+6. 默认在对话中展示；用户要求保存时，先确认项目约定的路径再写入。
+
+## 边界
+
+- 不使用固定模块编码、固定文档目录或不存在的下游 Skill 名称。
+- 无法从源码确认的运行行为标为待验证，不把推断写成事实。
+- 计划应保护现有工作区，并把外部环境、数据迁移和发布验证与本地代码验证分开。
+- 用户要求直接实施且任务简单明确时，不额外制造计划文档。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "变更计划"
+  short_description: "基于项目证据制定可执行的软件变更计划"
+  default_prompt: "使用 $plan-change 分析当前需求并制定可验证的实施计划。"
@@ -0,0 +1,5 @@
+# 现有功能变更计划
+
+先追踪当前入口、调用链、数据流、测试和相邻实现，明确哪些行为必须保持。列出直接修改、受影响消费者、兼容策略和回归范围。
+
+若同一功能存在多个版本或实现，记录实际适用版本和选择证据，不将升级目标冒充当前状态。
@@ -0,0 +1,5 @@
+# 新功能计划
+
+确认用户角色、核心场景、边界、数据所有权、接口边界、前后端范围和上线依赖。步骤通常先完成必要设计与契约确认，再实现、测试和交付；没有对应范围时省略，不为凑流程增加阶段。
+
+识别必须先确认的产品决策、跨团队契约、权限、安全、迁移和兼容问题。计划中区分可以并行的工作与必须串行的依赖。
@@ -0,0 +1,5 @@
+# 缺陷与重构计划
+
+缺陷计划应包含可观察现象、复现条件、证据链、可能根因、验证根因的方法和最小修复边界。尚未定位根因时，先规划诊断，不提前指定修复代码。
+
+重构计划应声明必须保持的外部行为、拆分顺序、兼容过渡、回滚点和等价性验证。性能、安全或数据问题应使用可度量的验收条件。
@@ -0,0 +1,24 @@
+---
+name: prepare-api
+description: 对照前端需求或设计与现有 API 契约，整理接口清单、字段映射、类型转换、缺失项和联调风险。适用于前后端对接准备与契约差异分析；设计新 HTTP API、实现请求代码、运行接口调试或修改页面文案不应触发。
+---
+
+# API 对接准备
+
+把前端需要的数据与可验证 API 契约对应起来，明确差异而不编造接口或直接修改代码。
+
+## 工作流
+
+1. 按 [契约来源](references/sources.md) 确认 API 文档、服务端源码、生成规范或用户材料的范围、版本和可信度。
+2. 读取前端需求、页面设计或相关代码，提取用户可见含义、字段、动作和状态。
+3. 按 [映射规则](references/mapping.md) 建立接口、请求、响应和双向类型转换映射。
+4. 分别列出已匹配、未匹配、冲突、缺失接口和需要后端或产品确认的事项。
+5. 按 [评审清单](references/review.md) 检查错误、分页、精度、时间、空值、权限和兼容风险。
+6. 默认在对话中输出；用户要求保存时，先确认项目约定路径再写入。
+
+## 边界
+
+- API 文档不能反向覆盖已经确认的页面文案、业务含义和交互要求。
+- 不预设请求客户端、响应包裹、分页字段、枚举结构、上传或工作流接口。
+- 不因名称相似自动匹配字段；不确定项必须保留证据和待确认状态。
+- 本 Skill 不设计新 API、不发起真实请求、不生成正式请求代码，也不修改前后端实现。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "接口准备"
+  short_description: "整理前后端接口映射和契约差异"
+  default_prompt: "使用 $prepare-api 分析前端需求与现有 API 契约的映射。"
@@ -0,0 +1,11 @@
+# 映射规则
+
+按页面动作建立接口清单，再分别映射请求和响应：
+
+- 字段的业务含义、路径、必填条件、基数、空值和默认值。
+- 前端表示与传输类型，以及初始化和提交两个方向的转换。
+- 标识符精度、金额精度、日期时间格式与时区、枚举值域和嵌套结构。
+- 查询、分页、排序、筛选、批量和文件传输约定。
+- 成功、业务拒绝、输入错误、认证授权失败和系统失败的呈现需求。
+
+名称不同但含义一致时记录映射证据；名称相同但含义或单位不同时列为冲突。未匹配字段和缺失接口必须完整保留，不用猜测值或临时 Mock 隐藏缺口。
@@ -0,0 +1,11 @@
+# API 对接评审
+
+- 每个页面动作是否有明确接口或缺失说明。
+- 请求方法、路径、参数位置和内容类型是否来自真实契约。
+- 请求与响应字段是否覆盖页面需要，未匹配项是否完整。
+- 双向转换是否处理精度、空值、时区、枚举和嵌套对象。
+- 分页、排序、批量和文件行为是否有契约依据。
+- 错误、权限、幂等、重复提交和并发更新是否可处理。
+- 契约版本、弃用、兼容期和环境差异是否说明。
+- 是否避免从 API 描述反向修改用户已确认的展示文案。
+- 未运行真实联调时，是否明确结果仅为静态契约分析。
@@ -0,0 +1,11 @@
+# 契约来源
+
+优先使用与目标环境和版本一致的契约：
+
+1. 用户指定的正式 OpenAPI 或其他机器可读契约。
+2. 当前项目生成并用于目标环境的接口文档。
+3. 服务端控制器、请求响应模型、校验和契约测试。
+4. 经过项目维护的 Markdown 文档和示例。
+5. 用户明确说明的临时约定。
+
+记录来源路径、版本或提交、生成时间和已知偏差。多个来源冲突时不自动裁决；列出冲突并由契约所有者确认。示例响应只能证明示例形态，不能代替完整字段约束。