synurex 2026.2.19-1

package/docs/zh-CN/concepts/usage-tracking.md

@@ -0,0 +1,42 @@
+---
+read_when:
+  - 你正在对接提供商使用量/配额界面
+  - 你需要解释使用量跟踪行为或认证要求
+summary: 使用量跟踪界面及凭据要求
+title: 使用量跟踪
+x-i18n:
+  generated_at: "2026-02-01T20:24:46Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 6f6ed2a70329b2a6206c327aa749a84fbfe979762caca5f0e7fb556f91631cbb
+  source_path: concepts/usage-tracking.md
+  workflow: 14
+---
+
+# 使用量跟踪
+
+## 功能简介
+
+- 直接从提供商的使用量端点拉取使用量/配额数据。
+- 不提供估算费用；仅展示提供商报告的时间窗口数据。
+
+## 展示位置
+
+- 聊天中的 `/status`：包含会话 token 数和估算费用的表情符号丰富的状态卡片（仅限 API 密钥）。当可用时，会显示**当前模型提供商**的使用量。
+- 聊天中的 `/usage off|tokens|full`：每次响应的使用量页脚（OAuth 仅显示 token 数）。
+- 聊天中的 `/usage cost`：从 Synurex 会话日志汇总的本地费用摘要。
+- CLI：`Synurex status --usage` 打印完整的按提供商分类的详细信息。
+- CLI：`Synurex channels list` 在提供商配置旁打印相同的使用量快照（使用 `--no-usage` 跳过）。
+- macOS 菜单栏：上下文菜单下的"使用量"部分（仅在可用时显示）。
+
+## 提供商及凭据
+
+- **Anthropic (Claude)**：认证配置中的 OAuth 令牌。
+- **GitHub Copilot**：认证配置中的 OAuth 令牌。
+- **Gemini CLI**：认证配置中的 OAuth 令牌。
+- **Antigravity**：认证配置中的 OAuth 令牌。
+- **OpenAI Codex**：认证配置中的 OAuth 令牌（存在时使用 accountId）。
+- **MiniMax**：API 密钥（编程计划密钥；`MINIMAX_CODE_PLAN_KEY` 或 `MINIMAX_API_KEY`）；使用 5 小时编程计划时间窗口。
+- **z.ai**：通过环境变量/配置/认证存储提供的 API 密钥。
+
+如果没有匹配的 OAuth/API 凭据，使用量信息将被隐藏。

package/docs/zh-CN/date-time.md

