@zhuan-ai/zhuanspec 2.11.3 → 2.11.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuan-ai/zhuanspec",
-  "version": "2.11.3",
+  "version": "2.11.6",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "zhuanspec",
@@ -39,6 +39,26 @@
     "!dist/**/__tests__",
     "!dist/**/*.map"
   ],
+  "scripts": {
+    "lint": "eslint src/",
+    "build": "node build.js",
+    "dev": "tsc --watch",
+    "dev:cli": "pnpm build && node bin/zhuanspec.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "test:postinstall": "node scripts/postinstall.js",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build",
+    "postinstall": "node scripts/postinstall.js",
+    "check:pack-version": "node scripts/pack-version-check.mjs",
+    "diagnose:cursor": "node scripts/diagnose-cursor-commands.js",
+    "release": "pnpm run release:ci",
+    "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
+    "release:local": "pnpm exec changeset version && pnpm run check:pack-version && pnpm exec changeset publish",
+    "changeset": "changeset"
+  },
   "engines": {
     "node": ">=20.19.0"
   },
@@ -60,23 +80,5 @@
     "ora": "^8.2.0",
     "yaml": "^2.8.2",
     "zod": "^4.0.17"
-  },
-  "scripts": {
-    "lint": "eslint src/",
-    "build": "node build.js",
-    "dev": "tsc --watch",
-    "dev:cli": "pnpm build && node bin/zhuanspec.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:ui": "vitest --ui",
-    "test:coverage": "vitest --coverage",
-    "test:postinstall": "node scripts/postinstall.js",
-    "postinstall": "node scripts/postinstall.js",
-    "check:pack-version": "node scripts/pack-version-check.mjs",
-    "diagnose:cursor": "node scripts/diagnose-cursor-commands.js",
-    "release": "pnpm run release:ci",
-    "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
-    "release:local": "pnpm exec changeset version && pnpm run check:pack-version && pnpm exec changeset publish",
-    "changeset": "changeset"
   }
-}
+}

package/schemas/spec-driven/schema.yaml

@@ -169,9 +169,17 @@ artifacts:
     instruction: |
       创建分解实施工作的任务列表。
 
+      ⚠️ 任务格式强制要求：
+      - 所有任务项必须使用 GitHub Flavored Markdown 复选框格式
+      - 待完成：- [ ] N.M 描述 @skill:xxx
+      - 已完成：- [x] N.M 描述 @skill:xxx
+      - 严禁使用 #### Task N.M: 或 #### T1: 标题格式
+      - 严禁使用 ✅ emoji 标记完成，必须用 [x] 复选框
+      - validate --strict 会对非复选框格式直接报 ERROR 并阻断流程
+
       指导原则：
-      - 在 ## 编号标题下对相关任务进行分组
-      - 每个任务是一个复选框：- [ ] X.Y 任务描述
+      - 任务必须组织在 Wave 标题下（### Wave 1, ### Wave 2 等）
+      - 每个任务按类型使用固定模板（新增文件/修改文件），填满所有字段
       - 任务应该足够小，可以在一次会话中完成
       - 按依赖关系排序任务（必须先做什么？）
 

package/schemas/spec-driven/templates/tasks.md

@@ -48,12 +48,96 @@ Answer: 是，每页20条
      - 数据依赖：后续任务使用前序任务创建的表/接口/类时，必须标注依赖
      - 独立任务：无数据或逻辑依赖的任务不要添加 @depends，以最大化并行度
 
+  @test-case 标注指南（可选）：
+  1. 仅当提供测试 case 时添加此标注
+  2. 格式：@test-case:TC-001 或 @test-case:TC-001,TC-002（多个用逗号分隔）
+  3. 确保引用的 TC-XXX 在 test-cases.md 中存在
+  4. 任务应覆盖对应测试 case 的所有验收点
+
+  @ref 标注指南：
+  1. 指向技术方案文档的具体章节（路径为实际定位到的技术方案文件相对路径）
+  2. 格式：@ref:<tech-spec路径>#章节编号-章节名称
+  3. 示例：@ref:techDesign/tech-spec.md#3.1-新建客户接口 或 @ref:/path/to/external-tech-spec.md#3.1-新建客户接口
+  4. 确保引用的章节在技术方案文档中存在
+
   示例：
   - [ ] 1.1 新增枚举值 @skill:kf-backend-coding-standards
   - [ ] 1.2 创建数据库表 @skill:java-db-schema-standards
   - [ ] 1.3 编写 DAO 层代码 @skill:java-dao-standards @depends:1.2
 -->
 
