# 文书工作台 Agent 优化 — 交付说明（v1.0）

> 日期：2026-09-01 ｜ 涉及仓库：prodream-next（前端）、prodream_backend（后端）
> 方案文档：[docs/essay-agent-optimization-plan.md](essay-agent-optimization-plan.md)（已实施，状态头已更新）

---

## 一、完成状态总览

| # | 需求 | 状态 | 关键实现 |
|---|---|---|---|
| 1 | Agent 对话进文书工作台（essay-chat skill） | ✅ 已实施 | tab6 替换为 DreamiChatV2 嵌入；后端 essay-chat skill + 控制面映射；`<<<ACTIONS>>>` 锚点落回编辑文档 |
| 2 | humanizer 规则融入（AI 味识别与优化） | ✅ 已实施 | SKILL.md 新增「AI 味检查」章节：参照 humanizer v2.11.2 裁剪的检测清单 + 逐段扫描→报告→确认后改写流程 |
| 3 | 文书评估常驻卡片 | ✅ 已实施 | 评估结果 zustand 常驻 + 历史时间线（GET /evaluation/history）+ 「去对话改写」闭环 |
| 4 | 体验优化（翻译 / 字数提示 / 汇总建议） | ✅ 已实施 | assistant 回复翻译按钮；输入框旁目标字数提示（BE 注入 word_count，改写自动带字数约束）；历史评估构造汇总建议 |
| 5 | 输入法误发送 bug | ✅ 已实施 | 5 处 onKeyDown 加 `isComposing` 守卫 |

## 二、commit 对照

### 前端 prodream-next（按顺序）

| 阶段 | commit | 内容 |
|---|---|---|
| A | `563a13cc8` | fix: 输入法组合期间回车误发送（5 处 onKeyDown 守卫） |
| C | `1153a1f61` | feat: essay 工作台 tab6 替换为 DreamiChatV2 essay-chat 嵌入 + ACTIONS 锚点落回 |
| D | `8ef4f0e75` | feat: 文书评估常驻卡片 + 历史时间线 + 建议→对话改写闭环 |
| F | `3aaf10bf6` | feat: essay workbench UX polish — translation buttons, word-count hint, history suggestions |

### 后端 prodream_backend（按顺序）

| 阶段 | commit | 内容 |
|---|---|---|
| B | `250e39454` | feat: essay-chat skill 骨架 + get_essay_evaluation 工具 |
| C | `88969a639` | feat: 控制面 chat.py essay-chat 映射 + toolset 切换 + context 富化 + ACTIONS 剥离回传 |
| D | `852236107` | feat: 评估历史接口 GET /essay/{id}/evaluation/history + SKILL 首轮带指令 |
| E | `d68b45386` | feat: essay-chat skill AI-flavor check（humanizer 改编清单 + 检测/确认/改写流程） |
| F | `82729a5d0` | feat: inject essay word_count into essay-chat context + SKILL context note |

> 注：阶段 B（skill 骨架）为纯后端改动，前端无对应 commit。

## 三、验收对照

### 需求 1：Agent 对话

| 验收点 | 状态 | 证据 |
|---|---|---|
| tab6（竖列底部 Dreami 按钮）进入即自动开聊 | ✅ 静态验证 | `autoStart` + `hideEmptyHero`，空首轮触发 SKILL 首轮盘点（agent_initiated） |
| 对话上下文带文书全文 / 题目 / 目标字数 / 评估 | ✅ 静态验证 | BE 按 essay_id 注入 current_document/essay_prompt/word_count/evaluation 到最后一条 user 消息 |
| 对话里改文书：确认后落回 | ✅ 静态验证 | SKILL「建议落地」先给改法→用户确认→`<<<ACTIONS>>>` 锚点替换 Tiptap 段落→useSaveEssay 落库 |
| 锚点未命中不猜测 | ✅ 静态验证 | `applyEssayActionsToEditor` 唯一命中才应用，未命中 toast 提示 |
| 语言跟随界面 locale | ✅ 静态验证 | taskMetadata.context.locale 注入 + 回复语言约束 |
| 浏览器实测 | ⏳ 待验证 | 见风险 5 |

### 需求 2：AI 味检查

| 验收点 | 状态 | 证据 |
|---|---|---|
| 检测清单覆盖 humanizer 35 条（裁剪） | ✅ 静态验证 | 内容/语言/风格三类清单 + 反误报清单，出处标注 humanizer v2.11.2 |
| 逐段扫描→报告（模式+原文引用+改法） | ✅ 静态验证 | SKILL「AI 味检查」检测流程 |
| 确认后改写，不改事实/删词不删意 | ✅ 静态验证 | 改写四原则 |
| 与 GPTZero 按钮互补不冲突 | ✅ 静态验证 | SKILL 互补说明 |

