73 lines
3.5 KiB
Markdown
73 lines
3.5 KiB
Markdown
# 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**：
|
||
|
||
```bash
|
||
./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） |
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
.venv/bin/pytest -q
|
||
```
|