Pi Codex Search

为 Pi 提供 Codex 风格的远程网络搜索。插件可以使用自身保存的 OpenAI-compatible/Sub2API 连接信息直接调用 /v1/alpha/search，也可以复用 Pi 的 官方 openai-codex 登录。

本项目从 @fadouse/pi-web@0.5.0 精简而来。可复现的上游来源和校验值见 ORIGIN.md。

功能范围

插件只注册一个工具 web_search，保留 Codex 远程搜索的完整命令面：

• search_query、image_query
• open、click、find、screenshot
• finance、weather、sports、time

它不包含 web_fetch、本地 HTTP 抓取、浏览器自动化、HTML 清洗、PDF/Office/EPUB 解析、Exa 或本地二次总结。其他本地能力继续使用 Pi 自带工具或独立插件。

安装

发布到 npm 后：

pi install npm:pi-codex-search-remote

从当前源码目录测试：

pi install /absolute/path/to/pi-codex-search

需要 Node.js 22.19 或更高版本。

npm 上的无 scope 包名 pi-codex-search 已被其他作者占用，因此本项目当前使用 pi-codex-search-remote。如果你有 npm scope，可以在发布前改为 @your-scope/pi-codex-search。

Sub2API 配置

运行以下命令，选择 openai-compatible，并依次填写中转站 baseUrl、API key 和 远程模型 ID。这里的模型 ID 直接发送给中转站，不要求出现在 Pi 的 /model 列表中。

/codex-search-config

全局配置保存在 ~/.pi/agent/pi-codex-search.json：

{
  "provider": "openai-compatible",
  "baseUrl": "https://your-sub2api.example/v1",
  "apiKey": "sk-...",
  "model": "gpt-5.6-luna",
  "mode": "live",
  "search_context_size": "medium",
  "max_output_tokens": 10000,
  "timeout_ms": 300000
}

Pi 的扩展输入框不是密码框，因此填写 API key 时字符可见。配置文件权限会设置为 0600。/codex-search-config show 会把 key 显示为 [configured]，但文件本身仍含明文凭据。建议把含 key 的配置保存为全局配置；若使用 可信项目的 .pi/pi-codex-search.json，不要提交到版本库。配置优先级为：

环境变量 > 可信项目配置 > 全局配置

openai-compatible 不读取 Pi 的 models.json、provider 登录状态或 OPENAI_API_KEY。对于上述配置，实际搜索地址为：

https://your-sub2api.example/v1/alpha/search

因此能否成功搜索取决于中转站是否真正支持该接口、模型和请求体，而不只是普通的 Responses API。

检查当前配置和路径：

/codex-search-config show
/codex-search-config paths

手动修改配置后运行 /reload。

OpenAI Codex 登录

也可以不使用 Sub2API，改用 Pi 的 openai-codex provider：

1. 在 Pi 中运行 /login 并选择 OpenAI Codex。
2. 在 /codex-search-config 中选择 openai-codex 和已安装模型。

插件会从 Pi 解析出的 OAuth 认证中取得访问令牌和 ChatGPT account ID，并根据模型 baseUrl 选择 /codex/alpha/search 路径。openai-codex 不接受插件配置中的 baseUrl 或 apiKey，也不需要改名。

从 0.1.0 迁移

旧版 provider: "openai" 会明确报迁移错误，因为它容易与 Pi 的内置 OpenAI provider 混淆。升级后重新运行 /codex-search-config，选择 openai-compatible 并填写中转站连接信息。旧的 openai-codex 配置无需修改。

配置字段

字段	含义	默认值
provider	openai-compatible 或 openai-codex	必填
baseUrl	中转站的 API 根地址；仅 openai-compatible	该模式必填
apiKey	中转站 API key；仅 openai-compatible	该模式必填
model	中转模型 ID，或 Pi 中已安装的 Codex 模型 ID	必填
mode	live、cached、indexed 或 disabled	live
search_context_size	low、medium 或 high	provider 默认
allowed_domains	最多 100 个域名	不限制
user_location	country/region/city/timezone	未设置
max_output_tokens	1 到 50000	10000
timeout_ms	1000 到 600000	300000

对应环境变量使用 PI_CODEX_SEARCH_ 前缀，例如：

export PI_CODEX_SEARCH_PROVIDER=openai-compatible
export PI_CODEX_SEARCH_BASE_URL=https://your-sub2api.example/v1
export PI_CODEX_SEARCH_API_KEY=sk-...
export PI_CODEX_SEARCH_MODEL=gpt-5.6-luna
export PI_CODEX_SEARCH_MODE=live
export PI_CODEX_SEARCH_ALLOWED_DOMAINS=github.com,openai.com

搜索 artifact

每次成功搜索会在以下目录保存独立快照：

~/.pi/agent/cache/pi-codex-search/<session>/ws_<id>/
├── report.md
├── raw-search.txt
└── metadata.json

• report.md：带永久“不可信网页内容”声明的完整报告。
• raw-search.txt：中转站返回的原始文本。
• metadata.json：query、provider/model、引用 ID、字节数和 SHA-256。

工具结果会返回 reportPath、rawSearchPath 和 metadataPath。文件权限为 0600， 目录权限为 0700。中转站 HTTP 响应最多读取 32 MiB，单次搜索 artifact 上限为 64 MiB；默认保留七天，所有会话合计最多占用 256 MiB，清理时优先删除最旧 artifact。

较早用户轮次中的搜索正文会从活跃模型上下文中替换为包含 report_path 的短回执， 磁盘快照和 Pi 会话记录保持不变。需要时让 Pi 用内置 read 读取该路径即可。

安全边界

• 每次工具调用只向所选模型解析出的 /alpha/search 地址发送一次 POST；插件不自动 重试，以免中转站重复计费或重复执行有状态操作。
• 插件不连接搜索结果 URL，不执行网页 JavaScript，不启动浏览器或外部程序。
• 搜索返回内容会带有“untrusted web search results”标记后进入模型上下文；网页内容 仍可能包含 prompt injection。该标记和工具提示用于要求模型把它当证据而非指令， 但不构成内容净化或绝对隔离。
• 为保持连续搜索和页面引用能力，请求会包含当前用户消息、前一个用户消息，以及两者 之间最多约 1000 token 的 assistant 文本。系统提示、工具结果和其他会话记录不会被 加入。使用 Sub2API 时，这些有限近期对话会发送给中转站；不要在相关消息中放入不愿 交给中转站的代码、凭据或内部信息。
• 插件不主动读取工作区、SSH 目录或其他用户文件。除上述 Pi 提供的有限近期消息外， 它只读取自身 prompt/config、模型信息和本插件创建的搜索 artifact。
• 与所有 Pi 扩展一样，安装后的代码在 Pi 进程权限下运行。发布前应审阅源码及 npm pack --dry-run 的文件列表。

开发和发布

npm install
npm run check
npm pack --dry-run

发布前确认 npm 包名和账户权限，然后：

npm publish --access public

当前版本没有生产依赖；Pi 相关包均为 peer dependencies。完整目标范围见 SPEC.md。

License

MIT。保留的上游版权声明见 LICENSE。