specops 0.2.2 → 0.2.4

package/.opencode/skills/test-driven-development/SKILL.md

@@ -0,0 +1,399 @@
+---
+name: test-driven-development
+description: 实现任何功能或修复bug之前使用，在编写实现代码之前
+---
+
+# 测试驱动开发（TDD）
+
+## 概述
+
+先写测试。看它失败。写最少的代码让它通过。
+
+**核心原则：** 如果你没有看到测试失败，你就不知道它是否测试了正确的东西。
+
+**违反规则的字面意思就是违反规则的精神。**
+
+## 何时使用
+
+**始终使用：**
+- 新功能
+- Bug 修复
+- 重构
+- 行为变更
+
+**例外（需征得你的人类搭档同意）：**
+- 一次性原型
+- 生成的代码
+- 配置文件
+
+想着"就这一次跳过 TDD"？停下来。那是自我合理化。
+
+## 铁律
+
+```
+没有先写失败测试，就不能写生产代码
+```
+
+先写了代码再写测试？删掉。从头来过。
+
+**没有例外：**
+- 不要把它留作"参考"
+- 不要在写测试时"改编"它
+- 不要看它
+- 删除就是删除
+
+从测试出发，重新实现。句号。
+
+## 红-绿-重构
+
+```dot
+digraph tdd_cycle {
+    rankdir=LR;
+    red [label="红灯\n写失败测试", shape=box, style=filled, fillcolor="#ffcccc"];
+    verify_red [label="验证失败\n是否正确", shape=diamond];
+    green [label="绿灯\n最少代码", shape=box, style=filled, fillcolor="#ccffcc"];
+    verify_green [label="验证通过\n全部绿灯", shape=diamond];
+    refactor [label="重构\n清理代码", shape=box, style=filled, fillcolor="#ccccff"];
+    next [label="下一个", shape=ellipse];
+
+    red -> verify_red;
+    verify_red -> green [label="是"];
+    verify_red -> red [label="错误的\n失败"];
+    green -> verify_green;
+    verify_green -> refactor [label="是"];
+    verify_green -> green [label="否"];
+    refactor -> verify_green [label="保持\n绿灯"];
+    verify_green -> next;
+    next -> red;
+}
+```
+
+### 红灯 - 写失败测试
+
+写一个最小的测试，展示期望的行为。
+
+<Good>
+```typescript
+test('失败操作重试 3 次', async () => {
+  let attempts = 0;
+  const operation = () => {
+    attempts++;
+    if (attempts < 3) throw new Error('fail');
+    return 'success';
+  };
+
+  const result = await retryOperation(operation);
+
+  expect(result).toBe('success');
+  expect(attempts).toBe(3);
+});
+```
+名称清晰，测试真实行为，只测一件事
+</Good>
+
+<Bad>
+```typescript
+test('重试能用', async () => {
+  const mock = jest.fn()
+    .mockRejectedValueOnce(new Error())
+    .mockRejectedValueOnce(new Error())
+    .mockResolvedValueOnce('success');
+  await retryOperation(mock);
+  expect(mock).toHaveBeenCalledTimes(3);
+});
+```
+名称模糊，测试的是 mock 而不是代码
+</Bad>
+
+**要求：**
+- 一个行为
+- 清晰的名称
+- 真实代码（除非不得已才用 mock）
+
+### 验证红灯 - 看它失败
+
+**必须执行。绝不跳过。**
+
+```bash
+npm test path/to/test.test.ts
+```
+
+确认：
+- 测试失败（不是报错）
+- 失败信息符合预期
+- 因为功能缺失而失败（不是拼写错误）
+
+**测试通过了？** 你在测试已有行为。修改测试。
+
+**测试报错了？** 修复错误，重新运行直到它正确失败。
+
+### 绿灯 - 最少代码
+
+写最简单的代码让测试通过。
+
+<Good>
+```typescript
+async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
+  for (let i = 0; i < 3; i++) {
+    try {
+      return await fn();
+    } catch (e) {
+      if (i === 2) throw e;
+    }
+  }
+  throw new Error('unreachable');
+}
+```
+刚好够通过
+</Good>
+
+<Bad>
+```typescript
+async function retryOperation<T>(
+  fn: () => Promise<T>,
+  options?: {
+    maxRetries?: number;
+    backoff?: 'linear' | 'exponential';
+    onRetry?: (attempt: number) => void;
+  }
+): Promise<T> {
+  // YAGNI（你不会需要它的）
+}
+```
+过度设计
+</Bad>
+
+不要添加功能，不要重构其他代码，不要"改进"测试之外的东西。
+
+### 验证绿灯 - 看它通过
+
+**必须执行。**
+
+```bash
+npm test path/to/test.test.ts
+```
+
+确认：
+- 测试通过
+- 其他测试仍然通过
+- 输出干净（没有错误、警告）
+
+**测试失败了？** 修改代码，不是测试。
+
+**其他测试失败了？** 立刻修复。
+
+### 重构 - 清理代码
+
+只在绿灯之后：
+- 消除重复
+- 改善命名
+- 提取辅助函数
+
+保持测试绿灯。不要添加行为。
+
+### 循环
+
+下一个失败测试，下一个功能。
+
+## 好的测试
+
+| 质量 | 好 | 坏 |
+|------|------|------|
+| **最小化** | 只测一件事。名称里有"和"？拆分它。 | `test('验证邮箱和域名和空格')` |
+| **清晰** | 名称描述行为 | `test('test1')` |
+| **展示意图** | 展示期望的 API | 模糊了代码应该做什么 |
+
+## 为什么顺序很重要
+
+**"我先写代码，之后再写测试来验证"**
+
+先写代码再写的测试会立刻通过。立刻通过什么都证明不了：
+- 可能测错了东西
+- 可能测的是实现，不是行为
+- 可能遗漏了你忘记的边界情况
+- 你从没看到它捕获过 bug
+
+先写测试迫使你看到测试失败，证明它确实在测试某些东西。
+
+**"我已经手动测试了所有边界情况"**
+
+手动测试是随意的。你以为测了所有情况，但是：
+- 没有记录你测了什么
+- 代码变更后无法重新运行
+- 压力下容易遗漏用例
+- "我试过能用" ≠ 全面覆盖
+
+自动化测试是系统性的。每次运行方式完全一样。
+
+**"删掉 X 小时的工作太浪费了"**
+
+沉没成本谬误。时间已经花了。你现在的选择是：
+- 删掉，用 TDD 重写（再花 X 小时，高置信度）
+- 保留，之后补测试（30 分钟，低置信度，很可能有 bug）
+
+"浪费"的是保留你无法信任的代码。没有真正测试的可运行代码就是技术债。
+
+**"TDD 太教条了，务实意味着灵活变通"**
+
+TDD 就是务实的：
+- 提交前发现 bug（比提交后调试快）
+- 防止回归（测试立刻捕获破坏）
+- 记录行为（测试展示如何使用代码）
+- 支持重构（放心改，测试捕获破坏）
+
+"务实"的捷径 = 在生产环境调试 = 更慢。
+
+**"后写测试也能达到同样目的，重要的是精神不是仪式"**
+
+不对。后写测试回答的是"这段代码做了什么？"先写测试回答的是"这段代码应该做什么？"
+
+后写测试受你的实现偏见影响。你测的是你写了什么，不是需求是什么。你验证的是你记得的边界情况，不是你发现的边界情况。
+
+先写测试迫使你在实现之前发现边界情况。后写测试验证的是你记住了所有情况（你没有）。
+
+30 分钟的后补测试 ≠ TDD。你得到了覆盖率，失去了测试有效的证明。
+
+## 常见的自我合理化
+
+| 借口 | 现实 |
+|------|------|
+| "太简单不用测" | 简单代码也会出错。测试只要 30 秒。 |
+| "我之后再测" | 立刻通过的测试什么都证明不了。 |
+| "后写测试也能达到同样目的" | 后写测试 = "这做了什么？" 先写测试 = "这应该做什么？" |
+| "已经手动测过了" | 随意 ≠ 系统性。没有记录，无法重跑。 |
+| "删掉 X 小时的工作太浪费" | 沉没成本谬误。保留未验证代码才是技术债。 |
+| "留着当参考，先写测试" | 你会改编它。那就是后写测试。删除就是删除。 |
+| "需要先探索一下" | 可以。扔掉探索结果，从 TDD 开始。 |
+| "测试难写 = 设计不清楚" | 听测试的话。难测试 = 难使用。 |
+| "TDD 会拖慢我" | TDD 比调试快。务实 = 先写测试。 |
+| "手动测试更快" | 手动测试不能证明边界情况。每次改动你都得重测。 |
+| "现有代码没有测试" | 你在改进它。给现有代码加测试。 |
+
+## 危险信号 - 停下来，从头开始
+
+- 先写了代码再写测试
+- 实现之后才写测试
+- 测试立刻通过
+- 无法解释测试为什么失败
+- 测试"之后再加"
+- 合理化"就这一次"
+- "我已经手动测过了"
+- "后写测试也能达到同样目的"
+- "重要的是精神不是仪式"
+- "留着当参考"或"改编现有代码"
+- "已经花了 X 小时，删掉太浪费"
+- "TDD 太教条了，我是在务实"
+- "这次情况不一样因为..."
+
+**以上所有都意味着：删掉代码。用 TDD 从头开始。**
+
+## 示例：Bug 修复
+
+**Bug：** 空邮箱被接受了
+
+**红灯**
+```typescript
+test('拒绝空邮箱', async () => {
+  const result = await submitForm({ email: '' });
+  expect(result.error).toBe('Email required');
+});
+```
+
+**验证红灯**
+```bash
+$ npm test
+FAIL: expected 'Email required', got undefined
+```
+
+**绿灯**
+```typescript
+function submitForm(data: FormData) {
+  if (!data.email?.trim()) {
+    return { error: 'Email required' };
+  }
+  // ...
+}
+```
+
+**验证绿灯**
+```bash
+$ npm test
+PASS
+```
+
+**重构**
+如果需要，提取验证逻辑用于多个字段。
+
+## 验证检查清单
+
+标记工作完成之前：
+
+- [ ] 每个新函数/方法都有测试
+- [ ] 在实现之前看到每个测试失败
+- [ ] 每个测试因预期原因失败（功能缺失，不是拼写错误）
+- [ ] 为每个测试写了最少的代码让它通过
+- [ ] 所有测试通过
+- [ ] 输出干净（没有错误、警告）
+- [ ] 测试使用真实代码（只在不得已时用 mock）
+- [ ] 覆盖了边界情况和错误情况
+
+不能全部勾选？你跳过了 TDD。从头来过。
+
+## 验收集成
+
+TDD 不只在实现阶段使用。在 specops 验收阶段，TDD 原则同样适用：
+
+### 单元测试验收
+- 运行 `npx vitest run` 确保所有单元测试通过
+- 检查测试覆盖率是否满足项目要求
+- 使用 specops 偷懒检测器扫描：不允许 `expect(true).toBe(true)` 等无意义断言
+
+### 集成测试验收
+- 运行 `tsc --noEmit` 确保类型安全
+- 运行技术偏移检测（tech-guard）确保未引入未批准依赖
+- 检查是否存在 `as any`、`@ts-ignore` 等禁止模式
+
+### E2E 测试验收
+- 由专门的验收 Agent 执行（配置浏览器 MCP）
+- 使用 browser-use `--browser real` 模式或 Playwright MCP
+- 覆盖所有核心业务流程的完整路径
+- 每个业务场景必须有对应的 E2E 用例
+
+### 验收运行器
+- specops 验收运行器（`src/acceptance/runner.ts`）串联所有检查
+- 生成 ACCEPTANCE.md 报告
+- 偷懒检测器（lazyDetector）扫描测试文件质量
+- 技术守护（tech-guard）检测技术偏移
+
+**验收失败 = 实现未完成。** 必须修复后重新验收。
+
+## 卡住时
+
+| 问题 | 解决方案 |
+|------|----------|
+| 不知道怎么测 | 写出你期望的 API。先写断言。问你的人类搭档。 |
+| 测试太复杂 | 设计太复杂。简化接口。 |
+| 必须 mock 所有东西 | 代码耦合太紧。使用依赖注入。 |
+| 测试准备工作太多 | 提取辅助函数。还是复杂？简化设计。 |
+
+## 调试集成
+
+发现 bug？写一个失败测试来复现它。遵循 TDD 循环。测试证明修复有效并防止回归。
+
+永远不要在没有测试的情况下修 bug。
+
+## 测试反模式
+
+添加 mock 或测试工具时，阅读 @testing-anti-patterns.md 避免常见陷阱：
+- 测试 mock 行为而不是真实行为
+- 给生产类添加仅测试用的方法
+- 不理解依赖关系就使用 mock
+
+## 最终规则
+
+```
+生产代码 → 测试存在且先失败过
+否则 → 不是 TDD
+```
+
+没有你的人类搭档的许可，没有例外。

