sub2api/openspec/changes/add-openai-compatible-prompt-audit/specs/prompt-input-guard/spec.md

ADDED Requirements

Requirement: 同步提示词门禁必须由显式配置启用

系统 SHALL 使用 enabled 与 blocking_enabled 表达关闭、异步只审计、同步审计并阻止三态。旧配置或缺失字段 MUST 归一为 blocking_enabled=false；系统 MUST 拒绝 enabled=false && blocking_enabled=true 的配置。

Scenario: 关闭提示词审计

• WHEN enabled=false
• THEN 有效模式 MUST 为 off
• THEN blocking_enabled MUST 被视为 false

Scenario: 启用异步审计

• WHEN enabled=true 且 blocking_enabled=false
• THEN 有效模式 MUST 为 async_audit
• THEN Guard 故障 MUST NOT 改变主请求结果

Scenario: 启用同步阻止

• WHEN enabled=true 且 blocking_enabled=true
• THEN 有效模式 MUST 为 blocking
• THEN 适用请求 MUST 等待 Guard 判定后才能进入账号选择、计费和上游阶段

Scenario: 保存非法开关组合

• WHEN 管理员保存 enabled=false 且 blocking_enabled=true
• THEN 后端 MUST 返回 400 和 prompt_guard_requires_audit_enabled

Requirement: 安全审计协调器必须保持两个引擎的独立语义

系统 SHALL 通过一个薄协调器把可信请求上下文交给现有内容审核和新增提示词审计。协调器 MUST 不转换两套风险分类、不共用事件表、不让提示词审计触发内容审核副作用，并 MUST 使用确定性的阻断优先级。

Scenario: 现有内容审核阻断

• WHEN 现有内容审核返回 Block
• THEN 客户端 MUST 继续收到升级前的状态码、错误码和文案
• THEN 提示词审计异步模式 MAY 继续完成自己的独立记录

Scenario: 仅提示词 Guard 阻断

• WHEN 现有内容审核允许但提示词 Guard 返回 Block
• THEN 客户端 MUST 收到 prompt_guard_blocked

Scenario: 两个引擎同时阻断

• WHEN 两个引擎都返回 Block
• THEN 现有内容审核错误语义 MUST 具有客户端响应优先级
• THEN 两个引擎 MUST 各自记录其结果和结构化日志

Requirement: 同步门禁必须位于外部副作用之前

系统 MUST 在鉴权和请求格式校验完成后、账号选择、账户并发、计费资格检查、任何预扣、上游连接和上游写入之前完成同步判定。被 Block 或 fail-closed 拒绝的请求 MUST 不产生这些下游副作用。

Scenario: HTTP 请求被 Guard 阻断

• WHEN 任一支持的 HTTP 模型请求得到 Block
• THEN 账号选择次数、计费检查/预扣次数和上游请求次数 MUST 均为 0
• THEN 流式请求 MUST 在拒绝前未写出 SSE 响应头或首字节

Scenario: Guard 不可用

• WHEN 同步模式下所有可用节点均失败
• THEN 请求 MUST 在任何账号、计费或上游副作用之前返回 503

Requirement: 同步门禁必须覆盖所有目标协议入口

系统 SHALL 覆盖现有内容审核已接入的所有用户文本入口，并通过结构测试防止后续路由绕过。至少包括 OpenAI Chat Completions、OpenAI Responses、Claude Messages、Gemini、OpenAI Images/Grok 媒体文本 prompt，以及 Responses WebSocket 首轮和后续轮次。

Scenario: OpenAI 兼容 HTTP 入口

• WHEN 客户端调用 Chat Completions 或 Responses 兼容入口
• THEN 系统 MUST 使用对应协议提取器并执行同一 Guard evaluator
• THEN 现有 OpenAI 请求和响应 envelope MUST 保持兼容

Scenario: Claude 或 Gemini 入口

• WHEN 客户端调用 Claude Messages 或 Gemini 入口
• THEN 系统 MUST 执行相同策略判定
• THEN 拒绝响应 MUST 使用该协议现有错误 envelope 和共享稳定 error_code

Scenario: 新增用户文本入口

• WHEN 后续代码新增一个可触发模型执行且包含用户文本的路由
• THEN 路由覆盖门禁 MUST 在缺少安全审计接线时失败

