@liangjie559567/ultrapower 5.0.4

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

@@ -0,0 +1,378 @@
+---
+name: test-driven-development
+description: 实现任何功能或 bug 修复时使用，在编写实现代码之前
+---
+
+# 测试驱动开发（TDD）
+
+## 概述
+
+先写测试。看它失败。写最少的代码让它通过。
+
+**核心原则：** 如果你没有看到测试失败，你不知道它是否测试了正确的东西。
+
+**违反规则的字面意思就是违反规则的精神。**
+
+## 使用时机
+
+**始终：**
+- 新功能
+- Bug 修复
+- 重构
+- 行为变更
+
+**例外（询问你的人类伙伴）：**
+- 一次性原型
+- 生成的代码
+- 配置文件
+
+想着"这次跳过 TDD"？停下。那是在自我合理化。
+
+## 铁律
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+在测试之前写了代码？删掉。重新开始。
+
+**无例外：**
+- 不要保留它作为"参考"
+- 不要在写测试时"改编"它
+- 不要看它
+- 删除就是删除
+
+从测试开始全新实现。就这样。
+
+## 红-绿-重构
+
+```dot
+digraph tdd_cycle {
+    rankdir=LR;
+    red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
+    verify_red [label="Verify fails\ncorrectly", shape=diamond];
+    green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
+    verify_green [label="Verify passes\nAll green", shape=diamond];
+    refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
+    next [label="Next", shape=ellipse];
+
+    red -> verify_red;
+    verify_red -> green [label="yes"];
+    verify_red -> red [label="wrong\nfailure"];
+    green -> verify_green;
+    verify_green -> refactor [label="yes"];
+    verify_green -> green [label="no"];
+    refactor -> verify_green [label="stay\ngreen"];
+    verify_green -> next;
+    next -> red;
+}
+```
+
+### RED - 写失败的测试
+
+写一个最小测试，展示应该发生什么。
+
+<Good>
+```typescript
+test('retries failed operations 3 times', 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('retry works', async () => {
+  const mock = jest.fn()
+    .mockRejectedValueOnce(new Error())
+    .mockRejectedValueOnce(new Error())
+    .mockResolvedValueOnce('success');
+  await retryOperation(mock);
+  expect(mock).toHaveBeenCalledTimes(3);
+});
+```
+名称模糊，测试 mock 而非代码
+</Bad>
+
+**要求：**
+- 一个行为
+- 清晰的名称
+- 真实代码（除非不可避免，否则不用 mock）
+
+### 验证 RED - 看它失败
+
+**必须。绝不跳过。**
+
+```bash
+npm test path/to/test.test.ts
+```
+
+确认：
+- 测试失败（不是报错）
+- 失败消息符合预期
+- 因功能缺失而失败（不是拼写错误）
+
+**测试通过了？** 你在测试已有行为。修复测试。
+
+**测试报错了？** 修复错误，重新运行直到正确失败。
+
+### GREEN - 最少代码
+
+写最简单的代码让测试通过。
+
+<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>
+
+不要添加功能、重构其他代码或"改进"超出测试范围的内容。
+
+### 验证 GREEN - 看它通过
+
+**必须。**
+
+```bash
+npm test path/to/test.test.ts
+```
+
+确认：
+- 测试通过
+- 其他测试仍然通过
+- 输出干净（无错误、警告）
+
+**测试失败？** 修复代码，不是测试。
+
+**其他测试失败？** 现在修复。
+
+### REFACTOR - 清理
+
+仅在绿色后：
+- 消除重复
+- 改善命名
+- 提取辅助函数
+
+保持测试绿色。不要添加行为。
+
+### 重复
+
+为下一个功能写下一个失败测试。
+
+## 好的测试
+
+| 质量 | 好 | 差 |
+|---------|------|-----|
+| **最小化** | 一件事。名称中有"and"？拆分它。 | `test('validates email and domain and whitespace')` |
+| **清晰** | 名称描述行为 | `test('test1')` |
+| **展示意图** | 演示期望的 API | 模糊代码应该做什么 |
+
+## 为什么顺序重要
+
+**"我会在之后写测试来验证它是否工作"**
+
+测试写在代码之后会立即通过。立即通过什么都证明不了：
+- 可能测试了错误的东西
+- 可能测试了实现，而非行为
+- 可能遗漏了你忘记的边界情况
+- 你从未看到它捕获 bug
+
+先写测试迫使你看到测试失败，证明它确实在测试某些东西。
+
+**"我已经手动测试了所有边界情况"**
+
+手动测试是临时的。你以为你测试了所有东西，但：
+- 没有测试内容的记录
+- 代码变更时无法重新运行
+- 在压力下容易忘记情况
+- "我试过时它工作了" ≠ 全面测试
+
+自动化测试是系统性的。每次以相同方式运行。
+
+**"删除 X 小时的工作是浪费"**
+
+沉没成本谬误。时间已经过去了。你现在的选择：
+- 删除并用 TDD 重写（再花 X 小时，高置信度）
+- 保留并在之后添加测试（30 分钟，低置信度，可能有 bug）
+
+"浪费"是保留你无法信任的代码。没有真实测试的工作代码是技术债务。
+
+**"TDD 是教条主义，务实意味着适应"**
+
+TDD 就是务实的：
+- 在提交前发现 bug（比之后调试更快）
+- 防止回归（测试立即捕获破坏）
+- 记录行为（测试展示如何使用代码）
+- 支持重构（自由修改，测试捕获破坏）
+
+"务实"的捷径 = 在生产中调试 = 更慢。
+
+**"测试后达到相同目标——是精神而非仪式"**
+
+不。测试后回答"这做什么？"测试前回答"这应该做什么？"
+
+测试后受你的实现偏见影响。你测试你构建的东西，而非需要的东西。你验证记住的边界情况，而非发现的。
+
+测试前在实现前强制发现边界情况。测试后验证你记住了所有东西（你没有）。
+
+30 分钟的测试后 ≠ TDD。你得到覆盖率，失去测试有效的证明。
+
+## 常见自我合理化
+
+| 借口 | 现实 |
+|--------|---------|
+| "太简单了不需要测试" | 简单代码也会出错。测试只需 30 秒。 |
+| "我会在之后测试" | 立即通过的测试什么都证明不了。 |
+| "测试后达到相同目标" | 测试后 = "这做什么？"测试前 = "这应该做什么？" |
+| "已经手动测试了" | 临时 ≠ 系统性。没有记录，无法重新运行。 |
+| "删除 X 小时是浪费" | 沉没成本谬误。保留未验证的代码是技术债务。 |
+| "保留作参考，先写测试" | 你会改编它。那就是测试后。删除就是删除。 |
+| "需要先探索" | 好。丢弃探索，从 TDD 开始。 |
+| "测试困难 = 设计不清晰" | 听测试的。难以测试 = 难以使用。 |
+| "TDD 会让我变慢" | TDD 比调试更快。务实 = 先写测试。 |
+| "手动测试更快" | 手动不能证明边界情况。每次变更都要重新测试。 |
+| "现有代码没有测试" | 你在改进它。为现有代码添加测试。 |
+
+## 红旗——停下并重新开始
+
+- 测试前写了代码
+- 实现后写测试
+- 测试立即通过
+- 无法解释为什么测试失败
+- 测试"稍后"添加
+- 合理化"就这一次"
+- "我已经手动测试了"
+- "测试后达到相同目的"
+- "是精神而非仪式"
+- "保留作参考"或"改编现有代码"
+- "已经花了 X 小时，删除是浪费"
+- "TDD 是教条主义，我在务实"
+- "这不同因为..."
+
+**所有这些都意味着：删除代码。从 TDD 重新开始。**
+
+## 示例：Bug 修复
+
+**Bug：** 接受了空邮箱
+
+**RED**
+```typescript
+test('rejects empty email', async () => {
+  const result = await submitForm({ email: '' });
+  expect(result.error).toBe('Email required');
+});
+```
+
+**验证 RED**
+```bash
+$ npm test
+FAIL: expected 'Email required', got undefined
+```
+
+**GREEN**
+```typescript
+function submitForm(data: FormData) {
+  if (!data.email?.trim()) {
+    return { error: 'Email required' };
+  }
+  // ...
+}
+```
+
+**验证 GREEN**
+```bash
+$ npm test
+PASS
+```
+
+**REFACTOR**
+如需要，为多个字段提取验证。
+
+## 验证清单
+
+标记工作完成前：
+
+- [ ] 每个新函数/方法都有测试
+- [ ] 在实现前看到每个测试失败
+- [ ] 每个测试因预期原因失败（功能缺失，不是拼写错误）
+- [ ] 写了最少代码让每个测试通过
+- [ ] 所有测试通过
+- [ ] 输出干净（无错误、警告）
+- [ ] 测试使用真实代码（仅在不可避免时使用 mock）
+- [ ] 覆盖了边界情况和错误
+
+无法勾选所有项？你跳过了 TDD。重新开始。
+
+## 卡住时
+
+| 问题 | 解决方案 |
+|---------|----------|
+| 不知道如何测试 | 写期望的 API。先写断言。询问你的人类伙伴。 |
+| 测试太复杂 | 设计太复杂。简化接口。 |
+| 必须 mock 所有东西 | 代码耦合太紧。使用依赖注入。 |
+| 测试设置很庞大 | 提取辅助函数。还是复杂？简化设计。 |
+
+## 调试集成
+
+发现 bug？写失败测试重现它。遵循 TDD 循环。测试证明修复并防止回归。
+
+绝不在没有测试的情况下修复 bug。
+
+## 测试反模式
+
+添加 mock 或测试工具时，阅读 @testing-anti-patterns.md 以避免常见陷阱：
+- 测试 mock 行为而非真实行为
+- 向生产类添加仅测试用的方法
+- 不理解依赖就 mock
+
+## 最终规则
+
+```
+Production code → test exists and failed first
+Otherwise → not TDD
+```
+
+未经人类伙伴许可，无例外。
+
+## 路由触发
+
+GREEN 阶段完成后调用 `next-step-router`：
+- current_skill: "test-driven-development"
+- stage: "green_complete"
+- output_summary: 通过的测试数、修改的文件列表

package/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('renders sidebar', () => {
+  render(<Page />);
+  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
+});
+```
+
+**为何错误：**
+- 你在验证 mock 是否有效，而非组件是否有效
+- 有 mock 时测试通过，没有时失败
+- 对真实行为毫无说明
+
+**你的人类伙伴的纠正：** "我们在测试 mock 的行为吗？"
+
+**修复：**
+```typescript
+// ✅ 正确：测试真实组件或不 mock 它
+test('renders sidebar', () => {
+  render(<Page />);  // 不 mock sidebar
+  expect(screen.getByRole('navigation')).toBeInTheDocument();
+});
+
+// 或者如果 sidebar 必须被 mock 以隔离：
+// 不要断言 mock——测试 sidebar 存在时 Page 的行为
+```
+
+### 门控函数
+
+```
+在断言任何 mock 元素之前：
+  问："我在测试真实组件行为还是只是 mock 的存在？"
+
+  如果在测试 mock 的存在：
+    停止——删除断言或取消 mock 该组件
+
+  改为测试真实行为
+```
+
+## 反模式 2：生产代码中的仅测试方法
+
+**违规：**
+```typescript
+// ❌ 错误：destroy() 只在测试中使用
+class Session {
+  async destroy() {  // 看起来像生产 API！
+    await this._workspaceManager?.destroyWorkspace(this.id);
+    // ... cleanup
+  }
+}
+
+// 在测试中
+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('detects duplicate server', () => {
+  // Mock 阻止了测试依赖的配置写入！
+  vi.mock('ToolCatalog', () => ({
+    discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
+  }));
+
+  await addServer(config);
+  await addServer(config);  // 应该抛出——但不会！
+});
+```
+
+**为何错误：**
+- 被 mock 的方法有测试依赖的副作用（写入配置）
+- 为了"安全"而过度 mock 破坏了实际行为
+- 测试因错误原因通过或神秘地失败
+
+**修复：**
+```typescript
+// ✅ 正确：在正确层级 mock
+test('detects duplicate server', () => {
+  // Mock 慢的部分，保留测试需要的行为
+  vi.mock('MCPServerManager'); // 只 mock 慢的服务器启动
+
+  await addServer(config);  // 配置已写入
+  await addServer(config);  // 检测到重复 ✓
+});
+```
+
+### 门控函数
+
+```
+在 mock 任何方法之前：
+  停止——先不要 mock
+
+  1. 问："真实方法有哪些副作用？"
+  2. 问："这个测试依赖这些副作用中的任何一个吗？"
+  3. 问："我完全理解这个测试需要什么吗？"
+
+  如果依赖副作用：
+    在更低层级 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。

package/skills/trace/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: trace
+description: 显示 agent 流程追踪时间线和摘要
+---
+
+# Agent 流程追踪
+
+[TRACE MODE ACTIVATED]
+
+## 目标
+
+显示流程追踪，展示本 session 中 hook、关键词、skill、agent 和工具的交互情况。
+
+## 说明
+
+1. **使用 `trace_timeline` MCP 工具**显示按时间顺序排列的事件时间线
+   - 不带参数调用以显示最新 session
+   - 使用 `filter` 参数聚焦特定事件类型（hooks、skills、agents、keywords、tools、modes）
+   - 使用 `last` 参数限制输出数量
+
+2. **使用 `trace_summary` MCP 工具**显示聚合统计
+   - Hook 触发次数
+   - 检测到的关键词
+   - 激活的 skill
+   - 模式转换
+   - 工具性能和瓶颈
+
+## 输出格式
+
+先展示时间线，再展示摘要。重点标注：
+- **模式转换**（执行模式如何变化）
+- **瓶颈**（慢速工具或 agent）
+- **流程模式**（关键词 -> skill -> agent 链）