第 1 步 → 阅读本章「核心概念」（约 5 分钟）
    ↓
第 2 步 → 尝试完成「第一个任务」（约 15 分钟）
    ↓
第 3 步 → 根据需要阅读工具章节
    ↓
第 4 步 → 选择适合的工作流程

# 在项目目录下启动
cd your-project
opencode
 
# 或直接启动（会自动检测当前目录）
opencode

OpenCode v1.x.x
Working directory: /path/to/your-project
Model: claude-3-5-sonnet
Ready for input...

# 直接输入自然语言
"请解释一下这个项目的技术栈"

这个项目使用以下技术栈：

框架：Next.js 15 (App Router)
语言：TypeScript 5.x
样式：Tailwind CSS v4
构建工具：Turbopack
...

主要依赖：
- react: 19.x
- next: 15.x
- typescript: 5.x
...

"请把登录页面的按钮文案从'确定'改成'立即登录'"

找到文件：app/login/page.tsx

修改内容：
- <button>确定</button>
+ <button>立即登录</button>

是否确认修改？(y/n)

# 类型检查
pnpm typecheck
 
# 构建验证
pnpm build
 
# 手动验证
# 在浏览器中打开登录页面，确认文案已更新

传统开发：写代码 → 写测试 → 发现 bug → 修 bug
         （像做完题再对答案，发现错了再改）

TDD 开发：写测试 → 测试失败 → 写代码 → 测试通过 → 完成
         （像先知道答案，做题时就知道对不对）

// 步骤 1：写失败的测试
test('登录成功后应该跳转到首页', async () => {
  await login('user@example.com', 'password');
  expect(window.location.pathname).toBe('/dashboard');
});
 
// 步骤 2：运行测试，确认失败
// Error: Expected '/dashboard' but got '/login'
 
// 步骤 3：写最小代码通过测试
async function login(email: string, password: string) {
  // 最小实现
  window.location.pathname = '/dashboard';
}
 
// 步骤 4：运行测试，确认通过
// ✓ 登录成功后应该跳转到首页
 
// 步骤 5：重构优化（测试必须保持通过）

没有 MCP 时：
你：帮我测试登录功能
AI：好的，你手动打开浏览器，输入用户名密码，点击登录按钮...

有 MCP 后：
你：帮我测试登录功能
AI：好的，我已经打开浏览器，输入了测试账号，点击了登录，验证通过。

你：我要一个登录功能，支持手机号登录，失败 3 次锁定
AI：好的，我来写代码
AI：代码写好了，请审查
你：审查通过，运行测试
AI：测试通过了
你：我在浏览器里试试...可以！确认完成

传统方式：
你：做一个登录功能
AI：[直接写代码]
你：不对，我要的是手机号登录
AI：[改代码]
你：还要失败 3 次锁定
AI：[再改代码]
...（反复返工）

OpenSpec 方式：
你：做一个登录功能
AI：[生成规格文档]
    - 支持手机号登录
    - 失败 3 次锁定
    - 锁定后 15 分钟解锁
你：确认规格
AI：[按规格实现]
你：验收通过

问：你的项目是否需要完整流程？

├─ 纯静态文档站点（无业务逻辑）
│   └─ ❌ 不适用 → 使用简化版流程
│
├─ 原型验证阶段
│   └─ ❌ 不适用 → 快速迭代优先，事后再补充测试
│
├─ 核心业务逻辑开发
│   └─ ✅ 适用 → 重点使用 TDD 章节
│
├─ 高风险模块（支付、认证等）
│   └─ ✅ 适用 → 必须使用完整流程
│
└─ 复杂应用、团队协作项目
    └─ ✅ 适用 → 完整流程

# 使用 npm 安装
npm install -g @anthropic/opencode
 
# 或使用 pnpm
pnpm add -g @anthropic/opencode
 
# 验证安装
opencode --version

// .ai/.config/opencode/opencode.json
{
  "model": "claude-3-5-sonnet",
  "maxTokens": 8192,
  "temperature": 0.7,
  "mcp": {
    // MCP 工具配置
  },
  "skills": [
    // 技能配置
  ]
}

// 方式 1: 使用 category（推荐用于任务委派）
task(
  category="quick",                    // 必需：任务类别
  load_skills=[],                      // 必需：技能数组
  description="Fix type error",        // 必需：短描述
  prompt="Fix the TypeScript error in src/utils.ts line 42...",  // 必需：完整提示词
  run_in_background=false              // 必需：false=任务委派，true=并行探索
)
 
// 方式 2: 使用 subagent_type（直接调用专门代理）
task(
  subagent_type="explore",             // 指定代理类型
  load_skills=[],
  description="Find auth patterns",
  prompt="搜索认证实现模式...",
  run_in_background=true               // 并行探索时用 true
)
 
// 方式 3: 继续之前的 session
task(
  session_id="ses_abc123",             // 上次返回的 session_id
  load_skills=[],
  description="Continue auth task",
  prompt="继续上一个任务...",
  run_in_background=false
)

# 方式 1: 指定变更名称
/opsx-propose add-user-login
 
# 方式 2: 直接描述需求，AI 自动生成名称
"我要添加一个用户登录模块，支持手机号和邮箱登录"

openspec/changes/add-user-login/
├── proposal.md    # 提案（做什么、为什么）
├── design.md      # 设计（怎么做）
└── tasks.md       # 任务清单

# 用户登录模块
 
## 概述
添加用户登录功能，支持手机号和邮箱登录。
 
## 验收标准
- [ ] 手机号登录成功
- [ ] 邮箱登录成功
- [ ] 失败 3 次锁定账户 15 分钟
- [ ] 锁定后提示用户
 
