Human Voice Rewrite Demo — 使用说明（给接手同事）

这是一个可以自己改、自己调的独立 Demo：前端（单页 HTML）+ 后端（FastAPI）+ 真实 OpenRouter 大模型调用。产品逻辑按《Human_Voice_Rewrite_PRD_v1.1》实现：AI 读懂与诊断 → 顾问人工重写 → AI 全文复检与精准返工。前台外观对齐 v6 Core Color Match 两栏原型。

一、快速启动

环境要求：本机有 Python 3.10+（macOS 一般自带；Windows 到 python.org 安装并勾选 Add to PATH）。

macOS / Linux：

./local_start.sh        # 若提示无执行权限，先 chmod +x local_start.sh

Windows：双击 start.bat（或在 cmd / PowerShell 里运行 start.bat）。

⚠️ 必须用上面的启动脚本启动，不要直接运行 uvicorn main:app：脚本负责从 .env 把 OpenRouter Key 导出到环境变量。直接跑 uvicorn 服务虽然能起来（健康检查正常），但所有 AI 调用会报「分析失败：缺少 OpenRouter Key」。

首次运行会自动创建 .venv 并安装依赖（需要联网）。看到 Human Voice Rewrite Demo: http://127.0.0.1:8000 后，浏览器打开该地址即可。

Key 已内置在本目录 .env（从公司后端环境变量导出，见第五节保密提醒）
端口冲突：macOS/Linux 用 HVR_PORT=8001 ./local_start.sh；Windows 先 set HVR_PORT=8001（PowerShell 用 $env:HVR_PORT=8001）再运行 start.bat
停止：终端 Ctrl+C

二、目录结构

文件	作用	同事常改的点
`index.html`	前端单页（两栏 Workbench、聚焦/全文、批注、调后端 API）	示例文书 `SAMPLE_ESSAY`、示例题目 `SAMPLE_PROMPT`、页面文案
`main.py`	FastAPI 入口与五个业务端点	一般不动
`prompts.py`	AI 提示词（分析/诊断/复检/写作起点/参考片段）+ Pattern 库	调 AI 行为和输出质量主要改这里
`llm.py`	OpenRouter 客户端（模型、温度、超时、重试）	模型默认值 `DEFAULT_MODEL`、`temperature`、`max_tokens`
`schemas.py`	前后端接口数据结构（对齐 PRD v1.1 §31）	增删字段时前后端同步改
`evidence.py`	Pattern / Annotation 证据核对（原文命不中则不画高亮）	一般不动
`local_start.sh` / `start.bat`	一键启动（建 venv、读 .env、起服务）	端口、env 路径
`.env`	OpenRouter Key + 代理地址	换 Key / 换代理在这里
`test_demo.py`	离线测试（不消耗模型调用）	改了逻辑后跑 `.venv/bin/pytest`
`README.md`	项目说明	—

三、三阶段业务流（真实模型）

文章理解 POST /api/analyze：全文理解 + 每段中文理解 + 语义锚点（PRD §31.1）
人味诊断 POST /api/diagnose：命中 P01–P12 + 每段 Rewrite Direction / Inline Annotation / Context Hint / Scaffold（PRD §31.2）；顾问在对话里补充的理解和约束优先
全文复检 POST /api/recheck：六维度验收，通过即结束；需返工只返回一个段落 + 单一返工目标，并绑定 rewrite_version（PRD §31.3）；/api/scaffold、/api/reference 只在顾问主动展开时使用，并写入 exposure 记录

前端流程：进入页（可粘贴自己的文章，自动分段）→ 开始分析 → 对话确认/纠偏 → 诊断 → 两栏逐段手写（左原文+批注，右安静写作区）→ 提交复检。段落数量按实际 1–N 动态渲染。

四、可以调什么（按频率）

想调什么	改哪里
换模型	`llm.py` 的 `DEFAULT_MODEL`，或启动前 `export HVR_LLM_MODEL=别的模型`
输出更稳/更发散	`llm.py` 的 `temperature`（默认 0.3）、`max_tokens`（默认 16000）
复检更严/更松	`prompts.py` 的 `build_recheck_prompt`（High Precision 规则在系统提示里）
Pattern 判定行为	`prompts.py` 的 `PATTERN_LIBRARY`（P01–P12 定义 + 改写动作）
示例文书/题目	`index.html` 顶部的 `SAMPLE_ESSAY` / `SAMPLE_PROMPT`
接口字段	`schemas.py`（改后 `index.html` 里对应渲染处同步）
重试/超时	`llm.py` `complete_json`（任何失败自动重试 1 次）与 `timeout`

