PRD：Expert Portal — 与 AI 迭代改进草稿文件（图片/PDF/Excel），满意后再发给 client
| 状态 | Draft — 待评审 |
| Owner | Franky（产品） |
| 日期 | 2026-07-09 |
| 交互载体 | 复用现有「Ask Specialist」侧聊（SideChatPanel）+ 草稿附件策展区（产品决策已确认） |
| P0 前置 | #4089（侧聊无法产出文件附件，OPEN）· 设计任务 #4092 |
| 关联 | #4153（幻觉附件 + 双开关不一致）· #3944（文件工具集，已关）· #3501（agent 文件存储范围，P3 未决）· #1621（侧聊内部性不变量） |
| 姊妹 PRD | Slack per-Specialist App · WhatsApp 1:1 号码 |
1. 问题陈述
客户会要求 Specialist 生成文件（图片 / PDF / Excel / PPT 等）。在 HITL 模型下，这些产物先以 AI 草稿附件的形式进入 Expert 队列。今天 Expert 的把关工具 是断裂的，存在三个缺口：
- 迭代不能产文件：Expert 想让 AI 改文件（换配色、补一页、改数据），唯一的对话工具「Ask Specialist」侧聊产不出文件（#4089：consult 路径缺
ATTACHMENT_PROTOCOL注入与产物提取——AI 要么口头承诺再收回，要么直接说做不到）。 - 产物进不了草稿：即便侧聊将来能产文件，也没有任何「采纳到草稿」的动作——Expert 只能手动下载再用回形针（paperclip）重新上传，且 AI 产物与手动上传是两套互不相通的模型。
- 满意度把关缺工具：草稿附件不可移除/替换、无版本概念；更糟的是发送前没有"文案-附件一致性"校验——#4153 的生产事故正是 Expert 放行了一条"声称附件在上方"却根本没有附件的草稿（置信 90%、LOW 风险，审核界面零提示）。
结果：文件类请求要么在 Expert 手里断掉，要么带着错误/幻觉发给客户，侵蚀「AI + 人类专家」的核心信任。
2. 目标
- G1 — 不离开队列完成迭代：Expert 在 Expert portal 内与 AI 迭代文件任意轮次，全程无需下载/外部工具。度量：文件迭代会话中外部往返（下载→重传）次数 = 0。
- G2 — 一键采纳：侧聊产物一次点击进入草稿附件区；采纳→发送零手动搬运。度量：采纳动作成功率 ≥ 99%；文件类草稿从"开始迭代"到"发送"的中位时长可测并下降。
- G3 — 发送即所见：客户收到的文件 = Expert 最后策展确认的版本，任何中间版本/侧聊内容绝不外泄。度量：内部性回归测试（#1621 族）100% 通过；中间版本外泄事故 = 0。
- G4 — 杜绝幻觉附件放行：草稿文案引用附件而附件区为空 → 发送前 100% 拦截（阻断或强提示）。度量：拦截器触发计数；#4153 类事故复发 = 0。
- G5 — 可观测：迭代轮次、采纳/替换/拦截次数、文件生成 token 成本按
osa_id归集可查。
3. 非目标（v1）
- 客户可见的迭代过程 — 侧聊与中间版本恒为 internal（
isInternal:true），客户只看到最终发送的版本。 - 专属文件工作台 — v1 复用侧聊；独立的"文件迭代面板/版本树 UI"列为 v2 演进。
- 跨会话文件库 / agent 文件系统浏览 — 依赖 #3501 的存储范围决策（per-agent vs per-org vs per-conversation），未决前不做。
- 文件的在线精细编辑（如 Excel 单元格级编辑器）— v1 的编辑模型是对话式重生成，不是编辑器。
- 修复 #4089 本身 — 它是本 PRD 的 P0 前置，按其自身 issue/设计任务（#4092）推进，此处只引用不重复立项。
4. 用户故事
Expert（核心角色）
- 作为 Expert，当草稿带着 AI 生成的文件时，我想直接对 AI 说"把第二页的数据改成最新的"，并拿到新版本文件，而不是自己动手重做。
- 作为 Expert，我想把侧聊里满意的那一版一键采纳进草稿附件区，替换掉旧版。
- 作为 Expert，我想看清草稿附件区里每个文件的来源（AI 生成 / 我上传），并能移除任何一个。
- 作为 Expert，如果草稿文字说"附件在此"而实际没有附件，我希望系统在我点 Accept & send 之前拦住我。
- 作为 Expert，我想在发送前预览每个附件的实际内容（而不是只看文件名）。
Client 6. 作为客户成员，我只会收到 Expert 最终确认的文件版本——不会看到中间稿、不会看到 Expert 和 AI 的讨论。
Ops（SuperAdmin / AM） 7. 作为 ops，我想看到文件迭代的用量与成本（生成次数、token、按 org × specialist 归集），评估该能力的 ROI。
5. UX 流程
5.1 迭代（发生在现有侧聊内）
入口 A（改进已有产物）：草稿附件 chip 上「与 AI 改进此文件 ▸」
→ 打开 Ask Specialist 侧聊，自动带上该文 件与草稿上下文
入口 B（从零生成）：Expert 在侧聊直接要求"生成一份 XX 的 PDF"
迭代：Expert 每轮给出修改意见 → AI 回复 + 新版本文件（消息级附件，
SideChatPanel 已有 AttachmentList 渲染能力）
失败/超时 → 明确报错文案，绝不出现"已生成"却无附件的回复（对齐 #4153 反幻觉要求）
5.2 采纳（新增动作，本 PRD 核心）
- 侧聊中每个 AI 产出的文件附件旁新增 「采纳到草稿」 按钮。
- 点击 → 该文件进入草稿附件策展区：
- 与草稿现有附件同名/同类型 → 默认替换（旧版仍留在侧聊历史，可再采纳换回）；
- 否则 → 追加；
- 每次采纳/替换写审计日志（谁、何时、替换了哪个版本）。
- 草稿附件策展区（Accept & send 上方）：每个附件显示 来源徽标（AI 生成 ✨ / Expert 上传 📎）、文件名、大小、预览入口、移除按钮。AI 产物与 paperclip 手动上传统一在同一列表中管理。
5.3 发送（现有把关点，加一道校验）
- Accept & send 携带策展区当前的附件集（现有 release 通路已接受
attachments并传给dispatchExpertReply，四渠道派发就绪）。 - 发送前一致性校验（新增）：若草稿文案引用了附件（"attached / 附件 / 见下图 / find the image…" 等）而策展区为空 → 阻断发送 + 提示「文案提到了附件，但当前没有任何附件——请采纳文件或修改文案」；反向（有附件但文案未提及）仅弱提示不阻断。
- 版本语义（v1 轻量）：侧聊历史天然保留每一版；策展区始终只有"当前版"；换版 = 回侧聊重新采纳。正式版本列表 + 一键回退为 P1。
5.4 文案（v1）
| 位置 | 文案 |
|---|---|
| 附件 chip 动作 | 与 AI 改进此文件 |
| 侧聊附件动作 | 采纳到草稿 |
| 采纳成功 toast | 已更新草稿附件：{filename} |
| 一致性拦截 | 草稿文案提到了附件，但当前没有任何附件。请先采纳文件，或修改文案。 |
| 来源徽标 | AI 生成 / Expert 上传 |
6. 需求
Must-have（P0）
R1 — 侧聊能产文件（引用 #4089，不重复立项）。 本 PRD 的一切建立在 consult 路径能产出真实 HW_ATTACHMENT 产物之上。验收以 #4089 自身为准（含流式路径、#4059 结构化输出对齐、fail-open：渲染失败不得吞掉文字回复）。
R2 — 采纳到草稿。 侧聊 AI 附件上的「采纳到草稿」把该产物（R2 storageKey 引用，不复制字节）写入草稿的附件集合。
- Given 侧聊产出文件 F2，草稿已有同名文件 F1，when Expert 采纳 F2，then 草稿附件区 F1 被 F2 替换，审计记录 (expert, 时间, F1→F2)；F1 仍可从侧聊历史再次采纳。
- Given 草稿无同类附件，then 采纳为追加。
- 幂等：重复点击同一文件的采纳不产生重复附件。
R3 — 草稿附件策展。 草稿附件区统一展示 AI 产物与 Expert 手动上传（来源徽标区分），支持预览与逐个移除；移 除写审计。
- 实现时按 HEAD 复核：AI 产物当前在草稿 Message 上的确切落点（
attachments列 vs metadata artifacts）——#3944 之后主路径已有投递门控与产物物化，但两处检出对"是否已写到草稿行"结论不一致，实现前须以 HEAD 为准对齐数据模型。
R4 — 发送携带策展集。 Accept & send / per-draft release 携带策展区当前附件集（现有 releaseDraft/F3 respond 的 attachments 参数通路），经 3 层派发到达客户渠道（Slack files.uploadV2 / WhatsApp Twilio 媒体 / Email Gmail 多部件 / webchat 内联）。
- 验收：四渠道各跑通一次"迭代→采纳→发送→客户收到最终版"端到端。
R5 — 发送前文案-附件一致性拦截。 草稿文案引用附件而策展区为空 → 阻断 + 提示；判定方式见开放问题 O5（启发式关键词起步，agent 自报 intent 为演进）。该拦截同时作为 #4153 的防复发验收之一。
R6 — 内部性不变量。 侧聊消息、中间版本文件、迭代过程永不进入客户可见面（复用 isInternal + metadata.expertAgentThread 排除；#1621）。新增回归：采纳动作不得把侧聊消息本身变为可见——只搬运文件引用。
R7 — 指标与审计。 expert_file_iteration_total{action=generate|adopt|replace|remove|block} 计数器 + 审计日志（actor/org/specialist/conversation）；文件生成 token/成本按 osa_id 归集（consult 路径成本归集现状在实现时核验）。§2 每个目标可由此度量。
Nice-to-have（P1）
- 版本历史面板：草稿附件的历次版本列表 + 一键回退（v1 靠侧聊历史换版）。
- 附件 chip 快捷指令：常用修改一键发起（"换成品牌配色""导出为 PDF"）。
- 成本展示：本会话文件生成消耗（次数/tokens）在侧聊头部可见。
- 文案中文本地化。
Future（P2）
- 专属文件工作台（独立面板：版本树、对比视图、批注）。
- 跨会话文件库（依赖 #3501 存储范围决策）。
- 模板化产物（品牌 PPT/报表模板，生成时套用）。
7. 现状基线（改什么）
| 能力 | 今天 | v1 之后 |
|---|---|---|
| 侧聊产文件 | ❌ #4089（consult 路径缺协议注入+产物提取） | ✅（前置修复，引用 #4089） |
| 侧聊渲染附件 | ✅ SideChatPanel 已有 AttachmentList | 复用 |
| 采纳到草稿 | ❌ 无任何 promote 动作 | ✅ R2 |
| 草稿附件管理 | ❌ AI 产物不可移除/替换；与手动上传两套模型 | ✅ R3 统一策展区 |
| 发送携带附件 | ✅ release attachments 参数 → dispatchExpertReply 四渠道 | 复用 + R4 端到端验收 |
| 文案-附件一致性 | ❌ 零校验（#4153 幻觉附件被 90% 置信放行） | ✅ R5 拦截 |
| 版本语义 | ❌ draft supersede 仅覆盖文字 | v1 轻量（侧聊历史）；P1 版本面板 |
| 内部性 | ✅ isInternal/expertAgentThread 排除（#1621） | 复用 + R6 新增回归 |
检出差异声明：上表"今天"列中侧聊/草稿附件的部分结论来自两个不同时点的代码检出且互有出入（#3944 落地前后）；已按 #4089 issue 正文（近期对 HEAD 验证）为权威，标注 R3 处实现前必须按当时 HEAD 复核数据模型落点。
8. 依赖与阶段
- P0 前置：#4089 实现（其设计文档 = #4092）。建议推进顺序：#4092 设计 → #4089 实现 → 本 PRD v1。
- 同期协同:#4153(生成开关一致性 + 反幻觉)——R5 拦截是其防复发面之一;修复 #4153 时的"agent 自报附件 intent"若落地,可直接升级 R5 的判定方式(O5)。
- v1：R1(引用)–R7。
- v1.1：P1 项（版本面板、快捷指令、成本展示）。
- v2：工作台、文件库（等 #3501）、模板化。
9. 开放问题
| # | 问题 | Owner | 阻塞？ |
|---|---|---|---|
| O1 | 采纳默认策略：同 名/同类替换、否则追加（现建议）——还是永远追加、由 Expert 手动删旧版？ | 产品（Franky） | 是 — 决定 R2 交互 |
| O2 | 采纳是否触发草稿"新版本"（supersede 语义扩展到附件）还是原地更新 + 审计（现建议：原地）？ | 产品 + 工程 | 是 — 决定数据模型 |
| O3 | 中间版本（未采纳的侧聊产物）保留期与存储配额（R2 成本） | 工程 + ops | 否 |
| O4 | 附件大小/类型限制与 paperclip 允许清单（25MB、MIME 白名单）对齐即可？生成类是否需要更大上限（如 PPT） | 工程 | 否 |
| O5 | 一致性拦截判定：v1 关键词启发式（中英"附件/attached/image…"）vs agent 结构化自报"本回复含 N 个附件 intent"（更准，依赖 agent 改动） | 工程 | 否 — v1 先启发式 |
| O6 | consult 路径的 token 成本目前是否已按 osa_id 归集（R7 前提） | 工程 | 否 — 实现时核验 |
10. 参考
- #4089 侧聊附件缺口（P0 前置）· #4092 其设计任务 · #4153 幻觉附件 · #3944 文件工具集 · #3501 存储范围 · #1621 侧聊内部性
- 代码：
frontend/src/app/workspace/queue/SideChatPanel.tsx·api/src/conversations/expert-agent-thread.service.ts·api/src/conversations/conversations.service.ts（草稿/投递门控）·api/src/expert-queue/expert-queue.service.ts（release）·api/src/channels/channel-dispatcher.service.ts（四渠道附件派发）·agent/attachment_render.py/agent/prompts_loader.py（HW_ATTACHMENT）