package/.opencode/skills/test-driven-development/testing-anti-patterns.md

@@ -0,0 +1,299 @@
+# 测试反模式
+
+**在以下情况加载此参考文档：** 编写或修改测试、添加 mock、或想给生产代码添加仅测试用方法时。
+
+## 概述
+
+测试必须验证真实行为，不是 mock 行为。Mock 是隔离的手段，不是被测试的对象。
+
+**核心原则：** 测试代码做了什么，不是 mock 做了什么。
+
+**严格遵循 TDD 可以防止这些反模式。**
+
+## 铁律
+
+```
+1. 绝不测试 mock 行为
+2. 绝不给生产类添加仅测试用的方法
+3. 绝不在不理解依赖关系的情况下使用 mock
+```
+
+## 反模式 1：测试 Mock 行为
+
+**违规做法：**
+```typescript
+// ❌ 坏：测试 mock 是否存在
+test('渲染侧边栏', () => {
+  render(<Page />);
+  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
+});
+```
+
+**为什么这是错的：**
+- 你在验证 mock 能用，不是组件能用
+- mock 存在就通过，不存在就失败
+- 对真实行为一无所知
+
+**你的人类搭档的纠正：** "我们是在测试 mock 的行为吗？"
+
+**正确做法：**
+```typescript
+// ✅ 好：测试真实组件或不要 mock 它
+test('渲染侧边栏', () => {
+  render(<Page />);  // 不要 mock 侧边栏
+  expect(screen.getByRole('navigation')).toBeInTheDocument();
+});
+
+// 或者如果必须 mock 侧边栏来隔离：
+// 不要断言 mock 本身，测试 Page 在侧边栏存在时的行为
+```
+
+### 门控函数
+
+```
+在断言任何 mock 元素之前：
+  问自己："我是在测试真实组件行为还是只是 mock 的存在？"
+
+  如果是测试 mock 的存在：
+    停下来 - 删除断言或取消 mock
+
+  测试真实行为
+```
+
+## 反模式 2：给生产代码添加仅测试用的方法
+
+**违规做法：**
+```typescript
+// ❌ 坏：destroy() 只在测试中使用
+class Session {
+  async destroy() {  // 看起来像生产 API！
+    await this._workspaceManager?.destroyWorkspace(this.id);
+    // ... 清理
+  }
+}
+
+// 在测试中
+afterEach(() => session.destroy());
+```
+
+**为什么这是错的：**
+- 生产类被仅测试用的代码污染
+- 如果在生产环境中意外调用很危险
+- 违反 YAGNI 和关注点分离
+- 混淆了对象生命周期和实体生命周期
+
+**正确做法：**
+```typescript
+// ✅ 好：测试工具处理测试清理
+// Session 没有 destroy() - 它在生产环境中是无状态的
+
+// 在 test-utils/ 中
+export async function cleanupSession(session: Session) {
+  const workspace = session.getWorkspaceInfo();
+  if (workspace) {
+    await workspaceManager.destroyWorkspace(workspace.id);
+  }
+}
+
+// 在测试中
+afterEach(() => cleanupSession(session));
+```
+
+### 门控函数
+
+```
+在给生产类添加任何方法之前：
+  问自己："这个方法只在测试中使用吗？"
+
+  如果是：
+    停下来 - 不要添加
+    放到测试工具中
+
+  问自己："这个类拥有这个资源的生命周期吗？"
+
+  如果不是：
+    停下来 - 这个方法放错了类
+```
+
+## 反模式 3：不理解依赖就使用 Mock
+
+**违规做法：**
+```typescript
+// ❌ 坏：Mock 破坏了测试逻辑
+test('检测重复服务器', () => {
+  // Mock 阻止了测试依赖的配置写入！
+  vi.mock('ToolCatalog', () => ({
+    discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
+  }));
+
+  await addServer(config);
+  await addServer(config);  // 应该抛异常，但不会！
+});
+```
+
+**为什么这是错的：**
+- 被 mock 的方法有测试依赖的副作用（写入配置）
+- 为了"安全"过度 mock 破坏了实际行为
+- 测试因为错误的原因通过或莫名其妙地失败
+
+**正确做法：**
+```typescript
+// ✅ 好：在正确的层级 mock
+test('检测重复服务器', () => {
+  // Mock 慢的部分，保留测试需要的行为
+  vi.mock('MCPServerManager'); // 只 mock 慢的服务器启动
+
+  await addServer(config);  // 配置被写入
+  await addServer(config);  // 检测到重复 ✓
+});
+```
+
+### 门控函数
+
+```
+在 mock 任何方法之前：
+  停下来 - 先不要 mock
+
+  1. 问自己："真实方法有什么副作用？"
+  2. 问自己："这个测试依赖这些副作用吗？"
+  3. 问自己："我完全理解这个测试需要什么吗？"
+
+  如果依赖副作用：
+    在更低层级 mock（实际慢的/外部的操作）
+    或者使用保留必要行为的测试替身
+    不要 mock 测试依赖的高层方法
+
+  如果不确定测试依赖什么：
+    先用真实实现运行测试
+    观察实际需要发生什么
+    然后在正确的层级添加最少的 mock
+
+  危险信号：
+    - "我 mock 这个以防万一"
+    - "这个可能很慢，最好 mock 掉"
+    - 不理解依赖链就 mock
+```
+
+## 反模式 4：不完整的 Mock
+
+**违规做法：**
+```typescript
+// ❌ 坏：部分 mock - 只有你认为需要的字段
+const mockResponse = {
+  status: 'success',
+  data: { userId: '123', name: 'Alice' }
+  // 缺少：下游代码使用的 metadata
+};
+
+// 之后：代码访问 response.metadata.requestId 时崩溃
+```
+
+**为什么这是错的：**
+- **部分 mock 隐藏了结构假设** - 你只 mock 了你知道的字段
+- **下游代码可能依赖你没包含的字段** - 静默失败
+- **测试通过但集成失败** - Mock 不完整，真实 API 完整
+- **虚假的信心** - 测试对真实行为什么都没证明
+
+**铁律：** Mock 完整的数据结构，按照它在现实中的样子，不只是你当前测试用到的字段。
+
+**正确做法：**
+```typescript
+// ✅ 好：镜像真实 API 的完整性
+const mockResponse = {
+  status: 'success',
+  data: { userId: '123', name: 'Alice' },
+  metadata: { requestId: 'req-789', timestamp: 1234567890 }
+  // 真实 API 返回的所有字段
+};
+```
+
+### 门控函数
+
+```
+在创建 mock 响应之前：
+  检查："真实 API 响应包含哪些字段？"
+
+  操作：
+    1. 从文档/示例中检查实际 API 响应
+    2. 包含系统下游可能消费的所有字段
+    3. 验证 mock 完全匹配真实响应的 schema
+
+  关键：
+    如果你在创建 mock，你必须理解完整的结构
+    部分 mock 在代码依赖被省略字段时静默失败
+
+  不确定时：包含所有文档记录的字段
+```
+
+## 反模式 5：集成测试当事后补充
+
+**违规做法：**
+```
+✅ 实现完成
+❌ 没写测试
+"准备好测试了"
+```
+
+**为什么这是错的：**
+- 测试是实现的一部分，不是可选的后续步骤
+- TDD 本来就能避免这个问题
+- 没有测试不能声称完成
+
+**正确做法：**
+```
+TDD 循环：
+1. 写失败测试
+2. 实现让它通过
+3. 重构
+4. 然后才能声称完成
+```
+
+## 当 Mock 变得太复杂
+
+**警告信号：**
+- Mock 准备工作比测试逻辑还长
+- 为了让测试通过 mock 了所有东西
+- Mock 缺少真实组件有的方法
+- 改了 mock 测试就挂
+
+**你的人类搭档的问题：** "我们这里真的需要用 mock 吗？"
+
+**考虑：** 使用真实组件的集成测试通常比复杂的 mock 更简单
+
+## TDD 如何防止这些反模式
+
+**为什么 TDD 有帮助：**
+1. **先写测试** → 迫使你思考你到底在测什么
+2. **看它失败** → 确认测试测的是真实行为，不是 mock
+3. **最少实现** → 不会悄悄加入仅测试用的方法
+4. **真实依赖** → 你在 mock 之前就看到测试实际需要什么
+
+**如果你在测试 mock 行为，你违反了 TDD** - 你在没有先让测试对真实代码失败的情况下就加了 mock。
+
+## 快速参考
+
+| 反模式 | 修复方法 |
+|--------|----------|
+| 断言 mock 元素 | 测试真实组件或取消 mock |
+| 生产代码中的仅测试方法 | 移到测试工具中 |
+| 不理解就 mock | 先理解依赖关系，最少化 mock |
+| 不完整的 mock | 完整镜像真实 API |
+| 测试当事后补充 | TDD - 先写测试 |
+| 过于复杂的 mock | 考虑集成测试 |
+
+## 危险信号
+
+- 断言检查 `*-mock` 测试 ID
+- 方法只在测试文件中被调用
+- Mock 准备工作占测试的 >50%
+- 移除 mock 测试就失败
+- 无法解释为什么需要 mock
+- "以防万一"就 mock
+
+## 底线
+
+**Mock 是隔离的工具，不是被测试的对象。**
+
+如果 TDD 揭示你在测试 mock 行为，你走错了方向。
+
+修复方法：测试真实行为，或者质疑你为什么要 mock。