Pi 兼容性 — 主机适配与升级移除门禁

责任¶

本清单用于主机代码的升级检查，以补偿缺失的 pi API、pi 缺陷或打包约束。pi 仍然是引擎和状态所有者。模块规格说明拥有详细理由；本索引记录升级必须重新检查的内容，以及哪些条件可以让我们删除该适配。已安装版本仅来自根依赖目录，不在此文件中再次固定版本。

上次复检¶

以下每个 MCP 条目均已对照已安装目录版本重新检查并予以保留：公开导出、内置 MCP 配置/写入器代码、openUrl、关停顺序与启动分发，以及临时 structuredContent 均未发生变化。那次升级将 structuredContent 扩展为任意 JSON 值，在连接时不再枚举资源（状态措辞 connected · N tools · resources），取消 OAuth 刷新期间被放弃的请求，并新增了 reachesTools；状态解析器和结果摘要测试覆盖了这两个可见变化。

升级契约¶

每次 pi 升级都会针对已安装包的导出与实现检查每个条目，而不仅仅是发布说明或上游 issue 的状态。升级的验证摘要应说明被删除的适配、有证据保留的适配或发生变更的适配，以及受影响且已运行的测试。新增的规避方案需要在此添加条目，并在其所属规格说明中写明理由；删除规避方案时，需同时删除该规避方案及其条目。对等性失败是漂移的证据，而不是削弱测试的理由。

公开 SDK 替换必须保留会话隔离、取消、项目信任、持久化记录以及编译/桌面行为，之后才能删除主机实现。在生产环境导入私有 dist 路径不算替换；此类导入仍仅限用于对等性测试。

MCP 适配¶

配置加载器与写入器¶

所有者： [[submodule-server-agent-mcp]]、agent/mcp/config.ts 和 writers.ts。 pi 的公开 loadConfig 钩子会整体替换其加载器；其加载器、验证器和写入器并非公开导出。主机移植这些文件语义，以应用项目策略并执行安全的多客户端写入。删除门槛： 公开的加载器/验证器/写入器接口需保留条目来源，并允许在项目覆盖合并之前进行准入。对照已安装的 core/mcp-servers 和 extensions/mcp/config 验证移植；运行 agent/mcp/config.test.ts 和 host/mcp.test.ts。主机隔离、过期写入检查和私有策略仍是主机义务。

运行时状态、管理与登录结果¶

所有者： [[submodule-server-agent]] 的 mcpSessions.ts / mcpSignIn.ts，以及 [[submodule-server-agent-mcp]] 的 status.ts / log.ts。 pi 通过 /mcp 和通知暴露管理能力，而非类型化控制器。主机捕获这些命令、解析状态和结果文本、读取 pi 的日志格式，并使用隔离的 pi 会话进行设置探测。OAuth 和凭据仍保留在 pi 中；授权 URL 可通过 pi 的公开 openUrl 回调获得，无需文本解析器。删除门槛： 公开的按会话状态读取/订阅、可取消的管理/认证 API，以及用于日志读取的结构化诊断信息。运行 mcpEngine.test.ts、mcpSignIn.test.ts 以及 MCP 状态/日志/脱敏测试；当 pi 措辞变化时，同时验证现代状态推送和旧版通知脱敏。

有序引擎关停与重载准入¶

所有者： [[submodule-server-agent]] 的会话生命周期，以及 [[submodule-server-agent-mcp]] 的 engine.ts。 AgentSession.dispose() 不会发出关停事件，pi 的顺序扩展关停可能被无关处理器阻塞。主机捕获内置 MCP 关停处理器，并在常规拆除/重载之前启动它，同时保留有界的主机退出路径。被捕获的关停与运行器发出的关停共享同一次按加载清理 Promise；重载会等待实际清理完成后再准入替换。pi 在等待关闭之前就清空其服务器列表，因此仅靠幂等性无法保证完成顺序。主机还会在关闭后守护实际的 MCP 启动/变更回调：beforeSessionStart 先于整个异步分发执行，单靠它无法阻止迟到的启动。删除门槛： 一个公开生命周期，能够独立于无关处理器关闭 MCP，在重复关停时加入同一次实际清理，仅在清理完成后准入替换，并且即使先前处理器在释放后恢复执行也能阻止启动。重新检查完成顺序和 AgentSession.reload 钩子，而不只是幂等性；运行 sessionShutdown.test.ts、reloadGate.test.ts 以及 MCP 删除/重载/进程生命周期回归测试，包括一个顽固的旧 PID 和一个通过异步 resources_discover 在关闭期间暂停的启动分发。 AgentSessionRuntime.dispose() 本身并不能证明这些主机义务已消失。