@@ -0,0 +1,129 @@
+---
+read_when:
+  - 你正在更改向模型或用户展示时间戳的方式
+  - 你正在调试消息或系统提示词输出中的时间格式问题
+summary: 信封、提示词、工具和连接器中的日期与时间处理
+title: 日期与时间
+x-i18n:
+  generated_at: "2026-02-01T20:24:52Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 753af5946a006215d6af2467fa478f3abb42b1dff027cf85d5dc4c7ba4b58d39
+  source_path: date-time.md
+  workflow: 14
+---
+
+# 日期与时间
+
+Synurex 默认使用**主机本地时间作为传输时间戳**，并且**仅在系统提示词中使用用户时区**。
+提供商时间戳会被保留，因此工具保持其原生语义（当前时间可通过 `session_status` 获取）。
+
+## 消息信封（默认为本地时间）
+
+入站消息会附带一个时间戳（分钟精度）：
+
+```
+[Provider ... 2026-01-05 16:26 PST] message text
+```
+
+此信封时间戳**默认为主机本地时间**，与提供商时区无关。
+
+你可以覆盖此行为：
+
+```json5
+{
+  agents: {
+    defaults: {
+      envelopeTimezone: "local", // "utc" | "local" | "user" | IANA 时区
+      envelopeTimestamp: "on", // "on" | "off"
+      envelopeElapsed: "on", // "on" | "off"
+    },
+  },
+}
+```
+
+- `envelopeTimezone: "utc"` 使用 UTC。
+- `envelopeTimezone: "local"` 使用主机时区。
+- `envelopeTimezone: "user"` 使用 `agents.defaults.userTimezone`（回退到主机时区）。
+- 使用显式 IANA 时区（例如 `"America/Chicago"`）指定固定时区。
+- `envelopeTimestamp: "off"` 从信封头中移除绝对时间戳。
+- `envelopeElapsed: "off"` 移除已用时间后缀（`+2m` 样式）。
+
+### 示例
+
+**本地时间（默认）：**
+
+```
+[WhatsApp +1555 2026-01-18 00:19 PST] hello
+```
+
+**用户时区：**
+
+```
+[WhatsApp +1555 2026-01-18 00:19 CST] hello
+```
+
+**启用已用时间：**
+
+```
+[WhatsApp +1555 +30s 2026-01-18T05:19Z] follow-up
+```
+
+## 系统提示词：当前日期与时间
+
+如果已知用户时区，系统提示词会包含一个专门的**当前日期与时间**部分，其中仅包含**时区**（不含时钟/时间格式），以保持提示词缓存的稳定性：
+
+```
+Time zone: America/Chicago
+```
+
+当智能体需要获取当前时间时，请使用 `session_status` 工具；状态卡中包含时间戳行。
+
+## 系统事件行（默认为本地时间）
+
+插入到智能体上下文中的排队系统事件会带有时间戳前缀，使用与消息信封相同的时区选择（默认：主机本地时间）。
+
+```
+System: [2026-01-12 12:19:17 PST] Model switched.
+```
+
+### 配置用户时区和格式
+
+```json5
+{
+  agents: {
+    defaults: {
+      userTimezone: "America/Chicago",
+      timeFormat: "auto", // auto | 12 | 24
+    },
+  },
+}
+```
+
+- `userTimezone` 设置提示词上下文中的**用户本地时区**。
+- `timeFormat` 控制提示词中的 **12 小时/24 小时显示格式**。`auto` 跟随操作系统偏好设置。
+
+## 时间格式检测（auto）
+
+当 `timeFormat: "auto"` 时，Synurex 会检查操作系统偏好设置（macOS/Windows），并回退到区域格式。检测到的值会**按进程缓存**，以避免重复的系统调用。
+
+## 工具载荷 + 连接器（原始提供商时间 + 标准化字段）
+
+渠道工具返回**提供商原生时间戳**，并添加标准化字段以保持一致性：
+
+- `timestampMs`：纪元毫秒数（UTC）
+- `timestampUtc`：ISO 8601 UTC 字符串
+
+原始提供商字段会被保留，不会丢失任何数据。
+
+- Slack：来自 API 的类纪元字符串
+- Discord：UTC ISO 时间戳
+- Telegram/WhatsApp：提供商特定的数字/ISO 时间戳
+
+如果需要本地时间，请使用已知时区在下游进行转换。
+
+## 相关文档
+
+- [系统提示词](/concepts/system-prompt)
+- [时区](/concepts/timezone)
+- [消息](/concepts/messages)

package/docs/zh-CN/debug/node-issue.md

