sdd-full 4.0.0 → 4.2.0

package/skills/mcp-builder/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: mcp-builder
+description: MCP 服务器构建方法论 — 系统化构建生产级 MCP 工具，让 AI 助手连接外部能力
+---
+
+# MCP 服务器构建
+
+系统化设计、实现、测试和部署 Model Context Protocol 服务器的方法论。
+
+## 1. 协议核心概念
+
+MCP 定义三种原语：
+
+- **Tools（工具）**：AI 助手主动调用的函数，有副作用。如搜索、创建、删除操作。
+- **Resources（资源）**：AI 助手只读访问的数据源，用 URI 标识。如 `users://{id}/profile`。
+- **Prompts（提示词模板）**：预定义交互模板，引导用户触发工作流。
+
+**选择原则：** 执行操作 → Tool | 读取数据 → Resource | 引导交互 → Prompt
+
+## 2. 项目结构规范
+
+### TypeScript
+```
+my-mcp-server/
+├── src/
+│   ├── index.ts          # 入口，注册 tools/resources
+│   ├── tools/             # 按功能拆分
+│   ├── resources/
+│   └── lib/               # 客户端封装、校验逻辑
+├── tests/
+├── package.json
+└── tsconfig.json
+```
+
+关键依赖：`@modelcontextprotocol/sdk` + `zod`
+
+### Python
+```
+my-mcp-server/
+├── src/my_mcp_server/
+│   ├── server.py
+│   ├── tools/
+│   └── lib/
+├── tests/
+└── pyproject.toml
+```
+
+关键依赖：`mcp` + `pydantic`
+
+## 3. Tool 设计原则
+
+### 命名
+- `snake_case` 格式，动词开头：`search_users`、`create_issue`、`delete_file`
+- 名称自解释，AI 助手靠名称选工具，模糊命名导致误调用
+
+### 参数
+- 每个参数有类型约束和 `.describe()` 描述
+- 可选参数给默认值，减少 AI 决策负担
+- 用枚举代替布尔开关
+
+```typescript
+server.tool("search_issues", {
+  query: z.string().describe("搜索关键词"),
+  status: z.enum(["open", "closed", "all"]).default("open").describe("状态筛选"),
+  limit: z.number().min(1).max(100).default(20).describe("返回上限"),
+}, async ({ query, status, limit }) => { /* ... */ });
+```
+
+### 描述
+说明**用途 + 返回内容 + 限制**，这是 AI 选择工具的关键依据：
+
+```typescript
+server.tool("search_users",
+  "根据姓名或邮箱搜索用户。返回 ID、姓名、邮箱列表。模糊匹配，最多 50 条。",
+  schema, handler);
+```
+
+### 输出
+- 结构化数据 → JSON，人类可读内容 → Markdown
+- 始终用 `content: [{ type: "text", text: "..." }]` 格式返回
+
+## 4. 输入验证和错误处理
+
+用 Zod/Pydantic 做 Schema 级校验，业务级校验放 handler 开头：
+
+```typescript
+server.tool("get_user", { id: z.string() }, async ({ id }) => {
+  try {
+    const user = await db.getUser(id);
+    if (!user) {
+      return {
+        content: [{ type: "text", text: `用户 ${id} 不存在，请检查 ID。` }],
+        isError: true,
+      };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(user, null, 2) }] };
+  } catch (err) {
+    return {
+      content: [{ type: "text", text: `查询失败：${err.message}` }],
+      isError: true,
+    };
+  }
+});
+```
+
+**错误处理四原则：**
+1. 永远不让服务器崩溃 — try/catch 包裹所有外部调用
+2. 返回可操作的错误信息 — 告诉 AI 问题是什么、能做什么
+3. 使用 `isError: true` — 让 AI 知道调用失败
+4. 区分错误类型 — 参数错误、权限不足、资源不存在、服务不可用
+
+## 5. 资源管理和生命周期
+
+```typescript
+// 资源注册
+server.resource("user-profile", "users://{userId}/profile", async (uri) => {
+  const profile = await db.getProfile(extractId(uri));
+  return { contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(profile) }] };
+});
+
+// 生命周期：先初始化 → 再 connect → 监听关闭信号
+const db = await Database.connect(config.dbUrl);
+await server.connect(new StdioServerTransport());
+process.on("SIGINT", async () => { await db.disconnect(); await server.close(); process.exit(0); });
+```
+
+关键点：使用连接池、所有外部调用设超时、优雅关闭清理资源。
+
+## 6. 测试策略
+
+### 单元测试 — 业务逻辑与 MCP 注册分离
+```typescript
+// tools/search.ts 导出纯函数
+export async function searchUsers(query: string, limit: number) { /* ... */ }
+
+// search.test.ts 独立测试
+test("返回匹配结果", async () => {
+  const results = await searchUsers("alice", 10);
+  expect(results[0].name).toContain("Alice");
+});
+```
+
+### 集成测试 — 用 SDK Client 做端到端验证
+```typescript
+const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+await server.connect(serverTransport);
+const client = new Client({ name: "test", version: "1.0.0" });
+await client.connect(clientTransport);
+const result = await client.callTool("search_users", { query: "test" });
+expect(result.isError).toBeFalsy();
+```
+
+### MCP Inspector — 交互式调试
+```bash
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+在浏览器中查看所有 tools/resources，手动调用并查看结果。
+
+**测试要点：** 每个 Tool 覆盖正常 + 异常路径、边界值、外部服务失败模拟。
+
+## 7. 安全考虑
+
+**权限控制：**
+- 最小权限原则，读写 Tool 分离
+- 危险操作要求确认参数（如 `confirm: true`）
+
+**输入安全：**
+- SQL 注入 → 参数化查询，绝不拼接
+- 路径遍历 → 校验路径，禁止 `../`
+- 命令注入 → 用 `execFile` 而非 `exec`
+
+**敏感数据：**
+- 密钥通过环境变量传入，不硬编码
+- 日志不打印完整敏感信息
+- 返回数据做脱敏处理
+
+**沙箱：** 文件操作限制目录、网络请求限制白名单、设置资源配额。
+
+## 8. 部署和分发
+
+### npm 发布
+```json
+{ "bin": { "mcp-server-myservice": "dist/index.js" }, "files": ["dist"] }
+```
+
+用户配置：
+```json
+{ "mcpServers": { "myservice": { "command": "npx", "args": ["@yourorg/mcp-server-myservice"], "env": { "API_KEY": "xxx" } } } }
+```
+
+### pip 发布
+```toml
+[project.scripts]
+mcp-server-myservice = "my_mcp_server.server:main"
+```
+
+### Docker — 适用于复杂依赖或隔离场景
+```dockerfile
+FROM node:20-slim
+WORKDIR /app
+COPY package*.json ./ && RUN npm ci --production
+COPY dist ./dist
+ENTRYPOINT ["node", "dist/index.js"]
+```
+
+## 9. 调试技巧
+
+**关键：MCP 用 stdio 通信，不能用 `console.log`，会破坏协议流。**
+
+```typescript
+// 错误
+console.log("debug");
+// 正确
+console.error("[DEBUG]", info);
+// 更好
+server.sendLoggingMessage({ level: "info", data: "处理中" });
+```
+
+**常见问题：**
+
+| 症状 | 原因 | 解决 |
+|------|------|------|
+| 启动无响应 | transport 未连接 | 检查 `server.connect()` |
+| Tool 不出现 | 注册在 connect 之后 | 先注册再 connect |
+| AI 不调用 Tool | 描述不清晰 | 改善名称和描述 |
+| 参数总错 | Schema 不明确 | 添加 `.describe()` |
+| 调用超时 | 外部服务慢 | 加超时和缓存 |
+
+**调试流程：** Inspector 验证基本功能 → 手动调用确认输入输出 → 连接真实 AI 客户端观察调用模式 → 根据实际行为调整设计。
+
+## 10. 构建检查清单
+
+### 设计
+- [ ] 明确 Tools vs Resources vs Prompts 分工
+- [ ] Tool 命名 `动词_名词`，描述说明用途和返回内容
+- [ ] 参数简洁，可选参数有合理默认值
+
+### 实现
+- [ ] 输入用 Zod/Pydantic 校验
+- [ ] 外部调用有 try/catch 和超时
+- [ ] 错误返回 `isError: true` 并附可操作信息
+- [ ] 不用 `console.log`（用 stderr 或 SDK 日志）
+- [ ] 敏感数据走环境变量
+
+### 测试
+- [ ] 核心逻辑有单元测试
+- [ ] 有集成测试验证 MCP 协议交互
+- [ ] 用 MCP Inspector 手动验证过
+- [ ] 用真实 AI 客户端测试过
+
+### 部署
+- [ ] README 含安装和配置说明
+- [ ] 提供客户端配置 JSON 示例
+- [ ] 遵循 semver，无硬编码密钥

package/skills/quality-assurance/bdd-acceptance/SKILL.md

@@ -0,0 +1,49 @@
+# bdd-acceptance - BDD风格验收标准
+
+## 功能说明
+
+所有需求配套BDD验收句式、场景写法、准入/准出标准的专用技能。
+
+## 触发词
+
+`BDD`、`验收标准`、`行为驱动`、`测试用例`
+
+## 参数说明
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| requirement_name | string | 是 | 需求名称 |
+| module | string | 否 | 所属模块 |
+
+## BDD句式结构
+
+### Given-When-Then 格式
+
+```
+场景: [场景名称]
+  Given [前置条件]
+  And [额外条件]
+  When [用户操作]
+  And [后续操作]
+  Then [预期结果]
+  And [额外验证]
+```
+
+### 验收标准
+
+| 阶段 | 准入条件 | 准出条件 |
+|------|----------|----------|
+| 开发 | 需求明确、设计完成 | 代码提交、单元测试通过 |
+| 测试 | 开发完成、代码审查通过 | 功能测试通过、无阻塞Bug |
+| 上线 | 测试通过、文档齐全 | 灰度发布成功、监控正常 |
+
+## 使用示例
+
+```
+trae调用 BDD风格验收标准SDD 需求名称=用户登录
+trae调用 BDD风格验收标准SDD 需求名称=订单支付 模块=支付系统
+```
+
+## 版本
+
+v4.1.0

package/skills/receiving-code-review/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: receiving-code-review
+description: 收到代码审查反馈后、实施建议之前使用，尤其当反馈不明确或技术上有疑问时——需要技术严谨性和验证，而非敷衍附和或盲目执行
+---
+
+# 接收代码审查
+
+## 概述
+
+代码审查需要的是技术评估，不是情绪表演。
+
+**核心原则：** 先验证再实施。先提问再假设。技术正确性优先于社交舒适度。
+
+## 响应模式
+
+```
+收到代码审查反馈时：
+
+1. 阅读：完整阅读反馈，不急于反应
+2. 理解：用自己的话复述需求（或提问）
+3. 验证：对照代码库的实际情况检查
+4. 评估：对这个代码库来说技术上合理吗？
+5. 回应：技术性确认或有理有据的反驳
+6. 实施：一次一项，逐个测试
+```
+
+## 禁止的回应
+
+**绝不要说：**
+- "你说得太对了！"（明确违反 CLAUDE.md 规定）
+- "好观点！"/"反馈很棒！"（敷衍表演）
+- "让我立刻实施"（在验证之前）
+
+**应该这样做：**
+- 复述技术需求
+- 提出澄清性问题
+- 如果审查意见有误，用技术理由反驳
+- 直接动手做（行动胜于言辞）
+
+## 处理不明确的反馈
+
+```
+如果有任何一项不明确：
+  停下来——先不要实施任何内容
+  就不明确的项目提出澄清
+
+为什么：各项之间可能有关联。部分理解 = 错误实施。
+```
+
+**示例：**
+```
+搭档："修复第 1-6 项"
+你理解 1、2、3、6。对 4、5 不确定。
+
+❌ 错误做法：先实施 1、2、3、6，稍后再问 4、5
+✅ 正确做法："第 1、2、3、6 项我理解了。第 4 和第 5 项需要澄清后再动手。"
+```
+
+## 按来源区别处理
+
+### 来自搭档的反馈
+- **可信赖** —— 理解后直接实施
+- **仍然要问** 如果范围不明确
+- **不要敷衍附和**
+- **直接行动** 或给出技术性确认
+
+### 来自外部审查者的反馈
+```
+实施之前：
+  1. 检查：对这个代码库来说技术上正确吗？
+  2. 检查：是否会破坏现有功能？
+  3. 检查：当前实现这样写是否有原因？
+  4. 检查：在所有平台/版本上都适用吗？
+  5. 检查：审查者了解完整上下文吗？
+
+如果建议似乎有误：
+  用技术理由反驳
+
+如果无法轻易验证：
+  说明情况："没有 [X] 我无法验证这一点。我应该 [调查/提问/先做]？"
+
+如果与搭档之前的决策冲突：
+  先停下来和搭档讨论
+```
+
+**搭档的原则：** "对外部反馈要持怀疑态度，但要仔细核实"
+
+## YAGNI 检查——针对"专业化"功能建议
+
+```
+如果审查者建议"正规地实现"：
+  在代码库中 grep 实际使用情况
+
+  如果没人用："这个接口没有被调用。删掉它（YAGNI）？"
+  如果有人用：那就正规实现
+```
+
+**搭档的原则：** "你和审查者都对我负责。如果我们不需要这个功能，就不要加。"
+
+## 实施顺序
+
+```
+对于包含多项的反馈：
+  1. 先澄清所有不明确的项
+  2. 然后按以下顺序实施：
+     - 阻塞性问题（崩溃、安全）
+     - 简单修复（拼写、导入）
+     - 复杂修复（重构、逻辑）
+  3. 逐个测试每项修复
+  4. 验证没有回归
+```
+
+## 何时反驳
+
+在以下情况反驳：
+- 建议会破坏现有功能
+- 审查者缺少完整上下文
+- 违反 YAGNI（功能没人用）
+- 对当前技术栈来说技术上不正确
+- 存在遗留/兼容性原因
+- 与搭档的架构决策冲突
+
+**如何反驳：**
+- 用技术理由，不要带防御情绪
+- 提出具体问题
+- 引用可正常工作的测试/代码
+- 如果涉及架构问题，让搭档参与
+
+**如果觉得不方便当众反驳，暗号是：** "Strange things are afoot at the Circle K"
+
+## 确认正确的反馈
+
+当反馈确实正确时：
+```
+✅ "已修复。[简要说明改了什么]"
+✅ "发现得好——[具体问题]。已在 [位置] 修复。"
+✅ [直接修复并在代码中体现]
+
+❌ "你说得太对了！"
+❌ "好观点！"
+❌ "感谢你发现了这个！"
+❌ "感谢你 [任何内容]"
+❌ 任何感谢的表达
+```
+
+**为什么不用感谢：** 行动说明一切。直接修复。代码本身就能表明你收到了反馈。
+
+**如果你发现自己要写"感谢"：** 删掉它。直接说明修复内容。
+
+## 优雅地纠正自己的反驳
+
+如果你反驳了但事后发现自己错了：
+```
+✅ "你是对的——我检查了 [X]，确实 [Y]。正在实施。"
+✅ "验证后确认你是对的。我最初的理解有误，因为 [原因]。正在修复。"
+
+❌ 长篇道歉
+❌ 为自己的反驳辩护
+❌ 过度解释
+```
+
+如实陈述纠正，然后继续。
+
+## 常见错误
+
+| 错误 | 修正 |
+|------|------|
+| 敷衍附和 | 复述需求或直接行动 |
+| 盲目实施 | 先对照代码库验证 |
+| 批量实施不测试 | 一次一项，逐个测试 |
+| 假设审查者一定对 | 检查是否会破坏现有功能 |
+| 回避反驳 | 技术正确性 > 社交舒适度 |
+| 部分理解就开始实施 | 先澄清所有项 |
+| 无法验证却继续推进 | 说明限制，请求指导 |
+
+## 真实案例
+
+**敷衍附和（反面例子）：**
+```
+审查者："删除遗留代码"
+❌ "你说得太对了！让我删掉它……"
+```
+
+**技术验证（正面例子）：**
+```
+审查者："删除遗留代码"
+✅ "查了一下……构建目标是 10.15+，这个 API 需要 13+。向后兼容需要保留遗留代码。当前实现有错误的 bundle ID——修复它还是放弃 pre-13 支持？"
+```
+
+**YAGNI（正面例子）：**
+```
+审查者："实现完善的指标追踪，包括数据库、日期过滤、CSV 导出"
+✅ "在代码库中 grep 了一下——没有任何地方调用这个接口。删掉它（YAGNI）？还是有我遗漏的调用？"
+```
+
+**不明确的项（正面例子）：**
+```
+搭档："修复第 1-6 项"
+你理解 1、2、3、6。对 4、5 不确定。
+✅ "第 1、2、3、6 项我理解了。第 4 和第 5 项需要澄清后再动手。"
+```
+
+## GitHub 评论回复
+
+在 GitHub 上回复行内审查评论时，在评论线程中回复（`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`），不要发顶层 PR 评论。
+
+## 底线
+
+**外部反馈 = 待评估的建议，不是必须执行的命令。**
+
+验证。质疑。然后实施。
+
+不要敷衍附和。始终保持技术严谨。

package/skills/requesting-code-review/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: requesting-code-review
+description: 完成任务、实现重要功能或合并前使用，用于验证工作成果是否符合要求
+---
+
+# 请求代码审查
+
+派遣 superpowers:code-reviewer 子代理来在问题扩散之前发现它们。审查者获得的是精心组织的评估上下文——绝不是你的会话历史。这样可以让审查者专注于工作成果而非你的思考过程，同时保留你自己的上下文以便继续工作。
+
+**核心原则：** 早审查，勤审查。
+
+## 何时请求审查
+
+**必须审查：**
+- 子代理驱动开发中每个任务完成后
+- 完成重要功能后
+- 合并到 main 之前
+
+**可选但有价值：**
+- 卡住时（换个视角）
+- 重构之前（建立基线）
+- 修复复杂 bug 之后
+
+## 如何请求
+
+**1. 获取 git SHA：**
+```bash
+BASE_SHA=$(git rev-parse HEAD~1)  # 或 origin/main
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+**2. 派遣 code-reviewer 子代理：**
+
+使用 Task 工具，指定 superpowers:code-reviewer 类型，填写 `code-reviewer.md` 中的模板
+
+**占位符说明：**
+- `{WHAT_WAS_IMPLEMENTED}` - 你刚完成的内容
+- `{PLAN_OR_REQUIREMENTS}` - 预期功能
+- `{BASE_SHA}` - 起始提交
+- `{HEAD_SHA}` - 结束提交
+- `{DESCRIPTION}` - 简要说明
+
+**3. 处理反馈：**
+- Critical 问题立即修复
+- Important 问题在继续之前修复
+- Minor 问题记录下来稍后处理
+- 如果审查者有误，用技术理由反驳
+
+## 示例
+
+```
+[刚完成任务 2：添加验证功能]
+
+你：让我在继续之前请求代码审查。
+
+BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
+HEAD_SHA=$(git rev-parse HEAD)
+
+[派遣 superpowers:code-reviewer 子代理]
+  WHAT_WAS_IMPLEMENTED: 会话索引的验证和修复功能
+  PLAN_OR_REQUIREMENTS: docs/superpowers/plans/deployment-plan.md 中的任务 2
+  BASE_SHA: a7981ec
+  HEAD_SHA: 3df7661
+  DESCRIPTION: 添加了 verifyIndex() 和 repairIndex()，支持 4 种问题类型
+
+[子代理返回]:
+  优点：架构清晰，测试真实
+  问题：
+    Important：缺少进度指示器
+    Minor：报告间隔使用了魔法数字 (100)
+  评估：可以继续
+
+你：[修复进度指示器]
+[继续任务 3]
+```
+
+## 与工作流的集成
+
+**子代理驱动开发：**
+- 每个任务完成后审查
+- 在问题叠加之前发现它们
+- 修复后再进入下一个任务
+
+**执行计划：**
+- 每批（3 个任务）后审查
+- 获取反馈，修复，继续
+
+**临时开发：**
+- 合并前审查
+- 卡住时审查
+
+## 红线
+
+**绝不要：**
+- 因为"很简单"就跳过审查
+- 忽略 Critical 问题
+- 带着未修复的 Important 问题继续推进
+- 对合理的技术反馈进行争辩
+
+**如果审查者有误：**
+- 用技术理由反驳
+- 展示证明其可行的代码/测试
+- 要求澄清
+
+参见模板：requesting-code-review/code-reviewer.md