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

## ADDED Requirements

### Requirement: 提示词审计必须是独立且默认关闭的安全审计引擎
系统 SHALL 在现有内容审核之外提供独立的提示词审计引擎。新引擎 MUST 拥有独立配置、运行态、任务、事件和开关，并 MUST 默认关闭；现有 OpenAI Moderations 内容审核的配置、判定、关键词、Hash、邮件、自动封号、日志表和清理行为 MUST NOT 因本能力而改变。

#### Scenario: 升级后未启用新引擎
- **WHEN** 系统完成包含本能力的升级且管理员尚未保存提示词审计配置
- **THEN** 所有模型请求 MUST 继续按升级前的内容审核和转发链路执行
- **THEN** 系统 MUST NOT 创建提示词审计任务、写入提示词审计事件或调用外部 Guard

#### Scenario: 两个审计引擎同时启用
- **WHEN** 现有内容审核和新增提示词审计都已启用
- **THEN** 两个引擎 MUST 使用各自的配置与风险语义独立执行
- **THEN** 提示词审计命中 MUST NOT 自动触发现有内容审核的邮件、封号或 Hash 黑名单副作用

### Requirement: 提示词审计节点必须使用 OpenAI 兼容协议
系统 SHALL 仅支持通过 OpenAI 兼容 Chat Completions 接口调用提示词审计节点。节点配置 MUST 支持名称、Base URL、API Key、Model、超时、单片输入上限、启用状态和有序优先级；默认模型 MUST 为 `sileader/qwen3guard:0.6b`。

#### Scenario: Worker 调用已配置节点
- **WHEN** Worker 领取到可处理任务并选择一个启用节点
- **THEN** 系统 MUST 向 `{base_url}/v1/chat/completions` 发送请求
- **THEN** 请求 MUST 使用 `role=user`、`temperature=0`、确定性的输出限制和管理员配置的模型
- **THEN** 系统 MUST NOT 调用旧的 `/v1/scan/prompt` 或 `llm_guard` 专用协议

#### Scenario: 管理员保存未填写模型的节点
- **WHEN** 管理员保存一个 Base URL 有效但 Model 为空的节点
- **THEN** 系统 MUST 将节点模型归一为 `sileader/qwen3guard:0.6b`

#### Scenario: 管理员探测节点
- **WHEN** 管理员请求探测一个节点
- **THEN** 后端 MUST 使用服务端网络环境执行真实的认证与模型连通性探测
- **THEN** 响应 MUST 包含成功状态、稳定错误码、HTTP 状态、耗时、是否可重试和检查时间
- **THEN** 响应 MUST NOT 回显 API Key

### Requirement: 审计节点凭据必须受到安全保护且出站目标由管理员负责
系统 MUST 使用现有 SecretEncryptor 加密持久化节点 API Key，并 MUST 对响应体实施大小限制。节点地址及其网络目标由管理员自行配置和负责；系统 MUST NOT 按公网、私网、回环、link-local、元数据、保留地址或 DNS 解析结果阻止保存、探测和实际调用，也 MUST NOT 禁止 HTTP 或正常 HTTP 重定向。完整凭据只允许短暂存在于管理员写入请求、前端未持久化输入内存、服务端解密内存和发往 Guard 的 Authorization Header；它们以及 URL query、提示词正文 MUST NOT 出现在日志、错误响应、管理读取响应或前端持久化/调试状态中。

#### Scenario: 保存带 API Key 的节点
- **WHEN** 管理员保存一个包含 API Key 的节点
- **THEN** settings 中 MUST 只保存加密密文和是否已配置标记
- **THEN** 后续读取配置 MUST 只返回 `has_token=true` 或等价状态

#### Scenario: 保存管理员配置的内网或特殊地址
- **WHEN** Base URL 使用 HTTP(S) 且指向私网、回环、link-local、元数据、保留地址或解析到这些地址的域名
- **THEN** 系统 MUST 接受该节点配置并从服务端网络环境执行探测和实际调用
- **THEN** 系统 MUST NOT 对 DNS 结果进行地址类别拦截

#### Scenario: 节点返回重定向或超大响应
- **WHEN** Guard 返回正常 HTTP 重定向
- **THEN** 系统 MUST 使用标准 HTTP 客户端行为跟随重定向
- **WHEN** Guard 返回超过配置上限的响应体
- **THEN** 系统 MUST 将响应判定为无效或不可用

### Requirement: 系统必须按协议提取用户输入提示词快照
系统 SHALL 从目标项目所有已支持、包含用户文本的模型入口提取提示词快照。快照 MUST 包含 request ID、user ID、用户名、用户邮箱、API key ID/名称、group ID/名称、provider、endpoint、protocol、model、提示词 Hash、脱敏预览、Unicode 字符数和消息数量；文本审计 MUST 优先扫描最新用户输入，同时完整覆盖需要审计的历史用户文本。

