# AI 请求参数检查器实施报告 V1

> 实施日期：2026-07-16  
> 状态：用户端与管理端已上线，后端统一 Provider Trace 待后续增强  
> 目标：让所有 AI 生成、审核、质检、预检与合成入口具备可追溯的页面参数视图。

## 1. 用户入口

登录用户端或管理端后，页面右侧固定显示“AI 请求参数”入口。面板默认关闭，点击后从右侧滑出；移动端改为全屏抽屉并保留横向请求历史。两端复用同一个共享组件和同一套路由规则，避免实现漂移。

抽屉支持：

- 最近 30 条会话级请求历史。
- 请求状态、HTTP 方法、接口路径、时间与 Request ID。
- 完整 `path_params`、`query_params` 与明文 `body`。
- 请求预览/预检的完整后端响应。
- 正式生成返回的 `task.input_json`、Generation Plan、Provider 路由、最终请求与成本证据。
- 一键复制与清空历史。

## 2. 捕获位置

检查器接入 `UserApiClient.request()` 与管理端 `ApiClient.request()`，在应用层加密之前复制一份仅用于诊断的安全快照，因此可以看到页面实际提交的可读参数，又不会改变原请求。

当前动作级白名单覆盖：

- Provider Lab 与提示词直出。
- 原著分析、改编圣经、角色/场景/道具提取与 Prompt 优化。
- 分集、场景剧本、分镜及其请求预览。
- 人物图片、人物三视图、角色元素测试与视觉质检。
- 关键帧、语音、单句 TTS 重试、字幕、音乐与视频生成。
- 视频预检、成本估算、自动 QC、重试与成片合成。
- 管理端 Provider 实测、小说方案/IP圣经/章节任务与爆款案例 AI 分析。

普通项目保存、人工审核、素材绑定、候选选择和确认操作不进入历史，避免诊断面板被非 AI 写请求污染。

## 3. 数据安全

- `password`、Authorization、API Key、Token、Secret 自动隐藏。
- Base64 与二进制正文不写入面板，只保留文件名、MIME、字节数或字符数摘要。
- 历史仅写入浏览器 `sessionStorage`，最多 30 条，不进入业务数据库。
- 检查器故障或浏览器存储已满时，不得阻断真实生成。

## 4. 两层事实边界

### 页面提交事实

始终记录前端实际送入 API 的路径参数、查询参数和请求体。这一层适合检查漏参、错参、Provider 选择与人工覆盖值。

### 后端执行事实

后端返回请求预览、Task、Generation Plan、Provider 路由或成本信息时，检查器同步展示。这一层适合检查 Prompt 编译、参考图、模型参数、回退与成本。

若旧接口没有返回执行证据，面板会明确显示“尚未返回”，不会把前端请求体伪装成最终 Provider 载荷。后续如需覆盖所有同步旧接口，应增加统一的后端 Provider Trace，而不是在前端猜测。

## 5. 验证

- `ai-request-inspector.spec.ts`：36/36 通过。
- User App 与 Admin TypeScript、Vite 生产构建：通过。
- `git diff --check`：通过。
- Nginx 已提供本次新构建静态资源。
- Backend 健康检查：`ok`。
- 本次验证未触发任何付费 AI 调用。

## 6. 后续

1. 在后端统一 Provider 执行层增加脱敏 Trace ID 与最终载荷摘要。
2. 让同步旧接口也能通过 Request ID 查询 Provider Trace。
3. 将请求记录与不可变 Generation Plan、ProviderLog 和成品 QC 建立可点击关联。
4. 按真实漏项继续维护动作级白名单，普通保存和人工操作必须保留误捕获测试。