@liangjie559567/ultrapower 5.0.4

package/skills/hud/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: hud
+description: 配置 HUD 显示选项（布局、预设、显示元素）
+role: config-writer  # 仅文档说明 - 此 skill 写入 ~/.claude/ 路径
+scope: ~/.claude/**  # 仅文档说明 - 允许的写入范围
+---
+
+# HUD Skill
+
+配置 OMC HUD（Heads-Up Display）状态栏。
+
+注意：本指南中所有 `~/.claude/...` 路径在设置了 `CLAUDE_CONFIG_DIR` 环境变量时均遵循该变量。
+
+## 快速命令
+
+| 命令 | 描述 |
+|---------|-------------|
+| `/ultrapower:hud` | 显示当前 HUD 状态（如需则自动设置） |
+| `/ultrapower:hud setup` | 安装/修复 HUD 状态栏 |
+| `/ultrapower:hud minimal` | 切换到最小显示 |
+| `/ultrapower:hud focused` | 切换到专注显示（默认） |
+| `/ultrapower:hud full` | 切换到完整显示 |
+| `/ultrapower:hud status` | 显示详细 HUD 状态 |
+
+## 自动设置
+
+运行 `/ultrapower:hud` 或 `/ultrapower:hud setup` 时，系统将自动：
+1. 检查 `~/.claude/hud/omc-hud.mjs` 是否存在
+2. 检查 `~/.claude/settings.json` 中是否配置了 `statusLine`
+3. 若缺失，创建 HUD 包装脚本并配置设置
+4. 报告状态，若有变更则提示重启 Claude Code
+
+**重要**：若参数为 `setup` 或 HUD 脚本不存在于 `~/.claude/hud/omc-hud.mjs`，必须按以下说明直接创建 HUD 文件。
+
+### 设置说明（运行以下命令）
+
+**步骤 1：** 检查是否需要设置：
+```bash
+node -e "const p=require('path'),f=require('fs'),d=process.env.CLAUDE_CONFIG_DIR||p.join(require('os').homedir(),'.claude');console.log(f.existsSync(p.join(d,'hud','omc-hud.mjs'))?'EXISTS':'MISSING')"
+```
+
+**步骤 2：** 验证插件已安装：
+```bash
+node -e "const p=require('path'),f=require('fs'),d=process.env.CLAUDE_CONFIG_DIR||p.join(require('os').homedir(),'.claude'),b=p.join(d,'plugins','cache','omc','ultrapower');try{const v=f.readdirSync(b).filter(x=>/^\d/.test(x)).sort((a,c)=>a.localeCompare(c,void 0,{numeric:true}));if(v.length===0){console.log('Plugin not installed - run: /plugin install ultrapower');process.exit()}const l=v[v.length-1],h=p.join(b,l,'dist','hud','index.js');console.log('Version:',l);console.log(f.existsSync(h)?'READY':'NOT_FOUND - try reinstalling: /plugin install ultrapower')}catch{console.log('Plugin not installed - run: /plugin install ultrapower')}"
+```
+
+**步骤 3：** 若 omc-hud.mjs 缺失或参数为 `setup`，创建 HUD 目录和脚本：
+
+首先，创建目录：
+```bash
+node -e "require('fs').mkdirSync(require('path').join(process.env.CLAUDE_CONFIG_DIR||require('path').join(require('os').homedir(),'.claude'),'hud'),{recursive:true})"
+```
+
+然后，使用 Write 工具创建 `~/.claude/hud/omc-hud.mjs`，内容如下：
+
+```javascript
+#!/usr/bin/env node
+/**
+ * OMC HUD - Statusline Script
+ * Wrapper that imports from plugin cache or development paths
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// Semantic version comparison: returns negative if a < b, positive if a > b, 0 if equal
+function semverCompare(a, b) {
+  // Use parseInt to handle pre-release suffixes (e.g. "0-beta" -> 0)
+  const pa = a.replace(/^v/, "").split(".").map(s => parseInt(s, 10) || 0);
+  const pb = b.replace(/^v/, "").split(".").map(s => parseInt(s, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const na = pa[i] || 0;
+    const nb = pb[i] || 0;
+    if (na !== nb) return na - nb;
+  }
+  // If numeric parts equal, non-pre-release > pre-release
+  const aHasPre = /-/.test(a);
+  const bHasPre = /-/.test(b);
+  if (aHasPre && !bHasPre) return -1;
+  if (!aHasPre && bHasPre) return 1;
+  return 0;
+}
+
+async function main() {
+  const home = homedir();
+  let pluginCacheDir = null;
+
+  // 1. Try plugin cache first (marketplace: omc, plugin: ultrapower)
+  const pluginCacheBase = join(home, ".claude/plugins/cache/omc/ultrapower");
+  if (existsSync(pluginCacheBase)) {
+    try {
+      const versions = readdirSync(pluginCacheBase);
+      if (versions.length > 0) {
+        const latestVersion = versions.sort(semverCompare).reverse()[0];
+        pluginCacheDir = join(pluginCacheBase, latestVersion);
+        const pluginPath = join(pluginCacheDir, "dist/hud/index.js");
+        if (existsSync(pluginPath)) {
+          await import(pathToFileURL(pluginPath).href);
+          return;
+        }
+      }
+    } catch { /* continue */ }
+  }
+
+  // 2. Development paths
+  const devPaths = [
+    join(home, "Workspace/oh-my-claude-sisyphus/dist/hud/index.js"),
+    join(home, "workspace/oh-my-claude-sisyphus/dist/hud/index.js"),
+    join(home, "Workspace/ultrapower/dist/hud/index.js"),
+    join(home, "workspace/ultrapower/dist/hud/index.js"),
+  ];
+
+  for (const devPath of devPaths) {
+    if (existsSync(devPath)) {
+      try {
+        await import(pathToFileURL(devPath).href);
+        return;
+      } catch { /* continue */ }
+    }
+  }
+
+  // 3. Fallback - HUD not found (provide actionable error message)
+  if (pluginCacheDir) {
+    console.log(`[OMC] HUD not built. Run: cd "${pluginCacheDir}" && npm install`);
+  } else {
+    console.log("[OMC] Plugin not found. Run: /ultrapower:omc-setup");
+  }
+}
+
+main();
+```
+
+**步骤 3（续）：** 设置可执行权限（仅 Unix，Windows 跳过）：
+```bash
+node -e "if(process.platform==='win32'){console.log('Skipped (Windows)')}else{require('fs').chmodSync(require('path').join(process.env.CLAUDE_CONFIG_DIR||require('path').join(require('os').homedir(),'.claude'),'hud','omc-hud.mjs'),0o755);console.log('Done')}"
+```
+
+**步骤 4：** 更新 settings.json 以使用 HUD：
+
+读取 `~/.claude/settings.json`，然后更新/添加 `statusLine` 字段。
+
+**重要：** 命令必须使用绝对路径，而非 `~`，因为 Windows 不会在 shell 命令中展开 `~`。
+
+首先，确定正确路径：
+```bash
+node -e "const p=require('path').join(require('os').homedir(),'.claude','hud','omc-hud.mjs');console.log(JSON.stringify(p))"
+```
+
+然后使用解析后的路径设置 `statusLine` 字段。Unix 上如下所示：
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node /home/username/.claude/hud/omc-hud.mjs"
+  }
+}
+```
+
+Windows 上如下所示：
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node C:\\Users\\username\\.claude\\hud\\omc-hud.mjs"
+  }
+}
+```
+
+使用 Edit 工具添加/更新此字段，同时保留其他设置。
+
+**步骤 5：** 清理旧 HUD 脚本（如有）：
+```bash
+node -e "const p=require('path'),f=require('fs'),d=process.env.CLAUDE_CONFIG_DIR||p.join(require('os').homedir(),'.claude'),t=p.join(d,'hud','sisyphus-hud.mjs');try{if(f.existsSync(t)){f.unlinkSync(t);console.log('Removed legacy script')}else{console.log('No legacy script found')}}catch{}"
+```
+
+**步骤 6：** 告知用户重启 Claude Code 以使变更生效。
+
+## 显示预设
+
+### 最小（Minimal）
+仅显示必要信息：
+
+### 专注（Focused，默认）
+显示所有相关元素：
+```
+[OMC] branch:main | ralph:3/10 | US-002 | ultrawork skill:planner | ctx:67% | agents:2 | bg:3/5 | todos:2/5
+```
+
+### 完整（Full）
+显示所有内容，包括多行 agent 详情：
+```
+[OMC] repo:ultrapower branch:main | ralph:3/10 | US-002 (2/5) | ultrawork | ctx:[████░░]67% | agents:3 | bg:3/5 | todos:2/5
+├─ O architect    2m   analyzing architecture patterns...
+├─ e explore     45s   searching for test files
+└─ s executor     1m   implementing validation logic
+```
+
+## 多行 Agent 显示
+
+Agent 运行时，HUD 在独立行显示详细信息：
+- **树形字符**（`├─`、`└─`）显示视觉层级
+- **Agent 代码**（O、e、s）表示 agent 类型及模型层级颜色
+- **持续时间** 显示每个 agent 已运行多长时间
+- **描述** 显示每个 agent 正在做什么（最多 45 个字符）
+
+## 显示元素
+
+| 元素 | 描述 |
+|---------|-------------|
+| `[OMC]` | 模式标识符 |
+| `repo:name` | Git 仓库名称（青色） |
+| `branch:name` | Git 分支名称（青色） |
+| `ralph:3/10` | Ralph 循环迭代/最大次数 |
+| `US-002` | 当前 PRD story ID |
+| `ultrawork` | 活跃模式徽章 |
+| `skill:name` | 最后激活的 skill（青色） |
+| `ctx:67%` | 上下文窗口使用率 |
+| `agents:2` | 运行中的子 agent 数量 |
+| `bg:3/5` | 后台任务槽位 |
+| `todos:2/5` | 待办完成情况 |
+
+## 颜色编码
+
+- **绿色**：正常/健康
+- **黄色**：警告（上下文 >70%，ralph >7）
+- **红色**：严重（上下文 >85%，ralph 达到最大值）
+
+## 配置位置
+
+HUD 配置存储于：`~/.claude/.omc/hud-config.json`
+
+## 手动配置
+
+可手动编辑配置文件。每个选项可单独设置 —— 未设置的值将使用默认值。
+
+```json
+{
+  "preset": "focused",
+  "elements": {
+    "omcLabel": true,
+    "ralph": true,
+    "prdStory": true,
+    "activeSkills": true,
+    "lastSkill": true,
+    "contextBar": true,
+    "agents": true,
+    "backgroundTasks": true,
+    "todos": true,
+    "showCache": true,
+    "showCost": true,
+    "maxOutputLines": 4
+  },
+  "thresholds": {
+    "contextWarning": 70,
+    "contextCritical": 85,
+    "ralphWarning": 7
+  }
+}
+```
+
+## 故障排除
+
+若 HUD 未显示：
+1. 运行 `/ultrapower:hud setup` 自动安装并配置
+2. 设置完成后重启 Claude Code
+3. 若仍不工作，运行 `/ultrapower:omc-doctor` 进行完整诊断
+
+手动验证：
+- HUD 脚本：`~/.claude/hud/omc-hud.mjs`
+- 设置：`~/.claude/settings.json` 应已配置 `statusLine`
+
+---
+
+*HUD 在活跃会话期间每约 300ms 自动更新。*

package/skills/learn-about-omc/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: learn-about-omc
+description: 了解你的 OMC 使用模式并获取个性化建议
+---
+
+# 了解 OMC
+
+分析你的 OMC 使用模式，提供个性化建议，帮助你更好地使用 ultrapower。
+
+## 用法
+
+```
+/ultrapower:learn-about-omc
+```
+
+## 行为
+
+1. **扫描使用数据**，来源：
+   - `.omc/sessions/` —— 会话历史
+   - `.omc/state/` —— 模式使用模式
+   - `.omc/notepad.md` —— 工作记忆
+   - `.omc/project-memory.json` —— 项目上下文
+   - Agent 流程追踪 —— 工具和 agent 使用情况
+2. **分析模式**：
+   - 最常用的模式和 skill
+   - 最频繁派生的 agent 类型
+   - 常见工作流和任务类型
+   - 会话时长和完成率
+3. **生成建议**：
+   - 符合你工作流但未充分利用的功能
+   - 更高效的 skill 组合
+   - 配置优化
+   - 基于你使用情况的技巧
+
+## 输出
+
+包含使用统计和可操作建议的个性化报告，帮助改善你的 OMC 工作流。

package/skills/learner/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: learner
+description: 从当前对话中提取已学到的 skill
+---
+
+# Learner Skill
+
+## 核心洞见
+
+可复用的 skill 不是用来复制粘贴的代码片段，而是**原则和决策启发式方法**，教会 Claude 如何思考一类问题。
+
+**区别所在：**
+- 差（模仿）："遇到 ConnectionResetError 时，添加这个 try/except 块"
+- 好（可复用 skill）："在异步网络代码中，任何 I/O 操作都可能因客户端/服务端生命周期不匹配而独立失败。原则：分别包装每个 I/O 操作，因为操作之间的失败是常见情况，而非例外。"
+
+好的 skill 改变的是 Claude 解决问题的方式，而不仅仅是它产出的代码。
+
+## 为何重要
+
+提取 skill 之前，先问自己：
+- "有人能在 5 分钟内 Google 到这个吗？" → 如果是，停止。不要提取。
+- "这是否特定于这个代码库？" → 如果否，停止。不要提取。
+- "这是否经过了真正的调试努力才发现的？" → 如果否，停止。不要提取。
+
+如果一个潜在 skill 在任何一个问题上失败，就不值得保存。
+
+## 识别模式
+
+仅在以下情况后使用 /ultrapower:learner：
+- 解决了需要深入调查的棘手 bug
+- 发现了特定于此代码库的非显而易见的解决方法
+- 找到了遗忘后会浪费时间的隐藏陷阱
+- 揭露了影响此项目的未记录行为
+
+## 方法
+
+### 提取流程
+
+**步骤 1：收集必要信息**
+
+- **问题描述**：发生的具体错误、症状或困惑
+  - 包含实际错误信息、文件路径、行号
+  - 示例："TypeError in src/hooks/session.ts:45 when sessionId is undefined after restart"
+
+- **解决方案**：确切的修复方法，而非泛泛建议
+  - 包含代码片段、文件路径、配置变更
+  - 示例："Add null check before accessing session.user, regenerate session on 401"
+
+- **触发词**：再次遇到此问题时会出现的关键词
+  - 使用错误信息片段、文件名、症状描述
+  - 示例：["sessionId undefined", "session.ts TypeError", "401 session"]
+
+- **范围**：几乎总是项目级别，除非是真正通用的洞见
+
+**步骤 2：质量验证**
+
+系统会拒绝以下 skill：
+- 过于泛泛（没有文件路径、行号或具体错误信息）
+- 容易 Google 到（标准模式、库的用法）
+- 解决方案模糊（没有代码片段或精确说明）
+- 触发词质量差（匹配所有内容的通用词汇）
+
+**步骤 3：保存位置**
+
+- **用户级别**：~/.claude/skills/omc-learned/ —— 少用。仅用于真正可移植的洞见。
+- **项目级别**：.omc/skills/ —— 默认。随仓库进行版本控制。
+
+### 什么是有用的 Skill
+
+**重要**：并非每个解决方案都值得保存。好的 skill 应具备：
+
+1. **无法 Google 到**：通过搜索不容易找到的内容
+   - 差："How to read files in TypeScript" ❌
+   - 好："This codebase uses custom path resolution in ESM that requires fileURLToPath + specific relative paths" ✓
+
+2. **上下文相关**：引用了此代码库中的实际文件、错误信息或模式
+   - 差："Use try/catch for error handling" ❌
+   - 好："The aiohttp proxy in server.py:42 crashes on ClientDisconnectedError - wrap StreamResponse in try/except" ✓
+
+3. **精确可操作**：明确告诉你做什么以及在哪里做
+   - 差："Handle edge cases" ❌
+   - 好："When seeing 'Cannot find module' in dist/, check tsconfig.json moduleResolution matches package.json type field" ✓
+
+4. **来之不易**：需要大量调试努力才能发现
+   - 差：通用编程模式 ❌
+   - 好："Race condition in worker.ts - the Promise.all at line 89 needs await before the map callback returns" ✓
+
+### 反模式（不要提取）
+
+- 通用编程模式（改用文档）
+- 重构技巧（这些是通用的）
+- 库的使用示例（改用库文档）
+- 类型定义或样板代码
+- 任何初级开发者能在 5 分钟内 Google 到的内容
+
+## Skill 格式
+
+Skill 以 markdown 格式保存，结构如下：
+
+### YAML Frontmatter
+
+标准元数据字段：
+- id, name, description, source, triggers, quality
+
+### 正文结构（必填）
+
+```markdown
+# [Skill Name]
+
+## 核心洞见
+你发现的底层原则是什么？不是代码，而是思维模型。
+示例："Async I/O operations are independently failable. Client lifecycle != server lifecycle."
+
+## 为何重要
+不知道这个会出什么问题？是什么症状引导你来到这里？
+示例："Proxy server crashes on client disconnect, taking down other requests."
+
+## 识别模式
+你怎么知道这个 skill 适用？有哪些迹象？
+示例："Building any long-lived connection handler (proxy, websocket, SSE)"
+
+## 方法
+决策启发式方法，而不仅仅是代码。Claude 应该如何思考这个问题？
+示例："For each I/O operation, ask: what if this fails right now? Handle it locally."
+
+## 示例（可选）
+如果代码有帮助，展示它——但作为原则的说明，而非复制粘贴的素材。
+```
+
+**关键**：如果 Claude 能将 skill 应用于新情况（而不仅仅是相同情况），它才是可复用的。
+
+## 相关命令
+
+- /ultrapower:note —— 保存能在 compaction 后存活的快速笔记（比 skill 更非正式）
+- /ultrapower:ralph —— 启动带有学习捕获的开发循环
+
+## Axiom 进化引擎触发逻辑（增强）
+
+当检测到以下条件时，自动触发学习队列处理：
+
+### 触发条件
+
+- 完成 3 个以上任务后
+- 遇到并解决了重复出现的错误模式（出现次数 ≥ 3）
+- 用户显式调用 `/ultrapower:learner`
+
+### 学习队列处理流程
+
+1. **收集学习条目**：从当前会话提取值得记录的洞见
+2. **模式检测**：检查 `.omc/axiom/project_decisions.md` 中的 Known Issues
+   - 若同类错误出现 ≥ 3 次 → 升级为正式模式记录
+3. **知识库更新**：将新模式写入 `.omc/knowledge/`
+4. **工作流指标**：记录任务完成率、平均修复次数、阻塞频率
+
+### 进化报告格式
+
+输出到 `.omc/axiom/evolution_report_[date].md`：
+
+```markdown
+## Evolution Report [Date]
+
+### 新增模式
+| 模式名称 | 触发条件 | 解决方案 | 出现次数 |
+|---------|---------|---------|---------|
+
+### 工作流指标
+- 任务完成率：X%
+- 平均修复次数：X
+- 最常见阻塞原因：[列表]
+
+### 反思日志
+[本次迭代的关键学习点]
+```
+
+### 知识库条目格式
+
+写入 `.omc/knowledge/[pattern-name].md`：
+```markdown
+---
+pattern: [模式名称]
+occurrences: [出现次数]
+last_seen: [日期]
+---
+
+## 触发条件
+## 根因
+## 解决方案
+## 预防措施
+```

package/skills/mcp-setup/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: mcp-setup
+description: 为 agent 配置常用 MCP server 以增强能力
+---
+
+# MCP Setup
+
+配置 Model Context Protocol (MCP) server，为 Claude Code 扩展外部工具能力，如网页搜索、文件系统访问和 GitHub 集成。
+
+## 概述
+
+MCP server 为 Claude Code agent 提供额外工具。本 skill 帮助你通过 `claude mcp add` 命令行界面配置常用 MCP server。
+
+## 第一步：显示可用 MCP Server
+
+使用 AskUserQuestion 向用户展示可用的 MCP server 选项：
+
+**问题：** "您想配置哪个 MCP server？"
+
+**选项：**
+1. **Context7** - 来自主流库的文档和代码上下文
+2. **Exa Web Search** - 增强网页搜索（替代内置 websearch）
+3. **Filesystem** - 扩展文件系统访问能力
+4. **GitHub** - GitHub API 集成，用于 issue、PR 和仓库管理
+5. **以上全部** - 配置所有推荐的 MCP server
+6. **自定义** - 添加自定义 MCP server
+
+## 第二步：收集所需信息
+
+### Context7：
+无需 API key，可立即使用。
+
+### Exa Web Search：
+询问 API key：
+```
+您有 Exa API key 吗？
+- 在 https://exa.ai 获取
+- 输入您的 API key，或输入 'skip' 稍后配置
+```
+
+### Filesystem：
+询问允许访问的目录：
+```
+filesystem MCP 应该访问哪些目录？
+默认：当前工作目录
+输入逗号分隔的路径，或按 Enter 使用默认值
+```
+
+### GitHub：
+询问 token：
+```
+您有 GitHub Personal Access Token 吗？
+- 在 https://github.com/settings/tokens 创建
+- 推荐权限：repo, read:org
+- 输入您的 token，或输入 'skip' 稍后配置
+```
+
+## 第三步：使用 CLI 添加 MCP Server
+
+使用 `claude mcp add` 命令配置每个 MCP server。CLI 会自动处理 settings.json 的更新和合并。
+
+### Context7 配置：
+```bash
+claude mcp add context7 -- npx -y @upstash/context7-mcp
+```
+
+### Exa Web Search 配置：
+```bash
+claude mcp add -e EXA_API_KEY=<用户提供的key> exa -- npx -y exa-mcp-server
+```
+
+### Filesystem 配置：
+```bash
+claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem <允许的目录>
+```
+
+### GitHub 配置：
+
+**选项 1：Docker（本地）**
+```bash
+claude mcp add -e GITHUB_PERSONAL_ACCESS_TOKEN=<用户提供的token> github -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
+```
+
+**选项 2：HTTP（远程）**
+```bash
+claude mcp add --transport http github https://api.githubcopilot.com/mcp/
+```
+
+> 注意：Docker 选项需要安装 Docker。HTTP 选项更简单但功能可能有所不同。
+
+## 第四步：验证安装
+
+配置完成后，验证 MCP server 是否正确设置：
+
+```bash
+# 列出已配置的 MCP server
+claude mcp list
+```
+
+这将显示所有已配置的 MCP server 及其状态。
+
+## 第五步：显示完成消息
+
+```
+MCP Server 配置完成！
+
+已配置的 SERVER：
+[列出已配置的 server]
+
+后续步骤：
+1. 重启 Claude Code 使更改生效
+2. 配置的 MCP 工具将对所有 agent 可用
+3. 运行 `claude mcp list` 验证配置
+
+使用提示：
+- Context7：询问库文档（如"如何使用 React hooks？"）
+- Exa：用于网页搜索（如"搜索最新 TypeScript 特性"）
+- Filesystem：工作目录之外的扩展文件操作
+- GitHub：与 GitHub 仓库、issue 和 PR 交互
+
+故障排除：
+- 如果 MCP server 未出现，运行 `claude mcp list` 检查状态
+- 确保已安装 Node.js 18+ 以使用基于 npx 的 server
+- GitHub Docker 选项需要安装并运行 Docker
+- 运行 /ultrapower:omc-doctor 诊断问题
+
+管理 MCP SERVER：
+- 添加更多 server：/ultrapower:mcp-setup 或 `claude mcp add ...`
+- 列出 server：`claude mcp list`
+- 删除 server：`claude mcp remove <server-name>`
+```
+
+## 自定义 MCP Server
+
+如果用户选择"自定义"：
+
+询问：
+1. Server 名称（标识符）
+2. 传输类型：`stdio`（默认）或 `http`
+3. stdio 方式：命令和参数（如 `npx my-mcp-server`）
+4. http 方式：URL（如 `https://example.com/mcp`）
+5. 环境变量（可选，key=value 格式）
+6. HTTP 请求头（可选，仅 http 传输）
+
+然后构建并运行相应的 `claude mcp add` 命令：
+
+**stdio server：**
+```bash
+# 不带环境变量
+claude mcp add <server-name> -- <command> [args...]
+
+# 带环境变量
+claude mcp add -e KEY1=value1 -e KEY2=value2 <server-name> -- <command> [args...]
+```
+
+**HTTP server：**
+```bash
+# 基本 HTTP server
+claude mcp add --transport http <server-name> <url>
+
+# 带请求头的 HTTP server
+claude mcp add --transport http --header "Authorization: Bearer <token>" <server-name> <url>
+```
+
+## 常见问题
+
+### MCP Server 未加载
+- 确保已安装 Node.js 18+
+- 检查 npx 是否在 PATH 中
+- 运行 `claude mcp list` 验证 server 状态
+- 检查 server 日志中的错误
+
+### API Key 问题
+- Exa：在 https://dashboard.exa.ai 验证 key
+- GitHub：确保 token 具有所需权限（repo, read:org）
+- 如需要，使用正确凭据重新运行 `claude mcp add`
+
+### Agent 仍在使用内置工具
+- 配置后重启 Claude Code
+- 配置 exa 后内置 websearch 将降低优先级
+- 运行 `claude mcp list` 确认 server 已激活
+
+### 删除或更新 Server
+- 删除：`claude mcp remove <server-name>`
+- 更新：先删除旧 server，再用新配置重新添加