未打包 codemode 时的暴露¶

所有者： [[submodule-server-agent-mcp]] 的 normalizeExposureForHost 和工具搜索激活。 文件配置的 codemode 暴露会变为 deferred；已注册服务器仍可通过 tool_search 访问。删除门槛： 在 CLI 和桌面端随 pi 一起发布 codemode worker/WASM，然后无需规范化即可保留原生暴露。运行配置/暴露测试和共享工件探测；仅凭公开工厂可用性并不能确立打包支持。

持久化展示细节¶

所有者： [[submodule-server-agent-mcp]] 的 results.ts，以及 [[submodule-web-chat]]。 pi 的原始 structuredContent 会到达钩子，但不会保留在最终定稿的转录消息中。主机存储有界、无 base64 的展示细节，使实时卡片与恢复后的卡片保持一致。删除门槛： 来自 pi 的等效有界持久化表示。重新检查结果形状和完整输出路径；运行 mcp/results.test.ts、mcpEngine.test.ts、web MCP 卡片测试和 e2e/mcp-tool-cards.spec.ts。绝不要仅仅为了删除适配器而持久化完整原始结果。

其他对 pi 敏感的主机接缝¶

• 仅图像的队列输入 — [[submodule-server-agent]]、队列投影。宿主补偿 pi 的仅文本已投递消息移除（上游 #8612），并保留会因破坏性队列 API 而丢失的图像内容。当已安装的实现原生处理该情况时，移除相应的变通方案；验证队列/图像回归，而不只是 issue 状态。
• 捆绑扩展加载与图像处理 — [[submodule-server-agent]]、[[module-cli]]、[[module-desktop]]。强制的 Jiti 转换、虚拟模块标识、静态提供者注册，以及图像缩放覆盖桥接资源，都是单文件工件无法发现或加载的。仅当 pi 提供等效的工件接缝时，才替换它们；运行 check:seams 和相关二进制/桌面工件探针，包括扩展值导入和图像。
• 无头主题 — [[submodule-server-agent]]、plainTextTheme。Pi 的终端主题不会在 SDK 会话创建时初始化。当 pi 提供可用的非 TUI 主题契约时，移除该子类；对完整的继承表面运行 webUiContext.test.ts。
• 信任发现与排除重载 — [[submodule-server-agent]]、projectTrust.ts 和 extensions.ts。资源类型发现镜像了 pi 的私有、需要信任的路径，而排除加载器则保留可重载的扩展路径和内置排除项。若存在公共的发现/过滤 API，应优先使用；在每次更改资源加载时，运行 projectTrust.test.ts、extensions.test.ts 和 piRuntime.test.ts。
• 会话发现与提示模板解析 — [[submodule-server-history]]、[[submodule-server-templates]]、[[submodule-web-chat]]。在公共 API 无法服务其读取/编辑 UI 的地方，宿主镜像了 pi 的会话目录/JSONL 发现以及提示模板/frontmatter 规则。当公共发现/解析 API 满足这些需求时，优先使用它们；在此之前，在 history、template 和 composer 测试中保持对等覆盖。

非临时性 SDK 变通方案¶

项目服务器审批、私有项目/聊天覆盖、确认策略、凭据掩蔽、wire 能力检查和 React 呈现都是 ThinkRail 有意为之的行为。它们的属主是 [[submodule-server-agent-mcp]] 和 [[submodule-server-agent]]。pi 升级不会静默移除或削弱它们。复用上游策略是一个独立的兼容性/产品决策，而不是假设名称相似的 API 具有相同语义。