## 禁止事项
- 不修改现有注册逻辑
- 不添加第三方登录
 
## 非目标
- 不包含密码重置功能
- 不包含多因素认证

# 进入探索模式
/opsx-explore
 
# 对话式探索
"我需要一个用户登录模块"
"支持手机号和邮箱登录"
"失败 3 次锁定账户"
 
# AI 会追问：
# - 手机号格式是哪国？
# - 锁定后如何解锁？
# - 是否需要验证码？

# 标准执行
/opsx-apply add-user-login
 
# 全功率执行（复杂任务）
ultrawork
# 或
/ulw-loop

/opsx-archive add-user-login
 
# 输出：
# 归档到 openspec/changes/archive/2026-03-27-add-user-login/

openspec/changes/archive/2026-03-27-add-user-login/
├── proposal.md
├── design.md
├── tasks.md
├── code/           # 代码快照
└── tests/          # 测试快照

# 方式 1: 自动触发（推荐）
# AI 会根据任务自动判断是否需要 brainstorming
 
# 方式 2: 手动调用
skill(name="brainstorming")

用户: 我要做一个用户登录模块
 
AI (brainstorming 模式):
让我先理解你的需求...
 
1. 登录方式：
   - 手机号登录？
   - 邮箱登录？
   - 第三方登录（微信、GitHub）？
 
2. 安全要求：
   - 失败几次锁定？
   - 锁定多久？
   - 如何解锁？
 
3. 用户体验：
   - 记住登录状态？
   - 自动填充上次账号？
 
请告诉我你的具体需求...

skill(name="test-driven-development")

// tests/auth/login.spec.ts
import { test, expect } from '@playwright/test';
 
test('用户应该能够成功登录', async ({ page }) => {
  // Given: 用户在登录页
  await page.goto('/login');
 
  // When: 填写正确的凭据并提交
  await page.getByLabel('邮箱').fill('test@example.com');
  await page.getByLabel('密码').fill('password123');
  await page.getByRole('button', { name: '登录' }).click();
 
  // Then: 应该跳转到仪表板
  await expect(page).toHaveURL('/dashboard');
});

npx playwright test tests/auth/login.spec.ts
 
# 期望输出：Error: page.waitForURL: Timeout
# （说明测试正确地失败了，因为功能还没实现）

// app/login/page.tsx
'use client';
 
import { useRouter } from 'next/navigation';
import { FormEvent } from 'react';
 
export default function LoginPage() {
  const router = useRouter();
 
  const handleSubmit = async (e: FormEvent) => {
    e.preventDefault();
    // 最小实现：直接跳转（后续再实现真正的认证逻辑）
    router.push('/dashboard');
  };
 
  return (
    <form onSubmit={handleSubmit}>
      <input aria-label="邮箱" type="email" name="email" />
      <input aria-label="密码" type="password" name="password" />
      <button type="submit">登录</button>
    </form>
  );
}

npx playwright test tests/auth/login.spec.ts
# 期望：1 passed

// 重构内容：
// 1. 提取表单组件
// 2. 添加表单验证
// 3. 实现真正的认证逻辑
// 4. 添加错误处理
 
// 每次重构后都要运行测试，确保不破坏功能
npx playwright test tests/auth/login.spec.ts
# 期望：1 passed

✅ 推荐使用:
- 核心业务逻辑
- 支付、认证等高风险模块
- 复杂算法实现
- 需要长期维护的代码

❌ 可跳过:
- UI/UX 密集型代码
- 快速原型验证
- 一次性脚本
- 配置文件修改

skill(name="systematic-debugging")

用户: 登录失败 3 次没有锁定账户
 
AI (systematic-debugging 模式):
让我系统化地调试这个问题...
 
步骤 1: 复现问题
- 输入错误密码 3 次
- 观察账户状态
- 结果：账户未被锁定
 
步骤 2: 检查相关代码
- 查找登录逻辑：src/auth/login.ts
- 查找锁定逻辑：src/auth/lockout.ts
 
步骤 3: 定位问题
- 发现：lockout.ts 中的计数器没有正确递增
- 原因：使用了错误的变量名
 
步骤 4: 验证假设
- 修复变量名
- 运行测试
 
步骤 5: 确认修复
- 测试通过
- 手动验证：账户正确锁定

skill(name="verification-before-completion")

⚠️ 无验证证据 = 未完成

必须验证：
1. 类型检查：pnpm typecheck
2. 构建验证：pnpm build
3. 代码检查：pnpm lint
4. 测试通过：pnpm test
5. 功能手动验证（最重要）

- [ ] 代码通过 lint 检查
- [ ] TypeScript 编译无错误
- [ ] 构建成功
- [ ] 测试全部通过
- [ ] 功能手动验证过
- [ ] 边界情况考虑过
- [ ] 安全风险审查过

AI: 登录功能已完成
 
你: 请运行验证
 
AI: 
运行 pnpm typecheck... ✓ 通过
运行 pnpm build... ✓ 通过
运行 pnpm lint... ✓ 通过
运行 pnpm test... ✓ 8 passed
 
验证结果：
- 类型检查：通过
- 构建：成功
- Lint：无错误
- 测试：8 passed
 
请手动验证：
1. 在浏览器中测试登录功能
2. 测试失败 3 次锁定
3. 测试锁定后解锁
 
你: 手动验证通过，确认完成

skill(name="writing-plans")

skill(name="executing-plans")

skill(name="requesting-code-review")

skill(name="receiving-code-review")

# 1. 全局安装 MCP 工具
npm install -g @playwright/mcp@latest
npm install -g chrome-devtools-mcp
npm install -g real-browser-mcp
 
# 2. 修改配置文件
# 编辑 .ai/.config/opencode/opencode.json
# 在 "mcp" 对象中添加配置（见下文）

