# 在你日常使用的 AI 助手中创建 Pi 演示文稿

从想法、内容或资料开始；主题和页数可选。创建后查询进度，再在 Pi 查看和编辑已保存的演示文稿。

## PI Dev

PI Dev 插件开发验证中；当前可按以下步骤添加 Pi MCP 远程连接。

## 端点

https://pi-mcp.deepvinci.tech/api/v1/mcp

传输：Streamable HTTP。认证：OAuth with PKCE 和服务的动态客户端注册（DCR）流程。

## 从你正在使用的 AI 助手接入

### Codex

使用以下 Codex 命令添加 Pi MCP 远程连接；需要连接账号时，再由你本人完成浏览器授权。

官方指南: https://learn.chatgpt.com/docs/extend/mcp

1. 在终端保存 Pi MCP 远程连接：

```
codex mcp add pi --url https://pi-mcp.deepvinci.tech/api/v1/mcp
```

2. 需要连接 Pi 账号时，请由你本人在浏览器完成授权：

```
codex mcp login pi --oauth-client-registration dcr
```

### Claude Desktop

在 Claude Desktop 中将 Pi 添加为账号级远程连接。

官方指南: https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp

1. 打开 Customize > Connectors > + Add > Add custom connector。

2. 添加远程 Pi 地址：https://pi-mcp.deepvinci.tech/api/v1/mcp

3. 出现提示时，请由你本人在浏览器完成账号级授权。

### Cursor

在 Cursor 的 MCP 设置或适用的项目/用户 mcp.json 中添加 Pi，并按 Cursor 提示完成 OAuth。

官方指南: https://cursor.com/docs/mcp

1. 在 Cursor 的 MCP 设置中添加远程服务，或在适用的 mcp.json 使用：

```
{
  "mcpServers": {
    "pi": {
      "url": "https://pi-mcp.deepvinci.tech/api/v1/mcp"
    }
  }
}
```

2. Cursor 提示 OAuth 时，请由你本人在浏览器完成。保存连接后，可在后续获得授权的请求中使用。

### OpenCode

在 opencode.json 中添加 Pi 远程 MCP；需要连接账号时，再运行授权命令。

官方指南: https://opencode.ai/docs/mcp-servers/

1. 在 opencode.json 中添加：

```
{
  "mcp": {
    "pi": {
      "type": "remote",
      "url": "https://pi-mcp.deepvinci.tech/api/v1/mcp"
    }
  }
}
```

2. 需要连接账号时，运行：

```
opencode mcp auth pi
```

### WorkBuddy

请按当前 WorkBuddy 连接器指南添加 Pi 远程连接。

官方指南: https://www.workbuddy.ai/docs/zh/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Connector

1. 按当前 WorkBuddy 连接器指南保存远程 Pi 地址：https://pi-mcp.deepvinci.tech/api/v1/mcp

2. 凭证由 WorkBuddy 管理；客户端请求时，请由你本人在浏览器完成 OAuth。

### DeepSeek Harness (dsh)

当当前 dsh 版本支持所需 OAuth 流程时，请按其已文档化的远程 HTTP MCP 流程添加 Pi 远程连接。

官方指南: https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/mcp/mcp-client/README.zh.md

1. 按 dsh 已文档化的远程 HTTP MCP 方式保存此地址：https://pi-mcp.deepvinci.tech/api/v1/mcp

2. 凭证由 dsh 管理；当前 dsh 版本请求时，请由你本人在浏览器完成 OAuth。

### 其他客户端

请选择支持远程 Streamable HTTP MCP 和标准 OAuth 的客户端，再按其已文档化的流程添加 Pi 连接。

1. 按该客户端已文档化的流程保存 https://pi-mcp.deepvinci.tech/api/v1/mcp。

2. 按该客户端已文档化的步骤操作；凭证由客户端管理，并在请求时由你本人完成浏览器 OAuth。

## 设置 Pi MCP 连接

设置 Pi 分为两个清晰步骤：保存连接；在你选择使用 Pi 时再授权账号。保存端点即完成安装；工具调用、创建文档、生成和使用额度需要后续请求及其授权。客户端负责 OAuth、合格令牌刷新、工具发现、工具加载和凭证管理。

选择客户端并按其已文档化的远程 MCP 与 OAuth 流程操作。仅检查 `pi` 的本地连接名称和端点，凭证保持由客户端管理。它指向此准确端点时可复用；若指向其他位置，请保留它并选择其他本地名称，或询问用户使用哪个连接。

## 准备使用 Pi 时再授权

若客户端可不经授权保存，保存后即完成安装。若保存时需要 OAuth，请等待用户本人在浏览器注册或登录并批准访问。Pi 凭证由客户端管理；不要粘贴到配置、提示词、请求头或静态密钥字段。

保存连接即完成安装。若客户端在保存时需要 OAuth，请由用户本人在浏览器完成。工具调用仅在后续用户请求及其授权后开始。复用有效连接，或让客户端刷新合格访问令牌。

进行 OAuth 发现时，先读取 `WWW-Authenticate` 中的 `resource_metadata` 引用，再读取其 `authorization_servers`。从该 issuer 构造授权服务器的 well-known URL，而不是盲目使用 MCP 主机。这是发现规则，不是调用新服务的指令。