@@ -0,0 +1,90 @@
+---
+read_when:
+  - 调试仅限 Node 的开发脚本或 watch 模式失败
+  - 排查 Synurex 中 tsx/esbuild 加载器崩溃问题
+summary: Node + tsx "__name is not a function" 崩溃说明及解决方法
+title: Node + tsx 崩溃
+x-i18n:
+  generated_at: "2026-02-01T20:24:52Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: f9e9bd2281508337a0696126b0db2d47a2d0f56de7a11872fbc0ac4689f9ad41
+  source_path: debug/node-issue.md
+  workflow: 14
+---
+
+# Node + tsx "\_\_name is not a function" 崩溃
+
+## 概述
+
+通过 Node 使用 `tsx` 运行 Synurex 时，启动阶段报错：
+
+```
+[Synurex] Failed to start CLI: TypeError: __name is not a function
+    at createSubsystemLogger (.../src/logging/subsystem.ts:203:25)
+    at .../src/agents/auth-profiles/constants.ts:25:20
+```
+
+此问题在开发脚本从 Bun 切换到 `tsx` 后出现（提交 `2871657e`，2026-01-06）。相同的运行路径在 Bun 下正常工作。
+
+## 环境
+
+- Node: v25.x（在 v25.3.0 上观察到）
+- tsx: 4.21.0
+- 操作系统: macOS（其他运行 Node 25 的平台也可能复现）
+
+## 复现步骤（仅 Node）
+
+```bash
+# 在仓库根目录
+node --version
+pnpm install
+node --import tsx src/entry.ts status
+```
+
+## 仓库内最小复现
+
+```bash
+node --import tsx scripts/repro/tsx-name-repro.ts
+```
+
+## Node 版本检查
+
+- Node 25.3.0：失败
+- Node 22.22.0（Homebrew `node@22`）：失败
+- Node 24：尚未安装，需要验证
+
+## 说明 / 假设
+
+- `tsx` 使用 esbuild 转换 TS/ESM。esbuild 的 `keepNames` 会生成一个 `__name` 辅助函数，并用 `__name(...)` 包裹函数定义。
+- 崩溃表明 `__name` 存在但在运行时不是函数，这意味着在 Node 25 的加载器路径中该辅助函数缺失或被覆盖。
+- 其他 esbuild 使用者也报告过类似的 `__name` 辅助函数缺失或被重写的问题。
+
+## 回归历史
+
+- `2871657e`（2026-01-06）：脚本从 Bun 改为 tsx，使 Bun 成为可选项。
+- 在此之前（Bun 路径），`Synurex status` 和 `gateway:watch` 均正常工作。
+
+## 解决方法
+
+- 开发脚本使用 Bun（当前临时回退方案）。
+- 使用 Node + tsc watch，然后运行编译产物：
+  ```bash
+  pnpm exec tsc --watch --preserveWatchOutput
+  node --watch Synurex.mjs status
+  ```
+- 已在本地确认：`pnpm exec tsc -p tsconfig.json` + `node Synurex.mjs status` 在 Node 25 上可正常运行。
+- 如果可能，在 TS 加载器中禁用 esbuild 的 keepNames（防止插入 `__name` 辅助函数）；tsx 目前不提供此配置项。
+- 在 Node LTS（22/24）上测试 `tsx`，确认该问题是否为 Node 25 特有。
+
+## 参考资料
+
+- https://opennext.js.org/cloudflare/howtos/keep_names
+- https://esbuild.github.io/api/#keep-names
+- https://github.com/evanw/esbuild/issues/1031
+
+## 后续步骤
+
+- 在 Node 22/24 上复现，确认是否为 Node 25 回归问题。
+- 测试 `tsx` nightly 版本，或在存在已知回归时固定到早期版本。
+- 如果在 Node LTS 上也能复现，则向上游提交包含 `__name` 堆栈跟踪的最小复现。

package/docs/zh-CN/diagnostics/flags.md

@@ -0,0 +1,98 @@
+---
+read_when:
+  - 你需要定向调试日志而不提高全局日志级别
+  - 你需要为支持人员捕获特定子系统的日志
+summary: 用于定向调试日志的诊断标志
+title: 诊断标志
+x-i18n:
+  generated_at: "2026-02-03T10:05:34Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: daf0eca0e6bd1cbc2c400b2e94e1698709a96b9cdba1a8cf00bd580a61829124
+  source_path: diagnostics/flags.md
+  workflow: 15
+---
+
+# 诊断标志
+
+诊断标志让你可以启用定向调试日志，而无需在所有地方开启详细日志。标志是可选启用的，除非子系统检查它们，否则不会生效。
+
+## 工作原理
+
+- 标志是字符串（不区分大小写）。
+- 你可以在配置中或通过环境变量覆盖来启用标志。
+- 支持通配符：
+  - `telegram.*` 匹配 `telegram.http`
+  - `*` 启用所有标志
+
+## 通过配置启用
+
+```json
+{
+  "diagnostics": {
+    "flags": ["telegram.http"]
+  }
+}
+```
+
+多个标志：
+
+```json
+{
+  "diagnostics": {
+    "flags": ["telegram.http", "gateway.*"]
+  }
+}
+```
+
+更改标志后重启 Gateway 网关。
+
+## 环境变量覆盖（一次性）
+
+```bash
+SYNUREX_DIAGNOSTICS=telegram.http,telegram.payload
+```
+
+禁用所有标志：
+
+```bash
+SYNUREX_DIAGNOSTICS=0
+```
+
+## 日志存储位置
+
+标志将日志输出到标准诊断日志文件。默认位置：
+
+```
+/tmp/Synurex/Synurex-YYYY-MM-DD.log
+```
+
+如果你设置了 `logging.file`，则使用该路径。日志为 JSONL 格式（每行一个 JSON 对象）。脱敏仍然根据 `logging.redactSensitive` 应用。
+
+## 提取日志
+
+选择最新的日志文件：
+
+```bash
+ls -t /tmp/Synurex/Synurex-*.log | head -n 1
+```
+
+过滤 Telegram HTTP 诊断：
+
+```bash
+rg "telegram http error" /tmp/Synurex/Synurex-*.log
+```
+
+或在复现时使用 tail：
+
+```bash
+tail -f /tmp/Synurex/Synurex-$(date +%F).log | rg "telegram http error"
+```
+
+对于远程 Gateway 网关，你也可以使用 `Synurex logs --follow`（参见 [/cli/logs](/cli/logs)）。
+
+## 注意事项
+
+- 如果 `logging.level` 设置为高于 `warn`，这些日志可能会被抑制。默认的 `info` 级别即可。
+- 标志可以安全地保持启用状态；它们只影响特定子系统的日志量。
+- 使用 [/logging](/logging) 更改日志目标、级别和脱敏设置。