#### Scenario: 提取 OpenAI Chat Completions 输入
- **WHEN** `/v1/chat/completions` 或等价兼容入口包含一个或多个 `role=user` 消息
- **THEN** 系统 MUST 提取用户文本内容并把最新用户输入置于扫描顺序最前
- **THEN** 系统 MUST 不把 assistant 或 tool 输出当作用户提示词主体

#### Scenario: 提取 OpenAI Responses 输入
- **WHEN** `/v1/responses` 请求使用字符串、消息数组或内容块表达用户输入
- **THEN** 系统 MUST 提取其中的用户文本并保留 Responses 协议标识

#### Scenario: 提取 Claude 和 Gemini 输入
- **WHEN** Claude Messages 或 Gemini 兼容入口包含用户角色文本
- **THEN** 系统 MUST 提取可审计文本并保留真实 protocol、endpoint 和 model

#### Scenario: 提取图像或媒体生成提示词
- **WHEN** OpenAI Images、Grok 媒体或目标项目其他生成入口包含文本 prompt
- **THEN** 新引擎 MUST 审计文本 prompt
- **THEN** 新引擎 MUST NOT 把图片二进制、base64 图片或远程图片内容发送给 Qwen3Guard
- **THEN** 图片内容审核 MUST 继续由现有内容审核引擎负责

#### Scenario: 请求没有用户文本
- **WHEN** 请求体有效但没有可审计的用户文本
- **THEN** 系统 MUST 跳过提示词任务并记录稳定的 skipped reason

### Requirement: 提示词数据库快照必须脱敏且不可恢复原文
系统 SHALL 在写入数据库前计算 SHA-256 Hash 和脱敏裁剪预览。PostgreSQL、结构化日志、管理 API 和前端 MUST NOT 保存或返回完整原始提示词；用于实际扫描的正文只允许保存在请求内存或 Redis 短 TTL 载荷中。

#### Scenario: 创建异步任务
- **WHEN** 系统为用户输入创建异步审计任务
- **THEN** `prompt_audit_jobs` MUST 保存 Hash、脱敏预览、字符数、消息数、分列的用户/API Key 展示快照和可关联请求上下文
- **THEN** 表中 MUST 不存在 raw_prompt、payload 或等价原文字段

#### Scenario: 管理员查看事件详情
- **WHEN** 管理员打开提示词审计事件详情
- **THEN** 页面和 API MUST 只展示脱敏预览、Hash、分类、结构化风险摘要、证据摘要和技术元数据
- **THEN** 任何证据片段 MUST 经过脱敏、长度限制并包含不可逆 Hash，而不是完整命中正文

### Requirement: 异步审计必须使用持久任务和短期 Redis 载荷
系统 SHALL 使用 PostgreSQL `prompt_audit_jobs` 作为任务事实源，并使用 Redis 保存默认 30 分钟 TTL 的完整扫描正文。异步任务投递 MUST 不阻塞或改变主模型请求结果。

#### Scenario: 成功投递异步任务
- **WHEN** 提示词审计处于 async_audit、请求在审计范围内且队列未满
- **THEN** 系统 MUST 先创建不可被 Worker 领取的 staging 任务
- **THEN** 系统 MUST 成功写入 Redis 载荷后再把任务发布为 queued
- **THEN** 主请求 MUST 继续进入现有网关链路

#### Scenario: Redis 载荷写入失败
- **WHEN** 数据库任务已创建但 Redis 载荷写入失败
- **THEN** 系统 MUST 将任务标记为 failed 或保持可清理的 staging 状态
- **THEN** 系统 MUST 输出 `prompt_audit.enqueue_dropped` 和稳定错误码
- **THEN** 主模型请求 MUST 不受影响

#### Scenario: 队列达到容量上限
- **WHEN** queued、retry、processing 和 staging 活跃任务达到配置容量
- **THEN** 系统 MUST 拒绝创建新的异步任务并记录 `reason=queue_full`
- **THEN** 主模型请求 MUST 继续转发

#### Scenario: 多实例同时争抢最后队列容量
- **WHEN** 多个实例并发入队且剩余容量不足以容纳全部请求
- **THEN** active count 检查与 staging INSERT MUST 在同一数据库准入锁事务中串行化
- **THEN** 已接受的 active jobs MUST NOT 超过该配置快照的 queue_capacity
- **THEN** 未获准任务 MUST 按 queue_full 或 queue_admission_busy 丢弃且不影响主请求

