feat(dev): 新增公开基线与专项设计 Skill

2026-08-26 10:17:41 +08:00
parent 72398c9f89
commit d1ce2df108
22 changed files with 243 additions and 0 deletions
@@ -0,0 +1,39 @@
+"""公开基线与专项设计 Skill 测试。"""
+
+from pathlib import Path
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[2]
+SKILLS = ROOT / "plugins" / "dev" / "skills"
+NAMES = (
+    "design-api", "design-db", "review-java", "review-frontend",
+    "design-frontend-data", "review-mybatis", "design-workflow",
+)
+
+
+class PublicBaselineBatchTest(unittest.TestCase):
+    """验证公开来源登记和版本边界。"""
+
+    def test_sources_are_official_and_dated(self) -> None:
+        for name in NAMES:
+            source = (SKILLS / name / "references" / "sources.md").read_text(encoding="utf-8")
+            self.assertIn("重建日期：2026-08-25", source)
+            self.assertIn("https://", source)
+
+    def test_project_version_is_not_replaced_by_latest(self) -> None:
+        content = "\n".join(
+            (SKILLS / name / "SKILL.md").read_text(encoding="utf-8") for name in NAMES
+        )
+        self.assertIn("不得默认最新", content)
+        self.assertIn("规则混用", content)
+        self.assertIn("精确版本", content)
+
+    def test_workflow_does_not_embed_approval_rules(self) -> None:
+        content = (SKILLS / "design-workflow" / "SKILL.md").read_text(encoding="utf-8")
+        self.assertIn("不内置审批节点", content)
+        self.assertIn("项目实际流程引擎", content)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,18 @@
+---
+name: design-api
+description: 基于项目需求、现有契约和对应版本官方规范设计或评审 HTTP API。适用于资源边界、方法、状态码、请求响应、兼容和 OpenAPI 契约；前后端字段对接、后端整体设计或直接编码不应触发。
+---
+
+# API 设计
+
+先确认项目协议、OpenAPI 版本、已有接口风格和兼容边界，再形成可实现、可验证的契约。
+
+## 工作流
+
+1. 读取 `.craftkit/project.json`、适用规范、现有契约和调用方证据。
+2. 明确资源、动作、幂等性、认证授权、输入、输出和错误语义。
+3. 方法、状态码、缓存、条件请求和重试语义以 [官方来源](references/sources.md) 及项目版本为依据。
+4. 输出路径与方法、参数位置、请求响应模型、错误、兼容、弃用和测试清单。
+5. 未确认的业务规则和框架封装列为待确认，不生成实现代码。
+
+项目规则高于公共建议；不得默认最新 OpenAPI 版本或把内部接口模式写成通用规则。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "API 设计"
+  short_description: "设计和评审可验证的 HTTP API 契约"
+  default_prompt: "使用 $design-api 为当前需求设计 HTTP API 契约。"
@@ -0,0 +1,8 @@
+# 官方来源
+
+重建日期：2026-08-25。
+
+- HTTP Semantics，RFC 9110：https://www.rfc-editor.org/rfc/rfc9110.html
+- OpenAPI Specification： https://spec.openapis.org/oas/latest.html
+
+RFC 9110 用于 HTTP 方法、状态和协议语义；OpenAPI 仅在项目采用的版本范围内用于契约表达。本文不复制规范正文，使用前应核对项目实际协议版本和官方勘误。IETF 文档受 IETF Trust 条款约束；OpenAPI 规范版权归 Linux Foundation，引用遵循其页面声明。
@@ -0,0 +1,18 @@
+---
+name: design-db
+description: 根据业务数据、访问模式和目标数据库版本设计或评审表、约束、索引、迁移与回滚方案。适用于数据库结构设计和 DDL 方案；ORM 映射检查、后端整体设计或未经确认直接执行数据库变更不应触发。
+---
+
+# 数据库设计
+
+以业务不变量、访问模式和目标数据库真实能力为依据，不套用固定字段、命名或数据库方言。
+
+## 工作流
+
+1. 确认数据库产品、精确版本、字符集、现有模型、数据规模和迁移约束。
+2. 设计实体、关系、主键、约束、类型、索引和数据生命周期。
+3. 按 [官方来源](references/sources.md) 核实目标版本语法及行为，不跨数据库复制 DDL。
+4. 输出结构、约束、索引依据、迁移顺序、兼容、回滚和验证查询。
+5. 默认只给方案；执行 DDL、迁移存量数据或连接数据库需要单独授权。
+
+未知容量、并发和查询模式应标为假设，不凭惯例制造审计字段或业务枚举。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "数据库设计"
+  short_description: "设计表结构、约束、索引和迁移方案"
+  default_prompt: "使用 $design-db 为当前需求设计数据库结构和迁移方案。"
@@ -0,0 +1,9 @@
+# 官方来源
+
+重建日期：2026-08-25。
+
+- PostgreSQL 当前版本 SQL 与数据定义：https://www.postgresql.org/docs/current/sql.html
+- PostgreSQL 数据定义：https://www.postgresql.org/docs/current/ddl.html
+- MySQL 8.4 Reference Manual：https://dev.mysql.com/doc/refman/8.4/en/
+
+只读取与项目数据库产品和精确版本匹配的官方手册。来源用于核实类型、约束、索引、DDL 与迁移行为，不复制手册正文；其他数据库必须补充其官方资料后再给出方言结论。
@@ -0,0 +1,18 @@
+---
+name: design-frontend-data
+description: 设计前端请求边界、视图模型、状态所有权、缓存、并发和请求响应转换。适用于前端数据层与状态流设计；页面结构、HTTP API 设计、接口字段映射或直接编码不应触发。
+---
+
+# 前端数据设计
+
+让传输模型、领域数据、视图状态和组件局部状态边界清晰，并适配项目真实框架与请求封装。
+
+## 工作流
+
+1. 确认框架版本、渲染模式、请求客户端、状态管理和现有数据边界。
+2. 区分服务端状态、共享客户端状态、页面状态、局部状态和可派生状态。
+3. 设计加载、成功、空、错误、取消、重试、竞态、缓存失效和乐观更新行为。
+4. 按 [官方来源](references/sources.md) 核实浏览器请求和框架状态语义。
+5. 输出数据流、所有权、转换边界、并发策略、错误策略和测试点，不预设字段或请求封装。
+
+具体 API 字段映射交由 `prepare-api`，页面组合交由 `design-frontend`。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "前端数据设计"
+  short_description: "设计请求、状态、缓存和视图模型边界"
+  default_prompt: "使用 $design-frontend-data 设计当前页面的数据流和状态边界。"
@@ -0,0 +1,9 @@
+# 官方来源
+
+重建日期：2026-08-25。
+
+- WHATWG Fetch Standard：https://fetch.spec.whatwg.org/
+- React Managing State：https://react.dev/learn/managing-state
+- Vue State Management：https://vuejs.org/guide/scaling-up/state-management.html
+
+Fetch 标准用于请求、响应、取消和浏览器网络语义；框架资料仅在项目实际采用该框架和版本时使用。缓存库、请求库与状态库必须读取项目对应版本官方文档，不能由本 Skill 预设。
@@ -0,0 +1,16 @@
+---
+name: design-workflow
+description: 基于项目现有流程引擎契约、业务状态和用户输入设计任务、状态转换、权限、回退、撤回、幂等和审计。适用于通用业务工作流设计；内部审批规则复刻、流程引擎代码实现或无契约猜测不应触发。
+---
+
+# 工作流设计
+
+以项目实际流程引擎和业务规则为准，不内置审批节点、接口、消息或状态编码。
+
+## 工作流
+
+1. 读取 `.craftkit/project.json`、项目规范、引擎依赖、已有流程定义和业务状态代码。
+2. 明确参与者、任务、状态、转换条件、权限、并发、超时、撤回、退回、终止和补偿。
+3. 设计业务事务与流程事务边界、幂等键、审计、通知和失败恢复。
+4. 需要过程建模时可参考 [官方来源](references/sources.md)，但必须映射回项目真实引擎能力。
+5. 输出状态转换表、时序、异常路径、接口需求、数据需求和验收场景；未确认规则列为待确认。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "工作流设计"
+  short_description: "设计状态、任务、权限和异常流程"
+  default_prompt: "使用 $design-workflow 为当前业务设计可验证的工作流。"
@@ -0,0 +1,7 @@
+# 官方来源
+
+重建日期：2026-08-25。
+
+- OMG BPMN 2.0.2 规格入口：https://www.omg.org/spec/BPMN/
+
+BPMN 仅作为通用过程建模术语和表达参考，不代表项目采用 BPMN，也不替代具体引擎官方文档。若项目使用特定流程引擎，必须读取其对应版本官方资料；本 Skill 不复制 OMG 规范正文或任何内部审批规则。
@@ -0,0 +1,16 @@
+---
+name: review-frontend
+description: 按项目实际前端框架、版本、构建工具和组件契约评审组件边界、状态、渲染、交互、可访问性和性能。适用于前端专项审查；视觉设计、组件选型、直接编码或未确认版本的迁移建议不应触发。
+---
+
+# 前端专项审查
+
+从依赖、锁文件和现有代码确认框架及精确版本，不把 Vue、React 或其他框架的规则混用。
+
+## 工作流
+
+1. 确认范围、版本、构建工具、状态管理、路由和测试方式。
+2. 读取项目规范及目标组件真实契约。
+3. 检查职责、数据流、状态所有权、生命周期、异步竞态、错误状态、可访问性和性能。
+4. 框架结论按 [官方来源](references/sources.md) 读取当前版本资料。
+5. 仅报告有代码证据和用户影响的问题；未渲染或未运行测试时明确边界，不自动修改代码。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "前端审查"
+  short_description: "按项目框架版本专项审查前端代码"
+  default_prompt: "使用 $review-frontend 按当前框架版本审查前端代码。"
@@ -0,0 +1,9 @@
+# 官方来源
+
+重建日期：2026-08-25。
+
+- Vue 3 Guide：https://vuejs.org/guide/introduction
+- Vue 2 Guide：https://v2.vuejs.org/v2/guide/
+- React Learn：https://react.dev/learn
+
+根据项目依赖选择对应框架和主版本资料。Vue 官方页面明确区分 Vue 2 与 Vue 3；React 结论也必须与项目实际版本和渲染模式匹配。本文不复制官方示例或第三方组件规则。
@@ -0,0 +1,16 @@
+---
+name: review-java
+description: 按项目 Java 版本、框架、规范和真实调用上下文评审 Java 代码的正确性、资源管理、并发、异常和可维护性。适用于 Java 专项审查；通用代码审查、直接实现或未确认版本的语法升级不应触发。
+---
+
+# Java 专项审查
+
+先从构建文件和 `.craftkit/project.json` 确认 Java 精确版本，再按项目规范和对应官方规格评审。
+
+## 工作流
+
+1. 确认审查范围、版本、框架、编译选项和相关测试。
+2. 检查类型与空值、异常边界、资源关闭、集合、并发、序列化和公开契约。
+3. 语言结论按 [官方来源](references/sources.md) 路由到当前版本；预览特性不得视为默认可用。
+4. 只报告可复现、有代码证据且影响明确的问题，按严重度给出最小修复建议。
+5. 未运行编译或测试时明确说明，不自动修改代码。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Java 审查"
+  short_description: "按项目版本专项审查 Java 代码"
+  default_prompt: "使用 $review-java 按当前项目版本审查这段 Java 代码。"
@@ -0,0 +1,8 @@
+# 官方来源
+
+重建日期：2026-08-25。
+
+- Java SE 与 JDK 25 规格入口：https://docs.oracle.com/en/java/javase/25/docs/specs/index.html
+- Java Language Specification, Java SE 25：https://docs.oracle.com/javase/specs/jls/se25/html/index.html
+
+Java 25 仅作为可用官方入口示例，不代表项目默认版本。实际审查必须改读项目所用 Java 版本的 Oracle/OpenJDK 官方规格。本文只独立整理审查流程，不复制受限规格正文。
@@ -0,0 +1,16 @@
+---
+name: review-mybatis
+description: 按项目 MyBatis 与数据库版本评审 Mapper 接口、XML 或注解映射、动态 SQL、参数结果映射、事务边界和查询性能。适用于 MyBatis 专项审查；通用 SQL 设计、直接修改或其他 ORM 不应触发。
+---
+
+# MyBatis 专项审查
+
+先确认 MyBatis、扩展库和数据库精确版本，再结合 Mapper 调用方与实际 SQL 评审。
+
+## 工作流
+
+1. 读取依赖、配置、Mapper、模型、调用方和相关测试。
+2. 检查 statement 对应、参数绑定、结果映射、动态 SQL、空集合、生成键、缓存和事务假设。
+3. 按 [官方来源](references/sources.md) 核实当前版本能力，数据库语法另查目标数据库官方文档。
+4. 对查询计划和性能只给可验证建议；未执行数据库计划时不得断言性能结果。
+5. 输出带路径和证据的问题、影响、修复方向及未验证边界，不自动修改代码。
@@ -0,0 +1,4 @@
+interface:
+  display_name: "MyBatis 审查"
+  short_description: "专项审查映射、动态 SQL 和查询边界"
+  default_prompt: "使用 $review-mybatis 审查当前 MyBatis Mapper 与 SQL。"
@@ -0,0 +1,8 @@
+# 官方来源
+
+重建日期：2026-08-25。
+
+- MyBatis 3 Reference Documentation：https://mybatis.org/mybatis-3/index.html
+- MyBatis 3 Java API：https://mybatis.org/mybatis-3/java-api.html
+
+官方资料用于配置、映射、动态 SQL、缓存和 Java API 行为。项目若使用扩展库或旧版本，应读取对应官方版本资料；本文不复制官方手册或内部 Mapper 规范。