pi-session-header

English

将 Pi 当前会话的 Session ID 自动注入 LLM Provider 的 HTTP 请求头。 上游网关可以据此实现路由、会话亲和和缓存复用；扩展只负责提供标识。

x-pi-session-id: <current-pi-session-id>

兼容范围

• 目标支持 Pi 0.85.0 及之后版本，使用官方 before_provider_headers 事件。
• 对 Pi 0.85.0、1.4.0 做类型检查；0.85.0、1.0.0、1.4.0 的 SDK 和真实 CLI 测试均已通过，CI 覆盖这三个版本。 后续 Pi 版本的兼容性取决于该事件是否继续支持原地修改请求头。
• Node.js 22.19+，与 Pi 要求一致。无运行时 npm 依赖，无需编译。
• 默认对所有调用官方 HTTP 请求头钩子的 Provider 生效，不按名称筛选。 绕过钩子的自定义传输不在覆盖范围内；WebSocket 消息及非 HTTP 传输不处理。
• 本地 HTTP 测试覆盖 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages、 Google Generative AI，以及工具调用后的连续请求；其他 Provider 未逐一连接真实服务验证。

安装和管理

从 npm 安装：

pi install npm:pi-session-header
pi install npm:[email protected]

源码推送后可从 Git 安装；固定标签需先创建对应 tag：

pi install git:github.com/or-less/pi-session-header
pi install git:github.com/or-less/[email protected]

内网仓库也可采用 git:git.example.com/team/pi-session-header，或 SSH 地址 ssh://[email protected]/team/pi-session-header.git。认证由 Git 管理。

默认写入用户全局配置，添加 -l 则写入当前项目。安装或修改后重启 Pi 或运行 /reload。

pi list
pi update npm:pi-session-header
pi remove npm:pi-session-header

Git 安装时，将更新、卸载命令中的来源换成对应 Git 来源。固定版本或标签不会自动升级； 需移除旧来源，再安装新的固定版本。不同 Pi 版本中裸 pi update 的含义有变化， 建议始终指定要更新的来源。

环境变量

启动 Pi 前配置。扩展加载时读取变量；修改启动终端的环境后需重新启动 Pi。

| 变量 | 默认值 | 说明 | |---|---|---| | PI_SESSION_HEADER_NAME | x-pi-session-id | 自定义请求头名称 | | PI_SESSION_HEADER_ENABLED | true | 是否启用注入 | | PI_SESSION_HEADER_DEBUG | false | 是否向 stderr 输出脱敏调试日志 |

布尔值支持 true/false、1/0、yes/no、on/off，忽略大小写及前后空白。 其他值视为配置错误。Header 名称必须符合 HTTP token 规范，不接受空白，统一转为小写。

PI_SESSION_HEADER_NAME=x-custom-session-id pi
PI_SESSION_HEADER_ENABLED=false pi
PI_SESSION_HEADER_DEBUG=true pi

Header 名称应根据上游网关的要求设置，不能假设网关识别 x-pi-session-id。 本版始终覆盖全部 Provider，暂不提供可选的 Provider 白名单。

禁止将认证头和传输控制头用作 Session Header，包括 Authorization、 Proxy-Authorization、常见 API Key 头、Cookie、Host、Content-Type、 Content-Length 等。配置无效时输出明确提示并停用注入，Pi 仍可继续运行。 调试日志不输出 Session ID、凭据、Prompt、请求正文或响应。

会话行为

每次钩子触发时读取 ctx.sessionManager.getSessionId()，不生成、不缓存 Session ID。

| 操作 | ID 行为 | |---|---| | 连续对话、工具调用 | 保持一致 | | 恢复历史会话 | 沿用原 ID | | 上下文压缩、切换模型或 Provider、/tree 导航 | 保持一致 | | 新建会话、/clone、/fork、CLI --fork | 使用 Pi 生成的新 ID | | 缺少 ID 或无法作为 HTTP Header 值 | 跳过注入 |

只添加或替换配置指定的 Header，同时处理其不同大小写形式。 保留其他 Header，不改请求正文或响应。Provider 内部重试可能直接复用请求头， 不再次触发钩子。Pi 的打印模式内部仍使用 HTTP 流式请求，扩展不改变该机制。

本地开发和验证

npm ci --ignore-scripts
npm run check
npm pack --dry-run
pi -e ./extensions/session-header.ts

也可用 pi install /absolute/path/to/pi-session-header 持久安装本地包。 Pi 直接加载 manifest 中声明的 TypeScript 入口，无需构建。

• npm run typecheck：对当前 SDK 和最低兼容 SDK 检查类型。
• npm test：配置校验、Header 保留、日志脱敏，以及真实 SDK 的会话生命周期。
• npm run test:e2e：启动本地 HTTP 接收服务，分别运行真实 Pi 0.85.0 和当前版本 CLI； 使用隔离的配置和会话目录，验证注入、恢复、分叉、跨 Provider、工具调用和本地安装流程。

端到端测试需要本地监听端口和启动子进程的权限，不需要真实 Provider 凭据， 也不会产生付费模型请求。 具体版本、验证结果和测试依赖的审计说明见源码仓库的 VALIDATION.md。

发布

仓库：or-less/pi-session-header。 使用 MIT License，变更见 CHANGELOG。

发布前运行 npm view pi-session-header 检查名称和所有权，更新版本与变更记录， 执行 npm run check、npm pack --dry-run，检查包内是否包含私有文件。 npm 返回 404 仅说明当前未发布，不能预留名称，也不保证当前账号有发布权限。

发布工作流仅允许手动触发。先为该仓库的 publish.yml 配置 npm Trusted Publishing， 并在 GitHub 建立带必需审核人的 npm environment。推送与包版本一致的 v<版本号> 标签后，在该标签上手动运行工作流。流程校验版本和标签、运行检查， 再携带 provenance 发布。获得发布授权后，也可在本地执行：

npm publish --access public

禁止在源码中保存发布凭据。

官方参考：Pi 0.85.0 扩展 API、 Pi 包规范。