企业官网建设流程全解析

@oh-my-pi/pi-ai 变更日志深度解读：统一多 Provider 的 LLM 推理、认证与流式容错工程

【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi

导读

本文以 packages/ai/CHANGELOG.md（截至 v18.1.17 的完整变更记录）为核心骨架，系统拆解 oh-my-pi 项目中@oh-my-pi/pi-ai包的架构演进与工程实践。@oh-my-pi/pi-ai是 oh-my-pi 的统一 LLM 接入层（见 packages/ai/package.json 中的描述 "Unified LLM API with automatic model discovery and provider configuration"），承担着多 Provider 请求路由、OAuth/API-Key 认证、用量配额管理、思考推理控制、Prompt 缓存、流式工具调用解析与容错重试等核心职责。读完本文，你将掌握该包的能力边界、关键配置项与环境变量、底层调用链，以及如何利用其导出面为自定义 Provider 和宿主应用集成推理能力。

包定位：oh-my-pi 的 LLM 接入中枢

从 packages/ai/src/index.ts 的导出面可以清晰看到@oh-my-pi/pi-ai的功能切分：

• 统一流式入口：streamSimple/completeSimple（见 packages/ai/src/stream.ts），其中completeSimple内部复用streamSimple并聚合完整结果，streamSimple还支持通过completeSimple回调观察内部思考循环重试的每一次结果（18.1.0 新增）。
• Provider 实现：Anthropic、OpenAI Responses/Completions、OpenAI Codex、Amazon Bedrock、Google/Gemini CLI/Vertex、GitLab Duo、Kimi、Ollama、Synthetic、Cursor、Devin 等，集中在 packages/ai/src/providers/。
• 认证与凭据存储：auth-retry、auth-storage、auth-broker / auth-gateway 以及 SQLite 凭据存储（packages/ai/src/auth/sqlite-credential-store.ts）。
• 工具调用方言引擎：packages/ai/src/dialect/ 下内置 11 种方言（Anthropic、DeepSeek、Gemini、Gemma、GLM、Harmony、Hermes、Kimi、Pi-native、Qwen3、XML）。
• 用量上报：packages/ai/src/usage/ 下的各 Provider 用量适配器。

值得注意的架构细节：stream.ts中对重量级 Provider（AWS SDK、Google 库等）使用register-builtins动态导入包装，把 Provider SDK 排除在 CLI 启动解析图之外；而gitlab-duo/kimi/synthetic保持同步导入，因为它们导出必须在流式传输前同步调用的路由谓词（isGitLabDuoModel、isKimiModel、isSyntheticModel）。这是阅读 packages/ai/src/stream.ts 时可以借鉴的按需加载设计。

多 Provider 生态与模型驱动行为

变更日志显示，Provider 行为已从“按模型名匹配”演进为“由每个模型的兼容性、身份、思考、行为策略驱动”（18.1.0）。这一设计的运行时读取层在 packages/catalog/src/model-thinking.ts：getSupportedEfforts读取模型元数据中声明的思考档位，clampThinkingLevelForModel把请求的思考级别夹紧到模型支持的档位。

新增与改进的 Provider

• GitHub Copilot：多版本围绕身份问题持续修复——Chat 请求以copilot-chat身份、被拒后以 Copilot CLI（copilot-developer-cli）身份重试一次，COPILOT_INTEGRATION_ID预先固定Copilot-Integration-Id头；Enterprise 域名使用 GitHub 自有 OAuth 应用，公开 github.com 才使用 OpenCode 客户端（18.1.15/18.1.17）。
• Amazon Bedrock：支持 Converse guardrail 配置（provider 级标识/版本/trace）、OpenAI-schema 模型（gpt-5.xSKU）的reasoning.effort、Mantle 区域选择、SigV4/bearer 认证、requestMetadata成本归属（18.0.1/18.1.2/18.1.6/17.2.6）。
• Cursor：现代 exec 线协议（agent.proto）端到端建模，七类 Pi 工具帧（read/bash/edit/write/grep/glob等）均有类型化应答（17.2.0）。
• 其他：Muse Code 订阅（18.1.12）、ClinePass（18.1.0）、Devin 路由模型（18.1.0）、GitLab Duo Agent/Workflow（16.2.0）、Z.AI GLM Coding Plan、QwenCloud Token Plan、SiliconFlow、Novita、Sakana AI、Baseten、Umans、ai& 等。

