Skill: pupuking723/spec-coding (version 1.0.0)

--- name: spec-coding description: 规格驱动编程工作流。根据用户需求生成 Spec 文档（功能/API/组件），或为现有代码逆向生成规格文档。使用场景：(1) 新项目启动时先写规格，(2) 老项目补规格文档，(3) 需求评审时生成规格草稿，(4) 代码审查时对照规格验收。 --- # Spec Coding 规格驱动编程 ## 核心工作流 ### 场景 1：新项目生成规格文档 当用户提出新需求时： 1. **判断规格类型** - 功能需求 → 使用 `feature-spec.md` 模板 - API 接口 → 使用 `api-spec.md` 模板 - UI 组件 → 使用 `component-spec.md` 模板 2. **生成规格草稿** - 读取对应模板（见 `assets/templates/`） - 根据用户需求填充各章节 - 重点明确：输入/输出规格、边界情况、验收标准 3. **输出格式** ```markdown # [功能名称] 规格文档 **状态**: `draft` **创建日期**: YYYY-MM-DD [完整规格内容] ``` 4. **后续流程** - 用户评审 → 修改 → 批准 - 状态改为 `approved` 后交付开发 - 开发完成后对照规格验收 ### 场景 2：老项目逆向生成规格 当用户需要为现有代码补规格文档时： 1. **读取源代码** - 功能代码 → 分析输入/输出/行为 - API 代码 → 提取路由/参数/响应格式 - 组件代码 → 分析 Props/状态/交互 2. **生成规格文档** - 对照模板填充已知信息 - 标注「待确认」章节（需要用户补充） - 输出 `review` 状态文档 3. **输出示例** ```markdown ## 2.1 输入规格（已分析代码得出） | 输入项 | 类型 | 必填 | 约束条件 | |--------|------|------|----------| | userId | string | 是 | UUID 格式 | ## 1.1 问题描述（待用户补充） > ⚠️ 待确认：这个功能要解决什么问题？ ``` ## 模板使用说明 读取模板文件前，先判断需求类型： | 模板文件 | 适用场景 | |----------|----------| | `assets/templates/feature-spec.md` | 业务功能、用户故事 | | `assets/templates/api-spec.md` | REST API、GraphQL、Webhook | | `assets/templates/component-spec.md` | React/Vue 组件、UI 控件 | ## 规格状态流转 ``` draft → review → approved → in-progress → done ``` - `draft`: 草稿，待用户补充信息 - `review`: 待评审，等待用户确认 - `approved`: 已批准，可交付开发 - `in-progress`: 开发中 - `done`: 已完成验收 ## 输出原则 1. **结构化优先** - 使用表格、代码块、列表 2. **明确边界** - 必须列出所有边界情况和错误处理 3. **可验收** - 每条规格都可被验证（是/否） 4. **简洁** - 避免冗长描述，用示例代替解释 ## 与子代理协作 - **研究员**: 搜集竞品规格、行业标准 - **文案师**: 润色用户提示文案、错误消息 - **落地执行**: 根据规格实现代码、编写测试 ## 参考文档 - 详细模板说明：`assets/templates/README.md` - 规格示例：`assets/examples/`

path: assets/examples/feature-example.md
content: # 示例：用户导出功能规格

**状态**: `approved`  
**创建日期**: 2026-03-12  
**负责人**: 落地执行  

---

## 1. 背景与目标

### 1.1 问题描述
用户需要将平台数据导出为 Excel 进行二次分析，当前只能在线查看，无法离线处理。

### 1.2 目标用户
- 运营人员：导出用户数据做周报
- 分析师：导出数据做深度分析
- 管理员：备份数据

### 1.3 成功指标
- 导出功能使用率 > 30%
- 导出请求成功率 > 99%
- P95 响应时间 < 30s

---

## 2. 功能规格

### 2.1 输入规格