+## 任务格式说明
+
+⚠️ **所有任务项必须使用 GitHub Flavored Markdown 复选框格式**：
+- 待完成：`- [ ] N.M 描述`
+- 已完成：`- [x] N.M 描述`
+- **严禁使用** `#### Task N.M:` 或 `#### T1:` 标题格式
+- **严禁使用** ✅ emoji 标记完成，必须用 `[x]`
+
+每个任务按类型使用对应的固定模板，必须填满所有字段：
+
+### 类型 A：新增文件
+
+- [ ] N.M [描述] @skill:xxx @ref:xxx
+  - **文件**: `完整相对路径`（新增）
+  - **内容**:
+    - 类定义: [类名、继承/实现关系]
+    - 依赖注入: [注入的 Bean/Service 列表]
+    - 核心方法: [方法签名 → 返回类型]（列出全部 public 方法）
+    - 关键逻辑: [核心业务流程，如：校验 → 加锁 → 写库 → 同步ES]
+    - 字段/配置: [若为 Entity/DTO/配置类，列出全部字段及类型]
+  - **验证**: [具体的输入输出断言，含正常和异常场景]
+
+示例：
+- [ ] 5.1 创建 CustomerDomainService @skill:java-scf-rpc-usage-skill
+  @ref:techDesign/tech-spec.md#3.1-新建客户
+  - **文件**: `domain_hub_server/src/main/java/com/zz/domain/hub/domain/CustomerDomainService.java`（新增）
+  - **内容**:
+    - 类定义: `@Service public class CustomerDomainService`
+    - 依赖注入: CustomerMapper, CustomerEmployeeMapper, EsSyncService, RedissonClient
+    - 核心方法: createCustomer(CreateCustomerRequest, Long tenantId) → Long
+    - 关键逻辑: customerName 必填校验 → selectByPhoneAndTenant 手机号唯一检查 → 分布式锁 dh:customer:merge:{phone} → insert t_customer → 异步 ES 同步
+    - 异常处理: 手机号重复抛 BizException(ErrorCode.PHONE_DUPLICATE)
+  - **验证**: 手机号重复返回 PHONE_DUPLICATE 错误码；正常创建返回 customerId > 0；无锁时并发创建只成功一个
+
+### 类型 B：修改文件
+
+- [ ] N.M [描述] @skill:xxx @ref:xxx
+  - **文件**: `完整相对路径`（总行数）
+  - **修改位置**: L行号范围 `函数名/类名` 之后/之内
+  - **内容**: [具体改什么：新增代码逻辑/修改现有逻辑/删除代码，描述修改方式]
+  - **验证**: [修改后的预期行为，含回归验证]
+
+示例：
+- [ ] 1.1 在 review 命令中增加任务完成度硬门禁 @skill:none
+  @ref:techDesign/tech-spec.md#7.1-任务完成度检查
+  - **文件**: `src/commands/review.ts`（138行）
+  - **修改位置**: L32-38 `runReview()` 函数内，现有校验逻辑之后
+  - **内容**: 新增任务完成度检查 — 读取 tasks.md 匹配 `- [ ]` 统计未完成任务数，>0 时输出未完成列表并阻断 review 流程，支持 `--force` 参数跳过检查
+  - **验证**: 有未完成任务时阻断并输出列表；--force 跳过；全部完成时正常通过
+
+## 任务粒度原则
+- 每个任务对应一个类或一个接口方法的实现
+- 单个任务 AI 执行时间不超过 30 分钟
+- 超过则需拆分为多个子任务
+- **禁止模糊描述**：不允许"创建XXX类"不带文件路径、"实现YYY方法"不带方法签名和关键逻辑
+
+## Coverage Checklist
+
+<!-- 当存在技术方案（techDesign/tech-spec.md/ 通过--tech-spec创建的提案）时，必须填写此表 -->
+<!-- 列出技术方案中所有维度与任务的映射关系，确保覆盖率 >= 95% -->
+
+| 维度 | 技术方案数量 | 提案任务覆盖 | 覆盖率 |
+|------|-------------|-------------|-------|
+| DB 表 | <!-- N张 --> | <!-- T编号范围 --> | <!-- 100% --> |
+| ES 索引 | <!-- N个 --> | <!-- T编号范围 --> | <!-- 100% --> |
+| Entity 类 | <!-- N个 --> | <!-- T编号范围 --> | <!-- 100% --> |
+| Mapper | <!-- N个 --> | <!-- T编号范围 --> | <!-- 100% --> |
+| SCF接口方法 | <!-- N个 --> | <!-- T编号范围 --> | <!-- 100% --> |
+| DTO 类 | <!-- N个 --> | <!-- T编号范围 --> | <!-- 100% --> |
+| 配置项 | <!-- N个 --> | <!-- T编号范围 --> | <!-- 100% --> |
+| 前端组件 | <!-- N个 --> | <!-- T编号范围 --> | <!-- 100% --> |
+
 ### Wave 1
 
 <!-- Wave 1: Tasks with no dependencies -->