Requirement: 同步分片必须共享总预算并完整覆盖

系统 SHALL 以有序节点列表中首个启用节点的 timeout 作为一次同步 evaluation 的总预算。所有分片和节点故障切换 MUST 共享该 deadline；任一必要分片失败、超时或无合法结果时 MUST fail-closed。

Scenario: 所有分片均为安全

• WHEN 每个非空分片都在总预算内返回 Safe 或允许的 Warn
• THEN 请求 MAY 进入下一阶段

Scenario: 中间分片阻断

• WHEN 任一分片返回 Block
• THEN evaluator MAY 立即早停
• THEN 请求 MUST 被阻断且不得部分转发

Scenario: 最后一个必要分片失败

• WHEN 前面分片安全但最后一个必要分片超时或响应无效
• THEN 系统 MUST 返回 unavailable/invalid_response
• THEN 系统 MUST NOT 根据部分结果放行

Requirement: 同步节点故障切换必须有序且 fail-closed

系统 SHALL 按配置顺序尝试启用节点。连接失败、429、5xx 和超时 MAY 在总 deadline 尚有剩余时切换到下一节点；401/403、严格解析失败或耗尽节点 MUST 结束为不可用/非法响应。同步模式 MUST NOT 提供隐式 fail-open。

Scenario: 首节点暂时失败而次节点成功

• WHEN 首节点返回可重试错误且次节点在剩余预算内返回合法结果
• THEN 系统 MUST 使用次节点结果
• THEN failover 指标 MUST 增加

Scenario: 认证失败

• WHEN 节点返回 401 或 403
• THEN 系统 MUST 视为不可重试配置错误
• THEN 请求 MUST 返回 503 而不是按 Safe 放行

Scenario: 所有节点容量饱和

• WHEN 全局或每节点 bulkhead 均无法接受 evaluation
• THEN 系统 MUST 快速返回 prompt_guard_unavailable
• THEN 系统 MUST 不无限排队

Requirement: HTTP 拒绝必须保持协议兼容和稳定错误码

同步 Guard MUST 使用现有 Handler 的协议错误构造器和最小扩展，且只向客户端暴露通用消息、稳定 Prompt Guard code/reason 和 request ID。OpenAI/Claude MUST 在 error 对象的可选 code 字段携带稳定代码并保留原合法 type；Gemini MUST 保留数值 error.code 与 canonical status，并在 google.rpc.ErrorInfo.reason 携带稳定代码。响应 MUST 不包含风险正文、类别细节、内部节点地址或凭据。

Scenario: HTTP Block

• WHEN 同步 Guard 判定为 Block
• THEN HTTP 状态 MUST 为 403
• THEN error_code MUST 为 prompt_guard_blocked

Scenario: Gemini HTTP Block

• WHEN Gemini 入口的同步 Guard 判定为 Block
• THEN Google error envelope 的 error.code MUST 保持数值 403 且 status MUST 为对应 canonical status
• THEN error.details 中 ErrorInfo reason MUST 为 prompt_guard_blocked

Scenario: HTTP Guard 不可用

• WHEN 节点超时、连接失败、熔断或容量不足
• THEN HTTP 状态 MUST 为 503
• THEN error_code MUST 为 prompt_guard_unavailable

Scenario: HTTP Guard 响应非法

• WHEN Guard 输出无法严格解析
• THEN HTTP 状态 MUST 为 503
• THEN error_code MUST 为 prompt_guard_invalid_response

Requirement: Responses WebSocket 必须对每个 response.create 执行门禁

系统 SHALL 在 WebSocket 首次和后续每个 response.create 帧进入本轮用户/账号并发、计费和上游发送之前执行同步 Guard。一次安全结果 MUST NOT 被复用于不同的后续帧。

Scenario: 首轮 Block

• WHEN 首个 response.create 被判定为 Block
• THEN 服务端 MUST 不建立本轮上游请求或计费记录
• THEN 服务端 MUST 使用 close code 4403 和 reason prompt_guard_blocked 关闭连接

Scenario: 后续轮次 Block