| 输入项 | 类型 | 必填 | 约束条件 | 示例 |
|--------|------|------|----------|------|
| dateRange | object | 是 | 最多 90 天 | {"start":"2026-01-01","end":"2026-03-31"} |
| filters | object | 否 | 最多 5 个条件 | {"status":"active","plan":"pro"} |
| format | string | 否 | enum: ['xlsx','csv'] | "xlsx" |

### 2.2 输出规格

| 输出项 | 类型 | 描述 | 示例 |
|--------|------|------|------|
| downloadUrl | string | 临时下载链接，15 分钟有效 | https://cdn.example.com/exports/xxx.xlsx |
| recordCount | number | 导出数据条数 | 1250 |
| fileSize | number | 文件大小（字节） | 524288 |

### 2.3 行为规格

#### 正常流程
1. 用户选择日期范围和筛选条件
2. 点击「导出」按钮
3. 系统异步生成文件（显示进度）
4. 生成完成后提供下载链接
5. 用户下载文件

#### 边界情况
- 数据量为 0 时：提示「无数据可导出」，不生成文件
- 数据量 > 10 万条：分批导出，每批 10 万条
- 导出时间 > 5 分钟：发送通知邮件
- 重复请求（相同参数）：复用已有文件，不重新生成

#### 错误处理
| 错误码 | 触发条件 | 用户提示 | 日志级别 |
|--------|----------|----------|----------|
| INVALID_DATE_RANGE | 日期范围 > 90 天 | 日期范围最多 90 天 | WARN |
| EXPORT_FAILED | 生成文件失败 | 导出失败，请重试 | ERROR |
| RATE_LIMITED | 1 小时内第 5 次导出 | 导出次数超限，请 1 小时后再试 | WARN |

---

## 3. 非功能需求

- **性能**: P95 响应时间 < 30s（10 万条数据以内）
- **兼容性**: 支持 Chrome/Firefox/Safari/Edge 最新版
- **安全性**: 下载链接 15 分钟过期，需要登录认证
- **可访问性**: 按钮有 aria-label，支持键盘操作

---

## 4. 验收标准

- [ ] 正常流程测试通过（100 条、1000 条、10 万条数据）
- [ ] 边界情况处理正确（0 条、>10 万条）
- [ ] 错误提示友好且准确
- [ ] 下载链接 15 分钟后失效
- [ ] 相同参数请求复用文件
- [ ] 性能指标达标（P95 < 30s）

---

## 5. 变更记录

| 日期 | 版本 | 变更内容 | 变更人 |
|------|------|----------|--------|
| 2026-03-12 | v1.0 | 初始版本 | 主脑 |


path: assets/templates/README.md
content: # 规格模板说明

## 模板列表

### feature-spec.md - 功能规格模板

**适用场景**：
- 新业务功能开发
- 用户故事实现
- 后台管理功能
- 数据处理流程

**核心章节**：
- 背景与目标（问题描述、目标用户、成功指标）
- 输入/输出规格（表格形式）
- 行为规格（正常流程、边界情况、错误处理）
- 非功能需求（性能、兼容性、安全性）
- 验收标准（Checklist）

---

### api-spec.md - API 规格模板

**适用场景**：
- REST API 设计
- GraphQL Schema 定义
- Webhook 事件规范
- 第三方集成接口

**核心章节**：
- 接口概述（路径、认证、速率限制）
- 请求规格（Header、路径参数、查询参数、请求体）
- 响应规格（成功响应、错误响应、状态码）
- 边界情况与错误处理
- 验收测试用例（curl 示例）

---

### component-spec.md - 组件规格模板

**适用场景**：
- React/Vue 组件开发
- UI 控件设计
- 表单组件
- 交互组件

**核心章节**：
- 组件概述（路径、类型、依赖）
- Props 规格（TypeScript 接口 + 详细说明表）
- 状态规格（内部状态、状态流转图）
- 行为规格（用户交互、自动行为）
- UI 规格（布局结构、响应式断点、状态样式）
- 可访问性（A11y）检查项
- 测试用例（Jest/Vitest 示例）