// opencode.json
{
  "mcp": {
    "playwright-mcp": {
      "command": ["playwright-mcp", "--cdp-endpoint", "http://localhost:9222"],
      "enabled": false,
      "type": "local"
    }
  }
}

# 启动开发服务器
pnpm dev
 
# 启用 Playwright MCP（修改配置：enabled: true）
 
# 自然语言指令
"打开 http://localhost:3000/login，填写测试账号并提交"
"验证登录成功后跳转到 /dashboard"

// opencode.json
{
  "mcp": {
    "chrome-devtools-mcp": {
      "command": ["chrome-devtools-mcp", "-u", "http://localhost:9222"],
      "enabled": false,
      "type": "local"
    }
  }
}

# 启动 Chrome 并开启调试端口
google-chrome --remote-debugging-port=9222
 
# 或使用快捷脚本
pnpm chrome:debug

# 性能分析
"在 localhost:3000/products 运行性能追踪"
"报告 LCP、CLS、INP 指标并提供改进建议"
 
# 网络调试
"检查 localhost:3000/api/users 的网络请求"
"分析请求耗时和响应数据"
 
# 控制台调试
"捕获 localhost:3000 的控制台错误"
"分析错误堆栈并提供修复建议"

// opencode.json
{
  "mcp": {
    "real-browser-mcp": {
      "command": ["real-browser-mcp"],
      "enabled": false,
      "type": "local",
      "environment": {
        "PORT": "7225"
      }
    }
  }
}

# 默认：headless 模式，端口 9851
scripts/real_browser.sh
 
# 可见窗口模式
scripts/real_browser.sh --headed
 
# 自定义端口
scripts/real_browser.sh 9888
 
# 保留登录状态（更快启动）
scripts/real_browser.sh --keep-profile

问：需要什么类型的浏览器自动化？
│
├─ 开发新功能 / E2E 测试
│   └─ 使用 Playwright MCP
│
├─ 性能分析 / 问题诊断
│   └─ 使用 Chrome DevTools MCP
│
├─ 已登录场景 / 真实环境
│   └─ 使用 Real Browser MCP
│
└─ 复杂场景（组合使用）
    └─ Playwright MCP (开发) + Chrome DevTools MCP (调试)

# 阶段 1: 开发（Playwright MCP）
@planner 为用户注册流程生成测试计划
@generator 将测试计划转换为测试代码
 
# 阶段 2: 实现
# AI 生成代码，人审查并调整
 
# 阶段 3: 验证（Playwright MCP）
npx playwright test
 
# 阶段 4: 性能检查（Chrome DevTools MCP）
"在注册页面运行性能追踪"
"确保 LCP < 2.5s"
 
# 阶段 5: 真实环境验证（Real Browser MCP）
"使用已登录账号验证注册流程"

# 阶段 1: 复现（Chrome DevTools MCP）
"捕获 localhost:3000/dashboard 的控制台错误"
"分析错误堆栈"
 
# 阶段 2: 定位
# 人根据错误信息定位代码位置
 
# 阶段 3: TDD 修复
# 写失败的测试复现 bug
# 修复代码
# 确认测试通过
 
# 阶段 4: 验证（Playwright MCP）
npx playwright test

# 加载技能
skill(name="real-browser")
 
# 同时需要加载 agent-browser 技能
skill(name="agent-browser")

# 默认：headless 模式，端口 9851
scripts/real_browser.sh
 
# 可见窗口模式
scripts/real_browser.sh --headed
 
# 自定义端口
scripts/real_browser.sh 9888
 
# 保留登录状态
scripts/real_browser.sh --keep-profile

# 1. 启动浏览器
scripts/real_browser.sh
 
# 2. 使用 agent-browser 操作
agent-browser --cdp 9851 open https://x.com
agent-browser --cdp 9851 wait --load networkidle
agent-browser --cdp 9851 snapshot -i
 
# 3. 点击元素
agent-browser --cdp 9851 click @e3
 
# 4. 填写表单
agent-browser --cdp 9851 fill @e5 "hello@world.com"

skill(name="chrome-devtools")

# 1. 导航到页面
"打开 https://example.com"
 
# 2. 等待内容加载
"等待页面加载完成"
 
# 3. 获取页面快照
"获取页面结构"
 
# 4. 性能分析
"运行性能追踪"
"报告 LCP、CLS、INP 指标"
 
# 5. 网络调试
"检查网络请求"
"分析请求耗时"

skill(name="web-design-reviewer")

# 1. 提供 URL
用户: 请审查 http://localhost:3000 的设计
 
AI:
开始设计审查...
 
## 信息收集
- 框架：Next.js 15
- 样式：Tailwind CSS
- 检查范围：首页
 
## 视觉检查
正在检查桌面视图 (1280px)...
正在检查移动视图 (375px)...
 
## 发现问题
 
### [P1] 按钮溢出
- 页面：首页
- 元素：.cta-button
- 问题：按钮在小屏幕上溢出容器
- 修复文件：app/page.tsx
 
### [P2] 对比度不足
- 页面：首页
- 元素：.description
- 问题：文本对比度 3.2:1，低于 WCAG AA 标准 4.5:1
- 修复文件：app/globals.css
 
## 修复中...
✓ 按钮溢出已修复
✓ 对比度已修复
 
## 重新验证
✓ 桌面视图正常
✓ 移动视图正常
 
## 完成报告
- 检测问题：2
- 修复问题：2
- 未修复：0

skill(name="code-simplifier")

