human-voice-rewrite-demo/README.md

Human Voice Rewrite Demo（独立 Demo，接入真实 OpenRouter）

按 Human_Voice_Rewrite_PRD_v1.1 做成打开即用的本地 Demo：前台交互对齐 Human Voice Rewrite Demo v6 · Core Color Match，底层状态、版本、返工、保存 与数据规则按 PRD 实现，不因演示而简化。所有 AI 内容走真实大模型（OpenRouter）。

分发给同事请直接给整个文件夹（或压缩包）：含 .env（内置 Key）与 「使用说明.md」。macOS/Linux 跑 ./local_start.sh，Windows 双击 start.bat。

启动

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

Windows：双击 start.bat（或在 cmd / PowerShell / Git Bash 中运行 start.bat）， 看到 Human Voice Rewrite Demo: http://127.0.0.1:8000 后浏览器打开该地址。

macOS / Linux：

./local_start.sh
# 打开 http://127.0.0.1:8000

脚本会：

1. 首次运行自动创建 .venv 并安装 requirements.txt；
2. 读取 Key（优先级：HVR_BACKEND_ENV 指定 > ../../prodream_backend/.env 仓库环境 > 本目录 .env 分发包）；缺失时明确报错退出；
3. 若 .env 配了 PRODREAM_BACKEND_OPENROUTER_PROXY_URL，则作为正向代理 （区域代理约定，httpx proxy=）访问 OpenRouter，否则直连 https://openrouter.ai/api/v1。

环境变量覆盖：HVR_LLM_MODEL（默认 google/gemini-3.7-flash，2026-08-25 由 v4-flash-0731 切换，实测 26.5s / 4 patterns，质量重叠 3/4 且更具体）、 HVR_PORT（默认 8000）、HVR_BACKEND_ENV（后端 env 路径）、 OPENROUTER_BASE_URL / OPENROUTER_PROXY_URL。

端口冲突：macOS/Linux 用 HVR_PORT=8001 ./local_start.sh；Windows 先 set HVR_PORT=8001（PowerShell 用 $env:HVR_PORT=8001）再运行 start.bat。 停止：终端 Ctrl+C。

（Mac 分发包拿到后如果 ./local_start.sh 没有执行权限，先 chmod +x local_start.sh。）

使用

• 进入页可输入/粘贴自己的文章（自动分段、实时字数），或「载入示例文书」；
• 「开始分析」→ 真实模型生成全文理解与分段理解；对话中可纠正理解、补充约束；
• 「理解准确，继续分析」→ 真实模型生成 Human Voice Diagnosis；
• 「确认方向，进入逐段改写」→ 两栏 Workbench：左「原文与改写提示」/ 右「我的人工改写」； 支持动态段落导航、聚焦 / 全文双模式、原文同色 Evidence 批注； Progressive Help 需主动展开（写作起点 → 参考片段）；改写自动保存且与进度分离；
• 「完成全文改写，提交复检」→ 真实模型全文复检：通过即结束；需要返工则定位目标段， 只给一个返工目标，并绑定 Recheck Snapshot。

接口

端点	说明
GET /api/health	健康检查
POST /api/analyze	文章理解（PRD §31.1）
POST /api/diagnose	Human Voice Diagnosis（PRD §31.2，含 annotations / evidence 校验）
POST /api/recheck	全文复检（PRD §31.3，绑定 rewrite_version）
POST /api/scaffold	Progressive Help Level 1：写作起点（PRD §22.2）
POST /api/reference	Progressive Help Level 2：参考片段（PRD §22.3）

测试

.venv/bin/pytest -q