### Requirement: 进程内 Worker 必须可靠消费持久任务
系统 SHALL 在主服务进程内启动可配置数量的 Worker。多实例 Worker MUST 通过 PostgreSQL 原子领取任务，并为每次领取生成单调递增的 claim version fencing token；租约刷新、事件提交和终态更新 MUST 校验该 token。系统还 MUST 支持重试退避、processing 租约刷新、滞留任务回收、最大尝试次数和优雅关闭。

#### Scenario: 多 Worker 并发领取任务
- **WHEN** 多个进程或 Worker 同时寻找可执行任务
- **THEN** 每个任务 MUST 只被一个 Worker 原子领取
- **THEN** 领取过程 MUST 使用数据库行锁/条件更新或等价的无重复执行机制

#### Scenario: 已回收的旧 Worker 恢复
- **WHEN** Worker A 的 processing 租约已被回收且任务随后由 Worker B 以更高 claim version 重新领取
- **THEN** Worker A 的租约刷新、事件写入和终态更新 MUST 因 claim version 不匹配而失败
- **THEN** Worker A MUST NOT 覆盖 Worker B 的任务状态或创建重复事件

#### Scenario: 可重试节点故障
- **WHEN** Guard 返回 429、5xx、连接失败或超时且任务仍有剩余尝试次数
- **THEN** Worker MUST 将任务置为 retry 并设置有界退避的 next_attempt_at

#### Scenario: 不可重试错误或达到最大尝试次数
- **WHEN** Guard 返回认证失败、严格解析失败或任务达到最大尝试次数
- **THEN** Worker MUST 将任务标记为 failed 并保存脱敏后的稳定错误码
- **THEN** Redis 载荷 MUST 被删除或等待短 TTL 自动清理

#### Scenario: 回收滞留 processing 任务
- **WHEN** processing 任务的租约超过允许时长
- **THEN** 系统 MUST 按剩余尝试次数把任务回收到 retry 或标记 failed
- **THEN** 系统 MUST 输出可关联 job ID 的回收日志

#### Scenario: Worker 启动失败
- **WHEN** 数据库、Redis、配置或加密依赖导致 Worker 无法启动
- **THEN** 主 API MUST 继续提供非提示词审计能力
- **THEN** 运行态 MUST 显示 error/degraded 和稳定错误码，而不是显示健康

### Requirement: Qwen3Guard 返回必须被严格归一化
系统 SHALL 严格解析单一 `Safety` 行和单一 `Categories` 行，并支持 Violent、Non-violent Illegal Acts、Sexual Content or Sexual Acts、PII、Suicide & Self-Harm、Unethical Acts、Politically Sensitive Topics、Copyright Violation、Jailbreak 九类输入风险。额外非空说明、重复字段、未知 Safety 或无法解析响应 MUST 视为 invalid_response。

#### Scenario: Safe 结果
- **WHEN** Guard 返回 `Safety: Safe`
- **THEN** 归一化结果 MUST 为 pass/low/Allow

#### Scenario: Controversial 结果
- **WHEN** Guard 返回 `Safety: Controversial`
- **THEN** 默认结果 MUST 为 flag/Warn
- **THEN** 命中已启用的 Jailbreak、PII 或 Suicide & Self-Harm 时 MUST 提升为 critical/Block

#### Scenario: Unsafe 结果
- **WHEN** Guard 返回 `Safety: Unsafe` 且命中至少一个已启用类别
- **THEN** 结果 MUST 为 critical/Block

#### Scenario: Unsafe 包含未知类别
- **WHEN** Guard 返回 Unsafe 但类别未知或不可映射
- **THEN** 系统 MUST 记录 `unknown_unsafe` 并保持 Block 语义

#### Scenario: 严格响应解析失败
- **WHEN** Guard 响应缺少字段、包含重复字段、出现额外非空说明或 Safety 不在允许枚举中
- **THEN** 系统 MUST 返回 `prompt_guard_invalid_response`
- **THEN** 系统 MUST NOT 把该结果伪装为 Safe

### Requirement: 长提示词必须完整进行 Unicode 分片审计
系统 SHALL 按 Unicode rune 而不是字节对提示词分片。最新用户输入 MUST 作为优先片段，其他输入按确定顺序完整覆盖；异步任务必须在每片开始前刷新 processing 租约，并为每片开始、完成、失败及最终聚合输出不含正文的结构化日志。

#### Scenario: 输入超过节点单片上限
- **WHEN** 提示词 Unicode 字符数超过节点 input_limit
- **THEN** 系统 MUST 生成覆盖全部非空文本的连续分片
- **THEN** 任一分片 Block MUST 使聚合结果为 Block
- **THEN** 只有全部必要分片成功后才能产生 Allow