• WHEN 已建立连接的后续 response.create 被判定为 Block
• THEN 该帧 MUST 不发送给上游且不得创建本轮计费记录
• THEN 服务端 MUST 使用 4403 关闭连接并记录 stage=subsequent_turn

Scenario: WebSocket Guard 不可用

• WHEN 首轮或后续轮次 Guard 不可用或响应非法
• THEN 服务端 MUST 使用 close code 1013
• THEN reason MUST 为 prompt_guard_unavailable 或 prompt_guard_invalid_response

Requirement: 同步结果必须复用到脱敏事件且不得重复扫描

系统 SHALL 在一次同步 evaluation 后把已得到的归一化结果交给独立记录路径。记录路径 MUST NOT 重新调用 Guard，也 MUST NOT 需要完整提示词正文；同步结果最多对应一个任务事实和一个按存储策略决定的事件。

Scenario: 同步 Block 被记录

• WHEN evaluator 已得到 Block
• THEN 系统 MUST 用脱敏快照和既有结果创建 done 任务及风险事件
• THEN Guard 调用次数 MUST 等于 evaluation 实际需要的节点/分片次数，而不是因记录而增加

Scenario: 同步 Allow 且不保存 Pass

• WHEN evaluator 得到 Allow 且 store_pass_events=false
• THEN 系统 MAY 只保存任务/指标而不创建 Pass 事件

Requirement: 配置必须以版本化快照发布到请求热路径

系统 SHALL 为提示词审计配置维护单调递增 config_version、updated_at、updated_by 和 change_summary。保存后 MUST 原子替换本实例快照并通过 Redis 发布失效通知；请求热路径 MUST 读取内存快照而不是逐请求查询数据库。

Scenario: 多实例收到配置更新

• WHEN 管理员成功保存新配置
• THEN 保存实例 MUST 立即安装新版本并发布 Redis 失效通知
• THEN 其他实例 MUST 重新加载并原子替换快照

Scenario: 两个管理员并发保存配置

• WHEN 两个保存请求携带相同 expected_config_version 且第一个已提交新版本
• THEN 第二个请求 MUST 返回 409 prompt_audit_config_conflict
• THEN 第二个请求 MUST NOT 静默覆盖第一个请求或复用相同 config_version

Scenario: Redis 通知不可用

• WHEN 配置已保存但 Redis publish 失败
• THEN 系统 MUST 记录 prompt_guard.config_reload_degraded
• THEN 其他实例 MUST 通过有界 TTL 刷新最终获得新版本

Scenario: 冷启动无法加载严格配置

• WHEN 实例冷启动且无法获得有效配置快照
• THEN 对已知要求同步阻止的适用请求 MUST fail-closed
• THEN 运行态 MUST 暴露配置加载错误

Requirement: Guard 关键路径必须可观测且不得泄密

系统 SHALL 输出稳定结构化事件并提供计数/耗时指标。日志至少 MUST 覆盖配置更新/加载/降级、evaluation 开始、Allow、Block、失败、结果记录失败、异步投递/丢弃、Worker 处理/重试/失败、逐分片开始/完成/失败、分片聚合和滞留回收。

Scenario: 同步请求被阻断

• WHEN Guard 阻断一个请求
• THEN 日志 MUST 包含 request_id、user_id、api_key_id、group_id、protocol、endpoint、model、config_version、guard_endpoint_id、decision、action、chunk_total、latency_ms、status 和 error_code
• THEN 日志 MUST 明确包含 upstream_dispatched=false 和 billing_preconsumed=false 或目标项目等价字段

Scenario: 检查日志敏感字段

• WHEN 测试捕获提示词审计日志
• THEN 日志中 MUST 不包含原始提示词、API Key、Authorization、完整 Guard URL query 或 Redis 载荷

Requirement: 禁用或回滚同步阻止必须即时恢复异步行为

系统 SHALL 支持仅通过关闭 blocking_enabled 回到异步只审计，无需删除表、清空历史事件或停止现有内容审核。

Scenario: 管理员关闭同步阻止

• WHEN blocking_enabled 从 true 保存为 false 且新配置已生效
• THEN 后续适用请求 MUST 不再等待 Guard 同步结果
• THEN enabled=true 时后续请求 MUST 改为异步投递
• THEN 历史任务和事件 MUST 保留