// 检查用户是否可以访问
function checkAccess(user: User, resource: Resource): boolean {
  let canAccess = false;
  if (user !== null) {
    if (user.isActive === true) {
      if (resource.isPublic === true) {
        canAccess = true;
      } else {
        if (user.role === 'admin') {
          canAccess = true;
        } else {
          if (user.permissions.includes(resource.requiredPermission)) {
            canAccess = true;
          } else {
            canAccess = false;
          }
        }
      }
    } else {
      canAccess = false;
    }
  } else {
    canAccess = false;
  }
  return canAccess;
}

function checkAccess(user: User | null, resource: Resource): boolean {
  if (!user?.isActive) return false;
  if (resource.isPublic) return true;
  if (user.role === 'admin') return true;
  return user.permissions.includes(resource.requiredPermission);
}

skill(name="review-and-refactor")

用户: 请审查并重构 src/auth/ 目录下的代码
 
AI:
正在审查代码...
 
## 审查结果
 
### 发现问题
 
1. **命名不规范**
   - 文件：src/auth/login.ts
   - 问题：函数名 `doLogin` 不符合 camelCase 规范
   - 建议：改为 `login`
 
2. **重复代码**
   - 文件：src/auth/login.ts, src/auth/register.ts
   - 问题：验证逻辑重复
   - 建议：提取到共享函数
 
3. **缺少类型注解**
   - 文件：src/auth/utils.ts
   - 问题：函数缺少返回类型
   - 建议：添加显式类型注解
 
## 重构中...
 
✓ 重命名 doLogin → login
✓ 提取共享验证函数到 src/auth/validation.ts
✓ 添加类型注解
 
## 验证
运行 pnpm test... ✓ 通过
运行 pnpm typecheck... ✓ 通过
 
重构完成！

skill(name="frontend-design")

用户: 创建一个登录页面
 
AI (frontend-design 模式):
我将创建一个现代、精致的登录页面...
 
[生成代码]
- 独特的视觉风格
- 精心设计的交互
- 响应式布局
- 可访问性支持

skill(name="shadcn-ui")

# 初始化
npx shadcn@latest init
 
# 安装组件
npx shadcn@latest add button
npx shadcn@latest add dialog
npx shadcn@latest add form
 
# 使用组件
import { Button } from "@/components/ui/button"
import { Dialog, DialogContent, DialogTrigger } from "@/components/ui/dialog"

skill(name="tailwind-design-system")

/* globals.css */
@theme {
  --color-primary: oklch(0.6 0.2 250);
  --color-secondary: oklch(0.7 0.15 180);
  
  --font-sans: "Inter", system-ui, sans-serif;
  
  --spacing-section: 4rem;
  --radius-card: 1rem;
}

skill(name="ahooks")

import { useRequest, useDebounce } from 'ahooks';
 
function SearchComponent() {
  const [keyword, setKeyword] = useState('');
  const debouncedKeyword = useDebounce(keyword, { wait: 500 });
  
  const { data, loading } = useRequest(
    () => fetchSearchResults(debouncedKeyword),
    { refreshDeps: [debouncedKeyword] }
  );
  
  return (
    <div>
      <input onChange={(e) => setKeyword(e.target.value)} />
      {loading ? 'Loading...' : <Results data={data} />}
    </div>
  );
}

# 直接描述，一句话搞定
"把 handleLogin 函数中的 try-catch 改为返回 Result 类型"
 
"在 utils.ts 中添加一个 formatDate 函数，支持相对时间"
 
"修复 src/api/users.ts 中的 TypeScript 错误"

# 检查 AI 的修改
# - 逻辑是否正确
# - 是否符合项目风格
# - 是否有潜在问题

# 类型检查
pnpm typecheck
 
# 手动验证
# 在浏览器中测试功能

# 步骤 1：描述需求
用户: 在 src/utils/date.ts 中添加一个 formatDate 函数，支持：
- 相对时间（如"3 分钟前"）
- 绝对时间（如"2026-03-27 10:30"）
- 自动选择（小于 24 小时用相对时间）
 
# 步骤 2：AI 执行
AI:
好的，我来添加这个函数...
 
创建文件：src/utils/date.ts
 
```typescript
/**
 * 格式化日期
 * @param date - 日期对象或时间戳
 * @param mode - 格式化模式：'relative' | 'absolute' | 'auto'
 */
export function formatDate(
  date: Date | number,
  mode: 'relative' | 'absolute' | 'auto' = 'auto'
): string {
  const timestamp = typeof date === 'number' ? date : date.getTime();
  const now = Date.now();
  const diff = now - timestamp;
  
  if (mode === 'relative' || (mode === 'auto' && diff < 24 * 60 * 60 * 1000)) {
    return formatRelative(diff);
  }
  
  return formatAbsolute(new Date(timestamp));
}
 
function formatRelative(diff: number): string {
  const seconds = Math.floor(diff / 1000);
  const minutes = Math.floor(seconds / 60);
  const hours = Math.floor(minutes / 60);
  
  if (seconds < 60) return '刚刚';
  if (minutes < 60) return `${minutes} 分钟前`;
  if (hours < 24) return `${hours} 小时前`;
  return `${Math.floor(hours / 24)} 天前`;
}
 
function formatAbsolute(date: Date): string {
  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, '0');
  const day = String(date.getDate()).padStart(2, '0');
  const hour = String(date.getHours()).padStart(2, '0');
  const minute = String(date.getMinutes()).padStart(2, '0');
  
  return `${year}-${month}-${day} ${hour}:${minute}`;
}

---

## 12. 中等任务：Plan Mode + 验证

### 12.1 适用场景

**特征**：
- 涉及多个文件
- 需要理解现有代码模式
- 有明确的验收标准
- 需要先规划再执行

**示例**：
- 添加用户权限系统
- 重构某个模块
- 集成第三方服务
- 添加新功能

### 12.2 操作步骤

```mermaid
flowchart TB
    A[描述需求] --> B[AI 分析并制定计划]
    B --> C[审查计划]
    C --> D{计划合理？}
    D -->|否| E[调整需求]
    E --> B
    D -->|是| F[分步实现]
    F --> G[每步验证]
    G --> H{还有步骤？}
    H -->|是| F
    H -->|否| I[最终验证]