package/docs/zh-CN/experiments/onboarding-config-protocol.md

@@ -0,0 +1,47 @@
+---
+read_when: Changing onboarding wizard steps or config schema endpoints
+summary: 新手引导向导和配置模式的 RPC 协议说明
+title: 新手引导和配置协议
+x-i18n:
+  generated_at: "2026-02-03T07:47:10Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 55163b3ee029c02476800cb616a054e5adfe97dae5bb72f2763dce0079851e06
+  source_path: experiments/onboarding-config-protocol.md
+  workflow: 15
+---
+
+# 新手引导 + 配置协议
+
+目的：CLI、macOS 应用和 Web UI 之间共享的新手引导 + 配置界面。
+
+## 组件
+
+- 向导引擎（共享会话 + 提示 + 新手引导状态）。
+- CLI 新手引导使用与 UI 客户端相同的向导流程。
+- Gateway 网关 RPC 公开向导 + 配置模式端点。
+- macOS 新手引导使用向导步骤模型。
+- Web UI 从 JSON Schema + UI 提示渲染配置表单。
+
+## Gateway 网关 RPC
+
+- `wizard.start` 参数：`{ mode?: "local"|"remote", workspace?: string }`
+- `wizard.next` 参数：`{ sessionId, answer?: { stepId, value? } }`
+- `wizard.cancel` 参数：`{ sessionId }`
+- `wizard.status` 参数：`{ sessionId }`
+- `config.schema` 参数：`{}`
+
+响应（结构）
+
+- 向导：`{ sessionId, done, step?, status?, error? }`
+- 配置模式：`{ schema, uiHints, version, generatedAt }`
+
+## UI 提示
+
+- `uiHints` 按路径键入；可选元数据（label/help/group/order/advanced/sensitive/placeholder）。
+- 敏感字段渲染为密码输入；无脱敏层。
+- 不支持的模式节点回退到原始 JSON 编辑器。
+
+## 注意
+
+- 本文档是跟踪新手引导/配置协议重构的唯一位置。

package/docs/zh-CN/experiments/plans/cron-add-hardening.md

@@ -0,0 +1,70 @@
+---
+last_updated: "2026-01-05"
+owner: Synurex
+status: complete
+summary: 加固 cron.add 输入处理，对齐 schema，改进 cron UI/智能体工具
+title: Cron Add 加固
+x-i18n:
+  generated_at: "2026-02-03T07:47:26Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: d7e469674bd9435b846757ea0d5dc8f174eaa8533917fc013b1ef4f82859496d
+  source_path: experiments/plans/cron-add-hardening.md
+  workflow: 15
+---
+
+# Cron Add 加固 & Schema 对齐
+
+## 背景
+
+最近的 Gateway 网关日志显示重复的 `cron.add` 失败，参数无效（缺少 `sessionTarget`、`wakeMode`、`payload`，以及格式错误的 `schedule`）。这表明至少有一个客户端（可能是智能体工具调用路径）正在发送包装的或部分指定的任务负载。另外，TypeScript 中的 cron 提供商枚举、Gateway 网关 schema、CLI 标志和 UI 表单类型之间存在漂移，加上 `cron.status` 的 UI 不匹配（期望 `jobCount` 而 Gateway 网关返回 `jobs`）。
+
+## 目标
+
+- 通过规范化常见的包装负载并推断缺失的 `kind` 字段来停止 `cron.add` INVALID_REQUEST 垃圾。
+- 在 Gateway 网关 schema、cron 类型、CLI 文档和 UI 表单之间对齐 cron 提供商列表。
+- 使智能体 cron 工具 schema 明确，以便 LLM 生成正确的任务负载。
+- 修复 Control UI cron 状态任务计数显示。
+- 添加测试以覆盖规范化和工具行为。
+
+## 非目标
+
+- 更改 cron 调度语义或任务执行行为。
+- 添加新的调度类型或 cron 表达式解析。
+- 除了必要的字段修复外，不大改 cron 的 UI/UX。
+
+## 发现（当前差距）
+
+- Gateway 网关中的 `CronPayloadSchema` 排除了 `signal` + `imessage`，而 TS 类型包含它们。
+- Control UI CronStatus 期望 `jobCount`，但 Gateway 网关返回 `jobs`。
+- 智能体 cron 工具 schema 允许任意 `job` 对象，导致格式错误的输入。
+- Gateway 网关严格验证 `cron.add` 而不进行规范化，因此包装的负载会失败。
+
+## 变更内容
+
+- `cron.add` 和 `cron.update` 现在规范化常见的包装形式并推断缺失的 `kind` 字段。
+- 智能体 cron 工具 schema 与 Gateway 网关 schema 匹配，减少无效负载。
+- 提供商枚举在 Gateway 网关、CLI、UI 和 macOS 选择器之间对齐。
+- Control UI 使用 Gateway 网关的 `jobs` 计数字段显示状态。
+
+## 当前行为
+
+- **规范化：**包装的 `data`/`job` 负载被解包；`schedule.kind` 和 `payload.kind` 在安全时被推断。
+- **默认值：**当缺失时，为 `wakeMode` 和 `sessionTarget` 应用安全默认值。
+- **提供商：**Discord/Slack/Signal/iMessage 现在在 CLI/UI 中一致显示。
+
+参见 [Cron 任务](/automation/cron-jobs) 了解规范化的形式和示例。
+
+## 验证
+
+- 观察 Gateway 网关日志中 `cron.add` INVALID_REQUEST 错误是否减少。
+- 确认 Control UI cron 状态在刷新后显示任务计数。
+
+## 可选后续工作
+
+- 手动 Control UI 冒烟测试：为每个提供商添加一个 cron 任务 + 验证状态任务计数。
+
+## 开放问题
+
+- `cron.add` 是否应该接受来自客户端的显式 `state`（当前被 schema 禁止）？
+- 我们是否应该允许 `webchat` 作为显式投递提供商（当前在投递解析中被过滤）？

package/docs/zh-CN/experiments/plans/group-policy-hardening.md

@@ -0,0 +1,45 @@
+---
+read_when:
+  - 查看历史 Telegram 允许列表更改
+summary: Telegram 允许列表加固：前缀 + 空白规范化
+title: Telegram 允许列表加固
+x-i18n:
+  generated_at: "2026-02-03T07:47:16Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: a2eca5fcc85376948cfe1b6044f1a8bc69c7f0eb94d1ceafedc1e507ba544162
+  source_path: experiments/plans/group-policy-hardening.md
+  workflow: 15
+---
+
+# Telegram 允许列表加固
+
+**日期**：2026-01-05  
+**状态**：已完成  
+**PR**：#216
+
+## 摘要
+
+Telegram 允许列表现在不区分大小写地接受 `telegram:` 和 `tg:` 前缀，并容忍意外的空白。这使入站允许列表检查与出站发送规范化保持一致。
+
+## 更改内容
+
+- 前缀 `telegram:` 和 `tg:` 被同等对待（不区分大小写）。
+- 允许列表条目会被修剪；空条目会被忽略。
+
+## 示例
+
+以下所有形式都被接受为同一 ID：
+
+- `telegram:123456`
+- `TG:123456`
+- `tg:123456`
+
+## 为什么重要
+
+从日志或聊天 ID 复制/粘贴通常会包含前缀和空白。规范化可避免在决定是否在私信或群组中响应时出现误判。
+
+## 相关文档
+
+- [群聊](/channels/groups)
+- [Telegram 提供商](/channels/telegram)

package/docs/zh-CN/experiments/plans/openresponses-gateway.md

@@ -0,0 +1,121 @@
+---
+last_updated: "2026-01-19"
+owner: Synurex
+status: draft
+summary: 计划：添加 OpenResponses /v1/responses 端点并干净地弃用 chat completions
+title: OpenResponses Gateway 网关计划
+x-i18n:
+  generated_at: "2026-02-03T07:47:33Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 71a22c48397507d1648b40766a3153e420c54f2a2d5186d07e51eb3d12e4636a
+  source_path: experiments/plans/openresponses-gateway.md
+  workflow: 15
+---
+
+# OpenResponses Gateway 网关集成计划
+
+## 背景
+
+Synurex Gateway 网关目前在 `/v1/chat/completions` 暴露了一个最小的 OpenAI 兼容 Chat Completions 端点（参见 [OpenAI Chat Completions](/gateway/openai-http-api)）。
+
+Open Responses 是基于 OpenAI Responses API 的开放推理标准。它专为智能体工作流设计，使用基于项目的输入加语义流式事件。OpenResponses 规范定义的是 `/v1/responses`，而不是 `/v1/chat/completions`。
+
+## 目标
+
+- 添加一个遵循 OpenResponses 语义的 `/v1/responses` 端点。
+- 保留 Chat Completions 作为兼容层，易于禁用并最终移除。
+- 使用隔离的、可复用的 schema 标准化验证和解析。
+
+## 非目标
+
+- 第一阶段完全实现 OpenResponses 功能（图片、文件、托管工具）。
+- 替换内部智能体执行逻辑或工具编排。
+- 在第一阶段更改现有的 `/v1/chat/completions` 行为。
+
+## 研究摘要
+
+来源：OpenResponses OpenAPI、OpenResponses 规范网站和 Hugging Face 博客文章。
+
+提取的关键点：
+
+- `POST /v1/responses` 接受 `CreateResponseBody` 字段，如 `model`、`input`（字符串或 `ItemParam[]`）、`instructions`、`tools`、`tool_choice`、`stream`、`max_output_tokens` 和 `max_tool_calls`。
+- `ItemParam` 是以下类型的可区分联合：
+  - 具有角色 `system`、`developer`、`user`、`assistant` 的 `message` 项
+  - `function_call` 和 `function_call_output`
+  - `reasoning`
+  - `item_reference`
+- 成功响应返回带有 `object: "response"`、`status` 和 `output` 项的 `ResponseResource`。
+- 流式传输使用语义事件，如：
+  - `response.created`、`response.in_progress`、`response.completed`、`response.failed`
+  - `response.output_item.added`、`response.output_item.done`
+  - `response.content_part.added`、`response.content_part.done`
+  - `response.output_text.delta`、`response.output_text.done`
+- 规范要求：
+  - `Content-Type: text/event-stream`
+  - `event:` 必须匹配 JSON `type` 字段
+  - 终止事件必须是字面量 `[DONE]`
+- Reasoning 项可能暴露 `content`、`encrypted_content` 和 `summary`。
+- HF 示例在请求中包含 `OpenResponses-Version: latest`（可选头部）。
+
+## 提议的架构
+
+- 添加 `src/gateway/open-responses.schema.ts`，仅包含 Zod schema（无 gateway 导入）。
+- 添加 `src/gateway/openresponses-http.ts`（或 `open-responses-http.ts`）用于 `/v1/responses`。
+- 保持 `src/gateway/openai-http.ts` 不变，作为遗留兼容适配器。
+- 添加配置 `gateway.http.endpoints.responses.enabled`（默认 `false`）。
+- 保持 `gateway.http.endpoints.chatCompletions.enabled` 独立；允许两个端点分别切换。
+- 当 Chat Completions 启用时发出启动警告，以表明其遗留状态。
+
+## Chat Completions 弃用路径
+
+- 保持严格的模块边界：responses 和 chat completions 之间不共享 schema 类型。
+- 通过配置使 Chat Completions 成为可选，这样无需代码更改即可禁用。
+- 一旦 `/v1/responses` 稳定，更新文档将 Chat Completions 标记为遗留。
+- 可选的未来步骤：将 Chat Completions 请求映射到 Responses 处理器，以便更简单地移除。
+
+## 第一阶段支持子集
+
+- 接受 `input` 为字符串或带有消息角色和 `function_call_output` 的 `ItemParam[]`。
+- 将 system 和 developer 消息提取到 `extraSystemPrompt` 中。
+- 使用最近的 `user` 或 `function_call_output` 作为智能体运行的当前消息。
+- 对不支持的内容部分（图片/文件）返回 `invalid_request_error` 拒绝。
+- 返回带有 `output_text` 内容的单个助手消息。
+- 返回带有零值的 `usage`，直到 token 计数接入。
+
+## 验证策略（无 SDK）
+
+- 为以下支持子集实现 Zod schema：
+  - `CreateResponseBody`
+  - `ItemParam` + 消息内容部分联合
+  - `ResponseResource`
+  - Gateway 网关使用的流式事件形状
+- 将 schema 保存在单个隔离模块中，以避免漂移并允许未来代码生成。
+
+## 流式实现（第一阶段）
+
+- 带有 `event:` 和 `data:` 的 SSE 行。
+- 所需序列（最小可行）：
+  - `response.created`
+  - `response.output_item.added`
+  - `response.content_part.added`
+  - `response.output_text.delta`（根据需要重复）
+  - `response.output_text.done`
+  - `response.content_part.done`
+  - `response.completed`
+  - `[DONE]`
+
+## 测试和验证计划
+
+- 为 `/v1/responses` 添加端到端覆盖：
+  - 需要认证
+  - 非流式响应形状
+  - 流式事件顺序和 `[DONE]`
+  - 使用头部和 `user` 的会话路由
+- 保持 `src/gateway/openai-http.e2e.test.ts` 不变。
+- 手动：用 `stream: true` curl `/v1/responses` 并验证事件顺序和终止 `[DONE]`。
+
+## 文档更新（后续）
+
+- 为 `/v1/responses` 使用和示例添加新文档页面。
+- 更新 `/gateway/openai-http-api`，添加遗留说明和指向 `/v1/responses` 的指针。

