sdd-full 4.2.0 → 4.3.0

package/skills/executing-plans/SKILL.md

@@ -1,175 +0,0 @@
----
-name: executing-plans
-description: 当你有一份书面实现计划需要在单独的会话中执行，并设有审查检查点时使用
----
-
-# 执行计划
-
-## 概述
-
-加载计划，批判性审查，执行所有任务，完成后报告。
-
-**开始时宣布：** "我正在使用 executing-plans 技能来实现此计划。"
-
-**注意：** 告诉你的人类伙伴，Superpowers 在有子代理支持时效果好得多。如果在支持子代理的平台上运行（如 Claude Code 或 Codex），其工作质量会显著提高。如果子代理可用，请使用 superpowers:subagent-driven-development 而非此技能。
-
-## 流程
-
-### 步骤 1：加载并审查计划
-
-1. 读取计划文件
-2. 批判性审查——识别计划中的任何问题或疑虑
-3. 如果有疑虑：在开始之前向你的人类伙伴提出
-4. 如果没有疑虑：创建 TodoWrite 并继续
-
-**审查时重点检查：**
-- 步骤之间是否有依赖遗漏？（A 依赖 B，但 B 排在 A 之后）
-- 验证条件是否明确？（"确认可用"不算，"运行 `npm test` 全部通过"才算）
-- 是否有隐含的环境假设？（Node 版本、数据库连接、API Key）
-
-**审查示例：**
-```
-计划文件：docs/plan.md
-任务清单：5 个任务
-
-审查发现：
-- 任务 3（添加数据库迁移）应在任务 2（编写数据模型）之后，顺序正确 ✓
-- 任务 4 的验证条件写的是"确认功能正常"→ 需澄清：具体跑什么测试？
-- 计划未提及 Python 版本要求 → 需确认
-
-向伙伴提出：
-"计划整体可执行。有两个问题：(1) 任务 4 的验证条件不够具体，建议改为
-'运行 pytest tests/test_api.py 全部通过'；(2) 需要确认 Python 版本要求。"
-```
-
-### 步骤 2：执行任务
-
-对于每个任务：
-
-1. **标记为进行中** — 更新 TodoWrite
-2. **理解目标** — 重读任务描述，明确完成标准
-3. **执行实现** — 严格按照计划步骤执行（计划已有小步骤）
-4. **运行验证** — 按要求运行测试或检查
-5. **提交变更** — 每完成一个任务提交一次，commit message 引用任务编号
-6. **标记为已完成** — 更新 TodoWrite
-
-**每个任务的节奏：**
-```
---- 任务 2/5：添加用户验证 ---
-[标记进行中]
-
-目标：为 /api/users 添加输入验证
-完成标准：所有验证测试通过，无效输入返回 400
-
-[实现]
-- 添加 validateUser() 中间件
-- 编写 3 个验证规则（email 格式、密码强度、用户名长度）
-
-[验证]
-$ npm test -- --grep "validation"
-  ✓ 拒绝无效 email (12ms)
-  ✓ 拒绝弱密码 (8ms)
-  ✓ 拒绝过长用户名 (5ms)
-  3 passing
-
-[提交]
-$ git add src/middleware/validate.js tests/validation.test.js
-$ git commit -m "feat: 添加用户输入验证（任务 2/5）"
-
-[标记完成]
---- 任务 2/5 完成 ---
-```
-
-**批量审查检查点：**
-- 每完成 3 个任务后，暂停回顾：整体方向还对吗？有没有偏离计划？
-- 如果发现前面的实现有问题，先修复再继续，不要带着问题往下走
-
-### 步骤 3：处理常见异常
-
-**测试失败：**
-1. 读错误信息，定位失败原因
-2. 区分：是实现 bug？还是测试本身有问题？还是计划描述有误？
-3. 实现 bug → 修复并重跑
-4. 测试有问题 → 修复测试，向伙伴说明
-5. 计划有误 → 停下来，向伙伴报告并建议修正
-
-**依赖缺失：**
-```
-任务 3 需要 Redis 连接，但计划中没有提及 Redis 配置。
-→ 停止执行
-→ 向伙伴报告："任务 3 需要 Redis，计划中未包含配置步骤。
-   建议：在任务 3 前插入 '配置 Redis 连接' 步骤。"
-```
-
-**指令不清：**
-- 不要猜测意图，不要"合理推断"
-- 列出你的理解和困惑，让伙伴澄清
-- 等待回复后再继续
-
-### 步骤 4：完成开发
-
-所有任务完成并验证后：
-- 宣布："我正在使用 finishing-a-development-branch 技能来完成此工作。"
-- **必需子技能：** 使用 superpowers:finishing-a-development-branch
-- 按照该技能的指引验证测试、展示选项、执行选择
-
-**完成报告模板：**
-```
-## 执行报告
-
-**计划：** docs/plan.md
-**分支：** feature/user-validation
-**任务：** 5/5 已完成
-
-### 完成的任务
-1. ✅ 初始化项目结构
-2. ✅ 添加用户验证
-3. ✅ 添加数据库迁移
-4. ✅ 实现 API 端点
-5. ✅ 添加集成测试
-
-### 验证结果
-- 单元测试：23/23 通过
-- 集成测试：8/8 通过
-- lint 检查：0 个警告
-
-### 偏离计划的地方
-- 任务 3：Redis 配置从 env 改为 config.yaml（经伙伴同意）
-
-### 下一步
-按 finishing-a-development-branch 技能处理合并/PR
-```
-
-## 何时停下来求助
-
-**在以下情况立即停止执行：**
-- 遇到阻塞（缺少依赖、测试失败、指令不清）
-- 计划有严重缺陷导致无法开始
-- 你不理解某条指令
-- 验证反复失败（同一测试失败 2 次以上）
-
-**不确定时就问，不要猜测。**
-
-## 何时回到之前的步骤
-
-**回到审查（步骤 1）当：**
-- 伙伴根据你的反馈更新了计划
-- 根本性的方案需要重新考虑
-
-**不要硬闯阻塞** — 停下来问。
-
-## 注意事项
-- 先批判性审查计划
-- 严格按照计划步骤执行
-- 不要跳过验证
-- 每个任务单独提交，commit message 引用任务编号
-- 计划要求时引用相应技能
-- 遇到阻塞时停下来，不要猜测
-- 未经用户明确同意，绝不在 main/master 分支上开始实现
-
-## 集成
-
-**必需的工作流技能：**
-- **superpowers:using-git-worktrees** - 必需：开始前建立隔离的工作空间
-- **superpowers:writing-plans** - 创建此技能要执行的计划
-- **superpowers:finishing-a-development-branch** - 所有任务完成后收尾开发