#### Scenario: 最新输入包含风险
- **WHEN** 最新用户输入位于长会话尾部并包含 Block 风险
- **THEN** 该输入 MUST 在历史文本之前接受扫描
- **THEN** 同步模式 MAY 在确认 Block 后停止后续分片，但 MUST NOT 部分放行

#### Scenario: 多分片扫描完成
- **WHEN** 一个提示词被拆成多个分片并完成聚合
- **THEN** 日志 MUST 包含 chunk_index、chunk_total、chunk_chars、input_chars、input_limit、guard endpoint、action 和 latency
- **THEN** 日志 MUST NOT 包含分片正文、脱敏前证据或内部优先级分隔符

### Requirement: 审计事件必须独立、可关联且可安全管理
系统 SHALL 把归一化结果写入 `prompt_audit_events`，并支持是否保存 Pass 事件。事件 MUST 包含请求上下文、分列的用户名/邮箱/API Key 名称快照、脱敏提示词快照、decision、risk_level、action、分类、scanner、证据、策略、节点、配置版本、分片数和耗时；管理 DTO MUST 从这些事实确定性派生结构化 `issue_summaries`，不得复制保存第二套风险事实。

#### Scenario: 风险事件被记录
- **WHEN** Worker 或同步 Guard 得到 flag/critical 结果
- **THEN** 系统 MUST 创建独立提示词审计事件
- **THEN** 事件 MUST 可通过 request_id、user_id、api_key_id、group_id 和 prompt_hash 检索

#### Scenario: Pass 事件存储关闭
- **WHEN** 结果为 pass 且 store_pass_events=false
- **THEN** 系统 MUST 完成任务但 MAY 不创建事件

#### Scenario: 同步结果写入失败
- **WHEN** 同步 Guard 已完成判定但事件持久化失败
- **THEN** 系统 MUST 输出 `prompt_guard.result_record_failed`
- **THEN** 持久化失败 MUST NOT 把已确定的 Allow 改成 Block，也 MUST NOT 撤销已确定的 Block

### Requirement: 提示词审计运行态必须反映真实依赖和处理状态
系统 SHALL 提供运行态接口，返回有效模式、期望/生效配置版本、配置加载时间与错误、Worker 心跳、队列容量与各状态数量、处理/失败统计、最近错误、节点连通性、数据库/Redis 状态和同步 Guard 指标。

#### Scenario: 管理员查询健康运行态
- **WHEN** Worker 正常心跳、数据库与 Redis 可用且至少一个节点探测成功
- **THEN** 运行态 MUST 显示 running/ok 和真实统计值

#### Scenario: Redis 不可用
- **WHEN** 提示词审计已启用但 Redis 载荷存储不可用
- **THEN** 异步运行态 MUST 显示 error 或 degraded
- **THEN** 页面 MUST NOT 仅因 Base URL 已配置而显示健康

### Requirement: 管理员必须能够查询和安全删除提示词审计事件
系统 SHALL 提供分页列表、详情、单条删除、批量 ID 删除和按筛选删除。筛选 MUST 支持 decision、risk level、endpoint、group、user、API key、request ID、prompt Hash、关键字和时间范围。

#### Scenario: 按筛选查询事件
- **WHEN** 管理员提交一个或多个受支持筛选条件
- **THEN** 系统 MUST 返回稳定排序的分页事件和总数

#### Scenario: 预览按筛选删除
- **WHEN** 管理员提交包含明确时间范围的删除筛选
- **THEN** 系统 MUST 返回 matched_count、规范化筛选摘要、snapshot_max_id、filter_hash 和绑定当前管理员且短期有效的 confirmation_token
- **THEN** 系统 MUST 不立即删除数据

#### Scenario: 确认按筛选删除
- **WHEN** 管理员提交相同筛选、有效 filter_hash、未过期 confirmation_token 和显式 confirm=true
- **THEN** 系统 MUST 只分批删除匹配且 id 不高于预览 snapshot_max_id 的事件，以及已无事件引用的孤立任务
- **THEN** 系统 MUST 清理相关 Redis 载荷并写入管理操作审计

#### Scenario: 伪造或重放其他管理员的删除确认
- **WHEN** confirmation_token 无法认证、已过期、操作者不匹配、Hash 不匹配或缺失
- **THEN** 系统 MUST 拒绝删除并返回稳定错误码
- **THEN** 客户端自行计算 filter_hash MUST NOT 绕过 delete-preview

#### Scenario: 无时间范围的大范围删除
- **WHEN** 管理员尝试按筛选删除但未提供明确时间范围
- **THEN** 系统 MUST 拒绝操作并返回稳定错误码