"我需要添加用户权限系统。先分析现有代码，然后制定实施计划。"

## 目标
[一句话描述要达成什么]
 
## 涉及文件
- file1.ts - [修改原因]
- file2.ts - [修改原因]
 
## 实施步骤
1. [第一步] → 验证点：[如何验证]
2. [第二步] → 验证点：[如何验证]
3. [第三步] → 验证点：[如何验证]
 
## 风险点
- [潜在问题及应对]

# 步骤 1：描述需求
用户: 我需要添加用户权限系统。要求：
1. 支持角色：admin、editor、viewer
2. 支持权限：read、write、delete
3. 角色与权限的映射关系
4. 在 API 中间件中检查权限
 
# 步骤 2：AI 分析并制定计划
AI:
让我分析现有代码结构...
 
## 分析结果
- 当前认证：src/auth/middleware.ts
- 用户模型：src/models/user.ts
- API 路由：src/api/*
 
## 实施计划
 
### 目标
添加基于角色的权限控制系统
 
### 涉及文件
- src/models/user.ts - 添加角色字段
- src/auth/permissions.ts - 新建权限定义
- src/auth/middleware.ts - 添加权限检查
- src/api/users/route.ts - 应用权限检查
 
### 实施步骤
1. 定义权限和角色 → 验证：类型检查通过
2. 更新用户模型 → 验证：数据库迁移成功
3. 创建权限中间件 → 验证：单元测试通过
4. 应用到 API 路由 → 验证：集成测试通过
 
### 风险点
- 现有用户默认角色：需要设置默认值
- 权限检查遗漏：需要全面审查 API
 
是否确认此计划？
 
# 步骤 3：审查并确认
用户: 确认，开始执行
 
# 步骤 4：分步实现
AI:
开始执行步骤 1：定义权限和角色...
 
[创建 src/auth/permissions.ts]
 
```typescript
// 权限定义
export type Permission = 'read' | 'write' | 'delete';
 
// 角色定义
export type Role = 'admin' | 'editor' | 'viewer';
 
// 角色权限映射
export const ROLE_PERMISSIONS: Record<Role, Permission[]> = {
  admin: ['read', 'write', 'delete'],
  editor: ['read', 'write'],
  viewer: ['read'],
};
 
// 检查权限
export function hasPermission(role: Role, permission: Permission): boolean {
  return ROLE_PERMISSIONS[role].includes(permission);
}

import { Role } from '../auth/permissions';
 
interface User {
  id: string;
  email: string;
  name: string;
  role: Role;  // 新增
  createdAt: Date;
  updatedAt: Date;
}

---

## 13. 核心功能：TDD + AI

### 13.1 适用场景

**特征**：
- 核心业务逻辑
- 支付、认证等高风险模块
- 复杂算法实现
- 需要长期维护的代码

### 13.2 RED-GREEN-REFACTOR 循环

```mermaid
flowchart TB
    subgraph RED["RED 阶段"]
        R1[写失败测试] --> R2[运行测试确认失败]
        R2 --> R3{失败原因正确？}
        R3 -->|否| R4[修正测试]
        R4 --> R2
        R3 -->|是| G1
    end
    
    subgraph GREEN["GREEN 阶段"]
        G1[写最小实现] --> G2[运行测试确认通过]
        G2 --> G3{测试通过？}
        G3 -->|否| G4[修改代码]
        G4 --> G2
        G3 -->|是| F1
    end
    
    subgraph REFACTOR["REFACTOR 阶段"]
        F1[重构代码] --> F2[运行测试确认通过]
        F2 --> F3{测试通过？}
        F3 -->|否| F4[回滚或修复]
        F4 --> F2
        F3 -->|是| F5{还有功能？}
        F5 -->|是| R1
        F5 -->|否| DONE[完成]
    end

// tests/auth/login.spec.ts
import { describe, test, expect, beforeEach } from 'vitest';
import { login, LoginError } from '@/auth/login';
 
describe('login', () => {
  const validEmail = 'user@example.com';
  const validPassword = 'password123';
  
  beforeEach(() => {
    // 重置测试状态
    resetAuthState();
  });
  
  test('成功登录返回 token', async () => {
    const result = await login(validEmail, validPassword);
    
    expect(result.success).toBe(true);
    expect(result.token).toBeDefined();
    expect(result.token).toMatch(/^eyJ/);  // JWT 格式
  });
  
  test('密码错误返回失败', async () => {
    const result = await login(validEmail, 'wrong-password');
    
    expect(result.success).toBe(false);
    expect(result.error).toBe(LoginError.INVALID_CREDENTIALS);
  });
  
  test('失败 3 次锁定账户', async () => {
    // 失败 3 次
    await login(validEmail, 'wrong');
    await login(validEmail, 'wrong');
    await login(validEmail, 'wrong');
    
    // 第 4 次即使密码正确也应该被锁定
    const result = await login(validEmail, validPassword);
    
    expect(result.success).toBe(false);
    expect(result.error).toBe(LoginError.ACCOUNT_LOCKED);
  });
  
  test('锁定 15 分钟后自动解锁', async () => {
    // 失败 3 次锁定
    await login(validEmail, 'wrong');
    await login(validEmail, 'wrong');
    await login(validEmail, 'wrong');
    
    // 模拟 15 分钟后
    vi.useFakeTimers();
    vi.advanceTimersByTime(15 * 60 * 1000);
    
    const result = await login(validEmail, validPassword);
    
    expect(result.success).toBe(true);
    
    vi.useRealTimers();
  });
});

pnpm test tests/auth/login.spec.ts
 
# 期望输出：
# ❌ login 成功登录返回 token
#    Error: Cannot find module '@/auth/login'
# ❌ login 密码错误返回失败
# ❌ login 失败 3 次锁定账户
# ❌ login 锁定 15 分钟后自动解锁

// src/auth/login.ts
import jwt from 'jsonwebtoken';
 
export enum LoginError {
  INVALID_CREDENTIALS = 'INVALID_CREDENTIALS',
  ACCOUNT_LOCKED = 'ACCOUNT_LOCKED',
}
 
interface LoginResult {
  success: boolean;
  token?: string;
  error?: LoginError;
}
 
// 简单的内存存储（实际项目用数据库）
const failedAttempts = new Map<string, number>();
const lockoutUntil = new Map<string, number>();
 
export async function login(
  email: string,
  password: string
): Promise<LoginResult> {
  // 检查是否被锁定
  const lockoutTime = lockoutUntil.get(email);
  if (lockoutTime && Date.now() < lockoutTime) {
    return { success: false, error: LoginError.ACCOUNT_LOCKED };
  }
  
  // 验证凭据（简化版，实际项目要查数据库）
  const validCredentials = email === 'user@example.com' && password === 'password123';
  
  if (!validCredentials) {
    // 记录失败次数
    const attempts = (failedAttempts.get(email) || 0) + 1;
    failedAttempts.set(email, attempts);
    
    // 3 次失败后锁定
    if (attempts >= 3) {
      lockoutUntil.set(email, Date.now() + 15 * 60 * 1000);
    }
    
    return { success: false, error: LoginError.INVALID_CREDENTIALS };
  }
  
  // 登录成功，重置失败计数
  failedAttempts.delete(email);
  lockoutUntil.delete(email);
  
  // 生成 token
  const token = jwt.sign({ email }, process.env.JWT_SECRET!, { expiresIn: '1h' });
  
  return { success: true, token };
}
 
// 测试辅助函数
export function resetAuthState() {
  failedAttempts.clear();
  lockoutUntil.clear();
}

pnpm test tests/auth/login.spec.ts
 
# 期望输出：
# ✓ login 成功登录返回 token
# ✓ login 密码错误返回失败
# ✓ login 失败 3 次锁定账户
# ✓ login 锁定 15 分钟后自动解锁
# 
# Test Files  1 passed
# Tests       4 passed

// src/auth/login.ts（重构后）
import jwt from 'jsonwebtoken';
 
export enum LoginError {
  INVALID_CREDENTIALS = 'INVALID_CREDENTIALS',
  ACCOUNT_LOCKED = 'ACCOUNT_LOCKED',
  USER_NOT_FOUND = 'USER_NOT_FOUND',
}
 
interface User {
  id: string;
  email: string;
  passwordHash: string;
}
 
interface LoginResult {
  success: boolean;
  token?: string;
  error?: LoginError;
}
 
interface AuthConfig {
  maxAttempts: number;
  lockoutDurationMs: number;
  tokenExpiry: string;
}
 
const DEFAULT_CONFIG: AuthConfig = {
  maxAttempts: 3,
  lockoutDurationMs: 15 * 60 * 1000,  // 15 分钟
  tokenExpiry: '1h',
};
 
export class AuthService {
  private failedAttempts = new Map<string, number>();
  private lockoutUntil = new Map<string, number>();
  
  constructor(
    private getUser: (email: string) => Promise<User | null>,
    private config: AuthConfig = DEFAULT_CONFIG
  ) {}
  
  async login(email: string, password: string): Promise<LoginResult> {
    // 检查锁定状态
    if (this.isLocked(email)) {
      return { success: false, error: LoginError.ACCOUNT_LOCKED };
    }
    
    // 获取用户
    const user = await this.getUser(email);
    if (!user) {
      return { success: false, error: LoginError.USER_NOT_FOUND };
    }
    
    // 验证密码
    const validPassword = await this.verifyPassword(password, user.passwordHash);
    if (!validPassword) {
      this.recordFailure(email);
      return { success: false, error: LoginError.INVALID_CREDENTIALS };
    }
    
    // 登录成功
    this.clearFailures(email);
    const token = this.generateToken(user);
    
    return { success: true, token };
  }
  
  private isLocked(email: string): boolean {
    const lockoutTime = this.lockoutUntil.get(email);
    return lockoutTime !== undefined && Date.now() < lockoutTime;
  }
  
  private recordFailure(email: string): void {
    const attempts = (this.failedAttempts.get(email) || 0) + 1;
    this.failedAttempts.set(email, attempts);
    
    if (attempts >= this.config.maxAttempts) {
      this.lockoutUntil.set(
        email,
        Date.now() + this.config.lockoutDurationMs
      );
    }
  }
  
  private clearFailures(email: string): void {
    this.failedAttempts.delete(email);
    this.lockoutUntil.delete(email);
  }
  
  private generateToken(user: User): string {
    return jwt.sign(
      { sub: user.id, email: user.email },
      process.env.JWT_SECRET!,
      { expiresIn: this.config.tokenExpiry }
    );
  }
  
  private async verifyPassword(password: string, hash: string): Promise<boolean> {
    // 实际项目使用 bcrypt 或 argon2
    const bcrypt = await import('bcrypt');
    return bcrypt.compare(password, hash);
  }
  
  // 测试辅助方法
  resetState(): void {
    this.failedAttempts.clear();
    this.lockoutUntil.clear();
  }
}

pnpm test tests/auth/login.spec.ts
 
# 期望输出：
# ✓ login 成功登录返回 token
# ✓ login 密码错误返回失败
# ✓ login 失败 3 次锁定账户
# ✓ login 锁定 15 分钟后自动解锁
# 
# Test Files  1 passed
# Tests       4 passed

/opsx-propose add-payment-system

# 支付系统
 
## 概述
实现完整的支付系统，支持订单创建、支付处理、回调通知。
 
## 用户故事
作为用户，我想要在线支付订单，以便完成购买。
 
## 验收标准
- [ ] 用户可以创建订单
- [ ] 用户可以选择支付方式（微信、支付宝）
- [ ] 支付成功后订单状态更新
- [ ] 支付失败后订单状态更新
- [ ] 支付超时后订单自动取消
- [ ] 支付回调验签正确
 
## 约束条件
- 必须使用 HTTPS
- 必须验证支付回调签名
- 敏感信息必须加密存储
 
## 非目标
- 不包含退款功能（后续迭代）
- 不包含分期付款（后续迭代）

# 支付系统设计
 
## 架构
 
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   前端      │────▶│   API       │────▶│  支付网关   │
│  (Next.js)  │     │  (Node.js)  │     │ (微信/支付宝)│
└─────────────┘     └─────────────┘     └─────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │   数据库    │
                    │ (PostgreSQL)│
                    └─────────────┘
 
## 数据模型
 
### Order（订单）
- id: UUID
- userId: UUID
- amount: Decimal
- status: Enum (pending, paid, failed, cancelled)
- paymentMethod: Enum (wechat, alipay)
- createdAt: DateTime
- paidAt: DateTime?
 
### Payment（支付记录）
- id: UUID
- orderId: UUID
- transactionId: String
- status: Enum
- rawCallback: JSON
- createdAt: DateTime
 
## API 设计
 
### POST /api/orders
创建订单
 
### POST /api/orders/:id/pay
发起支付
 
### POST /api/payments/callback/wechat
微信支付回调
 
### POST /api/payments/callback/alipay
支付宝支付回调
 
## 安全考虑
1. 回调验签
2. 幂等性处理
3. 金额校验
4. 超时处理

# 支付系统任务
 
## 阶段 1：基础设施
- [ ] 创建数据库迁移
- [ ] 定义数据模型
- [ ] 创建基础 API 路由
 
## 阶段 2：订单模块
- [ ] 实现订单创建 API
- [ ] 实现订单查询 API
- [ ] 编写订单测试
 
## 阶段 3：支付模块
- [ ] 集成微信支付 SDK
- [ ] 集成支付宝 SDK
- [ ] 实现支付发起 API
- [ ] 实现支付回调 API
- [ ] 编写支付测试
 
## 阶段 4：前端
- [ ] 创建订单页面
- [ ] 创建支付页面
- [ ] 创建支付结果页面
 
## 阶段 5：集成测试
- [ ] 端到端测试
- [ ] 性能测试
- [ ] 安全测试

# 使用 Prometheus 规划师
/start-work
 
# 或直接对话规划
"基于支付系统规格，生成详细的技术实现计划"

# 全功率执行
ultrawork
 
# 或标准执行
/opsx-apply add-payment-system

/opsx-archive add-payment-system

/opsx-propose add-phone-login

openspec/changes/add-phone-login/
├── proposal.md
├── design.md
└── tasks.md

skill(name="test-driven-development")

// tests/auth/phone-login.spec.ts
import { describe, test, expect, beforeEach, vi } from 'vitest';
 
describe('手机号登录', () => {
  const validPhone = '13800138000';
  const validCode = '123456';
  
  beforeEach(() => {
    vi.clearAllMocks();
  });
  
  describe('发送验证码', () => {
    test('有效手机号发送成功', async () => {
      const result = await sendVerificationCode(validPhone);
      
      expect(result.success).toBe(true);
      expect(result.message).toBe('验证码已发送');
    });
    
    test('无效手机号返回错误', async () => {
      const result = await sendVerificationCode('12345');
      
      expect(result.success).toBe(false);
      expect(result.error).toBe('手机号格式错误');
    });
    
    test('60 秒内重复发送返回错误', async () => {
      await sendVerificationCode(validPhone);
      const result = await sendVerificationCode(validPhone);
      
      expect(result.success).toBe(false);
      expect(result.error).toBe('验证码发送过于频繁');
    });
  });
  
  describe('验证码登录', () => {
    test('正确验证码登录成功', async () => {
      await sendVerificationCode(validPhone);
      const result = await loginWithPhone(validPhone, validCode);
      
      expect(result.success).toBe(true);
      expect(result.token).toBeDefined();
    });
    
    test('错误验证码登录失败', async () => {
      await sendVerificationCode(validPhone);
      const result = await loginWithPhone(validPhone, '000000');
      
      expect(result.success).toBe(false);
      expect(result.error).toBe('验证码错误');
    });
    
    test('过期验证码登录失败', async () => {
      await sendVerificationCode(validPhone);
      
      // 模拟 6 分钟后
      vi.useFakeTimers();
      vi.advanceTimersByTime(6 * 60 * 1000);
      
      const result = await loginWithPhone(validPhone, validCode);
      
      expect(result.success).toBe(false);
      expect(result.error).toBe('验证码已过期');
      
      vi.useRealTimers();
    });
  });
});

// src/auth/phone-login.ts
import jwt from 'jsonwebtoken';
 
interface SendCodeResult {
  success: boolean;
  message?: string;
  error?: string;
}
 
interface LoginResult {
  success: boolean;
  token?: string;
  error?: string;
}
 
// 验证码存储（实际项目用 Redis）
const verificationCodes = new Map<string, { code: string; expiresAt: number }>();
const lastSentAt = new Map<string, number>();
 
// 手机号验证
function isValidPhone(phone: string): boolean {
  return /^1[3-9]\d{9}$/.test(phone);
}
 
// 发送验证码
export async function sendVerificationCode(phone: string): Promise<SendCodeResult> {
  // 验证手机号
  if (!isValidPhone(phone)) {
    return { success: false, error: '手机号格式错误' };
  }
  
  // 检查发送频率
  const lastSent = lastSentAt.get(phone);
  if (lastSent && Date.now() - lastSent < 60 * 1000) {
    return { success: false, error: '验证码发送过于频繁' };
  }
  
  // 生成验证码
  const code = Math.random().toString().slice(2, 8);
  const expiresAt = Date.now() + 5 * 60 * 1000;  // 5 分钟有效
  
  // 存储
  verificationCodes.set(phone, { code, expiresAt });
  lastSentAt.set(phone, Date.now());
  
  // 发送（实际项目调用短信服务）
  console.log(`[SMS] 发送验证码 ${code} 到 ${phone}`);
  
  return { success: true, message: '验证码已发送' };
}
 
// 验证码登录
export async function loginWithPhone(phone: string, code: string): Promise<LoginResult> {
  // 验证手机号
  if (!isValidPhone(phone)) {
    return { success: false, error: '手机号格式错误' };
  }
  
  // 获取存储的验证码
  const stored = verificationCodes.get(phone);
  
  if (!stored) {
    return { success: false, error: '请先获取验证码' };
  }
  
  // 检查是否过期
  if (Date.now() > stored.expiresAt) {
    verificationCodes.delete(phone);
    return { success: false, error: '验证码已过期' };
  }
  
  // 验证码校验
  if (stored.code !== code) {
    return { success: false, error: '验证码错误' };
  }
  
  // 登录成功，清除验证码
  verificationCodes.delete(phone);
  
  // 生成 token
  const token = jwt.sign(
    { phone },
    process.env.JWT_SECRET!,
    { expiresIn: '7d' }
  );
  
  return { success: true, token };
}

// app/api/auth/send-code/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { sendVerificationCode } from '@/auth/phone-login';
 
export async function POST(request: NextRequest) {
  const { phone } = await request.json();
  
  const result = await sendVerificationCode(phone);
  
  return NextResponse.json(result);
}

// app/api/auth/phone-login/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { loginWithPhone } from '@/auth/phone-login';
 
export async function POST(request: NextRequest) {
  const { phone, code } = await request.json();
  
  const result = await loginWithPhone(phone, code);
  
  return NextResponse.json(result);
}

// app/login/page.tsx
'use client';
 
import { useState } from 'react';
import { useRouter } from 'next/navigation';
 
export default function PhoneLoginPage() {
  const router = useRouter();
  const [phone, setPhone] = useState('');
  const [code, setCode] = useState('');
  const [countdown, setCountdown] = useState(0);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState('');
  
  // 发送验证码
  const handleSendCode = async () => {
    if (countdown > 0) return;
    
    setLoading(true);
    setError('');
    
    try {
      const res = await fetch('/api/auth/send-code', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ phone }),
      });
      
      const data = await res.json();
      
      if (data.success) {
        // 开始倒计时
        setCountdown(60);
        const timer = setInterval(() => {
          setCountdown((prev) => {
            if (prev <= 1) {
              clearInterval(timer);
              return 0;
            }
            return prev - 1;
          });
        }, 1000);
      } else {
        setError(data.error);
      }
    } finally {
      setLoading(false);
    }
  };
  
  // 登录
  const handleLogin = async () => {
    setLoading(true);
    setError('');
    
    try {
      const res = await fetch('/api/auth/phone-login', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ phone, code }),
      });
      
      const data = await res.json();
      
      if (data.success) {
        // 存储 token
        localStorage.setItem('token', data.token);
        router.push('/dashboard');
      } else {
        setError(data.error);
      }
    } finally {
      setLoading(false);
    }
  };
  
  return (
    <div className="min-h-screen flex items-center justify-center bg-gray-50">
      <div className="max-w-md w-full space-y-8 p-8 bg-white rounded-lg shadow">
        <h2 className="text-2xl font-bold text-center">手机号登录</h2>
        
        {error && (
          <div className="p-3 text-red-600 bg-red-50 rounded">
            {error}
          </div>
        )}
        
        <div className="space-y-4">
          <div>
            <label htmlFor="phone" className="block text-sm font-medium">
              手机号
            </label>
            <input
              id="phone"
              type="tel"
              value={phone}
              onChange={(e) => setPhone(e.target.value)}
              placeholder="请输入手机号"
              className="mt-1 block w-full px-3 py-2 border rounded-md"
            />
          </div>
          
          <div>
            <label htmlFor="code" className="block text-sm font-medium">
              验证码
            </label>
            <div className="flex gap-2">
              <input
                id="code"
                type="text"
                value={code}
                onChange={(e) => setCode(e.target.value)}
                placeholder="请输入验证码"
                className="flex-1 px-3 py-2 border rounded-md"
              />
              <button
                onClick={handleSendCode}
                disabled={countdown > 0 || loading}
                className="px-4 py-2 bg-blue-600 text-white rounded-md disabled:opacity-50"
              >
                {countdown > 0 ? `${countdown}s` : '发送验证码'}
              </button>
            </div>
          </div>
          
          <button
            onClick={handleLogin}
            disabled={loading}
            className="w-full py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 disabled:opacity-50"
          >
            {loading ? '登录中...' : '登录'}
          </button>
        </div>
      </div>
    </div>
  );
}