package/skills/finishing-a-development-branch/SKILL.md

@@ -1,200 +0,0 @@
----
-name: finishing-a-development-branch
-description: 当实现完成、所有测试通过、需要决定如何集成工作时使用——通过提供合并、PR 或清理等结构化选项来引导开发工作的收尾
----
-
-# 完成开发分支
-
-## 概述
-
-通过提供清晰的选项并执行所选工作流来引导开发工作的收尾。
-
-**核心原则：** 验证测试 → 展示选项 → 执行选择 → 清理。
-
-**开始时宣布：** "我正在使用 finishing-a-development-branch 技能来完成这项工作。"
-
-## 流程
-
-### 步骤 1：验证测试
-
-**在展示选项之前，验证测试通过：**
-
-```bash
-# 运行项目的测试套件
-npm test / cargo test / pytest / go test ./...
-```
-
-**如果测试失败：**
-```
-测试失败（<N> 个失败）。必须先修复才能继续：
-
-[显示失败信息]
-
-在测试通过之前无法进行合并/PR。
-```
-
-停止。不要继续到步骤 2。
-
-**如果测试通过：** 继续步骤 2。
-
-### 步骤 2：确定基础分支
-
-```bash
-# 尝试常见的基础分支
-git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
-```
-
-或者询问："这个分支是从 main 分出来的——对吗？"
-
-### 步骤 3：展示选项
-
-展示以下 4 个选项：
-
-```
-实现已完成。你想怎么做？
-
-1. 在本地合并回 <base-branch>
-2. 推送并创建 Pull Request
-3. 保持分支现状（我稍后处理）
-4. 丢弃这项工作
-
-选哪个？
-```
-
-**不要添加解释** - 保持选项简洁。
-
-### 步骤 4：执行选择
-
-#### 选项 1：本地合并
-
-```bash
-# 切换到基础分支
-git checkout <base-branch>
-
-# 拉取最新代码
-git pull
-
-# 合并功能分支
-git merge <feature-branch>
-
-# 在合并结果上验证测试
-<test command>
-
-# 如果测试通过
-git branch -d <feature-branch>
-```
-
-然后：清理工作树（步骤 5）
-
-#### 选项 2：推送并创建 PR
-
-```bash
-# 推送分支
-git push -u origin <feature-branch>
-
-# 创建 PR
-gh pr create --title "<title>" --body "$(cat <<'EOF'
-## 摘要
-<2-3 条变更要点>
-
-## 测试计划
-- [ ] <验证步骤>
-EOF
-)"
-```
-
-然后：清理工作树（步骤 5）
-
-#### 选项 3：保持现状
-
-报告："保留分支 <name>。工作树保留在 <path>。"
-
-**不要清理工作树。**
-
-#### 选项 4：丢弃
-
-**先确认：**
-```
-这将永久删除：
-- 分支 <name>
-- 所有提交：<commit-list>
-- 工作树 <path>
-
-输入 'discard' 确认。
-```
-
-等待精确的确认。
-
-确认后：
-```bash
-git checkout <base-branch>
-git branch -D <feature-branch>
-```
-
-然后：清理工作树（步骤 5）
-
-### 步骤 5：清理工作树
-
-**对于选项 1、2、4：**
-
-检查是否在工作树中：
-```bash
-git worktree list | grep $(git branch --show-current)
-```
-
-如果是：
-```bash
-git worktree remove <worktree-path>
-```
-
-**对于选项 3：** 保留工作树。
-
-## 快速参考
-
-| 选项 | 合并 | 推送 | 保留工作树 | 清理分支 |
-|------|------|------|-----------|---------|
-| 1. 本地合并 | ✓ | - | - | ✓ |
-| 2. 创建 PR | - | ✓ | ✓ | - |
-| 3. 保持现状 | - | - | ✓ | - |
-| 4. 丢弃 | - | - | - | ✓（强制） |
-
-## 常见错误
-
-**跳过测试验证**
-- **问题：** 合并损坏的代码、创建失败的 PR
-- **修复：** 在提供选项前始终验证测试
-
-**开放式问题**
-- **问题：** "接下来该做什么？" → 含糊不清
-- **修复：** 准确展示 4 个结构化选项
-
-**自动清理工作树**
-- **问题：** 在可能还需要工作树时就删除了（选项 2、3）
-- **修复：** 只在选项 1 和 4 时清理
-
-**丢弃时不确认**
-- **问题：** 意外删除工作成果
-- **修复：** 要求输入 "discard" 确认
-
-## 红线
-
-**绝不：**
-- 在测试失败时继续
-- 合并前不验证测试结果
-- 不确认就删除工作成果
-- 未经明确请求就强制推送
-
-**始终：**
-- 在提供选项前验证测试
-- 准确展示 4 个选项
-- 选项 4 要求输入确认
-- 只在选项 1 和 4 时清理工作树
-
-## 集成
-
-**被以下技能调用：**
-- **subagent-driven-development**（步骤 7）- 所有任务完成后
-- **executing-plans**（步骤 5）- 所有批次完成后
-
-**配合使用：**
-- **using-git-worktrees** - 清理由该技能创建的工作树

package/skills/mcp-builder/SKILL.md

@@ -1,255 +0,0 @@
----
-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，无硬编码密钥