dev-playbooks-cn 1.0.0

package/skills/devbooks-coder/references//351/224/231/350/257/257/347/240/201/350/247/204/350/214/203.md

@@ -0,0 +1,463 @@
+# 错误码规范
+
+借鉴 VS Code 错误处理模式，本文档定义了应用程序错误码的标准规范。
+
+---
+
+## 1) 错误码设计原则
+
+### 1.1 可读性
+
+错误码应该人类可读，便于理解和记忆。
+
+```typescript
+// 推荐：语义化错误码
+'USER_NOT_FOUND'
+'INVALID_EMAIL_FORMAT'
+'PAYMENT_DECLINED'
+
+// 避免：纯数字或无意义编码
+'E10001'
+'ERR_X7B2'
+```
+
+### 1.2 唯一性
+
+每个错误码在整个系统中应该是唯一的。
+
+```typescript
+// 使用前缀区分模块
+'AUTH_INVALID_TOKEN'
+'AUTH_SESSION_EXPIRED'
+'ORDER_NOT_FOUND'
+'ORDER_ALREADY_PAID'
+```
+
+### 1.3 稳定性
+
+错误码一旦发布就不应该改变含义。
+
+---
+
+## 2) 错误码格式
+
+### 标准格式
+
+```
+<MODULE>_<CATEGORY>_<DESCRIPTION>
+```
+
+| 部分 | 说明 | 示例 |
+|------|------|------|
+| MODULE | 模块/服务名 | `AUTH`, `ORDER`, `USER` |
+| CATEGORY | 错误类别 | `INVALID`, `NOT_FOUND`, `FAILED` |
+| DESCRIPTION | 具体描述 | `TOKEN`, `EMAIL`, `PAYMENT` |
+
+### 示例
+
+```typescript
+// 认证模块
+'AUTH_INVALID_CREDENTIALS'
+'AUTH_TOKEN_EXPIRED'
+'AUTH_PERMISSION_DENIED'
+
+// 用户模块
+'USER_NOT_FOUND'
+'USER_ALREADY_EXISTS'
+'USER_INVALID_EMAIL'
+
+// 订单模块
+'ORDER_NOT_FOUND'
+'ORDER_INVALID_STATUS'
+'ORDER_PAYMENT_FAILED'
+```
+
+---
+
+## 3) 错误类别
+
+### 标准类别
+
+| 类别 | HTTP 状态码 | 说明 |
+|------|------------|------|
+| `INVALID` | 400 | 输入验证失败 |
+| `UNAUTHORIZED` | 401 | 未认证 |
+| `FORBIDDEN` | 403 | 无权限 |
+| `NOT_FOUND` | 404 | 资源不存在 |
+| `CONFLICT` | 409 | 资源冲突 |
+| `RATE_LIMITED` | 429 | 限流 |
+| `INTERNAL` | 500 | 内部错误 |
+| `UNAVAILABLE` | 503 | 服务不可用 |
+| `TIMEOUT` | 504 | 超时 |
+
+### 映射表
+
+```typescript
+const ERROR_STATUS_MAP: Record<string, number> = {
+  // 400 Bad Request
+  'INVALID': 400,
+  'VALIDATION': 400,
+  'MALFORMED': 400,
+
+  // 401 Unauthorized
+  'UNAUTHORIZED': 401,
+  'UNAUTHENTICATED': 401,
+
+  // 403 Forbidden
+  'FORBIDDEN': 403,
+  'PERMISSION': 403,
+
+  // 404 Not Found
+  'NOT_FOUND': 404,
+  'MISSING': 404,
+
+  // 409 Conflict
+  'CONFLICT': 409,
+  'DUPLICATE': 409,
+  'ALREADY_EXISTS': 409,
+
+  // 429 Too Many Requests
+  'RATE_LIMITED': 429,
+  'THROTTLED': 429,
+
+  // 500 Internal Server Error
+  'INTERNAL': 500,
+  'UNEXPECTED': 500,
+
+  // 503 Service Unavailable
+  'UNAVAILABLE': 503,
+  'MAINTENANCE': 503,
+
+  // 504 Gateway Timeout
+  'TIMEOUT': 504,
+};
+```
+
+---
+
+## 4) 错误类实现
+
+### 基础错误类
+
+```typescript
+interface ErrorDetails {
+  [key: string]: unknown;
+}
+
+class AppError extends Error {
+  public readonly code: string;
+  public readonly statusCode: number;
+  public readonly details?: ErrorDetails;
+  public readonly timestamp: string;
+  public readonly isOperational: boolean;
+
+  constructor(
+    code: string,
+    message: string,
+    statusCode: number = 500,
+    details?: ErrorDetails
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    this.timestamp = new Date().toISOString();
+    this.isOperational = true;  // 区分业务错误和系统错误
+
+    Error.captureStackTrace(this, this.constructor);
+  }
+
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      statusCode: this.statusCode,
+      details: this.details,
+      timestamp: this.timestamp,
+    };
+  }
+}
+```
+
+### 具体错误类
+
+```typescript
+// 验证错误
+class ValidationError extends AppError {
+  constructor(field: string, message: string) {
+    super(
+      `VALIDATION_${field.toUpperCase()}_INVALID`,
+      message,
+      400,
+      { field }
+    );
+  }
+}
+
+// 未找到错误
+class NotFoundError extends AppError {
+  constructor(resource: string, id: string) {
+    super(
+      `${resource.toUpperCase()}_NOT_FOUND`,
+      `${resource} with id '${id}' not found`,
+      404,
+      { resource, id }
+    );
+  }
+}
+
+// 认证错误
+class AuthenticationError extends AppError {
+  constructor(reason: string) {
+    super(
+      `AUTH_${reason.toUpperCase()}`,
+      `Authentication failed: ${reason}`,
+      401
+    );
+  }
+}
+
+// 权限错误
+class ForbiddenError extends AppError {
+  constructor(action: string, resource: string) {
+    super(
+      'AUTH_PERMISSION_DENIED',
+      `You don't have permission to ${action} ${resource}`,
+      403,
+      { action, resource }
+    );
+  }
+}
+
+// 冲突错误
+class ConflictError extends AppError {
+  constructor(resource: string, conflict: string) {
+    super(
+      `${resource.toUpperCase()}_CONFLICT`,
+      `${resource} conflict: ${conflict}`,
+      409,
+      { resource, conflict }
+    );
+  }
+}
+```
+
+---
+
+## 5) 错误码注册表
+
+### 中央注册表
+
+```typescript
+// errors/registry.ts
+export const ERROR_REGISTRY = {
+  // ===== 认证模块 (AUTH_*) =====
+  AUTH_INVALID_CREDENTIALS: {
+    message: 'Invalid username or password',
+    statusCode: 401,
+    recoverable: true,
+  },
+  AUTH_TOKEN_EXPIRED: {
+    message: 'Authentication token has expired',
+    statusCode: 401,
+    recoverable: true,
+  },
+  AUTH_TOKEN_INVALID: {
+    message: 'Invalid authentication token',
+    statusCode: 401,
+    recoverable: false,
+  },
+  AUTH_PERMISSION_DENIED: {
+    message: 'You do not have permission to perform this action',
+    statusCode: 403,
+    recoverable: false,
+  },
+
+  // ===== 用户模块 (USER_*) =====
+  USER_NOT_FOUND: {
+    message: 'User not found',
+    statusCode: 404,
+    recoverable: false,
+  },
+  USER_ALREADY_EXISTS: {
+    message: 'User already exists',
+    statusCode: 409,
+    recoverable: false,
+  },
+  USER_INVALID_EMAIL: {
+    message: 'Invalid email format',
+    statusCode: 400,
+    recoverable: true,
+  },
+
+  // ===== 订单模块 (ORDER_*) =====
+  ORDER_NOT_FOUND: {
+    message: 'Order not found',
+    statusCode: 404,
+    recoverable: false,
+  },
+  ORDER_INVALID_STATUS: {
+    message: 'Invalid order status transition',
+    statusCode: 400,
+    recoverable: false,
+  },
+  ORDER_PAYMENT_FAILED: {
+    message: 'Payment processing failed',
+    statusCode: 402,
+    recoverable: true,
+  },
+
+  // ===== 系统错误 (SYSTEM_*) =====
+  SYSTEM_INTERNAL_ERROR: {
+    message: 'An internal error occurred',
+    statusCode: 500,
+    recoverable: false,
+  },
+  SYSTEM_SERVICE_UNAVAILABLE: {
+    message: 'Service temporarily unavailable',
+    statusCode: 503,
+    recoverable: true,
+  },
+  SYSTEM_RATE_LIMITED: {
+    message: 'Too many requests, please try again later',
+    statusCode: 429,
+    recoverable: true,
+  },
+} as const;
+
+export type ErrorCode = keyof typeof ERROR_REGISTRY;
+```
+
+### 使用注册表
+
+```typescript
+function createError(code: ErrorCode, details?: ErrorDetails): AppError {
+  const config = ERROR_REGISTRY[code];
+  return new AppError(
+    code,
+    config.message,
+    config.statusCode,
+    details
+  );
+}
+
+// 使用
+throw createError('USER_NOT_FOUND', { userId: '12345' });
+```
+
+---
+
+## 6) 错误响应格式
+
+### API 错误响应
+
+```typescript
+interface ErrorResponse {
+  error: {
+    code: string;
+    message: string;
+    details?: ErrorDetails;
+    timestamp: string;
+    requestId?: string;
+    documentation?: string;
+  };
+}
+
+// 示例响应
+{
+  "error": {
+    "code": "USER_NOT_FOUND",
+    "message": "User with id '12345' not found",
+    "details": {
+      "userId": "12345"
+    },
+    "timestamp": "2024-01-15T10:30:00.000Z",
+    "requestId": "req-abc-123",
+    "documentation": "https://docs.example.com/errors/USER_NOT_FOUND"
+  }
+}
+```
+
+### Express 错误处理中间件
+
+```typescript
+function errorHandler(
+  err: Error,
+  req: Request,
+  res: Response,
+  next: NextFunction
+) {
+  if (err instanceof AppError) {
+    return res.status(err.statusCode).json({
+      error: {
+        code: err.code,
+        message: err.message,
+        details: err.details,
+        timestamp: err.timestamp,
+        requestId: req.id,
+      }
+    });
+  }
+
+  // 未知错误
+  console.error('Unexpected error:', err);
+  return res.status(500).json({
+    error: {
+      code: 'SYSTEM_INTERNAL_ERROR',
+      message: 'An unexpected error occurred',
+      timestamp: new Date().toISOString(),
+      requestId: req.id,
+    }
+  });
+}
+```
+
+---
+
+## 7) 错误文档
+
+### 文档模板
+
+```markdown
+## USER_NOT_FOUND
+
+**HTTP 状态码**: 404
+
+**描述**: 请求的用户不存在
+
+**可能原因**:
+- 用户 ID 不正确
+- 用户已被删除
+- 没有访问该用户的权限
+
+**解决方案**:
+1. 检查用户 ID 是否正确
+2. 确认用户未被删除
+3. 确认有足够的访问权限
+
+**示例响应**:
+```json
+{
+  "error": {
+    "code": "USER_NOT_FOUND",
+    "message": "User with id '12345' not found"
+  }
+}
+```
+```
+
+---
+
+## 8) 检查清单
+
+设计错误码时确认：
+
+- [ ] 错误码是否语义化？（人类可读）
+- [ ] 错误码是否唯一？（全局不重复）
+- [ ] 错误码是否包含模块前缀？
+- [ ] HTTP 状态码是否正确映射？
+- [ ] 错误消息是否对用户友好？
+- [ ] 敏感信息是否脱敏？
+- [ ] 是否记录到错误注册表？
+- [ ] 是否有文档说明？

package/skills/devbooks-delivery-workflow/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: devbooks-delivery-workflow
+description: devbooks-delivery-workflow：把一次变更跑成可追溯闭环（Design→Plan→Trace→Verify→Implement→Archive），明确 DoD、追溯矩阵与角色隔离（Test Owner 与 Coder 分离）。用户说"跑一遍闭环/交付验收/追溯矩阵/DoD/关账归档/验收工作流"等时使用。
+tools:
+  - Glob
+  - Grep
+  - Read
+  - Write
+  - Edit
+  - Bash
+---
+
+# DevBooks：交付验收工作流（闭环骨架）
+
+## 前置：配置发现（协议无关）
+
+- `<truth-root>`：当前真理目录根
+- `<change-root>`：变更包目录根
+
+执行前**必须**按以下顺序查找配置（找到后停止）：
+1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
+2. `dev-playbooks/project.md`（如存在）→ DevBooks 2.0 协议，使用默认映射
+4. `project.md`（如存在）→ template 协议，使用默认映射
+5. 若仍无法确定 → **停止并询问用户**
+
+**关键约束**：
+- 如果配置中指定了 `agents_doc`（规则文档），**必须先阅读该文档**再执行任何操作
+- 禁止猜测目录根
+- 禁止跳过规则文档阅读
+
+## 参考骨架（按需读取）
+
+- 工作流：`references/交付验收工作流.md`
+- 模板：`references/变更验证与追溯模板.md`
+
+## 可选检查脚本
+
+脚本位于本 Skill 的 `scripts/` 目录（可执行；优先"跑脚本拿结果"，而不是把脚本正文读进上下文）。
+
+- 初始化变更包骨架：`change-scaffold.sh <change-id> --project-root <repo-root> --change-root <change-root> --truth-root <truth-root>`
+- 一键校验变更包：`change-check.sh <change-id> --mode <proposal|apply|review|archive|strict> --role <test-owner|coder|reviewer> --project-root <repo-root> --change-root <change-root> --truth-root <truth-root>`
+- 结构守门决策校验（strict 会自动调用）：`guardrail-check.sh <change-id> --project-root <repo-root> --change-root <change-root>`
+- 初始化 spec delta 骨架：`change-spec-delta-scaffold.sh <change-id> <capability> --project-root <repo-root> --change-root <change-root>`
+- 证据采集（把 tests/命令输出落盘到 evidence）：`change-evidence.sh <change-id> --label <name> --project-root <repo-root> --change-root <change-root> -- <command> [args...]`
+- 大规模机械变更（LSC）codemod 脚本骨架：`change-codemod-scaffold.sh <change-id> --name <codemod-name> --project-root <repo-root> --change-root <change-root>`
+- 卫生检查（临时文件/进程清理）：`hygiene-check.sh <change-id> --project-root <repo-root> --change-root <change-root>`
+
+## 质量闸门脚本（v2）
+
+以下脚本用于强化质量闸门，拦截"假完成"：
+
+- 角色交接检查：`handoff-check.sh <change-id> --project-root <repo-root> --change-root <change-root>`
+- 环境声明检查：`env-match-check.sh <change-id> --project-root <repo-root> --change-root <change-root>`
+- 审计全量扫描：`audit-scope.sh <directory> --format <markdown|json>`
+- 进度仪表板：`progress-dashboard.sh <change-id> --project-root <repo-root> --change-root <change-root>`
+- v2 闸门迁移：`migrate-to-v2-gates.sh <change-id> --project-root <repo-root> --change-root <change-root>`
+
+### change-check.sh v2 新增检查项
+
+| 检查项 | 触发模式 | 说明 | AC |
+|--------|----------|------|-----|
+| `check_evidence_closure()` | archive, strict | 验证 `evidence/green-final/` 存在且非空 | AC-001 |
+| `check_task_completion_rate()` | strict | 验证任务完成率 100%（支持 SKIP-APPROVED） | AC-002 |
+| `check_role_boundaries()` | apply --role | 验证角色边界（扩展自 check_no_tests_changed） | AC-003 |
+| `check_skip_approval()` | strict | 验证 P0 任务跳过有审批记录 | AC-005 |
+| `check_env_match()` | archive, strict | 调用 env-match-check.sh 检查环境声明 | AC-006 |
+| `check_test_failure_in_evidence()` | archive, strict | 检测 Green 证据中的失败模式 | AC-007 |
+
+### change-check.sh 基础检查项
+
+| 检查项 | 触发模式 | 说明 |
+|--------|----------|------|
+| `check_proposal()` | 所有模式 | 检查 proposal.md 格式与决策状态 |
+| `check_design()` | 所有模式 | 检查 design.md 结构（AC 列表、Problem Context 等） |
+| `check_tasks()` | 所有模式 | 检查 tasks.md 结构（主线计划区、断点区） |
+| `check_verification()` | 所有模式 | 检查 verification.md 四大必填节 |
+| `check_spec_deltas()` | 所有模式 | 检查 specs/ 目录下 spec delta 格式 |
+| `check_implicit_changes()` | apply, archive, strict | 检测隐式变更（依赖、配置、构建） |
+
+### 角色边界约束
+
+| 角色 | 禁止修改 |
+|------|----------|
+| Coder | `tests/**`、`verification.md`、`.devbooks/` |
+| Test Owner | `src/**` |
+| Reviewer | 代码文件（`.ts`、`.js`、`.py`、`.sh` 等） |
+
+详细说明参见：`docs/quality-gates-guide.md`
+
+## 架构合规检查（依赖卫士）
+
+在合并前进行架构合规检查，防止依赖方向违规。
+
+### guardrail-check.sh 完整选项
+
+```bash
+guardrail-check.sh <change-id> [options]
+
+Options:
+  --project-root <dir>   项目根目录
+  --change-root <dir>    变更包目录
+  --truth-root <dir>     真理目录（包含 architecture/c4.md）
+  --role <role>          角色权限检查 (coder|test-owner|reviewer)
+  --check-lockfile       检查 lockfile 变更是否声明
+  --check-engineering    检查工程系统变更是否声明
+  --check-layers         检查分层约束违规（依赖卫士核心）
+  --check-cycles         检查循环依赖
+  --check-hotspots       警告热点文件变更
+```
+
+### 分层约束检查内容
+
+`--check-layers` 会检测以下违规：
+
+| 违规类型 | 示例 | 严重程度 |
+|----------|------|----------|
+| 下层引用上层 | `base/` 导入 `platform/` | 🔴 Critical |
+| common 引用 browser/node | `common/` 导入 `browser/` | 🔴 Critical |
+| common 使用 DOM API | `document.` 在 common 中 | 🔴 Critical |
+| core 引用 contrib | 违反扩展点设计 | 🟡 High |
+
+### 推荐用法
+
+```bash
+# 完整架构检查（合并前）
+guardrail-check.sh <change-id> \
+  --truth-root devbooks \
+  --check-layers \
+  --check-cycles \
+  --check-hotspots \
+  --check-lockfile \
+  --check-engineering
+
+# 快速检查（日常开发）
+guardrail-check.sh <change-id> --check-layers --check-cycles
+```
+
+### CI 集成示例
+
+```yaml
+# .github/workflows/pr.yml
+- name: Architecture Compliance Check
+  run: |
+    ./scripts/guardrail-check.sh ${{ github.event.pull_request.number }} \
+      --truth-root devbooks \
+      --check-layers \
+      --check-cycles
+```
+
+---
+
+## 上下文感知
+
+本 Skill 在执行前自动检测上下文，选择合适的工作流阶段。
+
+检测规则参考：`skills/_shared/context-detection-template.md`
+
+### 检测流程
+
+1. 检测变更包是否存在
+2. 检测当前阶段（proposal/apply/archive）
+3. 检测闸门状态
+
+### 本 Skill 支持的模式
+
+| 模式 | 触发条件 | 行为 |
+|------|----------|------|
+| **初始化模式** | 变更包不存在 | 创建变更包骨架 |
+| **检查模式** | 带 --check 参数 | 只运行闸门检查 |
+| **完整闭环** | 无特殊参数 | 执行完整 Design→Archive 流程 |
+
+### 检测输出示例
+
+```
+检测结果：
+- 变更包：存在
+- 当前阶段：apply
+- 闸门状态：proposal ✓, design ✓, tasks ✓
+- 运行模式：检查模式（apply 阶段）
+```
+
+---
+
+## MCP 增强
+
+本 Skill 支持 MCP 运行时增强，自动检测并启用高级功能。
+
+MCP 增强规则参考：`skills/_shared/mcp-enhancement-template.md`
+
+### 依赖的 MCP 服务
+
+| 服务 | 用途 | 超时 |
+|------|------|------|
+| `mcp__ckb__getStatus` | 检测 CKB 索引可用性 | 2s |
+
+### 检测流程
+
+1. 调用 `mcp__ckb__getStatus`（2s 超时）
+2. 在工作流状态报告中标注索引可用性
+3. 若不可用 → 建议在 apply 阶段前生成索引
+
+### 增强模式 vs 基础模式
+
+| 功能 | 增强模式 | 基础模式 |
+|------|----------|----------|
+| 架构检查 | 精确依赖分析 | 基于 import 语句 |
+| 热点预警 | CKB 实时分析 | 不可用 |
+| 影响评估 | 调用图分析 | 文件级估算 |
+
+### 降级提示
+
+当 MCP 不可用时，输出以下提示：
+
+```
+⚠️ CKB 索引不可用，架构检查将使用基础模式。
+建议运行 /devbooks:index 生成索引以启用精确检查。
+```