内容
# 困惑度 MCP 技能
适用于 Codex、Windsurf、Cursor、Claude Code 和 Antigravity 的困惑度模式捆绑包：低成本搜索、专业搜索、深入研究和特定 URL 读取。
[🇷🇺 以俄语阅读](README.ru.md)
## 本仓库的用途
本仓库将四种独立的困惑度模式打包，以便在多个代理运行时保持成本、深度和调用风格的明确：
- `Codex` 使用明确的技能调用，例如 `$perplexity_*`。
- `Windsurf` 使用技能 `@perplexity-*` 和工作流 `/perplexity-*`。
- `Cursor` 使用项目 MCP 配置和项目规则。
- `Claude Code` 使用项目 MCP 配置和项目技能。
- `Antigravity` 使用共享的 `AGENTS.md` 指导文件和相同的仓库本地脚本。
这种分离是有意的：快速查找不应无声地变为昂贵的研究，读取特定 URL 不应与一般搜索混淆。
## 30 秒内选择
| 任务 | 模式 | Codex | Windsurf | 需要 MCP |
| --- | --- | --- | --- | --- |
| 查找链接和片段 | 仅搜索 | `$perplexity_search_only` | `@perplexity-search` / `/perplexity-search` | 优先 |
| 获取带有来源的简短答案 | 专业搜索 | `$perplexity-pro-search` | `@perplexity-pro` / `/perplexity-pro` | 否 |
| 运行广泛的多源审查 | 深入研究 | `$perplexity_deep_research` | `@perplexity-research` / `/perplexity-research` | 是 |
| 读取一个或多个已知 URL | 获取 URL | `$perplexity-fetch-url-content` | `@perplexity-fetch-url` / `/perplexity-fetch-url` | 否 |
`Cursor`、`Claude Code` 和 `Antigravity` 通过项目配置和仓库指导文件使用相同的四种模式，而不是 Codex/Windsurf 样式的调用语法。它们的设置在下面记录。
## 兼容性矩阵
| 模式 | Codex | Windsurf | 需要 MCP | 需要 API 密钥 | 直接回退 | 典型成本/速度 |
| --- | --- | --- | --- | --- | --- | --- |
| 仅搜索 | `$perplexity_search_only` | `@perplexity-search` / `/perplexity-search` | 优先 | 是 | 搜索 API 脚本 | 最便宜，快速 |
| 专业搜索 | `$perplexity-pro-search` | `@perplexity-pro` / `/perplexity-pro` | 否 | 是 | 不适用 | 中等成本，快速 |
| 深入研究 | `$perplexity_deep_research` | `@perplexity-research` / `/perplexity-research` | 是 | 是 | 无 | 最高成本，最慢 |
| 获取 URL | `$perplexity-fetch-url-content` | `@perplexity-fetch-url` / `/perplexity-fetch-url` | 否 | 是 | 不适用 | 中等成本，取决于页面 |
## 快速设置
### 1. 获取困惑度 API 密钥
在 [困惑度控制台](https://console.perplexity.ai/) 中创建 API 密钥。不要将密钥存储在仓库文件中。
重要计费注意：
- 困惑度专业订阅不再包含每月 API 积分。
- Sonar API 使用 [困惑度控制台](https://console.perplexity.ai/) 中的单独余额。
- 如果余额为空，请求可能会在密钥配置正确时出现授权或计费错误。
### 2. 使用 npm 安装集成
使用 npm CLI 作为主要安装程序：
```bash
npx perplexity-mcp-skills install codex
npx perplexity-mcp-skills install windsurf --api-key "your_key"
npx perplexity-mcp-skills install cursor
npx perplexity-mcp-skills install claude
```
或安装所有支持的目标：
```bash
npx perplexity-mcp-skills install all --api-key "your_key"
```
有用的维护命令：
```bash
npx perplexity-mcp-skills doctor
npx perplexity-mcp-skills sync windsurf
npx perplexity-mcp-skills uninstall codex --dry-run
```
使用 `--dry-run` 预览写入，使用 `--force` 替换包拥有的文件，使用 `--no-key` 安装文件而不更改包含机密的 MCP 配置。
### 3. MCP 配置
对于 Windsurf，`install windsurf --api-key ...` 将官方困惑度 MCP 服务器添加到 `~/.codeium/windsurf/mcp_config.json`。
对于 Codex，您可以通过以下方式添加官方 MCP 服务器：
```bash
codex mcp add perplexity --env PERPLEXITY_API_KEY="your_key" -- npx -y @perplexity-ai/mcp-server
```
MCP 服务器形状为：
```json
{
"mcpServers": {
"perplexity": {
"command": "npx",
"args": ["-y", "@perplexity-ai/mcp-server"],
"env": {
"PERPLEXITY_API_KEY": "your_key"
}
}
}
}
```
`$perplexity_deep_research` 需要 MCP。`$perplexity_search_only` 仍然更喜欢 MCP 路径，但如果在活动运行时未公开该工具，则具有直接搜索 API 回退。
如果您不需要 MCP，直接脚本可以从以下位置读取密钥：
- `PERPLEXITY_API_KEY`
- `~/.codex/config.toml` 或 `CODEX_HOME/config.toml`
- `~/.codeium/windsurf/mcp_config.json`
在运行直接脚本之前，安装依赖项：
```bash
python3 -m pip install -r requirements.txt
```
### 4. 基于克隆的旧安装
当您故意从本地克隆工作时，旧的 shell 安装程序仍然可用：
#### Codex
```bash
./scripts/install_to_codex.sh
```
之后，技能可作为显式调用：
```text
$perplexity_search_only <查询>
$perplexity-pro-search <查询>
$perplexity_deep_research <查询>
$perplexity-fetch-url-content <网址> [网址 ...]
```
#### Windsurf
对于 Windsurf，仓库包含三个集成层：
- `.windsurf/skills/` 用于 `@perplexity-search`、`@perplexity-research`、`@perplexity-pro`、`@perplexity-fetch-url`
- `.windsurf/workflows/` 用于 `/perplexity-search`、`/perplexity-research`、`/perplexity-pro`、`/perplexity-fetch-url`
- `.windsurf/rules/perplexity-mcp-skills.md` 用于共享路由和成本控制
要全局安装它们：
```bash
PERPLEXITY_API_KEY="your_key" ./scripts/install_to_windsurf.sh
```
安装程序复制：
- 技能到 `~/.codeium/windsurf/skills/`
- 工作流到 `~/.codeium/windsurf/global_workflows/`
- MCP 配置到 `~/.codeium/windsurf/mcp_config.json`
重启 Windsurf 后，使用：
```text
@perplexity-search <查询>
@perplexity-pro <查询>
@perplexity-research <查询>
@perplexity-fetch-url <网址> [网址 ...]
```
或工作流：
```text
/perplexity-search
/perplexity-pro
/perplexity-research
/perplexity-fetch-url
```
#### Cursor
Cursor 支持通过以下方式提供：
- `.cursor/mcp.json` 中的项目 MCP 配置
- `.cursor/rules/perplexity.mdc` 中的项目规则
- 相同的仓库本地直接脚本在其他地方使用
在 Cursor 中打开仓库后，代理可以使用配置的 MCP 服务器和项目规则。对于 CLI 验证，Cursor 文档了 `cursor-agent mcp list` 和 `cursor-agent mcp list-tools <identifier>` 用于检查配置的服务器和工具。来源：Cursor MCP 和规则文档。
#### Claude Code
Claude Code 支持通过以下方式提供：
- `.mcp.json` 中的项目 MCP 配置
- `.claude/skills/` 中的项目技能
Claude Code 通过 `.mcp.json` 记录了项目范围的 MCP 配置，通过 `.claude/skills/` 记录了项目技能。在 Claude Code 中打开仓库后，MCP 服务器和项目技能在项目内可用。来源：Claude Code MCP 和代理技能文档。
#### Antigravity
Antigravity 支持通过 `AGENTS.md` 中的共享仓库指导文件和相同的仓库本地直接脚本提供。
此次部署未添加工具特定的 Antigravity MCP 配置文件，因为仓库未编码官方稳定的 Antigravity 项目配置路径。支持的路径是共享路由指导文件加上您已经在工作区中使用的本地脚本和 MCP 设置。
## 按任务分类的示例
### 快速廉价地查找来源
```text
使用 $perplexity_search_only 查找官方困惑度 MCP 服务器文档，并返回 5 个最佳链接和简短注释。
```
### 获取带有来源的简短答案
```text
使用 $perplexity-pro-search 比较 Codex 和 Windsurf 的当前困惑度 MCP 设置选项，并返回简洁的来源答案。
```
### 深入研究主题
```text
使用 $perplexity_deep_research 深入研究 GitHub 组织最佳实践。关注实用收获并保持答案简洁。
```
### 读取特定 URL
```text
使用 $perplexity-fetch-url-content 读取 https://docs.perplexity.ai/docs/sonar/pro-search/tools 并总结关键的 fetch_url_content 限制。
```
## 模式指南
### 仅搜索
最低成本模式。在需要链接、日期、片段和主要来源而无需答案合成时使用。
- 首选路径：MCP `perplexity_search`
- 直接回退：`perplexity_search_only/scripts/search_only.py`
- 它不应切换到 `perplexity_ask`、`perplexity_reason` 或 `perplexity_research`
### 专业搜索
链接查找和深入研究之间的中间模式。在需要带有来源的现成答案和显式 `search_type=pro` 时使用。
- 路径：`perplexity-pro-search/scripts/pro_search.py`
- 模型路径：`sonar-pro`
- 输出：答案、来源、使用情况、步骤日志
### 深入研究
最昂贵的模式。仅在需要长时间运行和较高成本的广泛多源问题时使用。
- 路径：MCP `perplexity_research`
- 回退：无
- 范围：即使在深入模式下，也要保持问题狭窄
### 获取 URL
通过内置的 Sonar Pro 工具 `fetch_url_content` 读取特定 URL 的模式。
- 路径：`perplexity-fetch-url-content/scripts/fetch_url_content.py`
- 使用 `--require-fetch` 当必须确认每个请求的 URL 时
- 不要暗示 API 返回完整的原始 HTML
## 验证
使用 npm CLI 进行快速诊断：
```bash
npx perplexity-mcp-skills doctor # 检查已安装的文件、API 密钥、Node/Python
npx perplexity-mcp-skills doctor --offline # 跳过子进程检查
```
开发人员检查：
```bash
npm run typecheck # TypeScript 类型验证
npm test # CLI 烟雾测试（构建 + 帮助 + 医生 + 安装 dry-run）
npm run check # 完整的离线烟雾检查（scripts/check.sh）
npm run pack:dry-run # 验证 npm 包内容
```
`scripts/check.sh` 运行：
- `python3 -m py_compile` 用于 `perplexity_common.py` 和直接脚本
- `search_only.py --dry-run --json`
- `fetch_url_content.py --dry-run --json`
- `pro_search.py --help`
- npm CLI 构建、类型检查和安装 dry-run
- grep 检查 README 和 `.windsurf/` 中的关键调用名称
由于这些会消耗 API 积分，因此故意将实时困惑度请求排除在 CI 和此烟雾检查之外。
## 故障排除
| 问题 | 检查内容 |
| --- | --- |
| `perplexity_search` 在会话中未公开 | 使用直接回退 `perplexity_search_only/scripts/search_only.py --json` 或匹配的 Windsurf 技能路径 |
| Cursor 无法看到困惑度 MCP 服务器 | 检查 `.cursor/mcp.json`，确认 `PERPLEXITY_API_KEY`，然后使用 `cursor-agent mcp list` 检查 |
| Claude Code 无法看到困惑度 MCP 服务器 | 检查 `.mcp.json`，确认 `PERPLEXITY_API_KEY`，然后使用 `claude mcp list` 检查 |
| Claude Code 技能未触发 | 检查 `.claude/skills/` 并重启 Claude Code 以重新加载项目技能 |
| Antigravity 未获取路由指导文件 | 检查工作区是否包含 `AGENTS.md`，然后直接使用仓库本地脚本 |
| `PERPLEXITY_API_KEY` 丢失 | 检查 shell 环境、`~/.codex/config.toml`、`CODEX_HOME/config.toml`、`~/.codeium/windsurf/mcp_config.json` |
| Sonar API 计费/授权错误 | 确保困惑度 API 余额已充值，而不仅仅是专业订阅 |
| URL 在 `fetched_urls` 中丢失 | 以 `--require-fetch` 运行 Fetch URL 模式并检查 `missing_requested_urls` |
| 沙盒阻止网络访问 | 使用提升的访问权限重新运行相同的脚本，而不是切换到另一个模式 |
| CI 在烟雾检查中失败 | 在本地运行 `./scripts/check.sh`，然后比较 README 调用名称和预期仓库结构 |
| 快速健康检查 | 运行 `npx perplexity-mcp-skills doctor` 检查已安装的文件、API 密钥和系统要求 |
## 成本说明
观察到的成本示例：
- `/perplexity-search`：一个示例包含 `4` 个搜索 API 请求，费用为 **$0.02**
- `/perplexity-pro`：最近一次运行费用为 **$0.01819**
- `/perplexity-fetch-url`：最近一次汇总运行费用为 **$0.01894**
- `/perplexity-research`：一次深入研究运行费用为 **$1.38**
深入研究通常比其他模式更昂贵。
## 仓库结构
```text
src/ # TypeScript CLI 源代码（安装、医生、同步、卸载）
dist/ # 编译的 CLI（由 prepack / npm run build 构建）
package.json # npm 包元数据、脚本和文件白名单
perplexity_search_only/ # Codex 技能 + 直接搜索 API 回退
perplexity-pro-search/ # Codex 技能 + Sonar 专业搜索脚本
perplexity_deep_research/ # Codex 技能，用于 MCP 深入研究
perplexity-fetch-url-content/ # Codex 技能 + fetch_url_content 脚本
.windsurf/skills/ # Windsurf 技能
.windsurf/workflows/ # Windsurf 工作流
.windsurf/rules/ # 共享的 Windsurf 路由规则
.cursor/mcp.json # Cursor 项目 MCP 配置
.cursor/rules/ # Cursor 项目规则
.claude/skills/ # Claude Code 项目技能
.mcp.json # Claude Code 项目 MCP 配置
AGENTS.md # 共享的跨工具路由指导文件
scripts/install_to_codex.sh # 旧的全局 Codex 安装
scripts/install_to_windsurf.sh # 旧的全局 Windsurf 安装
scripts/check.sh # 离线安全烟雾验证
docs/releasing.md # 发布流程文档
perplexity_common.py # 共享的直接脚本帮助程序
skills_manifest.yaml # 包清单和安装/源路径
```
## 注释
- 在 UI 中启用 MCP 服务器并不保证其工具在特定代理会话中公开。
- 搜索模式包括直接搜索 API 回退。
- `skills_manifest.yaml` 仍然是安装路径和 Windsurf 映射的轻量级源。
- Cursor MCP 项目配置遵循 Cursor 记录的 `.cursor/mcp.json` 路径，项目规则遵循 `.cursor/rules`。
- Claude Code 项目 MCP 配置遵循 Anthropic 记录的 `.mcp.json` 路径，项目技能遵循 `.claude/skills/`。
- 本项目在 MIT 许可下发布。有关详细信息，请参见 `LICENSE`。