改完重启服务即可生效（后端代码改动重启启动脚本；纯前端改 index.html 直接刷新页面）。

五、Key 与保密提醒（重要）

.env 内是公司真实 OpenRouter Key（含区域代理地址），已随包分发，仅限内部使用：
- 不要把整个文件夹/压缩包发到外网、公开仓库、微信群外；
- 同事间拷贝前先确认接收人是内部人员；
- 若怀疑泄露，请更换 prodream_backend/.env 里的 PRODREAM_BACKEND_OPENROUTER_API_KEY 并同步更新本包 .env。
本目录在仓库里是 gitignored 的，不会误提交。

六、常见问题

现象	处理
`错误：找不到环境变量文件`	本目录缺 `.env`，或设置了 `HVR_BACKEND_ENV` 指向了不存在的文件
服务能启动、健康检查正常，但分析时报`分析失败：缺少 OpenRouter Key`	没用启动脚本，直接跑了 `uvicorn main:app`。用 `start.bat` / `local_start.sh` 启动（脚本负责从 `.env` 导出 Key 到环境变量）
端口被占用	`HVR_PORT=8001 ./local_start.sh`（Windows 先 `set HVR_PORT=8001`）
分析时报 `调用大模型失败（HTTP …）`	看错误后半段：Key 失效→换 `.env`；403→代理问题（检查 `.env` 的代理地址）；超时→网络
`模型未返回内容（可能被截断或拒绝）`	已自动重试 1 次仍失败，多半是网络抖动，点页面「重试」即可
页面空白	确认是从 `http://127.0.0.1:8000` 访问（不是直接双击 index.html，那样没有后端）
想完全不用代理直连	把 `.env` 里 `PRODREAM_BACKEND_OPENROUTER_PROXY_URL` 那行删掉（国内网络可能不通）
右侧显示「已保存」	只表示草稿已持久化，不等于这段已经改完，也不等于 AI 通过

七、V1.1 不要再按旧 Demo 理解的几点

Workbench 是两栏，不再有独立第三栏 Writing Coach
已保存 ≠ 已改写；提交复检只看各段 rewrite_text 是否非空
段落导航和进度必须按实际段数动态生成，不能写死 4 段
Recheck 检查的是提交时的 Snapshot；提交后继续改会进入新版本
只有顾问真正展开过的 Scaffold / Reference 才会进入复制检测
分析中（AI 初审 / 诊断 / 复检进行中）在对话页输入框输入并点发送：输入框内显示红色「AI 分析中，请稍候…」，已输入文本不清除（可继续输入，发送会被拦截，不会丢字）
刷新位置规则：改写进行中刷新 → 回 Workbench（改写与进度保留）；理解/诊断结果态刷新 → 回对话页（历史卡完整）；复检结果已返回（pass 卡/返工卡在对话页）刷新 → 停留对话页；只有复检请求进行中刷新才回 Workbench（可重新提交复检）
分析耗时与超时提示（2026-08-25 同事实测诊断卡 5 分钟后的两轮优化）：真实模型生成通常需要 1–2 分钟（上游排队时更久）；loading 卡 45 秒后追加「仍在生成中，通常需要 1–3 分钟…」、2 分钟后追加「已超过 2 分钟…」——不是死机，是模型还在写。诊断侧已做三层控制：①输出精简（原来一次 6.6k tokens，现在约 2.5k）；②思考预算 2048→512——DeepSeek 思考 token 生成速度约为正文的 1/10，预算给满会把时间全烧在想（实测 2048 = 309.8s、512 = 70–200s），当前实测诊断约 1–3.5 分钟，波动来自 OpenRouter 吞吐（12–80 tok/s），属外部因素；③模型打满输出上限时快速失败并自动重试一次，还不行会给出可读错误卡，稍后重试即可；嫌慢可换模型：启动前 export HVR_LLM_MODEL=别的模型（如 faster 或其它 deepseek 系列）。后端日志会打印每次模型调用的耗时与 token 用量（llm ok model=... dt=... prompt=... completion=...），排查慢链路直接看这个；思考预算调参入口在 llm.py 的 reasoning_config

8.1 KiB Raw Permalink Blame History Unescape Escape