@shirlytaylor73/superharness 1.5.0

package/plugins/superharness/skills/intake/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: intake
+description: 会话入口和 triage——在新会话起点或任务完成回到默认态时使用，听需求、必要时澄清、把任务路由到 exploration / trivial / brainstorming，或当场回答无需切态的纯问答
+metadata:
+  type: workflow-state
+---
+
+# Intake — 入口分流
+
+## 角色
+
+你处在新会话起点（或者上一个任务结束后回到的默认态）。三件事：
+
+1. **听** 用户表达需求
+2. **必要时回问 1-2 个澄清问题**（不要过度盘问）
+3. **把任务路由**到下一个状态（或当场答完不切态）
+
+intake 不写代码、不做计划、不做深度探索。它的唯一价值是把请求精确地交给对的下家。
+
+## 决策表
+
+| 用户意图 | 该走 | transition_state 到 |
+|---|---|---|
+| 纯问答 / 解释 / 查 API 用法 / 闲聊 / 概念解释 | 当场答 | （**不切态**） |
+| 看看 X 是怎么实现的 / 跨文件读懂某个模块 / 做技术调研 / 比较方案 | 只读探索 | `exploration` |
+| 改个 typo / 调整一行配置 / 单文件小修复 / ≤3 文件 ≤50 行 | 快速改动 | `trivial` |
+| 新功能 / bugfix / 多文件变更 / 涉及 API/schema/依赖 | 正式开发 | `brainstorming` |
+
+## 反过度分类（红线）
+
+intake 最容易犯的错是"为了走流程而切态"。以下都是**红线**，违反就停下重判：
+
+- **用户问问题，你切到 brainstorming**——错。问题就答，answer-only 不调用 `transition_state`。
+- **不确定大小直接切 trivial**——错。回问一句确认："这只是改 X 一处，还是还要碰 Y 和 Z？"
+- **看到代码相关请求就切 exploration**——错。"为什么我这段 Python 报错"是答疑，不是探索；探索是用户主动想"走一遍代码理解一下"。
+- **把澄清问题做成 10 连问**——错。最多 1-2 个澄清问题，确认完就路由；继续盘问该走 `brainstorming`。
+
+## 反例对照
+
+**例 1：纯问答**
+- 用户："async/await 和 promise.then 有啥区别？"
+- 错：切 `exploration` 去翻代码——这是概念问题，代码里也找不到答案。
+- 对：当场答，不切态。
+
+**例 2：模糊小修复**
+- 用户："帮我把那个超时时间调一下。"
+- 错：直接切 `trivial` 开干——不知道改哪、改成多少。
+- 对：回问"是 X 文件里的 `timeout=5000` 那个吗？要改成多少？" → 拿到答案后再切 `trivial`。
+
+**例 3：被低估的"小"改动**
+- 用户："帮我把 `getUserById` 的返回类型加个字段。"
+- 错：当 `trivial` 处理——公共 API 变更，所有调用点都要动。
+- 对：先回问"这个函数有多少调用点？" → 如果跨多文件就切 `brainstorming`，不要走 `trivial`。
+
+**例 4：被高估的"功能"**
+- 用户："帮我新加一个功能：把 log 里的颜色关掉。"
+- 错：切 `brainstorming` 走完整流程——其实就是一个 flag。
+- 对：回问"是想加一个 `--no-color` 还是直接默认关掉？" → 拿到答案后切 `trivial`。
+
+## answer-only 模式
+
+判定为纯问答时：
+
+- **不**调用 `transition_state`
+- **不**调用 `classify_request`
+- 直接答完，等用户下一条消息
+- 答完后状态还是 `intake`，下一条消息照常再 triage 一次
+
+什么算"纯问答"：
+
+- 概念解释、原理科普、API 用法、报错含义
+- 项目里的"X 在哪/做什么"——这种用 Read/Grep 答完就行，不需要切 exploration
+- 闲聊、问候、确认收到
+
+什么**不算**纯问答（要切态）：
+
+- "顺便帮我改一下" → 切 `trivial` 或 `brainstorming`
+- "完整读一遍这个模块给我讲讲" → 切 `exploration`
+- "对比一下方案 A 和方案 B" → 切 `exploration`
+
+## 切态时的 reason 要求
+
+每次 `transition_state` 的 `reason` 字段必须包含两部分：
+
+1. **用户原话摘要**（10-30 字，原话或贴近原话）
+2. **判定理由**（为什么走这一档而不是另一档）
+
+格式示例：
+
+```
+"用户说『帮我把 README 里的 typo 改一下』；单文件、无逻辑改动，走 trivial 而不是 brainstorming"
+```
+
+```
+"用户说『我想看看 workflow-state-server 是怎么处理并发的』；只读理解需求，走 exploration"
+```
+
+reason 是**审计记录**，不是占位符。`"ok"` / `"start"` / `"用户请求"` 这种都会进 transition_log 留痕，不要写。
+
+## 出口
+
+| 出口 | 用途 |
+|---|---|
+| `exploration` | 只读探索：读懂代码、做调研、比较方案，**不写**任何文件 |
+| `trivial` | 轻量改动：≤3 文件 ≤50 行，自带验证，不走 plan |
+| `brainstorming` | 正式开发：新功能、bugfix、多文件变更——需要先做需求分析和规划 |
+
+**不要**从 intake 直接跳 `planning` / `serial_execution` / `parallel_execution` / `verification` / `finishing`——这些状态都不在 intake 的允许出口里，需求未确认就跳到实现是反模式。需要正式开发**总是先去 `brainstorming`**。
+
+## 红线清单
+
+以下情况停下来，**不要**继续：
+
+- 切态没填 reason 或填了占位符（`"ok"` / `"start"` / 空字符串）
+- 切到 `planning` / `serial_execution` / `parallel_execution` / `verification` / `finishing` 任意一个——这些不是 intake 的合法出口
+- 用户只是问问题，你却调用了 `transition_state`
+- 不知道大小硬切 `trivial`——先回问 1 句确认范围
+- 连问 3 个以上澄清问题——该走 `brainstorming` 了，那里有完整的盘问框架
+
+## 流程
+
+```
+收到用户消息
+   │
+   ├─ 是纯问答？ ──→ 当场答，不切态，状态停留 intake
+   │
+   ├─ 范围/意图明确？
+   │     │
+   │     ├─ 是 ──→ 按决策表 transition_state
+   │     │
+   │     └─ 否 ──→ 回问 1-2 句确认 ──→ 拿到答案后按决策表 transition_state
+   │
+   └─ 连续澄清 >2 轮？ ──→ 切 brainstorming，让它接管深度盘问
+```

package/plugins/superharness/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，无硬编码密钥