ai/docs/work-sync/AI_REQUEST_INSPECTOR_IMPLEMENTATION_REPORT_V1.md

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. 按真实漏项继续维护动作级白名单，普通保存和人工操作必须保留误捕获测试。