@@ -85,9 +169,38 @@ Wave assignment logic:
 - Wave 2: @depends:1.x → depends on Wave 1
 - Wave 3: @depends:2.x → depends on Wave 2
 
-## Quality Gates
-
-- [ ] Apply 全部任务完成后自动执行一次 `zhuanspec review <change-id>`（如失败则手动补执行）
+## File Conflict Analysis
+
+<!-- 当多个任务修改同一文件时，在此声明冲突并指定隔离策略 -->
+<!-- 隔离策略：parallel（不同区域可并行）/ serial（同区域必须串行）-->
+<!-- 此表帮助编排 Agent 做更精确的并行化决策，补充自动检测无法覆盖的"同文件不同区域可并行"场景 -->
+<!-- 无文件冲突时章节可省略，或将表格行填写 N/A -->
+
+| 文件 | 涉及任务 | 各任务修改区域 | 隔离策略 |
+|------|---------|-------------|---------|
+| <!-- 相对路径 --> | <!-- T1.x, T2.y --> | <!-- T1.x: 函数名/行范围; T2.y: 函数名/行范围 --> | <!-- parallel / serial --> |
+
+## Test Case Coverage
+
+<!-- ⚠️ CHECKPOINT [TEST-CASE-COVERAGE]: Each task should reference related test cases (recommended) -->
+<!-- Use @test-case:TC-XXX to link tasks to test cases -->
+<!-- 表格必须包含四列：Task、测试 Case ID、测试 Case 文件路径、覆盖场景 -->
+
+| Task | 测试 Case ID | 测试 Case 文件路径 | 覆盖场景 |
+|------|-------------|-------------------|----------|
+| <!-- T1 --> | <!-- TC-001 --> | <!-- BIC 路径层级，如：退货退款 > 创建售后 > 三选一页面 > 组装机弹窗 --> | <!-- 描述覆盖的场景 --> |
+
+<!--
+  测试 case 设计指南：
+  1. 为每个 Requirement 设计至少一个正向场景测试 case
+  2. 为关键业务逻辑设计异常场景测试 case
+  3. 测试 case 应与 Requirement 的 Scenario 对应
+  4. 测试 case ID 格式：TC-XXX（三位数字）
+  5. 测试 case 详情记录在 test-cases.md 文件中
+  6. "测试 Case 文件路径" 列填写 BIC 路径层级格式：
+     - 格式：功能模块 > 子模块 > 页面 > 操作 > 结果
+     - 示例：退货退款 > 创建售后 > 三选一页面 > 组装机 > 退货退款 > 点击后,显示组装机弹窗
+-->
 
 ## Workflow Diagram
 
@@ -98,4 +211,4 @@ Wave assignment logic:
 flowchart TD
     W1[Wave 1] --> W2[Wave 2]
     W2 --> W3[Wave 3]
-```
+```