授权后，仅在 OAuth、发现或加载异常证据表明确有需要时，按客户端文档刷新连接、重新加载工具或重启会话。以客户端实际发现的工具为准。用户请求只读验证时，可调用一次 `pi_list_themes`；成功后，在后续获得授权的请求中使用已发现的工具。仅在获得创建授权的请求中使用 `pi_create_document`。

## 安全使用 Pi

- 对于新的生成请求，只创建一次，再用 `pi_get_task` 查询该原任务并打开交付结果。用户明确请求创建即授权该次生成使用正常可用额度；不要再次要求生成或消费确认。新演示文稿默认使用 `link_readonly`：任何获得交付链接的人都可以阅读。用户要求私有时，显式使用 `owner_only`。披露的分享 scope 获得授权后，不要在每次生成时重复请求分享确认。旧令牌缺少 `pi:documents:share` 时，应让宿主为新的默认链接生成请求该权限；绝不能静默降级为私有。仅保存连接、批准 OAuth 或 Agent 自行调用工具都不构成生成授权。`pi_get_status` 和 `pi_list_themes` 是可选只读工具，并非创建前置条件。没有 `pi:account:read` 的旧令牌仍可按原 scope 使用原五个工具。

- 从想法、准备好的内容或宿主整理的文本创建；宿主会将附件整理为可用文本，Pi 不承诺直接读取任意文件。主题和页数均可省略：省略时由 Pi 选择默认值，显式支持值优先。

- `pi_get_task` 查询已有任务。`pi_get_outline` 读取已保存大纲。`pi_update_outline` 在请求时调整已保存大纲；它不承诺自动改写已完成的演示文稿。

## 主题选择与语义推荐

- 浏览主题是可选步骤。用户给出视觉或模板偏好并希望获得推荐时，使用 `preferences.query`（1-300 个字符）调用 `pi_list_themes`，比较返回的名称和预览，并使用真实 `theme_ref`。尊重用户明确选择的主题；未提供主题时，让 Pi 选择可见默认主题，不要编造引用。

- 语义搜索使用 `offset=0`，从有界搜索中最多返回 10 个可见候选。候选不保证匹配。应说明 `no_match`、不可用预览、不适合的候选或推荐失败；仅在用户授权范围内使用替代方案。它不创建文档或任务，但可能产生 embedding 提供商成本。不要自动重试或分页语义搜索。较旧部署可能不支持 `preferences.query`；应报告该限制，而不是声称已匹配。

## 账号和工作空间连续性

- 首次使用时，在首次成功的 `pi_get_status` 或 `pi_list_themes` 结果中内部保留非凭证 `auth_context`。文本 JSON 和 structuredContent 工具结果均包含相同的 `auth_context`；后续调用仅传入该原始值作为 `expected_auth_context`。不要要求用户查看摘要。刷新或登录后不要静默替换它。若返回 `auth_context_changed`，停止并要求确认账号和工作空间。若客户端不能使用此工具 schema，则无法保证身份安全恢复。不要猜测参数或声称可自动恢复。

## 额度、恢复与未知结果

- 用户请求创建演示文稿，即明确授权该次生成使用正常可用额度。账户余额或准入结果不是最终价格。服务不支持时，不要承诺最高价格、购买积分、充值或再次请求同一授权。新演示文稿默认使用 `link_readonly`，任何获得交付链接的人都可以阅读；私有交付须显式使用 `owner_only`。披露的 `pi:documents:share` 授权覆盖该默认行为，无需逐次重新确认。当前令牌缺少该权限时，应通过宿主请求缺失权限，不得静默更改访问范围。

- 若任务处于 `awaiting_credits`，保留并查询该原任务。启用自动恢复时（execute 和 recovery 均启用），充值可能自动恢复它；这不保证调度器正在运行。停止轮询不等于取消。写入结果未知时，仅核对原任务或幂等键。不要创建替代任务、再次提交操作、重试创建或更改幂等键。503 是服务失败：不要循环 OAuth 登录。

- 将非终态任务视为等待服务给出的 `poll_after_ms` 延迟。若它为 `0`、已停止、处于人工复核或受预算限制，不要忙轮询、推断已完成或提交替代任务。仅在服务或用户指示下一次读取时查询原任务。

- 保存连接后，可在后续获得授权的 Pi 请求中使用；客户端负责 OAuth 和工具流程。

## 告诉助手你希望 Pi 做什么

- 请只查询适合商务演示的主题，不生成演示文稿。

- 创建一份中文《泰坦尼克号》演示稿，约 8 页，仅自己可查看。我授权本次使用正常可用额度生成；不要充值，也不要重复生成。

- 查询刚才提到的 Pi 任务，不创建新任务或演示文稿。

## 常见问题与完整指南

- 账号与额度：使用客户端标准 OAuth，凭证由客户端管理。可先查询账户状态、主题和任务。自然语言主题推荐可能产生 embedding 提供商成本。余额或准入结果不是最终价格，最终计费以实际执行为准。创建仅在你明确授权后使用正常可用额度，绝不自动充值。

- 使用工具时，请按客户端的 OAuth、刷新、发现和加载流程操作。出现登录、发现或加载问题时，使用客户端已文档化的连接刷新、工具重载或新建会话流程；不要按名称前缀推断工具。

- 结果不明或等待额度时：先查询原任务或幂等键，不要重建或重复提交。开启自动恢复时，充值可能恢复任务；停止轮询不等于取消。