---

## 使用建议

1. **不要删减核心章节** - 每个章节都有其价值
2. **表格优先** - 能用表格的不用段落
3. **示例驱动** - 每个规格点配一个示例
4. **状态标记** - 始终在文档顶部标注当前状态


path: assets/templates/api-spec.md
content: # [API 名称] 规格文档

**状态**: `draft`  
**创建日期**: YYYY-MM-DD  
**负责人**: [姓名]  

---

## 1. 接口概述

| 属性 | 值 |
|------|-----|
| 路径 | `METHOD /api/v1/xxx` |
| 认证 | 需要/不需要 |
| 速率限制 | X 次/分钟 |
| 幂等性 | 是/否 |

---

## 2. 请求规格

### 2.1 请求头

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| Authorization | string | 是 | Bearer token |
| Content-Type | string | 是 | application/json |

### 2.2 路径参数

| 参数 | 类型 | 必填 | 约束 | 示例 |
|------|------|------|------|------|
| id | string | 是 | UUID 格式 | 550e8400-e29b... |

### 2.3 查询参数

| 参数 | 类型 | 默认值 | 约束 | 说明 |
|------|------|--------|------|------|
| page | number | 1 | >= 1 | 页码 |
| limit | number | 20 | 1-100 | 每页数量 |

### 2.4 请求体

```typescript
interface RequestBody {
  // 字段定义
  name: string;        // 必填，2-50 字符
  email?: string;      // 可选，邮箱格式
  tags?: string[];     // 可选，最多 10 个
}
```

---

## 3. 响应规格

### 3.1 成功响应 (200 OK)

```typescript
interface SuccessResponse {
  code: 0;
  data: {
    id: string;
    createdAt: string;  // ISO 8601
    // ...
  };
}
```

### 3.2 错误响应

| 状态码 | 错误码 | 说明 |
|--------|--------|------|
| 400 | INVALID_PARAM | 参数校验失败 |
| 401 | UNAUTHORIZED | 未认证 |
| 403 | FORBIDDEN | 无权限 |
| 404 | NOT_FOUND | 资源不存在 |
| 429 | RATE_LIMITED | 请求超限 |
| 500 | INTERNAL_ERROR | 服务器错误 |

```typescript
interface ErrorResponse {
  code: string;
  message: string;
  details?: Array<{
    field: string;
    reason: string;
  }>;
}
```

---

## 4. 边界情况

- 请求体为空时：返回 400 INVALID_PARAM
- 字段超出长度限制：截断/拒绝
- 并发请求：保证数据一致性

---

## 5. 验收测试用例

```bash
# 正常请求
curl -X POST /api/v1/xxx -d '{"name":"test"}'

# 边界测试
curl -X POST /api/v1/xxx -d '{"name":""}'  # 应返回 400

# 错误处理
curl -X POST /api/v1/xxx -d '{}'  # 缺少必填字段
```

---

## 6. 变更记录

| 日期 | 版本 | 变更内容 | 变更人 |
|------|------|----------|--------|
| | | | |


path: assets/templates/component-spec.md
content: # [组件名称] 规格文档

**状态**: `draft`  
**创建日期**: YYYY-MM-DD  
**负责人**: [姓名]  

---

## 1. 组件概述

| 属性 | 值 |
|------|-----|
| 组件路径 | `@/components/xxx.tsx` |
| 组件类型 | 无状态/有状态 |
| 依赖组件 | |

---

## 2. Props 规格

```typescript
interface ComponentProps {
  // 必填 props
  title: string;           // 标题，最多 50 字符
  onSubmit: (data: FormData) => Promise<void>;
  
  // 可选 props
  variant?: 'default' | 'compact' | 'full';  // 默认 'default'
  disabled?: boolean;      // 默认 false
  className?: string;      // 额外样式类名
  
  // 事件回调
  onCancel?: () => void;
  onError?: (error: Error) => void;
}
```

### Props 详细说明