推理思考控制

变更日志中“thinking”相关内容占比很高，体现了推理型模型时代的关键复杂度：

• 思考档位：18.4.0 将max提升为各 Provider 一等公民选项（Anthropic、Google、Bedrock、OpenAI），支持 32,768 token 最大预算；forceReasoningOff/disableReasoning（17.2.14）用于彻底关闭推理。
• 线格式映射：resolveWireModelId（packages/ai/src/stream.ts导入自 packages/catalog/src/model-thinking.ts）把会话思考档位映射到对应 SKU 的线格式模型 id——例如gemini-3.5-flash在 high 档位路由到gemini-3.5-flash-low；collapsed 的X/X-thinking配对模型在启用推理时切到思考 SKU（15.11.7/15.11.5）。
• 思考循环守卫：withThinkingLoopGuard（从withGeminiThinkingLoopGuard改名而来，17.3.0）覆盖 Gemini、DeepSeek、Grok 模型族；16.1.23 增加第三种“progress-lexicon stall”启发式，针对不断重排激励性措辞但不引入新词汇/技术引用的循环，官方在 537k 真实非 Gemini 思考块上校准（novelty floor 0.2 / run length 8 时零误报）。可通过PI_NO_THINKING_LOOP_GUARD=1关闭。
• 思考泄漏修复：流式场景下模型输出的```thinking、<think>等泄漏围栏会被拆分为结构化思考块（16.2.7/16.2.3）；16.3.8 修复 Gemini 思考摘要偶发泄漏围栏定界符；16.3.3 起 Claude Fable 推理回放改用纯文本而非<thinking>标签，避免跨模型切换后污染上下文。
• 推理回放：跨 API 切换（如 Z.AI Anthropic → Z.AI OpenAI、DeepSeek）时通过transformMessages保留先前推理为签名剥离的thinking/reasoning_content（16.1.19）；DeepSeek-family Responses 重放在思考模式被拒（400 The reasoning_text ... must be passed back）时，现在会合成非空占位符（18.1.7）。

Anthropic 思考签名兼容

• BedrockValidationException … thinking.signature: Field required被识别为“未签名思考块拒绝”：降级为文本、重试一次并记住该端点（18.1.3）。
• 自定义签名代理返回签名错误时自动以未签名块重试（16.3.3）。
• 18.1.2 新增anthropicPrefixMismatchBehavior配置项，处理无效 Anthropic 思考块的策略。

Prompt 缓存：多 Provider 的前缀复用工程

Prompt 缓存是降低推理成本的核心手段，变更日志中有大量相关条目：

• Anthropic OAuth 请求默认 1h 缓存保留（18.1.17 未发布版），匹配 Claude Code 订阅者行为，防止空闲期缓存过期；API-Key 请求同样默认 1h 保留（17.0.5，使用extended-cache-ttl-2025-04-11beta），可用PI_CACHE_RETENTION取值"short"/"none"覆盖。
• 历史降采样断点：每 15 个用户轮次设置一次历史降采样 Prompt 缓存断点，保证分支、回卷、会话恢复时缓存前缀稳定（18.1.17 未发布版）。
• 工具数组缓存断点：修复 Anthropic OAuth 请求遗漏工具数组缓存断点，工具定义现在可在会话重写和兄弟子代理间缓存（18.1.17 未发布版）。
• 滚动 5 分钟断点 + 空闲刷新（17.3.0）：保持 Prompt 前缀“温热”。
• 系统前缀稳定：17.2.5/16.2.x 优化缓存，避免易变的项目页脚细节（cwd、日期、工作区树）导致整个系统前缀失效；18.1.6 改进显式缓存断点以在消息尾部变化时保留可复用工具与系统提示。
• OpenAI 家族：16.3.15 为 OpenAI 系 chat completions 增加自动缓存亲和性头注入；17.1.1 增加 GPT-5.6 显式缓存控制（Responses 与 Chat Completions）；OpenAI Codex 的prompt_cache_key与禁用缓存保留逻辑在 17.2.3/17.1.5 修复。
• Kimi：会话稳定缓存键同时走两条传输（prompt_cache_key与metadata.user_id），cacheRetention: "none"时禁用自动亲和（17.1.5）。
• Ollama：/api/chatdone chunk 的prompt_eval_cached_count映射到cacheRead，input缩减为未缓存部分，使状态栏cache_turn/cache_hit段与缓存前缀审计报告真实命中率（18.1.17 未发布版）。

认证体系：OAuth、API-Key 与凭据轮换

登录与 OAuth 流

• 现代统一登录：17.1.4 起 OAuth 登录在凭据上盖authorizedAt时间戳，且每次刷新持久化都保留；ANTHROPIC_OAUTH_GRANT_TTL_MS用于计算 Anthropic 授权族 ~30 天后的重新登录截止点。
• 设备码/粘贴码流：xAI Grok OAuth 改用手动粘贴授权码（16.3.13），随后统一为设备码轮询（16.3.15）；OpenRouter 使用 OAuth PKCE 浏览器登录（18.0.5）。
• 自定义 Scheme 回调：18.1.9 为 macOS/Linux/Windows 增加可恢复的原生自定义 Scheme OAuth 回调，并提供手动兜底；17.2.0 起回调服务器提供GET /launch短链接（~30 字符）避免窄终端截断 OAuth 查询参数。
• IPv6 处理：localhost回调监听限制到 IPv4 回环（17.1.0），并在内核禁用 IPv6 时只监听 IPv4（17.3.8）；Google OAuth 回调主机从localhost切到127.0.0.1（16.0.7）。
• 环境变量与登录 Provider：CLINE_API_KEY（ClinePass）、ABLITERATION_API_KEY/ABLIT_KEY（18.1.5/login abliteration）、COREWEAVE_API_KEY/WANDB_API_KEY（16.1.23）、GITLAB_CLIENT_ID/GITLAB_REDIRECT_URI（15.12.4）、LITELLM_BASE_URL提示（16.0.5）等。

凭据轮换与错误分类

凭据轮换是保障多账号稳定性的关键，变更日志体现了精细的分级策略：

• 403 旋转：上游403 Forbidden（Anthropicpermission_error、Copilot 模型策略拒绝）现在像用量限制一样轮换兄弟凭据，被拒凭据软屏蔽 60s 且重新验证，不删除；所有兄弟尝试后才上抛原始 403（17.1.7）。
• 402 余额耗尽：Anthropic/OpenRouter 的402（"would exceed your available credits" / "Insufficient credits"）自动切换到兄弟账号（18.1.6）；16.3.x 将 402 与 "balance exhausted" 归类为持久用量限制。
• 使用量限制与退避：auth_credential_blocks（auth schema v5）持久化跨进程的按凭据屏蔽（16.3.6）；retry.usageReservePct（Reserve Margin）现在尊重 Fable/Mythos 周档用量（17.3.8）；AuthStorage.redeemResetCredit优先花费最早过期的已存重置额度（17.2.2）。
• 代理支持：PI_PROXY与PI_PROXY_<PROVIDER>全局代理（16.1.14），installGlobalProxyFetch()让 OAuth 令牌刷新、用量探测、模型发现都走代理（18.0.1）；NO_PROXY与回环/私网直连（18.0.1/16.1.14）。
• auth-broker：OMP_AUTH_BROKER_URL配置；快照缓存 stale-while-revalidate（18.0.1）；GET /v1/credentials/disabled与禁用凭据墓碑（17.1.4）；按客户端燃烧跟踪（POST /v1/usage/observed，10s 批量，5 分钟桶）（17.1.2）；OMP_AUTH_BROKER_ACCOUNT_POOL_FILE进程级 OAuth 账号池（17.1.0）。

流式容错：重试、看门狗与错误分类

可重放安全重试

• 18.0.5 将流式重试辅助函数从withEmptyCompletionRetry改名为withReplaySafeStreamRetry，并新增空完成与 Provider 错误的策略选项（Breaking Change）。
• 16.1.4 为空完成添加有界自动重试（OpenAI Completions、Responses、Anthropic Messages）：未流式输出任何内容且未计费输出 token 的良性终止，最多重试两次，指数退避遵循providerRetryWait；重试只在任何内容流式输出前发生。
• 18.0.2 修复[DONE]哨兵终止但缺失/置空finish_reason的流：现在作为干净停止收尾；真正的传输 EOF 才报不完整流错误。

流式看门狗

• Bun 原生 ~300s 预响应fetch超时被禁用，改为可配置的PI_STREAM_FIRST_EVENT_TIMEOUT_MS、PI_OPENAI_STREAM_IDLE_TIMEOUT_MS、compat.streamIdleTimeoutMs（15.13.0）。
• compat.streamIdleTimeoutMs可放宽或置 0 禁用事件间看门狗（17.2.4）；model.compat.streamIdleTimeoutMs针对惰性流 Provider（17.2.11）。
• Anthropicping心跳只在最近真实事件后的有界窗口（3 倍空闲超时）内延长看门狗，避免生成卡死时无限挂起（16.3.13）。

错误分类

• 用量限制模式：isUsageLimitError的USAGE_LIMIT_PATTERN增加 Antigravity "Individual quota reached"、quota.?reached等措辞（15.10.12）；中文配额耗尽/限流消息分类（17.2.11）。
• HTTP 413：区分 payload/媒体大小限制与上下文窗口溢出，避免错误的 token 压缩（18.0.4）。
• HTTP 429：Antigravity 结构化google.rpc.ErrorInfo原因分类，用 ≥5 分钟重试延迟区分可轮换配额窗口与瞬时限流（17.3.2）；并发请求上限与配额耗尽分开处理（17.2.9）。
• 空响应重试：Google 各面（公开、Vertex、Cloud Code Assist）通过hasMeaningfulGoogleContent分类空响应并重试至MAX_EMPTY_STREAM_RETRIES（15.12.4）。

工具调用：方言引擎与容错解析

11 种方言

16.0.0 将公开入口从@oh-my-pi/pi-ai/grammar改名为@oh-my-pi/pi-ai/dialect，支持 11 种方言：Anthropic、DeepSeek、Gemini、Gemma、GLM、Harmony、Hermes、Kimi、Pi-native、Qwen3、XML。核心 API（见 packages/ai/src/dialect/index.ts）：

• getDialectDefinition：按名获取方言实现；
• createInbandScanner：实例化方言专用扫描器（packages/ai/src/dialect/factory.ts）；
• renderToolCatalog/renderToolInventory/renderToolExamples：工具目录与文档渲染（packages/ai/src/dialect/inventory.ts）；
• wrapInbandToolStream：带工具调用解析的流式包装（packages/ai/src/dialect/owned-stream.ts）；
• encodeInbandToolHistory：方言格式历史编码（packages/ai/src/dialect/history.ts）。

工具示例渲染统一使用 Python 关键字参数语法（name(key="value")），消除模型特定方言参数（17.2.5）。

宽松 JSON 解析

16.1.10 以自研RelaxedJson替代外部 JSON 依赖与partial-json：接受单引号字符串、无引号键、尾随/游离逗号、//与/* */注释、PythonTrue/False/None、原始控制字符、非法转义、未转义撇号；同时拒绝 JS 特有NaN/Infinity，流式解析非抛错并回滚不完整尾部 token。16.1.10 的流式解析还防止非有限数值作为undefined/NaN泄漏。

Schema 校验与严格工具

• strict tools 降级：enforceStrictSchema拼接嵌套纯 union 进父级anyOf，避免无type分支被 OpenRouter 等严格校验器拒绝（15.11.0）；OpenAI-compat 非严格重试在识别Invalid tool parameters schema ...400 后持久化strictToolsDisabled（15.11.0）。
• 单工具隔离：单个 MCP 工具无法生成合法严格 schema 时，convertTools通过findStrictToolSchemaViolation只隔离该工具并告警，不拖垮整轮（16.0.2）。
• 宽松工具调用修复：transformMessages丢弃空/空白名称的toolCall块并按同一 assistant→tool-result 窗口配对结果（16.1.19）；validateToolArguments预校验解析双重 JSON 编码的字符串（16.0.4/16.0.1/16.1.9）。
• 布尔子 schema：true/false子 schema 在 Ollama/llama.cpp/vLLM 与 Google/Cloud Code Assist 上被重写为对象/联合形式（16.1.9/17.0.1/16.3.6）。

流式工具调用解析

• Codex Responses 流式function_call_arguments.delta现在按item_id键控路由，晚到的 delta 被丢弃而非污染兄弟调用（15.13.2）；Cursor 的args_text_delta累积快照按前缀剥离并合并McpArgs映射（15.13.2）；Cursor 流式解码按信封call_id保留打开块（17.2.0）。

用量与配额报告

• 统一入口：/usage、omp usage、TUI 状态栏、ACP/usage多端渲染；omp usage invalidate强制清缓存刷新（17.3.5/17.3.4）。
• 配额窗口：滚动 5 小时/周/月窗口；UsageWindow.resetLabel提供准确的动词（"tick in 12m"/"regen in 51m"，Synthetic 再生式窗口，17.0.9）；OMP_APP_NAME应用级用量归属（默认omp，18.0.7）。
• 各 Provider 用量适配器：Claude Extra Usage USD 行（17.1.0/17.1.1）、Cursor 个人月配额（17.2.11）、MiniMax Token Plan（17.1.4）、Muse Code 配额（18.1.12）、Z.AI 5h+周CREDIT_LIMIT窗口与plan: lite/pro/max档位（18.0.8）、OpenCode Go/Zen 会话标识（18.1.11）、Umans 加权用量（17.3.5）、SyntheticGET /v2/quotas（17.0.9）、Antigravity 按模型族分级屏蔽（15.10.12）。
• 用量历史：AuthStorage.listUsageHistory与 SQLite 持久化时间序列快照、sinceMs/provider过滤（15.11.5）；auth-brokerGET /v1/usage/history（17.1.2）。

开发者集成要点：导出面与破坏性变更

• 错误模块：@oh-my-pi/pi-ai/error公开结构化错误分类、Provider 特定 HTTP 错误类（ProviderHttpError及CodexApiError、AuthGatewayError、GoogleApiError、OllamaApiError、BedrockApiError、AnthropicApiError）、限流工具与可重试谓词（16.2.2/15.11.4）。
• Schema 工具：jsonSchemaToTypeScript渲染紧凑 TypeScript 签名，支持style: "harmony"（17.2.5）；@oh-my-pi/pi-ai/utils/schema提供findStrictToolSchemaViolation等（16.0.2）。
• 钩子：onPayload替换载荷在所有 Provider（含 Completions/Bedrock/Cursor）生效（17.3.8/16.0.1）；onModerationMetadata回调（15.11.4）。
• 破坏性变更提醒（升级时需注意）：17.2.10 移除zod与z/ZodType重导出，改用omptype的type()schema（Zod 风格写作经@oh-my-pi/omptype/zod保留）；17.2.7 以@oh-my-pi/omptype替换arktype；18.1.6 将claudeCodeSessionId/openAIRequestSessionId重命名为sessionId；16.2.0 将 JSON 修复/解析助手迁至@oh-my-pi/pi-utils；15.11.8 移除 Codex SSE 有状态路径（不再发送previous_response_iddelta 输入）。

版本节奏与维护建议

从变更日志可见@oh-my-pi/pi-ai保持高频迭代（v16.0 → v18.1 跨约三个月，含多个同版本号日期分段，如 18.1.5/18.1.6/18.1.7 均标注 2026-09-03）。实用建议：

• 升级前先扫描Breaking Changes小节（涉及导出重命名、依赖替换、传输路径移除），例如withReplaySafeStreamRetry、sessionId、@oh-my-pi/pi-ai/dialect等迁移点；
• 涉及自建网关/代理时，关注 18.0.1 的代理行为变更（installGlobalProxyFetch使 OAuth 刷新也走PI_PROXY）与 17.2.11 的ANTHROPIC_BASE_URL修复；
• 涉及多账号负载均衡时，理解 16.3.6 持久化凭据屏蔽、17.1.7 的 403 旋转与 16.1.18 的 OAuth 失败分类（裸 403/429/网络错误为瞬时，仅显式失效授权才拆除凭据）。

变更日志更早的条目归档于同文件的尾部说明（历史提交快照），当前文件覆盖自 v15.10 起的完整演进脉络，可作为阅读源码的导航地图。

【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi