实例规格透传 quotaNames,重新生成 swagger

- POST /ai/v1/tts:xAI 官方 TTS 格式转换层(text/voice_id→input/voice),复用 Speech 编排,model 缺省 xai.grok-tts;实测 output_format/speed 透传生效
- 「过滤弃用模型」开关(GET/PUT /api/v1/ai-settings,settings 表持久化):开启后已宣布弃用(未退役)模型从列表与路由排除;同步入库与退役提醒不受影响
- AI 网关文档更名 docs/AI网关.md,补 tts 矩阵段与开关说明;README 引用同步
- CHANGELOG 0.5.0(0.4.0 已发版冻结);DASH_VERSION v0.5.0

.trellis/spec/backend/database-guidelines.md

@@ -24,7 +24,20 @@ Questions to answer:
 
 <!-- How should queries be written? Batch operations? -->
 
-(To be filled by the team)
+### 租户级数据删除
+
+- 租户主体与本地关联数据必须在同一 GORM transaction 中按“子记录→父记录”删除，每步错误用 `%w` 返回，不得忽略。
+- JSON payload/Setting 键等非外键引用要显式枚举并改写；不能只依赖 `AutoMigrate` 或 ORM association 推断级联范围。
+- 与后台任务、Webhook、解析器等并发写入交叉时，先定义全局一致的行锁顺序，并在写入前重新确认父记录存在。
+- 进程内 cron/缓存只在事务提交后同步；客户端取消不应中断已提交删除的必需运行时对齐。
+- 批量删除/清理遇到**无法解析的 JSON payload** 时记 `log.Printf` 警告并跳过该行(原样保留),不 fail-closed 阻断整个流程——坏数据不应把删除逼到手工修库(tenantdelete.go `logSkippedTask`)。
+
+### 大集合谓词用子查询,禁止展开 IN 列表
+
+- 行数无上界的集合(日志事件、调用日志等)做关联删除/查询时,一律 `WHERE x IN (SELECT …)` 子查询,**不要**先 Pluck ID 再 `IN ?` 展开:绑定变量有硬上限(modernc SQLite 32766,MySQL/PG 65535),数万行即失败且重试无解。
+- GORM 写法:把 `tx.Model(&T{}).Select("id").Where(...)` 作为参数传入 `Where("x IN (?)", sub)`(见 tenantdelete.go `deleteAlertHits` / `alertHitRuleIDs`)。
+- 若原本的 Pluck 兼有 `FOR UPDATE` 锁定语义,保留锁定 SELECT 本身,只是不再把结果拼进后续 SQL(`lockTenantEventRows`)。
+- 行数有小上界的集合(渠道、规则等配置类)可以继续用内存 ID 列表。
 
 ---
 
@@ -48,6 +61,14 @@ Questions to answer:
 
 <!-- Database-related mistakes your team has made -->
 
+### Common Mistake: 用 `Save` 持久化在途任务的陈旧快照
+
+**Symptom**:一条记录已被另一事务删除，在途任务随后执行 `Save` 却把该行重新插入，或覆盖并发更新后的 payload。
+
+**Cause**:GORM `Save` 在 `UPDATE` 零命中时会回退到 `CREATE`/upsert，不适合持久化长时运行开始时读取的快照。
+
+**Fix**:用 `WHERE id = ? AND updated_at = ?` 的条件 `Updates`，并严格要求 `RowsAffected == 1`；零命中表示记录已删除或版本已变，不得补做 `Create`。
+
 ### Common Mistake: gorm 读 NULL 列到已有值的结构体字段不会清零
 
 **Symptom**:UPDATE 把可空列(如 `*time.Time`)写成 NULL 后,用**同一个结构体变量**再次 `First()` 读回,该字段仍是旧值;而新变量读取正常。断言/返回值出现「幽灵旧值」。
@@ -66,3 +87,19 @@ db.Model(&model.AiChannel{}).
     Where("id = ? AND (fail_count > 0 OR disabled_until IS NOT NULL)", id).
     Updates(map[string]any{"fail_count": 0, "disabled_until": gorm.Expr("NULL")})
 ```
+
+### `serializer:json` 字段走 map Updates 时手动 marshal
+
+- 切片/结构体字段用 `gorm:"serializer:json;type:text"` 声明(如 `AiKey.Models []string`),Create/First/struct 路径自动序列化;
+- 但 `Updates(map[string]any{...})` 路径不要依赖 GORM 对 map 值应用 serializer——把值 `json.Marshal` 成 string 放进 map(见 aigateway.go `UpdateKey`),行为版本无关且可测;
+- 存储格式与 serializer 一致(JSON 文本),读回仍走自动反序列化;`nil` 切片 marshal 为 `null`,读回 nil,天然表达「空 = 不限」语义。
+
+### Common Mistake: 进程内缓存键漏掉查询维度
+
+**Symptom**:多区间(compartment)租户在前端切换区间后,实例/卷/VCN 列表短暂显示上一个区间的数据(TTL 窗口内)。
+
+**Cause**:`internal/oci/cached.go` 的 `ckey` 只拼了租户 OCID+资源名+region,而底层查询按 `cred.EffectiveCompartment()` 过滤——影响结果的维度没有全部进键,不同参数命中同一条缓存。
+
+**Fix**:键值加入 `cred.CompartmentID`(空 = 租户根,天然区分)。
+
+**Prevention**:缓存键必须覆盖影响回源结果的**全部**输入维度(租户、区间、区域、过滤参数);给 Credentials/查询结构体新增会改变结果的字段时,同步检查 `ckey` 调用点;隔离行为写进 `cached_test.go` 的 isolation 用例。

.trellis/spec/backend/index.md

@@ -1,6 +1,6 @@
 # Backend Development Guidelines(oci-portal 后端规范)
 
-> Go 后端(`oci-portal/`)编码规范入口。规范提炼自 Google / Uber Go Style Guide、Effective Go 与 Go 官方模块布局指南,按本项目裁剪;条目与项目约定冲突时,以本 spec 为准。迁自 docs/开发指南.md 与根目录 AGENTS.md(2026-07)。
+> Go 后端(`oci-portal/`)编码规范入口。规范提炼自 Google / Uber Go Style Guide、Effective Go 与 Go 官方模块布局指南,按本项目裁剪;条目与项目约定冲突时,以本 spec 为准。
 
 ---
 
@@ -20,6 +20,7 @@ Gin + GORM + SQLite(纯 Go 驱动 `glebarez/sqlite`,免 CGO;默认与推荐)+ AE
 | [Concurrency](./concurrency.md) | goroutine 生命周期与 context 传递 | 已填 |
 | [Testing](./testing.md) | table-driven 测试要求 | 已填 |
 | [Database Guidelines](./database-guidelines.md) | ORM 模式、查询、迁移 | 待填 |
+| [OCI Audit](./oci-audit.md) | 审计事件双通道数据源、检索语义与预算纪律 | 已填 |
 | [Logging Guidelines](./logging-guidelines.md) | 结构化日志、日志级别 | 待填 |
 
 ---
@@ -51,7 +52,7 @@ go mod tidy                     # 依赖有变更时
 全部 HTTP 接口带 swaggo 注释(@Summary 中文/@Tags 按域/@Param/@Success/@Router;JWT 组接口标 @Security BearerAuth)。**新增或修改接口必须同步注释**,并重新生成 spec:
 
 ```bash
-go tool swag init -g cmd/server/main.go -o docs --parseInternal --parseDependency
+go tool swag init -g cmd/server/main.go -o docs --parseInternal --parseDependency --overridesFile docs/.swaggo
 ```
 
 生成的 `docs/` 一并提交;UI 由 `SWAGGER=1` 开启(/swagger/index.html)。同名 handler 方法(list/create/get/update/remove)分布在多个 struct 上,写注释时确认 @Router 路径与该 receiver 的真实注册一致(routes_*.go)。

.trellis/spec/backend/oci-audit.md

@@ -0,0 +1,19 @@
+# OCI 审计事件集成约定
+
+> 2026-07 审计日志重构(数据源切换 + 检索 + 配额回退)沉淀;实现见 `internal/oci/audit.go`。
+
+## 数据源:双通道,Search 主路 + Audit API 回退
+
+- **Audit API(`audit.ListEvents`)无排序参数,窗口内固定按处理时间正序分页**。任何"从最新往更早"的列表需求禁止直接用它凑批——首批会拿到窗口内最旧的一段(2026-07-16 曾以此形态上线出 bug)。
+- 倒序列表一律走 **Logging Search**(`loggingsearch.SearchLogs`,`search "<tenancy>/_Audit" | ... | sort by datetime desc`)。硬约束:单次查询时间窗 ≤ 14 天、limit ≤ 1000、时间过滤基于**处理时间**而非发生时间。
+- **部分免费租户 Logging Search 服务配额为零**(报错含 `Rate limit exceeded` + `maxQueriesPerMinute: 0`,SDK 解析该错误体还会失败),属永久不可用,须自动回退 Audit API(小窗正序 + 前端全局重排);普通限流(配额非零)不回退。游标携带通道模式,续查不再试错。
+
+## 检索语义
+
+- `logContent = '*词*'` 是对整条日志 JSON **所有字段值**的包含匹配,会命中隐藏认证元数据(如 `opc-principal` 头里的 `ttype: login`),只可作服务端粗筛;**用户可见语义必须再做客户端精筛**(只匹配列表可见字段,不区分大小写,`*` 通配分段)。
+- 用户输入进检索语句前必须消毒(去引号/反斜杠/控制字符、截断),见 `SanitizeAuditTerm`。
+
+## 批式回溯的预算纪律
+
+- 单批双预算:页数(`maxAuditPages`)+ 时间(`auditBatchTimeBudget`≈20s)。全文检索命中稀疏时大窗扫描单页可达十余秒,没有时间预算会出现 3 分钟级单请求。
+- 空窗按倍增扩窗(上限受 14 天查询窗约束);响应回传 `scannedThrough` 供前端展示回溯进度,前端自动补批必须封顶,由用户显式继续。

CHANGELOG.md

@@ -1,8 +1,117 @@
 # Changelog
 
-格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循语义化版本。
+格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)（版本段不记日期），版本号遵循语义化版本。
 
-## [0.3.1] - 2026-07-13
+## [0.7.2]
+
+### Added
+
+- AI 网关设置新增「上游无响应预算」（`upstreamWaitSeconds`，30..900 秒，缺省 300，持久化、即时生效）：非流式为单次尝试总超时，流式为等待响应头上限，供 multi-agent / 搜索类慢模型调宽
+
+### Changed
+
+- 出站代理 Transport 补齐阶段超时（连接 30 秒 / TLS 握手 10 秒，对齐 SDK 直连模板）：连不上的代理快速失败，不再拖满总超时
+
+### Fixed
+
+- 修复 Responses 直通调用 multi-agent / 搜索类模型必然超时：SDK 默认 `http.Client` 60 秒总超时覆盖到 body 读完，流式恰好 60 秒断流、非流式（响应头 >60 秒才返回）重试耗尽后约 121 秒报错。非流式改用预算总超时；流式去掉总超时，以定时取消模拟等待响应头预算，响应头到达后流时长不限、生命周期由客户端连接决定。附带消除此类超时对渠道熔断计数的误伤
+
+## [0.7.1]
+
+### Added
+
+- 审计事件接口新增检索参数 `q`：服务端 `logContent` 全文粗筛 + 可见字段（事件名 / 资源 / 操作者 / IP / 请求路径等）精筛，不区分大小写、支持 `*` 通配；关键字内嵌续查游标，跨批过滤口径一致。全文粗筛不作最终判定——`logContent` 会命中隐藏认证元数据（如 `opc-principal` 头里的 `ttype: login`）
+- 审计批式响应新增 `scannedThrough`（已完整回溯到的时刻），供前端展示回溯进度
+- Logging Search 服务配额为零的租户（报错含 `maxQueriesPerMinute: 0`，部分免费租户如此）自动回退 Audit API 小窗回溯：游标携带通道模式、续查不再试错，搜索降级为客户端可见字段匹配，审计页不再报错
+
+### Changed
+
+- 审计事件数据源由 Audit API 切换为 Logging Search（`_Audit` 日志按 `datetime` 倒序，单页 200 条）；空窗倍增上限由 30 天收紧到 14 天（单次查询时间窗硬限），单批新增约 20 秒时间预算，命中稀疏的深回溯拆成多个有界请求由前端接力
+
+### Fixed
+
+- 修复审计日志固定显示旧事件、刷新也看不到最新记录：Audit API 无排序参数且窗口内固定按处理时间正序，原实现凑满一批即返回，首批永远是 24h 窗口内最旧的一段，「向更早加载」实际在向更新方向翻页
+
+## [0.7.0]
+
+### Added
+
+- AI 网关运行时设置扩展（`GET` / `PUT /api/v1/ai-settings`，持久化、即时生效）：
+  - Responses 流式保险丝：开关 + 阈值（KB，1..1024），超阈值的流式请求预防性改非流式上游并合成最小 SSE
+  - grok 服务端搜索工具默认注入：`xai.` 前缀模型的 Responses 请求按开关默认注入 `web_search` / `x_search`，请求 `tools` 已含同名工具（任意参数形态）时不覆盖，注入动作记服务端日志
+- 聚合模型目录端点 `GET /api/v1/ai-model-catalog`：启用渠道去重、含能力字段（空能力归一 CHAT），与模型列表同口径（随「过滤弃用」开关），供设置页黑名单添加弹窗使用
+
+### Changed
+
+- Responses 流式保险丝触发口径由「完整请求体 > 76KB（环境变量 `AI_RESP_STREAM_UPGRADE_KB`）」改为「`instructions` + `tools` 原始字节合计超阈值（默认开、60KB，设置页可调）」：复测证实约 82KB 的纯体积断流已由上游修复，而 `instructions`+`tools` 合计 >≈64.5KB 的流式静默断流仍存在（`input` 不计入）；环境变量随之废弃
+- 升级 oci-go-sdk 到 v65.121.0
+
+### Fixed
+
+- 修复多网卡实例的列表 / 详情地址字段随机：并发填充改以主网卡为准（主卡未返回前允许先到网卡兜底，主卡到达后覆盖并锁定），公网 IP / 私网 IP / IPv6 / 子网恒为主网卡数据
+
+## [0.6.1]
+
+### Added
+
+- Responses 直通 codex 兼容层，codex CLI（`wire_api = "responses"`）指向网关即用，实测 codex-cli 0.144.1 主会话与 multi-agent 子代理全链路可用：
+  - `namespace` 工具组（承载 codex multi-agent 与全部 MCP 工具，仅 OpenAI 原生后端识别，OCI 实测 422）拍平为限定名 `function` 工具上送（`ns__child`，`mcp__` 开头子工具名不加前缀），响应中命中的 `function_call` 还原为短名并补回 `namespace` 字段（codex 以该双字段路由）；多轮历史 `function_call` 与对象形态 `tool_choice` 上的 `namespace` 字段自动重限定
+  - `custom` 自由格式工具（apply_patch 及 GPT-5.x 档位子代理形态，OCI 不识别）转换为带 `{"input": string}` 包装 schema 的 `function`，响应回转 `custom_tool_call` 并解包 `input`，多轮历史的 `custom_tool_call(_output)` 逆向转换，往返无损；例外：`apply_patch` 整体剥离（grok 系未训练 codex 补丁格式，模型自然回落 shell 编辑）
+  - `tool_search`（codex 工具目录搜索）剥离：namespace 已全量拍平上送，搜索语义冗余且上游不识别
+  - `web_search` 的 OpenAI 专有参数 `external_web_access`（OCI 实测 400）：`true` 仅删键放行（等价上游默认行为），`false` 为"仅缓存检索"降权模式，按不越权原则连工具剥离
+  - 以上改写动作（拍平 / 转换 / 剥离）与校验拒绝均记服务端日志可观测
+- Responses 直通流式升级回退：实测 OCI 上游对超过约 82KB 的流式请求会在推理阶段掐断流（纯请求体积触发，与工具构成无关，非流式不受影响），请求体超 76KB 时自动改调非流式上游并合成最小 SSE 事件序列（`created` → 逐项 `output_item.done` → `completed`）返回，语义完整仅丢失增量输出——0.3.1 中「Responses 直通无法透明降级」的限制自此按体积预判解除
+
+### Changed
+
+- `/ai/v1/responses` 工具类型白名单扩展：`namespace` / `custom` / `tool_search` 不再 400 拒绝，按上述兼容策略处理后转发；其余未知工具类型维持请求前置拒绝
+
+## [0.6.0]
+
+### Added
+
+- 渠道模型缓存列表端点 `GET /api/v1/ai-channels/{id}/models`：黑名单模型查询层兜底排除，「过滤弃用模型」开关开启时同样剔除已宣布弃用者（数据保留，展示口径过滤）
+- 单模型测试端点 `POST /api/v1/ai-channels/{id}/test-model`：对指定模型发 max_tokens=16 试调，通过即写入渠道「探测验证模型」（此后手动探测与每日后台任务将其置于试调候选首位），渠道探测状态不为可用时顺带置可用并复位熔断；未通过如实返回上游错误且不改动渠道状态
+- 渠道列表响应回填 `modelCount`（模型缓存计数，与模型列表同口径：排除黑名单、随过滤弃用开关）
+
+### Fixed
+
+- 修复渠道探测「无配额」误判：配额试调遇 401/403/鉴权 404 不再立即定论租户无配额（可能仅个别模型无权限），改为继续尝试其余候选，任一成功即判可用，全部失败且出现过鉴权拒绝才判无配额
+- 探测试调 `max_output_tokens` 由 1 提升到 16：openai.gpt-oss 系列要求 ≥16，原值被 400 拒导致仅有该系列对话模型的渠道被误判
+
+## [0.5.1]
+
+### Fixed
+
+- 修复外部身份（OAuth2）登录 / 绑定无系统日志的问题：回调成功记 200（用户名为面板账号）、失败记 401（附失败原因）；此前回调为 GET 请求不经写操作日志中间件，完全无记录
+
+## [0.5.0]
+
+### Added
+
+- xAI 官方格式文本转语音端点 `POST /ai/v1/tts`：接受 xAI 官方 TTS 请求（`text` / `language` 必填，`voice_id`、`output_format`{codec, sample_rate, bit_rate}、`speed` 等），网关转换为 OpenAI 兼容形态后与 `/ai/v1/audio/speech` 走同一上游与渠道调度；`model` 为网关扩展字段（缺省 `xai.grok-tts`）；实测 `output_format` 对象与 `speed` 透传生效，xAI SDK / 客户端可直接指向网关
+- 「过滤弃用模型」开关（`GET` / `PUT /api/v1/ai-settings`，持久化）：开启后 OCI 已宣布弃用（即使未到退役日）的模型从模型列表与路由中同时排除，关闭恢复；渠道同步入库与 30 天退役提醒不受影响
+
+### Changed
+
+- AI 网关文档更名为 `docs/AI网关.md`（原 `docs/ai-gateway.md`），README 引用同步
+
+## [0.4.0]
+
+### Added
+
+- 文本转语音端点 `POST /ai/v1/audio/speech`：OpenAI Audio Speech 兼容，直通 OCI 兼容面（模型 `xai.grok-tts`，voice 取 xAI Grok Voice 列表 `ara`/`eve`/`leo`/`rex`/`sal`）；上游必填的 `language` 缺省时自动注入 `"auto"`，xAI 专属参数平铺透传；响应为一次性完整音频（Content-Type 透传上游，缺省 audio/mpeg），不提供流式
+- 文档重排端点 `POST /ai/v1/rerank`：Jina / Cohere 通行协议，走 OCI typed 面（`cohere.rerank-v4.0-pro` / `-fast`），支持 `top_n` 与 `return_documents`，`results[].index` 指向入参 `documents` 下标
+- 内容审核端点 `POST /ai/v1/moderations`：OpenAI moderations 外壳映射 OCI Guardrails（内容审核 / PII / 提示注入），`input` 为字符串或字符串数组（单次至多 8 条），categories 用 OCI 原生维度 `overall` / `blocklist` / `prompt_injection`（任一得分 ≥0.5 判 `flagged`），PII 命中放扩展字段 `results[].pii`（不参与 flagged；实测中文人名 / 手机号识别较弱，英文正常）
+- Responses 服务端工具扩展：放行 Oracle 文档化的 xAI `code_interpreter` 与远程 `mcp` 工具，并解除 `web_search` / `x_search` 仅非流式的限制——四类服务端工具非流式与流式均实测可用；`code_interpreter` 的命名容器管理与 File Search 不提供
+- 模型能力映射扩展：`TEXT_RERANK` → RERANK、`TEXT_TO_AUDIO` → TTS，渠道探测 / 同步自动发现重排与语音模型入池
+
+### Changed
+
+- AI 网关文档独立成篇 `docs/ai-gateway.md`（端点定位、兼容边界、已知上游限制、字段兼容矩阵——矩阵只列支持项，不支持 / 忽略项以文字简述），README 精简为概览并引用；实测披露：Responses `input_file` 内容块被上游以 ZDR 形态拒绝，能力不可用
+- swagger 全面修缺：135 处响应注解从泛型 map 改为具体类型（补文档用途响应结构与泛型列表外壳），AI 网关端点请求 / 响应 schema 完整可见；`json.RawMessage` 与联合类型统一渲染为任意 JSON 值（AnyJSON），不再误显示为 byte 数组；swag overrides 配置移至 `docs/.swaggo`，生成命令加 `--overridesFile docs/.swaggo`；顺带修正网页控制台会话创建响应码（200→201）与 SAML 元数据下载（改文件响应）两处注解失真
+
+## [0.3.1]
 
 ### Added
 
@@ -16,7 +125,7 @@
 
 - AI 网关流式假成功：上游 error / `response.failed` 事件此前被吞掉，流提前 EOF 也被伪装成正常结束，调用日志呈现 200 · 0/0 且无错误信息；现 Messages 将上游失败转为 Anthropic `error` 事件，三个流式端点日志均记录上游错误消息或「上游流提前终止，未返回终态事件」
 
-## [0.3.0] - 2026-07-13
+## [0.3.0]
 
 ### Added
 
@@ -33,7 +142,7 @@
 
 - **移除自定义审计告警规则**及其阈值、窗口和冷却匹配能力；`/api/v1/log-events/alert-rules` 与 `/api/v1/log-events/alert-rules/{ruleId}` 管理接口、`audit_alert` 通知模板不再提供，已有规则升级后不再执行
 
-## [0.2.0] - 2026-07-12
+## [0.2.0]
 
 ### Added
 
@@ -60,7 +169,7 @@
 - 渠道「同步模型成功但探测报错不可用」：法兰克福等区域的微调基座模型占满探测候选导致的误报（探测状态与真实可用性不符的根因）
 - 租户删除：告警命中清理改子查询，日志事件数万条时不再超出 SQL 绑定变量上限导致删除失败；无法解析的任务 payload 记警告跳过并保留原任务，不再永久阻断租户删除
 
-## [0.1.0] - 2026-07-10
+## [0.1.0]
 
 ### Added
 
@@ -88,7 +197,7 @@
 - HTTP 入口加固：显式读写超时与优雅关闭、请求体上限（面板 1MB / AI 网关 10MB）、登录字段长度上限、登录守卫条目数有界
 - 出错响应脱敏：内部错误只返回固定文案 + requestId，完整原因写服务端日志；GORM SQL 日志参数化输出，不再记录实参
 
-## [0.0.1] - 2026-07-09
+## [0.0.1]
 
 首个版本：自托管 OCI 多租户管理面板后端。
 

DASH_VERSION

@@ -1 +1 @@
-v0.3.0
+v0.7.2

README.md

@@ -6,12 +6,14 @@
 
 **自托管的 OCI 多租户管理面板与 GenAI 兼容网关**
 
-![Release](https://img.shields.io/github/v/release/wangdefaa/oci-portal?display_name=tag)
+[![Release](https://img.shields.io/github/v/release/wangdefaa/oci-portal?display_name=tag)](https://github.com/wangdefaa/oci-portal/releases/latest)
-![Go](https://img.shields.io/badge/Go-1.26.5-00ADD8?logo=go&logoColor=white)
+[![Go](https://img.shields.io/badge/Go-1.26.5-00ADD8?logo=go&logoColor=white)](go.mod)
-![Docker](https://img.shields.io/badge/Docker-amd64%20%7C%20arm64-2496ED?logo=docker&logoColor=white)
+[![Docker](https://img.shields.io/badge/Docker-amd64%20%7C%20arm64-2496ED?logo=docker&logoColor=white)](docker-compose.yml)
-![License](https://img.shields.io/badge/License-MIT-blue)
+[![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
 
-[快速开始](#快速开始) · [核心能力](#核心能力) · [生产部署](#生产部署) · [AI 网关](#ai-网关) · [开发](#开发)
+[界面预览](#界面预览) · [核心能力](#核心能力) · [快速开始](#快速开始) · [生产部署](#生产部署) · [AI 网关](#ai-网关) · [开发](#开发)
+
+[AI 网关文档](docs/AI网关.md) · [OpenAPI](docs/swagger.yaml) · [更新日志](CHANGELOG.md) · [前端仓库](https://github.com/wangdefaa/oci-portal-dash)
 
 </div>
 
@@ -21,27 +23,36 @@ OCI Portal 将多份 OCI API Key、云资源、自动化任务、审计事件和
 
 ## 界面预览
 
-| 总览 | 登录 |
+<p align="center">
-| --- | --- |
+  <img src="docs/assets/screenshot-overview.png" width="960" alt="OCI Portal 总览">
-| ![总览](docs/assets/screenshot-overview.png) | ![登录](docs/assets/screenshot-signin.png) |
+</p>
 
-| 租户 | 任务 |
+<details>
-| --- | --- |
+<summary><strong>展开更多界面截图</strong></summary>
-| ![租户](docs/assets/screenshot-tenants.png) | ![任务](docs/assets/screenshot-tasks.png) |
 
-| AI 网关 | 通知设置 |
+| 登录 | 租户 |
 | --- | --- |
-| ![AI 网关](docs/assets/screenshot-ai-gateway.png) | ![通知设置](docs/assets/screenshot-settings-notify.png) |
+| ![登录](docs/assets/screenshot-signin.png) | ![租户](docs/assets/screenshot-tenants.png) |
+
+| 任务 | AI 网关 |
+| --- | --- |
+| ![任务](docs/assets/screenshot-tasks.png) | ![AI 网关](docs/assets/screenshot-ai-gateway.png) |
+
+| 通知设置 |
+| --- |
+| ![通知设置](docs/assets/screenshot-settings-notify.png) |
+
+</details>
 
 ## 核心能力
 
-- **租户与区域**：集中管理多份 OCI API Key，支持分组、批量测活、账户画像、订阅区域缓存与区域切换；私钥和口令使用 AES-256-GCM 加密落库
+| 能力域 | 覆盖范围 |
-- **计算、网络与存储**：实例创建与电源操作、公网 IP、IPv6、VNIC、串行控制台连接，VCN / 子网 / 安全列表，引导卷与块存储挂载，限额和成本查询
+| --- | --- |
-- **自动化任务**：抢机、租户测活、成本同步、AI 渠道探测四类 cron 任务，提供执行日志、重叠执行防护、熔断与结果通知
+| **租户与云资源** | 多 OCI API Key、分组、批量测活、账户画像、订阅区域缓存与切换；实例创建与电源操作、VNIC、公网 IP、IPv6、VCN、安全列表、引导卷、块存储挂载、限额与成本查询 |
-- **网页控制台**：浏览器内使用 xterm 串行终端和 noVNC，通过 OCI 控制台连接建立两跳 SSH 隧道
+| **自动化与控制台** | 抢机、租户测活、成本同步、AI 渠道探测；执行日志、重叠防护、熔断与结果通知；xterm 串行终端、noVNC 和 OCI 控制台连接两跳 SSH 隧道 |
-- **身份与审计**：IAM 用户、MFA、API Key、密码策略、SAML 身份提供商、通知收件人和多 Identity Domain 管理；OCI Audit 事件可经 Service Connector Hub 与 Notifications 回传，关键事件按类别通过「云端事件」通知推送
+| **身份与审计** | IAM 用户、MFA、API Key、密码策略、SAML、通知收件人与多 Identity Domain；通过 Service Connector Hub 与 Notifications 接收并分类推送 OCI Audit 事件 |
-- **通知与安全**：Telegram、Webhook、ntfy、Bark、SMTP 五类渠道；JWT、bcrypt、TOTP、OIDC / GitHub 登录、登录锁定、IP 限速、会话撤销和系统操作审计
+| **通知与安全** | Telegram、Webhook、ntfy、Bark、SMTP；AES-256-GCM、JWT、bcrypt、TOTP、OIDC / GitHub 登录、登录锁定、IP 限速、会话撤销和操作审计 |
-- **AI 网关**：提供 OpenAI Responses、Chat Completions、Embeddings 与 Anthropic Messages 兼容接口，支持渠道分组、加权路由、熔断探测、模型黑白名单、密钥管理和调用日志
+| **AI 网关** | OpenAI Responses、Chat Completions、Embeddings 与 Anthropic Messages；渠道分组、加权路由、熔断探测、模型治理、密钥管理和调用日志 |
 
 ## 运行形态
 
@@ -57,7 +68,9 @@ OCI Portal 将多份 OCI API Key、云资源、自动化任务、审计事件和
 └─────────────────────────────────────────────────────────────────┘
 ```
 
-默认推荐 SQLite 单实例部署。MySQL 和 PostgreSQL 适配仍属 experimental，不应据此推断服务支持多副本并发运行。
+> [!NOTE]
+> 默认推荐 SQLite 单实例部署。MySQL 和 PostgreSQL 适配仍属 experimental，
+> 不应据此推断服务支持多副本并发运行。
 
 ## 快速开始
 
@@ -65,6 +78,10 @@ OCI Portal 将多份 OCI API Key、云资源、自动化任务、审计事件和
 
 前置条件：Docker、Docker Compose v2、OpenSSL。
 
+> [!CAUTION]
+> `.env` 中的 `DATA_KEY` 用于解密 OCI 私钥、口令和渠道凭据。首次生成后必须长期
+> 保存；升级或重装时不要覆盖，否则已有密文将无法恢复。
+
 1. 克隆仓库并生成一份需要长期保存的 `.env`：
 
    ```bash
@@ -79,19 +96,27 @@ OCI Portal 将多份 OCI API Key、云资源、自动化任务、审计事件和
    chmod 600 .env
    ```
 
-2. 准备数据目录并启动：
+2. 准备数据目录：
 
    ```bash
    mkdir -p data
+   ```
 
-   # Linux bind mount 需要让镜像内的 nonroot 用户（uid 65532）可写。
+   Linux 使用 bind mount 时，需要让镜像内的 nonroot 用户（uid `65532`）可写；
+   Docker Desktop 用户通常不需要执行：
+
+   ```bash
    sudo chown 65532:65532 data
+   ```
 
+3. 启动并检查状态：
+
+   ```bash
    docker compose up -d
    docker compose ps
    ```
 
-3. 查看初始管理员密码并登录：
+4. 查看初始管理员密码并登录：
 
    ```bash
    grep '^ADMIN_PASSWORD=' .env
@@ -99,7 +124,14 @@ OCI Portal 将多份 OCI API Key、云资源、自动化任务、审计事件和
 
    访问 `http://127.0.0.1:18888`，默认用户名为 `admin`。
 
-> `DATA_KEY` 用于解密数据库中的 OCI 私钥、口令和渠道凭据。它只能生成一次并持续复用；丢失或更换后，已有密文无法恢复。请将 `.env` 与 `data/oci-portal.db` 一起备份。
+   启动异常时查看最近日志：
+
+   ```bash
+   docker compose logs --tail=100 oci-portal
+   ```
+
+> [!TIP]
+> 请将 `.env` 与 `data/oci-portal.db` 成对备份；恢复时两者必须匹配。
 
 ### 二进制运行
 
@@ -107,6 +139,8 @@ Release 提供 Linux amd64 / arm64 二进制。以下以 amd64 为例；arm64
 
 ```bash
 curl -fLO https://github.com/wangdefaa/oci-portal/releases/latest/download/oci-portal-server-linux-amd64
+curl -fLO https://github.com/wangdefaa/oci-portal/releases/latest/download/SHA256SUMS
+grep 'oci-portal-server-linux-amd64$' SHA256SUMS | sha256sum -c -
 chmod +x oci-portal-server-linux-amd64
 
 # 复用上文生成并妥善保存的 .env。
@@ -142,7 +176,9 @@ CGO_ENABLED=0 go build -trimpath -o bin/oci-portal-server ./cmd/server
 
 ## 生产部署
 
-服务本身只提供 HTTP。除本机试用外，应保持服务仅监听回环地址或容器内部网络，并由 TLS 反向代理提供 HTTPS；否则管理员密码、JWT、AI 密钥和租户凭据会经明文连接传输。
+> [!WARNING]
+> 服务本身只提供 HTTP。除本机试用外，应仅监听回环地址或容器内部网络，并由
+> TLS 反向代理提供 HTTPS；否则管理员密码、JWT、AI 密钥和租户凭据会经明文传输。
 
 ### Caddy
 
@@ -197,206 +233,21 @@ server {
 
 ## AI 网关
 
-AI 网关使用面板创建的独立密钥鉴权，支持 `Authorization: Bearer sk-...` 和 `x-api-key: sk-...`。密钥可绑定渠道分组和模型白名单；全局模型黑名单会从模型列表、路由和探测候选中同时排除目标模型。
+面板内置 OpenAI / Anthropic 兼容的 GenAI 网关：独立密钥鉴权（`Authorization: Bearer sk-...` 或 `x-api-key`），支持渠道分组、加权路由、熔断探测、模型黑白名单、内容日志与调用日志。
 
 | 端点 | 定位 | 流式 |
 | --- | --- | --- |
-| `POST /ai/v1/responses` | OpenAI Responses，无状态主接口 | SSE；服务端工具除外 |
+| `POST /ai/v1/responses` | OpenAI Responses，无状态主接口（xAI 服务端工具 / MCP） | SSE |
-| `POST /ai/v1/chat/completions` | OpenAI Chat Completions，存量客户端兼容层 | SSE |
+| `POST /ai/v1/chat/completions` | OpenAI Chat Completions 兼容层 | SSE |
 | `POST /ai/v1/messages` | Anthropic Messages 转换层 | SSE |
 | `POST /ai/v1/embeddings` | OpenAI Embeddings | 否 |
+| `POST /ai/v1/audio/speech` | 文本转语音（xAI Voice） | 否 |
+| `POST /ai/v1/tts` | 文本转语音（xAI 官方格式） | 否 |
+| `POST /ai/v1/rerank` | 文档重排（Cohere Rerank） | 否 |
+| `POST /ai/v1/moderations` | 内容审核（OCI Guardrails） | 否 |
 | `GET /ai/v1/models` | 当前密钥可见的模型列表 | 否 |
 
-兼容边界：
+协议兼容边界、已知上游限制与逐字段兼容矩阵见 **[AI 网关文档](./docs/AI网关.md)**。
-
-- 对话请求统一转发 OCI OpenAI 兼容面，当前供给以 `xai.`、`meta.`、`openai.` 前缀模型为主；Cohere Embeddings 不受该对话模型范围影响
-- 网关不保存会话历史，客户端需要携带完整上下文；Responses 拒绝非空 `previous_response_id`、非 `null` `conversation` 和 `background:true`
-- Responses 支持 xAI Grok `web_search` / `x_search` 服务端工具，但仅限非流式请求
-- Responses 的 `reasoning.effort`、Messages 的 `output_config.effort` 和 Chat Completions 的 `reasoning_effort` 会传给上游，实际档位和效果由模型决定
-- Chat Completions 只承担协议转换与兼容修复；新能力优先在 Responses 和 Messages 提供
-- 单次请求最多尝试三个渠道；可重试错误会切换渠道，流式响应建立后不会换渠道重试
-
-### 已知上游限制：大 system 区流式断流
-
-实测（2026-07-13）OCI 兼容面对 `instructions` 与 `tools` 合计超约 64.5KB 的**流式**请求会在发出少量事件后静默断开连接（无任何错误事件；同请求非流式正常），与模型、字符集、消息正文大小均无关——消息正文（`input`）不计入该限制。Chat Completions 与 Messages 的 system/developer 提示会转换为 `instructions`，因此 Claude Code 等自带大体量系统提示与工具定义的客户端极易触发。
-
-网关侧应对：
-
-- Messages 与 Chat Completions 的流式请求在客户端尚未收到任何输出时遭遇上游断流，会自动降级为非流式重做，并按标准事件/chunk 序列一次推送；调用日志记 `retries=1` 与降级标记
-- Responses 直通因初始事件已转发、协议上无法透明降级，调用日志记「上游流提前终止」，客户端需自行回退非流式
-- 应急规避：将超长 system 内容移入首条 user 消息正文可绕过该限制（正文不计入），但语义有别，根治有待上游修复
-
-这里提供的是兼容接口而非 OpenAI / Anthropic 协议的完整实现。OCI OpenAI 兼容面的部分行为来自实测，未见 Oracle 文档承诺，可能随上游调整。路由与鉴权定义以 [Swagger YAML](docs/swagger.yaml) 或运行时 Swagger UI 为准；无法由 OpenAPI 完整表达的兼容边界列于上方。
-
-### 字段兼容矩阵
-
-以下矩阵以 2026-07-13 的 [OpenAI Responses](https://developers.openai.com/api/reference/resources/responses/methods/create)、[Chat Completions](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)、[Embeddings](https://developers.openai.com/api/reference/resources/embeddings/methods/create) 和 [Anthropic Messages](https://platform.claude.com/docs/en/api/messages/create) 为标准基线，并与当前实现逐项核对。
-
-这是一份兼容性快照，不替代 Swagger。标准接口和 OCI 上游都可能变化，最终行为以当前版本代码与实测为准。
-
-| 标记 | 含义 |
-| :---: | --- |
-| ✅ | 网关直接支持 |
-| ➡️ | 网关原样透传；是否生效由 OCI 上游决定 |
-| 🔄 | 网关进行字段或协议转换后支持 |
-| ◐ | 部分支持、存在前置条件或语义降级 |
-| ⚠️ | 请求可被接受，但字段会被忽略 |
-| ❌ | 网关在请求到达上游前拒绝 |
-
-<details>
-<summary><code>POST /ai/v1/responses</code> 对比 OpenAI Responses</summary>
-
-Responses 是“原始 JSON 直通 + 本地门禁”。除 `store` 外，网关不会重建请求体；未知顶层字段也会保留并送往 OCI。
-
-| 标准字段 | 状态 | 网关行为 |
-| --- | :---: | --- |
-| `model` | ◐ | 必须非空，还要通过密钥模型白名单并匹配可用渠道；随后原样透传 |
-| `input` | ➡️ | 支持标准的字符串或 item 数组，原始内容透传；网关不逐项保证 OCI 能处理所有 item 类型 |
-| `instructions`、`max_output_tokens` | ➡️ | 类型可解析后原样透传，不做范围或模型能力校验 |
-| `temperature`、`top_p`、`parallel_tool_calls` | ➡️ | 原样透传，不做取值范围校验 |
-| `text` / `text.format` / `text.verbosity` | ➡️ | 整个原始对象透传；结构化输出是否可用由 OCI 模型决定 |
-| `reasoning` | ➡️ | 整个原始对象透传；`effort` 不校验档位，`summary` 等字段不会被网关删除 |
-| `tool_choice` | ➡️ | 任意 JSON 原样透传，本地不校验枚举或结构 |
-| `context_management`、`include`、`max_tool_calls`、`metadata`、`moderation`、`prompt` | ➡️ | 网关未建模但会保留在原始请求中，由 OCI 决定是否接受 |
-| `prompt_cache_key`、`prompt_cache_retention`、`safety_identifier`、`service_tier` | ➡️ | 原样透传，不代表 OCI 一定实现 OpenAI 的对应语义 |
-| `stream_options`、`top_logprobs`、`truncation`、`user` | ➡️ | 原样透传，不做本地语义校验 |
-| `store` | 🔄 | 无论客户端传什么，上游请求都强制改写为 `false` |
-| `previous_response_id` | ❌ | 非空即返回 400；网关不保存历史响应 |
-| `conversation` | ◐ | 省略或 `null` 可通过；任何非 `null` 值返回 400 |
-| `background` | ◐ | `true` 返回 400；`false`、`null` 或省略时继续透传 |
-| `stream` | ◐ | 普通请求和 `function` 工具支持 SSE；含 `web_search` / `x_search` 时拒绝流式 |
-| `tools[].type=function` | ➡️ | 非流式和流式均可，工具对象原样透传 |
-| `tools[].type=web_search` / `x_search` | ◐ | 使用 xAI 服务端工具语义且仅支持非流式；`x_search` 不是 OpenAI 标准工具 |
-| 其他标准工具类型 | ❌ | `web_search_preview`、`file_search`、`computer`、`code_interpreter`、`image_generation`、`mcp`、`shell`、`custom` 等返回 400 |
-| 其他未知顶层字段 | ➡️ | 只要整个请求是合法 JSON，字段名、结构和数值都会保留 |
-
-响应边界：
-
-- 非流式成功响应不做转换，OCI JSON 原样返回；usage 解析只用于面板调用日志
-- SSE 事件逐行原样转发，不补 `data: [DONE]`，推理增量也不会被网关过滤
-- 流建立前最多切换三个渠道；流建立后中断不重试，客户端可能只收到部分事件
-- 未知模型返回 404、无渠道返回 503；上游错误会套入 OpenAI 风格错误体，不保证与标准 OpenAI 错误字段完全相同
-
-实现依据：[`airesponses.go`](internal/service/airesponses.go) · [`responses.go`](internal/aiwire/responses.go) · [`aigateway.go`](internal/api/aigateway.go)
-
-</details>
-
-<details>
-<summary><code>POST /ai/v1/chat/completions</code> 对比 OpenAI Chat Completions</summary>
-
-Chat Completions 会先转换为 Responses 请求，再把 OCI Responses 响应桥接回 Chat Completions 形态。
-
-| 标准字段 | 状态 | 网关行为 |
-| --- | :---: | --- |
-| `model` | ◐ | 必填，受密钥白名单和可用渠道限制；模型名保留到上游请求 |
-| `messages` | 🔄 | 必填并转换为 Responses `input` / `instructions` |
-| `system` / `developer` 消息 | ◐ | 文本按出现顺序合并为 `instructions`；块数组中的非文本内容被忽略 |
-| `user` / `assistant` 文本内容 | 🔄 | 字符串及 `text` 块分别转为 `input_text` / `output_text` |
-| `image_url` 内容块 | ◐ | URL 或 data URI 转为 `input_image`；`image_url.detail` 被忽略 |
-| `input_audio`、`file`、`refusal` 等内容块 | ❌ | 当前消息转换器不支持，返回 400 |
-| assistant `tool_calls` / `role=tool` | 🔄 | 转为 `function_call` / `function_call_output`，保留调用 ID、函数名和参数 |
-| 消息 `name`、`refusal`、`audio`、旧式 `function_call` | ⚠️ | 当前消息结构未建模，静默忽略 |
-| `max_completion_tokens` | 🔄 | 转为 `max_output_tokens`，优先于 `max_tokens` |
-| `max_tokens` | 🔄 | 未提供 `max_completion_tokens` 时转为 `max_output_tokens` |
-| `temperature`、`top_p`、`parallel_tool_calls` | ◐ | 原值写入 Responses 请求，但不校验范围或模型能力 |
-| `stream` | 🔄 | OCI Responses SSE 桥接为 `chat.completion.chunk`，末尾补 `data: [DONE]`；上游断流且尚无输出时自动降级非流式重做，结果按 chunk 序列一次推送 |
-| `stream_options.include_usage` | 🔄 | 控制网关在终块后追加 `choices: []` 的 usage 块 |
-| `stream_options.include_obfuscation` | ⚠️ | 未建模，静默忽略 |
-| `tools[].type=function` | ◐ | `name`、`description`、`parameters` 支持；`function.strict` 被忽略 |
-| `tools[].type=custom` 及其他工具 | ❌ | 只接受 `function`，其他类型返回 400 |
-| `tool_choice` | ◐ | 支持 `auto` / `none` / `required` 和具名 function；非法或未知值被静默忽略 |
-| `response_format` | ◐ | `json_object`、`json_schema` 转为 Responses `text.format`；未知类型交给 OCI 处理 |
-| `reasoning_effort` | ◐ | 转小写后映射为 `reasoning.effort`，不校验模型或档位 |
-| `store` | ⚠️ / 🔄 | 客户端字段被忽略，转换后的上游请求始终使用 `store:false` |
-| `stop`、`seed`、`n`、`frequency_penalty`、`presence_penalty` | ⚠️ | 静默忽略；`n` 因此恒为单个 choice |
-| `logprobs`、`top_logprobs`、`logit_bias`、`user` | ⚠️ | 静默忽略 |
-| `audio`、`modalities`、`prediction`、`metadata`、`moderation` | ⚠️ | 静默忽略 |
-| `prompt_cache_key`、`safety_identifier`、`service_tier`、`verbosity`、`web_search_options` | ⚠️ | 静默忽略 |
-| 其他未知字段 | ⚠️ | JSON 解码器不会拒绝未知字段，但转换后的上游请求不包含它们 |
-
-响应边界：
-
-- 非流式固定生成一个 `choices[0]`；文本会合并，函数调用转为 `tool_calls`
-- `finish_reason` 只生成 `stop`、`tool_calls`、`length`；其他上游终止原因不保留
-- reasoning 输出、logprobs、refusal、annotations、audio、service tier 和 system fingerprint 不返回
-- usage 保留 `prompt_tokens`、`completion_tokens`、`total_tokens` 和 `prompt_tokens_details.cached_tokens`
-- 已建立的流中断或上游 `response.failed` 不会转换成标准 SSE 错误事件
-
-实现依据：[`chatresponses.go`](internal/service/chatresponses.go) · [`openai.go`](internal/aiwire/openai.go) · [`aigateway.go`](internal/api/aigateway.go)
-
-</details>
-
-<details>
-<summary><code>POST /ai/v1/embeddings</code> 对比 OpenAI Embeddings</summary>
-
-| 标准字段 | 状态 | 网关行为 |
-| --- | :---: | --- |
-| `model` | ◐ | 必填，受密钥白名单限制，并且必须存在具有 `EMBEDDING` 能力的渠道 |
-| `input` 为字符串 | ✅ | 包装为单个输入后调用 OCI |
-| `input` 为字符串数组 | ✅ | 按原顺序调用 OCI |
-| `input` 为 token ID 数组或二维 token ID 数组 | ❌ | 只能解码字符串或字符串数组，绑定阶段返回 400 |
-| 空数组 / `null` | ❌ | 本地返回 400；空字符串不在本地拒绝，由 OCI 决定 |
-| `dimensions` | ◐ | 映射为 OCI 输出维度，不做范围或模型能力校验 |
-| `encoding_format=float` | ✅ | 返回 float 数组；省略时行为相同 |
-| `encoding_format=base64` | ❌ | 本地返回 400，不提供 base64 响应 |
-| `user` | ⚠️ | 能解析但不会传给 OCI |
-| 其他未知字段 | ⚠️ | 静默忽略 |
-
-响应使用标准的 `object:"list"`、`data[].object:"embedding"`、`index`、`model` 和可选 `usage` 外壳；向量为 `float32` 数组，不支持流式。
-
-实现依据：[`embeddings.go`](internal/aiwire/embeddings.go) · [`aigateway_chat.go`](internal/service/aigateway_chat.go) · [`aigateway.go`](internal/api/aigateway.go)
-
-</details>
-
-<details>
-<summary><code>POST /ai/v1/messages</code> 对比 Anthropic Messages</summary>
-
-网关接受 `Authorization: Bearer` 或 `x-api-key`，但不会校验或使用标准 Anthropic `anthropic-version`、`anthropic-beta` 请求头。
-
-| 标准字段 | 状态 | 网关行为 |
-| --- | :---: | --- |
-| `model` | ◐ | 用于模型与渠道选择，但空字符串不会在 handler 中按参数错误拒绝，通常最终返回模型不存在 |
-| `max_tokens` | 🔄 | 可缺省（缺省或 ≤0 时按默认值 8192），转换为 `max_output_tokens` |
-| `messages` | ◐ | 必须非空；角色、交替顺序和空内容不做完整校验 |
-| `system` | ◐ | 支持字符串或 text 块数组；多个文本块直接拼接，`cache_control` 等附加字段被忽略 |
-| `temperature`、`top_p` | ◐ | 写入 Responses 请求，不做取值范围或模型能力校验 |
-| `top_k` | ⚠️ | 能解析但不会传给上游 |
-| `stop_sequences` | ⚠️ | 能解析但不会传给上游；响应 `stop_sequence` 恒为 `null` |
-| `stream` | 🔄 | Responses SSE 桥接为 Anthropic 事件序列；上游断流且尚无输出时自动降级非流式重做，结果按事件序列一次推送 |
-| `tools` | ◐ | 每个工具都转换成 Responses `function`；自定义客户端工具可用，Anthropic 服务端工具类型不保留原语义 |
-| `tool_choice` | ◐ | 支持 `auto`、`any`、`none`、具名 `tool`；`disable_parallel_tool_use` 等附加字段被忽略 |
-| `metadata` | ⚠️ | 能解析但不会传给上游 |
-| `thinking` | ⚠️ | 顶层 thinking 配置不会控制上游思考预算 |
-| `output_config.effort` | 🔄 | 转小写后映射为 Responses `reasoning.effort` |
-| `output_config` 其他子字段 | ⚠️ | 未建模，静默忽略 |
-| `cache_control`、`container`、`inference_geo`、`service_tier` | ⚠️ | 标准 SDK 中存在，但当前请求结构未建模，静默忽略 |
-| 其他未知顶层字段 | ⚠️ | JSON 解码器接受，但转换后的上游请求不包含它们 |
-
-`messages[].content`：
-
-| 标准内容块 | 状态 | 网关行为 |
-| --- | :---: | --- |
-| 字符串 / `text` | 🔄 | user 转 `input_text`，assistant 历史转 `output_text` |
-| `image` | ◐ | 仅支持 `base64` 和 `url` source；缺字段或其他 source 类型返回 400 |
-| `tool_use` | 🔄 | 转为 `function_call`，保留 ID、名称和输入 |
-| `tool_result` | ◐ | 转为 `function_call_output`；块数组只拼接 text，`is_error` 和非文本结果丢失 |
-| `thinking` / `redacted_thinking` | ⚠️ | 历史思考块被删除，不进入上游上下文 |
-| `document`、服务端工具结果及其他未知块 | ❌ | 返回 400 |
-| `null` / 空块数组 | ◐ | 该消息可能从上游 input 中消失，不返回参数错误 |
-
-响应边界：
-
-- 非流式只把 Responses `output_text` 转成 `text`、`function_call` 转成 `tool_use`
-- `stop_reason` 只生成 `end_turn`、`tool_use`、`max_tokens`；`stop_sequence` 恒为 `null`
-- reasoning 不会生成 Anthropic `thinking` / `redacted_thinking` 块，也没有 signature
-- usage 只保留 `input_tokens`、`output_tokens` 和 `cache_read_input_tokens`，不提供 `cache_creation_input_tokens`
-- 流式输出标准事件骨架，但不生成 `thinking_delta` 和 `signature_delta`；上游错误事件与无终态断流会转成 Anthropic `error` 事件
-
-实现依据：[`anthresponses.go`](internal/service/anthresponses.go) · [`anthropic.go`](internal/aiwire/anthropic.go) · [`aigateway.go`](internal/api/aigateway.go)
-
-</details>
-
-`GET /ai/v1/models` 使用 OpenAI Models 列表外壳（`object`、`data[].id/object/created/owned_by`），但只返回当前渠道目录中通过分组、全局黑名单和密钥白名单筛选后的模型；网关不提供标准的单模型检索端点。
 
 ## API 与配置
 
@@ -414,29 +265,31 @@ OpenAPI 文件随仓库维护：[`docs/swagger.yaml`](docs/swagger.yaml) · [`do
 
 ### 环境变量
 
-| 变量 | 必填 | 默认值 | 说明 |
+| 变量 | 使用条件 | 默认值 | 说明 |
 | --- | :---: | --- | --- |
-| `DATA_KEY` | 是 | — | 敏感字段加密主密钥；必须持久保存，不能随意轮换 |
+| `DATA_KEY` | 必填 | — | 敏感字段加密主密钥；必须持久保存，不能随意轮换 |
-| `JWT_SECRET` | 是 | — | JWT 签名密钥；更换会使已有登录令牌失效 |
+| `JWT_SECRET` | 必填 | — | JWT 签名密钥；更换会使已有登录令牌失效 |
-| `ADMIN_USERNAME` | 否 | `admin` | 初始管理员用户名 |
+| `ADMIN_USERNAME` | 可选 | `admin` | 初始管理员用户名 |
 | `ADMIN_PASSWORD` | 首次启动 | — | 仅在数据库无用户时创建管理员，不会重置已有密码 |
-| `ADDR` | 否 | `:8080` | HTTP 监听地址 |
+| `ADDR` | 可选 | `:8080` | HTTP 监听地址 |
-| `DB_DRIVER` | 否 | `sqlite` | `sqlite` / `mysql` / `postgres`；后两者为 experimental |
+| `DB_DRIVER` | 可选 | `sqlite` | `sqlite` / `mysql` / `postgres`；后两者为 experimental |
 | `DB_PATH` | SQLite | `oci-portal.db` | SQLite 文件路径 |
-| `DB_DSN` | 外部数据库 | — | MySQL 需 `parseTime=True`；不要在日志或文档中暴露凭据 |
+| `DB_DSN` | MySQL / PostgreSQL | — | MySQL 需 `parseTime=True`；不要在日志或文档中暴露凭据 |
-| `PUBLIC_URL` | 否 | — | 面板公网基址，作为 OAuth 回调和日志回传引导的回退值 |
+| `PUBLIC_URL` | 可选 | — | 面板公网基址，作为 OAuth 回调和日志回传引导的回退值 |
-| `TZ` | 否 | 系统时区 | cron 表达式的解释时区；容器示例使用 `Asia/Shanghai` |
+| `TZ` | 可选 | 系统时区 | cron 表达式的解释时区；容器示例使用 `Asia/Shanghai` |
-| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | 否 | — | Go 标准出站代理变量；面板内显式代理配置优先用于对应业务 |
+| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | 可选 | — | Go 标准出站代理变量；面板内显式代理配置优先用于对应业务 |
-| `SWAGGER` | 否 | 关闭 | 设为 `1` 时开放 Swagger UI |
+| `SWAGGER` | 可选 | 关闭 | 设为 `1` 时开放 Swagger UI |
-| `GIN_MODE` | 否 | `release` | `debug` / `release` |
+| `GIN_MODE` | 可选 | `release` | `debug` / `release` |
 
 ## 升级与备份
 
-- 升级前同时备份 `.env` 和数据库；SQLite Compose 部署的数据文件为 `data/oci-portal.db`
+1. 阅读 [CHANGELOG](CHANGELOG.md)，确认目标版本的行为变化。
-- 保持 `DATA_KEY` 不变；只恢复数据库而没有原密钥，敏感字段无法解密
+2. 备份 `.env` 和数据库。SQLite Compose 部署建议先停止服务，再复制
-- 服务启动时会自动执行数据库迁移；跨版本升级前先阅读 [CHANGELOG](CHANGELOG.md)
+   `data/oci-portal.db`，避免在线复制产生不一致快照。
-- Compose 部署使用 `docker compose pull && docker compose up -d` 更新镜像
+3. 保持原 `DATA_KEY` 不变；只有数据库而没有对应密钥时，敏感字段无法解密。
-- OCI API Key 应遵循最小权限原则；生产环境保持 Swagger 关闭并限制管理面访问来源
+4. Compose 部署执行 `docker compose pull`，再执行 `docker compose up -d`；服务启动时
+   会自动完成数据库迁移。
+5. 生产环境保持 Swagger 关闭、限制管理面访问来源，并为 OCI API Key 配置最小权限。
 
 ## 开发
 
@@ -446,7 +299,7 @@ go vet ./...
 go test ./...
 
 # Handler 注释变更后重新生成唯一的对外 API 文档。
-go tool swag init -g cmd/server/main.go -o docs --parseInternal --parseDependency
+go tool swag init -g cmd/server/main.go -o docs --parseInternal --parseDependency --overridesFile docs/.swaggo
 ```
 
 - Go 后端规范与目录约定：[`AGENTS.md`](AGENTS.md) · [`.trellis/spec/backend/`](.trellis/spec/backend/)

docs/.swaggo

@@ -0,0 +1,6 @@
+// swag 全局类型替换:原始 JSON 与联合类型统一渲染为 AnyJSON(任意 JSON 值),
+// 避免 json.RawMessage 被误渲染成 byte 数组、联合类型暴露内部字段。
+replace encoding/json.RawMessage oci-portal/internal/aiwire.AnyJSON
+replace oci-portal/internal/aiwire.RespInput oci-portal/internal/aiwire.AnyJSON
+replace oci-portal/internal/aiwire.Content oci-portal/internal/aiwire.AnyJSON
+replace oci-portal/internal/aiwire.StringList oci-portal/internal/aiwire.AnyJSON

docs/AI网关.md

@@ -0,0 +1,583 @@
+<a id="top"></a>
+
+<div align="center">
+
+<img src="assets/logo.svg" width="88" alt="OCI Portal logo">
+
+# AI 网关
+
+**将多路 OCI Generative AI 统一为 OpenAI、Anthropic 与 xAI 兼容接口**
+
+![OpenAI](https://img.shields.io/badge/OpenAI-Responses%20%7C%20Chat-412991?logo=openai&logoColor=white)
+![Anthropic](https://img.shields.io/badge/Anthropic-Messages-D97757?logo=anthropic&logoColor=white)
+![xAI](https://img.shields.io/badge/xAI-TTS%20%7C%20Tools-111111?logo=x&logoColor=white)
+![Streaming](https://img.shields.io/badge/Streaming-SSE-0F9D58)
+
+[快速接入](#quick-start) · [端点一览](#endpoints) · [路由机制](#routing) · [Codex 接入](#codex) · [已知限制](#limitations) · [兼容矩阵](#compatibility)
+
+</div>
+
+> [!NOTE]
+> 网关集中处理密钥鉴权、模型访问控制、渠道调度与协议适配。路径、参数和
+> 响应结构以 [Swagger YAML](swagger.yaml) 或运行时 Swagger UI 为准；协议差异、
+> 兼容改写和实测边界以本文为准。
+
+| 文档属性 | 当前值 |
+| --- | --- |
+| 兼容快照 | **2026-07-16** |
+| API 基址 | `/ai/v1` |
+| 首选对话协议 | OpenAI Responses |
+| 会话模式 | 无状态，客户端携带完整上下文 |
+
+<a id="quick-start"></a>
+
+## 快速接入
+
+### 基础地址与鉴权
+
+网关密钥在管理面板中创建。连接信息如下：
+
+| 项目 | 配置 |
+| --- | --- |
+| Base URL | `https://<网关地址>/ai/v1` |
+| Bearer 鉴权 | `Authorization: Bearer sk-...` |
+| API Key 鉴权 | `x-api-key: sk-...` |
+
+密钥可绑定渠道分组和模型白名单。全局模型黑名单会同时作用于模型列表、
+请求路由和探测候选；开启「过滤弃用模型」后，OCI 已宣布弃用的模型也会从
+列表与路由中移除。
+
+可先用模型列表验证地址与密钥：
+
+```bash
+curl "https://<网关地址>/ai/v1/models" \
+  -H "Authorization: Bearer $OCI_PORTAL_KEY"
+```
+
+再发起一条最小 Responses 请求；请将示例模型替换为模型列表中的可见模型：
+
+```bash
+curl "https://<网关地址>/ai/v1/responses" \
+  -H "Authorization: Bearer $OCI_PORTAL_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"xai.grok-4.3","input":"你好，请用一句话介绍自己。"}'
+```
+
+<a id="endpoints"></a>
+
+## 端点一览
+
+| 协议域 | 端点 | 角色 | 流式 |
+| --- | --- | --- | :---: |
+| 对话 | `POST /ai/v1/responses` | OpenAI Responses，无状态主接口 | SSE |
+| 对话 | `POST /ai/v1/chat/completions` | OpenAI Chat Completions 兼容层 | SSE |
+| 对话 | `POST /ai/v1/messages` | Anthropic Messages 转换层 | SSE |
+| 向量 | `POST /ai/v1/embeddings` | OpenAI Embeddings | — |
+| 语音 | `POST /ai/v1/audio/speech` | OpenAI Audio Speech 外壳 | — |
+| 语音 | `POST /ai/v1/tts` | xAI TTS 格式转换层 | — |
+| 检索 | `POST /ai/v1/rerank` | Cohere / Jina 风格文档重排 | — |
+| 安全 | `POST /ai/v1/moderations` | OpenAI 外壳映射 OCI Guardrails | — |
+| 发现 | `GET /ai/v1/models` | 当前密钥可见模型列表 | — |
+
+### 如何选择协议
+
+| 使用场景 | 推荐接口 |
+| --- | --- |
+| 新客户端、推理模型、服务端工具 | **Responses** |
+| Anthropic SDK、Claude 生态客户端 | **Messages** |
+| 仅支持旧 OpenAI 对话协议的客户端 | **Chat Completions** |
+| 向量、语音、重排与安全审核 | 对应专用端点 |
+
+<a id="routing"></a>
+
+## 路由与全局行为
+
+### 请求链路
+
+```mermaid
+flowchart LR
+    A[客户端] --> B[网关密钥鉴权]
+    B --> C[分组、白名单与全局过滤]
+    C --> D[模型与能力匹配]
+    D --> E[选择最小 Priority]
+    E --> F[同优先级按 Weight 加权]
+    F --> G[OCI GenAI]
+    G -. 可重试且流未建立 .-> D
+```
+
+单次请求最多尝试三个渠道。模型不可用、限流、上游服务错误或网络错误可触发
+换渠道；流式连接建立后不会切换渠道重试。
+
+### 全局兼容边界
+
+| 主题 | 当前行为 |
+| --- | --- |
+| 会话状态 | 网关不保存会话历史，客户端必须在每次请求中携带完整上下文 |
+| 上游存储 | Responses 请求始终强制 `store:false` |
+| 有状态字段 | Responses 拒绝非空 `previous_response_id`、非 `null` 的 `conversation` 和 `background:true` |
+| 对话上游 | 对话请求统一进入 OCI OpenAI 兼容面，当前供给以 `xai.`、`meta.`、`openai.` 前缀模型为主 |
+| 推理强度 | Responses `reasoning.effort`、Messages `output_config.effort`、Chat `reasoning_effort` 会传给上游；可用档位由模型决定 |
+| 服务端工具 | Responses 支持 `web_search`、`x_search`、`code_interpreter` 和远程 `mcp`；命名容器管理与 File Search 不提供 |
+| 文件输入 | `input_file` 会被 OCI ZDR 形态拒绝，详见[已知限制](#limitations) |
+| Chat 定位 | Chat Completions 只承担协议转换与兼容修复；新能力优先落在 Responses 与 Messages |
+
+### 可配置运行策略
+
+| 策略 | 默认行为 | 配置入口 |
+| --- | --- | --- |
+| Responses 流式保险丝 | 开启；阈值 `60 KB`，按 `instructions` 与 `tools` 两个字段的原始 JSON 值计算 | **设置 → AI → 流式保险丝** |
+| Grok 服务端搜索 | 对 `xai.` 模型默认注入 `web_search` 与 `x_search`；同名工具不重复覆盖 | **设置 → AI → Grok 服务端搜索工具** |
+| 弃用模型过滤 | 开启后从模型列表、请求路由与探测候选中统一排除 | **设置 → AI → 模型治理** |
+
+<a id="codex"></a>
+
+## Codex 接入
+
+### 主配置
+
+自定义模型提供方必须写在用户级 `~/.codex/config.toml`。Codex 的项目级
+`.codex/config.toml` 不允许改写 `model_provider` 与 `model_providers`。
+
+```toml
+model = "xai.grok-4.3"
+model_provider = "oci"
+
+[model_providers.oci]
+name = "oci-portal"
+base_url = "https://<网关地址>/ai/v1"
+env_key = "OCI_PORTAL_KEY"
+wire_api = "responses"
+```
+
+### 自定义子代理
+
+新版 Codex 可在 `~/.codex/agents/` 或项目级 `.codex/agents/` 放置独立 TOML
+文件，并为子代理覆盖模型。每个文件都需要 `name`、`description` 和
+`developer_instructions`：
+
+```toml
+# .codex/agents/oci-worker.toml
+name = "oci-worker"
+description = "通过 OCI Portal 网关执行通用开发任务。"
+developer_instructions = """
+完成被分配的开发任务，保持改动聚焦，并返回验证结果。
+"""
+model = "xai.grok-4.3"
+```
+
+> [!IMPORTANT]
+> `Codex CLI 0.144.1` 已实测主会话和 multi-agent 子代理全链路可用。
+> 内置 worker 可能先尝试 `gpt-5.6-luna` 或 `gpt-5.4`；网关没有对应渠道时
+> 会出现少量 404，随后由 Codex 回落到可用模型。自定义 agent 的模型覆盖是否
+> 直接生效取决于 Codex 版本；0.144.1 的实测主要依赖自动回落。
+
+Codex 工具兼容现状：
+
+| 工具形态 | 网关处理 | 验证状态 |
+| --- | --- | --- |
+| `function` | 原样透传 | 可用 |
+| `namespace` | 子工具拍平为限定名 `function`，响应时还原 | multi-agent 已端到端实测；MCP 同路径有单测 |
+| `custom` | 顶层普通工具转换为 `function`，调用与历史记录双向回转 | 可用，但存在降级边界 |
+| `custom:apply_patch` | 直接剥离，让模型回落到其他编辑方式 | 有意限制 |
+| `tool_search` | namespace 已完整展开，目录搜索语义冗余，直接剥离 | 有意降级 |
+
+配置语法参考 [Codex Subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents)
+与 [Codex Advanced Configuration](https://learn.chatgpt.com/docs/config-file/config-advanced)。
+
+<a id="limitations"></a>
+
+## 已知限制
+
+### `instructions` / `tools` 大体量流式断流
+
+> [!WARNING]
+> `instructions` 与 `tools` 两个字段的原始 JSON 值合计超过约 **64.5 KB** 时，
+> 上游流式请求可能在推理阶段静默断连：连接直接 EOF，不发送 `error` 或终态事件。
+> 同一请求改为非流式实测可正常完成；单独扩大 `input` 未触发该限制。
+
+该问题于 2026-07-13 通过字节级二分定位，2026-07-16 在 Chicago 复测仍存在：
+`70.4 KB` 断流、`59.7 KB` 正常，API Key 与签名鉴权表现一致。本文及设置页中的
+`KB` 均按 `1024 B` 计算。
+
+| 协议 | 网关保护 | 客户端表现 |
+| --- | --- | --- |
+| Responses | 保险丝默认开启；超过 `60 KB` 时改走非流式上游，并合成最小 SSE 序列 | 结果语义保留，但不再增量输出 |
+| Chat Completions / Messages | 客户端尚未收到内容就断流时，自动改用非流式重做 | 合成对应 chunk / event 序列 |
+| 已开始输出的流 | 无法透明重试；调用日志记录提前终止 | 客户端可能只收到部分事件 |
+
+Responses 合成的最小事件序列为：`response.created` →
+`response.output_item.done` → `response.completed`。保险丝可在
+**设置 → AI → 流式保险丝** 调整或关闭。
+
+<details>
+<summary><strong>历史问题：完整请求体体积断流（已由上游修复）</strong></summary>
+
+2026-07-15 曾在完整请求体约 `82 KB`（含 `input`）时观测到纯体积流式断流。
+2026-07-16 复核 `83 KB`、真实 Codex 形态 `104.5 KB`、`200 KB` 与 `400 KB`
+请求均正常完成；Chicago 与 Phoenix、签名与 API Key 两条路径结果一致。
+
+</details>
+
+### `multi-agent` 加密推理内容流式断流
+
+> [!WARNING]
+> 当 `multi-agent` 请求同时启用 `stream: true` 与
+> `include: ["reasoning.encrypted_content"]` 时，上游可能在序列化大体量
+> `encrypted_content` 事件期间静默断开连接，且不返回 `error` 或终态事件。
+>
+> 已复现场景中的断点位于 `output_index: 8` 附近：第三次搜索结束后，上游准备
+> 发送较大的加密推理块时连接被中止。`multi-agent` 产生的加密推理内容体积较大，
+> 因而更容易暴露该上游流式序列化缺陷。
+
+### ZDR 与文件输入
+
+Responses 的 `input_file` 内容块（`file_url` / `file_data`）实测会被上游拒绝：
+
+```text
+File content is currently unsupported for ZDR customers
+```
+
+网关强制 `store:false`，属于 ZDR 请求形态，因此当前不能通过该端点上传或引用文件。
+
+<a id="compatibility"></a>
+
+## 字段兼容矩阵
+
+> [!IMPORTANT]
+> 本项目提供兼容接口，而不是 OpenAI、Anthropic 或 xAI 协议的完整实现。部分 OCI
+> OpenAI 兼容行为来自实测，未见 Oracle 文档合同，可能随上游调整。
+
+### 矩阵索引
+
+[Responses](#compat-responses) · [Chat Completions](#compat-chat) · [Messages](#compat-messages) · [Embeddings](#compat-embeddings) · [语音生成](#compat-audio) · [Rerank](#compat-rerank) · [Moderations](#compat-moderations) · [Models](#compat-models)
+
+<details>
+<summary><strong>展开参考规格</strong></summary>
+
+- [OpenAI Responses](https://developers.openai.com/api/reference/resources/responses/methods/create)
+- [OpenAI Chat Completions](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)
+- [OpenAI Embeddings](https://developers.openai.com/api/reference/resources/embeddings/methods/create)
+- [OpenAI Audio Speech](https://developers.openai.com/api/reference/resources/audio/methods/speech)
+- [OpenAI Moderations](https://developers.openai.com/api/reference/resources/moderations/methods/create)
+- [Anthropic Messages](https://platform.claude.com/docs/en/api/messages/create)
+- [Cohere Rerank](https://docs.cohere.com/reference/rerank)
+
+</details>
+
+| 标记 | 含义 |
+| :---: | --- |
+| ✅ | 网关直接支持 |
+| ➡️ | 原样保留或透传；是否生效由 OCI 上游决定 |
+| 🔄 | 网关执行字段或协议转换后支持 |
+| ◐ | 部分支持、存在前置条件或语义降级 |
+
+<a id="compat-responses"></a>
+
+### OpenAI Responses
+
+**`POST /ai/v1/responses` · 无状态主接口**
+
+网关以原始 JSON 为基底保留未知字段，但会强制关闭上游存储，并执行下表列出的
+Codex 工具兼容改写。请求会重新编码，不承诺字节级原样转发。
+
+<details open>
+<summary><strong>核心字段</strong></summary>
+
+| 标准字段 | 状态 | 网关行为 |
+| --- | :---: | --- |
+| `model` | ◐ | 必填；通过密钥白名单并匹配可用渠道后送往上游 |
+| `input` | ➡️ | 支持字符串或 item 数组；普通内容保留，Codex 工具历史项可能改写 |
+| `instructions`、`max_output_tokens` | ➡️ | 类型可解析后保留，不做范围或模型能力校验 |
+| `temperature`、`top_p` | ➡️ | 保留，不做取值范围校验 |
+| `parallel_tool_calls` | ◐ | 通常保留；若全部工具被剥离，则与 `tool_choice` 一并删除 |
+| `text` / `text.format` / `text.verbosity` | ➡️ | 整个对象保留；是否生效由 OCI 模型决定 |
+| `reasoning` | ➡️ | 整个对象保留；`effort` 不校验档位 |
+| `tool_choice` | ◐ | 普通形态保留；namespace 对象会重限定，全部工具被剥离时删除 |
+| `store` | 🔄 | 无论客户端传什么，上游请求都强制改写为 `false` |
+| `stream` | ◐ | 支持 SSE；`instructions` 与 `tools` 的原始 JSON 值合计超过保险丝阈值时，预防性改走非流式上游（默认开启、`60 KB`，见[已知限制](#limitations)） |
+| 其余标准与未知顶层字段 | ➡️ | `context_management`、`include`、`metadata`、`prompt`、`prompt_cache_key`、`service_tier`、`truncation`、`user` 等均保留，由 OCI 决定是否接受 |
+
+</details>
+
+<details>
+<summary><strong>工具兼容</strong></summary>
+
+| 工具或参数 | 状态 | 网关行为 |
+| --- | :---: | --- |
+| `tools[].type=function` | ➡️ | 非流式与流式均可，工具对象保留 |
+| `web_search` / `x_search` / `code_interpreter` | ◐ | Oracle 文档化的 xAI 服务端工具；参数与限制遵循 [xAI 规格](https://docs.oracle.com/en-us/iaas/Content/generative-ai/get-started-agents.htm#xai-compatible-tools) |
+| `tools[].type=mcp` | ➡️ | 远程 MCP 由上游直连，`server_url`、`require_approval`、`authorization` 等保留 |
+| `tools[].type=namespace` | 🔄 | 子 `function` 上提并限定命名；响应、历史调用和 `tool_choice` 会反向还原；组内非 `function` 子工具被剥离 |
+| `tools[].type=custom` | ◐ | 顶层非 `apply_patch` 工具转为带 `input` schema 的 `function`；响应与多轮历史双向回转；`format` 会删除 |
+| `custom:apply_patch` | ◐ | 整体剥离；Grok 系未针对 Codex 补丁格式训练，模型应回落其他编辑方式 |
+| `tools[].type=tool_search` | ◐ | 请求可被接受，但工具本身直接剥离 |
+| `web_search.external_web_access=true` | 🔄 | 删除上游不识别的字段，保留 `web_search` |
+| `web_search.external_web_access=false` | ◐ | 上游没有“仅缓存检索”对应能力，按不越权原则剥离整个工具 |
+
+</details>
+
+本地拒绝（返回 400）：
+
+- 非空 `previous_response_id`
+- 非 `null` 的 `conversation`
+- `background:true`
+- 未列入白名单的工具类型，例如 `web_search_preview`、`file_search`、
+  `computer`、`image_generation`、`shell`
+
+响应边界：
+
+- 无工具还原且未触发流式升级时，普通响应保持直通语义
+- namespace / custom 调用会在非流式响应与命中的 SSE `data` 事件中定向还原
+- 普通 SSE 不补 `data: [DONE]`，reasoning 增量不会被过滤
+- 未知模型返回 404，无可用渠道返回 503
+- 上游错误使用 OpenAI 风格错误外壳，但不保证字段与标准 OpenAI 完全一致
+
+<a id="compat-chat"></a>
+
+### OpenAI Chat Completions
+
+**`POST /ai/v1/chat/completions` · 存量客户端兼容层**
+
+请求先转换为 Responses，再将 OCI Responses 响应桥接回 Chat Completions。
+只有下表字段会进入上游请求。
+
+<details>
+<summary><strong>展开字段矩阵</strong></summary>
+
+| 标准字段 | 状态 | 网关行为 |
+| --- | :---: | --- |
+| `model` | ◐ | 必填，受密钥白名单和可用渠道限制 |
+| `messages` | 🔄 | 必填，转换为 Responses `input` / `instructions` |
+| `system` / `developer` 消息 | ◐ | 文本按顺序合并为 `instructions`；块数组中的非文本内容忽略 |
+| `user` / `assistant` 文本 | 🔄 | 字符串和 `text` 块分别转为 `input_text` / `output_text` |
+| `image_url` | ◐ | URL 或 data URI 转为 `input_image`；`detail` 忽略 |
+| assistant `tool_calls` / `role=tool` | 🔄 | 转为 `function_call` / `function_call_output` |
+| `max_completion_tokens` | 🔄 | 转为 `max_output_tokens`，优先于 `max_tokens` |
+| `max_tokens` | 🔄 | 未提供 `max_completion_tokens` 时转为 `max_output_tokens` |
+| `temperature`、`top_p`、`parallel_tool_calls` | ◐ | 写入 Responses，不校验范围或模型能力 |
+| `stream` | 🔄 | Responses SSE 转为 `chat.completion.chunk`，末尾补 `data: [DONE]` |
+| `stream_options.include_usage` | 🔄 | 控制终块后的独立 usage 块 |
+| `tools[].type=function` | ◐ | 支持 `name`、`description`、`parameters`；`strict` 忽略 |
+| `tool_choice` | ◐ | 支持 `auto` / `none` / `required` 和具名 function |
+| `response_format` | ◐ | `json_object`、`json_schema` 转为 Responses `text.format` |
+| `reasoning_effort` | ◐ | 转小写后映射为 `reasoning.effort` |
+| `store` | 🔄 | 客户端取值忽略，上游始终使用 `store:false` |
+
+</details>
+
+不支持（返回 400）：`input_audio`、`file`、`refusal` 等消息内容块，以及
+`function` 之外的工具类型。
+
+<details>
+<summary><strong>静默忽略字段</strong></summary>
+
+消息级 `name` / `refusal` / `audio` / 旧式 `function_call`；`stop`、`seed`、
+`n`、`frequency_penalty`、`presence_penalty`、`logprobs`、`top_logprobs`、
+`logit_bias`；`user`、`audio`、`modalities`、`prediction`、`metadata`、
+`moderation`、`prompt_cache_key`、`safety_identifier`、`service_tier`、
+`verbosity`、`web_search_options`、`stream_options.include_obfuscation`
+及其他未知字段。
+
+</details>
+
+响应边界：
+
+- 非流式固定生成一个 `choices[0]`；文本合并，函数调用转为 `tool_calls`
+- `finish_reason` 只生成 `stop`、`tool_calls`、`length`
+- reasoning、logprobs、refusal、annotations、audio、service tier 和 system fingerprint 不返回
+- usage 保留 `prompt_tokens`、`completion_tokens`、`total_tokens` 与
+  `prompt_tokens_details.cached_tokens`
+- 已开始输出的流中断不会转换成标准 SSE 错误事件
+
+<a id="compat-messages"></a>
+
+### Anthropic Messages
+
+**`POST /ai/v1/messages` · Anthropic 协议转换层**
+
+支持 `Authorization: Bearer` 与 `x-api-key`，但不校验或使用
+`anthropic-version`、`anthropic-beta` 请求头。
+
+<details>
+<summary><strong>展开顶层字段矩阵</strong></summary>
+
+| 标准字段 | 状态 | 网关行为 |
+| --- | :---: | --- |
+| `model` | ◐ | 用于模型与渠道选择；空字符串通常最终返回模型不存在 |
+| `max_tokens` | 🔄 | 缺省或 ≤0 时使用 8192，再转为 `max_output_tokens` |
+| `messages` | ◐ | 必须非空；角色、交替顺序和空内容不做完整校验 |
+| `system` | ◐ | 支持字符串或 text 块数组；文本块拼接，附加字段忽略 |
+| `temperature`、`top_p` | ◐ | 写入 Responses，不校验范围或模型能力 |
+| `stream` | 🔄 | Responses SSE 桥接为 Anthropic 标准事件序列 |
+| `tools` | ◐ | 每个工具转为 Responses `function`；服务端工具类型不保留原语义 |
+| `tool_choice` | ◐ | 支持 `auto`、`any`、`none`、具名 `tool` |
+| `output_config.effort` | 🔄 | 转小写后映射为 `reasoning.effort` |
+
+</details>
+
+内容块兼容：
+
+| `messages[].content` | 状态 | 网关行为 |
+| --- | :---: | --- |
+| 字符串 / `text` | 🔄 | user 转 `input_text`，assistant 历史转 `output_text` |
+| `image` | ◐ | 仅支持 `base64` 与 `url` source |
+| `tool_use` | 🔄 | 转为 `function_call`，保留 ID、名称与输入 |
+| `tool_result` | ◐ | 转为 `function_call_output`；块数组只拼接 text，`is_error` 与非文本结果丢失 |
+| `null` / 空块数组 | ◐ | 消息可能从上游 input 中消失，不返回参数错误 |
+
+不支持（返回 400）：`document`、服务端工具结果及未知内容块。历史
+`thinking` / `redacted_thinking` 会删除。
+
+<details>
+<summary><strong>静默忽略字段</strong></summary>
+
+`top_k`、`stop_sequences`、`metadata`、`thinking`、`output_config` 其余子字段、
+`cache_control`、`container`、`inference_geo`、`service_tier` 及其他未知顶层字段。
+
+</details>
+
+响应边界：
+
+- 仅将 Responses `output_text` 转为 `text`，`function_call` 转为 `tool_use`
+- `stop_reason` 只生成 `end_turn`、`tool_use`、`max_tokens`
+- 不生成 Anthropic thinking / signature 内容块
+- usage 只保留 `input_tokens`、`output_tokens` 与 `cache_read_input_tokens`
+- 流式上游错误与无终态断流会转成 Anthropic `error` 事件
+
+<a id="compat-embeddings"></a>
+
+### OpenAI Embeddings
+
+**`POST /ai/v1/embeddings` · 向量化专用端点**
+
+| 标准字段 | 状态 | 网关行为 |
+| --- | :---: | --- |
+| `model` | ◐ | 必填，受白名单限制，且需要 `EMBEDDING` 能力渠道 |
+| 字符串 `input` | ✅ | 包装为单个输入后调用 OCI |
+| 字符串数组 `input` | ✅ | 按原顺序调用 OCI |
+| `dimensions` | ◐ | 映射为 OCI 输出维度，不校验范围或模型能力 |
+| `encoding_format=float` | ✅ | 返回 float 数组；省略时相同 |
+
+不支持（返回 400）：token ID 数组、空数组、`null` 和
+`encoding_format=base64`。`user` 与其他未知字段静默忽略。
+
+响应使用标准 `object:"list"` 外壳，向量为 `float32` 数组，不支持流式。
+
+<a id="compat-audio"></a>
+
+### 语音生成
+
+两个端点最终使用同一 OCI xAI TTS 上游与渠道调度：
+
+#### OpenAI Audio Speech
+
+**`POST /ai/v1/audio/speech`**
+
+| 标准字段 | 状态 | 网关行为 |
+| --- | :---: | --- |
+| `model` | ◐ | 必填，受白名单限制，需要 `TTS` 能力渠道；当前为 `xai.grok-tts` |
+| `input` | ◐ | 必填非空，随后保留 |
+| `voice` | ➡️ | 使用 xAI 音色 `ara` / `eve` / `leo` / `rex` / `sal` |
+| `response_format` | ➡️ | 实测 `mp3` 可用，其余格式由上游决定 |
+| `language`（扩展） | 🔄 | 上游必填；缺省时注入 `"auto"` |
+| `speed`、`instructions` 与未知字段 | ➡️ | 保留，是否生效由上游决定 |
+
+#### xAI TTS
+
+**`POST /ai/v1/tts`**
+
+接受 [xAI 官方 TTS 格式](https://docs.x.ai/developers/model-capabilities/audio/text-to-speech)，
+转换为 OpenAI 兼容形态后进入同一上游。
+
+| 字段 | 状态 | 网关行为 |
+| --- | :---: | --- |
+| `text` | 🔄 | 必填非空，转换为 `input` |
+| `language` | ◐ | 必填，接受 BCP-47 或 `auto` |
+| `voice_id` | 🔄 | 转为 `voice`；缺省交给上游默认值 `eve` |
+| `output_format` | ➡️ | `{codec, sample_rate, bit_rate}` 对象保留，实测生效 |
+| `speed` | ➡️ | 保留，实测可用 |
+| `model`（网关扩展） | ◐ | 缺省注入 `xai.grok-tts`，可覆盖，受白名单限制 |
+| 其余未知字段 | ➡️ | 保留，是否生效由上游决定 |
+
+共同响应边界：
+
+- 成功响应为一次性完整音频，`Content-Type` 透传上游，缺省 `audio/mpeg`
+- 不提供 HTTP 流式音频或 WebSocket 代理
+- 无 token 用量口径，调用日志只记时延与渠道
+
+<a id="compat-rerank"></a>
+
+### Rerank
+
+**`POST /ai/v1/rerank` · Cohere / Jina 风格协议**
+
+上游走 OCI typed 面，模型为 `cohere.rerank-v4.0-pro` 或 `-fast`。
+
+| 字段 | 状态 | 网关行为 |
+| --- | :---: | --- |
+| `model` | ◐ | 必填，受白名单限制，需要 `RERANK` 能力渠道 |
+| `query` | ✅ | 必填非空 |
+| `documents` | ◐ | 仅接受字符串数组；旧版 `{"text": ...}` 对象数组返回 400 |
+| `top_n` | ✅ | 可选，限制返回条数 |
+| `return_documents` | ✅ | 为 `true` 时回带原文 |
+
+`max_tokens_per_doc` 与未知字段静默忽略。响应按相关度降序，
+`results[].index` 指向输入下标，`relevance_score` 为 0～1 浮点；无 token 用量口径。
+
+<a id="compat-moderations"></a>
+
+### Moderations
+
+**`POST /ai/v1/moderations` · OpenAI 外壳映射 OCI Guardrails**
+
+| 标准字段 | 状态 | 网关行为 |
+| --- | :---: | --- |
+| 字符串 `input` | ✅ | 单条审核 |
+| 字符串数组 `input` | ✅ | 逐条审核，单次 1～8 条 |
+
+不支持（返回 400）：多模态 input、空字符串条目、空数组或超过 8 条。
+`model` 接受但忽略，不参与白名单判断。
+
+响应边界：
+
+- categories 使用 OCI 原生维度 `overall` / `blocklist` / `prompt_injection`
+- 任一维度得分 ≥ 0.5 时 `flagged=true`
+- PII 命中放在扩展字段 `results[].pii`，包含 `text`、`label`、`score`、
+  `offset` 与 `length`，不参与 `flagged`
+- 实测中文人名与手机号识别较弱，英文 PII 识别正常
+- 响应 `model` 恒为 `oci-guardrails`
+
+<a id="compat-models"></a>
+
+### Models
+
+**`GET /ai/v1/models` · 当前密钥可见模型列表**
+
+响应使用 OpenAI Models 列表外壳，只返回同时通过以下条件的模型：
+
+1. 存在于当前渠道目录
+2. 匹配密钥绑定的渠道分组
+3. 不在全局模型黑名单
+4. 命中密钥模型白名单（配置时）
+5. 未被「过滤弃用模型」开关排除
+
+网关不提供标准的单模型检索端点。
+
+<a id="implementation"></a>
+
+## 附录：实现索引
+
+| 端点 / 能力 | 主要实现 |
+| --- | --- |
+| Responses 直通与 Codex 工具兼容 | [`airesponses.go`](../internal/service/airesponses.go) · [`responses.go`](../internal/aiwire/responses.go) |
+| Chat Completions 转换 | [`chatresponses.go`](../internal/service/chatresponses.go) · [`openai.go`](../internal/aiwire/openai.go) |
+| Anthropic Messages 转换 | [`anthresponses.go`](../internal/service/anthresponses.go) · [`anthropic.go`](../internal/aiwire/anthropic.go) |
+| 渠道路由与 Embeddings | [`aigateway_chat.go`](../internal/service/aigateway_chat.go) |
+| TTS 上游 | [`genai_speech.go`](../internal/oci/genai_speech.go) · [`aigateway_extras.go`](../internal/service/aigateway_extras.go) |
+| Rerank / Moderations 上游 | [`genai_guard.go`](../internal/oci/genai_guard.go) · [`rerank.go`](../internal/aiwire/rerank.go) · [`moderations.go`](../internal/aiwire/moderations.go) |
+| HTTP Handler 与流式桥接 | [`aigateway.go`](../internal/api/aigateway.go) · [`aigateway_extras.go`](../internal/api/aigateway_extras.go) |
+
+本文是兼容性快照，不替代 Swagger。标准接口、Codex 客户端与 OCI 上游均可能
+变化，最终行为以当前版本代码、运行时 Swagger 和实测结果为准。
+
+[返回顶部](#top)

go.mod

@@ -8,7 +8,7 @@ require (
 	github.com/glebarez/sqlite v1.11.0
 	github.com/golang-jwt/jwt/v5 v5.3.1
 	github.com/gorilla/websocket v1.5.3
-	github.com/oracle/oci-go-sdk/v65 v65.120.0
+	github.com/oracle/oci-go-sdk/v65 v65.121.0
 	github.com/pquerna/otp v1.5.0
 	github.com/robfig/cron/v3 v3.0.1
 	github.com/swaggo/files v1.0.1

go.sum

@@ -119,8 +119,8 @@ github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJ
 github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
 github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
 github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e/go.mod h1:zD1mROLANZcx1PVRCS0qkT7pwLkGfwJo4zjcN/Tysno=
-github.com/oracle/oci-go-sdk/v65 v65.120.0 h1:qpGdts2Yleg6TdmtxXkL8MAnsASO+SOG+iG/Nd8wUGk=
+github.com/oracle/oci-go-sdk/v65 v65.121.0 h1:1J+5ARgrodrx8kzFy/hxznaoUzz43jr0EestCzEaOHw=
-github.com/oracle/oci-go-sdk/v65 v65.120.0/go.mod h1:Pzy+BpgkDesvGZXEHgslwhIYobHCPHg6wRta1mWnlqQ=
+github.com/oracle/oci-go-sdk/v65 v65.121.0/go.mod h1:Pzy+BpgkDesvGZXEHgslwhIYobHCPHg6wRta1mWnlqQ=
 github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
 github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=

internal/aiwire/anyjson.go

@@ -0,0 +1,5 @@
+package aiwire
+
+// AnyJSON 仅供 swagger 文档渲染:经 .swaggo 全局替换,代表任意 JSON 值
+// (json.RawMessage 与 string/数组联合类型),运行时代码不使用。
+type AnyJSON struct{}

internal/aiwire/moderations.go

@@ -0,0 +1,63 @@
+package aiwire
+
+import "encoding/json"
+
+// ModerationsRequest 是 /ai/v1/moderations 请求体;input 兼容 OpenAI 的
+// string 与 []string 两种形态,model 字段接受但忽略(上游为服务级 API)。
+type ModerationsRequest struct {
+	Model string          `json:"model,omitempty"`
+	Input json.RawMessage `json:"input"`
+}
+
+// ModerationPii 是一处 PII 命中(OCI 扩展,OpenAI 协议无对应物)。
+type ModerationPii struct {
+	Text   string  `json:"text"`
+	Label  string  `json:"label"`
+	Score  float64 `json:"score"`
+	Offset int     `json:"offset"`
+	Length int     `json:"length"`
+}
+
+// ModerationResult 是一条输入的审核结果:categories / category_scores 用
+// OCI 原生维度(overall / blocklist / prompt_injection),pii 为扩展字段。
+type ModerationResult struct {
+	Flagged        bool               `json:"flagged"`
+	Categories     map[string]bool    `json:"categories"`
+	CategoryScores map[string]float64 `json:"category_scores"`
+	Pii            []ModerationPii    `json:"pii,omitempty"`
+}
+
+// ModerationsResponse 是 /ai/v1/moderations 响应体(OpenAI moderations 外壳)。
+type ModerationsResponse struct {
+	ID      string             `json:"id"`
+	Model   string             `json:"model"`
+	Results []ModerationResult `json:"results"`
+}
+
+// SpeechRequest 描述 /ai/v1/audio/speech 请求体的已知字段(文档用途)。
+// 直通端点实际按原样透传,未列字段与 xAI 专属参数(如 output_format)同样保留。
+type SpeechRequest struct {
+	Model          string `json:"model"`
+	Input          string `json:"input"`
+	Voice          string `json:"voice,omitempty"`
+	ResponseFormat string `json:"response_format,omitempty"`
+	Language       string `json:"language,omitempty"`
+}
+
+// TtsRequest 描述 /ai/v1/tts 请求体的已知字段(xAI 官方 TTS 格式,文档用途)。
+// model 为网关扩展字段(缺省 xai.grok-tts);未列字段原样透传上游。
+type TtsRequest struct {
+	Model        string           `json:"model,omitempty"`
+	Text         string           `json:"text"`
+	Language     string           `json:"language"`
+	VoiceID      string           `json:"voice_id,omitempty"`
+	OutputFormat *TtsOutputFormat `json:"output_format,omitempty"`
+	Speed        float64          `json:"speed,omitempty"`
+}
+
+// TtsOutputFormat 是 xAI TTS 输出格式配置(缺省 MP3 24kHz/128kbps)。
+type TtsOutputFormat struct {
+	Codec      string `json:"codec,omitempty"`
+	SampleRate int    `json:"sample_rate,omitempty"`
+	BitRate    int    `json:"bit_rate,omitempty"`
+}

internal/aiwire/rerank.go

@@ -0,0 +1,28 @@
+package aiwire
+
+// RerankRequest 是 /ai/v1/rerank 请求体(Jina / Cohere 通行风格)。
+type RerankRequest struct {
+	Model           string   `json:"model"`
+	Query           string   `json:"query"`
+	Documents       []string `json:"documents"`
+	TopN            *int     `json:"top_n,omitempty"`
+	ReturnDocuments *bool    `json:"return_documents,omitempty"`
+}
+
+// RerankDocument 包装原文,仅在 return_documents 时返回。
+type RerankDocument struct {
+	Text string `json:"text"`
+}
+
+// RerankResult 是一条重排结果:index 指向请求 documents 下标。
+type RerankResult struct {
+	Index          int             `json:"index"`
+	RelevanceScore float64         `json:"relevance_score"`
+	Document       *RerankDocument `json:"document,omitempty"`
+}
+
+// RerankResponse 是 /ai/v1/rerank 响应体。
+type RerankResponse struct {
+	Model   string         `json:"model"`
+	Results []RerankResult `json:"results"`
+}

internal/aiwire/responses.go

@@ -184,3 +184,16 @@ type RespError struct {
 type RespIncomplete struct {
 	Reason string `json:"reason"`
 }
+
+// RespResponse 描述 /ai/v1/responses 非流式响应的常用顶层字段(文档用途)。
+// 直通端点原样返回上游 JSON,未列字段(reasoning、incomplete_details 等)同样保留。
+type RespResponse struct {
+	ID        string          `json:"id"`
+	Object    string          `json:"object"`
+	CreatedAt int64           `json:"created_at"`
+	Status    string          `json:"status"`
+	Model     string          `json:"model"`
+	Output    json.RawMessage `json:"output"`
+	Usage     *RespUsage      `json:"usage,omitempty"`
+	Error     *RespError      `json:"error,omitempty"`
+}

internal/api/about.go

@@ -30,7 +30,7 @@ func SetAboutRuntime(dbDriver, dbPath string) {
 //
 // @Summary  返回构建、运行时长与资源占用信息,「设置 · 关于」页展示
 // @Tags     设置
-// @Success  200 {object} map[string]any
+// @Success  200 {object} aboutResponse
 // @Security BearerAuth
 // @Router   /api/v1/about [get]
 func about(c *gin.Context) {

internal/api/aiadmin.go

@@ -3,9 +3,13 @@ package api
 import (
 	"net/http"
 	"strconv"
+	"time"
 
 	"github.com/gin-gonic/gin"
 
+	_ "oci-portal/internal/aiwire" // swagger 注解引用
+	_ "oci-portal/internal/model"  // swagger 注解引用
+
 	"oci-portal/internal/service"
 )
 
@@ -18,7 +22,7 @@ type aiAdminHandler struct {
 
 // @Summary  ---- 密钥 ----
 // @Tags     AI 管理
-// @Success  200 {object} map[string]any
+// @Success  200 {object} itemsResponse[model.AiKey]
 // @Security BearerAuth
 // @Router   /api/v1/ai-keys [get]
 func (h *aiAdminHandler) listKeys(c *gin.Context) {
@@ -35,7 +39,7 @@ func (h *aiAdminHandler) listKeys(c *gin.Context) {
 // @Summary  生成密钥
 // @Tags     AI 管理
 // @Param    body body object true "请求体(见接口说明)"
-// @Success  201 {object} map[string]any
+// @Success  201 {object} aiKeyCreateResponse "key 为明文密钥,仅本次返回"
 // @Security BearerAuth
 // @Router   /api/v1/ai-keys [post]
 func (h *aiAdminHandler) createKey(c *gin.Context) {
@@ -110,7 +114,7 @@ func (h *aiAdminHandler) deleteKey(c *gin.Context) {
 // @Tags     AI 管理
 // @Param    id path int true "配置 ID"
 // @Param    body body object true "请求体(见接口说明)"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} model.AiKey
 // @Security BearerAuth
 // @Router   /api/v1/ai-keys/{id}/content-log [put]
 func (h *aiAdminHandler) updateKeyContentLog(c *gin.Context) {
@@ -137,7 +141,7 @@ func (h *aiAdminHandler) updateKeyContentLog(c *gin.Context) {
 //
 // @Summary  分页查询内容日志
 // @Tags     AI 管理
-// @Success  200 {object} map[string]any
+// @Success  200 {object} pagedResponse[model.AiCallLog]
 // @Security BearerAuth
 // @Router   /api/v1/ai-content-logs [get]
 func (h *aiAdminHandler) listContentLogs(c *gin.Context) {
@@ -157,7 +161,7 @@ func (h *aiAdminHandler) listContentLogs(c *gin.Context) {
 
 // @Summary  ---- 渠道 ----
 // @Tags     AI 管理
-// @Success  200 {object} map[string]any
+// @Success  200 {object} itemsResponse[model.AiChannel]
 // @Security BearerAuth
 // @Router   /api/v1/ai-channels [get]
 func (h *aiAdminHandler) listChannels(c *gin.Context) {
@@ -172,7 +176,7 @@ func (h *aiAdminHandler) listChannels(c *gin.Context) {
 // @Summary  创建 AI 渠道
 // @Tags     AI 管理
 // @Param    body body service.ChannelInput true "请求体"
-// @Success  201 {object} map[string]any
+// @Success  201 {object} model.AiChannel
 // @Security BearerAuth
 // @Router   /api/v1/ai-channels [post]
 func (h *aiAdminHandler) createChannel(c *gin.Context) {
@@ -236,7 +240,7 @@ func (h *aiAdminHandler) deleteChannel(c *gin.Context) {
 // @Summary  触发探测:服务可见性 + 模型同步 + 配额试调,返回更新后的渠道
 // @Tags     AI 管理
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} model.AiChannel
 // @Security BearerAuth
 // @Router   /api/v1/ai-channels/{id}/probe [post]
 func (h *aiAdminHandler) probeChannel(c *gin.Context) {
@@ -255,7 +259,7 @@ func (h *aiAdminHandler) probeChannel(c *gin.Context) {
 // @Summary  同步渠道模型缓存
 // @Tags     AI 管理
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} itemsResponse[model.AiModelCache]
 // @Security BearerAuth
 // @Router   /api/v1/ai-channels/{id}/sync-models [post]
 func (h *aiAdminHandler) syncChannelModels(c *gin.Context) {
@@ -271,11 +275,60 @@ func (h *aiAdminHandler) syncChannelModels(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"items": models})
 }
 
+// @Summary  渠道模型缓存列表
+// @Tags     AI 管理
+// @Param    id path int true "渠道 ID"
+// @Success  200 {object} itemsResponse[model.AiModelCache]
+// @Security BearerAuth
+// @Router   /api/v1/ai-channels/{id}/models [get]
+func (h *aiAdminHandler) listChannelModels(c *gin.Context) {
+	id, ok := aiPathID(c)
+	if !ok {
+		return
+	}
+	models, err := h.gw.ChannelModels(c.Request.Context(), id)
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"items": models})
+}
+
+type testChannelModelRequest struct {
+	Model string `json:"model" binding:"required"`
+}
+
+// @Summary  测试渠道模型(max_tokens=16 试调;通过即设为探测验证模型并按需置渠道可用)
+// @Tags     AI 管理
+// @Param    id path int true "渠道 ID"
+// @Param    body body testChannelModelRequest true "模型名"
+// @Success  200 {object} model.AiChannel
+// @Failure  502 {object} errorResponse "试调未通过"
+// @Security BearerAuth
+// @Router   /api/v1/ai-channels/{id}/test-model [post]
+func (h *aiAdminHandler) testChannelModel(c *gin.Context) {
+	id, ok := aiPathID(c)
+	if !ok {
+		return
+	}
+	var req testChannelModelRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	ch, err := h.gw.TestChannelModel(c.Request.Context(), id, req.Model)
+	if err != nil {
+		c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, ch)
+}
+
 // ---- 聚合模型与调用日志 ----
 
 // @Summary  ---- 聚合模型与调用日志 ----
 // @Tags     AI 管理
-// @Success  200 {object} map[string]any
+// @Success  200 {object} itemsResponse[aiwire.Model]
 // @Security BearerAuth
 // @Router   /api/v1/ai-models [get]
 func (h *aiAdminHandler) gatewayModels(c *gin.Context) {
@@ -291,7 +344,7 @@ func (h *aiAdminHandler) gatewayModels(c *gin.Context) {
 
 // @Summary  模型黑名单列表
 // @Tags     AI 管理
-// @Success  200 {object} map[string]any
+// @Success  200 {object} itemsResponse[model.AiModelBlacklist]
 // @Security BearerAuth
 // @Router   /api/v1/ai-blacklist [get]
 func (h *aiAdminHandler) listBlacklist(c *gin.Context) {
@@ -308,7 +361,7 @@ func (h *aiAdminHandler) listBlacklist(c *gin.Context) {
 // @Summary  添加模型黑名单
 // @Tags     AI 管理
 // @Param    body body object true "请求体:{name: 模型名}"
-// @Success  201 {object} map[string]any
+// @Success  201 {object} itemResponse[model.AiModelBlacklist]
 // @Security BearerAuth
 // @Router   /api/v1/ai-blacklist [post]
 func (h *aiAdminHandler) addBlacklist(c *gin.Context) {
@@ -347,7 +400,7 @@ func (h *aiAdminHandler) removeBlacklist(c *gin.Context) {
 
 // @Summary  AI 调用日志列表
 // @Tags     AI 管理
-// @Success  200 {object} map[string]any
+// @Success  200 {object} pagedResponse[model.AiContentLog]
 // @Security BearerAuth
 // @Router   /api/v1/ai-logs [get]
 func (h *aiAdminHandler) listLogs(c *gin.Context) {
@@ -369,3 +422,104 @@ func aiPathID(c *gin.Context) (uint, bool) {
 	}
 	return uint(id), true
 }
+
+// modelCatalog 返回启用渠道聚合去重后的模型目录(含能力),黑名单添加弹窗用。
+//
+// @Summary  聚合模型目录
+// @Tags     AI 管理
+// @Success  200 {object} itemsResponse[service.AggregatedModel]
+// @Security BearerAuth
+// @Router   /api/v1/ai-model-catalog [get]
+func (h *aiAdminHandler) modelCatalog(c *gin.Context) {
+	items, err := h.gw.AggregatedModels(c.Request.Context())
+	if err != nil {
+		respondError(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"items": items})
+}
+
+// aiSettingsResponse 是 AI 网关全局设置(文档与响应共用)。
+type aiSettingsResponse struct {
+	// FilterDeprecated 开启后已宣布弃用(即使未退役)的模型从列表与路由中排除
+	FilterDeprecated bool `json:"filterDeprecated"`
+	// StreamGuardEnabled / StreamGuardKB 是 Responses 流式保险丝:
+	// instructions+tools 合计超阈值(KB)的流式请求改非流式上游并合成 SSE
+	StreamGuardEnabled bool `json:"streamGuardEnabled"`
+	StreamGuardKB      int  `json:"streamGuardKB"`
+	// GrokWebSearch / GrokXSearch 是 xai. 模型服务端搜索工具默认注入开关;
+	// 请求 tools 已包含同名工具时不覆盖
+	GrokWebSearch bool `json:"grokWebSearch"`
+	GrokXSearch   bool `json:"grokXSearch"`
+	// UpstreamWaitSeconds 是 responses 直通的上游无响应预算(秒):非流式为单次
+	// 尝试总超时,流式为等待响应头预算;multi-agent/搜索类模型需远超 60s
+	UpstreamWaitSeconds int `json:"upstreamWaitSeconds"`
+}
+
+// currentAiSettings 汇总网关运行时设置为响应体。
+func (h *aiAdminHandler) currentAiSettings() aiSettingsResponse {
+	guardOn, guardKB := h.gw.StreamGuard()
+	web, x := h.gw.GrokSearch()
+	return aiSettingsResponse{
+		FilterDeprecated:    h.gw.FilterDeprecated(),
+		StreamGuardEnabled:  guardOn,
+		StreamGuardKB:       guardKB,
+		GrokWebSearch:       web,
+		GrokXSearch:         x,
+		UpstreamWaitSeconds: int(h.gw.UpstreamWait() / time.Second),
+	}
+}
+
+// aiSettings 返回 AI 网关全局设置。
+//
+// @Summary  AI 网关全局设置
+// @Tags     AI 管理
+// @Success  200 {object} aiSettingsResponse
+// @Security BearerAuth
+// @Router   /api/v1/ai-settings [get]
+func (h *aiAdminHandler) aiSettings(c *gin.Context) {
+	c.JSON(http.StatusOK, h.currentAiSettings())
+}
+
+// updateAiSettings 更新 AI 网关全局设置(过滤弃用/流式保险丝/grok 搜索工具默认注入)。
+//
+// @Summary  更新 AI 网关全局设置
+// @Tags     AI 管理
+// @Param    body body aiSettingsResponse true "全量提交;保险丝阈值限 1..1024 KB,上游无响应预算限 30..900 秒"
+// @Success  200 {object} aiSettingsResponse
+// @Failure  400 {object} map[string]string
+// @Security BearerAuth
+// @Router   /api/v1/ai-settings [put]
+func (h *aiAdminHandler) updateAiSettings(c *gin.Context) {
+	var req aiSettingsResponse
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if req.StreamGuardKB < 1 || req.StreamGuardKB > 1024 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "streamGuardKB 须在 1..1024"})
+		return
+	}
+	if req.UpstreamWaitSeconds < 30 || req.UpstreamWaitSeconds > 900 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "upstreamWaitSeconds 须在 30..900"})
+		return
+	}
+	ctx := c.Request.Context()
+	if err := h.gw.SetFilterDeprecated(ctx, req.FilterDeprecated); err != nil {
+		respondError(c, err)
+		return
+	}
+	if err := h.gw.SetStreamGuard(ctx, req.StreamGuardEnabled, req.StreamGuardKB); err != nil {
+		respondError(c, err)
+		return
+	}
+	if err := h.gw.SetGrokSearch(ctx, req.GrokWebSearch, req.GrokXSearch); err != nil {
+		respondError(c, err)
+		return
+	}
+	if err := h.gw.SetUpstreamWait(ctx, req.UpstreamWaitSeconds); err != nil {
+		respondError(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, h.currentAiSettings())
+}

internal/api/aigateway.go

@@ -8,6 +8,7 @@ import (
 	"encoding/json"
 	"errors"
 	"io"
+	"log"
 	"net/http"
 	"slices"
 	"strings"
@@ -165,8 +166,8 @@ func fillUsage(entry *model.AiCallLog, u *aiwire.Usage) {
 //
 // @Summary  OpenAI 兼容向量嵌入
 // @Tags     AI 网关
-// @Param    body body object true "OpenAI embeddings 请求体"
+// @Param    body body aiwire.EmbeddingsRequest true "OpenAI embeddings 请求体"
-// @Success  200 {object} map[string]any "OpenAI 兼容响应"
+// @Success  200 {object} aiwire.EmbeddingsResponse "OpenAI 兼容响应"
 // @Router   /ai/v1/embeddings [post]
 func (h *aiGatewayHandler) embeddings(c *gin.Context) {
 	var req aiwire.EmbeddingsRequest
@@ -218,8 +219,8 @@ const anthDefaultMaxTokens = 8192
 //
 // @Summary  Anthropic Messages 兼容端点
 // @Tags     AI 网关
-// @Param    body body object true "Anthropic messages 请求体(支持 stream;经 OCI OpenAI 兼容面直通;max_tokens 可缺省,默认 8192)"
+// @Param    body body aiwire.MessagesRequest true "Anthropic messages 请求体(支持 stream;经 OCI OpenAI 兼容面直通;max_tokens 可缺省,默认 8192)"
-// @Success  200 {object} map[string]any "Anthropic 兼容响应(流式为 SSE)"
+// @Success  200 {object} aiwire.MessagesResponse "Anthropic 兼容响应(非流式;流式为 SSE 事件序列)"
 // @Router   /ai/v1/messages [post]
 func (h *aiGatewayHandler) messages(c *gin.Context) {
 	var req aiwire.MessagesRequest
@@ -381,8 +382,8 @@ func writeAnthEvents(c *gin.Context, events []service.AnthEvent) {
 //
 // @Summary  OpenAI Chat Completions 兼容端点
 // @Tags     AI 网关
-// @Param    body body object true "OpenAI chat/completions 请求体(支持 stream;经 Responses 转换直通)"
+// @Param    body body aiwire.ChatRequest true "OpenAI chat/completions 请求体(支持 stream;经 Responses 转换直通)"
-// @Success  200 {object} map[string]any "OpenAI 兼容响应(流式为 SSE,末尾 data: [DONE])"
+// @Success  200 {object} aiwire.ChatResponse "OpenAI 兼容响应(非流式;流式为 SSE,末尾 data: [DONE])"
 // @Router   /ai/v1/chat/completions [post]
 func (h *aiGatewayHandler) chatCompletions(c *gin.Context) {
 	var req aiwire.ChatRequest
@@ -528,7 +529,7 @@ func writeChatChunks(c *gin.Context, chunks []aiwire.ChatChunk) {
 //
 // @Summary  可用模型列表
 // @Tags     AI 网关
-// @Success  200 {object} map[string]any "OpenAI 兼容 models 列表"
+// @Success  200 {object} aiwire.ModelList "OpenAI 兼容 models 列表"
 // @Router   /ai/v1/models [get]
 func (h *aiGatewayHandler) listModels(c *gin.Context) {
 	list, err := h.gw.GatewayModels(c.Request.Context(), keyGroup(c))
@@ -552,8 +553,8 @@ func (h *aiGatewayHandler) listModels(c *gin.Context) {
 //
 // @Summary  OpenAI Responses 兼容端点
 // @Tags     AI 网关
-// @Param    body body object true "OpenAI responses 请求体(支持 stream;web_search/x_search 服务端工具仅非流式)"
+// @Param    body body aiwire.RespRequest true "OpenAI responses 请求体(支持 stream;服务端工具 web_search/x_search/code_interpreter/mcp 含流式;codex 兼容:namespace 工具组拍平为限定名 function 并在响应还原,custom 工具转 function 包装并回转 custom_tool_call(apply_patch 丢弃),tool_search 剥离,web_search.external_web_access 上游不支持自动处理,超 76KB 流式请求自动改非流式合成 SSE;未列字段原样透传上游)"
-// @Success  200 {object} map[string]any "OpenAI 兼容响应(流式为 SSE)"
+// @Success  200 {object} aiwire.RespResponse "OpenAI 兼容响应(非流式;流式为 SSE);直通仅建模常用字段,未列字段原样返回"
 // @Router   /ai/v1/responses [post]
 func (h *aiGatewayHandler) responses(c *gin.Context) {
 	raw, err := c.GetRawData()
@@ -576,16 +577,27 @@ func (h *aiGatewayHandler) responses(c *gin.Context) {
 // OCI /actions/v1/responses,响应原样透传。
 func (h *aiGatewayHandler) responsesPassthrough(c *gin.Context, raw []byte, req aiwire.RespRequest) {
 	if err := service.RespPassthroughValidate(req); err != nil {
+		log.Printf("responses 直通(model=%s): 校验拒绝: %v", req.Model, err)
 		aiError(c, http.StatusBadRequest, "invalid_request_error", err.Error())
 		return
 	}
-	body, err := service.RespPassthroughBody(raw)
+	body, compat, err := service.RespPassthroughBody(raw)
 	if err != nil {
 		aiError(c, http.StatusBadRequest, "invalid_request_error", err.Error())
 		return
 	}
+	logRespCompat(req.Model, compat)
+	web, x := h.gw.GrokSearch()
+	if injectedBody, injected := service.RespInjectGrokTools(body, req.Model, web, x); len(injected) > 0 {
+		body = injectedBody
+		log.Printf("responses 直通(model=%s): 默认注入 %s", req.Model, strings.Join(injected, ", "))
+	}
 	if req.Stream {
-		h.responsesPassthroughStream(c, body, req)
+		if on, kb := h.gw.StreamGuard(); on && service.RespGuardBytes(body) > kb*1024 {
+			h.responsesStreamUpgrade(c, body, req, compat)
+			return
+		}
+		h.responsesPassthroughStream(c, body, req, compat)
 		return
 	}
 	start := time.Now()
@@ -597,6 +609,7 @@ func (h *aiGatewayHandler) responsesPassthrough(c *gin.Context, raw []byte, req
 		h.logFailure(c, entry, req)
 		return
 	}
+	payload = service.RespRestoreToolCalls(payload, compat)
 	entry.Status = http.StatusOK
 	fillUsage(&entry, service.RespPassthroughUsage(payload))
 	callID := h.gw.LogCall(entry)
@@ -604,9 +617,75 @@ func (h *aiGatewayHandler) responsesPassthrough(c *gin.Context, raw []byte, req
 	c.Data(http.StatusOK, "application/json; charset=utf-8", payload)
 }
 
+// logRespCompat 记录直通请求的 codex 兼容改写动作(观测)。
+func logRespCompat(model string, compat service.RespCompat) {
+	if len(compat.Flattened) == 0 && len(compat.Dropped) == 0 && len(compat.Converted) == 0 {
+		return
+	}
+	var parts []string
+	if len(compat.Flattened) > 0 {
+		parts = append(parts, "拍平: "+strings.Join(compat.Flattened, ", "))
+	}
+	if len(compat.Converted) > 0 {
+		parts = append(parts, "转换: "+strings.Join(compat.Converted, ", "))
+	}
+	if len(compat.Dropped) > 0 {
+		parts = append(parts, "剥离: "+strings.Join(compat.Dropped, ", "))
+	}
+	log.Printf("responses 直通(model=%s): %s", model, strings.Join(parts, "; "))
+}
+
+// responsesStreamUpgrade 流式升级回退:instructions+tools 合计超过保险丝阈值
+// (设置页 AI Tab 配置,默认开 60KB;上游对 >≈64.5KB 会静默断流)时改调非流式
+// 上游拿完整响应,本地合成最小 SSE 事件序列回给客户端;丢失增量输出,换会话不中断。
+func (h *aiGatewayHandler) responsesStreamUpgrade(c *gin.Context, body []byte, req aiwire.RespRequest, compat service.RespCompat) {
+	start := time.Now()
+	nsBody, err := service.RespDisableStream(body)
+	if err != nil {
+		aiError(c, http.StatusBadRequest, "invalid_request_error", err.Error())
+		return
+	}
+	log.Printf("responses 直通(model=%s): instructions+tools %dKB 超保险丝阈值,改走非流式合成 SSE",
+		req.Model, service.RespGuardBytes(body)/1024)
+	payload, meta, err := h.gw.RespPassthrough(c.Request.Context(), nsBody, req.Model, keyGroup(c))
+	entry := h.logEntry(c, "responses", req.Model, true, meta, start)
+	if err != nil {
+		upstreamError(c, err)
+		entry.ErrMsg = err.Error()
+		h.logFailure(c, entry, req)
+		return
+	}
+	payload = service.RespRestoreToolCalls(payload, compat)
+	writeSynthSSE(c, payload)
+	entry.Status = http.StatusOK
+	entry.LatencyMs = time.Since(start).Milliseconds()
+	fillUsage(&entry, service.RespPassthroughUsage(payload))
+	callID := h.gw.LogCall(entry)
+	h.maybeLogContent(c, callID, "responses", req.Model, true, req, json.RawMessage(payload))
+}
+
+// writeSynthSSE 把完整响应按合成事件序列写出;合成失败时降级为一次性 JSON,
+// 客户端至少拿到完整结果。
+func writeSynthSSE(c *gin.Context, payload []byte) {
+	events, err := service.RespSynthSSEEvents(payload)
+	if err != nil {
+		log.Printf("responses 直通: 合成 SSE 失败,降级 JSON 返回: %v", err)
+		c.Data(http.StatusOK, "application/json; charset=utf-8", payload)
+		return
+	}
+	sseHeaders(c)
+	for _, ev := range events {
+		c.Writer.Write([]byte("data: "))
+		c.Writer.Write(ev)
+		c.Writer.Write([]byte("\n\n"))
+	}
+	c.Writer.Flush()
+}
+
 // responsesPassthroughStream 流式直通:SSE 事件原样转发(推理增量等直达客户端),
-// 逐行扫描 completed 事件提取 usage 记账。
+// 逐行扫描 completed 事件提取 usage 记账;refs 非空时对 function_call 事件做
-func (h *aiGatewayHandler) responsesPassthroughStream(c *gin.Context, body []byte, req aiwire.RespRequest) {
+// namespace 还原后再转发。
+func (h *aiGatewayHandler) responsesPassthroughStream(c *gin.Context, body []byte, req aiwire.RespRequest, compat service.RespCompat) {
 	start := time.Now()
 	upstream, meta, err := h.gw.RespPassthroughStream(c.Request.Context(), body, req.Model, keyGroup(c))
 	entry := h.logEntry(c, "responses", req.Model, true, meta, start)
@@ -618,7 +697,7 @@ func (h *aiGatewayHandler) responsesPassthroughStream(c *gin.Context, body []byt
 	}
 	defer upstream.Close()
 	sseHeaders(c)
-	usage, upErr, err := forwardSSE(c, upstream)
+	usage, upErr, err := forwardSSE(c, upstream, compat)
 	if err != nil {
 		entry.ErrMsg = err.Error()
 	} else if upErr != "" {
@@ -635,25 +714,29 @@ func (h *aiGatewayHandler) responsesPassthroughStream(c *gin.Context, body []byt
 }
 
 // forwardSSE 把上游 SSE 逐行转发给客户端,空行(事件边界)即 flush;
-// 顺带从 data 行提取 response.completed 的 usage 与错误事件消息。
+// 顺带从 data 行提取 response.completed 的 usage 与错误事件消息;
-func forwardSSE(c *gin.Context, upstream io.Reader) (*aiwire.Usage, string, error) {
+// refs 非空时 data 行先做 namespace 还原(未改动的行原样转发)。
+func forwardSSE(c *gin.Context, upstream io.Reader, compat service.RespCompat) (*aiwire.Usage, string, error) {
 	reader := bufio.NewReader(upstream)
 	var usage *aiwire.Usage
 	var upErr string
 	for {
 		line, err := reader.ReadBytes('\n')
 		if len(line) > 0 {
-			c.Writer.Write(line)
 			trimmed := bytes.TrimSpace(line)
-			if len(trimmed) == 0 {
+			if data, ok := bytes.CutPrefix(trimmed, []byte("data: ")); ok {
-				c.Writer.Flush()
+				c.Writer.Write(restoreSSELine(line, data, compat))
-			} else if data, ok := bytes.CutPrefix(trimmed, []byte("data: ")); ok {
 				if u := service.RespStreamCompletedUsage(data); u != nil {
 					usage = u
 				}
 				if m := service.RespStreamErrorMsg(data); m != "" && upErr == "" {
 					upErr = m
 				}
+			} else {
+				c.Writer.Write(line)
+				if len(trimmed) == 0 {
+					c.Writer.Flush()
+				}
 			}
 		}
 		if err != nil {
@@ -665,3 +748,20 @@ func forwardSSE(c *gin.Context, upstream io.Reader) (*aiwire.Usage, string, erro
 		}
 	}
 }
+
+// restoreSSELine 对一行 data 事件做工具调用项还原(namespace/custom),
+// 未改动时原行透传(字节级直通)。
+func restoreSSELine(line, data []byte, compat service.RespCompat) []byte {
+	if !compat.NeedRestore() {
+		return line
+	}
+	restored, changed := service.RespRestoreToolCallsEvent(data, compat)
+	if !changed {
+		return line
+	}
+	out := make([]byte, 0, len(restored)+8)
+	out = append(out, "data: "...)
+	out = append(out, restored...)
+	out = append(out, '\n')
+	return out
+}

internal/api/aigateway_extras.go

@@ -0,0 +1,145 @@
+package api
+
+import (
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+
+	"oci-portal/internal/aiwire"
+	"oci-portal/internal/service"
+)
+
+// audioSpeech 是 OpenAI /ai/v1/audio/speech 端点(TTS,直通兼容面)。
+//
+// @Summary  OpenAI Audio Speech 兼容端点(文本转语音)
+// @Tags     AI 网关
+// @Param    body body aiwire.SpeechRequest true "OpenAI audio speech 请求体(model/input 必填,voice 见 xAI Grok Voice 列表,language 缺省 auto;未列字段原样透传)"
+// @Success  200 {file} binary "音频字节(Content-Type 透传上游,默认 audio/mpeg)"
+// @Router   /ai/v1/audio/speech [post]
+func (h *aiGatewayHandler) audioSpeech(c *gin.Context) {
+	raw, err := c.GetRawData()
+	if err != nil {
+		aiError(c, http.StatusBadRequest, "invalid_request_error", err.Error())
+		return
+	}
+	modelName, body, err := service.SpeechBodyNormalize(raw)
+	if err != nil {
+		aiError(c, http.StatusBadRequest, "invalid_request_error", err.Error())
+		return
+	}
+	h.speechRespond(c, "speech", modelName, raw, body)
+}
+
+// tts 是 xAI 官方格式 TTS 端点(/ai/v1/tts),转换为上游 OpenAI 兼容形态后复用 Speech 编排。
+//
+// @Summary  xAI 官方格式文本转语音端点
+// @Tags     AI 网关
+// @Param    body body aiwire.TtsRequest true "xAI TTS 请求体(text/language 必填,voice_id 缺省 eve;model 为网关扩展,缺省 xai.grok-tts;未列字段原样透传)"
+// @Success  200 {file} binary "音频字节(Content-Type 透传上游,默认 audio/mpeg)"
+// @Router   /ai/v1/tts [post]
+func (h *aiGatewayHandler) tts(c *gin.Context) {
+	raw, err := c.GetRawData()
+	if err != nil {
+		aiError(c, http.StatusBadRequest, "invalid_request_error", err.Error())
+		return
+	}
+	modelName, body, err := service.TtsBodyConvert(raw)
+	if err != nil {
+		aiError(c, http.StatusBadRequest, "invalid_request_error", err.Error())
+		return
+	}
+	h.speechRespond(c, "tts", modelName, raw, body)
+}
+
+// speechRespond 是 audioSpeech / tts 的公共主体:白名单校验、上游调用、日志与音频响应。
+func (h *aiGatewayHandler) speechRespond(c *gin.Context, endpoint, modelName string, raw, body []byte) {
+	if !checkKeyModel(c, modelName) {
+		return
+	}
+	start := time.Now()
+	audio, contentType, meta, err := h.gw.Speech(c.Request.Context(), modelName, body, keyGroup(c))
+	entry := h.logEntry(c, endpoint, modelName, false, meta, start)
+	if err != nil {
+		upstreamError(c, err)
+		entry.ErrMsg = err.Error()
+		h.logFailure(c, entry, string(raw))
+		return
+	}
+	entry.Status = http.StatusOK
+	callID := h.gw.LogCall(entry)
+	h.maybeLogContent(c, callID, endpoint, modelName, false, string(raw), nil)
+	if contentType == "" {
+		contentType = "audio/mpeg"
+	}
+	c.Data(http.StatusOK, contentType, audio)
+}
+
+// rerank 是 /ai/v1/rerank 端点(Jina / Cohere 风格文档重排)。
+//
+// @Summary  文档重排端点(Cohere Rerank)
+// @Tags     AI 网关
+// @Param    body body aiwire.RerankRequest true "重排请求体(model/query/documents 必填,可选 top_n/return_documents)"
+// @Success  200 {object} aiwire.RerankResponse "重排结果(results[].index 指向入参下标)"
+// @Router   /ai/v1/rerank [post]
+func (h *aiGatewayHandler) rerank(c *gin.Context) {
+	var req aiwire.RerankRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		aiError(c, http.StatusBadRequest, "invalid_request_error", err.Error())
+		return
+	}
+	if strings.TrimSpace(req.Model) == "" || strings.TrimSpace(req.Query) == "" || len(req.Documents) == 0 {
+		aiError(c, http.StatusBadRequest, "invalid_request_error", "model、query 与 documents 不能为空")
+		return
+	}
+	if !checkKeyModel(c, req.Model) {
+		return
+	}
+	start := time.Now()
+	resp, meta, err := h.gw.Rerank(c.Request.Context(), req, keyGroup(c))
+	entry := h.logEntry(c, "rerank", req.Model, false, meta, start)
+	if err != nil {
+		upstreamError(c, err)
+		entry.ErrMsg = err.Error()
+		h.logFailure(c, entry, req)
+		return
+	}
+	entry.Status = http.StatusOK
+	callID := h.gw.LogCall(entry)
+	h.maybeLogContent(c, callID, "rerank", req.Model, false, req, resp)
+	c.JSON(http.StatusOK, resp)
+}
+
+// moderations 是 /ai/v1/moderations 端点(OpenAI 外壳映射 OCI Guardrails)。
+//
+// @Summary  内容审核端点(OCI Guardrails)
+// @Tags     AI 网关
+// @Param    body body aiwire.ModerationsRequest true "审核请求体(input 为字符串或字符串数组,单次至多 8 条;model 接受但忽略)"
+// @Success  200 {object} aiwire.ModerationsResponse "审核结果(categories/category_scores 为 overall/blocklist/prompt_injection,pii 为扩展字段)"
+// @Router   /ai/v1/moderations [post]
+func (h *aiGatewayHandler) moderations(c *gin.Context) {
+	var req aiwire.ModerationsRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		aiError(c, http.StatusBadRequest, "invalid_request_error", err.Error())
+		return
+	}
+	inputs, err := service.ModerationInputs(req.Input)
+	if err != nil {
+		aiError(c, http.StatusBadRequest, "invalid_request_error", err.Error())
+		return
+	}
+	start := time.Now()
+	resp, meta, err := h.gw.Moderations(c.Request.Context(), aiRandID("modr_"), inputs, keyGroup(c))
+	entry := h.logEntry(c, "moderations", "oci-guardrails", false, meta, start)
+	if err != nil {
+		upstreamError(c, err)
+		entry.ErrMsg = err.Error()
+		h.logFailure(c, entry, req)
+		return
+	}
+	entry.Status = http.StatusOK
+	callID := h.gw.LogCall(entry)
+	h.maybeLogContent(c, callID, "moderations", "oci-guardrails", false, req, resp)
+	c.JSON(http.StatusOK, resp)
+}

internal/api/aigateway_test.go

@@ -95,6 +95,18 @@ func TestAiGatewayKeyModelRestrict(t *testing.T) {
 		{"chat completions 不支持内容块拒绝", "open-key-12345", "/ai/v1/chat/completions",
 			`{"model":"ghost-model","messages":[{"role":"user","content":[{"type":"input_audio"}]}]}`,
 			400, []string{"invalid_request_error"}},
+		{"audio speech 白名单外拦截", "limited-key-1234", "/ai/v1/audio/speech",
+			`{"model":"meta.llama-3.3-70b-instruct","input":"你好"}`, 404, deny},
+		{"rerank 白名单外拦截", "limited-key-1234", "/ai/v1/rerank",
+			`{"model":"meta.llama-3.3-70b-instruct","query":"q","documents":["d"]}`, 404, deny},
+		{"rerank 缺 documents 拒绝", "open-key-12345", "/ai/v1/rerank",
+			`{"model":"ghost-model","query":"q"}`, 400, []string{"invalid_request_error"}},
+		{"moderations 空 input 拒绝", "open-key-12345", "/ai/v1/moderations",
+			`{"input":[]}`, 400, []string{"invalid_request_error"}},
+		{"tts 缺 language 拒绝", "open-key-12345", "/ai/v1/tts",
+			`{"text":"你好"}`, 400, []string{"invalid_request_error"}},
+		{"tts 白名单外拦截", "limited-key-1234", "/ai/v1/tts",
+			`{"model":"meta.llama-3.3-70b-instruct","text":"你好","language":"zh"}`, 404, deny},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {

internal/api/attachment.go

@@ -15,7 +15,7 @@ import (
 // @Param    id path int true "配置 ID"
 // @Param    instanceId path string true "instanceId"
 // @Param    body body object true "请求体(见接口说明)"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} publicIpResponse
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/instances/{instanceId}/change-public-ip [post]
 func (h *ociConfigHandler) changePublicIP(c *gin.Context) {
@@ -40,7 +40,7 @@ func (h *ociConfigHandler) changePublicIP(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    instanceId path string true "instanceId"
 // @Param    body body object true "请求体(见接口说明)"
-// @Success  201 {object} map[string]any
+// @Success  201 {object} ipv6AddressResponse
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/instances/{instanceId}/ipv6-addresses [post]
 func (h *ociConfigHandler) addInstanceIpv6(c *gin.Context) {
@@ -92,7 +92,7 @@ type attachVnicRequest struct {
 // @Tags     计算
 // @Param    id path int true "配置 ID"
 // @Param    instanceId path string true "instanceId"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.Vnic
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/instances/{instanceId}/vnics [get]
 func (h *ociConfigHandler) listInstanceVnics(c *gin.Context) {
@@ -113,7 +113,7 @@ func (h *ociConfigHandler) listInstanceVnics(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    instanceId path string true "instanceId"
 // @Param    body body attachVnicRequest true "请求体"
-// @Success  201 {object} map[string]any
+// @Success  201 {object} oci.Vnic
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/instances/{instanceId}/vnics [post]
 func (h *ociConfigHandler) attachVnic(c *gin.Context) {
@@ -160,7 +160,7 @@ func (h *ociConfigHandler) detachVnic(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    vnicId path string true "vnicId"
 // @Param    body body object true "请求体(见接口说明)"
-// @Success  201 {object} map[string]any
+// @Success  201 {object} addressResponse
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/vnics/{vnicId}/ipv6-addresses [post]
 func (h *ociConfigHandler) addVnicIpv6(c *gin.Context) {
@@ -195,7 +195,7 @@ type attachBootVolumeRequest struct {
 // @Tags     存储
 // @Param    id path int true "配置 ID"
 // @Param    instanceId path string true "instanceId"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.BootVolumeAttachment
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/instances/{instanceId}/boot-volume-attachments [get]
 func (h *ociConfigHandler) listBootVolumeAttachments(c *gin.Context) {
@@ -216,7 +216,7 @@ func (h *ociConfigHandler) listBootVolumeAttachments(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    instanceId path string true "instanceId"
 // @Param    body body attachBootVolumeRequest true "请求体"
-// @Success  201 {object} map[string]any
+// @Success  201 {object} oci.BootVolumeAttachment
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/instances/{instanceId}/boot-volume-attachments [post]
 func (h *ociConfigHandler) attachBootVolume(c *gin.Context) {
@@ -242,7 +242,7 @@ func (h *ociConfigHandler) attachBootVolume(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    instanceId path string true "instanceId"
 // @Param    body body attachBootVolumeRequest true "请求体"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.BootVolumeAttachment
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/instances/{instanceId}/replace-boot-volume [post]
 func (h *ociConfigHandler) replaceBootVolume(c *gin.Context) {
@@ -293,7 +293,7 @@ type attachVolumeRequest struct {
 // @Summary  块存储卷列表
 // @Tags     存储
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.BlockVolume
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/volumes [get]
 func (h *ociConfigHandler) listBlockVolumes(c *gin.Context) {
@@ -313,7 +313,7 @@ func (h *ociConfigHandler) listBlockVolumes(c *gin.Context) {
 // @Tags     存储
 // @Param    id path int true "配置 ID"
 // @Param    instanceId path string true "instanceId"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.VolumeAttachment
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/instances/{instanceId}/volume-attachments [get]
 func (h *ociConfigHandler) listVolumeAttachments(c *gin.Context) {
@@ -334,7 +334,7 @@ func (h *ociConfigHandler) listVolumeAttachments(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    instanceId path string true "instanceId"
 // @Param    body body attachVolumeRequest true "请求体"
-// @Success  201 {object} map[string]any
+// @Success  201 {object} oci.VolumeAttachment
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/instances/{instanceId}/volume-attachments [post]
 func (h *ociConfigHandler) attachVolume(c *gin.Context) {

internal/api/auth.go

@@ -32,9 +32,9 @@ type loginRequest struct {
 // @Accept   json
 // @Produce  json
 // @Param    body body loginRequest true "登录凭据"
-// @Success  200 {object} map[string]any "token 与 expiresAt"
+// @Success  200 {object} tokenResponse "token 与 expiresAt"
-// @Failure  401 {object} map[string]string "凭据错误"
+// @Failure  401 {object} errorResponse "凭据错误"
-// @Failure  428 {object} map[string]any "需要两步验证码(totpRequired=true)"
+// @Failure  428 {object} totpRequiredResponse "需要两步验证码(totpRequired=true)"
 // @Router   /api/v1/auth/login [post]
 func (h *authHandler) login(c *gin.Context) {
 	var req loginRequest

internal/api/authx.go

@@ -5,9 +5,12 @@ import (
 	"net/http"
 	"net/url"
 	"strconv"
+	"time"
 
 	"github.com/gin-gonic/gin"
 
+	"oci-portal/internal/model"
+
 	"oci-portal/internal/service"
 )
 
@@ -15,6 +18,7 @@ import (
 type authxHandler struct {
 	auth  *service.AuthService
 	oauth *service.OAuthService
+	logs  *service.SystemLogService
 }
 
 // ---- TOTP(JWT 组内) ----
@@ -23,7 +27,7 @@ type authxHandler struct {
 //
 // @Summary  两步验证状态
 // @Tags     认证
-// @Success  200 {object} map[string]bool "enabled"
+// @Success  200 {object} enabledResponse "enabled"
 // @Security BearerAuth
 // @Router   /api/v1/auth/totp [get]
 func (h *authxHandler) totpStatus(c *gin.Context) {
@@ -39,8 +43,8 @@ func (h *authxHandler) totpStatus(c *gin.Context) {
 //
 // @Summary  发起两步验证设置
 // @Tags     认证
-// @Success  200 {object} map[string]string "secret 与 otpauthUri"
+// @Success  200 {object} totpSetupResponse "secret 与 otpauthUri"
-// @Failure  409 {object} map[string]string "已启用"
+// @Failure  409 {object} errorResponse "已启用"
 // @Security BearerAuth
 // @Router   /api/v1/auth/totp/setup [post]
 func (h *authxHandler) totpSetup(c *gin.Context) {
@@ -128,7 +132,7 @@ func (h *authxHandler) respondFreshToken(c *gin.Context) {
 //
 // @Summary  撤销全部会话
 // @Tags     认证
-// @Success  200 {object} map[string]string "新 token 与 expiresAt"
+// @Success  200 {object} tokenResponse "新 token 与 expiresAt"
 // @Security BearerAuth
 // @Router   /api/v1/auth/revoke-sessions [post]
 func (h *authxHandler) revokeSessions(c *gin.Context) {
@@ -146,7 +150,7 @@ func (h *authxHandler) revokeSessions(c *gin.Context) {
 //
 // @Summary  登录凭据摘要
 // @Tags     认证
-// @Success  200 {object} map[string]any "username 与 passwordLoginDisabled"
+// @Success  200 {object} credentialsResponse "username 与 passwordLoginDisabled"
 // @Security BearerAuth
 // @Router   /api/v1/auth/credentials [get]
 func (h *authxHandler) getCredentials(c *gin.Context) {
@@ -167,7 +171,7 @@ func (h *authxHandler) getCredentials(c *gin.Context) {
 // @Tags     认证
 // @Param    body body service.UpdateCredentialsInput true "新凭据(当前密码必验)"
 // @Success  204 "已更新,请重新登录"
-// @Failure  401 {object} map[string]string "当前密码错误"
+// @Failure  401 {object} errorResponse "当前密码错误"
 // @Security BearerAuth
 // @Router   /api/v1/auth/credentials [put]
 func (h *authxHandler) updateCredentials(c *gin.Context) {
@@ -199,7 +203,7 @@ func (h *authxHandler) updateCredentials(c *gin.Context) {
 // @Tags     认证
 // @Param    body body object true "{disabled: bool}"
 // @Success  204 "已保存"
-// @Failure  409 {object} map[string]string "未绑定外部身份"
+// @Failure  409 {object} errorResponse "未绑定外部身份"
 // @Security BearerAuth
 // @Router   /api/v1/auth/password-login [put]
 func (h *authxHandler) updatePasswordLogin(c *gin.Context) {
@@ -230,7 +234,7 @@ func (h *authxHandler) updatePasswordLogin(c *gin.Context) {
 //
 // @Summary  外部登录 provider 列表
 // @Tags     认证
-// @Success  200 {object} map[string]any "providers 与 passwordLoginDisabled"
+// @Success  200 {object} oauthProvidersResponse "providers 与 passwordLoginDisabled"
 // @Router   /api/v1/auth/oauth/providers [get]
 func (h *authxHandler) oauthProviders(c *gin.Context) {
 	providers := h.oauth.Providers(c.Request.Context())
@@ -247,7 +251,7 @@ func (h *authxHandler) oauthProviders(c *gin.Context) {
 // @Tags     认证
 // @Param    provider path string true "oidc / github"
 // @Param    mode query string false "bind=绑定当前账号(需 Bearer),缺省登录"
-// @Success  200 {object} map[string]string "url"
+// @Success  200 {object} urlResponse "url"
 // @Router   /api/v1/auth/oauth/{provider}/authorize [get]
 func (h *authxHandler) oauthAuthorize(c *gin.Context) {
 	provider := c.Param("provider")
@@ -299,10 +303,12 @@ func (h *authxHandler) bearerUser(c *gin.Context) (string, bool) {
 // @Success  302 "登录 token 经 fragment 回前端,绑定回设置页"
 // @Router   /api/v1/auth/oauth/{provider}/callback [get]
 func (h *authxHandler) oauthCallback(c *gin.Context) {
+	start := time.Now()
 	provider := c.Param("provider")
-	token, _, mode, err := h.oauth.HandleCallback(
+	token, username, mode, err := h.oauth.HandleCallback(
 		c.Request.Context(), provider, c.Query("state"), c.Query("code"))
 	if err != nil {
+		h.recordOauth(c, username, http.StatusUnauthorized, oauthErrText(err), start)
 		target := "/login"
 		if mode == "bind" {
 			target = "/settings"
@@ -310,6 +316,7 @@ func (h *authxHandler) oauthCallback(c *gin.Context) {
 		c.Redirect(http.StatusFound, target+"?oauthError="+url.QueryEscape(oauthErrText(err)))
 		return
 	}
+	h.recordOauth(c, username, http.StatusOK, "", start)
 	if mode == "bind" {
 		// 绑定模式:版本已递增,新 token 经 fragment 带回设置页无感换发
 		c.Redirect(http.StatusFound, "/settings?oauth=bound#oauthToken="+url.QueryEscape(token))
@@ -319,6 +326,24 @@ func (h *authxHandler) oauthCallback(c *gin.Context) {
 	c.Redirect(http.StatusFound, "/login#oauthToken="+url.QueryEscape(token))
 }
 
+// recordOauth 把外部登录 / 绑定结果记入系统日志——回调是 GET,
+// 不经写方法中间件;实际响应恒为 302,日志按语义记 200 / 401。
+func (h *authxHandler) recordOauth(c *gin.Context, username string, status int, errMsg string, start time.Time) {
+	if h.logs == nil {
+		return
+	}
+	h.logs.Record(model.SystemLog{
+		Username:   username,
+		Method:     c.Request.Method,
+		Path:       requestPath(c),
+		Status:     status,
+		DurationMs: time.Since(start).Milliseconds(),
+		ClientIP:   requestIP(c),
+		UserAgent:  truncateLogField(c.Request.UserAgent(), 256),
+		ErrMsg:     errMsg,
+	})
+}
+
 // oauthErrText 把流程错误转为用户可读文案;内部错误不透出细节。
 func oauthErrText(err error) string {
 	for _, known := range []error{service.ErrOAuthNotConfigured, service.ErrOAuthNoAppURL, service.ErrOAuthDisabled, service.ErrOAuthState, service.ErrOAuthNotBound, service.ErrOAuthBound} {
@@ -333,7 +358,7 @@ func oauthErrText(err error) string {
 //
 // @Summary  已绑定外部身份
 // @Tags     认证
-// @Success  200 {object} map[string]any "items"
+// @Success  200 {object} itemsResponse[model.UserIdentity] "items"
 // @Security BearerAuth
 // @Router   /api/v1/auth/identities [get]
 func (h *authxHandler) identities(c *gin.Context) {
@@ -351,7 +376,7 @@ func (h *authxHandler) identities(c *gin.Context) {
 // @Tags     认证
 // @Param    id path int true "身份 ID"
 // @Success  204 "已解绑"
-// @Failure  409 {object} map[string]string "最后一个身份不可解绑"
+// @Failure  409 {object} errorResponse "最后一个身份不可解绑"
 // @Security BearerAuth
 // @Router   /api/v1/auth/identities/{id} [delete]
 func (h *authxHandler) unbindIdentity(c *gin.Context) {

internal/api/console.go

@@ -4,6 +4,8 @@ import (
 	"net/http"
 
 	"github.com/gin-gonic/gin"
+
+	_ "oci-portal/internal/oci" // swagger 注解引用
 )
 
 // ---- 控制台连接（VNC / 串口） ----
@@ -18,7 +20,7 @@ type createConsoleConnectionRequest struct {
 // @Param    id path int true "配置 ID"
 // @Param    instanceId path string true "instanceId"
 // @Param    body body createConsoleConnectionRequest true "请求体"
-// @Success  201 {object} map[string]any
+// @Success  201 {object} oci.ConsoleConnection
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/instances/{instanceId}/console-connections [post]
 func (h *ociConfigHandler) createConsoleConnection(c *gin.Context) {
@@ -43,7 +45,7 @@ func (h *ociConfigHandler) createConsoleConnection(c *gin.Context) {
 // @Tags     计算
 // @Param    id path int true "配置 ID"
 // @Param    instanceId path string true "instanceId"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.ConsoleConnection
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/instances/{instanceId}/console-connections [get]
 func (h *ociConfigHandler) listConsoleConnections(c *gin.Context) {

internal/api/federation.go

@@ -41,7 +41,7 @@ func boolOr(v *bool, def bool) bool {
 // @Tags     租户 IAM
 // @Param    id path int true "配置 ID"
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.IdentityProviderInfo
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/identity-providers [get]
 func (h *ociConfigHandler) listIdentityProviders(c *gin.Context) {
@@ -62,7 +62,7 @@ func (h *ociConfigHandler) listIdentityProviders(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
 // @Param    body body createIdpRequest true "请求体"
-// @Success  201 {object} map[string]any
+// @Success  201 {object} oci.IdentityProviderInfo
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/identity-providers [post]
 func (h *ociConfigHandler) createIdentityProvider(c *gin.Context) {
@@ -102,7 +102,7 @@ func (h *ociConfigHandler) createIdentityProvider(c *gin.Context) {
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
 // @Param    idpId path string true "idpId"
 // @Param    body body object true "请求体(见接口说明)"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.IdentityProviderInfo
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/identity-providers/{idpId}/activate [post]
 func (h *ociConfigHandler) activateIdentityProvider(c *gin.Context) {
@@ -149,7 +149,7 @@ func (h *ociConfigHandler) deleteIdentityProvider(c *gin.Context) {
 // @Tags     租户 IAM
 // @Param    id path int true "配置 ID"
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
-// @Success  200 {object} map[string]any
+// @Success  200 {file} file "SAML 元数据 XML(附件下载)"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/saml-metadata [get]
 func (h *ociConfigHandler) downloadSamlMetadata(c *gin.Context) {
@@ -170,7 +170,7 @@ func (h *ociConfigHandler) downloadSamlMetadata(c *gin.Context) {
 // @Tags     租户 IAM
 // @Param    id path int true "配置 ID"
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.SignOnRuleInfo
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/sign-on-rules [get]
 func (h *ociConfigHandler) listSignOnRules(c *gin.Context) {
@@ -191,7 +191,7 @@ func (h *ociConfigHandler) listSignOnRules(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
 // @Param    body body object true "请求体(见接口说明)"
-// @Success  201 {object} map[string]any
+// @Success  201 {object} oci.SignOnRuleInfo
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/sign-on-exemptions [post]
 func (h *ociConfigHandler) createMfaExemption(c *gin.Context) {

internal/api/instance.go

@@ -11,7 +11,7 @@ import (
 // @Summary  可用域列表
 // @Tags     租户配置
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} string
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/availability-domains [get]
 func (h *ociConfigHandler) availabilityDomains(c *gin.Context) {
@@ -67,7 +67,7 @@ type instanceActionRequest struct {
 // @Summary  实例列表
 // @Tags     计算
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.Instance
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/instances [get]
 func (h *ociConfigHandler) listInstances(c *gin.Context) {
@@ -87,7 +87,7 @@ func (h *ociConfigHandler) listInstances(c *gin.Context) {
 // @Tags     计算
 // @Param    id path int true "配置 ID"
 // @Param    body body createInstanceRequest true "请求体"
-// @Success  201 {object} map[string]any
+// @Success  201 {object} createInstancesResponse "部分成功仍 201,errors 为逐台失败信息"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/instances [post]
 func (h *ociConfigHandler) createInstance(c *gin.Context) {
@@ -147,7 +147,7 @@ func (h *ociConfigHandler) createInstance(c *gin.Context) {
 // @Tags     计算
 // @Param    id path int true "配置 ID"
 // @Param    instanceId path string true "instanceId"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.Instance
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/instances/{instanceId} [get]
 func (h *ociConfigHandler) getInstance(c *gin.Context) {
@@ -168,7 +168,7 @@ func (h *ociConfigHandler) getInstance(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    instanceId path string true "instanceId"
 // @Param    body body updateInstanceRequest true "请求体"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.Instance
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/instances/{instanceId} [put]
 func (h *ociConfigHandler) updateInstance(c *gin.Context) {
@@ -220,7 +220,7 @@ func (h *ociConfigHandler) terminateInstance(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    instanceId path string true "instanceId"
 // @Param    body body instanceActionRequest true "请求体"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.Instance
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/instances/{instanceId}/action [post]
 func (h *ociConfigHandler) instanceAction(c *gin.Context) {
@@ -253,7 +253,7 @@ type updateBootVolumeRequest struct {
 // @Summary  引导卷列表
 // @Tags     存储
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.BootVolume
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/boot-volumes [get]
 func (h *ociConfigHandler) listBootVolumes(c *gin.Context) {
@@ -273,7 +273,7 @@ func (h *ociConfigHandler) listBootVolumes(c *gin.Context) {
 // @Tags     存储
 // @Param    id path int true "配置 ID"
 // @Param    bootVolumeId path string true "bootVolumeId"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.BootVolume
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/boot-volumes/{bootVolumeId} [get]
 func (h *ociConfigHandler) getBootVolume(c *gin.Context) {
@@ -294,7 +294,7 @@ func (h *ociConfigHandler) getBootVolume(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    bootVolumeId path string true "bootVolumeId"
 // @Param    body body updateBootVolumeRequest true "请求体"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.BootVolume
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/boot-volumes/{bootVolumeId} [put]
 func (h *ociConfigHandler) updateBootVolume(c *gin.Context) {

internal/api/logevent.go

@@ -7,6 +7,8 @@ import (
 
 	"github.com/gin-gonic/gin"
 
+	_ "oci-portal/internal/model" // swagger 注解引用
+
 	"oci-portal/internal/service"
 )
 
@@ -20,7 +22,7 @@ type logEventHandler struct {
 // @Summary  查询配置的回调地址
 // @Tags     任务与日志回传
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} logWebhookStatusResponse
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/log-webhook [get]
 func (h *logEventHandler) getWebhook(c *gin.Context) {
@@ -45,7 +47,7 @@ func (h *logEventHandler) getWebhook(c *gin.Context) {
 // @Summary  生成
 // @Tags     任务与日志回传
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} service.LogWebhookInfo
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/log-webhook [post]
 func (h *logEventHandler) ensureWebhook(c *gin.Context) {
@@ -87,7 +89,7 @@ func (h *logEventHandler) revokeWebhook(c *gin.Context) {
 // @Tags     任务与日志回传
 // @Param    configId query int false "按配置过滤"
 // @Param    q query string false "关键字"
-// @Success  200 {object} map[string]any "items 与 total"
+// @Success  200 {object} pagedResponse[model.LogEvent] "items 与 total"
 // @Security BearerAuth
 // @Router   /api/v1/log-events [get]
 func (h *logEventHandler) list(c *gin.Context) {
@@ -111,7 +113,7 @@ func (h *logEventHandler) list(c *gin.Context) {
 // @Summary  查询 OCI 侧链路状态与关键事件清单
 // @Tags     任务与日志回传
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} service.RelayView
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/log-relay [get]
 func (h *logEventHandler) getRelay(c *gin.Context) {
@@ -132,7 +134,7 @@ func (h *logEventHandler) getRelay(c *gin.Context) {
 // @Summary  一键建立回传链路
 // @Tags     任务与日志回传
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} service.RelayView
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/log-relay [post]
 func (h *logEventHandler) setupRelay(c *gin.Context) {

internal/api/network.go

@@ -11,7 +11,7 @@ import (
 // @Summary  实例形状列表
 // @Tags     租户配置
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.ComputeShape
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/shapes [get]
 func (h *ociConfigHandler) shapes(c *gin.Context) {
@@ -30,7 +30,7 @@ func (h *ociConfigHandler) shapes(c *gin.Context) {
 // @Summary  镜像列表
 // @Tags     租户配置
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.Image
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/images [get]
 func (h *ociConfigHandler) images(c *gin.Context) {
@@ -54,7 +54,7 @@ func (h *ociConfigHandler) images(c *gin.Context) {
 // @Tags     租户配置
 // @Param    id path int true "配置 ID"
 // @Param    imageId path string true "imageId"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.Image
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/images/{imageId} [get]
 func (h *ociConfigHandler) getImage(c *gin.Context) {
@@ -89,7 +89,7 @@ type renameRequest struct {
 // @Summary  VCN 列表
 // @Tags     网络
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.VCN
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/vcns [get]
 func (h *ociConfigHandler) listVCNs(c *gin.Context) {
@@ -109,7 +109,7 @@ func (h *ociConfigHandler) listVCNs(c *gin.Context) {
 // @Tags     网络
 // @Param    id path int true "配置 ID"
 // @Param    body body createVCNRequest true "请求体"
-// @Success  201 {object} map[string]any
+// @Success  201 {object} oci.VCN
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/vcns [post]
 func (h *ociConfigHandler) createVCN(c *gin.Context) {
@@ -141,7 +141,7 @@ func (h *ociConfigHandler) createVCN(c *gin.Context) {
 // @Tags     网络
 // @Param    id path int true "配置 ID"
 // @Param    vcnId path string true "vcnId"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.VCN
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/vcns/{vcnId} [get]
 func (h *ociConfigHandler) getVCN(c *gin.Context) {
@@ -162,7 +162,7 @@ func (h *ociConfigHandler) getVCN(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    vcnId path string true "vcnId"
 // @Param    body body renameRequest true "请求体"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.VCN
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/vcns/{vcnId} [put]
 func (h *ociConfigHandler) updateVCN(c *gin.Context) {
@@ -211,7 +211,7 @@ type enableIPv6Request struct {
 // @Param    id path int true "配置 ID"
 // @Param    vcnId path string true "vcnId"
 // @Param    body body enableIPv6Request true "请求体"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} ipv6StepsResponse
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/vcns/{vcnId}/enable-ipv6 [post]
 func (h *ociConfigHandler) enableVCNIPv6(c *gin.Context) {
@@ -247,7 +247,7 @@ type createSubnetRequest struct {
 // @Summary  子网列表
 // @Tags     网络
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.Subnet
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/subnets [get]
 func (h *ociConfigHandler) listSubnets(c *gin.Context) {
@@ -267,7 +267,7 @@ func (h *ociConfigHandler) listSubnets(c *gin.Context) {
 // @Tags     网络
 // @Param    id path int true "配置 ID"
 // @Param    body body createSubnetRequest true "请求体"
-// @Success  201 {object} map[string]any
+// @Success  201 {object} oci.Subnet
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/subnets [post]
 func (h *ociConfigHandler) createSubnet(c *gin.Context) {
@@ -300,7 +300,7 @@ func (h *ociConfigHandler) createSubnet(c *gin.Context) {
 // @Tags     网络
 // @Param    id path int true "配置 ID"
 // @Param    subnetId path string true "subnetId"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.Subnet
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/subnets/{subnetId} [get]
 func (h *ociConfigHandler) getSubnet(c *gin.Context) {
@@ -321,7 +321,7 @@ func (h *ociConfigHandler) getSubnet(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    subnetId path string true "subnetId"
 // @Param    body body renameRequest true "请求体"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.Subnet
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/subnets/{subnetId} [put]
 func (h *ociConfigHandler) updateSubnet(c *gin.Context) {
@@ -381,7 +381,7 @@ type updateSecurityListRequest struct {
 // @Summary  安全列表清单
 // @Tags     网络
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.SecurityList
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/security-lists [get]
 func (h *ociConfigHandler) listSecurityLists(c *gin.Context) {
@@ -401,7 +401,7 @@ func (h *ociConfigHandler) listSecurityLists(c *gin.Context) {
 // @Tags     网络
 // @Param    id path int true "配置 ID"
 // @Param    body body createSecurityListRequest true "请求体"
-// @Success  201 {object} map[string]any
+// @Success  201 {object} oci.SecurityList
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/security-lists [post]
 func (h *ociConfigHandler) createSecurityList(c *gin.Context) {
@@ -432,7 +432,7 @@ func (h *ociConfigHandler) createSecurityList(c *gin.Context) {
 // @Tags     网络
 // @Param    id path int true "配置 ID"
 // @Param    securityListId path string true "securityListId"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.SecurityList
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/security-lists/{securityListId} [get]
 func (h *ociConfigHandler) getSecurityList(c *gin.Context) {
@@ -453,7 +453,7 @@ func (h *ociConfigHandler) getSecurityList(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    securityListId path string true "securityListId"
 // @Param    body body updateSecurityListRequest true "请求体"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.SecurityList
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/security-lists/{securityListId} [put]
 func (h *ociConfigHandler) updateSecurityList(c *gin.Context) {

internal/api/ociconfig.go

@@ -9,8 +9,10 @@ import (
 	"strconv"
 
 	"github.com/gin-gonic/gin"
+
 	"github.com/oracle/oci-go-sdk/v65/common"
 	"gorm.io/gorm"
+	_ "oci-portal/internal/model" // swagger 注解引用
 
 	"oci-portal/internal/oci"
 	"oci-portal/internal/service"
@@ -39,7 +41,7 @@ type importRequest struct {
 // @Summary  导入租户配置
 // @Tags     租户配置
 // @Param    body body importRequest true "API Key 配置(私钥密文落库)"
-// @Success  201 {object} map[string]any
+// @Success  201 {object} model.OciConfig
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs [post]
 func (h *ociConfigHandler) create(c *gin.Context) {
@@ -71,7 +73,7 @@ func (h *ociConfigHandler) create(c *gin.Context) {
 
 // @Summary  租户配置列表
 // @Tags     租户配置
-// @Success  200 {object} map[string]any "items"
+// @Success  200 {array} service.ConfigSummary
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs [get]
 func (h *ociConfigHandler) list(c *gin.Context) {
@@ -86,7 +88,7 @@ func (h *ociConfigHandler) list(c *gin.Context) {
 // @Summary  租户配置详情
 // @Tags     租户配置
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} model.OciConfig
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id} [get]
 func (h *ociConfigHandler) get(c *gin.Context) {
@@ -105,7 +107,7 @@ func (h *ociConfigHandler) get(c *gin.Context) {
 // @Summary  验证配置连通性并刷新画像
 // @Tags     租户配置
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} configChangesResponse "config 与 changes 字段变更对照"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/verify [post]
 func (h *ociConfigHandler) verify(c *gin.Context) {
@@ -139,7 +141,7 @@ type updateConfigRequest struct {
 // @Tags     租户配置
 // @Param    id path int true "配置 ID"
 // @Param    body body object true "可更新字段(别名/分组/代理/多区域开关等)"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} configChangesResponse "config 与 changes 字段变更对照"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id} [put]
 func (h *ociConfigHandler) update(c *gin.Context) {
@@ -194,7 +196,7 @@ func (h *ociConfigHandler) remove(c *gin.Context) {
 // @Summary  列出租户下全部 ACTIVE compartment
 // @Tags     租户配置
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.Compartment
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/compartments [get]
 func (h *ociConfigHandler) compartments(c *gin.Context) {
@@ -216,7 +218,7 @@ func (h *ociConfigHandler) compartments(c *gin.Context) {
 // @Summary  返回筛选器用区域列表：未开多区域支持只含默认区域
 // @Tags     租户配置
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} service.RegionSubscriptionView
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/cached-regions [get]
 func (h *ociConfigHandler) cachedRegions(c *gin.Context) {
@@ -237,7 +239,7 @@ func (h *ociConfigHandler) cachedRegions(c *gin.Context) {
 // @Summary  返回筛选器用区间列表：未开多区间支持返回空数组
 // @Tags     租户配置
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.Compartment
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/cached-compartments [get]
 func (h *ociConfigHandler) cachedCompartments(c *gin.Context) {

internal/api/overview.go

@@ -4,13 +4,15 @@ import (
 	"net/http"
 
 	"github.com/gin-gonic/gin"
+
+	_ "oci-portal/internal/service" // swagger 注解引用
 )
 
 // overview 返回总览页聚合数据（本地快照，不发云端请求）。
 //
 // @Summary  返回总览页聚合数据
 // @Tags     租户配置
-// @Success  200 {object} map[string]any
+// @Success  200 {object} service.Overview
 // @Security BearerAuth
 // @Router   /api/v1/overview [get]
 func (h *ociConfigHandler) overview(c *gin.Context) {

internal/api/proxy.go

@@ -18,7 +18,7 @@ type proxyHandler struct {
 //
 // @Summary  代理列表
 // @Tags     设置
-// @Success  200 {object} map[string]any "items"
+// @Success  200 {object} itemsResponse[service.ProxyView] "items"
 // @Security BearerAuth
 // @Router   /api/v1/proxies [get]
 func (h *proxyHandler) list(c *gin.Context) {
@@ -35,7 +35,7 @@ func (h *proxyHandler) list(c *gin.Context) {
 // @Summary  创建代理
 // @Tags     设置
 // @Param    body body service.ProxyInput true "代理配置(密码只写不回)"
-// @Success  201 {object} map[string]any
+// @Success  201 {object} service.ProxyView
 // @Security BearerAuth
 // @Router   /api/v1/proxies [post]
 func (h *proxyHandler) create(c *gin.Context) {
@@ -58,7 +58,7 @@ func (h *proxyHandler) create(c *gin.Context) {
 // @Tags     设置
 // @Param    id path int true "代理 ID"
 // @Param    body body service.ProxyInput true "代理配置(密码缺省沿用)"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} service.ProxyView
 // @Security BearerAuth
 // @Router   /api/v1/proxies/{id} [put]
 func (h *proxyHandler) update(c *gin.Context) {
@@ -104,7 +104,7 @@ func (h *proxyHandler) remove(c *gin.Context) {
 // @Summary  批量导入代理
 // @Tags     设置
 // @Param    body body object true "请求体(见接口说明)"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} service.ImportResult
 // @Security BearerAuth
 // @Router   /api/v1/proxies/import [post]
 func (h *proxyHandler) importBatch(c *gin.Context) {
@@ -128,7 +128,7 @@ func (h *proxyHandler) importBatch(c *gin.Context) {
 // @Summary  手动重测代理出口地区,同步返回最新视图
 // @Tags     设置
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} service.ProxyView
 // @Security BearerAuth
 // @Router   /api/v1/proxies/{id}/probe [post]
 func (h *proxyHandler) probe(c *gin.Context) {
@@ -150,7 +150,7 @@ func (h *proxyHandler) probe(c *gin.Context) {
 // @Tags     设置
 // @Param    id path int true "代理 ID"
 // @Param    body body object true "请求体 {\"ociConfigIds\": [1,2]}"
-// @Success  200 {object} map[string]any "usedBy"
+// @Success  200 {object} usedByResponse "usedBy"
 // @Security BearerAuth
 // @Router   /api/v1/proxies/{id}/tenants [put]
 func (h *proxyHandler) setTenants(c *gin.Context) {

internal/api/region.go

@@ -6,6 +6,8 @@ import (
 
 	"github.com/gin-gonic/gin"
 
+	_ "oci-portal/internal/service" // swagger 注解引用
+
 	"oci-portal/internal/oci"
 )
 
@@ -13,7 +15,7 @@ import (
 //
 // @Summary  返回本地维护的完整区域表
 // @Tags     租户配置
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.RegionInfo
 // @Security BearerAuth
 // @Router   /api/v1/regions [get]
 func listRegions(c *gin.Context) {
@@ -28,7 +30,7 @@ func listRegions(c *gin.Context) {
 // @Summary  区域订阅列表
 // @Tags     租户配置
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} service.RegionSubscriptionView
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/region-subscriptions [get]
 func (h *ociConfigHandler) regionSubscriptions(c *gin.Context) {
@@ -52,7 +54,7 @@ type subscribeRegionRequest struct {
 // @Tags     租户配置
 // @Param    id path int true "配置 ID"
 // @Param    body body subscribeRegionRequest true "请求体"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} service.RegionSubscriptionView
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/region-subscriptions [post]
 func (h *ociConfigHandler) subscribeRegion(c *gin.Context) {
@@ -76,7 +78,7 @@ func (h *ociConfigHandler) subscribeRegion(c *gin.Context) {
 // @Summary  服务限额查询
 // @Tags     租户配置
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.LimitValue
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/limits [get]
 func (h *ociConfigHandler) limits(c *gin.Context) {

internal/api/routes_ai.go

@@ -15,6 +15,10 @@ func registerAiGateway(r *gin.Engine, aiGateway *service.AiGatewayService) {
 	ai.POST("/responses", aih.responses)
 	ai.POST("/messages", aih.messages)
 	ai.POST("/embeddings", aih.embeddings)
+	ai.POST("/audio/speech", aih.audioSpeech)
+	ai.POST("/tts", aih.tts)
+	ai.POST("/rerank", aih.rerank)
+	ai.POST("/moderations", aih.moderations)
 	ai.GET("/models", aih.listModels)
 }
 
@@ -32,7 +36,12 @@ func registerAiAdmin(secured *gin.RouterGroup, aiGateway *service.AiGatewayServi
 	secured.DELETE("/ai-channels/:id", aiadmin.deleteChannel)
 	secured.POST("/ai-channels/:id/probe", aiadmin.probeChannel)
 	secured.POST("/ai-channels/:id/sync-models", aiadmin.syncChannelModels)
+	secured.GET("/ai-channels/:id/models", aiadmin.listChannelModels)
+	secured.POST("/ai-channels/:id/test-model", aiadmin.testChannelModel)
 	secured.GET("/ai-models", aiadmin.gatewayModels)
+	secured.GET("/ai-model-catalog", aiadmin.modelCatalog)
+	secured.GET("/ai-settings", aiadmin.aiSettings)
+	secured.PUT("/ai-settings", aiadmin.updateAiSettings)
 	secured.GET("/ai-blacklist", aiadmin.listBlacklist)
 	secured.POST("/ai-blacklist", aiadmin.addBlacklist)
 	secured.DELETE("/ai-blacklist/:id", aiadmin.removeBlacklist)

internal/api/routes_auth.go

@@ -12,7 +12,7 @@ func registerAuthPublic(v1 *gin.RouterGroup, auth *service.AuthService, oauth *s
 	v1.POST("/auth/login", ah.login)
 
 	// 外部身份登录:provider 列表 / 授权跳转(bind 模式 handler 内校验 JWT)/ 回调
-	ax := &authxHandler{auth: auth, oauth: oauth}
+	ax := &authxHandler{auth: auth, oauth: oauth, logs: systemLogs}
 	v1.GET("/auth/oauth/providers", ax.oauthProviders)
 	v1.GET("/auth/oauth/:provider/authorize", ax.oauthAuthorize)
 	v1.GET("/auth/oauth/:provider/callback", ax.oauthCallback)

internal/api/settings.go

@@ -19,7 +19,7 @@ type settingsHandler struct {
 //
 // @Summary  返回脱敏后的 Telegram 配置，绝不回 token 明文
 // @Tags     设置
-// @Success  200 {object} map[string]any
+// @Success  200 {object} service.TelegramView
 // @Security BearerAuth
 // @Router   /api/v1/settings/telegram [get]
 func (h *settingsHandler) getTelegram(c *gin.Context) {
@@ -44,7 +44,7 @@ type updateTelegramRequest struct {
 // @Summary  保存配置并返回最新脱敏视图
 // @Tags     设置
 // @Param    body body updateTelegramRequest true "请求体"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} service.TelegramView
 // @Security BearerAuth
 // @Router   /api/v1/settings/telegram [put]
 func (h *settingsHandler) updateTelegram(c *gin.Context) {
@@ -84,7 +84,7 @@ func (h *settingsHandler) testTelegram(c *gin.Context) {
 //
 // @Summary  返回全部通知渠道的脱敏视图
 // @Tags     设置
-// @Success  200 {object} map[string]any
+// @Success  200 {object} itemsResponse[service.NotifyChannelView]
 // @Security BearerAuth
 // @Router   /api/v1/settings/notify-channels [get]
 func (h *settingsHandler) listNotifyChannels(c *gin.Context) {
@@ -119,7 +119,7 @@ type updateNotifyChannelRequest struct {
 // @Tags     设置
 // @Param    type path string true "渠道类型(webhook/ntfy/bark/smtp)"
 // @Param    body body updateNotifyChannelRequest true "请求体"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} itemsResponse[service.NotifyChannelView]
 // @Security BearerAuth
 // @Router   /api/v1/settings/notify-channels/{type} [put]
 func (h *settingsHandler) updateNotifyChannel(c *gin.Context) {
@@ -160,7 +160,7 @@ func (h *settingsHandler) testNotifyChannel(c *gin.Context) {
 //
 // @Summary  返回全部通知事件开关
 // @Tags     设置
-// @Success  200 {object} map[string]any
+// @Success  200 {object} service.NotifyEventsView
 // @Security BearerAuth
 // @Router   /api/v1/settings/notify-events [get]
 func (h *settingsHandler) getNotifyEvents(c *gin.Context) {
@@ -178,7 +178,7 @@ func (h *settingsHandler) getNotifyEvents(c *gin.Context) {
 // @Summary  全量保存五个事件开关并返回最新值
 // @Tags     设置
 // @Param    body body service.NotifyEventsView true "请求体"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} service.NotifyEventsView
 // @Security BearerAuth
 // @Router   /api/v1/settings/notify-events [put]
 func (h *settingsHandler) updateNotifyEvents(c *gin.Context) {
@@ -198,7 +198,7 @@ func (h *settingsHandler) updateNotifyEvents(c *gin.Context) {
 //
 // @Summary  返回全部通知模板
 // @Tags     设置
-// @Success  200 {object} map[string]any
+// @Success  200 {object} itemsResponse[service.NotifyTemplateView]
 // @Security BearerAuth
 // @Router   /api/v1/settings/notify-templates [get]
 func (h *settingsHandler) listNotifyTemplates(c *gin.Context) {
@@ -263,7 +263,7 @@ func (h *settingsHandler) testNotifyTemplate(c *gin.Context) {
 //
 // @Summary  返回任务行为设置
 // @Tags     设置
-// @Success  200 {object} map[string]any
+// @Success  200 {object} service.TaskSettingsView
 // @Security BearerAuth
 // @Router   /api/v1/settings/task [get]
 func (h *settingsHandler) getTaskSettings(c *gin.Context) {
@@ -280,7 +280,7 @@ func (h *settingsHandler) getTaskSettings(c *gin.Context) {
 // @Summary  保存任务行为设置并返回最新值
 // @Tags     设置
 // @Param    body body service.TaskSettingsView true "请求体"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} service.TaskSettingsView
 // @Security BearerAuth
 // @Router   /api/v1/settings/task [put]
 func (h *settingsHandler) updateTaskSettings(c *gin.Context) {
@@ -304,7 +304,7 @@ func (h *settingsHandler) updateTaskSettings(c *gin.Context) {
 //
 // @Summary  返回安全设置
 // @Tags     设置
-// @Success  200 {object} map[string]any
+// @Success  200 {object} service.SecuritySettings
 // @Security BearerAuth
 // @Router   /api/v1/settings/security [get]
 func (h *settingsHandler) getSecurity(c *gin.Context) {
@@ -321,7 +321,7 @@ func (h *settingsHandler) getSecurity(c *gin.Context) {
 // @Summary  保存安全设置并返回最新值
 // @Tags     设置
 // @Param    body body service.SecuritySettings true "请求体"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} service.SecuritySettings
 // @Security BearerAuth
 // @Router   /api/v1/settings/security [put]
 func (h *settingsHandler) updateSecurity(c *gin.Context) {

internal/api/subscription.go

@@ -4,12 +4,14 @@ import (
 	"net/http"
 
 	"github.com/gin-gonic/gin"
+
+	_ "oci-portal/internal/oci" // swagger 注解引用
 )
 
 // @Summary  订阅列表
 // @Tags     租户配置
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.SubscriptionInfo
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/subscriptions [get]
 func (h *ociConfigHandler) subscriptions(c *gin.Context) {
@@ -29,7 +31,7 @@ func (h *ociConfigHandler) subscriptions(c *gin.Context) {
 // @Tags     租户配置
 // @Param    id path int true "配置 ID"
 // @Param    subscriptionId path string true "subscriptionId"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.SubscriptionDetail
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/subscriptions/{subscriptionId} [get]
 func (h *ociConfigHandler) subscriptionDetail(c *gin.Context) {
@@ -48,7 +50,7 @@ func (h *ociConfigHandler) subscriptionDetail(c *gin.Context) {
 // @Summary  限额服务列表
 // @Tags     租户配置
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.LimitService
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/limits/services [get]
 func (h *ociConfigHandler) limitServices(c *gin.Context) {

internal/api/swagger_resp.go

@@ -0,0 +1,176 @@
+package api
+
+import (
+	"encoding/json"
+	"time"
+
+	"oci-portal/internal/model"
+	"oci-portal/internal/oci"
+	"oci-portal/internal/service"
+)
+
+// 本文件的类型仅供 swagger 文档渲染(@Success/@Failure 注解引用),
+// 运行时代码不使用;字段与各 handler 返回的 gin.H 外壳保持一致。
+
+// errorResponse 是统一错误响应外壳。
+type errorResponse struct {
+	Error string `json:"error"`
+}
+
+// itemsResponse 是 {"items": [...]} 列表外壳。
+type itemsResponse[T any] struct {
+	Items []T `json:"items"`
+}
+
+// pagedResponse 是 {"items": [...], "total": n} 分页外壳。
+type pagedResponse[T any] struct {
+	Items []T   `json:"items"`
+	Total int64 `json:"total"`
+}
+
+// itemResponse 是 {"item": {...}} 单项外壳。
+type itemResponse[T any] struct {
+	Item T `json:"item"`
+}
+
+// triggerResponse 是任务触发受理响应。
+type triggerResponse struct {
+	Triggered bool `json:"triggered"`
+}
+
+// tokenResponse 是登录 / 换发令牌响应。
+type tokenResponse struct {
+	Token     string    `json:"token"`
+	ExpiresAt time.Time `json:"expiresAt"`
+}
+
+// totpRequiredResponse 是密码通过但需两步验证码的 428 响应。
+type totpRequiredResponse struct {
+	Error        string `json:"error"`
+	TotpRequired bool   `json:"totpRequired"`
+}
+
+// enabledResponse 是布尔开关查询响应。
+type enabledResponse struct {
+	Enabled bool `json:"enabled"`
+}
+
+// totpSetupResponse 是 TOTP 初始化响应。
+type totpSetupResponse struct {
+	Secret     string `json:"secret"`
+	OtpauthUri string `json:"otpauthUri"`
+}
+
+// credentialsResponse 是当前登录账号信息。
+type credentialsResponse struct {
+	Username              string `json:"username"`
+	PasswordLoginDisabled bool   `json:"passwordLoginDisabled"`
+}
+
+// oauthProvidersResponse 是外部登录 provider 列表。
+type oauthProvidersResponse struct {
+	Providers             []service.ProviderInfo `json:"providers"`
+	PasswordLoginDisabled bool                   `json:"passwordLoginDisabled"`
+}
+
+// urlResponse 是跳转地址响应。
+type urlResponse struct {
+	URL string `json:"url"`
+}
+
+// aboutResponse 是「设置 · 关于」页构建与运行信息。
+type aboutResponse struct {
+	Version       string         `json:"version"`
+	BuildTime     string         `json:"buildTime"`
+	GoVersion     string         `json:"goVersion"`
+	Platform      string         `json:"platform"`
+	StartedAt     string         `json:"startedAt"`
+	UptimeSeconds int64          `json:"uptimeSeconds"`
+	Resources     aboutResources `json:"resources"`
+}
+
+// aboutResources 是进程资源占用快照。
+type aboutResources struct {
+	CpuAvgPercent float64 `json:"cpuAvgPercent"`
+	NumCpu        int     `json:"numCpu"`
+	Goroutines    int     `json:"goroutines"`
+	MemHeapBytes  uint64  `json:"memHeapBytes"`
+	MemSysBytes   uint64  `json:"memSysBytes"`
+	DbEngine      string  `json:"dbEngine"`
+	DbBytes       int64   `json:"dbBytes"`
+}
+
+// publicIpResponse 是换绑公网 IP 结果。
+type publicIpResponse struct {
+	PublicIp string `json:"publicIp"`
+}
+
+// ipv6AddressResponse 是实例新增 IPv6 结果。
+type ipv6AddressResponse struct {
+	Ipv6Address string `json:"ipv6Address"`
+}
+
+// addressResponse 是 VNIC 新增 IPv6 结果。
+type addressResponse struct {
+	Address string `json:"address"`
+}
+
+// ipv6StepsResponse 是 VCN 开启 IPv6 的分步结果。
+type ipv6StepsResponse struct {
+	Steps []oci.IPv6Step `json:"steps"`
+}
+
+// configChangesResponse 是租户配置校验 / 更新结果(config 与字段变更对照)。
+type configChangesResponse struct {
+	Config  *model.OciConfig `json:"config"`
+	Changes service.Changes  `json:"changes"`
+}
+
+// aiKeyCreateResponse 是 AI 密钥创建结果;key 为明文,仅本次返回。
+type aiKeyCreateResponse struct {
+	Key  string      `json:"key"`
+	Item model.AiKey `json:"item"`
+}
+
+// usedByResponse 是代理关联租户结果(关联数)。
+type usedByResponse struct {
+	UsedBy int64 `json:"usedBy"`
+}
+
+// rawDetailResponse 是审计事件原文响应。
+type rawDetailResponse struct {
+	Raw json.RawMessage `json:"raw"`
+}
+
+// passwordResponse 是租户用户重置密码结果(一次性明文)。
+type passwordResponse struct {
+	Password string `json:"password"`
+}
+
+// deletedTotpResponse 是清除 MFA 设备结果。
+type deletedTotpResponse struct {
+	DeletedTotpDevices int `json:"deletedTotpDevices"`
+}
+
+// deletedApiKeysResponse 是清理用户 API Key 结果。
+type deletedApiKeysResponse struct {
+	DeletedApiKeys int `json:"deletedApiKeys"`
+}
+
+// createInstancesResponse 是批量创建实例结果;部分成功仍 201,errors 为逐台失败信息。
+type createInstancesResponse struct {
+	Instances []oci.Instance `json:"instances"`
+	Errors    []string       `json:"errors"`
+}
+
+// logWebhookStatusResponse 是日志回传 webhook 状态。
+type logWebhookStatusResponse struct {
+	Exists  bool                    `json:"exists"`
+	Webhook *service.LogWebhookInfo `json:"webhook,omitempty"`
+}
+
+// webConsoleSessionResponse 是网页控制台会话创建结果。
+type webConsoleSessionResponse struct {
+	SessionId string `json:"sessionId"`
+	Type      string `json:"type"`
+}

internal/api/systemlog.go

@@ -6,6 +6,7 @@ import (
 
 	"github.com/gin-gonic/gin"
 
+	_ "oci-portal/internal/model" // swagger 注解引用
 	"oci-portal/internal/service"
 )
 
@@ -18,7 +19,7 @@ type systemLogHandler struct {
 //
 // @Summary  系统操作日志列表
 // @Tags     设置
-// @Success  200 {object} map[string]any "items 与 total"
+// @Success  200 {object} pagedResponse[model.SystemLog] "items 与 total"
 // @Security BearerAuth
 // @Router   /api/v1/system-logs [get]
 func (h *systemLogHandler) list(c *gin.Context) {

internal/api/task.go

@@ -8,6 +8,7 @@ import (
 
 	"github.com/gin-gonic/gin"
 
+	_ "oci-portal/internal/model" // swagger 注解引用
 	"oci-portal/internal/service"
 )
 
@@ -33,7 +34,7 @@ type updateTaskRequest struct {
 // @Summary  创建任务
 // @Tags     任务与日志回传
 // @Param    body body createTaskRequest true "任务定义(类型/cron/payload)"
-// @Success  201 {object} map[string]any
+// @Success  201 {object} model.Task
 // @Security BearerAuth
 // @Router   /api/v1/tasks [post]
 func (h *taskHandler) create(c *gin.Context) {
@@ -57,7 +58,7 @@ func (h *taskHandler) create(c *gin.Context) {
 
 // @Summary  任务列表
 // @Tags     任务与日志回传
-// @Success  200 {array} map[string]any
+// @Success  200 {array} model.Task
 // @Security BearerAuth
 // @Router   /api/v1/tasks [get]
 func (h *taskHandler) list(c *gin.Context) {
@@ -72,7 +73,7 @@ func (h *taskHandler) list(c *gin.Context) {
 // @Summary  任务详情
 // @Tags     任务与日志回传
 // @Param    id path int true "任务 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} model.Task
 // @Security BearerAuth
 // @Router   /api/v1/tasks/{id} [get]
 func (h *taskHandler) get(c *gin.Context) {
@@ -92,7 +93,7 @@ func (h *taskHandler) get(c *gin.Context) {
 // @Tags     任务与日志回传
 // @Param    id path int true "任务 ID"
 // @Param    body body updateTaskRequest true "可更新字段"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} model.Task
 // @Security BearerAuth
 // @Router   /api/v1/tasks/{id} [put]
 func (h *taskHandler) update(c *gin.Context) {
@@ -139,7 +140,7 @@ func (h *taskHandler) remove(c *gin.Context) {
 // @Summary  任务执行日志
 // @Tags     任务与日志回传
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} model.TaskLog
 // @Security BearerAuth
 // @Router   /api/v1/tasks/{id}/logs [get]
 func (h *taskHandler) logs(c *gin.Context) {
@@ -159,8 +160,8 @@ func (h *taskHandler) logs(c *gin.Context) {
 // @Summary  立即执行任务(异步触发,结果经任务日志轮询获取)
 // @Tags     任务与日志回传
 // @Param    id path int true "配置 ID"
-// @Success  202 {object} map[string]any
+// @Success  202 {object} triggerResponse
-// @Failure  409 {object} map[string]any "任务正在执行中"
+// @Failure  409 {object} errorResponse "任务正在执行中"
 // @Security BearerAuth
 // @Router   /api/v1/tasks/{id}/run [post]
 func (h *taskHandler) run(c *gin.Context) {

internal/api/tenant.go

@@ -18,7 +18,7 @@ import (
 // @Tags     计算
 // @Param    id path int true "配置 ID"
 // @Param    instanceId path string true "instanceId"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.InstanceTraffic
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/instances/{instanceId}/traffic [get]
 func (h *ociConfigHandler) instanceTraffic(c *gin.Context) {
@@ -38,7 +38,7 @@ func (h *ociConfigHandler) instanceTraffic(c *gin.Context) {
 // @Summary  配置成本快照
 // @Tags     成本
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.CostItem
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/costs [get]
 func (h *ociConfigHandler) costs(c *gin.Context) {
@@ -68,14 +68,16 @@ func (h *ociConfigHandler) costs(c *gin.Context) {
 // ---- 租户审计日志 ----
 
 // getAuditEvents 批式懒加载查询审计事件:cursor 为空自当前时刻首查,
-// 非空从上次响应游标继续向更早回溯;limit 单批目标条数(缺省 100,上限 200)。
+// 非空从上次响应游标继续向更早回溯;limit 单批目标条数(缺省 100,上限 200);
+// q 为服务端全文检索关键字,仅首查生效,续查沿用游标内嵌关键字。
 //
 // @Summary  批式懒加载查询租户 OCI 审计事件
 // @Tags     租户 IAM
 // @Param    id path int true "配置 ID"
 // @Param    cursor query string false "续查游标(上次响应原样带回)"
 // @Param    limit query int false "单批目标条数,缺省 100,上限 200"
-// @Success  200 {object} map[string]any
+// @Param    q query string false "检索关键字(服务端全文匹配,支持 * 通配;仅首查生效)"
+// @Success  200 {object} service.AuditEventsView
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/audit-events [get]
 func (h *ociConfigHandler) getAuditEvents(c *gin.Context) {
@@ -84,7 +86,7 @@ func (h *ociConfigHandler) getAuditEvents(c *gin.Context) {
 		return
 	}
 	limit, _ := strconv.Atoi(c.Query("limit"))
-	q := service.AuditQuery{Region: c.Query("region"), Cursor: c.Query("cursor"), Limit: limit}
+	q := service.AuditQuery{Region: c.Query("region"), Cursor: c.Query("cursor"), Limit: limit, Q: c.Query("q")}
 	result, err := h.svc.AuditEvents(c.Request.Context(), id, q)
 	if errors.Is(err, service.ErrInvalidAuditCursor) {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
@@ -103,7 +105,7 @@ func (h *ociConfigHandler) getAuditEvents(c *gin.Context) {
 // @Summary  按 eventId 取回原始事件 JSON:缓存命中秒开,
 // @Tags     租户 IAM
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} rawDetailResponse "raw 为事件原文 JSON"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/audit-events/detail [get]
 func (h *ociConfigHandler) getAuditEventDetail(c *gin.Context) {
@@ -145,7 +147,7 @@ type createTenantUserRequest struct {
 // @Summary  租户身份域列表
 // @Tags     租户 IAM
 // @Param    id path int true "配置 ID"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.IdentityDomain
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/domains [get]
 func (h *ociConfigHandler) listIdentityDomains(c *gin.Context) {
@@ -165,7 +167,7 @@ func (h *ociConfigHandler) listIdentityDomains(c *gin.Context) {
 // @Tags     租户 IAM
 // @Param    id path int true "配置 ID"
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.TenantUser
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/users [get]
 func (h *ociConfigHandler) listTenantUsers(c *gin.Context) {
@@ -186,7 +188,7 @@ func (h *ociConfigHandler) listTenantUsers(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
 // @Param    userId path string true "userId"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.TenantUserDetail
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/users/{userId} [get]
 func (h *ociConfigHandler) getTenantUserDetail(c *gin.Context) {
@@ -207,7 +209,7 @@ func (h *ociConfigHandler) getTenantUserDetail(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
 // @Param    body body createTenantUserRequest true "请求体"
-// @Success  201 {object} map[string]any
+// @Success  201 {object} oci.TenantUser
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/users [post]
 func (h *ociConfigHandler) createTenantUser(c *gin.Context) {
@@ -253,7 +255,7 @@ type updateTenantUserRequest struct {
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
 // @Param    userId path string true "userId"
 // @Param    body body updateTenantUserRequest true "请求体"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.TenantUser
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/users/{userId} [put]
 func (h *ociConfigHandler) updateTenantUser(c *gin.Context) {
@@ -306,7 +308,7 @@ func (h *ociConfigHandler) deleteTenantUser(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
 // @Param    userId path string true "userId"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} passwordResponse "一次性明文密码"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/users/{userId}/reset-password [post]
 func (h *ociConfigHandler) resetTenantUserPassword(c *gin.Context) {
@@ -327,7 +329,7 @@ func (h *ociConfigHandler) resetTenantUserPassword(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
 // @Param    userId path string true "userId"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} deletedTotpResponse
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/users/{userId}/mfa-devices [delete]
 func (h *ociConfigHandler) deleteTenantUserMfa(c *gin.Context) {
@@ -347,7 +349,7 @@ func (h *ociConfigHandler) deleteTenantUserMfa(c *gin.Context) {
 // @Tags     租户 IAM
 // @Param    id path int true "配置 ID"
 // @Param    userId path string true "userId"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} deletedApiKeysResponse
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/users/{userId}/api-keys [delete]
 func (h *ociConfigHandler) deleteTenantUserApiKeys(c *gin.Context) {
@@ -370,7 +372,7 @@ func (h *ociConfigHandler) deleteTenantUserApiKeys(c *gin.Context) {
 // @Tags     租户 IAM
 // @Param    id path int true "配置 ID"
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.NotificationRecipients
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/notification-recipients [get]
 func (h *ociConfigHandler) getNotificationRecipients(c *gin.Context) {
@@ -391,7 +393,7 @@ func (h *ociConfigHandler) getNotificationRecipients(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
 // @Param    body body object true "请求体(见接口说明)"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.NotificationRecipients
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/notification-recipients [put]
 func (h *ociConfigHandler) updateNotificationRecipients(c *gin.Context) {
@@ -418,7 +420,7 @@ func (h *ociConfigHandler) updateNotificationRecipients(c *gin.Context) {
 // @Tags     租户 IAM
 // @Param    id path int true "配置 ID"
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
-// @Success  200 {object} map[string]any
+// @Success  200 {array} oci.PasswordPolicyInfo
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/password-policies [get]
 func (h *ociConfigHandler) listPasswordPolicies(c *gin.Context) {
@@ -440,7 +442,7 @@ func (h *ociConfigHandler) listPasswordPolicies(c *gin.Context) {
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
 // @Param    policyId path string true "policyId"
 // @Param    body body object true "请求体(见接口说明)"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.PasswordPolicyInfo
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/password-policies/{policyId} [put]
 func (h *ociConfigHandler) updatePasswordPolicy(c *gin.Context) {
@@ -473,7 +475,7 @@ func (h *ociConfigHandler) updatePasswordPolicy(c *gin.Context) {
 // @Tags     租户 IAM
 // @Param    id path int true "配置 ID"
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.IdentitySettingInfo
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/identity-settings [get]
 func (h *ociConfigHandler) getIdentitySetting(c *gin.Context) {
@@ -494,7 +496,7 @@ func (h *ociConfigHandler) getIdentitySetting(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
 // @Param    body body object true "请求体(见接口说明)"
-// @Success  200 {object} map[string]any
+// @Success  200 {object} oci.IdentitySettingInfo
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/identity-settings [put]
 func (h *ociConfigHandler) updateIdentitySetting(c *gin.Context) {

internal/api/webconsole.go

@@ -29,7 +29,7 @@ type createConsoleSessionRequest struct {
 // @Param    id path int true "配置 ID"
 // @Param    instanceId path string true "实例 OCID"
 // @Param    body body object true "{type: serial|vnc}"
-// @Success  200 {object} map[string]any "sessionId 与 wsPath"
+// @Success  201 {object} webConsoleSessionResponse "sessionId 与 type"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/instances/{instanceId}/console-sessions [post]
 func (h *consoleHandler) create(c *gin.Context) {

internal/api/webhook.go

@@ -53,7 +53,7 @@ type webhookHandler struct {
 // @Param    secret path string true "面板生成的回传密钥(鉴权凭据)"
 // @Param    body body object true "ONS 消息原文(SubscriptionConfirmation / Notification)"
 // @Success  200 "已受理"
-// @Failure  403 {object} map[string]string "时间戳超窗或证书源非 Oracle 域"
+// @Failure  403 {object} errorResponse "时间戳超窗或证书源非 Oracle 域"
 // @Failure  404 "secret 无效(不暴露端点存在性)"
 // @Router   /api/v1/webhooks/oci-logs/{secret} [post]
 func (h *webhookHandler) handle(c *gin.Context) {

internal/model/models.go

@@ -268,12 +268,16 @@ type AiChannel struct {
 	LastProbeAt   *time.Time `json:"lastProbeAt"`
 	ProbeStatus   string     `gorm:"size:16" json:"probeStatus"` // ok / no_service / no_quota / error
 	ProbeError    string     `gorm:"size:512" json:"probeError"`
+	// ProbeModel 是用户测试通过后固定的探测验证模型名;探测时置于候选首位
+	ProbeModel string    `gorm:"size:96" json:"probeModel"`
 	CreatedAt  time.Time `json:"createdAt"`
 	UpdatedAt  time.Time `json:"updatedAt"`
+	// ModelCount 是渠道模型缓存计数,列表查询回填,不落库
+	ModelCount int64 `gorm:"-" json:"modelCount"`
 }
 
 // AiModelCache 是渠道区域的可用模型缓存(整渠道覆盖式同步)。
-// Capability 为 CHAT / EMBEDDING;存量空串视为 CHAT(加列前只同步对话模型)。
+// Capability 为 CHAT / EMBEDDING / RERANK / TTS;存量空串视为 CHAT(加列前只同步对话模型)。
 type AiModelCache struct {
 	ID         uint      `gorm:"primaryKey" json:"-"`
 	ChannelID  uint      `gorm:"index" json:"channelId"`

internal/oci/audit.go

@@ -6,19 +6,29 @@ import (
 	"fmt"
 	"net"
 	"sort"
+	"strings"
 	"time"
 
 	"github.com/oracle/oci-go-sdk/v65/audit"
 	"github.com/oracle/oci-go-sdk/v65/common"
+	"github.com/oracle/oci-go-sdk/v65/loggingsearch"
 )
 
-// maxAuditPages 限制单次查询的翻页数:繁忙租户单日事件可上千,
+// maxAuditPages 限制单次查询的翻页数:每页最多 auditSearchPageLimit 条,
-// 到限即返回 Truncated=true,由调用方收窄时间窗。
+// 到限即截断(窗口式回传 Truncated,批式留游标),由调用方续查。
-// 默认过滤(噪声事件/内网发起)后有效结果变少,页数放宽到 10 缓解截断。
 const maxAuditPages = 10
 
+// auditBatchTimeBudget 是批式查询的单批耗时预算:全文检索命中稀疏时
+// 大窗扫描单页可达十余秒,超时即带游标返回,把长回溯拆成多个有界请求,
+// 前端按已回溯位置展示进度并自动续查。
+const auditBatchTimeBudget = 20 * time.Second
+
+// auditSearchPageLimit 是 SearchLogs 单页条数(API 上限 1000):批式查询
+// 攒满目标条数(~100)即携整页返回,页取 200 兼顾单页凑满一批与响应体量。
+const auditSearchPageLimit = 200
+
 // AuditEvent 是审计事件的列表精简视图;EventId 为 CloudEvents 全局唯一 id,
-// 详情反查的键。Raw 为 SDK 原始事件的 JSON 序列化,由 service 层剥离进缓存,
+// 详情反查的键。Raw 为 _Audit 日志 logContent 原文,由 service 层剥离进缓存,
 // 列表响应不再携带(详情接口按 eventId 取回)。
 type AuditEvent struct {
 	EventId         string          `json:"eventId"`
@@ -35,7 +45,7 @@ type AuditEvent struct {
 	Raw             json.RawMessage `json:"raw,omitempty"`
 }
 
-// AuditEventsResult 是一次审计查询的结果;Truncated 表示翻页到限被截断,
+// AuditEventsResult 是一次窗口式审计查询的结果;Truncated 表示翻页到限被截断,
 // 此时 NextPage 携带 opc-next-page 游标,同一时间窗回传可断点续翻。
 type AuditEventsResult struct {
 	Items     []AuditEvent `json:"items"`
@@ -43,6 +53,324 @@ type AuditEventsResult struct {
 	NextPage  string       `json:"nextPage,omitempty"`
 }
 
+// auditSearchClient 构造区域化的日志搜索客户端。审计数据源为 Logging Search
+// 的 _Audit 日志:Audit API 无排序参数、窗口内固定按处理时间正序,首批只能
+// 拿到窗口内最旧的一段;Logging Search 支持 datetime 倒序,才能从最新回溯。
+func (c *RealClient) auditSearchClient(cred Credentials, region string) (loggingsearch.LogSearchClient, error) {
+	sc, err := loggingsearch.NewLogSearchClientWithConfigurationProvider(provider(cred))
+	if err != nil {
+		return sc, fmt.Errorf("new logging search client: %w", err)
+	}
+	applyProxy(&sc.BaseClient, cred)
+	if region != "" {
+		sc.SetRegion(normalizeRegion(region))
+	}
+	return sc, nil
+}
+
+// auditSearchQuery 组装租户根 compartment 审计日志的倒序检索语句;
+// SummarizeMetricsData 遥测噪声占比高,服务端先滤一道减少无效翻页。
+// q 非空时追加 logContent 全文包含匹配——它扫的是整条 JSON 的所有值,只当
+// 粗筛;可见字段的精筛由 filterAuditTerm 兜底,避免隐藏元数据误命中。
+func auditSearchQuery(tenancyOCID, q string) string {
+	query := fmt.Sprintf("search %q | where data.eventName != 'SummarizeMetricsData'", tenancyOCID+"/_Audit")
+	if term := SanitizeAuditTerm(q); term != "" {
+		query += fmt.Sprintf(" and logContent = '*%s*'", term)
+	}
+	return query + " | sort by datetime desc"
+}
+
+// auditTermMaxLen 限制检索关键字长度,防止游标与查询语句被撑爆。
+const auditTermMaxLen = 100
+
+// SanitizeAuditTerm 归一检索关键字:去除引号/反斜杠/控制字符防语句注入
+// (查询目标已锁定本租户 _Audit 流,注入最坏只是语法错),截断超长输入;
+// 保留 * 供用户通配。返回空串表示不追加过滤子句。
+// service 构造首查游标与本包组装语句共用,对篡改游标二次消毒兜底。
+func SanitizeAuditTerm(q string) string {
+	out := make([]rune, 0, len(q))
+	for _, r := range q {
+		if r == '\'' || r == '"' || r == '\\' || r < 0x20 {
+			continue
+		}
+		out = append(out, r)
+		if len(out) >= auditTermMaxLen {
+			break
+		}
+	}
+	return strings.TrimSpace(string(out))
+}
+
+// ListAuditEvents 实现 Client:实时查询租户根 compartment 在 [start, end) 内的
+// 审计事件,最多翻 maxAuditPages 页,结果按发生时间倒序;纯读不落库。
+// page 非空时从该游标断点续翻(必须配同一时间窗);到限截断时回传 NextPage。
+// Search 配额为零的租户自动回退 Audit API 重查同一窗口(page 跨通道失效,重头吃窗)。
+func (c *RealClient) ListAuditEvents(ctx context.Context, cred Credentials, region string, start, end time.Time, page string) (AuditEventsResult, error) {
+	f := c.newAuditFetchers(cred, region)
+	res, err := listAuditWindow(ctx, f.search, AuditCursor{Start: start, End: end, Page: page})
+	if err != nil && isSearchQuotaZero(err) {
+		res, err = listAuditWindow(ctx, f.audit, AuditCursor{Start: start, End: end})
+	}
+	return res, err
+}
+
+// listAuditWindow 用给定取页函数吃一个固定时间窗,最多 maxAuditPages 页;
+// 页预算耗尽即截断,NextPage 携带未消费的窗内游标。
+func listAuditWindow(ctx context.Context, fetch auditPageFetch, cur AuditCursor) (AuditEventsResult, error) {
+	result := AuditEventsResult{Items: []AuditEvent{}}
+	for i := 0; i < maxAuditPages; i++ {
+		items, next, err := fetch(ctx, cur)
+		if err != nil {
+			return AuditEventsResult{}, err
+		}
+		result.Items = appendKeptAuditEvents(result.Items, items)
+		if next == "" {
+			sortAuditEvents(result.Items)
+			return result, nil
+		}
+		cur.Page = next
+	}
+	result.Truncated = true
+	result.NextPage = cur.Page
+	sortAuditEvents(result.Items)
+	return result, nil
+}
+
+// auditPageFetch 拉取游标位置的一页已映射事件,返回窗内下一页游标。
+type auditPageFetch func(ctx context.Context, cur AuditCursor) ([]AuditEvent, string, error)
+
+// auditFetchers 汇集两条数据通道:search 为 Logging Search 倒序主路,
+// audit 为 Search 配额为零租户的 Audit API 回退路。
+type auditFetchers struct {
+	search auditPageFetch
+	audit  auditPageFetch
+}
+
+// newAuditFetchers 构造两条通道的取页闭包;客户端惰性初始化,
+// 各模式的续查不会白建用不到的客户端。
+func (c *RealClient) newAuditFetchers(cred Credentials, region string) auditFetchers {
+	return auditFetchers{search: c.searchFetcher(cred, region), audit: c.auditAPIFetcher(cred, region)}
+}
+
+// searchFetcher 构造 Logging Search 通道的取页闭包。
+func (c *RealClient) searchFetcher(cred Credentials, region string) auditPageFetch {
+	var sc *loggingsearch.LogSearchClient
+	return func(ctx context.Context, cur AuditCursor) ([]AuditEvent, string, error) {
+		if sc == nil {
+			cli, err := c.auditSearchClient(cred, region)
+			if err != nil {
+				return nil, "", err
+			}
+			sc = &cli
+		}
+		return searchAuditPage(ctx, *sc, cred.TenancyOCID, cur)
+	}
+}
+
+// auditAPIFetcher 构造 Audit API 回退通道的取页闭包。
+func (c *RealClient) auditAPIFetcher(cred Credentials, region string) auditPageFetch {
+	var ac *audit.AuditClient
+	return func(ctx context.Context, cur AuditCursor) ([]AuditEvent, string, error) {
+		if ac == nil {
+			cli, err := c.auditClient(cred, region)
+			if err != nil {
+				return nil, "", err
+			}
+			ac = &cli
+		}
+		return listAuditPage(ctx, *ac, cred.TenancyOCID, cur)
+	}
+}
+
+// isSearchQuotaZero 识别「租户 Logging Search 配额为零」的失败:此类租户该
+// 服务永久不可用(maxQueriesPerMinute/maxConcurrentQueries 均为 0),应回退
+// Audit API;普通限流(配额非零)不回退,避免数据通道来回切换。
+func isSearchQuotaZero(err error) bool {
+	if err == nil {
+		return false
+	}
+	msg := strings.ToLower(strings.ReplaceAll(err.Error(), " ", ""))
+	return strings.Contains(msg, "ratelimitexceeded") && strings.Contains(msg, "maxqueriesperminute:0,")
+}
+
+// appendKeptAuditEvents 过滤噪声后追加一页已映射事件;窗口式与批式查询共用。
+func appendKeptAuditEvents(dst []AuditEvent, items []AuditEvent) []AuditEvent {
+	for _, ev := range items {
+		if keepAuditEvent(ev) {
+			dst = append(dst, ev)
+		}
+	}
+	return dst
+}
+
+// ---- 批式懒加载查询:分窗回溯 + 游标续查 ----
+
+// 批式查询参数:单批翻页预算沿用 maxAuditPages;首窗 24h,连续空窗倍增
+// 加速跨越闲置期,上限 14 天(Logging Search 单次查询时间窗硬限);
+// 回溯下限为审计事件保留期 365 天。
+const (
+	auditWindowHours    = 24
+	auditWindowMaxHours = 336
+	auditRetentionDays  = 365
+)
+
+// auditModeFallback 标记游标处于 Audit API 回退模式:部分租户的
+// Logging Search 服务配额为零(maxQueriesPerMinute: 0),永久不可用。
+const auditModeFallback = "a"
+
+// auditFallbackWindowHours 是回退模式的基准窗宽:Audit API 窗口内固定按
+// 处理时间正序且无排序参数,只能小窗回溯 + 前端全局重排保住从新到旧的体验。
+const auditFallbackWindowHours = 1
+
+// AuditCursor 是批式查询的续查位置:当前时间窗、窗内翻页游标、当前窗宽
+// (小时,空窗倍增的记忆)、检索关键字(随游标续查,保证跨批过滤一致)
+// 与数据通道模式(空为 Search 主路,"a" 为 Audit API 回退,续查沿用不再试错)。
+// 序列化为不透明 cursor 由 service 层负责。
+type AuditCursor struct {
+	Start       time.Time `json:"s"`
+	End         time.Time `json:"e"`
+	Page        string    `json:"p,omitempty"`
+	WindowHours int       `json:"w"`
+	Q           string    `json:"q,omitempty"`
+	M           string    `json:"m,omitempty"`
+}
+
+// toFallback 把游标切到 Audit API 回退模式:Search 页游标跨通道失效须清空;
+// 首窗收窄到基准窗宽,避免大窗正序分页又回到「首批全是窗口内最旧事件」的老问题。
+func (cur AuditCursor) toFallback() AuditCursor {
+	cur.M = auditModeFallback
+	cur.Page = ""
+	cur.WindowHours = auditFallbackWindowHours
+	if cur.End.Sub(cur.Start) > auditFallbackWindowHours*time.Hour {
+		cur.Start = cur.End.Add(-auditFallbackWindowHours * time.Hour)
+	}
+	return cur
+}
+
+// NewAuditCursor 构造首查游标:自 now 起回溯第一个 24h 窗。
+func NewAuditCursor(now time.Time) AuditCursor {
+	end := now.UTC().Truncate(time.Minute)
+	return AuditCursor{Start: end.Add(-auditWindowHours * time.Hour), End: end, WindowHours: auditWindowHours}
+}
+
+// advance 推进到紧邻更早的窗;empty 表示刚结束的窗无保留事件,窗宽倍增,
+// 否则重置为该模式基准窗宽。done 为 true 表示已越过保留期尽头。
+func (cur AuditCursor) advance(now time.Time, empty bool) (AuditCursor, bool) {
+	base := auditWindowHours
+	if cur.M == auditModeFallback {
+		base = auditFallbackWindowHours
+	}
+	w := cur.WindowHours
+	if w <= 0 {
+		w = base
+	}
+	if empty {
+		if w *= 2; w > auditWindowMaxHours {
+			w = auditWindowMaxHours
+		}
+	} else {
+		w = base
+	}
+	end := cur.Start
+	if end.Before(now.UTC().AddDate(0, 0, -auditRetentionDays)) {
+		return cur, true
+	}
+	return AuditCursor{Start: end.Add(-time.Duration(w) * time.Hour), End: end, WindowHours: w, Q: cur.Q, M: cur.M}, false
+}
+
+// AuditBatchResult 是一批懒加载结果;Cursor 为 nil 且 Exhausted 为 true
+// 表示已回溯到保留期尽头,无更早数据。
+type AuditBatchResult struct {
+	Items     []AuditEvent
+	Cursor    *AuditCursor
+	Exhausted bool
+}
+
+// ListAuditEventsBatch 实现 Client:从 cur 位置向更早方向收集约 limit 条
+// 保留事件;单批受页预算与时间预算双重约束,不足额也返回,由前端按需续查。
+// 倒序返回下,窗口不重叠 + 窗内游标续翻保证跨批不重不漏。
+func (c *RealClient) ListAuditEventsBatch(ctx context.Context, cred Credentials, region string, cur AuditCursor, limit int) (AuditBatchResult, error) {
+	return listAuditBatch(ctx, c.newAuditFetchers(cred, region), cur, limit)
+}
+
+// listAuditBatch 是批式回溯的通道无关内核,取页函数注入便于测试。
+func listAuditBatch(ctx context.Context, f auditFetchers, cur AuditCursor, limit int) (AuditBatchResult, error) {
+	res := AuditBatchResult{Items: []AuditEvent{}}
+	windowHasKept := false
+	deadline := time.Now().Add(auditBatchTimeBudget)
+	for budget := maxAuditPages; budget > 0 && len(res.Items) < limit && time.Now().Before(deadline); budget-- {
+		items, next, nextCur, err := fetchAuditPage(ctx, f, cur)
+		if err != nil {
+			return AuditBatchResult{}, err
+		}
+		cur = nextCur
+		before := len(res.Items)
+		res.Items = appendKeptAuditEvents(res.Items, filterAuditTerm(items, cur))
+		windowHasKept = windowHasKept || len(res.Items) > before
+		if next != "" {
+			cur.Page = next
+			continue
+		}
+		adv, done := cur.advance(time.Now(), !windowHasKept)
+		if done {
+			res.Exhausted = true
+			sortAuditEvents(res.Items)
+			return res, nil
+		}
+		cur, windowHasKept = adv, false
+	}
+	sortAuditEvents(res.Items)
+	res.Cursor = &cur
+	return res, nil
+}
+
+// fetchAuditPage 按游标模式取一页;Search 主路报「配额为零」时切到回退游标
+// 并立即用 Audit API 重试,后续批次凭游标模式直达回退通道不再试错。
+func fetchAuditPage(ctx context.Context, f auditFetchers, cur AuditCursor) ([]AuditEvent, string, AuditCursor, error) {
+	if cur.M == auditModeFallback {
+		items, next, err := f.audit(ctx, cur)
+		return items, next, cur, err
+	}
+	items, next, err := f.search(ctx, cur)
+	if err != nil && isSearchQuotaZero(err) {
+		cur = cur.toFallback()
+		items, next, err = f.audit(ctx, cur)
+	}
+	return items, next, cur, err
+}
+
+// filterAuditTerm 关键字精筛:只认列表可见字段(matchesAuditTerm),两条通道
+// 语义一致。Search 主路的 logContent 全文条件会命中隐藏认证元数据(如
+// opc-principal 头里的 ttype:login),只作粗筛减少翻页,不作为最终判定。
+func filterAuditTerm(items []AuditEvent, cur AuditCursor) []AuditEvent {
+	if cur.Q == "" {
+		return items
+	}
+	out := items[:0]
+	for _, ev := range items {
+		if matchesAuditTerm(ev, cur.Q) {
+			out = append(out, ev)
+		}
+	}
+	return out
+}
+
+// matchesAuditTerm 判断事件是否命中关键字:不区分大小写的包含匹配,
+// * 作为通配分段、各段都出现即命中,近似 Search 通道的 logContent 语义。
+func matchesAuditTerm(ev AuditEvent, q string) bool {
+	hay := strings.ToLower(strings.Join([]string{
+		ev.EventName, ev.Source, ev.ResourceName, ev.CompartmentName,
+		ev.PrincipalName, ev.IPAddress, ev.Status, ev.RequestAction, ev.RequestPath,
+	}, "\n"))
+	for _, part := range strings.Split(strings.ToLower(q), "*") {
+		if part != "" && !strings.Contains(hay, part) {
+			return false
+		}
+	}
+	return true
+}
+
+// auditClient 构造区域化的 Audit API 客户端(回退通道)。
 func (c *RealClient) auditClient(cred Credentials, region string) (audit.AuditClient, error) {
 	ac, err := audit.NewAuditClientWithConfigurationProvider(provider(cred))
 	if err != nil {
@@ -55,153 +383,10 @@ func (c *RealClient) auditClient(cred Credentials, region string) (audit.AuditCl
 	return ac, nil
 }
 
-// ListAuditEvents 实现 Client:实时查询租户根 compartment 在 [start, end) 内的
+// listAuditPage 拉取窗口内一页 Audit API 原始事件并压平;该 API 窗口内固定
-// 审计事件,最多翻 maxAuditPages 页,结果按发生时间倒序;纯读不落库。
+// 正序且只接受分钟粒度(起止秒与毫秒必须为 0)。Raw 为 SDK 事件原文,
-// page 非空时从该游标断点续翻(必须配同一时间窗);到限截断时回传 NextPage。
+// 与 Search 通道的 logContent 形态不同,详情弹窗均按任意 JSON 渲染。
-func (c *RealClient) ListAuditEvents(ctx context.Context, cred Credentials, region string, start, end time.Time, page string) (AuditEventsResult, error) {
+func listAuditPage(ctx context.Context, ac audit.AuditClient, tenancyOCID string, cur AuditCursor) ([]AuditEvent, string, error) {
-	ac, err := c.auditClient(cred, region)
-	if err != nil {
-		return AuditEventsResult{}, err
-	}
-	// Audit API 只接受分钟粒度：起止时间的秒与毫秒必须为 0
-	req := audit.ListEventsRequest{
-		CompartmentId: &cred.TenancyOCID,
-		StartTime:     &common.SDKTime{Time: start.UTC().Truncate(time.Minute)},
-		EndTime:       &common.SDKTime{Time: end.UTC().Truncate(time.Minute)},
-	}
-	if page != "" {
-		req.Page = &page
-	}
-	result := AuditEventsResult{Items: []AuditEvent{}}
-	for i := 0; i < maxAuditPages; i++ {
-		resp, err := ac.ListEvents(ctx, req)
-		if err != nil {
-			return AuditEventsResult{}, fmt.Errorf("list audit events: %w", err)
-		}
-		appendAuditEvents(&result, resp.Items)
-		if resp.OpcNextPage == nil {
-			sortAuditEvents(result.Items)
-			return result, nil
-		}
-		req.Page = resp.OpcNextPage
-	}
-	result.Truncated = true
-	result.NextPage = deref(req.Page)
-	sortAuditEvents(result.Items)
-	return result, nil
-}
-
-// appendAuditEvents 过滤噪声后追加一页事件;原始事件只对保留条目序列化。
-func appendAuditEvents(result *AuditEventsResult, items []audit.AuditEvent) {
-	result.Items = appendKeptAuditEvents(result.Items, items)
-}
-
-// appendKeptAuditEvents 是过滤追加的通用形态,窗口式与批式查询共用。
-func appendKeptAuditEvents(dst []AuditEvent, items []audit.AuditEvent) []AuditEvent {
-	for _, ev := range items {
-		out := toAuditEvent(ev)
-		if !keepAuditEvent(out) {
-			continue
-		}
-		if raw, mErr := json.Marshal(ev); mErr == nil {
-			out.Raw = raw
-		}
-		dst = append(dst, out)
-	}
-	return dst
-}
-
-// ---- 批式懒加载查询:分窗回溯 + 游标续查 ----
-
-// 批式查询参数:单批 OCI 翻页预算沿用 maxAuditPages;首窗 24h,
-// 连续空窗倍增(上限 30 天)加速跨越闲置期;回溯下限为事件保留期 365 天。
-const (
-	auditWindowHours    = 24
-	auditWindowMaxHours = 720
-	auditRetentionDays  = 365
-)
-
-// AuditCursor 是批式查询的续查位置:当前时间窗、窗内 OCI 翻页游标
-// 与当前窗宽(小时,空窗倍增的记忆)。序列化为不透明 cursor 由 service 层负责。
-type AuditCursor struct {
-	Start       time.Time `json:"s"`
-	End         time.Time `json:"e"`
-	Page        string    `json:"p,omitempty"`
-	WindowHours int       `json:"w"`
-}
-
-// NewAuditCursor 构造首查游标:自 now 起回溯第一个 24h 窗。
-func NewAuditCursor(now time.Time) AuditCursor {
-	end := now.UTC().Truncate(time.Minute)
-	return AuditCursor{Start: end.Add(-auditWindowHours * time.Hour), End: end, WindowHours: auditWindowHours}
-}
-
-// advance 推进到紧邻更早的窗;empty 表示刚结束的窗无保留事件,窗宽倍增,
-// 否则重置 24h。done 为 true 表示已越过保留期尽头。
-func (cur AuditCursor) advance(now time.Time, empty bool) (AuditCursor, bool) {
-	w := cur.WindowHours
-	if w <= 0 {
-		w = auditWindowHours
-	}
-	if empty {
-		if w *= 2; w > auditWindowMaxHours {
-			w = auditWindowMaxHours
-		}
-	} else {
-		w = auditWindowHours
-	}
-	end := cur.Start
-	if end.Before(now.UTC().AddDate(0, 0, -auditRetentionDays)) {
-		return cur, true
-	}
-	return AuditCursor{Start: end.Add(-time.Duration(w) * time.Hour), End: end, WindowHours: w}, false
-}
-
-// AuditBatchResult 是一批懒加载结果;Cursor 为 nil 且 Exhausted 为 true
-// 表示已回溯到保留期尽头,无更早数据。
-type AuditBatchResult struct {
-	Items     []AuditEvent
-	Cursor    *AuditCursor
-	Exhausted bool
-}
-
-// ListAuditEventsBatch 实现 Client:从 cur 位置向更早方向收集约 limit 条
-// 保留事件;单批最多消费 maxAuditPages 页 OCI 调用,不足额也按预算返回,
-// 由前端按需续查。窗口不重叠 + 窗内游标续翻保证跨批不重不漏。
-func (c *RealClient) ListAuditEventsBatch(ctx context.Context, cred Credentials, region string, cur AuditCursor, limit int) (AuditBatchResult, error) {
-	ac, err := c.auditClient(cred, region)
-	if err != nil {
-		return AuditBatchResult{}, err
-	}
-	res := AuditBatchResult{Items: []AuditEvent{}}
-	windowHasKept := false
-	for budget := maxAuditPages; budget > 0 && len(res.Items) < limit; budget-- {
-		items, next, err := listAuditPage(ctx, ac, cred.TenancyOCID, cur)
-		if err != nil {
-			return AuditBatchResult{}, err
-		}
-		before := len(res.Items)
-		res.Items = appendKeptAuditEvents(res.Items, items)
-		windowHasKept = windowHasKept || len(res.Items) > before
-		if next != "" {
-			cur.Page = next
-			continue
-		}
-		nextCur, done := cur.advance(time.Now(), !windowHasKept)
-		if done {
-			res.Exhausted = true
-			sortAuditEvents(res.Items)
-			return res, nil
-		}
-		cur, windowHasKept = nextCur, false
-	}
-	sortAuditEvents(res.Items)
-	res.Cursor = &cur
-	return res, nil
-}
-
-// listAuditPage 拉取当前游标位置的一页原始事件。
-func listAuditPage(ctx context.Context, ac audit.AuditClient, tenancyOCID string, cur AuditCursor) ([]audit.AuditEvent, string, error) {
 	req := audit.ListEventsRequest{
 		CompartmentId: &tenancyOCID,
 		StartTime:     &common.SDKTime{Time: cur.Start.UTC().Truncate(time.Minute)},
@@ -214,42 +399,18 @@ func listAuditPage(ctx context.Context, ac audit.AuditClient, tenancyOCID string
 	if err != nil {
 		return nil, "", fmt.Errorf("list audit events: %w", err)
 	}
-	return resp.Items, deref(resp.OpcNextPage), nil
+	items := make([]AuditEvent, 0, len(resp.Items))
+	for _, ev := range resp.Items {
+		out := toAuditEvent(ev)
+		if raw, mErr := json.Marshal(ev); mErr == nil {
+			out.Raw = raw
+		}
+		items = append(items, out)
+	}
+	return items, deref(resp.OpcNextPage), nil
 }
 
-// auditInternalCIDRs 是 OCI 服务内部互调的发起方网段(RFC1918 + CGNAT)。
+// toAuditEvent 把 Audit SDK 事件压平为列表 DTO;SDK 字段全为指针,逐层判 nil。
-var auditInternalCIDRs = func() []*net.IPNet {
-	out := make([]*net.IPNet, 0, 4)
-	for _, cidr := range []string{"10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "100.64.0.0/10"} {
-		_, block, _ := net.ParseCIDR(cidr)
-		out = append(out, block)
-	}
-	return out
-}()
-
-// keepAuditEvent 保留有展示价值的事件:Audit API 无服务端过滤参数(仅时间窗),
-// 在翻页循环内排除高频遥测噪声(SummarizeMetricsData)与内网地址发起的服务互调;
-// 无 IP 的事件(控制面内部)保留。
-func keepAuditEvent(ev AuditEvent) bool {
-	if ev.EventName == "SummarizeMetricsData" {
-		return false
-	}
-	if ev.IPAddress == "" {
-		return true
-	}
-	ip := net.ParseIP(ev.IPAddress)
-	if ip == nil {
-		return true
-	}
-	for _, block := range auditInternalCIDRs {
-		if block.Contains(ip) {
-			return false
-		}
-	}
-	return true
-}
-
-// toAuditEvent 把 SDK 审计事件压平为列表 DTO；SDK 字段全为指针，逐层判 nil。
 func toAuditEvent(ev audit.AuditEvent) AuditEvent {
 	out := AuditEvent{EventId: deref(ev.EventId), Source: deref(ev.Source)}
 	if ev.EventTime != nil {
@@ -275,6 +436,130 @@ func toAuditEvent(ev audit.AuditEvent) AuditEvent {
 	return out
 }
 
+// searchAuditPage 拉取游标窗口内按 datetime 倒序的一页审计事件(已映射未过滤)。
+func searchAuditPage(ctx context.Context, sc loggingsearch.LogSearchClient, tenancyOCID string, cur AuditCursor) ([]AuditEvent, string, error) {
+	req := loggingsearch.SearchLogsRequest{
+		SearchLogsDetails: loggingsearch.SearchLogsDetails{
+			TimeStart:   &common.SDKTime{Time: cur.Start.UTC().Truncate(time.Minute)},
+			TimeEnd:     &common.SDKTime{Time: cur.End.UTC().Truncate(time.Minute)},
+			SearchQuery: common.String(auditSearchQuery(tenancyOCID, cur.Q)),
+		},
+		Limit: common.Int(auditSearchPageLimit),
+	}
+	if cur.Page != "" {
+		req.Page = &cur.Page
+	}
+	resp, err := sc.SearchLogs(ctx, req)
+	if err != nil {
+		return nil, "", fmt.Errorf("search audit logs: %w", err)
+	}
+	items := make([]AuditEvent, 0, len(resp.Results))
+	for _, r := range resp.Results {
+		if ev, ok := toSearchAuditEvent(r); ok {
+			items = append(items, ev)
+		}
+	}
+	return items, deref(resp.OpcNextPage), nil
+}
+
+// auditInternalCIDRs 是 OCI 服务内部互调的发起方网段(RFC1918 + CGNAT)。
+var auditInternalCIDRs = func() []*net.IPNet {
+	out := make([]*net.IPNet, 0, 4)
+	for _, cidr := range []string{"10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "100.64.0.0/10"} {
+		_, block, _ := net.ParseCIDR(cidr)
+		out = append(out, block)
+	}
+	return out
+}()
+
+// keepAuditEvent 保留有展示价值的事件:SummarizeMetricsData 已在检索语句里
+// 先滤(此处兜底),内网地址发起的服务互调用 CIDR 判断(查询语言不便表达);
+// 无 IP 的事件(控制面内部)保留。
+func keepAuditEvent(ev AuditEvent) bool {
+	if ev.EventName == "SummarizeMetricsData" {
+		return false
+	}
+	if ev.IPAddress == "" {
+		return true
+	}
+	ip := net.ParseIP(ev.IPAddress)
+	if ip == nil {
+		return true
+	}
+	for _, block := range auditInternalCIDRs {
+		if block.Contains(ip) {
+			return false
+		}
+	}
+	return true
+}
+
+// searchAuditContent 是 _Audit 日志 logContent 的字段投影,只取列表展示所需;
+// identity / request / response 可能为 null,零值即缺省。
+type searchAuditContent struct {
+	ID     string     `json:"id"`
+	Time   *time.Time `json:"time"`
+	Source string     `json:"source"`
+	Data   struct {
+		EventName       string `json:"eventName"`
+		ResourceName    string `json:"resourceName"`
+		CompartmentName string `json:"compartmentName"`
+		Identity        struct {
+			PrincipalName string `json:"principalName"`
+			IPAddress     string `json:"ipAddress"`
+		} `json:"identity"`
+		Request struct {
+			Action string `json:"action"`
+			Path   string `json:"path"`
+		} `json:"request"`
+		Response struct {
+			Status string `json:"status"`
+		} `json:"response"`
+	} `json:"data"`
+}
+
+// toSearchAuditEvent 把日志搜索结果压平为列表 DTO;Raw 即 logContent 原文。
+// 结构不符的条目丢弃(返回 false),不因单条脏数据整页失败。
+func toSearchAuditEvent(r loggingsearch.SearchResult) (AuditEvent, bool) {
+	if r.Data == nil {
+		return AuditEvent{}, false
+	}
+	b, err := json.Marshal(r.Data)
+	if err != nil {
+		return AuditEvent{}, false
+	}
+	var hit struct {
+		LogContent json.RawMessage `json:"logContent"`
+	}
+	if err := json.Unmarshal(b, &hit); err != nil || len(hit.LogContent) == 0 {
+		return AuditEvent{}, false
+	}
+	var content searchAuditContent
+	if err := json.Unmarshal(hit.LogContent, &content); err != nil {
+		return AuditEvent{}, false
+	}
+	ev := searchContentToEvent(content)
+	ev.Raw = hit.LogContent
+	return ev, true
+}
+
+// searchContentToEvent 把投影字段填入列表 DTO;Raw 由调用方设置。
+func searchContentToEvent(c searchAuditContent) AuditEvent {
+	return AuditEvent{
+		EventId:         c.ID,
+		EventTime:       c.Time,
+		EventName:       c.Data.EventName,
+		Source:          c.Source,
+		ResourceName:    c.Data.ResourceName,
+		CompartmentName: c.Data.CompartmentName,
+		PrincipalName:   c.Data.Identity.PrincipalName,
+		IPAddress:       c.Data.Identity.IPAddress,
+		Status:          c.Data.Response.Status,
+		RequestAction:   c.Data.Request.Action,
+		RequestPath:     c.Data.Request.Path,
+	}
+}
+
 // sortAuditEvents 按发生时间倒序排列；服务端返回顺序不保证，nil 时间排最后。
 func sortAuditEvents(items []AuditEvent) {
 	sort.SliceStable(items, func(i, j int) bool {

internal/oci/audit_test.go

@@ -1,14 +1,262 @@
 package oci
 
 import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
 	"reflect"
+	"strings"
 	"testing"
 	"time"
 
 	"github.com/oracle/oci-go-sdk/v65/audit"
 	"github.com/oracle/oci-go-sdk/v65/common"
+	"github.com/oracle/oci-go-sdk/v65/loggingsearch"
 )
 
+// quotaZeroErr 复刻 Search 配额为零租户的真实报错(SDK 解析错误体失败后带原文)。
+var quotaZeroErr = errors.New(`search audit logs: Failed to parse json from response body due to: json: cannot unmarshal number into Go struct field servicefailure.code of type string. With response body { "code" : 500, "message" : "Rate limit exceeded for ocid: ocid1.tenancy..x, maxQueriesPerMinute: 0, maxConcurrentQueries: 0" }.`)
+
+func TestIsSearchQuotaZero(t *testing.T) {
+	cases := []struct {
+		name string
+		err  error
+		want bool
+	}{
+		{"配额为零真实报错", quotaZeroErr, true},
+		{"普通限流不回退", errors.New(`Rate limit exceeded for ocid: x, maxQueriesPerMinute: 60, maxConcurrentQueries: 2`), false},
+		{"其他错误", errors.New("service unavailable"), false},
+		{"nil", nil, false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := isSearchQuotaZero(tc.err); got != tc.want {
+				t.Fatalf("isSearchQuotaZero() = %v, want %v", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestListAuditBatchFallback(t *testing.T) {
+	et := time.Now().UTC().Add(-10 * time.Minute)
+	searchCalls, auditCalls := 0, 0
+	f := auditFetchers{
+		search: func(context.Context, AuditCursor) ([]AuditEvent, string, error) {
+			searchCalls++
+			return nil, "", quotaZeroErr
+		},
+		audit: func(_ context.Context, cur AuditCursor) ([]AuditEvent, string, error) {
+			auditCalls++
+			if cur.M != auditModeFallback || cur.Page != "" {
+				t.Fatalf("回退通道应携带模式标记且清空页游标, got %+v", cur)
+			}
+			ev := AuditEvent{EventId: fmt.Sprint(auditCalls), EventName: "GetInstance", EventTime: &et}
+			return []AuditEvent{ev}, "", nil
+		},
+	}
+	res, err := listAuditBatch(context.Background(), f, NewAuditCursor(time.Now()), 3)
+	if err != nil {
+		t.Fatalf("配额为零应回退成功, got %v", err)
+	}
+	if searchCalls != 1 {
+		t.Fatalf("Search 只应试错一次, got %d", searchCalls)
+	}
+	if len(res.Items) < 3 || auditCalls < 3 {
+		t.Fatalf("回退后应继续凑批, items=%d auditCalls=%d", len(res.Items), auditCalls)
+	}
+	if res.Cursor == nil || res.Cursor.M != auditModeFallback || res.Cursor.WindowHours != auditFallbackWindowHours {
+		t.Fatalf("续查游标应保持回退模式与基准窗宽, got %+v", res.Cursor)
+	}
+}
+
+func TestListAuditBatchFallbackCursorSkipsSearch(t *testing.T) {
+	et := time.Now().UTC().Add(-10 * time.Minute)
+	f := auditFetchers{
+		search: func(context.Context, AuditCursor) ([]AuditEvent, string, error) {
+			t.Fatal("回退模式游标不应再调用 Search 通道")
+			return nil, "", nil
+		},
+		audit: func(context.Context, AuditCursor) ([]AuditEvent, string, error) {
+			return []AuditEvent{{EventId: "e1", EventName: "GetVcn", EventTime: &et}}, "", nil
+		},
+	}
+	cur := NewAuditCursor(time.Now()).toFallback()
+	if _, err := listAuditBatch(context.Background(), f, cur, 1); err != nil {
+		t.Fatalf("回退模式续查失败: %v", err)
+	}
+}
+
+func TestListAuditBatchSearchErrorNoFallback(t *testing.T) {
+	f := auditFetchers{
+		search: func(context.Context, AuditCursor) ([]AuditEvent, string, error) {
+			return nil, "", errors.New("search audit logs: timeout")
+		},
+		audit: func(context.Context, AuditCursor) ([]AuditEvent, string, error) {
+			t.Fatal("普通错误不应触发回退")
+			return nil, "", nil
+		},
+	}
+	if _, err := listAuditBatch(context.Background(), f, NewAuditCursor(time.Now()), 1); err == nil {
+		t.Fatal("普通错误应原样上抛")
+	}
+}
+
+func TestFilterAuditTerm(t *testing.T) {
+	login := AuditEvent{EventId: "e1", EventName: "InteractiveLogin"}
+	noise := AuditEvent{EventId: "e2", EventName: "ListRecommendations"}
+	items := []AuditEvent{login, noise}
+	cases := []struct {
+		name string
+		cur  AuditCursor
+		want int
+	}{
+		{"无关键字原样放行", AuditCursor{}, 2},
+		{"Search 主路也精筛可见字段", AuditCursor{Q: "login"}, 1},
+		{"回退模式精筛", AuditCursor{Q: "login", M: auditModeFallback}, 1},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := filterAuditTerm(append([]AuditEvent{}, items...), tc.cur); len(got) != tc.want {
+				t.Fatalf("filterAuditTerm() 保留 %d 条, want %d", len(got), tc.want)
+			}
+		})
+	}
+}
+
+func TestListAuditBatchSearchTermPrecision(t *testing.T) {
+	et := time.Now().UTC().Add(-10 * time.Minute)
+	// 模拟 Search 主路粗筛后仍混入的隐藏元数据误命中(如 ttype:login)
+	f := auditFetchers{
+		search: func(_ context.Context, cur AuditCursor) ([]AuditEvent, string, error) {
+			return []AuditEvent{
+				{EventId: "hit", EventName: "InteractiveLogin", EventTime: &et},
+				{EventId: "noise1", EventName: "ListRecommendations", EventTime: &et},
+				{EventId: "noise2", EventName: "SearchLogs", EventTime: &et},
+			}, "", nil
+		},
+		audit: func(context.Context, AuditCursor) ([]AuditEvent, string, error) {
+			t.Fatal("Search 正常时不应走回退")
+			return nil, "", nil
+		},
+	}
+	cur := NewAuditCursor(time.Now())
+	cur.Q = "login"
+	res, err := listAuditBatch(context.Background(), f, cur, 1)
+	if err != nil {
+		t.Fatalf("listAuditBatch() err = %v", err)
+	}
+	if len(res.Items) != 1 || res.Items[0].EventId != "hit" {
+		t.Fatalf("应只保留可见字段命中的事件, got %+v", res.Items)
+	}
+}
+
+func TestMatchesAuditTerm(t *testing.T) {
+	ev := AuditEvent{EventName: "ListVnicAttachments", ResourceName: "web-1", PrincipalName: "Vivien", IPAddress: "1.2.3.4"}
+	cases := []struct {
+		name string
+		q    string
+		want bool
+	}{
+		{"不区分大小写", "listvnic", true},
+		{"通配分段都出现", "List*Attachments", true},
+		{"资源名命中", "WEB-1", true},
+		{"未命中", "TerminateInstance", false},
+		{"通配缺段不命中", "List*Volume", false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := matchesAuditTerm(ev, tc.q); got != tc.want {
+				t.Fatalf("matchesAuditTerm(%q) = %v, want %v", tc.q, got, tc.want)
+			}
+		})
+	}
+}
+
+// searchResultFromJSON 把 JSON 文本构造成 SearchLogs 单条结果(Data 为 interface{})。
+func searchResultFromJSON(t *testing.T, s string) loggingsearch.SearchResult {
+	t.Helper()
+	var v interface{}
+	if err := json.Unmarshal([]byte(s), &v); err != nil {
+		t.Fatalf("fixture 不是合法 JSON: %v", err)
+	}
+	return loggingsearch.SearchResult{Data: &v}
+}
+
+func TestToSearchAuditEvent(t *testing.T) {
+	eventTime := time.Date(2026, 7, 6, 10, 30, 0, 0, time.UTC)
+	tests := []struct {
+		name   string
+		data   string
+		wantOK bool
+		want   AuditEvent
+	}{
+		{
+			name: "全字段齐全",
+			data: `{"datetime":1783074600000,"logContent":{
+				"id":"evt-abc","time":"2026-07-06T10:30:00Z","source":"ComputeApi",
+				"data":{"eventName":"TerminateInstance","resourceName":"web-1","compartmentName":"prod",
+					"identity":{"principalName":"api-admin","ipAddress":"1.2.3.4"},
+					"request":{"action":"DELETE","path":"/20160918/instances/ocid1..."},
+					"response":{"status":"204"}}}}`,
+			wantOK: true,
+			want: AuditEvent{
+				EventId:         "evt-abc",
+				EventTime:       &eventTime,
+				EventName:       "TerminateInstance",
+				Source:          "ComputeApi",
+				ResourceName:    "web-1",
+				CompartmentName: "prod",
+				PrincipalName:   "api-admin",
+				IPAddress:       "1.2.3.4",
+				Status:          "204",
+				RequestAction:   "DELETE",
+				RequestPath:     "/20160918/instances/ocid1...",
+			},
+		},
+		{
+			name: "identity/request/response 为 null 时只保留信封字段",
+			data: `{"logContent":{"id":"evt-x","time":"2026-07-06T10:30:00Z","source":"VcnApi",
+				"data":{"eventName":"GetVcn","identity":null,"request":null,"response":null}}}`,
+			wantOK: true,
+			want:   AuditEvent{EventId: "evt-x", EventTime: &eventTime, Source: "VcnApi", EventName: "GetVcn"},
+		},
+		{
+			name:   "缺 logContent 丢弃",
+			data:   `{"datetime":1783074600000}`,
+			wantOK: false,
+		},
+		{
+			name:   "logContent 结构不符丢弃",
+			data:   `{"logContent":"plain-text"}`,
+			wantOK: false,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, ok := toSearchAuditEvent(searchResultFromJSON(t, tt.data))
+			if ok != tt.wantOK {
+				t.Fatalf("ok = %v, want %v", ok, tt.wantOK)
+			}
+			if !ok {
+				return
+			}
+			if len(got.Raw) == 0 {
+				t.Fatalf("Raw 应携带 logContent 原文")
+			}
+			if !auditEventEqual(got, tt.want) {
+				t.Errorf("toSearchAuditEvent() = %+v, want %+v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestToSearchAuditEventNilData(t *testing.T) {
+	if _, ok := toSearchAuditEvent(loggingsearch.SearchResult{}); ok {
+		t.Fatal("Data 为 nil 应丢弃")
+	}
+}
+
 func TestToAuditEvent(t *testing.T) {
 	eventTime := time.Date(2026, 7, 6, 10, 30, 0, 0, time.UTC)
 	tests := []struct {
@@ -38,44 +286,23 @@ func TestToAuditEvent(t *testing.T) {
 				},
 			},
 			want: AuditEvent{
-				EventId:         "evt-abc",
+				EventId: "evt-abc", EventTime: &eventTime, EventName: "TerminateInstance",
-				EventTime:       &eventTime,
+				Source: "ComputeApi", ResourceName: "web-1", CompartmentName: "prod",
-				EventName:       "TerminateInstance",
+				PrincipalName: "api-admin", IPAddress: "1.2.3.4", Status: "204",
-				Source:          "ComputeApi",
+				RequestAction: "DELETE", RequestPath: "/20160918/instances/ocid1...",
-				ResourceName:    "web-1",
-				CompartmentName: "prod",
-				PrincipalName:   "api-admin",
-				IPAddress:       "1.2.3.4",
-				Status:          "204",
-				RequestAction:   "DELETE",
-				RequestPath:     "/20160918/instances/ocid1...",
 			},
 		},
-		{
-			name: "Data 为 nil 时只保留信封字段",
-			ev: audit.AuditEvent{
-				Source:    common.String("VcnApi"),
-				EventTime: &common.SDKTime{Time: eventTime},
-			},
-			want: AuditEvent{EventTime: &eventTime, Source: "VcnApi"},
-		},
 		{
 			name: "嵌套局部 nil 各自安全跳过",
 			ev: audit.AuditEvent{
 				Data: &audit.Data{
 					EventName: common.String("GetInstance"),
-					Identity:  nil,
 					Request:   &audit.Request{Path: common.String("/instances")},
-					Response:  nil,
 				},
 			},
 			want: AuditEvent{EventName: "GetInstance", RequestPath: "/instances"},
 		},
-		{
+		{name: "空事件全部零值", ev: audit.AuditEvent{}, want: AuditEvent{}},
-			name: "空事件全部零值",
-			ev:   audit.AuditEvent{},
-			want: AuditEvent{},
-		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -86,6 +313,37 @@ func TestToAuditEvent(t *testing.T) {
 	}
 }
 
+func TestAuditSearchQuery(t *testing.T) {
+	const prefix = `search "ocid1.tenancy.oc1..aaa/_Audit" | where data.eventName != 'SummarizeMetricsData'`
+	cases := []struct {
+		name string
+		term string
+		want string
+	}{
+		{"无关键字", "", prefix + ` | sort by datetime desc`},
+		{"带关键字追加全文匹配", "TerminateInstance", prefix + ` and logContent = '*TerminateInstance*' | sort by datetime desc`},
+		{"引号与反斜杠被消毒", `O'Brien\"x`, prefix + ` and logContent = '*OBrienx*' | sort by datetime desc`},
+		{"纯引号消毒后为空不追加", `'"`, prefix + ` | sort by datetime desc`},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := auditSearchQuery("ocid1.tenancy.oc1..aaa", tc.term); got != tc.want {
+				t.Fatalf("auditSearchQuery() = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestSanitizeAuditTerm(t *testing.T) {
+	if got := SanitizeAuditTerm("  Get*Instance\t "); got != "Get*Instance" {
+		t.Fatalf("应保留 * 并去除首尾空白与控制字符, got %q", got)
+	}
+	long := strings.Repeat("a", 300)
+	if got := SanitizeAuditTerm(long); len(got) != auditTermMaxLen {
+		t.Fatalf("超长应截断到 %d, got %d", auditTermMaxLen, len(got))
+	}
+}
+
 // auditEventEqual 比较两个 DTO：EventTime 按值比较,Raw 不参与,其余反射比较。
 func auditEventEqual(a, b AuditEvent) bool {
 	if (a.EventTime == nil) != (b.EventTime == nil) {
@@ -149,6 +407,7 @@ func TestAuditCursorAdvance(t *testing.T) {
 		Start:       now.Add(-24 * time.Hour),
 		End:         now,
 		WindowHours: 24,
+		Q:           "kw",
 	}
 	cases := []struct {
 		name      string
@@ -159,8 +418,10 @@ func TestAuditCursorAdvance(t *testing.T) {
 	}{
 		{"有事件重置 24h 窗", AuditCursor{Start: base.Start, End: base.End, WindowHours: 96}, false, 24, false},
 		{"空窗倍增", base, true, 48, false},
-		{"倍增封顶 720h", AuditCursor{Start: base.Start, End: base.End, WindowHours: 512}, true, 720, false},
+		{"倍增封顶 336h(14 天查询窗硬限)", AuditCursor{Start: base.Start, End: base.End, WindowHours: 256}, true, 336, false},
 		{"窗宽缺省按 24h 起算", AuditCursor{Start: base.Start, End: base.End}, true, 48, false},
+		{"回退模式有事件重置 1h 基准窗", AuditCursor{Start: base.Start, End: base.End, WindowHours: 8, M: auditModeFallback}, false, 1, false},
+		{"回退模式空窗照常倍增", AuditCursor{Start: base.Start, End: base.End, WindowHours: 1, M: auditModeFallback}, true, 2, false},
 		{"越过保留期即尽头", AuditCursor{Start: now.AddDate(0, 0, -366), End: now.AddDate(0, 0, -365), WindowHours: 24}, false, 0, true},
 	}
 	for _, tc := range cases {
@@ -184,6 +445,12 @@ func TestAuditCursorAdvance(t *testing.T) {
 			if next.Page != "" {
 				t.Fatalf("新窗应清空窗内游标, got %q", next.Page)
 			}
+			if next.Q != tc.cur.Q {
+				t.Fatalf("新窗应继承检索关键字, got %q want %q", next.Q, tc.cur.Q)
+			}
+			if next.M != tc.cur.M {
+				t.Fatalf("新窗应继承通道模式, got %q want %q", next.M, tc.cur.M)
+			}
 		})
 	}
 }

internal/oci/cached.go

@@ -32,8 +32,10 @@ func NewCachedClient(inner Client) *CachedClient {
 }
 
 // ckey 组缓存键;租户 OCID 在最前,写失效按前缀一锅端。
+// compartment 必须参与键值:列表查询按 EffectiveCompartment 过滤,
+// 同租户切换区间时若共用键会串到上一个区间的缓存结果。
 func ckey(cred Credentials, parts ...string) string {
-	return cred.TenancyOCID + "|" + strings.Join(parts, "|")
+	return cred.TenancyOCID + "|" + cred.CompartmentID + "|" + strings.Join(parts, "|")
 }
 
 // bust 写操作成功后失效该租户全部读缓存。

internal/oci/cached_test.go

@@ -49,6 +49,13 @@ func TestCachedClientHitAndIsolation(t *testing.T) {
 	if inner.instCalls != 3 {
 		t.Errorf("跨租户/区域回源 %d 次, want 3", inner.instCalls)
 	}
+	// 同租户不同 compartment 各自回源,不得共用缓存
+	inCompartment := testCred("t1")
+	inCompartment.CompartmentID = "ocid1.compartment.a"
+	_, _ = c.ListInstances(ctx, inCompartment, "r1")
+	if inner.instCalls != 4 {
+		t.Errorf("跨 compartment 回源 %d 次, want 4", inner.instCalls)
+	}
 }
 
 func TestCachedClientWriteBusts(t *testing.T) {

internal/oci/client.go

@@ -102,10 +102,18 @@ type Client interface {
 	ListGenAiModels(ctx context.Context, cred Credentials, region string) ([]GenAiModel, error)
 	GenAiProbeChat(ctx context.Context, cred Credentials, region, modelOcid, modelName string) (int, error)
 	GenAiEmbed(ctx context.Context, cred Credentials, region, modelOcid string, inputs []string, dimensions *int) ([][]float32, *aiwire.Usage, error)
-	// GenAiCompatResponses 直通 OpenAI Responses 请求体到 /actions/v1/responses(xAI 服务端工具通路)。
+	// GenAiCompatResponses 直通 OpenAI Responses 请求体到 /actions/v1/responses(xAI 服务端工具通路);
-	GenAiCompatResponses(ctx context.Context, cred Credentials, region string, body []byte) ([]byte, error)
+	// wait 是上游无响应预算(整请求总超时),multi-agent/搜索类模型需远超 SDK 默认 60s。
-	// GenAiCompatResponsesStream 流式直通 /actions/v1/responses,建立成功返回 SSE body。
+	GenAiCompatResponses(ctx context.Context, cred Credentials, region string, body []byte, wait time.Duration) ([]byte, error)
-	GenAiCompatResponsesStream(ctx context.Context, cred Credentials, region string, body []byte) (io.ReadCloser, error)
+	// GenAiCompatResponsesStream 流式直通 /actions/v1/responses,建立成功返回 SSE body;
+	// wait 仅约束等待响应头阶段,建立后的流生命周期由 ctx 决定。
+	GenAiCompatResponsesStream(ctx context.Context, cred Credentials, region string, body []byte, wait time.Duration) (io.ReadCloser, error)
+	// GenAiCompatSpeech 直通 OpenAI Audio Speech 请求体到 /openai/v1/audio/speech,返回音频与 Content-Type。
+	GenAiCompatSpeech(ctx context.Context, cred Credentials, region string, body []byte) ([]byte, string, error)
+	// GenAiRerank 文档重排,返回按相关度排序的下标与得分。
+	GenAiRerank(ctx context.Context, cred Credentials, region, modelOcid, query string, documents []string, topN *int) ([]RerankRank, error)
+	// GenAiApplyGuardrails 对单条文本执行内容审核 / PII / 提示注入检测。
+	GenAiApplyGuardrails(ctx context.Context, cred Credentials, region, text string) (*GuardrailsOutcome, error)
 	// 控制台连接：创建（VNC/串口连接串）、列出、删除。
 	CreateConsoleConnection(ctx context.Context, cred Credentials, region, instanceID, sshPublicKey string) (ConsoleConnection, error)
 	ListConsoleConnections(ctx context.Context, cred Credentials, region, instanceID string) ([]ConsoleConnection, error)

internal/oci/genai.go

@@ -131,6 +131,11 @@ func modelCapability(m generativeai.ModelSummary) string {
 			return "CHAT"
 		case generativeai.ModelCapabilityTextEmbeddings:
 			capability = "EMBEDDING"
+		case generativeai.ModelCapabilityTextRerank:
+			capability = "RERANK"
+		case generativeai.ModelCapabilityEnum("TEXT_TO_AUDIO"):
+			// SDK v65.120 尚无该枚举常量,按原始字符串匹配(xai.grok-tts)
+			capability = "TTS"
 		}
 	}
 	return capability
@@ -144,15 +149,17 @@ func capStrings(caps []generativeai.ModelCapabilityEnum) []string {
 	return out
 }
 
-// GenAiProbeChat 实现 Client:经 OpenAI 兼容面(直通同链路)发一次极小请求探测渠道;配额探测专用的最小聊天(maxTokens=1),返回 HTTP 状态码;
+// GenAiProbeChat 实现 Client:经 OpenAI 兼容面(直通同链路)发一次极小请求探测渠道;
-// modelName 决定请求格式(cohere.* 走 COHERE)。
+// 配额探测专用的最小聊天,返回 HTTP 状态码。max_output_tokens 取 16:
+// openai.gpt-oss 系列要求 >=16,其余模型均兼容,成本差异可忽略。
 func (c *RealClient) GenAiProbeChat(ctx context.Context, cred Credentials, region, modelOcid, modelName string) (int, error) {
 	body, err := json.Marshal(map[string]any{"model": modelName, "input": "hi",
-		"max_output_tokens": 1, "store": false})
+		"max_output_tokens": 16, "store": false})
 	if err != nil {
 		return 0, err
 	}
-	if _, err = c.GenAiCompatResponses(ctx, cred, region, body); err == nil {
+	// 探测追求快速失败,沿用 SDK 默认量级的 60s 预算即可
+	if _, err = c.GenAiCompatResponses(ctx, cred, region, body, 60*time.Second); err == nil {
 		return http.StatusOK, nil
 	}
 	if status, ok := ServiceStatus(err); ok {

internal/oci/genai_guard.go

@@ -0,0 +1,127 @@
+package oci
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/oracle/oci-go-sdk/v65/common"
+	"github.com/oracle/oci-go-sdk/v65/generativeaiinference"
+)
+
+// RerankRank 是重排结果的一项:index 指向入参 documents 下标。
+type RerankRank struct {
+	Index int
+	Score float64
+}
+
+// GuardrailCategory 是内容审核分类得分(OVERALL / BLOCKLIST)。
+type GuardrailCategory struct {
+	Name  string
+	Score float64
+}
+
+// GuardrailPiiHit 是一处 PII 命中(片段原文与位置)。
+type GuardrailPiiHit struct {
+	Text   string
+	Label  string
+	Score  float64
+	Offset int
+	Length int
+}
+
+// GuardrailsOutcome 汇总 ApplyGuardrails 三能力结果。
+type GuardrailsOutcome struct {
+	Categories           []GuardrailCategory
+	Pii                  []GuardrailPiiHit
+	PromptInjectionScore *float64
+}
+
+// GenAiRerank 实现 Client:文档重排(on-demand serving),返回按相关度排序的下标与得分。
+func (c *RealClient) GenAiRerank(ctx context.Context, cred Credentials, region, modelOcid, query string, documents []string, topN *int) ([]RerankRank, error) {
+	ic, err := c.genAiInferenceClient(cred, region)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := ic.RerankText(ctx, generativeaiinference.RerankTextRequest{
+		RerankTextDetails: generativeaiinference.RerankTextDetails{
+			CompartmentId: &cred.TenancyOCID,
+			ServingMode:   generativeaiinference.OnDemandServingMode{ModelId: &modelOcid},
+			Input:         &query,
+			Documents:     documents,
+			TopN:          topN,
+		},
+	})
+	if err != nil {
+		return nil, fmt.Errorf("genai rerank: %w", err)
+	}
+	ranks := make([]RerankRank, 0, len(resp.DocumentRanks))
+	for _, r := range resp.DocumentRanks {
+		if r.Index == nil || r.RelevanceScore == nil {
+			continue
+		}
+		ranks = append(ranks, RerankRank{Index: *r.Index, Score: *r.RelevanceScore})
+	}
+	return ranks, nil
+}
+
+// GenAiApplyGuardrails 实现 Client:对单条文本执行内容审核 / PII / 提示注入三检测。
+func (c *RealClient) GenAiApplyGuardrails(ctx context.Context, cred Credentials, region, text string) (*GuardrailsOutcome, error) {
+	ic, err := c.genAiInferenceClient(cred, region)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := ic.ApplyGuardrails(ctx, generativeaiinference.ApplyGuardrailsRequest{
+		ApplyGuardrailsDetails: generativeaiinference.ApplyGuardrailsDetails{
+			CompartmentId: &cred.TenancyOCID,
+			Input:         generativeaiinference.GuardrailsTextInput{Content: common.String(text)},
+			GuardrailConfigs: &generativeaiinference.GuardrailConfigs{
+				ContentModerationConfig:                 &generativeaiinference.ContentModerationConfiguration{Categories: []string{"OVERALL"}},
+				PersonallyIdentifiableInformationConfig: &generativeaiinference.PersonallyIdentifiableInformationConfiguration{Types: []string{}},
+				PromptInjectionConfig:                   &generativeaiinference.PromptInjectionConfiguration{},
+			},
+		},
+	})
+	if err != nil {
+		return nil, fmt.Errorf("genai guardrails: %w", err)
+	}
+	return guardrailsOutcome(resp.Results), nil
+}
+
+// guardrailsOutcome 把 SDK 结果换算为 IR;空段置空切片,得分缺失跳过。
+func guardrailsOutcome(r *generativeaiinference.GuardrailsResults) *GuardrailsOutcome {
+	out := &GuardrailsOutcome{}
+	if r == nil {
+		return out
+	}
+	if r.ContentModeration != nil {
+		for _, cat := range r.ContentModeration.Categories {
+			if cat.Name == nil || cat.Score == nil {
+				continue
+			}
+			out.Categories = append(out.Categories, GuardrailCategory{Name: *cat.Name, Score: *cat.Score})
+		}
+	}
+	for _, hit := range r.PersonallyIdentifiableInformation {
+		h := GuardrailPiiHit{}
+		if hit.Text != nil {
+			h.Text = *hit.Text
+		}
+		if hit.Label != nil {
+			h.Label = *hit.Label
+		}
+		if hit.Score != nil {
+			h.Score = *hit.Score
+		}
+		if hit.Offset != nil {
+			h.Offset = *hit.Offset
+		}
+		if hit.Length != nil {
+			h.Length = *hit.Length
+		}
+		out.Pii = append(out.Pii, h)
+	}
+	if r.PromptInjection != nil && r.PromptInjection.Score != nil {
+		out.PromptInjectionScore = r.PromptInjection.Score
+	}
+	return out
+}

internal/oci/genai_responses.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"time"
 
 	"github.com/oracle/oci-go-sdk/v65/common"
 )
@@ -13,18 +14,19 @@ import (
 // compatResponsesLimit 限制直通响应体大小;web_search 输出含多段引用,给足余量。
 const compatResponsesLimit = int64(8 << 20)
 
-// GenAiCompatResponses 实现 Client:把 OpenAI Responses 请求体直通到 OCI
+// dispatcherWithTimeout 把 dispatcher 换成指定总超时的拷贝(保留 Transport,
-// `/20231130/actions/v1/responses`(IAM 签名)。该端点实测可执行 xAI 服务端工具
+// 代理链路不受影响);timeout=0 表示无总超时(流式读 body 不能有总时限)。
-// (web_search / x_search),但不在 Oracle 文档化工具白名单内,行为可能随服务
+// 非 *http.Client 的自定义 dispatcher 保持原样,维持既有超时行为。
-// 版本、模型或区域变化;调用方须自行校验并改写请求体(store/stream)。
+func dispatcherWithTimeout(d common.HTTPRequestDispatcher, timeout time.Duration) common.HTTPRequestDispatcher {
-func (c *RealClient) GenAiCompatResponses(ctx context.Context, cred Credentials, region string, body []byte) ([]byte, error) {
+	hc, ok := d.(*http.Client)
-	ic, err := c.genAiInferenceClient(cred, region)
+	if !ok {
-	if err != nil {
+		return d
-		return nil, err
 	}
-	client := ic.BaseClient
+	return &http.Client{Transport: hc.Transport, Timeout: timeout}
-	common.UpdateEndpointTemplateForOptions(&client)
+}
-	common.SetMissingTemplateParams(&client)
+
+// newCompatResponsesRequest 构造 /actions/v1/responses 直通请求。
+func newCompatResponsesRequest(ctx context.Context, cred Credentials, body []byte) (*http.Request, error) {
 	request, err := http.NewRequestWithContext(ctx, http.MethodPost, "/actions/v1/responses", bytes.NewReader(body))
 	if err != nil {
 		return nil, fmt.Errorf("build compat responses request: %w", err)
@@ -32,6 +34,27 @@ func (c *RealClient) GenAiCompatResponses(ctx context.Context, cred Credentials,
 	request.Header.Set("Content-Type", "application/json")
 	request.Header.Set("CompartmentId", cred.TenancyOCID)
 	request.Header.Set("opc-compartment-id", cred.TenancyOCID)
+	return request, nil
+}
+
+// GenAiCompatResponses 实现 Client:把 OpenAI Responses 请求体直通到 OCI
+// `/20231130/actions/v1/responses`(IAM 签名)。xAI 服务端工具(web_search /
+// x_search / code_interpreter)与 mcp 已被 Oracle 文档正式支持,工具参数与限制
+// 遵循 xAI 规格;调用方须自行校验并改写请求体(store/stream)。
+// wait 为整请求总超时:非流式上游要等全部生成完才回响应头,SDK 默认 60s 会掐断慢模型。
+func (c *RealClient) GenAiCompatResponses(ctx context.Context, cred Credentials, region string, body []byte, wait time.Duration) ([]byte, error) {
+	ic, err := c.genAiInferenceClient(cred, region)
+	if err != nil {
+		return nil, err
+	}
+	client := ic.BaseClient
+	common.UpdateEndpointTemplateForOptions(&client)
+	common.SetMissingTemplateParams(&client)
+	client.HTTPClient = dispatcherWithTimeout(client.HTTPClient, wait)
+	request, err := newCompatResponsesRequest(ctx, cred, body)
+	if err != nil {
+		return nil, err
+	}
 	response, err := client.Call(ctx, request)
 	if err != nil {
 		return nil, err
@@ -44,10 +67,46 @@ func (c *RealClient) GenAiCompatResponses(ctx context.Context, cred Credentials,
 	return payload, nil
 }
 
+// cancelReadCloser 在流关闭时同步取消建立阶段派生的 ctx,避免其随流生命周期泄漏。
+type cancelReadCloser struct {
+	io.ReadCloser
+	cancel context.CancelFunc
+}
+
+func (c *cancelReadCloser) Close() error {
+	c.cancel()
+	return c.ReadCloser.Close()
+}
+
+// httpCaller 抽象 BaseClient.Call,便于对预算逻辑做无签名单测。
+type httpCaller interface {
+	Call(ctx context.Context, request *http.Request) (*http.Response, error)
+}
+
+// callWithHeaderBudget 以 wait 为等待响应头预算执行调用:预算内未返回则取消
+// 请求(SDK Call 会把 ctx 重绑到请求);响应头到达即解除预算,之后流的生命
+// 周期由 ctx 决定,返回的流 Close 时同步取消派生 ctx。
+func callWithHeaderBudget(ctx context.Context, c httpCaller, req *http.Request, wait time.Duration) (io.ReadCloser, error) {
+	callCtx, cancel := context.WithCancel(ctx)
+	timer := time.AfterFunc(wait, cancel)
+	response, err := c.Call(callCtx, req)
+	timer.Stop()
+	if err != nil {
+		if response != nil && response.Body != nil {
+			response.Body.Close()
+		}
+		cancel()
+		return nil, err
+	}
+	return &cancelReadCloser{ReadCloser: response.Body, cancel: cancel}, nil
+}
+
 // GenAiCompatResponsesStream 实现 Client:以流式直通 OCI `/actions/v1/responses`,
 // 建立成功(2xx)返回 SSE body(调用方负责 Close);建立失败返回 SDK ServiceError,
 // 与既有渠道切换/熔断错误分类兼容。请求体须由调用方置 stream:true。
-func (c *RealClient) GenAiCompatResponsesStream(ctx context.Context, cred Credentials, region string, body []byte) (io.ReadCloser, error) {
+// 总超时置 0(SSE 读 body 不能有总时限);wait 以定时取消模拟等待响应头预算,
+// 响应头到达即解除,此后流的生命周期完全由 ctx(下游客户端断开)决定。
+func (c *RealClient) GenAiCompatResponsesStream(ctx context.Context, cred Credentials, region string, body []byte, wait time.Duration) (io.ReadCloser, error) {
 	ic, err := c.genAiInferenceClient(cred, region)
 	if err != nil {
 		return nil, err
@@ -55,19 +114,10 @@ func (c *RealClient) GenAiCompatResponsesStream(ctx context.Context, cred Creden
 	client := ic.BaseClient
 	common.UpdateEndpointTemplateForOptions(&client)
 	common.SetMissingTemplateParams(&client)
-	request, err := http.NewRequestWithContext(ctx, http.MethodPost, "/actions/v1/responses", bytes.NewReader(body))
+	client.HTTPClient = dispatcherWithTimeout(client.HTTPClient, 0)
+	request, err := newCompatResponsesRequest(ctx, cred, body)
 	if err != nil {
-		return nil, fmt.Errorf("build compat responses stream request: %w", err)
-	}
-	request.Header.Set("Content-Type", "application/json")
-	request.Header.Set("CompartmentId", cred.TenancyOCID)
-	request.Header.Set("opc-compartment-id", cred.TenancyOCID)
-	response, err := client.Call(ctx, request)
-	if err != nil {
-		if response != nil && response.Body != nil {
-			response.Body.Close()
-		}
 		return nil, err
 	}
-	return response.Body, nil
+	return callWithHeaderBudget(ctx, client, request, wait)
 }

internal/oci/genai_responses_test.go

@@ -0,0 +1,141 @@
+package oci
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/oracle/oci-go-sdk/v65/common"
+)
+
+// staticDispatcher 是非 *http.Client 的自定义 dispatcher,用于降级分支。
+type staticDispatcher struct{}
+
+func (staticDispatcher) Do(*http.Request) (*http.Response, error) { return nil, nil }
+
+func TestDispatcherWithTimeout(t *testing.T) {
+	tr := &http.Transport{}
+	tests := []struct {
+		name    string
+		in      common.HTTPRequestDispatcher
+		timeout time.Duration
+		check   func(t *testing.T, out common.HTTPRequestDispatcher)
+	}{
+		{
+			name: "http.Client 换总超时并保留 Transport", in: &http.Client{Transport: tr, Timeout: 60 * time.Second},
+			timeout: 300 * time.Second,
+			check: func(t *testing.T, out common.HTTPRequestDispatcher) {
+				hc, ok := out.(*http.Client)
+				if !ok || hc.Timeout != 300*time.Second || hc.Transport != tr {
+					t.Fatalf("期望拷贝 client 且 Timeout=300s、Transport 保留, 得到 %#v", out)
+				}
+			},
+		},
+		{
+			name: "timeout=0 表示无总超时", in: &http.Client{Timeout: 60 * time.Second}, timeout: 0,
+			check: func(t *testing.T, out common.HTTPRequestDispatcher) {
+				if hc := out.(*http.Client); hc.Timeout != 0 {
+					t.Fatalf("期望 Timeout=0, 得到 %v", hc.Timeout)
+				}
+			},
+		},
+		{
+			name: "非 http.Client 原样返回", in: staticDispatcher{}, timeout: 300 * time.Second,
+			check: func(t *testing.T, out common.HTTPRequestDispatcher) {
+				if _, ok := out.(staticDispatcher); !ok {
+					t.Fatalf("期望原样返回自定义 dispatcher, 得到 %#v", out)
+				}
+			},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) { tt.check(t, dispatcherWithTimeout(tt.in, tt.timeout)) })
+	}
+}
+
+// ctxReader 模拟真实 HTTP body:请求 ctx 取消后读即失败。
+type ctxReader struct {
+	ctx context.Context
+	r   io.Reader
+}
+
+func (c *ctxReader) Read(p []byte) (int, error) {
+	if err := c.ctx.Err(); err != nil {
+		return 0, err
+	}
+	return c.r.Read(p)
+}
+
+// fakeCaller 在 delay 后返回响应;期间 ctx 取消则按真实行为返回 ctx 错误。
+type fakeCaller struct {
+	delay   time.Duration
+	body    string
+	gotCtx  context.Context
+	failErr error
+}
+
+func (f *fakeCaller) Call(ctx context.Context, _ *http.Request) (*http.Response, error) {
+	f.gotCtx = ctx
+	if f.failErr != nil {
+		return nil, f.failErr
+	}
+	select {
+	case <-time.After(f.delay):
+		body := &ctxReader{ctx: ctx, r: strings.NewReader(f.body)}
+		return &http.Response{StatusCode: http.StatusOK, Body: io.NopCloser(body)}, nil
+	case <-ctx.Done():
+		return nil, ctx.Err()
+	}
+}
+
+func TestCallWithHeaderBudget(t *testing.T) {
+	req, _ := http.NewRequest(http.MethodPost, "/actions/v1/responses", nil)
+	t.Run("预算内返回响应头后长读不受预算影响", func(t *testing.T) {
+		fc := &fakeCaller{delay: 0, body: "data: hello"}
+		stream, err := callWithHeaderBudget(context.Background(), fc, req, 30*time.Millisecond)
+		if err != nil {
+			t.Fatalf("callWithHeaderBudget = %v", err)
+		}
+		defer stream.Close()
+		time.Sleep(90 * time.Millisecond) // 远超预算,验证响应头到达后预算已解除
+		payload, err := io.ReadAll(stream)
+		if err != nil || string(payload) != "data: hello" {
+			t.Fatalf("预算解除后读流 = %q, %v; 期望完整 body", payload, err)
+		}
+	})
+	t.Run("超预算未返回响应头即取消", func(t *testing.T) {
+		fc := &fakeCaller{delay: time.Minute}
+		start := time.Now()
+		_, err := callWithHeaderBudget(context.Background(), fc, req, 30*time.Millisecond)
+		if !errors.Is(err, context.Canceled) {
+			t.Fatalf("期望 context.Canceled, 得到 %v", err)
+		}
+		if elapsed := time.Since(start); elapsed > 5*time.Second {
+			t.Fatalf("取消耗时 %v, 未受预算约束", elapsed)
+		}
+	})
+	t.Run("关闭流时取消派生 ctx", func(t *testing.T) {
+		fc := &fakeCaller{delay: 0, body: "x"}
+		stream, err := callWithHeaderBudget(context.Background(), fc, req, time.Minute)
+		if err != nil {
+			t.Fatalf("callWithHeaderBudget = %v", err)
+		}
+		stream.Close()
+		if fc.gotCtx.Err() == nil {
+			t.Fatal("Close 后派生 ctx 应已取消")
+		}
+	})
+	t.Run("建立失败时同样取消派生 ctx", func(t *testing.T) {
+		fc := &fakeCaller{failErr: errors.New("boom")}
+		if _, err := callWithHeaderBudget(context.Background(), fc, req, time.Minute); err == nil {
+			t.Fatal("期望建立失败")
+		}
+		if fc.gotCtx.Err() == nil {
+			t.Fatal("失败路径派生 ctx 应已取消")
+		}
+	})
+}

internal/oci/genai_speech.go

@@ -0,0 +1,44 @@
+package oci
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+
+	"github.com/oracle/oci-go-sdk/v65/common"
+)
+
+// compatSpeechLimit 限制 TTS 音频响应体大小(长文本 mp3 给足余量)。
+const compatSpeechLimit = int64(64 << 20)
+
+// GenAiCompatSpeech 实现 Client:把 OpenAI Audio Speech 请求体直通到 OCI
+// 兼容面 `/openai/v1/audio/speech`(IAM 签名,BasePath 置空——该面与
+// /20231130/actions 面并存,实测仅前者承载 TTS)。返回音频字节与 Content-Type。
+func (c *RealClient) GenAiCompatSpeech(ctx context.Context, cred Credentials, region string, body []byte) ([]byte, string, error) {
+	ic, err := c.genAiInferenceClient(cred, region)
+	if err != nil {
+		return nil, "", err
+	}
+	client := ic.BaseClient
+	common.UpdateEndpointTemplateForOptions(&client)
+	common.SetMissingTemplateParams(&client)
+	client.BasePath = ""
+	request, err := http.NewRequestWithContext(ctx, http.MethodPost, "/openai/v1/audio/speech", bytes.NewReader(body))
+	if err != nil {
+		return nil, "", fmt.Errorf("build compat speech request: %w", err)
+	}
+	request.Header.Set("Content-Type", "application/json")
+	request.Header.Set("opc-compartment-id", cred.TenancyOCID)
+	response, err := client.Call(ctx, request)
+	if err != nil {
+		return nil, "", err
+	}
+	defer response.Body.Close()
+	payload, err := io.ReadAll(io.LimitReader(response.Body, compatSpeechLimit))
+	if err != nil {
+		return nil, "", fmt.Errorf("read compat speech body: %w", err)
+	}
+	return payload, response.Header.Get("Content-Type"), nil
+}

internal/oci/instance.go

@@ -400,6 +400,7 @@ func fillInstanceIPs(ctx context.Context, cc core.ComputeClient, vn core.Virtual
 		wg          sync.WaitGroup
 		mu          sync.Mutex
 		sem         = make(chan struct{}, 8)
+		primarySeen = make(map[*Instance]bool)
 	)
 	for _, att := range attResp.Items {
 		inst, ok := active[deref(att.InstanceId)]
@@ -416,16 +417,30 @@ func fillInstanceIPs(ctx context.Context, cc core.ComputeClient, vn core.Virtual
 				return
 			}
 			mu.Lock()
-			inst.SubnetID = deref(vnicResp.SubnetId)
+			applyVnicAddrs(inst, vnicResp.Vnic, primarySeen)
-			inst.PrivateIP = deref(vnicResp.PrivateIp)
-			inst.PublicIP = deref(vnicResp.PublicIp)
-			inst.Ipv6Addresses = vnicResp.Ipv6Addresses
 			mu.Unlock()
 		}(att.VnicId, inst)
 	}
 	wg.Wait()
 }
 
+// applyVnicAddrs 将 VNIC 地址写入实例。多网卡实例以主网卡为准：
+// 主网卡返回前先用先到的网卡兜底，主网卡到达后覆盖并锁定，避免并发
+// 完成顺序决定展示结果。调用方需持有保护 inst 与 primarySeen 的锁。
+func applyVnicAddrs(inst *Instance, v core.Vnic, primarySeen map[*Instance]bool) {
+	isPrimary := v.IsPrimary != nil && *v.IsPrimary
+	if !isPrimary && (primarySeen[inst] || inst.SubnetID != "") {
+		return
+	}
+	inst.SubnetID = deref(v.SubnetId)
+	inst.PrivateIP = deref(v.PrivateIp)
+	inst.PublicIP = deref(v.PublicIp)
+	inst.Ipv6Addresses = v.Ipv6Addresses
+	if isPrimary {
+		primarySeen[inst] = true
+	}
+}
+
 func toInstance(inst core.Instance) Instance {
 	out := Instance{
 		ID:                 deref(inst.Id),

internal/oci/instance_test.go

@@ -5,9 +5,51 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/oracle/oci-go-sdk/v65/common"
 	"github.com/oracle/oci-go-sdk/v65/core"
 )
 
+func TestApplyVnicAddrs(t *testing.T) {
+	primary := core.Vnic{
+		IsPrimary: common.Bool(true),
+		SubnetId:  common.String("sub-a"),
+		PrivateIp: common.String("10.0.0.2"),
+		PublicIp:  common.String("1.1.1.1"),
+	}
+	secondary := core.Vnic{
+		IsPrimary: common.Bool(false),
+		SubnetId:  common.String("sub-b"),
+		PrivateIp: common.String("10.0.0.9"),
+	}
+	secondary2 := core.Vnic{
+		SubnetId:  common.String("sub-c"),
+		PrivateIp: common.String("10.0.0.7"),
+	}
+	tests := []struct {
+		name        string
+		order       []core.Vnic
+		wantPrivate string
+		wantSubnet  string
+	}{
+		{name: "主卡先到不被次卡覆盖", order: []core.Vnic{primary, secondary}, wantPrivate: "10.0.0.2", wantSubnet: "sub-a"},
+		{name: "次卡先兜底主卡后覆盖", order: []core.Vnic{secondary, primary}, wantPrivate: "10.0.0.2", wantSubnet: "sub-a"},
+		{name: "无主卡时先到者保留", order: []core.Vnic{secondary, secondary2}, wantPrivate: "10.0.0.9", wantSubnet: "sub-b"},
+		{name: "仅次卡也能兜底", order: []core.Vnic{secondary2}, wantPrivate: "10.0.0.7", wantSubnet: "sub-c"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			inst := &Instance{}
+			seen := make(map[*Instance]bool)
+			for _, v := range tt.order {
+				applyVnicAddrs(inst, v, seen)
+			}
+			if inst.PrivateIP != tt.wantPrivate || inst.SubnetID != tt.wantSubnet {
+				t.Errorf("got (%q, %q), want (%q, %q)", inst.PrivateIP, inst.SubnetID, tt.wantPrivate, tt.wantSubnet)
+			}
+		})
+	}
+}
+
 func TestShellSingleQuote(t *testing.T) {
 	tests := []struct {
 		name string

internal/oci/logrelay.go

@@ -234,8 +234,12 @@ func (c *RealClient) EnsureRelayConnector(ctx context.Context, cred Credentials,
 	if err != nil {
 		return RelayResource{}, err
 	}
-	if res, ok, err := findRelayConnector(ctx, sc, cred.TenancyOCID); err != nil || ok {
+	res, ok, err := findRelayConnector(ctx, sc, cred.TenancyOCID)
-		return res, err
+	if err != nil {
+		return RelayResource{}, err
+	}
+	if ok {
+		return res, reconcileRelayCondition(ctx, sc, res.ID, condition)
 	}
 	details := sch.CreateServiceConnectorDetails{
 		DisplayName:   common.String(relayConnectorName),
@@ -257,6 +261,45 @@ func (c *RealClient) EnsureRelayConnector(ctx context.Context, cred Credentials,
 	return waitRelayConnector(ctx, sc, cred.TenancyOCID)
 }
 
+// reconcileRelayCondition 对齐存量 Connector 的过滤条件:关键事件清单变更
+// (如去除 LaunchInstance)后,已建链路经「一键创建」幂等调用原地更新,无需拆除重建。
+func reconcileRelayCondition(ctx context.Context, sc sch.ServiceConnectorClient, id, condition string) error {
+	got, err := sc.GetServiceConnector(ctx, sch.GetServiceConnectorRequest{ServiceConnectorId: &id})
+	if err != nil {
+		return fmt.Errorf("get service connector: %w", err)
+	}
+	if !relayConditionDiffers(got.Tasks, condition) {
+		return nil
+	}
+	details := sch.UpdateServiceConnectorDetails{Tasks: []sch.TaskDetails{}}
+	if condition != "" {
+		details.Tasks = []sch.TaskDetails{sch.LogRuleTaskDetails{Condition: &condition}}
+	}
+	_, err = sc.UpdateServiceConnector(ctx, sch.UpdateServiceConnectorRequest{
+		ServiceConnectorId: &id, UpdateServiceConnectorDetails: details,
+	})
+	if err != nil {
+		return fmt.Errorf("update service connector condition: %w", err)
+	}
+	return nil
+}
+
+// relayConditionDiffers 判断现有任务集与期望条件是否不一致:
+// 期望形态是单条 LogRule 条件;任务数、类型或条件文本不同均视为漂移。
+func relayConditionDiffers(tasks []sch.TaskDetailsResponse, want string) bool {
+	if want == "" {
+		return len(tasks) > 0
+	}
+	if len(tasks) != 1 {
+		return true
+	}
+	rule, ok := tasks[0].(sch.LogRuleTaskDetailsResponse)
+	if !ok || rule.Condition == nil {
+		return true
+	}
+	return *rule.Condition != want
+}
+
 // findRelayConnector 按名查找存活 Connector。
 func findRelayConnector(ctx context.Context, sc sch.ServiceConnectorClient, tenancy string) (RelayResource, bool, error) {
 	list, err := sc.ListServiceConnectors(ctx, sch.ListServiceConnectorsRequest{

internal/oci/logrelay_test.go

@@ -3,6 +3,8 @@ package oci
 import (
 	"strings"
 	"testing"
+
+	"github.com/oracle/oci-go-sdk/v65/sch"
 )
 
 func TestRelayEventCondition(t *testing.T) {
@@ -35,3 +37,31 @@ func TestRelayEventConditionQuoting(t *testing.T) {
 		t.Errorf("单引号数 = %d, want 2 (%s)", strings.Count(cond, "'"), cond)
 	}
 }
+
+func TestRelayConditionDiffers(t *testing.T) {
+	cond := "data.eventName='TerminateInstance'"
+	rule := func(c string) sch.TaskDetailsResponse {
+		return sch.LogRuleTaskDetailsResponse{Condition: &c}
+	}
+	tests := []struct {
+		name  string
+		tasks []sch.TaskDetailsResponse
+		want  string
+		diff  bool
+	}{
+		{name: "条件一致不漂移", tasks: []sch.TaskDetailsResponse{rule(cond)}, want: cond, diff: false},
+		{name: "条件文本不同漂移", tasks: []sch.TaskDetailsResponse{rule("data.eventName='LaunchInstance'")}, want: cond, diff: true},
+		{name: "无任务但期望条件漂移", tasks: nil, want: cond, diff: true},
+		{name: "多任务漂移", tasks: []sch.TaskDetailsResponse{rule(cond), rule(cond)}, want: cond, diff: true},
+		{name: "期望空且无任务不漂移", tasks: nil, want: "", diff: false},
+		{name: "期望空但有任务漂移", tasks: []sch.TaskDetailsResponse{rule(cond)}, want: "", diff: true},
+		{name: "条件缺失漂移", tasks: []sch.TaskDetailsResponse{sch.LogRuleTaskDetailsResponse{}}, want: cond, diff: true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := relayConditionDiffers(tt.tasks, tt.want); got != tt.diff {
+				t.Errorf("differs = %v, want %v", got, tt.diff)
+			}
+		})
+	}
+}

internal/oci/proxyhttp.go

@@ -2,6 +2,7 @@ package oci
 
 import (
 	"fmt"
+	"net"
 	"net/http"
 	"net/url"
 	"time"
@@ -23,6 +24,13 @@ type ProxySpec struct {
 // proxyClientTimeout 与 SDK 默认 HTTPClient 超时保持一致。
 const proxyClientTimeout = 60 * time.Second
 
+// 阶段超时对齐 SDK 直连 Transport 模板(transport_template_provider):连不上的
+// 代理快速失败,而不是拖满总超时;responses 直通去掉总超时后这是建立阶段的兜底之一。
+const (
+	proxyDialTimeout         = 30 * time.Second
+	proxyTLSHandshakeTimeout = 10 * time.Second
+)
+
 // applyProxy 在 SDK client 构造后统一挂出站代理;未关联代理时不动默认配置。
 // 所有 New*ClientWithConfigurationProvider 调用点构造成功后都必须经过这里。
 func applyProxy(base *common.BaseClient, cred Credentials) {
@@ -52,18 +60,23 @@ func HTTPClientFor(p *ProxySpec) *http.Client {
 // transportFor 构造代理 Transport:http / https 走 CONNECT,socks5 走拨号器。
 func transportFor(p *ProxySpec) *http.Transport {
 	addr := fmt.Sprintf("%s:%d", p.Host, p.Port)
+	dialer := &net.Dialer{Timeout: proxyDialTimeout}
 	if p.Type == "http" || p.Type == "https" {
 		u := &url.URL{Scheme: p.Type, Host: addr}
 		if p.Username != "" {
 			u.User = url.UserPassword(p.Username, p.Password)
 		}
-		return &http.Transport{Proxy: http.ProxyURL(u)}
+		return &http.Transport{
+			Proxy:               http.ProxyURL(u),
+			DialContext:         dialer.DialContext,
+			TLSHandshakeTimeout: proxyTLSHandshakeTimeout,
+		}
 	}
 	var auth *proxy.Auth
 	if p.Username != "" {
 		auth = &proxy.Auth{User: p.Username, Password: p.Password}
 	}
-	d, err := proxy.SOCKS5("tcp", addr, auth, proxy.Direct)
+	d, err := proxy.SOCKS5("tcp", addr, auth, dialer)
 	if err != nil {
 		return nil
 	}
@@ -71,5 +84,8 @@ func transportFor(p *ProxySpec) *http.Transport {
 	if !ok {
 		return nil
 	}
-	return &http.Transport{DialContext: cd.DialContext}
+	return &http.Transport{
+		DialContext:         cd.DialContext,
+		TLSHandshakeTimeout: proxyTLSHandshakeTimeout,
+	}
 }

internal/oci/proxyhttp_test.go

@@ -0,0 +1,34 @@
+package oci
+
+import (
+	"testing"
+)
+
+func TestTransportForStageTimeouts(t *testing.T) {
+	tests := []struct {
+		name      string
+		spec      *ProxySpec
+		wantProxy bool // CONNECT 分支应设 Proxy 函数
+	}{
+		{name: "http CONNECT 代理", spec: &ProxySpec{Type: "http", Host: "127.0.0.1", Port: 8080}, wantProxy: true},
+		{name: "https CONNECT 代理", spec: &ProxySpec{Type: "https", Host: "127.0.0.1", Port: 8443}, wantProxy: true},
+		{name: "socks5 代理", spec: &ProxySpec{Type: "socks5", Host: "127.0.0.1", Port: 1080, Username: "u", Password: "p"}},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tr := transportFor(tt.spec)
+			if tr == nil {
+				t.Fatal("transportFor 返回 nil")
+			}
+			if (tr.Proxy != nil) != tt.wantProxy {
+				t.Fatalf("Proxy 函数存在性 = %v, 期望 %v", tr.Proxy != nil, tt.wantProxy)
+			}
+			if tr.DialContext == nil {
+				t.Fatal("应设置带超时的 DialContext")
+			}
+			if tr.TLSHandshakeTimeout != proxyTLSHandshakeTimeout {
+				t.Fatalf("TLSHandshakeTimeout = %v, 期望 %v", tr.TLSHandshakeTimeout, proxyTLSHandshakeTimeout)
+			}
+		})
+	}
+}

internal/oci/shape.go

@@ -26,6 +26,9 @@ type ComputeShape struct {
 	MemoryMaxGBs         float32 `json:"memoryMaxGBs,omitempty"`
 	Gpus                 int     `json:"gpus,omitempty"`
 	ProcessorDescription string  `json:"processorDescription,omitempty"`
+	// QuotaNames 是该 shape 对应的配额名(与 Limits 服务 compute limit name 同名),
+	// 前端据此结合 limits 行判定配额与 AD 可用性。
+	QuotaNames []string `json:"quotaNames,omitempty"`
 }
 
 // shapeCacheEntry 是一份 shape 清单的缓存条目。
@@ -92,6 +95,7 @@ func toComputeShape(s core.Shape) ComputeShape {
 		BillingType:          string(s.BillingType),
 		IsFlexible:           s.OcpuOptions != nil,
 		ProcessorDescription: deref(s.ProcessorDescription),
+		QuotaNames:           s.QuotaNames,
 	}
 	out.Ocpus, out.MemoryInGBs = deref32(s.Ocpus), deref32(s.MemoryInGBs)
 	if s.Gpus != nil {

internal/service/aigateway.go

@@ -10,8 +10,10 @@ import (
 	"fmt"
 	"log"
 	"sort"
+	"strconv"
 	"strings"
 	"sync"
+	"sync/atomic"
 	"time"
 
 	"gorm.io/gorm"
@@ -58,11 +60,156 @@ type AiGatewayService struct {
 	lastTouch map[uint]time.Time
 	// onChannelsChanged 在渠道增删后触发,由 main 装配为探测任务同步钩子
 	onChannelsChanged func(context.Context)
+	// filterDeprecated 是「过滤弃用模型」开关(内存镜像,持久化在 settings 表)
+	filterDeprecated atomic.Bool
+	// streamGuard* 是 Responses 流式保险丝(instructions+tools 合计超阈值改非流式)
+	streamGuardEnabled atomic.Bool
+	streamGuardKB      atomic.Int64
+	// grokWebSearch / grokXSearch 是 xai. 模型服务端搜索工具默认注入开关
+	grokWebSearch atomic.Bool
+	grokXSearch   atomic.Bool
+	// upstreamWaitSec 是 responses 直通的上游无响应预算(秒):非流式为单次尝试
+	// 总超时,流式为等待响应头预算;multi-agent/搜索类模型远超 SDK 默认 60s
+	upstreamWaitSec atomic.Int64
 }
 
 // NewAiGatewayService 组装依赖;调用 StartCleanup 后开始调用日志周期清理。
 func NewAiGatewayService(db *gorm.DB, configs *OciConfigService, client oci.Client) *AiGatewayService {
-	return &AiGatewayService{db: db, configs: configs, client: client, lastTouch: map[uint]time.Time{}}
+	s := &AiGatewayService{db: db, configs: configs, client: client, lastTouch: map[uint]time.Time{}}
+	s.filterDeprecated.Store(loadBoolSetting(db, settingAiFilterDeprecated, false))
+	s.streamGuardEnabled.Store(loadBoolSetting(db, settingAiStreamGuardEnabled, true))
+	s.streamGuardKB.Store(int64(loadIntSetting(db, settingAiStreamGuardKB, defaultStreamGuardKB)))
+	s.grokWebSearch.Store(loadBoolSetting(db, settingAiGrokWebSearch, true))
+	s.grokXSearch.Store(loadBoolSetting(db, settingAiGrokXSearch, true))
+	s.upstreamWaitSec.Store(int64(loadIntSetting(db, settingAiUpstreamWaitSec, defaultUpstreamWaitSec)))
+	return s
+}
+
+// AI 网关运行时设置的配置键;bool 值存 "1"/"0"。
+const (
+	// settingAiFilterDeprecated 是「过滤弃用模型」开关,缺省关闭。
+	settingAiFilterDeprecated = "ai_filter_deprecated"
+	// settingAiStreamGuardEnabled / settingAiStreamGuardKB 是流式保险丝开关与
+	// 阈值(KB),缺省开、60(上游对 instructions+tools >≈64.5KB 流式静默断流)。
+	settingAiStreamGuardEnabled = "ai_stream_guard_enabled"
+	settingAiStreamGuardKB      = "ai_stream_guard_kb"
+	// settingAiGrokWebSearch / settingAiGrokXSearch 是 grok 搜索工具默认注入
+	// 开关,缺省开。
+	settingAiGrokWebSearch = "ai_grok_web_search"
+	settingAiGrokXSearch   = "ai_grok_x_search"
+	// settingAiUpstreamWaitSec 是 responses 直通的上游无响应预算(秒)。
+	settingAiUpstreamWaitSec = "ai_upstream_wait_seconds"
+)
+
+// defaultStreamGuardKB 是保险丝阈值缺省值,低于实测断流边界留余量。
+const defaultStreamGuardKB = 60
+
+// defaultUpstreamWaitSec 是上游无响应预算缺省值(秒):multi-agent 非流式
+// 实测 100~180s 才回响应头,给足余量;上下限见 SetUpstreamWait。
+const defaultUpstreamWaitSec = 300
+
+// loadBoolSetting 读 settings 表布尔键,无行或值非法时返回缺省。
+func loadBoolSetting(db *gorm.DB, key string, def bool) bool {
+	var row model.Setting
+	if err := db.Where("key = ?", key).First(&row).Error; err != nil {
+		return def
+	}
+	return row.Value == "1"
+}
+
+// loadIntSetting 读 settings 表整数键,无行或解析失败时返回缺省。
+func loadIntSetting(db *gorm.DB, key string, def int) int {
+	var row model.Setting
+	if err := db.Where("key = ?", key).First(&row).Error; err != nil {
+		return def
+	}
+	n, err := strconv.Atoi(row.Value)
+	if err != nil {
+		return def
+	}
+	return n
+}
+
+// saveBoolSetting 持久化布尔键。
+func (s *AiGatewayService) saveBoolSetting(ctx context.Context, key string, on bool) error {
+	value := "0"
+	if on {
+		value = "1"
+	}
+	return s.db.WithContext(ctx).Save(&model.Setting{Key: key, Value: value}).Error
+}
+
+// FilterDeprecated 返回「过滤弃用模型」开关状态。
+func (s *AiGatewayService) FilterDeprecated() bool { return s.filterDeprecated.Load() }
+
+// SetFilterDeprecated 持久化并即时生效开关:开启后已宣布弃用
+// (deprecated_at 非空,即使未退役)的模型从列表与路由中排除。
+func (s *AiGatewayService) SetFilterDeprecated(ctx context.Context, on bool) error {
+	if err := s.saveBoolSetting(ctx, settingAiFilterDeprecated, on); err != nil {
+		return fmt.Errorf("保存过滤弃用模型开关: %w", err)
+	}
+	s.filterDeprecated.Store(on)
+	return nil
+}
+
+// StreamGuard 返回流式保险丝开关与阈值(KB)。
+func (s *AiGatewayService) StreamGuard() (bool, int) {
+	return s.streamGuardEnabled.Load(), int(s.streamGuardKB.Load())
+}
+
+// SetStreamGuard 持久化并即时生效流式保险丝;kb 限定 1..1024。
+func (s *AiGatewayService) SetStreamGuard(ctx context.Context, on bool, kb int) error {
+	if kb < 1 || kb > 1024 {
+		return fmt.Errorf("流式保险丝阈值须在 1..1024 KB, 收到 %d", kb)
+	}
+	if err := s.saveBoolSetting(ctx, settingAiStreamGuardEnabled, on); err != nil {
+		return fmt.Errorf("保存流式保险丝开关: %w", err)
+	}
+	err := s.db.WithContext(ctx).
+		Save(&model.Setting{Key: settingAiStreamGuardKB, Value: strconv.Itoa(kb)}).Error
+	if err != nil {
+		return fmt.Errorf("保存流式保险丝阈值: %w", err)
+	}
+	s.streamGuardEnabled.Store(on)
+	s.streamGuardKB.Store(int64(kb))
+	return nil
+}
+
+// UpstreamWait 返回 responses 直通的上游无响应预算。
+func (s *AiGatewayService) UpstreamWait() time.Duration {
+	return time.Duration(s.upstreamWaitSec.Load()) * time.Second
+}
+
+// SetUpstreamWait 持久化并即时生效上游无响应预算;sec 限定 30..900。
+func (s *AiGatewayService) SetUpstreamWait(ctx context.Context, sec int) error {
+	if sec < 30 || sec > 900 {
+		return fmt.Errorf("上游无响应预算须在 30..900 秒, 收到 %d", sec)
+	}
+	err := s.db.WithContext(ctx).
+		Save(&model.Setting{Key: settingAiUpstreamWaitSec, Value: strconv.Itoa(sec)}).Error
+	if err != nil {
+		return fmt.Errorf("保存上游无响应预算: %w", err)
+	}
+	s.upstreamWaitSec.Store(int64(sec))
+	return nil
+}
+
+// GrokSearch 返回 grok 服务端搜索工具默认注入开关(web_search, x_search)。
+func (s *AiGatewayService) GrokSearch() (bool, bool) {
+	return s.grokWebSearch.Load(), s.grokXSearch.Load()
+}
+
+// SetGrokSearch 持久化并即时生效 grok 搜索工具默认注入开关。
+func (s *AiGatewayService) SetGrokSearch(ctx context.Context, web, x bool) error {
+	if err := s.saveBoolSetting(ctx, settingAiGrokWebSearch, web); err != nil {
+		return fmt.Errorf("保存 grok web_search 开关: %w", err)
+	}
+	if err := s.saveBoolSetting(ctx, settingAiGrokXSearch, x); err != nil {
+		return fmt.Errorf("保存 grok x_search 开关: %w", err)
+	}
+	s.grokWebSearch.Store(web)
+	s.grokXSearch.Store(x)
+	return nil
 }
 
 // SetOnChannelsChanged 注册渠道数量变化钩子(渠道创建/删除成功后调用)。
@@ -239,11 +386,34 @@ func valueOr(p *int, def int) int {
 	return def
 }
 
-// Channels 列出全部渠道。
+// Channels 列出全部渠道并回填各自的模型缓存计数。
 func (s *AiGatewayService) Channels(ctx context.Context) ([]model.AiChannel, error) {
 	var chs []model.AiChannel
-	err := s.db.WithContext(ctx).Order("priority ASC, id ASC").Find(&chs).Error
+	if err := s.db.WithContext(ctx).Order("priority ASC, id ASC").Find(&chs).Error; err != nil {
-	return chs, err
+		return nil, err
+	}
+	var rows []struct {
+		ChannelID uint
+		N         int64
+	}
+	q := s.db.WithContext(ctx).Model(&model.AiModelCache{}).
+		Select("channel_id, COUNT(*) AS n").
+		Where("name NOT IN (SELECT name FROM ai_model_blacklists)")
+	if s.FilterDeprecated() {
+		q = q.Where("deprecated_at IS NULL")
+	}
+	err := q.Group("channel_id").Scan(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+	counts := make(map[uint]int64, len(rows))
+	for _, r := range rows {
+		counts[r.ChannelID] = r.N
+	}
+	for i := range chs {
+		chs[i].ModelCount = counts[chs[i].ID]
+	}
+	return chs, nil
 }
 
 // UpdateChannel 修改渠道名称 / 分组 / 启停 / 优先级 / 权重。
@@ -286,7 +456,7 @@ func (s *AiGatewayService) DeleteChannel(ctx context.Context, id uint) error {
 
 // ---- 探测与模型同步 ----
 
-// ProbeChannel 探测渠道可用性:服务可见性 → 模型同步 → maxTokens=1 配额试调。
+// ProbeChannel 探测渠道可用性:服务可见性 → 模型同步 → 极小 max_tokens 配额试调。
 func (s *AiGatewayService) ProbeChannel(ctx context.Context, id uint) (*model.AiChannel, error) {
 	var ch model.AiChannel
 	if err := s.db.WithContext(ctx).First(&ch, id).Error; err != nil {
@@ -335,13 +505,15 @@ func (s *AiGatewayService) probe(ctx context.Context, cred oci.Credentials, ch *
 	return s.probeChat(ctx, cred, ch, models)
 }
 
-// probeChat 按候选顺序试调(上限 8):遇「模型不可按需调用」(微调基座 400 / 实体
+// probeChat 按候选顺序试调(上限 8,已验证的探测模型置首位):遇「模型不可按需
-// 不存在 404)换下一个候选,错误信息带模型名供用户加入黑名单;401/403 与鉴权类 404
+// 调用」(微调基座 400 / 实体不存在 404)换下一个候选,错误信息带模型名供用户加入
-// 属租户级直接定论 no_quota;其余错误(元数据标 CHAT 但实际不可对话等)累计 3 次止损。
+// 黑名单;401/403 与鉴权类 404 可能只是模型级无权限,记录后继续换候选,全部候选
+// 失败且出现过鉴权拒绝才定论 no_quota;其余错误累计 3 次止损。
 func (s *AiGatewayService) probeChat(ctx context.Context, cred oci.Credentials, ch *model.AiChannel, models []oci.GenAiModel) (string, string) {
 	status, detail := "error", "无可试调对话模型"
+	quotaDetail := ""
 	errBudget := 3
-	for _, m := range probeCandidates(models) {
+	for _, m := range probeCandidates(ch.ProbeModel, models) {
 		code, err := s.client.GenAiProbeChat(ctx, cred, ch.Region, m.Ocid, m.Name)
 		switch {
 		case code == 200 || code == 429:
@@ -349,7 +521,7 @@ func (s *AiGatewayService) probeChat(ctx context.Context, cred oci.Credentials,
 		case oci.IsModelUnavailable(err):
 			status, detail = "error", truncateErr(fmt.Sprintf("%s: 不可按需调用,建议加入模型黑名单", m.Name))
 		case code == 401 || code == 403 || code == 404:
-			return "no_quota", truncateErr(oci.CompactError(err))
+			quotaDetail = truncateErr(fmt.Sprintf("%s: %s", m.Name, oci.CompactError(err)))
 		default:
 			status, detail = "error", truncateErr(fmt.Sprintf("%s: %s", m.Name, oci.CompactError(err)))
 			if errBudget--; errBudget == 0 {
@@ -357,6 +529,9 @@ func (s *AiGatewayService) probeChat(ctx context.Context, cred oci.Credentials,
 			}
 		}
 	}
+	if quotaDetail != "" {
+		return "no_quota", quotaDetail
+	}
 	return status, detail
 }
 
@@ -364,13 +539,18 @@ func (s *AiGatewayService) probeChat(ctx context.Context, cred oci.Credentials,
 // 不可按需调用的坏模型找到可用者;其他错误另有 3 次止损预算。
 const probeCandidateCap = 8
 
-// probeCandidates 只取对话模型,按可靠度排序后跨厂商取候选:主流文本模型优先;
+// probeCandidates 只取对话模型,按可靠度排序后跨厂商取候选:用户已验证的
+// probeModel 固定放首位(不做能力过滤,测试通过即有效),其余主流文本模型优先;
 // voice 等负分形态(元数据标 CHAT 但实际不可对话)直接排除,不浪费试调预算;
 // 每厂商先取最高分再按分数补位——部分区域某厂商全为微调基座(调用必失败),
 // 不能让单一厂商占满候选名额拖垮整个渠道的探测结论。
-func probeCandidates(models []oci.GenAiModel) []oci.GenAiModel {
+func probeCandidates(probeModel string, models []oci.GenAiModel) []oci.GenAiModel {
-	var sorted []oci.GenAiModel
+	var pinned, sorted []oci.GenAiModel
 	for _, m := range models {
+		if probeModel != "" && m.Name == probeModel {
+			pinned = append(pinned, m)
+			continue
+		}
 		if (m.Capability == "" || m.Capability == "CHAT") && probeScore(m.Name) >= 0 {
 			sorted = append(sorted, m)
 		}
@@ -378,7 +558,7 @@ func probeCandidates(models []oci.GenAiModel) []oci.GenAiModel {
 	sort.SliceStable(sorted, func(i, j int) bool {
 		return probeScore(sorted[i].Name) > probeScore(sorted[j].Name)
 	})
-	return diversifyByVendor(sorted, probeCandidateCap)
+	return append(pinned, diversifyByVendor(sorted, probeCandidateCap)...)
 }
 
 // diversifyByVendor 从已排序列表先每厂商各取一个,不足 limit 再按原序补位。
@@ -497,12 +677,80 @@ func (s *AiGatewayService) replaceModels(ctx context.Context, channelID uint, mo
 	})
 }
 
+// channelModels 列出渠道模型缓存;黑名单模型查询层兜底过滤
+// (拉黑即删缓存,正常不会残留,防御旧数据 / 并发窗口);
+// 「过滤弃用模型」开关开启时同样剔除已宣布弃用者(数据保留,展示口径过滤)。
 func (s *AiGatewayService) channelModels(ctx context.Context, channelID uint) ([]model.AiModelCache, error) {
+	q := s.db.WithContext(ctx).Where("channel_id = ?", channelID).
+		Where("name NOT IN (SELECT name FROM ai_model_blacklists)")
+	if s.FilterDeprecated() {
+		q = q.Where("deprecated_at IS NULL")
+	}
 	var rows []model.AiModelCache
-	err := s.db.WithContext(ctx).Where("channel_id = ?", channelID).Order("name ASC").Find(&rows).Error
+	err := q.Order("name ASC").Find(&rows).Error
 	return rows, err
 }
 
+// ChannelModels 列出渠道的模型缓存(名称排序),渠道不存在时报错。
+func (s *AiGatewayService) ChannelModels(ctx context.Context, id uint) ([]model.AiModelCache, error) {
+	var n int64
+	if err := s.db.WithContext(ctx).Model(&model.AiChannel{}).Where("id = ?", id).Count(&n).Error; err != nil {
+		return nil, err
+	}
+	if n == 0 {
+		return nil, fmt.Errorf("渠道不存在")
+	}
+	return s.channelModels(ctx, id)
+}
+
+// TestChannelModel 对渠道缓存中的指定模型发极小试调;通过时把该模型设
+// 为渠道探测验证模型(此后探测置于候选首位),渠道探测状态不为 ok 时顺带置 ok 并
+// 复位熔断;未通过仅返回错误,不改动渠道状态。
+func (s *AiGatewayService) TestChannelModel(ctx context.Context, id uint, name string) (*model.AiChannel, error) {
+	var ch model.AiChannel
+	if err := s.db.WithContext(ctx).First(&ch, id).Error; err != nil {
+		return nil, fmt.Errorf("渠道不存在")
+	}
+	var mc model.AiModelCache
+	err := s.db.WithContext(ctx).Where("channel_id = ? AND name = ?", id, name).First(&mc).Error
+	if err != nil {
+		return nil, fmt.Errorf("模型不在该渠道缓存中,请先同步模型")
+	}
+	cred, err := s.configs.credentialsByID(ctx, ch.OciConfigID)
+	if err != nil {
+		return nil, err
+	}
+	code, err := s.client.GenAiProbeChat(ctx, cred, ch.Region, mc.ModelOcid, mc.Name)
+	if code != 200 && code != 429 {
+		msg := fmt.Sprintf("HTTP %d", code)
+		if err != nil {
+			msg = oci.CompactError(err)
+		}
+		return nil, fmt.Errorf("测试未通过:%s", truncateErr(msg))
+	}
+	return s.adoptProbeModel(ctx, &ch, name)
+}
+
+// adoptProbeModel 记录探测验证模型并返回更新后的渠道;
+// 状态不为 ok 时一并置 ok 并复位熔断。
+func (s *AiGatewayService) adoptProbeModel(ctx context.Context, ch *model.AiChannel, name string) (*model.AiChannel, error) {
+	updates := map[string]any{"probe_model": name}
+	if ch.ProbeStatus != "ok" {
+		updates["probe_status"] = "ok"
+		updates["probe_error"] = ""
+		updates["last_probe_at"] = time.Now()
+		updates["fail_count"] = 0
+		updates["disabled_until"] = gorm.Expr("NULL")
+	}
+	if err := s.db.WithContext(ctx).Model(&model.AiChannel{}).Where("id = ?", ch.ID).Updates(updates).Error; err != nil {
+		return nil, err
+	}
+	// 重读用新变量:gorm 扫描 NULL 列到已有值的结构体时会保留旧值
+	var fresh model.AiChannel
+	err := s.db.WithContext(ctx).First(&fresh, ch.ID).Error
+	return &fresh, err
+}
+
 // GatewayModels 聚合启用渠道的可用模型(按名称去重),供 /ai/v1/models;
 // group 非空时仅聚合该分组渠道(与密钥分组路由口径一致)。
 func (s *AiGatewayService) GatewayModels(ctx context.Context, group string) (aiwire.ModelList, error) {
@@ -511,6 +759,9 @@ func (s *AiGatewayService) GatewayModels(ctx context.Context, group string) (aiw
 	if group != "" {
 		q = q.Where("ai_channels.channel_group = ?", group)
 	}
+	if s.FilterDeprecated() {
+		q = q.Where("ai_model_caches.deprecated_at IS NULL")
+	}
 	var rows []model.AiModelCache
 	err := q.Order("ai_model_caches.name ASC").Find(&rows).Error
 	list := aiwire.ModelList{Object: "list", Data: []aiwire.Model{}}
@@ -528,6 +779,40 @@ func (s *AiGatewayService) GatewayModels(ctx context.Context, group string) (aiw
 	return list, nil
 }
 
+// AggregatedModel 是聚合模型目录条目(设置页黑名单添加弹窗用)。
+type AggregatedModel struct {
+	Name       string `json:"name"`
+	Capability string `json:"capability"`
+}
+
+// AggregatedModels 返回启用渠道去重后的模型目录(含能力);空能力归一为 CHAT。
+// 与模型列表口径一致:「过滤弃用」开启时弃用模型不出现在目录中。
+func (s *AiGatewayService) AggregatedModels(ctx context.Context) ([]AggregatedModel, error) {
+	q := s.db.WithContext(ctx).
+		Joins("JOIN ai_channels ON ai_channels.id = ai_model_caches.channel_id AND ai_channels.enabled = ?", true)
+	if s.FilterDeprecated() {
+		q = q.Where("ai_model_caches.deprecated_at IS NULL")
+	}
+	var rows []model.AiModelCache
+	if err := q.Order("ai_model_caches.name ASC").Find(&rows).Error; err != nil {
+		return nil, fmt.Errorf("聚合模型目录: %w", err)
+	}
+	seen := map[string]bool{}
+	out := []AggregatedModel{}
+	for _, r := range rows {
+		if seen[r.Name] {
+			continue
+		}
+		seen[r.Name] = true
+		cap := r.Capability
+		if cap == "" {
+			cap = "CHAT"
+		}
+		out = append(out, AggregatedModel{Name: r.Name, Capability: cap})
+	}
+	return out, nil
+}
+
 // DeprecatingModels 返回 within 窗口内即将退役或即将弃用的在池模型(按名称去重):
 // 退役(TimeOnDemandRetired)才导致不可调用,单独标注;已过弃用日但未到退役日的
 // 模型仍可正常调用,不再反复告警;已过退役日的在同步层剔除,不会出现在池中。

internal/service/aigateway_chat.go

@@ -27,27 +27,27 @@ type aiCandidate struct {
 	modelOcid string
 }
 
-// RespPassthrough 编排一次非流式直通调用:选渠道(priority→加权随机)→ 调用 →
+// routeRetry 统一编排「选渠道(priority→加权随机)→ 调用 → 可重试错误换渠道」,
-// 可重试错误换渠道(整请求上限 3 次)并维护熔断;group 非空时只在同分组渠道内路由。
+// 整请求上限 3 次并维护熔断;group 非空时只在同分组渠道内路由。
-// 上游为 OpenAI-compatible /actions/v1/responses(实测可用,无 Oracle 文档合同)。
+func routeRetry[T any](ctx context.Context, s *AiGatewayService, modelName, group, capability string, once func(*aiCandidate) (T, error)) (T, ChatMeta, error) {
-func (s *AiGatewayService) RespPassthrough(ctx context.Context, raw []byte, modelName, group string) ([]byte, ChatMeta, error) {
+	var zero T
 	meta := ChatMeta{}
 	excluded := map[uint]bool{}
 	var lastErr error
 	for attempt := 0; attempt < 3; attempt++ {
-		cand, err := s.pick(ctx, modelName, group, "CHAT", excluded)
+		cand, err := s.pick(ctx, modelName, group, capability, excluded)
 		if err != nil {
-			return nil, meta, firstErr(lastErr, err)
+			return zero, meta, firstErr(lastErr, err)
 		}
 		meta.ChannelID, meta.ChannelName = cand.ch.ID, cand.ch.Name
-		payload, err := s.passthroughOnce(ctx, cand, raw)
+		out, err := once(cand)
 		if err == nil {
 			s.markSuccess(ctx, cand.ch.ID)
-			return payload, meta, nil
+			return out, meta, nil
 		}
 		retry, penalize := switchable(err)
 		if !retry {
-			return nil, meta, err
+			return zero, meta, err
 		}
 		if penalize {
 			s.markFailure(ctx, cand.ch.ID)
@@ -56,7 +56,15 @@ func (s *AiGatewayService) RespPassthrough(ctx context.Context, raw []byte, mode
 		meta.Retries++
 		lastErr = err
 	}
-	return nil, meta, lastErr
+	return zero, meta, lastErr
+}
+
+// RespPassthrough 编排一次非流式直通调用。
+// 上游为 OpenAI-compatible /actions/v1/responses(实测可用,无 Oracle 文档合同)。
+func (s *AiGatewayService) RespPassthrough(ctx context.Context, raw []byte, modelName, group string) ([]byte, ChatMeta, error) {
+	return routeRetry(ctx, s, modelName, group, "CHAT", func(cand *aiCandidate) ([]byte, error) {
+		return s.passthroughOnce(ctx, cand, raw)
+	})
 }
 
 func (s *AiGatewayService) passthroughOnce(ctx context.Context, cand *aiCandidate, raw []byte) ([]byte, error) {
@@ -64,42 +72,19 @@ func (s *AiGatewayService) passthroughOnce(ctx context.Context, cand *aiCandidat
 	if err != nil {
 		return nil, err
 	}
-	return s.client.GenAiCompatResponses(ctx, cred, cand.ch.Region, raw)
+	return s.client.GenAiCompatResponses(ctx, cred, cand.ch.Region, raw, s.UpstreamWait())
 }
 
 // RespPassthroughStream 编排流式直通:流建立成功即绑定渠道,建立失败按 switchable
 // 换渠道重试;建立后的中断不重试、不计熔断(与 OpenStream 语义一致)。
 func (s *AiGatewayService) RespPassthroughStream(ctx context.Context, raw []byte, modelName, group string) (io.ReadCloser, ChatMeta, error) {
-	meta := ChatMeta{}
+	return routeRetry(ctx, s, modelName, group, "CHAT", func(cand *aiCandidate) (io.ReadCloser, error) {
-	excluded := map[uint]bool{}
-	var lastErr error
-	for attempt := 0; attempt < 3; attempt++ {
-		cand, err := s.pick(ctx, modelName, group, "CHAT", excluded)
-		if err != nil {
-			return nil, meta, firstErr(lastErr, err)
-		}
-		meta.ChannelID, meta.ChannelName = cand.ch.ID, cand.ch.Name
 		cred, err := s.configs.credentialsByID(ctx, cand.ch.OciConfigID)
 		if err != nil {
-			return nil, meta, err
+			return nil, err
 		}
-		stream, err := s.client.GenAiCompatResponsesStream(ctx, cred, cand.ch.Region, raw)
+		return s.client.GenAiCompatResponsesStream(ctx, cred, cand.ch.Region, raw, s.UpstreamWait())
-		if err == nil {
+	})
-			s.markSuccess(ctx, cand.ch.ID)
-			return stream, meta, nil
-		}
-		retry, penalize := switchable(err)
-		if !retry {
-			return nil, meta, err
-		}
-		if penalize {
-			s.markFailure(ctx, cand.ch.ID)
-		}
-		excluded[cand.ch.ID] = true
-		meta.Retries++
-		lastErr = err
-	}
-	return nil, meta, lastErr
 }
 
 // firstErr 在换渠道后仍失败时优先返回上游错误(而非「无渠道」)。
@@ -164,6 +149,9 @@ func (s *AiGatewayService) modelChannels(ctx context.Context, modelName, capabil
 	} else {
 		q = q.Where("capability = ?", capability)
 	}
+	if s.FilterDeprecated() {
+		q = q.Where("deprecated_at IS NULL")
+	}
 	var rows []model.AiModelCache
 	if err := q.Find(&rows).Error; err != nil {
 		return nil, nil, err
@@ -218,34 +206,11 @@ func weightedPick(chs []model.AiChannel) model.AiChannel {
 	return chs[len(chs)-1]
 }
 
-// Embeddings 编排向量化调用:按 EMBEDDING 能力选渠道,可重试错误换渠道(整请求上限 3 次)。
+// Embeddings 编排向量化调用:按 EMBEDDING 能力选渠道,可重试错误换渠道。
 func (s *AiGatewayService) Embeddings(ctx context.Context, req aiwire.EmbeddingsRequest, group string) (*aiwire.EmbeddingsResponse, ChatMeta, error) {
-	meta := ChatMeta{}
+	return routeRetry(ctx, s, req.Model, group, "EMBEDDING", func(cand *aiCandidate) (*aiwire.EmbeddingsResponse, error) {
-	excluded := map[uint]bool{}
+		return s.embedOnce(ctx, cand, req)
-	var lastErr error
+	})
-	for attempt := 0; attempt < 3; attempt++ {
-		cand, err := s.pick(ctx, req.Model, group, "EMBEDDING", excluded)
-		if err != nil {
-			return nil, meta, firstErr(lastErr, err)
-		}
-		meta.ChannelID, meta.ChannelName = cand.ch.ID, cand.ch.Name
-		resp, err := s.embedOnce(ctx, cand, req)
-		if err == nil {
-			s.markSuccess(ctx, cand.ch.ID)
-			return resp, meta, nil
-		}
-		retry, penalize := switchable(err)
-		if !retry {
-			return nil, meta, err
-		}
-		if penalize {
-			s.markFailure(ctx, cand.ch.ID)
-		}
-		excluded[cand.ch.ID] = true
-		meta.Retries++
-		lastErr = err
-	}
-	return nil, meta, lastErr
 }
 
 // embedOnce 调用渠道向量化并装配 OpenAI 形态响应。

internal/service/aigateway_extras.go

@@ -0,0 +1,284 @@
+package service
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+	"time"
+
+	"oci-portal/internal/aiwire"
+	"oci-portal/internal/model"
+	"oci-portal/internal/oci"
+)
+
+// moderationsMaxInputs 限制单次审核条数,防止批量滥用拖垮渠道配额。
+const moderationsMaxInputs = 8
+
+// SpeechBodyNormalize 校验并规范化 TTS 请求体:model / input 必填;
+// xAI 上游把 language 当必填(实测缺失返回 422),缺省注入 "auto"。
+// 其余字段(voice / response_format / extra_body 平铺项)原样保留。
+func SpeechBodyNormalize(raw []byte) (string, []byte, error) {
+	dec := json.NewDecoder(strings.NewReader(string(raw)))
+	dec.UseNumber()
+	var body map[string]any
+	if err := dec.Decode(&body); err != nil {
+		return "", nil, fmt.Errorf("解析请求体: %w", err)
+	}
+	modelName, _ := body["model"].(string)
+	input, _ := body["input"].(string)
+	if strings.TrimSpace(modelName) == "" || strings.TrimSpace(input) == "" {
+		return "", nil, fmt.Errorf("model 与 input 不能为空")
+	}
+	if lang, ok := body["language"].(string); !ok || strings.TrimSpace(lang) == "" {
+		body["language"] = "auto"
+	}
+	out, err := json.Marshal(body)
+	if err != nil {
+		return "", nil, fmt.Errorf("重组请求体: %w", err)
+	}
+	return modelName, out, nil
+}
+
+// ttsDefaultModel 是 /ai/v1/tts 缺省注入的模型(xAI 官方格式无 model 字段)。
+const ttsDefaultModel = "xai.grok-tts"
+
+// TtsBodyConvert 把 xAI 官方 TTS 格式转换为上游 OpenAI 兼容 audio/speech 形态:
+// text→input、voice_id→voice,text 与 language 必填(对齐 xAI 官方);
+// model 为网关扩展字段,缺省注入 ttsDefaultModel;其余字段原样保留。
+func TtsBodyConvert(raw []byte) (string, []byte, error) {
+	dec := json.NewDecoder(strings.NewReader(string(raw)))
+	dec.UseNumber()
+	var body map[string]any
+	if err := dec.Decode(&body); err != nil {
+		return "", nil, fmt.Errorf("解析请求体: %w", err)
+	}
+	text, _ := body["text"].(string)
+	language, _ := body["language"].(string)
+	if strings.TrimSpace(text) == "" || strings.TrimSpace(language) == "" {
+		return "", nil, fmt.Errorf("text 与 language 不能为空")
+	}
+	modelName, _ := body["model"].(string)
+	if strings.TrimSpace(modelName) == "" {
+		modelName = ttsDefaultModel
+		body["model"] = modelName
+	}
+	delete(body, "text")
+	body["input"] = text
+	if voice, ok := body["voice_id"].(string); ok && strings.TrimSpace(voice) != "" {
+		body["voice"] = voice
+	}
+	delete(body, "voice_id")
+	out, err := json.Marshal(body)
+	if err != nil {
+		return "", nil, fmt.Errorf("重组请求体: %w", err)
+	}
+	return modelName, out, nil
+}
+
+// Speech 编排 TTS 调用:按 TTS 能力选渠道,可重试错误换渠道(上限 3 次)。
+func (s *AiGatewayService) Speech(ctx context.Context, modelName string, body []byte, group string) ([]byte, string, ChatMeta, error) {
+	meta := ChatMeta{}
+	excluded := map[uint]bool{}
+	var lastErr error
+	for attempt := 0; attempt < 3; attempt++ {
+		cand, err := s.pick(ctx, modelName, group, "TTS", excluded)
+		if err != nil {
+			return nil, "", meta, firstErr(lastErr, err)
+		}
+		meta.ChannelID, meta.ChannelName = cand.ch.ID, cand.ch.Name
+		cred, err := s.configs.credentialsByID(ctx, cand.ch.OciConfigID)
+		if err != nil {
+			return nil, "", meta, err
+		}
+		audio, contentType, err := s.client.GenAiCompatSpeech(ctx, cred, cand.ch.Region, body)
+		if err == nil {
+			s.markSuccess(ctx, cand.ch.ID)
+			return audio, contentType, meta, nil
+		}
+		if done := s.retryStep(ctx, cand.ch.ID, err, excluded, &meta, &lastErr); done {
+			return nil, "", meta, err
+		}
+	}
+	return nil, "", meta, lastErr
+}
+
+// Rerank 编排文档重排:按 RERANK 能力选渠道,装配 Jina 风格响应。
+func (s *AiGatewayService) Rerank(ctx context.Context, req aiwire.RerankRequest, group string) (*aiwire.RerankResponse, ChatMeta, error) {
+	meta := ChatMeta{}
+	excluded := map[uint]bool{}
+	var lastErr error
+	for attempt := 0; attempt < 3; attempt++ {
+		cand, err := s.pick(ctx, req.Model, group, "RERANK", excluded)
+		if err != nil {
+			return nil, meta, firstErr(lastErr, err)
+		}
+		meta.ChannelID, meta.ChannelName = cand.ch.ID, cand.ch.Name
+		cred, err := s.configs.credentialsByID(ctx, cand.ch.OciConfigID)
+		if err != nil {
+			return nil, meta, err
+		}
+		ranks, err := s.client.GenAiRerank(ctx, cred, cand.ch.Region, cand.modelOcid, req.Query, req.Documents, req.TopN)
+		if err == nil {
+			s.markSuccess(ctx, cand.ch.ID)
+			return rerankResponse(req, ranks), meta, nil
+		}
+		if done := s.retryStep(ctx, cand.ch.ID, err, excluded, &meta, &lastErr); done {
+			return nil, meta, err
+		}
+	}
+	return nil, meta, lastErr
+}
+
+// retryStep 统一处理换渠道重试:不可重试返回 true 终止,可重试记罚并排除渠道。
+func (s *AiGatewayService) retryStep(ctx context.Context, chID uint, err error, excluded map[uint]bool, meta *ChatMeta, lastErr *error) bool {
+	retry, penalize := switchable(err)
+	if !retry {
+		return true
+	}
+	if penalize {
+		s.markFailure(ctx, chID)
+	}
+	excluded[chID] = true
+	meta.Retries++
+	*lastErr = err
+	return false
+}
+
+// rerankResponse 把上游排序结果装配为对外响应;return_documents 时回填原文。
+func rerankResponse(req aiwire.RerankRequest, ranks []oci.RerankRank) *aiwire.RerankResponse {
+	out := &aiwire.RerankResponse{Model: req.Model, Results: make([]aiwire.RerankResult, 0, len(ranks))}
+	withDoc := req.ReturnDocuments != nil && *req.ReturnDocuments
+	for _, r := range ranks {
+		if r.Index < 0 || r.Index >= len(req.Documents) {
+			continue
+		}
+		item := aiwire.RerankResult{Index: r.Index, RelevanceScore: r.Score}
+		if withDoc {
+			item.Document = &aiwire.RerankDocument{Text: req.Documents[r.Index]}
+		}
+		out.Results = append(out.Results, item)
+	}
+	return out
+}
+
+// ModerationInputs 解析 moderations 的 input 字段:string 或 []string,
+// 条数与空值校验(上限 moderationsMaxInputs)。
+func ModerationInputs(raw json.RawMessage) ([]string, error) {
+	var single string
+	if err := json.Unmarshal(raw, &single); err == nil {
+		if strings.TrimSpace(single) == "" {
+			return nil, fmt.Errorf("input 不能为空")
+		}
+		return []string{single}, nil
+	}
+	var many []string
+	if err := json.Unmarshal(raw, &many); err != nil {
+		return nil, fmt.Errorf("input 需为字符串或字符串数组")
+	}
+	if len(many) == 0 || len(many) > moderationsMaxInputs {
+		return nil, fmt.Errorf("input 条数需在 1~%d 之间", moderationsMaxInputs)
+	}
+	for _, item := range many {
+		if strings.TrimSpace(item) == "" {
+			return nil, fmt.Errorf("input 含空条目")
+		}
+	}
+	return many, nil
+}
+
+// Moderations 编排内容审核:guardrails 为服务级 API 无模型维度,
+// 按分组选启用渠道(整批同渠道),可重试错误换渠道(上限 3 次)。
+func (s *AiGatewayService) Moderations(ctx context.Context, id string, inputs []string, group string) (*aiwire.ModerationsResponse, ChatMeta, error) {
+	meta := ChatMeta{}
+	excluded := map[uint]bool{}
+	var lastErr error
+	for attempt := 0; attempt < 3; attempt++ {
+		ch, err := s.pickGuardChannel(ctx, group, excluded)
+		if err != nil {
+			return nil, meta, firstErr(lastErr, err)
+		}
+		meta.ChannelID, meta.ChannelName = ch.ID, ch.Name
+		resp, err := s.moderateOnce(ctx, ch, id, inputs)
+		if err == nil {
+			s.markSuccess(ctx, ch.ID)
+			return resp, meta, nil
+		}
+		if done := s.retryStep(ctx, ch.ID, err, excluded, &meta, &lastErr); done {
+			return nil, meta, err
+		}
+	}
+	return nil, meta, lastErr
+}
+
+// pickGuardChannel 按分组挑一个启用且未熔断的渠道(权重加成,不查模型缓存)。
+func (s *AiGatewayService) pickGuardChannel(ctx context.Context, group string, excluded map[uint]bool) (model.AiChannel, error) {
+	q := s.db.WithContext(ctx).Where("enabled = ?", true)
+	if group != "" {
+		q = q.Where("channel_group = ?", group)
+	}
+	var channels []model.AiChannel
+	if err := q.Find(&channels).Error; err != nil {
+		return model.AiChannel{}, err
+	}
+	now := time.Now()
+	avail := channels[:0]
+	for _, ch := range channels {
+		if excluded[ch.ID] || (ch.DisabledUntil != nil && ch.DisabledUntil.After(now)) {
+			continue
+		}
+		avail = append(avail, ch)
+	}
+	if len(avail) == 0 {
+		return model.AiChannel{}, ErrAiNoChannel
+	}
+	return weightedPick(topPriority(avail)), nil
+}
+
+// moderateOnce 在单渠道上逐条审核并装配 OpenAI moderations 外壳。
+func (s *AiGatewayService) moderateOnce(ctx context.Context, ch model.AiChannel, id string, inputs []string) (*aiwire.ModerationsResponse, error) {
+	cred, err := s.configs.credentialsByID(ctx, ch.OciConfigID)
+	if err != nil {
+		return nil, err
+	}
+	out := &aiwire.ModerationsResponse{ID: id, Model: "oci-guardrails",
+		Results: make([]aiwire.ModerationResult, 0, len(inputs))}
+	for _, text := range inputs {
+		outcome, err := s.client.GenAiApplyGuardrails(ctx, cred, ch.Region, text)
+		if err != nil {
+			return nil, err
+		}
+		out.Results = append(out.Results, moderationResult(outcome))
+	}
+	return out, nil
+}
+
+// moderationFlagThreshold 是判定违规的得分阈值(上游 CM / PI 为二值得分)。
+const moderationFlagThreshold = 0.5
+
+// moderationResult 把 guardrails 结果映射为 OpenAI moderations 条目:
+// flagged 由内容审核与提示注入判定,PII 命中只作扩展信息不参与 flagged。
+func moderationResult(outcome *oci.GuardrailsOutcome) aiwire.ModerationResult {
+	res := aiwire.ModerationResult{Categories: map[string]bool{}, CategoryScores: map[string]float64{}}
+	for _, cat := range outcome.Categories {
+		key := strings.ToLower(cat.Name)
+		res.Categories[key] = cat.Score >= moderationFlagThreshold
+		res.CategoryScores[key] = cat.Score
+		if res.Categories[key] {
+			res.Flagged = true
+		}
+	}
+	if outcome.PromptInjectionScore != nil {
+		hit := *outcome.PromptInjectionScore >= moderationFlagThreshold
+		res.Categories["prompt_injection"] = hit
+		res.CategoryScores["prompt_injection"] = *outcome.PromptInjectionScore
+		if hit {
+			res.Flagged = true
+		}
+	}
+	for _, p := range outcome.Pii {
+		res.Pii = append(res.Pii, aiwire.ModerationPii{Text: p.Text, Label: p.Label,
+			Score: p.Score, Offset: p.Offset, Length: p.Length})
+	}
+	return res
+}

internal/service/aigateway_extras_test.go

@@ -0,0 +1,222 @@
+package service
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+
+	"oci-portal/internal/aiwire"
+	"oci-portal/internal/model"
+	"oci-portal/internal/oci"
+)
+
+// TestSpeechBodyNormalize 断言 TTS 请求体校验与 language 缺省注入。
+func TestSpeechBodyNormalize(t *testing.T) {
+	tests := []struct {
+		name     string
+		raw      string
+		wantErr  bool
+		wantLang string
+	}{
+		{"缺 model 拒绝", `{"input":"你好"}`, true, ""},
+		{"缺 input 拒绝", `{"model":"xai.grok-tts"}`, true, ""},
+		{"language 缺省注入 auto", `{"model":"xai.grok-tts","input":"你好","voice":"ara"}`, false, "auto"},
+		{"language 已有保留", `{"model":"xai.grok-tts","input":"你好","language":"zh"}`, false, "zh"},
+		{"非 JSON 拒绝", `<html>`, true, ""},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			modelName, body, err := SpeechBodyNormalize([]byte(tt.raw))
+			if (err != nil) != tt.wantErr {
+				t.Fatalf("err = %v, wantErr %v", err, tt.wantErr)
+			}
+			if err != nil {
+				return
+			}
+			var out map[string]any
+			_ = json.Unmarshal(body, &out)
+			if modelName != "xai.grok-tts" || out["language"] != tt.wantLang {
+				t.Fatalf("model=%s language=%v, want %s", modelName, out["language"], tt.wantLang)
+			}
+		})
+	}
+}
+
+// TestTtsBodyConvert 断言 xAI 官方 TTS 格式到 OpenAI 兼容形态的转换。
+func TestTtsBodyConvert(t *testing.T) {
+	tests := []struct {
+		name      string
+		raw       string
+		wantErr   bool
+		wantModel string
+	}{
+		{"缺 text 拒绝", `{"language":"zh"}`, true, ""},
+		{"缺 language 拒绝", `{"text":"你好"}`, true, ""},
+		{"缺省注入默认模型", `{"text":"你好","language":"zh"}`, false, "xai.grok-tts"},
+		{"model 扩展字段可覆盖", `{"model":"xai.other-tts","text":"你好","language":"auto"}`, false, "xai.other-tts"},
+		{"非 JSON 拒绝", `<html>`, true, ""},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			modelName, _, err := TtsBodyConvert([]byte(tt.raw))
+			if (err != nil) != tt.wantErr {
+				t.Fatalf("err = %v, wantErr %v", err, tt.wantErr)
+			}
+			if err != nil {
+				return
+			}
+			if modelName != tt.wantModel {
+				t.Fatalf("model = %s, want %s", modelName, tt.wantModel)
+			}
+		})
+	}
+}
+
+// TestTtsBodyConvertMapping 断言字段映射与未知字段保留。
+func TestTtsBodyConvertMapping(t *testing.T) {
+	raw := `{"text":"你好","language":"zh","voice_id":"ara","speed":1.2,` +
+		`"output_format":{"codec":"mp3","sample_rate":44100}}`
+	_, body, err := TtsBodyConvert([]byte(raw))
+	if err != nil {
+		t.Fatalf("err = %v", err)
+	}
+	var out map[string]any
+	_ = json.Unmarshal(body, &out)
+	if out["input"] != "你好" || out["voice"] != "ara" {
+		t.Fatalf("input/voice 映射错误: %v", out)
+	}
+	if _, ok := out["text"]; ok {
+		t.Fatal("text 字段应被移除")
+	}
+	if _, ok := out["voice_id"]; ok {
+		t.Fatal("voice_id 字段应被移除")
+	}
+	of, _ := out["output_format"].(map[string]any)
+	if of == nil || of["codec"] != "mp3" {
+		t.Fatalf("output_format 应原样保留: %v", out["output_format"])
+	}
+	if out["language"] != "zh" || out["speed"] == nil {
+		t.Fatalf("language/speed 应保留: %v", out)
+	}
+}
+
+// TestModerationInputs 断言 input 的 string / []string 解析与边界校验。
+func TestModerationInputs(t *testing.T) {
+	tests := []struct {
+		name    string
+		raw     string
+		wantN   int
+		wantErr bool
+	}{
+		{"单字符串", `"hello"`, 1, false},
+		{"数组", `["a","b"]`, 2, false},
+		{"空字符串拒绝", `""`, 0, true},
+		{"空数组拒绝", `[]`, 0, true},
+		{"含空条目拒绝", `["a",""]`, 0, true},
+		{"超上限拒绝", `["1","2","3","4","5","6","7","8","9"]`, 0, true},
+		{"非法类型拒绝", `{"x":1}`, 0, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := ModerationInputs(json.RawMessage(tt.raw))
+			if (err != nil) != tt.wantErr || len(got) != tt.wantN {
+				t.Fatalf("got %v (err=%v), want n=%d wantErr=%v", got, err, tt.wantN, tt.wantErr)
+			}
+		})
+	}
+}
+
+// TestModerationResultMapping 断言 guardrails 结果到 OpenAI 外壳的映射与 flagged 判定。
+func TestModerationResultMapping(t *testing.T) {
+	one := 1.0
+	zero := 0.0
+	tests := []struct {
+		name        string
+		outcome     oci.GuardrailsOutcome
+		wantFlagged bool
+		wantPii     int
+	}{
+		{"内容审核命中", oci.GuardrailsOutcome{Categories: []oci.GuardrailCategory{{Name: "OVERALL", Score: 1}}}, true, 0},
+		{"提示注入命中", oci.GuardrailsOutcome{PromptInjectionScore: &one}, true, 0},
+		{"仅 PII 不 flag", oci.GuardrailsOutcome{Categories: []oci.GuardrailCategory{{Name: "OVERALL", Score: 0}},
+			PromptInjectionScore: &zero, Pii: []oci.GuardrailPiiHit{{Text: "Jane", Label: "PERSON", Score: 0.99}}}, false, 1},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			res := moderationResult(&tt.outcome)
+			if res.Flagged != tt.wantFlagged || len(res.Pii) != tt.wantPii {
+				t.Fatalf("res = %+v, want flagged=%v pii=%d", res, tt.wantFlagged, tt.wantPii)
+			}
+		})
+	}
+}
+
+// TestAiRerank 断言重排编排:能力路由、top_n 透传、return_documents 回填与越界防御。
+func TestAiRerank(t *testing.T) {
+	client := &gatewayStubClient{
+		fakeClient:  &fakeClient{tenancy: oci.TenancyInfo{Name: "t"}},
+		rerankRanks: []oci.RerankRank{{Index: 1, Score: 0.9}, {Index: 0, Score: 0.4}, {Index: 9, Score: 0.1}},
+	}
+	gw, svc := newTestGateway(t, client)
+	cfg := importAliveConfig(t, svc)
+	ch := seedChannel(t, gw, cfg.ID, "us-chicago-1", 1, 1)
+	gw.db.Create(&model.AiModelCache{ChannelID: ch.ID, ModelOcid: "ocid1..rr", Name: "cohere.rerank-v4.0-fast",
+		Vendor: "cohere", Capability: "RERANK", SyncedAt: time.Now()})
+	ctx := context.Background()
+	yes := true
+	req := aiwire.RerankRequest{Model: "cohere.rerank-v4.0-fast", Query: "q", Documents: []string{"d0", "d1"}, ReturnDocuments: &yes}
+	resp, _, err := gw.Rerank(ctx, req, "")
+	if err != nil || len(resp.Results) != 2 {
+		t.Fatalf("Rerank = %+v, %v(越界 index 应被丢弃)", resp, err)
+	}
+	if resp.Results[0].Index != 1 || resp.Results[0].Document == nil || resp.Results[0].Document.Text != "d1" {
+		t.Fatalf("results[0] = %+v", resp.Results[0])
+	}
+	// 对话模型名打 rerank:能力不匹配 → 未知模型
+	if _, _, err := gw.Rerank(ctx, aiwire.RerankRequest{Model: "meta.llama-3.3-70b-instruct", Query: "q", Documents: []string{"d"}}, ""); !errors.Is(err, ErrAiUnknownModel) {
+		t.Errorf("chat 模型走 rerank err = %v, want ErrAiUnknownModel", err)
+	}
+}
+
+// TestAiSpeech 断言 TTS 编排走 TTS 能力路由并透传音频与 Content-Type。
+func TestAiSpeech(t *testing.T) {
+	client := &gatewayStubClient{
+		fakeClient:  &fakeClient{tenancy: oci.TenancyInfo{Name: "t"}},
+		speechAudio: []byte{0xFF, 0xF3}, speechCT: "audio/mpeg",
+	}
+	gw, svc := newTestGateway(t, client)
+	cfg := importAliveConfig(t, svc)
+	ch := seedChannel(t, gw, cfg.ID, "us-chicago-1", 1, 1)
+	gw.db.Create(&model.AiModelCache{ChannelID: ch.ID, ModelOcid: "ocid1..tts", Name: "xai.grok-tts",
+		Vendor: "xai", Capability: "TTS", SyncedAt: time.Now()})
+	audio, ct, _, err := gw.Speech(context.Background(), "xai.grok-tts", []byte(`{"model":"xai.grok-tts","input":"你好","language":"auto"}`), "")
+	if err != nil || ct != "audio/mpeg" || len(audio) != 2 {
+		t.Fatalf("Speech = %d bytes, ct=%s, %v", len(audio), ct, err)
+	}
+}
+
+// TestAiModerations 断言审核编排:无模型维度按分组选渠道,多条输入逐条聚合。
+func TestAiModerations(t *testing.T) {
+	one := 1.0
+	client := &gatewayStubClient{
+		fakeClient:   &fakeClient{tenancy: oci.TenancyInfo{Name: "t"}},
+		guardOutcome: &oci.GuardrailsOutcome{Categories: []oci.GuardrailCategory{{Name: "OVERALL", Score: 1}}, PromptInjectionScore: &one},
+	}
+	gw, svc := newTestGateway(t, client)
+	cfg := importAliveConfig(t, svc)
+	seedChannel(t, gw, cfg.ID, "us-chicago-1", 1, 1)
+	resp, meta, err := gw.Moderations(context.Background(), "modr_test", []string{"a", "b"}, "")
+	if err != nil || len(resp.Results) != 2 || !resp.Results[0].Flagged || resp.ID != "modr_test" {
+		t.Fatalf("Moderations = %+v, meta=%+v, %v", resp, meta, err)
+	}
+	if !strings.Contains(resp.Model, "guardrails") {
+		t.Errorf("model = %s", resp.Model)
+	}
+	// 分组不匹配 → 无可用渠道
+	if _, _, err := gw.Moderations(context.Background(), "modr_x", []string{"a"}, "ghost-group"); !errors.Is(err, ErrAiNoChannel) {
+		t.Errorf("ghost 分组 err = %v, want ErrAiNoChannel", err)
+	}
+}

internal/service/aigateway_test.go

@@ -61,9 +61,29 @@ type gatewayStubClient struct {
 	passErrs    []error
 	passCalls   int
 	passRegions []string
+
+	speechAudio  []byte
+	speechCT     string
+	speechErr    error
+	rerankRanks  []oci.RerankRank
+	rerankErr    error
+	guardOutcome *oci.GuardrailsOutcome
+	guardErr     error
 }
 
-func (f *gatewayStubClient) GenAiCompatResponses(ctx context.Context, cred oci.Credentials, region string, body []byte) ([]byte, error) {
+func (f *gatewayStubClient) GenAiCompatSpeech(ctx context.Context, cred oci.Credentials, region string, body []byte) ([]byte, string, error) {
+	return f.speechAudio, f.speechCT, f.speechErr
+}
+
+func (f *gatewayStubClient) GenAiRerank(ctx context.Context, cred oci.Credentials, region, modelOcid, query string, documents []string, topN *int) ([]oci.RerankRank, error) {
+	return f.rerankRanks, f.rerankErr
+}
+
+func (f *gatewayStubClient) GenAiApplyGuardrails(ctx context.Context, cred oci.Credentials, region, text string) (*oci.GuardrailsOutcome, error) {
+	return f.guardOutcome, f.guardErr
+}
+
+func (f *gatewayStubClient) GenAiCompatResponses(ctx context.Context, cred oci.Credentials, region string, body []byte, wait time.Duration) ([]byte, error) {
 	f.passCalls++
 	f.passRegions = append(f.passRegions, region)
 	if len(f.passErrs) > 0 {
@@ -76,7 +96,7 @@ func (f *gatewayStubClient) GenAiCompatResponses(ctx context.Context, cred oci.C
 	return f.passPayload, nil
 }
 
-func (f *gatewayStubClient) GenAiCompatResponsesStream(ctx context.Context, cred oci.Credentials, region string, body []byte) (io.ReadCloser, error) {
+func (f *gatewayStubClient) GenAiCompatResponsesStream(ctx context.Context, cred oci.Credentials, region string, body []byte, wait time.Duration) (io.ReadCloser, error) {
 	f.passCalls++
 	f.passRegions = append(f.passRegions, region)
 	if len(f.passErrs) > 0 {
@@ -116,7 +136,7 @@ func (f *gatewayStubClient) GenAiProbeChat(ctx context.Context, cred oci.Credent
 func newTestGateway(t *testing.T, client oci.Client) (*AiGatewayService, *OciConfigService) {
 	t.Helper()
 	svc := newTestService(t, client)
-	if err := svc.db.AutoMigrate(&model.AiKey{}, &model.AiChannel{}, &model.AiModelCache{}, &model.AiModelBlacklist{}, &model.AiCallLog{}); err != nil {
+	if err := svc.db.AutoMigrate(&model.Setting{}, &model.AiKey{}, &model.AiChannel{}, &model.AiModelCache{}, &model.AiModelBlacklist{}, &model.AiCallLog{}); err != nil {
 		t.Fatalf("auto migrate ai tables: %v", err)
 	}
 	return NewAiGatewayService(svc.db, svc, client), svc
@@ -208,6 +228,46 @@ func seedChannel(t *testing.T, gw *AiGatewayService, cfgID uint, region string,
 	return ch
 }
 
+// TestFilterDeprecatedModels 断言「过滤弃用模型」开关对列表 / 路由的过滤与持久化。
+func TestFilterDeprecatedModels(t *testing.T) {
+	gw, svc := newTestGateway(t, &gatewayStubClient{fakeClient: &fakeClient{tenancy: oci.TenancyInfo{Name: "t"}}})
+	cfg := importAliveConfig(t, svc)
+	ch := seedChannel(t, gw, cfg.ID, "eu-frankfurt-1", 1, 1)
+	dep := time.Now().Add(-24 * time.Hour)
+	old := &model.AiModelCache{ChannelID: ch.ID, ModelOcid: "ocid1..dep", Name: "meta.llama-old",
+		Vendor: "meta", SyncedAt: time.Now(), DeprecatedAt: &dep}
+	if err := gw.db.Create(old).Error; err != nil {
+		t.Fatalf("seed deprecated cache: %v", err)
+	}
+	ctx := context.Background()
+
+	list, _ := gw.GatewayModels(ctx, "")
+	if len(list.Data) != 2 {
+		t.Fatalf("开关关:应含弃用模型,got %d", len(list.Data))
+	}
+	if err := gw.SetFilterDeprecated(ctx, true); err != nil {
+		t.Fatalf("SetFilterDeprecated: %v", err)
+	}
+	list, _ = gw.GatewayModels(ctx, "")
+	if len(list.Data) != 1 || list.Data[0].ID != "meta.llama-3.3-70b-instruct" {
+		t.Fatalf("开关开:弃用模型应被过滤,got %+v", list.Data)
+	}
+	if _, err := gw.pick(ctx, "meta.llama-old", "", "CHAT", map[uint]bool{}); !errors.Is(err, ErrAiUnknownModel) {
+		t.Errorf("开关开:弃用模型路由应不可达,err = %v", err)
+	}
+	// 持久化:重建 service 后开关仍生效
+	gw2 := NewAiGatewayService(gw.db, svc, &gatewayStubClient{})
+	if !gw2.FilterDeprecated() {
+		t.Error("重建后开关状态应保持开启")
+	}
+	if err := gw.SetFilterDeprecated(ctx, false); err != nil {
+		t.Fatalf("关闭开关: %v", err)
+	}
+	if list, _ = gw.GatewayModels(ctx, ""); len(list.Data) != 2 {
+		t.Errorf("开关关:弃用模型应恢复,got %d", len(list.Data))
+	}
+}
+
 func TestPickPriorityAndBreaker(t *testing.T) {
 	gw, svc := newTestGateway(t, &gatewayStubClient{fakeClient: &fakeClient{tenancy: oci.TenancyInfo{Name: "t"}}})
 	cfg := importAliveConfig(t, svc)
@@ -393,7 +453,7 @@ func TestProbeCandidates(t *testing.T) {
 		{Ocid: "o3", Name: "meta.llama-3.3-70b-instruct"},
 		{Ocid: "o4", Name: "google.gemini-2.5-flash"},
 	}
-	got := probeCandidates(models)
+	got := probeCandidates("", models)
 	if len(got) != 3 || got[0].Name != "meta.llama-3.3-70b-instruct" || got[1].Name != "google.gemini-2.5-flash" {
 		t.Errorf("候选排序 = %+v", got)
 	}
@@ -413,7 +473,7 @@ func TestProbeCandidatesVendorDiversity(t *testing.T) {
 		{Ocid: "c1", Name: "cohere.command-a-03-2025"},
 		{Ocid: "g1", Name: "xai.grok-4"},
 	}
-	got := probeCandidates(models)
+	got := probeCandidates("", models)
 	if len(got) != 5 || got[0].Name != "meta.llama-3-70b-instruct" {
 		t.Fatalf("上限内全量返回且最高分居首: %+v", got)
 	}
@@ -429,11 +489,38 @@ func TestProbeCandidatesVendorDiversity(t *testing.T) {
 	for i := 0; i < 12; i++ {
 		many = append(many, oci.GenAiModel{Ocid: fmt.Sprintf("m%d", i), Name: fmt.Sprintf("meta.llama-%d", i)})
 	}
-	if capped := probeCandidates(many); len(capped) != probeCandidateCap {
+	if capped := probeCandidates("", many); len(capped) != probeCandidateCap {
 		t.Errorf("候选应截断到 %d: got %d", probeCandidateCap, len(capped))
 	}
 }
 
+// TestProbeCandidatesPinsProbeModel 断言探测验证模型置首位且不占常规候选逻辑。
+func TestProbeCandidatesPinsProbeModel(t *testing.T) {
+	models := []oci.GenAiModel{
+		{Ocid: "o2", Name: "cohere.command-r-plus"},
+		{Ocid: "o3", Name: "meta.llama-3.3-70b-instruct"},
+		{Ocid: "o4", Name: "xai.grok-4"},
+	}
+	tests := []struct {
+		name       string
+		probeModel string
+		wantFirst  string
+		wantLen    int
+	}{
+		{"验证模型置首位", "xai.grok-4", "xai.grok-4", 3},
+		{"未设置走常规排序", "", "meta.llama-3.3-70b-instruct", 3},
+		{"验证模型已不在缓存则忽略", "gone.model", "meta.llama-3.3-70b-instruct", 3},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := probeCandidates(tt.probeModel, models)
+			if len(got) != tt.wantLen || got[0].Name != tt.wantFirst {
+				t.Errorf("probeCandidates(%q) = %+v, want first %q", tt.probeModel, got, tt.wantFirst)
+			}
+		})
+	}
+}
+
 // entityNotFoundErr 模拟「实体不存在」404(模型在区域内无按需供给)。
 func entityNotFoundErr() stubServiceError {
 	return stubServiceError{status: 404,
@@ -500,6 +587,128 @@ func TestProbeAuth404StillNoQuota(t *testing.T) {
 	}
 }
 
+// TestChannelModelsExcludeBlacklist 断言模型列表与数量统计对黑名单做查询层兜底过滤。
+func TestChannelModelsExcludeBlacklist(t *testing.T) {
+	gw, svc := newTestGateway(t, &gatewayStubClient{fakeClient: &fakeClient{tenancy: oci.TenancyInfo{Name: "t"}}})
+	cfg := importAliveConfig(t, svc)
+	ch := seedChannel(t, gw, cfg.ID, "eu-frankfurt-1", 1, 1)
+	ctx := context.Background()
+
+	// 直插黑名单行但保留缓存,模拟脏数据 / 并发窗口
+	gw.db.Create(&model.AiModelBlacklist{Name: "meta.llama-3.3-70b-instruct"})
+	rows, err := gw.ChannelModels(ctx, ch.ID)
+	if err != nil || len(rows) != 0 {
+		t.Errorf("黑名单模型应被过滤: %+v, %v", rows, err)
+	}
+	chs, err := gw.Channels(ctx)
+	if err != nil || len(chs) != 1 || chs[0].ModelCount != 0 {
+		t.Errorf("模型数量统计应剔除黑名单: %+v, %v", chs, err)
+	}
+}
+
+// TestChannelModelsFilterDeprecated 断言「过滤弃用模型」开关同样作用于
+// 渠道模型列表与数量统计(数据保留,展示口径过滤)。
+func TestChannelModelsFilterDeprecated(t *testing.T) {
+	gw, svc := newTestGateway(t, &gatewayStubClient{fakeClient: &fakeClient{tenancy: oci.TenancyInfo{Name: "t"}}})
+	cfg := importAliveConfig(t, svc)
+	ch := seedChannel(t, gw, cfg.ID, "eu-frankfurt-1", 1, 1)
+	dep := time.Now().Add(-24 * time.Hour)
+	gw.db.Create(&model.AiModelCache{ChannelID: ch.ID, ModelOcid: "ocid1..dep", Name: "xai.grok-3",
+		Vendor: "xai", SyncedAt: time.Now(), DeprecatedAt: &dep})
+	ctx := context.Background()
+
+	rows, _ := gw.ChannelModels(ctx, ch.ID)
+	if len(rows) != 2 {
+		t.Fatalf("开关关:弃用模型应在列,got %d", len(rows))
+	}
+	if err := gw.SetFilterDeprecated(ctx, true); err != nil {
+		t.Fatalf("SetFilterDeprecated: %v", err)
+	}
+	rows, _ = gw.ChannelModels(ctx, ch.ID)
+	if len(rows) != 1 || rows[0].Name != "meta.llama-3.3-70b-instruct" {
+		t.Errorf("开关开:弃用模型应被过滤,got %+v", rows)
+	}
+	chs, _ := gw.Channels(ctx)
+	if len(chs) != 1 || chs[0].ModelCount != 1 {
+		t.Errorf("开关开:数量统计应同口径,got %+v", chs)
+	}
+}
+
+// TestProbe403ContinuesToNextCandidate 断言模型级 403 不再武断定论渠道无配额:
+// 后续候选成功 → ok;全部候选鉴权拒绝 → 仍 no_quota。
+func TestProbe403ContinuesToNextCandidate(t *testing.T) {
+	deny := probeResult{403, stubServiceError{status: 403, msg: "NotAuthorizedOrNotFound"}}
+	tests := []struct {
+		name       string
+		seq        []probeResult
+		wantStatus string
+	}{
+		{"403 后换候选成功", []probeResult{deny, {200, nil}}, "ok"},
+		{"403 后换候选限流也算可用", []probeResult{deny, {429, stubServiceError{status: 429}}}, "ok"},
+		{"全部候选 403", []probeResult{deny, deny}, "no_quota"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			client := &gatewayStubClient{
+				fakeClient: &fakeClient{tenancy: oci.TenancyInfo{Name: "t"}},
+				models: []oci.GenAiModel{
+					{Ocid: "m1", Name: "meta.llama-3.3-70b-instruct", Vendor: "meta"},
+					{Ocid: "m2", Name: "cohere.command-a-03-2025", Vendor: "cohere"},
+				},
+				probeSeq: tt.seq,
+			}
+			gw, svc := newTestGateway(t, client)
+			cfg := importAliveConfig(t, svc)
+			ctx := context.Background()
+
+			ch, _ := gw.CreateChannel(ctx, ChannelInput{OciConfigID: cfg.ID, Region: "eu-frankfurt-1"})
+			probed, err := gw.ProbeChannel(ctx, ch.ID)
+			if err != nil || probed.ProbeStatus != tt.wantStatus {
+				t.Fatalf("ProbeChannel = %+v, %v, want %q", probed, err, tt.wantStatus)
+			}
+		})
+	}
+}
+
+// TestChannelModelTest 断言单模型试调:通过时写探测验证模型并翻转状态,失败不动。
+func TestChannelModelTest(t *testing.T) {
+	client := &gatewayStubClient{fakeClient: &fakeClient{tenancy: oci.TenancyInfo{Name: "t"}}}
+	gw, svc := newTestGateway(t, client)
+	cfg := importAliveConfig(t, svc)
+	ch := seedChannel(t, gw, cfg.ID, "eu-frankfurt-1", 1, 1)
+	gw.db.Model(ch).Updates(map[string]any{"probe_status": "no_quota", "probe_error": "旧错误", "fail_count": 6})
+	ctx := context.Background()
+
+	if _, err := gw.TestChannelModel(ctx, ch.ID, "not.exists"); err == nil {
+		t.Error("缓存外模型应报错")
+	}
+	client.probeCode, client.probeErr = 403, stubServiceError{status: 403}
+	if _, err := gw.TestChannelModel(ctx, ch.ID, "meta.llama-3.3-70b-instruct"); err == nil {
+		t.Error("403 试调应报测试未通过")
+	}
+	var still model.AiChannel
+	gw.db.First(&still, ch.ID)
+	if still.ProbeStatus != "no_quota" || still.ProbeModel != "" {
+		t.Errorf("失败不应改动渠道: %+v", still)
+	}
+	client.probeCode, client.probeErr = 200, nil
+	fresh, err := gw.TestChannelModel(ctx, ch.ID, "meta.llama-3.3-70b-instruct")
+	if err != nil {
+		t.Fatalf("TestChannelModel: %v", err)
+	}
+	if fresh.ProbeModel != "meta.llama-3.3-70b-instruct" || fresh.ProbeStatus != "ok" ||
+		fresh.ProbeError != "" || fresh.FailCount != 0 {
+		t.Errorf("通过后应写验证模型并置可用: %+v", fresh)
+	}
+	// 已 ok 渠道再测另一模型:仅更新验证模型,不重写探测时间
+	cache2 := &model.AiModelCache{ChannelID: ch.ID, ModelOcid: "ocid1..m2", Name: "xai.grok-4", Vendor: "xai", SyncedAt: time.Now()}
+	gw.db.Create(cache2)
+	fresh2, err := gw.TestChannelModel(ctx, ch.ID, "xai.grok-4")
+	if err != nil || fresh2.ProbeModel != "xai.grok-4" {
+		t.Fatalf("已可用渠道更新验证模型: %+v, %v", fresh2, err)
+	}
+}
+
 func TestAiChatFinetuneSwitchesChannelWithoutPenalty(t *testing.T) {
 	// 微调基座 400 换渠道重试成功,且不计入熔断失败
 	client := &gatewayStubClient{
@@ -851,3 +1060,102 @@ func TestRespPassthroughStreamSwitchesChannel(t *testing.T) {
 		t.Errorf("流内容未透传: %s", payload)
 	}
 }
+
+// TestAiRuntimeSettings 断言流式保险丝与 grok 注入开关的缺省值、往返与持久化。
+func TestAiRuntimeSettings(t *testing.T) {
+	gw, svc := newTestGateway(t, &gatewayStubClient{fakeClient: &fakeClient{tenancy: oci.TenancyInfo{Name: "t"}}})
+	ctx := context.Background()
+
+	if on, kb := gw.StreamGuard(); !on || kb != 60 {
+		t.Fatalf("保险丝缺省应为 开/60, got %v/%d", on, kb)
+	}
+	if web, x := gw.GrokSearch(); !web || !x {
+		t.Fatalf("grok 注入缺省应双开, got %v/%v", web, x)
+	}
+	for _, bad := range []int{0, -1, 1025} {
+		if err := gw.SetStreamGuard(ctx, true, bad); err == nil {
+			t.Errorf("阈值 %d 应报错", bad)
+		}
+	}
+	if err := gw.SetStreamGuard(ctx, false, 80); err != nil {
+		t.Fatalf("SetStreamGuard: %v", err)
+	}
+	if err := gw.SetGrokSearch(ctx, false, true); err != nil {
+		t.Fatalf("SetGrokSearch: %v", err)
+	}
+	gw2 := NewAiGatewayService(gw.db, svc, &gatewayStubClient{})
+	if on, kb := gw2.StreamGuard(); on || kb != 80 {
+		t.Errorf("重建后保险丝应为 关/80, got %v/%d", on, kb)
+	}
+	if web, x := gw2.GrokSearch(); web || !x {
+		t.Errorf("重建后 grok 注入应为 关/开, got %v/%v", web, x)
+	}
+}
+
+// TestAggregatedModelsFilterDeprecated 断言聚合目录与模型列表口径一致:
+// 「过滤弃用」开启时弃用模型不出现,关闭时出现;空能力归一为 CHAT。
+func TestAggregatedModelsFilterDeprecated(t *testing.T) {
+	gw, svc := newTestGateway(t, &gatewayStubClient{fakeClient: &fakeClient{tenancy: oci.TenancyInfo{Name: "t"}}})
+	cfg := importAliveConfig(t, svc)
+	ch := seedChannel(t, gw, cfg.ID, "eu-frankfurt-1", 1, 1)
+	dep := time.Now().Add(-24 * time.Hour)
+	old := &model.AiModelCache{ChannelID: ch.ID, ModelOcid: "ocid1..dep", Name: "meta.llama-old",
+		Vendor: "meta", SyncedAt: time.Now(), DeprecatedAt: &dep}
+	if err := gw.db.Create(old).Error; err != nil {
+		t.Fatalf("seed deprecated cache: %v", err)
+	}
+	ctx := context.Background()
+
+	items, err := gw.AggregatedModels(ctx)
+	if err != nil {
+		t.Fatalf("AggregatedModels: %v", err)
+	}
+	if len(items) != 2 || items[0].Capability == "" {
+		t.Fatalf("开关关:应含弃用模型且能力归一, got %+v", items)
+	}
+	if err := gw.SetFilterDeprecated(ctx, true); err != nil {
+		t.Fatalf("SetFilterDeprecated: %v", err)
+	}
+	items, err = gw.AggregatedModels(ctx)
+	if err != nil {
+		t.Fatalf("AggregatedModels(过滤): %v", err)
+	}
+	if len(items) != 1 || items[0].Name == "meta.llama-old" {
+		t.Fatalf("开关开:弃用模型应被过滤, got %+v", items)
+	}
+}
+
+func TestUpstreamWaitSetting(t *testing.T) {
+	gw, _ := newTestGateway(t, &gatewayStubClient{fakeClient: &fakeClient{}})
+	ctx := context.Background()
+
+	if got := gw.UpstreamWait(); got != 300*time.Second {
+		t.Fatalf("缺省上游无响应预算 = %v, 期望 300s", got)
+	}
+	tests := []struct {
+		name    string
+		sec     int
+		wantErr bool
+	}{
+		{name: "下界 30 有效", sec: 30},
+		{name: "上界 900 有效", sec: 900},
+		{name: "低于下界拒绝", sec: 29, wantErr: true},
+		{name: "高于上界拒绝", sec: 901, wantErr: true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := gw.SetUpstreamWait(ctx, tt.sec)
+			if (err != nil) != tt.wantErr {
+				t.Fatalf("SetUpstreamWait(%d) = %v, wantErr=%v", tt.sec, err, tt.wantErr)
+			}
+			if !tt.wantErr && gw.UpstreamWait() != time.Duration(tt.sec)*time.Second {
+				t.Fatalf("UpstreamWait = %v, 期望 %ds", gw.UpstreamWait(), tt.sec)
+			}
+		})
+	}
+	// 持久化后新实例应加载已存值(最后一次成功设置为 900)
+	gw2 := NewAiGatewayService(gw.db, nil, nil)
+	if got := gw2.UpstreamWait(); got != 900*time.Second {
+		t.Fatalf("重建服务加载预算 = %v, 期望 900s", got)
+	}
+}

internal/service/airesponses.go

@@ -22,50 +22,513 @@ func respRejectStateful(req aiwire.RespRequest) error {
 	return nil
 }
 
-// RespServerTools 报告工具列表是否含 xAI 服务端工具(web_search / x_search)。
-func RespServerTools(tools []aiwire.RespTool) bool {
-	for _, t := range tools {
-		if t.Type == "web_search" || t.Type == "x_search" {
-			return true
-		}
-	}
-	return false
-}
-
 // RespPassthroughValidate 校验直通请求:模型必填,有状态特性不支持,工具类型
-// 只放行 function 与已实测的 web_search / x_search;流式仅在含服务端工具时拒绝
+// 放行 function、Oracle 文档化的服务端工具(web_search / x_search /
-// (工具流式事件形态未实测,不放开)。
+// code_interpreter / mcp)与 codex 特有形态(namespace 工具分组、custom 自由
+// 格式,上游不识别,转发前拍平/转换)。
 func RespPassthroughValidate(req aiwire.RespRequest) error {
 	if strings.TrimSpace(req.Model) == "" {
 		return fmt.Errorf("model 不能为空")
 	}
-	if req.Stream && RespServerTools(req.Tools) {
-		return fmt.Errorf("服务端工具暂不支持流式:请去掉 stream 或改用 function 工具")
-	}
 	if err := respRejectStateful(req); err != nil {
 		return err
 	}
 	for _, t := range req.Tools {
 		switch t.Type {
-		case "function", "web_search", "x_search":
+		case "function", "web_search", "x_search", "code_interpreter", "mcp", "namespace", "custom", "tool_search":
 		default:
-			return fmt.Errorf("不支持的工具类型 %q:服务端工具仅支持 web_search / x_search", t.Type)
+			return fmt.Errorf("不支持的工具类型 %q:服务端工具仅支持 web_search / x_search / code_interpreter / mcp", t.Type)
 		}
 	}
 	return nil
 }
 
+// RespNsRef 一条拍平映射:限定名对应的原 namespace 与短名。codex 的回程路由
+// 依赖 function_call 项上的 name+namespace 双字段,响应侧按此映射还原。
+type RespNsRef struct {
+	Namespace string
+	Name      string
+}
+
+// RespCompat 是直通请求 codex 兼容改写的结果:Flattened/Converted/Dropped 供
+// 调用方记日志;NsRefs / CustomNames 非空表示响应侧需做工具调用项还原。
+type RespCompat struct {
+	Flattened   []string
+	Converted   []string
+	Dropped     []string
+	NsRefs      map[string]RespNsRef
+	CustomNames map[string]struct{}
+}
+
+// NeedRestore 报告响应是否需要做工具调用项还原。
+func (c RespCompat) NeedRestore() bool {
+	return len(c.NsRefs) > 0 || len(c.CustomNames) > 0
+}
+
 // RespPassthroughBody 以原始请求体为基构造上游 body:强制 store:false(禁上游
 // 存态),stream 原样保留(流式直通);用 json.Number 保真未知字段与数值。
-func RespPassthroughBody(raw []byte) ([]byte, error) {
+// 同时做 codex 兼容改写(namespace 拍平、多轮历史与 tool_choice 重限定)。
+func RespPassthroughBody(raw []byte) ([]byte, RespCompat, error) {
 	dec := json.NewDecoder(strings.NewReader(string(raw)))
 	dec.UseNumber()
 	var body map[string]any
 	if err := dec.Decode(&body); err != nil {
-		return nil, fmt.Errorf("解析请求体: %w", err)
+		return nil, RespCompat{}, fmt.Errorf("解析请求体: %w", err)
 	}
 	body["store"] = false
-	return json.Marshal(body)
+	compat := respCompatTools(body)
+	respCompatInputCalls(body)
+	respCompatToolChoice(body)
+	out, err := json.Marshal(body)
+	return out, compat, err
+}
+
+// respCompatTools 对 tools 做 codex 兼容改写(上游实测行为见任务档案):
+// namespace 工具组上游 422,拆平为限定名 function 工具;custom(自由格式)上游
+// 同样 422,apply_patch 丢弃(grok 系未训练该补丁格式,失败编辑不如 shell 回退),
+// 其余转 function 包装;web_search 的 external_web_access 参数上游 400,false 是
+// "仅缓存检索"降权模式,按不越权原则连工具剥离,true 等价默认行为仅删键;
+// 剔空后删 tools,并连删 tool_choice 与 parallel_tool_calls(上游拒绝无 tools
+// 带 tool_choice)。
+func respCompatTools(body map[string]any) RespCompat {
+	tools, ok := body["tools"].([]any)
+	if !ok {
+		return RespCompat{}
+	}
+	compat := RespCompat{NsRefs: map[string]RespNsRef{}, CustomNames: map[string]struct{}{}}
+	kept := make([]any, 0, len(tools))
+	for _, item := range tools {
+		tool, _ := item.(map[string]any)
+		switch {
+		case tool != nil && tool["type"] == "namespace":
+			ns, _ := tool["name"].(string)
+			compat.Flattened = append(compat.Flattened, "namespace:"+ns)
+			kept = append(kept, respFlattenNsTool(ns, tool, &compat)...)
+			continue
+		case tool != nil && tool["type"] == "custom":
+			name, _ := tool["name"].(string)
+			if name == "apply_patch" {
+				compat.Dropped = append(compat.Dropped, "custom:apply_patch")
+				continue
+			}
+			respConvertCustomTool(tool)
+			if name != "" {
+				compat.CustomNames[name] = struct{}{}
+				compat.Converted = append(compat.Converted, "custom:"+name)
+			}
+			kept = append(kept, tool)
+			continue
+		}
+		if desc, drop := respToolDrop(tool); drop {
+			compat.Dropped = append(compat.Dropped, desc)
+			continue
+		}
+		kept = append(kept, item)
+	}
+	if len(kept) == 0 {
+		delete(body, "tools")
+		delete(body, "tool_choice")
+		delete(body, "parallel_tool_calls")
+	} else {
+		body["tools"] = kept
+	}
+	return compat
+}
+
+// respConvertCustomTool 把 custom(自由格式)工具改写为 function:补 input 包装
+// schema(custom 工具本无 parameters),模型以 {"input": 文本} 形态调用,响应侧
+// 按 CustomNames 回转;custom 专有的 format(语法约束)字段一并移除。
+func respConvertCustomTool(tool map[string]any) {
+	tool["type"] = "function"
+	delete(tool, "format")
+	if _, ok := tool["parameters"]; !ok {
+		tool["parameters"] = map[string]any{
+			"type":       "object",
+			"properties": map[string]any{"input": map[string]any{"type": "string"}},
+			"required":   []any{"input"},
+		}
+	}
+}
+
+// respFlattenNsTool 把 namespace 组内子工具上提为顶层工具:限定改名、缺
+// parameters 补空 schema(上游必填),映射写入 NsRefs 供响应侧还原;非
+// function 子工具(如 custom)上游同样不认,剥离并记录。
+func respFlattenNsTool(ns string, tool map[string]any, compat *RespCompat) []any {
+	children, _ := tool["tools"].([]any)
+	out := make([]any, 0, len(children))
+	for _, c := range children {
+		child, _ := c.(map[string]any)
+		if child == nil {
+			continue
+		}
+		short, _ := child["name"].(string)
+		if t, _ := child["type"].(string); t != "" && t != "function" {
+			compat.Dropped = append(compat.Dropped, ns+"."+short+"(type="+t+")")
+			continue
+		}
+		qualified := respQualifyNsName(ns, short)
+		if qualified == "" {
+			continue
+		}
+		child["name"] = qualified
+		if _, ok := child["parameters"]; !ok {
+			child["parameters"] = map[string]any{"type": "object", "properties": map[string]any{}}
+		}
+		compat.NsRefs[qualified] = RespNsRef{Namespace: ns, Name: short}
+		out = append(out, child)
+	}
+	return out
+}
+
+// respQualifyNsName 生成拍平后的限定名,与响应侧还原互逆(对齐 CLIProxyAPI):
+// mcp__ 开头的子工具名自带全局前缀不再限定;ns 以 __ 结尾直接拼接;已带前缀
+// 不重复添加。
+func respQualifyNsName(ns, name string) string {
+	ns, name = strings.TrimSpace(ns), strings.TrimSpace(name)
+	if ns == "" || name == "" || strings.HasPrefix(name, "mcp__") {
+		return name
+	}
+	prefix := ns
+	if !strings.HasSuffix(prefix, "__") {
+		prefix += "__"
+	}
+	if strings.HasPrefix(name, prefix) {
+		return name
+	}
+	return prefix + name
+}
+
+// respCompatInputCalls 改写多轮历史 input:function_call 的 namespace 字段重限定
+// (上游不认识该字段);custom_tool_call / custom_tool_call_output 转换为上游
+// 认识的 function_call(_output) 形态(上游 item 变体表不含 custom 系)。
+func respCompatInputCalls(body map[string]any) {
+	input, _ := body["input"].([]any)
+	for _, it := range input {
+		item, _ := it.(map[string]any)
+		if item == nil {
+			continue
+		}
+		switch item["type"] {
+		case "function_call":
+			respQualifyCallField(item)
+		case "custom_tool_call":
+			item["type"] = "function_call"
+			item["arguments"] = respCustomCallArguments(item["input"])
+			delete(item, "input")
+		case "custom_tool_call_output":
+			item["type"] = "function_call_output"
+			item["output"] = respCustomCallOutput(item["output"])
+		}
+	}
+}
+
+// respCustomCallArguments 把 custom_tool_call 的 input 包装为 function_call 的
+// arguments JSON 串(对齐 CLIProxyAPI):input 串本身是 JSON 对象则直用,普通
+// 文本包一层 {"input": 文本};对象取序列化;缺失为 {}。与响应侧
+// respUnwrapCustomInput 互逆,保证多轮往返无损。
+func respCustomCallArguments(input any) string {
+	switch v := input.(type) {
+	case string:
+		trimmed := strings.TrimSpace(v)
+		var probe map[string]any
+		if json.Unmarshal([]byte(trimmed), &probe) == nil && probe != nil {
+			return trimmed
+		}
+		enc, err := json.Marshal(v)
+		if err != nil {
+			return "{}"
+		}
+		return `{"input":` + string(enc) + `}`
+	case nil:
+		return "{}"
+	default:
+		enc, err := json.Marshal(v)
+		if err != nil {
+			return "{}"
+		}
+		return string(enc)
+	}
+}
+
+// respCustomCallOutput 归一 output 为字符串:非字符串时序列化保底。
+func respCustomCallOutput(output any) any {
+	if _, ok := output.(string); ok {
+		return output
+	}
+	if output == nil {
+		return ""
+	}
+	enc, err := json.Marshal(output)
+	if err != nil {
+		return ""
+	}
+	return string(enc)
+}
+
+// respCompatToolChoice 限定化对象形态的 tool_choice 及其 allowed_tools 列表
+// (上游不认 tool_choice 上的 namespace 字段)。
+func respCompatToolChoice(body map[string]any) {
+	tc, _ := body["tool_choice"].(map[string]any)
+	if tc == nil {
+		return
+	}
+	if tc["type"] == "function" {
+		respQualifyCallField(tc)
+	}
+	list, _ := tc["tools"].([]any)
+	for _, it := range list {
+		if sub, _ := it.(map[string]any); sub != nil && sub["type"] == "function" {
+			respQualifyCallField(sub)
+		}
+	}
+}
+
+// respQualifyCallField 把一个带 name/namespace 的对象改写为限定名形态。
+func respQualifyCallField(m map[string]any) {
+	ns, _ := m["namespace"].(string)
+	if strings.TrimSpace(ns) == "" {
+		return
+	}
+	name, _ := m["name"].(string)
+	if q := respQualifyNsName(ns, name); q != "" {
+		m["name"] = q
+	}
+	delete(m, "namespace")
+}
+
+// respToolDrop 判定单个工具是否剥离。web_search 的 external_web_access 参数
+// 上游 400:false 表示 OpenAI 的"仅缓存检索"降权模式,上游无对应能力,按不
+// 越权原则整个工具剥离;true 等价上游默认行为,仅删键放行。tool_search(codex
+// 的工具目录搜索)上游不识别,且 namespace 已全量拍平上送、搜索语义冗余,剥离。
+func respToolDrop(tool map[string]any) (string, bool) {
+	if tool == nil {
+		return "", false
+	}
+	switch tool["type"] {
+	case "tool_search":
+		return "tool_search", true
+	case "web_search":
+		access, has := tool["external_web_access"]
+		if !has {
+			return "", false
+		}
+		delete(tool, "external_web_access")
+		if access == false {
+			return "web_search(external_web_access=false)", true
+		}
+	}
+	return "", false
+}
+
+// RespGuardBytes 返回请求体中 instructions 与 tools 两字段的原始字节数之和,
+// 流式保险丝据此判定。上游对二者合计 >≈64.5KB 的流式请求会在推理阶段静默断流
+// (纯 EOF,input 正文不计入;2026-07-16 实测仍存在),阈值由设置页 AI Tab 配置。
+// 解析失败返回 0(放行,交由上游正常报错)。
+func RespGuardBytes(body []byte) int {
+	var probe struct {
+		Instructions json.RawMessage `json:"instructions"`
+		Tools        json.RawMessage `json:"tools"`
+	}
+	if err := json.Unmarshal(body, &probe); err != nil {
+		return 0
+	}
+	return len(probe.Instructions) + len(probe.Tools)
+}
+
+// RespInjectGrokTools 为 xai. 前缀模型默认注入服务端搜索工具:开关开启且请求
+// tools 中不存在同名工具时追加 {"type":"web_search"} / {"type":"x_search"};
+// 已存在(含任意参数形态)不覆盖。返回改写后 body 与注入清单(观测日志用);
+// 模型不匹配、两开关全关或解析失败时原样返回。
+func RespInjectGrokTools(body []byte, model string, web, x bool) ([]byte, []string) {
+	if !strings.HasPrefix(model, "xai.") || (!web && !x) {
+		return body, nil
+	}
+	dec := json.NewDecoder(strings.NewReader(string(body)))
+	dec.UseNumber()
+	var m map[string]any
+	if err := dec.Decode(&m); err != nil {
+		return body, nil
+	}
+	tools, _ := m["tools"].([]any)
+	missing := map[string]bool{"web_search": web, "x_search": x}
+	for _, t := range tools {
+		tool, ok := t.(map[string]any)
+		if !ok {
+			continue
+		}
+		if typ, _ := tool["type"].(string); missing[typ] {
+			missing[typ] = false
+		}
+	}
+	var injected []string
+	for _, typ := range []string{"web_search", "x_search"} {
+		if missing[typ] {
+			tools = append(tools, map[string]any{"type": typ})
+			injected = append(injected, typ)
+		}
+	}
+	if len(injected) == 0 {
+		return body, nil
+	}
+	m["tools"] = tools
+	out, err := json.Marshal(m)
+	if err != nil {
+		return body, nil
+	}
+	return out, injected
+}
+
+// RespDisableStream 把请求体的 stream 改为 false(流式升级回退用),其余字段
+// 原样保留。
+func RespDisableStream(body []byte) ([]byte, error) {
+	dec := json.NewDecoder(strings.NewReader(string(body)))
+	dec.UseNumber()
+	var m map[string]any
+	if err := dec.Decode(&m); err != nil {
+		return nil, fmt.Errorf("解析请求体: %w", err)
+	}
+	m["stream"] = false
+	return json.Marshal(m)
+}
+
+// RespSynthSSEEvents 把一份非流式响应合成为最小 SSE 事件序列:created →
+// 每个输出项一条 output_item.done → completed。流式升级回退用,客户端拿到
+// 完整事件语义但无增量;输出项与 usage 原样承载。
+func RespSynthSSEEvents(payload []byte) ([][]byte, error) {
+	dec := json.NewDecoder(strings.NewReader(string(payload)))
+	dec.UseNumber()
+	var resp map[string]any
+	if err := dec.Decode(&resp); err != nil {
+		return nil, fmt.Errorf("解析上游响应: %w", err)
+	}
+	output, _ := resp["output"].([]any)
+	status, hadStatus := resp["status"]
+	resp["status"], resp["output"] = "in_progress", []any{}
+	created, err := json.Marshal(map[string]any{"type": "response.created", "response": resp})
+	if err != nil {
+		return nil, err
+	}
+	if hadStatus {
+		resp["status"] = status
+	} else {
+		delete(resp, "status")
+	}
+	resp["output"] = output
+	events := [][]byte{created}
+	for i, item := range output {
+		ev, err := json.Marshal(map[string]any{"type": "response.output_item.done", "output_index": i, "item": item})
+		if err != nil {
+			return nil, err
+		}
+		events = append(events, ev)
+	}
+	completed, err := json.Marshal(map[string]any{"type": "response.completed", "response": resp})
+	if err != nil {
+		return nil, err
+	}
+	return append(events, completed), nil
+}
+
+// RespRestoreToolCalls 非流式响应还原:output 数组中命中 NsRefs 的 function_call
+// 把限定名还原为短名并补回 namespace 字段(codex 以该双字段路由);命中
+// CustomNames 的回转 custom_tool_call(codex 期望 input 字段形态)。无需还原或
+// 解析失败时返回原字节,不破坏直通。
+func RespRestoreToolCalls(payload []byte, compat RespCompat) []byte {
+	if !compat.NeedRestore() {
+		return payload
+	}
+	dec := json.NewDecoder(strings.NewReader(string(payload)))
+	dec.UseNumber()
+	var body map[string]any
+	if dec.Decode(&body) != nil {
+		return payload
+	}
+	if !respRestoreOutput(body["output"], compat) {
+		return payload
+	}
+	out, err := json.Marshal(body)
+	if err != nil {
+		return payload
+	}
+	return out
+}
+
+// RespRestoreToolCallsEvent 流式单事件还原:处理事件顶层 item(output_item.*)
+// 与 response.output(created/completed 等快照)。返回还原后数据与是否改动;
+// 未改动时调用方转发原始行,保持字节级直通。
+func RespRestoreToolCallsEvent(data []byte, compat RespCompat) ([]byte, bool) {
+	if !compat.NeedRestore() {
+		return data, false
+	}
+	dec := json.NewDecoder(strings.NewReader(string(data)))
+	dec.UseNumber()
+	var ev map[string]any
+	if dec.Decode(&ev) != nil {
+		return data, false
+	}
+	changed := respRestoreCallItem(ev["item"], compat)
+	if resp, _ := ev["response"].(map[string]any); resp != nil {
+		changed = respRestoreOutput(resp["output"], compat) || changed
+	}
+	if !changed {
+		return data, false
+	}
+	out, err := json.Marshal(ev)
+	if err != nil {
+		return data, false
+	}
+	return out, true
+}
+
+// respRestoreOutput 还原一个 output 数组,返回是否有改动。
+func respRestoreOutput(v any, compat RespCompat) bool {
+	items, _ := v.([]any)
+	changed := false
+	for _, it := range items {
+		if respRestoreCallItem(it, compat) {
+			changed = true
+		}
+	}
+	return changed
+}
+
+// respRestoreCallItem 还原单个 function_call 项,返回是否改动。namespace 还原与
+// custom 回转互斥:custom 工具不参与 namespace 拍平。
+func respRestoreCallItem(v any, compat RespCompat) bool {
+	item, _ := v.(map[string]any)
+	if item == nil || item["type"] != "function_call" {
+		return false
+	}
+	name, _ := item["name"].(string)
+	if ref, ok := compat.NsRefs[name]; ok {
+		item["name"] = ref.Name
+		item["namespace"] = ref.Namespace
+		return true
+	}
+	if _, ok := compat.CustomNames[name]; ok {
+		item["type"] = "custom_tool_call"
+		item["input"] = respUnwrapCustomInput(item["arguments"])
+		delete(item, "arguments")
+		return true
+	}
+	return false
+}
+
+// respUnwrapCustomInput 解包 arguments:形如 {"input": 串} 取其 input(非串取该
+// 值原文),其余情况整串返回。与请求侧 respCustomCallArguments 互逆。
+func respUnwrapCustomInput(arguments any) string {
+	s, _ := arguments.(string)
+	var probe map[string]json.RawMessage
+	if json.Unmarshal([]byte(s), &probe) == nil {
+		if raw, ok := probe["input"]; ok {
+			var str string
+			if json.Unmarshal(raw, &str) == nil {
+				return str
+			}
+			return string(raw)
+		}
+	}
+	return s
 }
 
 // RespPassthroughUsage 从直通响应提取用量;缺失时返回 nil(日志记零)。

internal/service/airesponses_test.go

@@ -2,6 +2,8 @@ package service
 
 import (
 	"encoding/json"
+	"fmt"
+	"slices"
 	"strings"
 	"testing"
 
@@ -24,27 +26,6 @@ func deref(p *int) int {
 	return *p
 }
 
-func TestRespServerTools(t *testing.T) {
-	tests := []struct {
-		name  string
-		tools []aiwire.RespTool
-		want  bool
-	}{
-		{"web_search", []aiwire.RespTool{{Type: "web_search"}}, true},
-		{"x_search混用", []aiwire.RespTool{{Type: "function", Name: "f"}, {Type: "x_search"}}, true},
-		{"仅function", []aiwire.RespTool{{Type: "function", Name: "f"}}, false},
-		{"空", nil, false},
-		{"其他类型", []aiwire.RespTool{{Type: "code_interpreter"}}, false},
-	}
-	for _, test := range tests {
-		t.Run(test.name, func(t *testing.T) {
-			if got := RespServerTools(test.tools); got != test.want {
-				t.Fatalf("got %v, want %v", got, test.want)
-			}
-		})
-	}
-}
-
 func TestRespPassthroughValidate(t *testing.T) {
 	prev := "resp_1"
 	bg := true
@@ -56,12 +37,17 @@ func TestRespPassthroughValidate(t *testing.T) {
 		{"合法", aiwire.RespRequest{Model: "m", Tools: []aiwire.RespTool{{Type: "web_search"}}}, false},
 		{"混用function", aiwire.RespRequest{Model: "m", Tools: []aiwire.RespTool{{Type: "web_search"}, {Type: "function", Name: "f"}}}, false},
 		{"缺model", aiwire.RespRequest{Tools: []aiwire.RespTool{{Type: "web_search"}}}, true},
-		{"工具加流式拒绝", aiwire.RespRequest{Model: "m", Stream: true, Tools: []aiwire.RespTool{{Type: "web_search"}}}, true},
+		{"服务端工具流式放行", aiwire.RespRequest{Model: "m", Stream: true, Tools: []aiwire.RespTool{{Type: "web_search"}}}, false},
 		{"无工具流式放行", aiwire.RespRequest{Model: "m", Stream: true}, false},
 		{"function工具流式放行", aiwire.RespRequest{Model: "m", Stream: true, Tools: []aiwire.RespTool{{Type: "function", Name: "f"}}}, false},
+		{"code_interpreter放行", aiwire.RespRequest{Model: "m", Tools: []aiwire.RespTool{{Type: "code_interpreter"}}}, false},
+		{"mcp流式放行", aiwire.RespRequest{Model: "m", Stream: true, Tools: []aiwire.RespTool{{Type: "mcp"}}}, false},
 		{"有状态拒绝", aiwire.RespRequest{Model: "m", PreviousResponseID: prev}, true},
 		{"background拒绝", aiwire.RespRequest{Model: "m", Background: &bg}, true},
-		{"未知工具拒绝", aiwire.RespRequest{Model: "m", Tools: []aiwire.RespTool{{Type: "web_search"}, {Type: "mcp"}}}, true},
+		{"未知工具拒绝", aiwire.RespRequest{Model: "m", Tools: []aiwire.RespTool{{Type: "web_search"}, {Type: "file_search"}}}, true},
+		{"namespace放行", aiwire.RespRequest{Model: "m", Tools: []aiwire.RespTool{{Type: "namespace", Name: "multi_agent_v1"}}}, false},
+		{"custom放行", aiwire.RespRequest{Model: "m", Tools: []aiwire.RespTool{{Type: "custom", Name: "run_script"}}}, false},
+		{"tool_search放行", aiwire.RespRequest{Model: "m", Tools: []aiwire.RespTool{{Type: "tool_search"}}}, false},
 	}
 	for _, test := range tests {
 		t.Run(test.name, func(t *testing.T) {
@@ -75,10 +61,13 @@ func TestRespPassthroughValidate(t *testing.T) {
 
 func TestRespPassthroughBody(t *testing.T) {
 	raw := []byte(`{"model":"m","input":"hi","stream":true,"store":true,"max_output_tokens":128,"custom_field":{"a":1.5}}`)
-	out, err := RespPassthroughBody(raw)
+	out, compat, err := RespPassthroughBody(raw)
 	if err != nil {
 		t.Fatalf("RespPassthroughBody: %v", err)
 	}
+	if len(compat.Dropped) != 0 || len(compat.Flattened) != 0 || len(compat.NsRefs) != 0 {
+		t.Errorf("无 codex 工具不应有兼容改写: %+v", compat)
+	}
 	var body map[string]any
 	if err := json.Unmarshal(out, &body); err != nil {
 		t.Fatalf("unmarshal out: %v", err)
@@ -95,11 +84,206 @@ func TestRespPassthroughBody(t *testing.T) {
 	if !strings.Contains(string(out), `"custom_field"`) {
 		t.Errorf("未知字段应保留: %s", out)
 	}
-	if _, err := RespPassthroughBody([]byte("not-json")); err == nil {
+	if _, _, err := RespPassthroughBody([]byte("not-json")); err == nil {
 		t.Error("非法 JSON 应报错")
 	}
 }
 
+// TestRespQualifyNsName 断言限定名生成规则与 CLIProxyAPI 对齐。
+func TestRespQualifyNsName(t *testing.T) {
+	tests := []struct{ name, ns, tool, want string }{
+		{"常规拼接", "multi_agent_v1", "spawn_agent", "multi_agent_v1__spawn_agent"},
+		{"mcp子工具不加前缀", "mcp__sites", "mcp__sites__create_site", "mcp__sites__create_site"},
+		{"ns以双下划线结尾", "codex_app__", "update", "codex_app__update"},
+		{"已带前缀不重复", "ns1", "ns1__tool", "ns1__tool"},
+		{"空ns原样", "", "tool", "tool"},
+		{"空名返回空", "ns1", "", ""},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			if got := respQualifyNsName(test.ns, test.tool); got != test.want {
+				t.Fatalf("respQualifyNsName(%q,%q) = %q, want %q", test.ns, test.tool, got, test.want)
+			}
+		})
+	}
+}
+
+// TestRespPassthroughBodyCompatTools 断言 codex 工具兼容改写:namespace 拍平为
+// 限定名 function 并建映射,web_search 降权剥离,剔空连删 tool_choice。
+func TestRespPassthroughBodyCompatTools(t *testing.T) {
+	tests := []struct {
+		name          string
+		raw           string
+		wantFlattened []string
+		wantDropped   []string
+		wantRefs      map[string]RespNsRef
+		wantContains  []string
+		wantAbsent    []string
+	}{
+		{
+			"namespace拍平保留function",
+			`{"model":"m","tools":[{"type":"function","name":"exec"},{"type":"namespace","name":"multi_agent_v1","tools":[{"type":"function","name":"spawn_agent","parameters":{"type":"object"}}]}]}`,
+			[]string{"namespace:multi_agent_v1"},
+			nil,
+			map[string]RespNsRef{"multi_agent_v1__spawn_agent": {Namespace: "multi_agent_v1", Name: "spawn_agent"}},
+			[]string{`"name":"multi_agent_v1__spawn_agent"`, `"name":"exec"`},
+			[]string{`"type":"namespace"`},
+		},
+		{
+			"mcp子工具保名并补parameters",
+			`{"model":"m","tools":[{"type":"namespace","name":"mcp__sites","tools":[{"type":"function","name":"mcp__sites__create"}]}]}`,
+			[]string{"namespace:mcp__sites"},
+			nil,
+			map[string]RespNsRef{"mcp__sites__create": {Namespace: "mcp__sites", Name: "mcp__sites__create"}},
+			[]string{`"name":"mcp__sites__create"`, `"parameters":{"properties":{},"type":"object"}`},
+			[]string{`"type":"namespace"`},
+		},
+		{
+			"非function子工具剥离",
+			`{"model":"m","tools":[{"type":"namespace","name":"ns1","tools":[{"type":"custom","name":"patch"},{"type":"function","name":"run"}]}]}`,
+			[]string{"namespace:ns1"},
+			[]string{"ns1.patch(type=custom)"},
+			map[string]RespNsRef{"ns1__run": {Namespace: "ns1", Name: "run"}},
+			[]string{`"name":"ns1__run"`},
+			[]string{"patch"},
+		},
+		{
+			"剔空连删tool_choice",
+			`{"model":"m","tool_choice":"auto","parallel_tool_calls":false,"tools":[{"type":"web_search","external_web_access":false}]}`,
+			nil,
+			[]string{"web_search(external_web_access=false)"},
+			nil,
+			nil,
+			[]string{`"tools"`, `"tool_choice"`, `"parallel_tool_calls"`},
+		},
+		{
+			"web_search全访问仅删键",
+			`{"model":"m","tools":[{"type":"web_search","external_web_access":true}]}`,
+			nil,
+			nil,
+			nil,
+			[]string{`"tools":[{"type":"web_search"}]`},
+			[]string{"external_web_access"},
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			out, compat, err := RespPassthroughBody([]byte(test.raw))
+			if err != nil {
+				t.Fatalf("RespPassthroughBody: %v", err)
+			}
+			if !slices.Equal(compat.Flattened, test.wantFlattened) {
+				t.Errorf("Flattened = %v, want %v", compat.Flattened, test.wantFlattened)
+			}
+			if !slices.Equal(compat.Dropped, test.wantDropped) {
+				t.Errorf("Dropped = %v, want %v", compat.Dropped, test.wantDropped)
+			}
+			for q, ref := range test.wantRefs {
+				if compat.NsRefs[q] != ref {
+					t.Errorf("NsRefs[%s] = %+v, want %+v", q, compat.NsRefs[q], ref)
+				}
+			}
+			for _, s := range test.wantContains {
+				if !strings.Contains(string(out), s) {
+					t.Errorf("应包含 %s: %s", s, out)
+				}
+			}
+			for _, s := range test.wantAbsent {
+				if strings.Contains(string(out), s) {
+					t.Errorf("不应包含 %s: %s", s, out)
+				}
+			}
+		})
+	}
+}
+
+// TestRespCompatHistoryAndToolChoice 断言多轮历史 function_call 与对象 tool_choice
+// 的 namespace 字段被重限定并删除。
+func TestRespCompatHistoryAndToolChoice(t *testing.T) {
+	raw := `{"model":"m",
+		"tool_choice":{"type":"function","name":"spawn_agent","namespace":"multi_agent_v1"},
+		"input":[
+			{"type":"function_call","name":"spawn_agent","namespace":"multi_agent_v1","call_id":"c1","arguments":"{}"},
+			{"type":"function_call","name":"exec","call_id":"c2","arguments":"{}"},
+			{"type":"function_call_output","call_id":"c1","output":"ok"}
+		],
+		"tools":[{"type":"namespace","name":"multi_agent_v1","tools":[{"type":"function","name":"spawn_agent","parameters":{}}]}]}`
+	out, _, err := RespPassthroughBody([]byte(raw))
+	if err != nil {
+		t.Fatalf("RespPassthroughBody: %v", err)
+	}
+	s := string(out)
+	if !strings.Contains(s, `"tool_choice":{"name":"multi_agent_v1__spawn_agent","type":"function"}`) {
+		t.Errorf("tool_choice 应限定化: %s", s)
+	}
+	if strings.Contains(s, `"namespace":"multi_agent_v1"`) {
+		t.Errorf("namespace 字段应全部删除: %s", s)
+	}
+	if !strings.Contains(s, `"name":"exec"`) {
+		t.Errorf("无 namespace 的历史项应原样: %s", s)
+	}
+	if c := strings.Count(s, "multi_agent_v1__spawn_agent"); c != 3 {
+		t.Errorf("限定名应出现 3 次(tools/input/tool_choice), got %d: %s", c, s)
+	}
+}
+
+// TestRespRestoreNamespace 断言非流式响应把限定名还原为短名+namespace 双字段。
+func TestRespRestoreNamespace(t *testing.T) {
+	compat := RespCompat{NsRefs: map[string]RespNsRef{"multi_agent_v1__spawn_agent": {Namespace: "multi_agent_v1", Name: "spawn_agent"}}}
+	payload := []byte(`{"id":"r1","output":[{"type":"function_call","name":"multi_agent_v1__spawn_agent","call_id":"c1","arguments":"{}"},{"type":"message","content":[]}],"usage":{"total_tokens":7}}`)
+	out := RespRestoreToolCalls(payload, compat)
+	s := string(out)
+	if !strings.Contains(s, `"name":"spawn_agent"`) || !strings.Contains(s, `"namespace":"multi_agent_v1"`) {
+		t.Errorf("应还原短名并补 namespace: %s", s)
+	}
+	if !strings.Contains(s, `"total_tokens":7`) {
+		t.Errorf("其余字段应保真: %s", s)
+	}
+	for name, payload := range map[string][]byte{
+		"未命中原样":  []byte(`{"output":[{"type":"function_call","name":"other","call_id":"c"}]}`),
+		"非法JSON": []byte(`xx`),
+	} {
+		if got := RespRestoreToolCalls(payload, compat); string(got) != string(payload) {
+			t.Errorf("%s: 应返回原字节, got %s", name, got)
+		}
+	}
+	if got := RespRestoreToolCalls(payload, RespCompat{}); string(got) != string(payload) {
+		t.Error("无需还原时应返回原字节")
+	}
+}
+
+// TestRespRestoreNamespaceEvent 断言流式事件还原覆盖 item 与 response.output
+// 两个位置,无关事件保持未改动。
+func TestRespRestoreNamespaceEvent(t *testing.T) {
+	compat := RespCompat{NsRefs: map[string]RespNsRef{"ns1__run": {Namespace: "ns1", Name: "run"}}}
+	tests := []struct {
+		name        string
+		data        string
+		wantChanged bool
+		wantSub     string
+	}{
+		{"output_item.done", `{"type":"response.output_item.done","item":{"type":"function_call","name":"ns1__run","call_id":"c1"}}`, true, `"namespace":"ns1"`},
+		{"completed快照", `{"type":"response.completed","response":{"output":[{"type":"function_call","name":"ns1__run"}],"usage":{"total_tokens":1}}}`, true, `"name":"run"`},
+		{"文本增量不动", `{"type":"response.output_text.delta","delta":"hi"}`, false, ""},
+		{"未命中不动", `{"type":"response.output_item.done","item":{"type":"function_call","name":"exec"}}`, false, ""},
+		{"非法JSON不动", `not-json`, false, ""},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			out, changed := RespRestoreToolCallsEvent([]byte(test.data), compat)
+			if changed != test.wantChanged {
+				t.Fatalf("changed = %v, want %v", changed, test.wantChanged)
+			}
+			if !changed && string(out) != test.data {
+				t.Fatalf("未改动应返回原字节: %s", out)
+			}
+			if test.wantSub != "" && !strings.Contains(string(out), test.wantSub) {
+				t.Fatalf("应包含 %s: %s", test.wantSub, out)
+			}
+		})
+	}
+}
+
 func TestRespPassthroughUsage(t *testing.T) {
 	tests := []struct {
 		name           string
@@ -145,3 +329,231 @@ func TestRespStreamCompletedUsage(t *testing.T) {
 		}
 	}
 }
+
+// TestRespGuardBytes 断言保险丝计量:instructions+tools 原始字节和,缺字段计 0,
+// 解析失败返回 0 放行。
+func TestRespGuardBytes(t *testing.T) {
+	for _, tc := range []struct {
+		name, body string
+		want       int
+	}{
+		{"双字段", `{"instructions":"abcd","tools":[{"type":"web_search"}],"input":"xxxxxxxx"}`,
+			len(`"abcd"`) + len(`[{"type":"web_search"}]`)},
+		{"仅 instructions", `{"instructions":"abcd"}`, len(`"abcd"`)},
+		{"均缺失 input 不计", `{"input":"xxxxxxxxxxxxxxxx"}`, 0},
+		{"解析失败放行", `not-json`, 0},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := RespGuardBytes([]byte(tc.body)); got != tc.want {
+				t.Fatalf("RespGuardBytes() = %d, want %d", got, tc.want)
+			}
+		})
+	}
+}
+
+// TestRespInjectGrokTools 断言 grok 搜索工具默认注入:仅 xai. 模型、开关可控、
+// 已带同名工具不覆盖、注入清单正确。
+func TestRespInjectGrokTools(t *testing.T) {
+	for _, tc := range []struct {
+		name, body, model string
+		web, x            bool
+		wantInjected      []string
+		wantContains      []string
+	}{
+		{"非 xai 不注入", `{"tools":[]}`, "meta.llama-3.3", true, true, nil, nil},
+		{"双开无 tools 字段注入两个", `{"model":"xai.grok-4.3"}`, "xai.grok-4.3", true, true,
+			[]string{"web_search", "x_search"}, []string{`"web_search"`, `"x_search"`}},
+		{"已带 web_search 只注入 x_search", `{"tools":[{"type":"web_search","filters":{"x":1}}]}`,
+			"xai.grok-4.3", true, true, []string{"x_search"}, []string{`"filters"`}},
+		{"开关全关不注入", `{"tools":[]}`, "xai.grok-4.3", false, false, nil, nil},
+		{"仅开 x_search", `{"tools":[]}`, "xai.grok-4.3", false, true, []string{"x_search"}, nil},
+		{"解析失败原样", `not-json`, "xai.grok-4.3", true, true, nil, nil},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			out, injected := RespInjectGrokTools([]byte(tc.body), tc.model, tc.web, tc.x)
+			if fmt.Sprint(injected) != fmt.Sprint(tc.wantInjected) {
+				t.Fatalf("injected = %v, want %v", injected, tc.wantInjected)
+			}
+			if len(injected) == 0 && string(out) != tc.body {
+				t.Fatalf("未注入时应原样返回: %s", out)
+			}
+			for _, sub := range append(tc.wantContains, toolTypes(injected)...) {
+				if !strings.Contains(string(out), sub) {
+					t.Fatalf("输出缺少 %s: %s", sub, out)
+				}
+			}
+		})
+	}
+}
+
+// toolTypes 把注入清单转为输出应包含的片段断言。
+func toolTypes(injected []string) []string {
+	var out []string
+	for _, typ := range injected {
+		out = append(out, `{"type":"`+typ+`"}`)
+	}
+	return out
+}
+
+// TestRespDisableStream 断言流式升级回退把 stream 置 false 且其余字段保留。
+func TestRespDisableStream(t *testing.T) {
+	out, err := RespDisableStream([]byte(`{"model":"m","stream":true,"max_output_tokens":64}`))
+	if err != nil {
+		t.Fatalf("RespDisableStream: %v", err)
+	}
+	if !strings.Contains(string(out), `"stream":false`) || !strings.Contains(string(out), `"max_output_tokens":64`) {
+		t.Fatalf("字段不符: %s", out)
+	}
+	if _, err := RespDisableStream([]byte("x")); err == nil {
+		t.Error("非法 JSON 应报错")
+	}
+}
+
+// TestRespSynthSSEEvents 断言合成事件序列:created(in_progress,空 output)→
+// 逐项 output_item.done → completed(完整响应)。
+func TestRespSynthSSEEvents(t *testing.T) {
+	payload := []byte(`{"id":"r1","status":"completed","output":[{"type":"reasoning","summary":[]},{"type":"function_call","name":"run","call_id":"c1"}],"usage":{"total_tokens":9}}`)
+	events, err := RespSynthSSEEvents(payload)
+	if err != nil {
+		t.Fatalf("RespSynthSSEEvents: %v", err)
+	}
+	if len(events) != 4 {
+		t.Fatalf("事件数 = %d, want 4", len(events))
+	}
+	first := string(events[0])
+	if !strings.Contains(first, `"type":"response.created"`) || !strings.Contains(first, `"status":"in_progress"`) || !strings.Contains(first, `"output":[]`) {
+		t.Errorf("created 事件不符: %s", first)
+	}
+	if !strings.Contains(string(events[1]), `"type":"response.output_item.done"`) || !strings.Contains(string(events[1]), `"output_index":0`) {
+		t.Errorf("item.done 事件不符: %s", events[1])
+	}
+	if !strings.Contains(string(events[2]), `"name":"run"`) {
+		t.Errorf("第二项应为 function_call: %s", events[2])
+	}
+	last := string(events[3])
+	if !strings.Contains(last, `"type":"response.completed"`) || !strings.Contains(last, `"status":"completed"`) ||
+		!strings.Contains(last, `"total_tokens":9`) || !strings.Contains(last, `"name":"run"`) {
+		t.Errorf("completed 事件不符: %s", last)
+	}
+	if _, err := RespSynthSSEEvents([]byte("x")); err == nil {
+		t.Error("非法 JSON 应报错")
+	}
+}
+
+// TestRespCompatCustomTools 断言 custom 工具转换:apply_patch 丢弃,其余转
+// function 并补 input 包装 schema、记入 CustomNames;format 字段移除。
+func TestRespCompatCustomTools(t *testing.T) {
+	raw := `{"model":"m","tools":[
+		{"type":"custom","name":"apply_patch","description":"edit files"},
+		{"type":"custom","name":"run_script","description":"run it","format":{"type":"grammar"}},
+		{"type":"function","name":"exec","parameters":{}}]}`
+	out, compat, err := RespPassthroughBody([]byte(raw))
+	if err != nil {
+		t.Fatalf("RespPassthroughBody: %v", err)
+	}
+	if !slices.Equal(compat.Dropped, []string{"custom:apply_patch"}) {
+		t.Errorf("Dropped = %v", compat.Dropped)
+	}
+	if !slices.Equal(compat.Converted, []string{"custom:run_script"}) {
+		t.Errorf("Converted = %v", compat.Converted)
+	}
+	if _, ok := compat.CustomNames["run_script"]; !ok {
+		t.Errorf("CustomNames 缺 run_script: %v", compat.CustomNames)
+	}
+	s := string(out)
+	if strings.Contains(s, "apply_patch") || strings.Contains(s, `"type":"custom"`) || strings.Contains(s, "grammar") {
+		t.Errorf("apply_patch/custom/format 应消失: %s", s)
+	}
+	if !strings.Contains(s, `"required":["input"]`) || !strings.Contains(s, `"input":{"type":"string"}`) {
+		t.Errorf("run_script 应补 input 包装 schema: %s", s)
+	}
+}
+
+// TestRespCompatCustomHistory 断言 input 历史的 custom_tool_call(_output) 转换
+// 与 arguments 包装三分支。
+func TestRespCompatCustomHistory(t *testing.T) {
+	raw := `{"model":"m","input":[
+		{"type":"custom_tool_call","call_id":"c1","name":"run_script","input":"plain text"},
+		{"type":"custom_tool_call","call_id":"c2","name":"run_script","input":"{\"a\":1}"},
+		{"type":"custom_tool_call","call_id":"c3","name":"run_script"},
+		{"type":"custom_tool_call_output","call_id":"c1","output":"done"},
+		{"type":"custom_tool_call_output","call_id":"c2","output":{"ok":true}}]}`
+	out, _, err := RespPassthroughBody([]byte(raw))
+	if err != nil {
+		t.Fatalf("RespPassthroughBody: %v", err)
+	}
+	s := string(out)
+	if strings.Contains(s, "custom_tool_call") {
+		t.Fatalf("custom_tool_call 系应全部转换: %s", s)
+	}
+	for _, want := range []string{
+		`"arguments":"{\"input\":\"plain text\"}"`,
+		`"arguments":"{\"a\":1}"`,
+		`"arguments":"{}"`,
+		`"output":"done"`,
+		`"output":"{\"ok\":true}"`,
+	} {
+		if !strings.Contains(s, want) {
+			t.Errorf("应包含 %s: %s", want, s)
+		}
+	}
+}
+
+// TestRespRestoreCustomToolCalls 断言响应侧回转:命中 CustomNames 的
+// function_call 变 custom_tool_call 且 input 解包;流式事件同样生效。
+func TestRespRestoreCustomToolCalls(t *testing.T) {
+	compat := RespCompat{CustomNames: map[string]struct{}{"run_script": {}}}
+	payload := []byte(`{"output":[{"type":"function_call","name":"run_script","call_id":"c1","arguments":"{\"input\":\"echo hi\"}"},{"type":"function_call","name":"exec","call_id":"c2","arguments":"{}"}]}`)
+	s := string(RespRestoreToolCalls(payload, compat))
+	if !strings.Contains(s, `"type":"custom_tool_call"`) || !strings.Contains(s, `"input":"echo hi"`) {
+		t.Errorf("应回转 custom_tool_call 并解包 input: %s", s)
+	}
+	if strings.Contains(s, `"arguments":"{\"input\":\"echo hi\"}"`) {
+		t.Errorf("arguments 应删除: %s", s)
+	}
+	if !strings.Contains(s, `"name":"exec"`) || strings.Count(s, "custom_tool_call") != 1 {
+		t.Errorf("非转换名不应动: %s", s)
+	}
+	ev := []byte(`{"type":"response.output_item.done","item":{"type":"function_call","name":"run_script","arguments":"not-json"}}`)
+	got, changed := RespRestoreToolCallsEvent(ev, compat)
+	if !changed || !strings.Contains(string(got), `"input":"not-json"`) {
+		t.Errorf("非 JSON arguments 应整串作 input: %s", got)
+	}
+}
+
+// TestRespUnwrapCustomInput 断言解包分支:input 键取值、非串取原文、其余整串。
+func TestRespUnwrapCustomInput(t *testing.T) {
+	tests := []struct {
+		name string
+		args any
+		want string
+	}{
+		{"包装取input", `{"input":"hello"}`, "hello"},
+		{"input非串取原文", `{"input":{"x":1}}`, `{"x":1}`},
+		{"无input键整串", `{"cmd":"ls"}`, `{"cmd":"ls"}`},
+		{"非JSON整串", "raw text", "raw text"},
+		{"非串类型空串", 42, ""},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			if got := respUnwrapCustomInput(test.args); got != test.want {
+				t.Fatalf("respUnwrapCustomInput(%v) = %q, want %q", test.args, got, test.want)
+			}
+		})
+	}
+}
+
+// TestRespCompatToolSearchDrop 断言 tool_search 剥离(拍平后语义冗余,上游不识别)。
+func TestRespCompatToolSearchDrop(t *testing.T) {
+	raw := `{"model":"m","tools":[{"type":"tool_search"},{"type":"function","name":"exec"}]}`
+	out, compat, err := RespPassthroughBody([]byte(raw))
+	if err != nil {
+		t.Fatalf("RespPassthroughBody: %v", err)
+	}
+	if !slices.Equal(compat.Dropped, []string{"tool_search"}) {
+		t.Errorf("Dropped = %v", compat.Dropped)
+	}
+	if strings.Contains(string(out), "tool_search") || !strings.Contains(string(out), `"name":"exec"`) {
+		t.Errorf("tool_search 应剥离且 function 保留: %s", out)
+	}
+}

internal/service/audit.go

@@ -30,19 +30,23 @@ var ErrInvalidAuditCursor = errors.New("audit events: invalid cursor, refresh to
 var ErrAuditEventGone = errors.New("原始事件已不可取回,请刷新列表后重试")
 
 // AuditQuery 是批式懒加载查询参数:Cursor 为空表示自当前时刻首查,
-// 非空则从上次响应的游标位置继续向更早回溯;Limit 为单批目标条数。
+// 非空则从上次响应的游标位置继续向更早回溯;Limit 为单批目标条数;
+// Q 为检索关键字,仅首查生效(续查沿用游标内嵌的关键字,保证跨批一致)。
 type AuditQuery struct {
 	Region string
 	Cursor string
 	Limit  int
+	Q      string
 }
 
 // AuditEventsView 是批式查询响应:列表不含 raw(详情接口取回);
-// Cursor 供下一批续查原样带回,空且 Exhausted 表示已到 365 天保留期尽头。
+// Cursor 供下一批续查原样带回,空且 Exhausted 表示已到 365 天保留期尽头;
+// ScannedThrough 为已完整回溯到的时刻(比它更新的时段已扫完),供前端展示进度。
 type AuditEventsView struct {
 	Items          []oci.AuditEvent `json:"items"`
 	Cursor         string           `json:"cursor,omitempty"`
 	Exhausted      bool             `json:"exhausted"`
+	ScannedThrough *time.Time       `json:"scannedThrough,omitempty"`
 }
 
 // AuditEvents 实时查询租户 OCI 审计事件,纯透传不入库;region 为空时用配置
@@ -52,6 +56,9 @@ func (s *OciConfigService) AuditEvents(ctx context.Context, id uint, q AuditQuer
 	if err != nil {
 		return AuditEventsView{}, err
 	}
+	if q.Cursor == "" {
+		cur.Q = oci.SanitizeAuditTerm(q.Q)
+	}
 	cred, err := s.credentialsByID(ctx, id)
 	if err != nil {
 		return AuditEventsView{}, err
@@ -63,6 +70,7 @@ func (s *OciConfigService) AuditEvents(ctx context.Context, id uint, q AuditQuer
 	view := AuditEventsView{Items: s.stripAuditRaw(id, res.Items), Exhausted: res.Exhausted}
 	if res.Cursor != nil {
 		view.Cursor = encodeAuditCursor(*res.Cursor)
+		view.ScannedThrough = &res.Cursor.End
 	}
 	return view, nil
 }

internal/service/logevent.go

@@ -554,6 +554,8 @@ func envActor(env onsEnvelope) string {
 
 // envOutcome 判读事件成败与补充说明:登录事件解析 auditEventMapValue;其余
 // Audit 事件看 message 后缀,补充说明取 stateChange.current.description(策略描述)。
+// 计算类失败形如 "LaunchInstance failed with response 'NotAuthorizedOrNotFound'",
+// 判失败并以引号内错误码作补充说明(无其他说明时)。
 func envOutcome(env onsEnvelope) (outcome, detail string) {
 	if env.StateChange != nil {
 		detail = env.StateChange.Current.Description
@@ -566,10 +568,24 @@ func envOutcome(env onsEnvelope) (outcome, detail string) {
 		outcome = "成功"
 	case strings.HasSuffix(env.Message, " failed"):
 		outcome = "失败"
+	case strings.Contains(env.Message, " failed with response "):
+		outcome = "失败"
+		if detail == "" {
+			detail = failedResponse(env.Message)
+		}
 	}
 	return outcome, detail
 }
 
+// failedResponse 提取 "X failed with response 'Err'" 中引号内的错误码。
+func failedResponse(msg string) string {
+	_, after, ok := strings.Cut(msg, " failed with response ")
+	if !ok {
+		return ""
+	}
+	return strings.Trim(strings.TrimSpace(after), "'")
+}
+
 // ssoOutcome 解析 IDCS 审计负载(JSON 字符串):eventId 含 success/failure 定成败,
 // 失败时以其 message 作为原因说明。
 func ssoOutcome(raw, detail string) (string, string) {

internal/service/logevent_test.go

@@ -308,6 +308,14 @@ func TestParseLogEvent(t *testing.T) {
 			wantType:    "x",
 			wantOutcome: "失败",
 		},
+		{
+			name: "failed with response 判失败并提取错误码",
+			payload: `{"type":"com.oraclecloud.computeApi.LaunchInstance.begin","data":{
+				"message":"LaunchInstance failed with response 'NotAuthorizedOrNotFound'"}}`,
+			wantType:    "com.oraclecloud.computeApi.LaunchInstance.begin",
+			wantOutcome: "失败",
+			wantDetail:  "NotAuthorizedOrNotFound",
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {

internal/service/logrelay.go

@@ -1,6 +1,7 @@
 package service
 
 import (
+	"cmp"
 	"context"
 	"errors"
 	"fmt"
@@ -23,9 +24,11 @@ const (
 )
 
 // RelayCriticalEvents 是回传的关键事件清单(Connector Log Filter 与 P2 告警共用):
-// 实例生命周期、用户与凭据、区域订阅、策略变更、控制台登录。
+// 实例终止与电源操作、用户与凭据、区域订阅、策略变更、控制台登录。
+// 不含 LaunchInstance:创建以面板自身(手动/抢机反复尝试)发起为主,回传即噪声
+// (10 个 1min 抢机任务一天即可刷掉 2 万条上限),终止与电源操作才是外部风险信号。
 var RelayCriticalEvents = []string{
-	"LaunchInstance", "TerminateInstance", "InstanceAction",
+	"TerminateInstance", "InstanceAction",
 	"CreateUser", "DeleteUser", "UpdateUser",
 	"CreateApiKey", "DeleteApiKey", "UpdateUserCapabilities",
 	"CreateRegionSubscription",
@@ -46,7 +49,7 @@ var relayCriticalSet = func() map[string]bool {
 // 通知管理「云端事件」按此细分开关。
 func relayEventClass(name string) string {
 	switch name {
-	case "LaunchInstance", "TerminateInstance", "InstanceAction":
+	case "TerminateInstance", "InstanceAction":
 		return "instance"
 	case "CreateUser", "DeleteUser", "UpdateUser",
 		"CreateApiKey", "DeleteApiKey", "UpdateUserCapabilities":
@@ -313,24 +316,30 @@ func (s *LogEventService) teardownResources(ctx context.Context, cred oci.Creden
 
 // ---- P2 告警联动:解析出关键事件后经 Notifier 推送 ----
 
-// relayEventShortName 取 CloudEvents type 末段(com.oraclecloud.ComputeApi.LaunchInstance → LaunchInstance)。
+// relayEventShortName 取 CloudEvents type 中的事件短名:Audit v2 计算类事件带
+// .begin/.end 阶段后缀(com.oraclecloud.ComputeApi.LaunchInstance.end),先剥阶段再取末段。
 func relayEventShortName(eventType string) string {
-	if i := strings.LastIndex(eventType, "."); i >= 0 {
+	t := strings.TrimSuffix(strings.TrimSuffix(eventType, ".begin"), ".end")
-		return eventType[i+1:]
+	if i := strings.LastIndex(t, "."); i >= 0 {
+		return t[i+1:]
 	}
-	return eventType
+	return t
 }
 
 // criticalEventVars 判定关键事件并生成模板变量;非关键事件 ok 为 false。
+// 成对事件只推 .begin(携带操作者/IP/成败),.end 无操作者且信息重复,不再告警;
 // actor/ip/outcome/resource 缺失时兜底 —,detail 包装为独立行(空则不占行)。
 func criticalEventVars(alias string, p parsedEvent) (map[string]string, bool) {
+	if strings.HasSuffix(p.EventType, ".end") {
+		return nil, false
+	}
 	name := relayEventShortName(p.EventType)
 	if name == "" || !relayCriticalSet[name] {
 		return nil, false
 	}
 	return map[string]string{
 		"tenant": alias, "event": name,
-		"resource": orDash(p.ResourceName), "actor": orDash(p.Actor),
+		"resource": orDash(cmp.Or(p.ResourceName, p.Source)), "actor": orDash(p.Actor),
 		"ip": orDash(p.SourceIP), "outcome": orDash(p.Outcome),
 		"detail": detailLine(p.Detail),
 	}, true

internal/service/logrelay_test.go

@@ -339,10 +339,22 @@ func TestCriticalEventText(t *testing.T) {
 			wantOK: true,
 			want:   map[string]string{"event": "CreatePolicy", "detail": "\n允许发布到 ONS Topic"},
 		},
+		{
+			name: "begin 阶段剥后缀命中并回退 source 作资源",
+			event: parsedEvent{EventType: "com.oraclecloud.computeApi.TerminateInstance.begin",
+				Source: "instance-20260717-1445", Actor: "IT Team", SourceIP: "137.131.7.136", Outcome: "成功"},
+			wantOK: true,
+			want: map[string]string{"event": "TerminateInstance", "resource": "instance-20260717-1445",
+				"actor": "IT Team", "ip": "137.131.7.136", "outcome": "成功"},
+		},
+		{name: "end 阶段不重复告警",
+			event: parsedEvent{EventType: "com.oraclecloud.ComputeApi.TerminateInstance.end"}, wantOK: false},
+		{name: "LaunchInstance 已移出清单不告警",
+			event: parsedEvent{EventType: "com.oraclecloud.computeApi.LaunchInstance.begin"}, wantOK: false},
 		{name: "List 噪声不推", event: parsedEvent{EventType: "com.oraclecloud.ComputeApi.ListInstances"}, wantOK: false},
 		{name: "空类型不推", event: parsedEvent{}, wantOK: false},
-		{name: "短名直接命中", event: parsedEvent{EventType: "LaunchInstance"}, wantOK: true,
+		{name: "短名直接命中", event: parsedEvent{EventType: "InstanceAction"}, wantOK: true,
-			want: map[string]string{"event": "LaunchInstance"}},
+			want: map[string]string{"event": "InstanceAction"}},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -370,7 +382,7 @@ func TestRelayEventClass(t *testing.T) {
 		name  string
 		class string
 	}{
-		{"LaunchInstance", "instance"},
+		{"LaunchInstance", ""}, // 已移出回传清单,不归类
 		{"TerminateInstance", "instance"},
 		{"InstanceAction", "instance"},
 		{"CreateUser", "identity"},

internal/service/oauth.go

@@ -187,7 +187,7 @@ type externalIdentity struct {
 
 // HandleCallback 完成授权码回调:换取身份后,bind 模式写绑定、login 模式签发 JWT;
 // token 仅 login 模式非空;mode 尽力返回(state 无效时为空),供 api 决定错误回跳页面。
-func (o *OAuthService) HandleCallback(ctx context.Context, provider, state, code string) (token, display, mode string, err error) {
+func (o *OAuthService) HandleCallback(ctx context.Context, provider, state, code string) (token, username, mode string, err error) {
 	p, err := o.takeState(provider, state)
 	if err != nil {
 		return "", "", "", err
@@ -198,14 +198,14 @@ func (o *OAuthService) HandleCallback(ctx context.Context, provider, state, code
 	}
 	if p.mode == "bind" {
 		if err := o.bind(ctx, p.username, provider, ident); err != nil {
-			return "", ident.Display, p.mode, err
+			return "", p.username, p.mode, err
 		}
 		// 绑定属敏感变更:版本递增使旧令牌失效,同时为操作者签新令牌随回跳带回
 		token, _, err := o.auth.RevokeSessions(ctx, p.username)
-		return token, ident.Display, p.mode, err
+		return token, p.username, p.mode, err
 	}
-	token, display, err = o.loginByIdentity(ctx, provider, ident)
+	token, username, err = o.loginByIdentity(ctx, provider, ident)
-	return token, display, p.mode, err
+	return token, username, p.mode, err
 }
 
 // fetchIdentity 用授权码向 provider 换取稳定 subject 与展示名。
@@ -311,7 +311,7 @@ func (o *OAuthService) loginByIdentity(ctx context.Context, provider string, ide
 		return "", "", fmt.Errorf("find bound user: %w", err)
 	}
 	token, _, err := o.auth.signToken(user.Username, user.TokenVersion)
-	return token, ident.Display, err
+	return token, user.Username, err
 }
 
 // Identities 列出账号已绑定的外部身份。

internal/service/totp_oauth_test.go

@@ -169,12 +169,12 @@ func TestOAuthBindLoginUnbind(t *testing.T) {
 		t.Errorf("重复绑定 err = %v, want ErrOAuthBound", err)
 	}
 	// 已绑定身份可登录并拿到有效 JWT
-	token, display, err := o.loginByIdentity(ctx, "github", externalIdentity{Subject: "10086", Display: "octocat"})
+	token, loginUser, err := o.loginByIdentity(ctx, "github", externalIdentity{Subject: "10086", Display: "octocat"})
 	if err != nil || token == "" {
 		t.Fatalf("loginByIdentity: %v", err)
 	}
-	if display != "octocat" {
+	if loginUser != "admin" {
-		t.Errorf("display = %q", display)
+		t.Errorf("loginUser = %q, want admin", loginUser)
 	}
 	if username, err := auth.ParseToken(context.Background(), token); err != nil || username != "admin" {
 		t.Errorf("token 应属 admin, got %q (%v)", username, err)

internal/service/webconsole.go

@@ -46,6 +46,7 @@ type ConsoleSession struct {
 type ConsoleService struct {
 	configs      *OciConfigService
 	pollInterval time.Duration // 清理残留连接的轮询间隔，测试注入缩短
+	sessionTTL   time.Duration // 会话回收检查周期，测试注入缩短
 
 	mu       sync.Mutex
 	sessions map[string]*ConsoleSession
@@ -55,6 +56,7 @@ func NewConsoleService(configs *OciConfigService) *ConsoleService {
 	return &ConsoleService{
 		configs:      configs,
 		pollInterval: 2 * time.Second,
+		sessionTTL:   consoleSessionTTL,
 		sessions:     map[string]*ConsoleSession{},
 	}
 }
@@ -161,11 +163,12 @@ func (s *ConsoleService) storeSession(cfgID uint, instanceID, region, typ, connI
 	s.mu.Lock()
 	s.sessions[sess.ID] = sess
 	s.mu.Unlock()
-	time.AfterFunc(consoleSessionTTL, func() { s.expire(sess.ID) })
+	time.AfterFunc(s.sessionTTL, func() { s.expire(sess.ID) })
 	return sess
 }
 
-// expire TTL 到期回收：正在使用的会话跳过（连接断开后自然停止，无续期）。
+// expire TTL 到期回收：正在使用的会话跳过并重挂下一轮检查，
+// 连接断开后由后续轮次回收，避免会话与云端连接常驻到进程退出。
 func (s *ConsoleService) expire(id string) {
 	s.mu.Lock()
 	sess, ok := s.sessions[id]
@@ -173,6 +176,7 @@ func (s *ConsoleService) expire(id string) {
 		sess.mu.Lock()
 		if sess.inUse {
 			ok = false
+			time.AfterFunc(s.sessionTTL, func() { s.expire(id) })
 		} else {
 			delete(s.sessions, id)
 		}

internal/service/webconsole_test.go

@@ -116,3 +116,44 @@ func TestCreateConsoleSession(t *testing.T) {
 		})
 	}
 }
+
+// TestConsoleSessionExpire 验证过期回收:在用会话跳过本轮,断开后下一轮回收。
+func TestConsoleSessionExpire(t *testing.T) {
+	tests := []struct {
+		name      string
+		inUse     bool
+		wantAlive bool
+	}{
+		{name: "在用会话跳过回收", inUse: true, wantAlive: true},
+		{name: "空闲会话回收并删云端连接", inUse: false, wantAlive: false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			client := &consoleFakeClient{}
+			console, cfgID := newConsoleTestService(t, client)
+			sess, err := console.CreateSession(context.Background(), cfgID, "ocid1.instance.i", "", ConsoleTypeSerial)
+			if err != nil {
+				t.Fatalf("CreateSession: %v", err)
+			}
+			sess.MarkUse(tt.inUse)
+			console.expire(sess.ID)
+			if alive := console.Get(sess.ID) != nil; alive != tt.wantAlive {
+				t.Fatalf("session alive = %v, want %v", alive, tt.wantAlive)
+			}
+			if wantDel := !tt.wantAlive; (len(client.deleted) == 1) != wantDel {
+				t.Errorf("cloud connection deleted %v, want %v", client.deleted, wantDel)
+			}
+			if tt.inUse {
+				// 断开后下一轮回收(此前的缺陷:跳过后不再检查,会话常驻)
+				sess.MarkUse(false)
+				console.expire(sess.ID)
+				if console.Get(sess.ID) != nil {
+					t.Fatal("session still alive after idle expire round")
+				}
+				if len(client.deleted) != 1 {
+					t.Errorf("cloud connection not deleted after idle expire: %v", client.deleted)
+				}
+			}
+		})
+	}
+}