### 需求 3：评估常驻卡片

| 验收点 | 状态 | 证据 |
|---|---|---|
| 评估完结果常驻（刷新/重进恢复） | ✅ 静态验证 | zustand 空态自动恢复 history[0] |
| 多次评估可回看历史 | ✅ 静态验证 | GET /essay/{id}/evaluation/history + 历史时间线折叠列表 |
| 历史项可选回看 | ✅ 静态验证 | onSelect 切换 result + 构造只读建议 |
| 从建议「去对话改写」 | ✅ 静态验证 | handleChatRewrite 暂存指令→切 tab6；历史建议 origin 留空→guard 引导走对话 |

### 需求 4：体验优化

| 验收点 | 状态 | 证据 |
|---|---|---|
| assistant 回复一键翻译（复用 translate API） | ✅ 静态验证 | assistantTranslate prop（仅 essay-chat 传，其他场景行为不变）+ 译文消息下方展开/收起 |
| 输入框旁目标字数提示 | ✅ 静态验证 | expect_word_count + editor 词数实时；超出变红；无字数要求题不显示 |
| 改写指令自动带字数约束 | ✅ 静态验证 | BE 注入 word_count 字段 + SKILL 换算单段比例逻辑 |
| 汇总建议：一句话行动项 | ✅ 静态验证 | improvement 字段既有能力，未新造 |
| 历史里能看到上次评估建议并可再次进入改写 | ✅ 静态验证 | handleSelectHistory 构造 FeedbackImprovement 列表 + 「去对话改写」按钮 |

### 需求 5：输入法 bug

| 验收点 | 状态 | 证据 |
|---|---|---|
| 中文输入组合期间回车不误发送 | ✅ 静态验证 | 5 处 `onKeyDown` 加 `e.nativeEvent.isComposing` 守卫；tsc pass |
| 组合完成后回车正常发送 | ✅ 静态验证 | 组合状态 false 走原逻辑 |

## 四、验证记录

- 后端：`py_compile` 全部改动文件 pass
- 前端：`tsc --noEmit`（主仓 node_modules 绝对路径）exit 0
- i18n：cn.json / en.json JSON.parse pass，key 一一对应
- 浏览器端到端验证（pre.prodream.cn）：⏳ 未做 — 需要测试账号（见风险 5）

## 五、改动文件清单

### 前端
- `components/editor/rightbar/chatbot/Chatbot.tsx` — essay-chat 嵌入 + ACTIONS 落回 + 字数提示 + assistantTranslate
- `components/dreami/DreamiChatV2.tsx` — assistantTranslate / composerHint 可选 prop + 翻译按钮 UI
- `components/editor/rightbar/feedback/Feedback.tsx` — 常驻恢复 + 历史时间线 + handleSelectHistory
- `components/editor/rightbar/feedback/Result.tsx` — 评估报告翻译按钮 + 译文区
- `components/editor/rightbar/feedback/Improvement.tsx` — 历史建议 origin guard
- `components/dreami/dreamiAdapter.ts` — EssayAnchorAction 类型透传
- 输入法 5 处 onKeyDown（chat 输入框所在组件）
- `dictionaries/cn.json` / `dictionaries/en.json` — 新增 key

### 后端
- `dreami/control-plane/dreami_control_plane/api/chat.py` — essay-chat task 映射 + toolset + context 富化 + `<<<ACTIONS>>>` 剥离回传 + word_count 注入
- `dreami_skills/essay-chat/SKILL.md` — 骨架 + 首轮盘点 + AI 味检查章节
- 评估历史接口 + `get_essay_evaluation` 工具

## 六、风险与未做项

1. **浏览器验证未做**（风险 5）：pre.prodream.cn 需要测试账号。联调验证时需要你提供账号，或由你自行走查。
2. **对话改写需用户确认**：已按方案（先给改法→确认→落回）实现，未绕过确认——这是刻意行为，不是缺陷。
3. **评估为异步任务**：对话内 get_essay_evaluation 走工具调用，结果以工具返回注入；AI 输出等待提示由 skill 指令约束。耗时表现需浏览器实测确认。
4. **humanizer 为参照非照搬**：35 条按文书场景裁剪（检测保留、改写挑选），详见 SKILL「AI 味检查」章节出处标注。
5. **未动评估 prompt 体系**：评估质量体系（招生官视角 + 8 维度）原样保留。