# ASR Pipeline on tools-pve

独立的录音转写、精修、人工审核和导出服务。WebUI 与 Agent API 共用 `192.168.50.49:8788`；worker 调用 unRaid 上的 Qwen3-ASR/CAM++ 服务以及 ZenMux 模型 API。

## 数据边界

- `/mnt/truenas/personal/ASR-Pipeline` → 容器 `/data`：原始录音、转写、ASR 原始响应、草稿、正式稿、日志和 SQLite 在线备份。
- `/opt/asr-pipeline/state` → 容器 `/state`：活动 SQLite、worker heartbeat、revision queue。SQLite WAL 不放在 NFS。
- `/srv/asr/inbox`：指向 TrueNAS inbox 的宿主机链接，供 `scp`/`sftp` 上传。
- `.env`：仅存在 Arcane Project / tools-pve，权限 `0600`，不进入 Git。

SSH 大文件建议先上传为 `.part`，完成后在同一目录原子改名为受支持扩展名：

```bash
scp call.m4a tools@192.168.50.49:/srv/asr/inbox/call.m4a.part
ssh tools@192.168.50.49 'mv /srv/asr/inbox/call.m4a.part /srv/asr/inbox/call.m4a'
```

## Agent API

所有 `/api/v1/*` 路由使用 `Authorization: Bearer $ASR_AGENT_TOKEN`。

```bash
curl -X POST http://192.168.50.49:8788/api/v1/jobs \
  -H "Authorization: Bearer $ASR_AGENT_TOKEN" \
  -H 'X-Filename: call.m4a' -H 'X-Title: 项目通话' \
  -H 'X-Context: 参与人和项目背景' --data-binary @call.m4a

curl -H "Authorization: Bearer $ASR_AGENT_TOKEN" \
  http://192.168.50.49:8788/api/v1/jobs/JOB_ID
```

路由：

- `POST /api/v1/jobs`：上传并创建异步任务。
- `GET /api/v1/jobs?limit=&offset=&status=`：分页查询。
- `GET /api/v1/jobs/{id}`：任务详情、事件时间线与产物链接。
- `GET /api/v1/jobs/{id}/artifacts/{transcript|draft|result}`：读取产物。
- `GET /api/v1/jobs/{id}/reviews`：待人工确认项。
- `POST /api/v1/jobs/{id}/reviews/{question_id}`：JSON `{"answer":"..."}`。
- `POST /api/v1/jobs/{id}/retry`：重试失败任务。

`/healthz` 仅表示 Web 进程存活；`/readyz` 同时检查数据库与 worker heartbeat。

## 通知

`ASR_NOTIFY_BACKEND=none|telegram|hermes`。Telegram 需要 `TELEGRAM_BOT_TOKEN` 与 `TELEGRAM_CHAT_ID`；Hermes 需要一个明确存在的签名 webhook URL 与共享密钥。发送失败只影响提醒，不改变任务结果。

## 运维

项目由 Arcane Git Sync 管理，自动同步、自动 pull 和自动 redeploy 均关闭。Compose 变更先在 Git 中验证，再对 tools-pve 的准确 Sync 手动同步。活动数据库每小时通过 SQLite backup API 写到 `/data/backups/*.latest`。