| Prop | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| title | string | 是 | - | 组件标题 |
| variant | enum | 否 | 'default' | 变体样式 |
| disabled | boolean | 否 | false | 禁用状态 |

---

## 3. 状态规格

### 3.1 内部状态

```typescript
type ComponentState = {
  isLoading: boolean;
  error: Error | null;
  // ...
};
```

### 3.2 状态流转

```
idle → loading → success
           ↓
         error
```

---

## 4. 行为规格

### 4.1 用户交互

| 操作 | 预期行为 |
|------|----------|
| 点击提交按钮 | 验证表单 → 调用 onSubmit → 显示加载状态 |
| 点击取消按钮 | 调用 onCancel → 关闭组件 |
| 表单验证失败 | 显示错误提示，不提交 |

### 4.2 自动行为

- 组件挂载时：
- 数据变化时：
- 组件卸载时：

---

## 5. UI 规格

### 5.1 布局结构

```
┌─────────────────────────┐
│  [Title]                │
├─────────────────────────┤
│  [Content Area]         │
│                         │
├─────────────────────────┤
│  [Cancel]  [Submit]     │
└─────────────────────────┘
```

### 5.2 响应式断点

| 断点 | 行为 |
|------|------|
| < 640px | 按钮垂直排列 |
| >= 640px | 按钮水平排列 |

### 5.3 状态样式

- **Loading**: 显示骨架屏/加载动画
- **Error**: 红色边框 + 错误提示
- **Disabled**: 灰色，不可点击

---

## 6. 可访问性 (A11y)

- [ ] 支持键盘导航
- [ ] 有适当的 aria 标签
- [ ] 错误信息可被屏幕阅读器读取
- [ ] 颜色对比度符合 WCAG AA

---

## 7. 测试用例

```typescript
// 单元测试
describe('Component', () => {
  it('renders correctly with required props');
  it('calls onSubmit when form is valid');
  it('shows error message on validation failure');
  it('handles loading state correctly');
});
```

---

## 8. 变更记录

| 日期 | 版本 | 变更内容 | 变更人 |
|------|------|----------|--------|
| | | | |


path: assets/templates/feature-spec.md
content: # [功能名称] 规格文档

**状态**: `draft`  
**创建日期**: YYYY-MM-DD  
**负责人**: [姓名]  

---

## 1. 背景与目标

### 1.1 问题描述
> 这个功能要解决什么问题？当前痛点是什么？

### 1.2 目标用户
> 谁会使用这个功能？使用场景是什么？

### 1.3 成功指标
> 如何衡量这个功能成功了？（量化指标）

---

## 2. 功能规格

### 2.1 输入规格

| 输入项 | 类型 | 必填 | 约束条件 | 示例 |
|--------|------|------|----------|------|
| | | | | |

### 2.2 输出规格

| 输出项 | 类型 | 描述 | 示例 |
|--------|------|------|------|
| | | | |

### 2.3 行为规格

#### 正常流程
1. 用户...
2. 系统...
3. 返回...

#### 边界情况
- 空输入时：
- 超大数据时：
- 网络超时时：
- 权限不足时：

#### 错误处理
| 错误码 | 触发条件 | 用户提示 | 日志级别 |
|--------|----------|----------|----------|
| | | | |

---

## 3. 非功能需求

- **性能**: 响应时间 < X ms (P95)
- **兼容性**: 支持浏览器/设备...
- **安全性**: 需要认证/授权/加密...
- **可访问性**: WCAG 等级...

---

## 4. 验收标准

- [ ] 正常流程测试通过
- [ ] 所有边界情况处理正确
- [ ] 错误提示友好且准确
- [ ] 性能指标达标
- [ ] 代码审查通过

---

## 5. 变更记录

| 日期 | 版本 | 变更内容 | 变更人 |
|------|------|----------|--------|
| | | | |

---

## 6. 附录

### 6.1 参考链接
- 

### 6.2 相关文档
- 


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)