pi-codex-native-search

把 Codex Responses API 的服务端原生 web_search hosted tool接入 pi。搜索由 Codex/OpenAI 服务端执行，不需要 Tavily、Exa 或额外的搜索 API Key；它复用 pi 当前的 openai-codex 登录。

功能

• 只为 openai-codex-responses 请求注入官方 {"type":"web_search"} 工具
• 支持 live、cached、indexed 和 disabled 四种模式
• 支持搜索上下文大小及文本/图片搜索配置
• 保留 pi 已有的 function tools，并去重在本扩展之前已注入的 web search hosted tool
• 可用 /web-search 在当前运行时切换模式；流式响应期间输入命令会等待当前运行结束
• 非 Codex 模型不会收到工具或额外提示词

安装

从 npm 安装：

pi install npm:pi-codex-native-search

临时试用而不写入设置：

pi -e npm:pi-codex-native-search

项目级安装：

pi install -l npm:pi-codex-native-search

从源码开发或试用：

git clone https://github.com/xoralis/pi-codex-native-search.git
cd pi-codex-native-search
npm install
pi -e .

然后在 pi 中通过 /login 登录 openai-codex，并选择使用 openai-codex-responses API 的 Codex 模型。

使用

默认开启 live 搜索。直接提出需要实时信息的问题即可，例如：

搜索 OpenAI 今天发布的 Codex 更新，引用官方来源并总结关键变化。

运行时命令：

/web-search status
/web-search live
/web-search cached
/web-search indexed
/web-search disabled

启动时也可以覆盖模式：

pi -e . --codex-web-search cached

模式含义

模式	发送给 Codex 的字段	含义
live	external_web_access: true	允许实时互联网访问
cached	external_web_access: false	只使用搜索缓存/索引
indexed	external_web_access: true, indexed_web_access: true	实时访问，但限制为已索引页面
disabled	不注入工具	关闭扩展提供的搜索

环境变量

环境变量在扩展加载时读取；CLI 参数和 /web-search 只覆盖 mode，不会清除上下文大小或内容类型配置。

变量	可选值/格式	默认值
PI_CODEX_WEB_SEARCH_MODE	live, cached, indexed, disabled	live
PI_CODEX_WEB_SEARCH_CONTEXT_SIZE	low, medium, high	由 Codex 决定
PI_CODEX_WEB_SEARCH_CONTENT_TYPES	text 或 text,image	由 Codex 模型决定

PowerShell 示例：

$env:PI_CODEX_WEB_SEARCH_MODE = "live"
$env:PI_CODEX_WEB_SEARCH_CONTEXT_SIZE = "high"
pi -e .

图片搜索能力取决于当前 Codex 模型；如果上游模型不支持，请不要设置 image。

工作原理

扩展使用 pi 的 before_provider_request 生命周期事件，在 pi 已构造好的 Codex Responses payload 中加入：

{
  "type": "web_search",
  "external_web_access": true
}

可选配置会映射为 Codex 当前使用的 search_context_size、search_content_types 和 indexed_web_access 字段。扩展不会发送域名过滤或地理位置信息。工具由提供商托管，因此它不会像 pi 本地工具一样执行第二次客户端 tool loop。

扩展还会为 Codex 模型追加简短提示，要求只在需要外部/实时信息时搜索，并在答案中给出来源 URL。

限制

• 仅支持 model.api === "openai-codex-responses"；普通 openai-responses、Chat Completions 和其他提供商不会被修改。
• pi 0.82.x 的 Responses 流解析器会忽略 web_search_call 状态事件，因此搜索通常不会显示成独立的 pi 工具行；最终答案仍由同一次 Codex 响应返回。
• pi 按加载顺序串联 before_provider_request。本扩展会去重此前已有的 hosted search；若更晚加载的其他扩展再次注入同类工具，仍可能产生重复项，应只启用一个注入扩展或把本扩展放在最后。
• 可用性、搜索范围、速率限制和计费由 Codex/OpenAI 账户及所选模型决定。
• 搜索查询会发送给 Codex/OpenAI。项目本地扩展仍具有 pi 扩展的完整进程权限，请只从可信来源安装。

开发

npm install
npm run verify
npm pack --dry-run

npm run verify 会执行 TypeScript 检查、全部测试以及 pi 扩展加载烟雾测试。测试覆盖环境配置解析、官方 wire shape、payload 不可变注入、hosted tool 去重、模型隔离、CLI 覆盖和运行时命令。

发布维护

首次本地发布

先推送本仓库，确保 .github/workflows/publish.yml 已存在于 GitHub。然后在本地交互登录 npm 并创建 package：

npm login --registry=https://registry.npmjs.org/
npm whoami --registry=https://registry.npmjs.org/
npm publish --access public --registry=https://registry.npmjs.org/

发布 0.1.0 后，在 npm package 的 Settings → Trusted Publisher 中配置：

配置项	值
Provider	GitHub Actions
Organization or user	xoralis
Repository	pi-codex-native-search
Workflow filename	publish.yml
Environment	留空
Allowed actions	npm publish

GitHub Actions 后续通过 OIDC 发布，无需在 GitHub 保存 NPM_TOKEN，也无需提交包含 token 的 .npmrc。可以再为 v0.1.0 创建 GitHub Release；工作流检测到该版本已存在时会跳过重复发布。

后续版本

1. 更新版本并推送提交和 tag：

   npm version patch
   git push origin main --follow-tags
   

2. 在 GitHub 为对应 tag（例如 v0.1.1）发布 Release。

3. .github/workflows/publish.yml 会校验 tag 与 package.json 版本、运行验证，并通过 npm Trusted Publishing/OIDC 发布。

稳定版本发布到 npm latest dist-tag；GitHub prerelease 或带 SemVer 预发布后缀的版本发布到 next，不会覆盖普通安装使用的稳定版本。发布工作流具有幂等检查：如果该版本已经存在于 npm，则验证后跳过重复发布。