sdd-full 3.2.0 → 4.2.0

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

@@ -0,0 +1,200 @@
+---
+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

@@ -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

@@ -1,56 +1,49 @@
-name: BDD风格验收标准SDD
-description: BDD验收句式、场景写法、准入/准出标准
-author: 
-version: 1.0.0
-trigger:
-  - BDD验收标准
-  - BDD测试
-  - 验收规范
-tags:
-  - BDD
-  - 测试
-  - 验收标准
-  - SDD模板
+# bdd-acceptance - BDD风格验收标准
 
-【claude code调用标识：BDD风格验收标准SDD】【trae调用标识：BDD风格验收标准SDD+验收规范】【流程场景：1.完整3阶段SDD流程、3.小型功能迭代、4.Bug处理】
+## 功能说明
 
-## 功能描述
+所有需求配套BDD验收句式、场景写法、准入/准出标准的专用技能。
 
-本技能提供BDD风格验收标准模板，包含Given-When-Then句式、场景写法和准入/准出标准，帮助团队建立规范的验收流程。
+## 触发词
 
-## 调用方式
+`BDD`、`验收标准`、`行为驱动`、`测试用例`
+
+## 参数说明
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| requirement_name | string | 是 | 需求名称 |
+| module | string | 否 | 所属模块 |
+
+## BDD句式结构
+
+### Given-When-Then 格式
 
-### Claude Code调用
 ```
-调用 BDD风格验收标准SDD 需求名称=用户登录 优先级=P0
+场景: [场景名称]
+  Given [前置条件]
+  And [额外条件]
+  When [用户操作]
+  And [后续操作]
+  Then [预期结果]
+  And [额外验证]
 ```
 
-### Trae调用
+### 验收标准
+
+| 阶段 | 准入条件 | 准出条件 |
+|------|----------|----------|
+| 开发 | 需求明确、设计完成 | 代码提交、单元测试通过 |
+| 测试 | 开发完成、代码审查通过 | 功能测试通过、无阻塞Bug |
+| 上线 | 测试通过、文档齐全 | 灰度发布成功、监控正常 |
+
+## 使用示例
+
 ```
-trae调用 BDD风格验收标准SDD 需求名称=用户登录 优先级=P0 流程场景=小型功能迭代
+trae调用 BDD风格验收标准SDD 需求名称=用户登录
+trae调用 BDD风格验收标准SDD 需求名称=订单支付 模块=支付系统
 ```
 
-## 参数说明
+## 版本
 
-| 参数名 | 类型 | 必填 | 说明 |
-|--------|------|------|------|
-| 需求名称 | string | 是 | 需求名称 |
-| Jira编号 | string | 否 | 工单编号 |
-| 优先级 | string | 否 | P0/P1/P2 |
-| 提出人 | string | 否 | 需求提出人 |
-
-## 输出内容
-
-1. 需求概述（描述、来源、优先级）
-2. 场景定义（正常场景、异常场景、边界场景）
-3. 验收句式（Given-When-Then格式）
-4. 准入标准（需求澄清、设计稿、依赖确认）
-5. 准出标准（功能验证、测试覆盖、文档完整）
-6. 测试用例（单元、集成、E2E测试）
-
-## 适用场景
-
-- 需求验收
-- 测试用例设计
-- 质量把关
-- Bug修复验证
+v4.1.0