package/docs/zh-CN/experiments/proposals/model-config.md

@@ -0,0 +1,42 @@
+---
+read_when:
+  - 探索未来模型选择和认证配置文件的方案
+summary: 探索：模型配置、认证配置文件和回退行为
+title: 模型配置探索
+x-i18n:
+  generated_at: "2026-02-01T20:25:05Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 48623233d80f874c0ae853b51f888599cf8b50ae6fbfe47f6d7b0216bae9500b
+  source_path: experiments/proposals/model-config.md
+  workflow: 14
+---
+
+# 模型配置（探索）
+
+本文档记录了未来模型配置的**构想**。这不是正式的发布规范。如需了解当前行为，请参阅：
+
+- [模型](/concepts/models)
+- [模型故障转移](/concepts/model-failover)
+- [OAuth + 配置文件](/concepts/oauth)
+
+## 动机
+
+运营者希望：
+
+- 每个提供商支持多个认证配置文件（个人 vs 工作）。
+- 简单的 `/model` 选择，并具有可预测的回退行为。
+- 文本模型与图像模型之间有清晰的分离。
+
+## 可能的方向（高层级）
+
+- 保持模型选择简洁：`provider/model` 加可选别名。
+- 允许提供商拥有多个认证配置文件，并指定明确的顺序。
+- 使用全局回退列表，使所有会话以一致的方式进行故障转移。
+- 仅在明确配置时才覆盖图像路由。
+
+## 待解决的问题
+
+- 配置文件轮换应该按提供商还是按模型进行？
+- UI 应如何为会话展示配置文件选择？
+- 从旧版配置键迁移的最安全路径是什么？