feat: 批量新增字典数据

2026-07-14 15:58:00 +08:00
parent 11fe65a437
commit 88b6e21a8c
67 changed files with 11851 additions and 36 deletions
--- a/.cursor/skills/test-driven-development/SKILL.md
+++ b/.cursor/skills/test-driven-development/SKILL.md
@@ -0,0 +1,376 @@
+---
+name: test-driven-development
+description: 在实现任何功能或修复 bug 时使用，在编写实现代码之前
+version: "1.0.0"
+license: MIT
+metadata:
+  hermes:
+    tags: [testing, development]
+---
+
+# 测试驱动开发（TDD）
+
+## 概述
+
+先写测试。看它失败。写最少的代码让它通过。
+
+**核心原则：** 如果你没有看到测试失败，你就不知道它是否测试了正确的东西。
+
+**违反规则的字面意思就是违反规则的精神。**
+
+## 何时使用
+
+**始终使用：**
+- 新功能
+- Bug 修复
+- 重构
+- 行为变更
+
+**例外（需询问你的人类伙伴）：**
+- 一次性原型
+- 生成的代码
+- 配置文件
+
+想着"就这一次跳过 TDD"？停下来。那是在给自己找借口。
+
+## 铁律
+
+```
+没有失败的测试，就不写生产代码
+```
+
+先写了代码再写测试？删掉它。从头来过。
+
+**没有例外：**
+- 不要保留作为"参考"
+- 不要在写测试时"改编"它
+- 不要看它
+- 删除就是删除
+
+从测试出发，重新实现。句号。
+
+## 红-绿-重构
+
+```dot
+digraph tdd_cycle {
+    rankdir=LR;
+    red [label="红灯\n编写失败的测试", shape=box, style=filled, fillcolor="#ffcccc"];
+    verify_red [label="验证正确失败", 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('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）
+
+### 验证红灯 - 看它失败
+
+**必须执行。绝不跳过。**
+
+```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('validates email and domain and whitespace')` |
+| **清晰** | 名称描述行为 | `test('test1')` |
+| **展示意图** | 展示期望的 API | 掩盖了代码应该做什么 |
+
+## 为什么顺序很重要
+
+**"我先写完再补测试来验证"**
+
+后写的测试立即通过。立即通过什么也证明不了：
+- 可能测试了错误的东西
+- 可能测试的是实现而非行为
+- 可能遗漏了你忘掉的边界情况
+- 你从未看到它捕获 bug
+
+先写测试迫使你看到测试失败，证明它确实在测试某些东西。
+
+**"我已经手动测试了所有边界情况"**
+
+手动测试是临时的。你以为你测试了所有情况，但是：
+- 没有测试记录
+- 代码变更后无法重新运行
+- 在压力下容易遗忘
+- "我试过了能跑" 不等于 全面测试
+
+自动化测试是系统性的。它们每次以相同方式运行。
+
+**"删除 X 小时的工作太浪费了"**
+
+沉没成本谬误。时间已经花了。你现在的选择：
+- 删除并用 TDD 重写（再花 X 小时，高信心）
+- 保留并后补测试（30 分钟，低信心，可能有 bug）
+
+"浪费"的是保留你无法信任的代码。没有真正测试的可运行代码就是技术债。
+
+**"TDD 太教条了，务实意味着灵活变通"**
+
+TDD 就是务实的：
+- 在 commit 前发现 bug（比事后调试快）
+- 防止回归（测试立即发现破坏）
+- 记录行为（测试展示如何使用代码）
+- 支持重构（放心修改，测试捕获破坏）
+
+"务实的"捷径 = 在生产环境调试 = 更慢。
+
+**"后补测试也能达到相同目的——重要的是精神不是仪式"**
+
+不对。后补测试回答"这段代码做了什么？"先写测试回答"这段代码应该做什么？"
+
+后补测试受你实现的偏见影响。你测试的是你构建的东西，而非需求要求的。你验证的是你记得的边界情况，而非发现的。
+
+先写测试迫使你在实现前发现边界情况。后补测试验证的是你记住了所有情况（你没有）。
+
+30 分钟的后补测试 ≠ TDD。你得到了覆盖率，但失去了测试有效的证明。
+
+## 常见借口
+
+| 借口 | 现实 |
+|------|------|
+| "太简单了不用测" | 简单的代码也会出 bug。测试只需 30 秒。 |
+| "我之后补测试" | 立即通过的测试什么也证明不了。 |
+| "后补测试也能达到相同目的" | 后补测试 = "这做了什么？" 先写测试 = "这应该做什么？" |
+| "已经手动测试过了" | 临时测试 ≠ 系统测试。无记录，无法重现。 |
+| "删除 X 小时的工作太浪费" | 沉没成本谬误。保留未验证的代码就是技术债。 |
+| "留作参考，然后先写测试" | 你会去改编它。那就是后补测试。删除就是删除。 |
+| "需要先探索一下" | 可以。探索完了扔掉，从 TDD 开始。 |
+| "测试难写 = 设计不清楚" | 听测试的。难以测试 = 难以使用。 |
+| "TDD 会拖慢我" | TDD 比调试快。务实 = 先写测试。 |
+| "手动测试更快" | 手动测试无法证明边界情况。每次修改你都得重新测。 |
+| "现有代码没有测试" | 你在改进它。为现有代码补测试。 |
+
+## 危险信号 - 停下来，从头开始
+
+- 先写了代码再写测试
+- 实现完了才补测试
+- 测试立即通过
+- 无法解释测试为什么失败
+- "之后再补"测试
+- 说服自己"就这一次"
+- "我已经手动测试过了"
+- "后补测试也能达到相同目的"
+- "重要的是精神不是仪式"
+- "留作参考"或"改编现有代码"
+- "已经花了 X 小时了，删掉太浪费"
+- "TDD 太教条了，我是在务实"
+- "这次情况不同，因为……"
+
+**以上所有情况都意味着：删除代码。用 TDD 从头开始。**
+
+## 示例：Bug 修复
+
+**Bug：** 空邮箱被接受了
+
+**红灯**
+```typescript
+test('rejects empty email', 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。从头开始。
+
+## 遇到困难时
+
+| 问题 | 解决方案 |
+|------|----------|
+| 不知道怎么测试 | 写出你期望的 API。先写断言。问你的人类伙伴。 |
+| 测试太复杂 | 设计太复杂。简化接口。 |
+| 必须 mock 所有东西 | 代码耦合太紧。使用依赖注入。 |
+| 测试 setup 太庞大 | 提取辅助函数。还是复杂？简化设计。 |
+
+## 调试集成
+
+发现 bug？写一个重现 bug 的失败测试。按 TDD 循环走。测试既证明了修复有效，又防止了回归。
+
+绝不在没有测试的情况下修复 bug。
+
+## 测试反模式
+
+添加 mock 或测试工具时，阅读 @testing-anti-patterns.md 以避免常见陷阱：
+- 测试 mock 行为而非真实行为
+- 在生产类中添加仅测试用的方法
+- 在不理解依赖的情况下使用 mock
+
+## 最终规则
+
+```
+生产代码 → 测试存在且先失败
+否则 → 不是 TDD
+```
+
+没有你的人类伙伴的许可，没有例外。
--- a/.cursor/skills/test-driven-development/testing-anti-patterns.md
+++ b/.cursor/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();
+});
+
+// 或者如果必须 mock sidebar 来隔离：
+// 不要对 mock 做断言——测试 Page 在 sidebar 存在时的行为
+```
+
+### 门控函数
+
+```
+在对任何 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('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 完全匹配真实响应的结构
+
+  关键：
+    如果你在创建 mock，你必须理解完整的结构
+    部分 mock 在代码依赖遗漏字段时会静默失败
+
+  不确定时：包含所有文档记录的字段
+```
+
+## 反模式 5：集成测试作为事后补充
+
+**违规做法：**
+```
+✅ 实现完成
+❌ 没写测试
+"准备好测试了"
+```
+
+**为什么这是错误的：**
+- 测试是实现的一部分，不是可选的后续
+- TDD 本可以防止这种情况
+- 没有测试就不能声称完成
+
+**正确做法：**
+```
+TDD 循环：
+1. 编写失败的测试
+2. 实现使其通过
+3. 重构
+4. 然后才声称完成
+```
+
+## 当 Mock 变得过于复杂时
+
+**警告信号：**
+- Mock 的 setup 比测试逻辑还长
+- 为了让测试通过而 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` test ID
+- 方法仅在测试文件中被调用
+- Mock setup 占测试的 >50%
+- 移除 mock 测试就失败
+- 无法解释为什么需要 mock
+- "保险起见" mock 掉
+
+## 底线
+
+**Mock 是隔离的工具，不是被测试的对象。**
+
+如果 TDD 揭示你在测试 mock 行为，你已经走偏了。
+
+修复方法：测试真实行为，或质疑为什么要 mock。