HEL-879 rework materials: hatchling cache correction with the offline mem0ai wheel actually built from the fixed source (sha256 698284b6..., zero downloads/installs, no 3.10 mixing, recorded in release-artifacts.json), hel895 release doc §0 now separates the historical HEL-895/896 candidate from the current hel-879-assembly candidate and §4/§5 carry the v3 snapshot semantics, budget §6.2.4 amended - a sealed library is never reopened by raising total_requests (contradiction removed), runbook §3.3/3.5/3.6/4.4/4.5 corrected (bounded cleanup ledger replaces the unproven rooms-die-naturally claim; assistant_interim kind; real-but-default-off proactive seam; single-owner dual launcher), one comment-only correction in web/src/voice/session.ts removing the unproven server-auto-cleanup claim (no logic/style change; CSS and JS bundle hashes byte-stable), CG-011 + her incremental subtitles now have a real minimal backend seam (voice/seam.py + worker/llm_chat_api wiring, proactive default off) with the precise frontend interface and acceptance list in docs/rework/hel879/voice-seam-interfaces.md, real-SDK check extended to 10 items (worker callback path on real SpeechHandle/SpeechCreatedEvent; interim seam through real LLMStream) and re-run on .12 ALL PASS, handoff-HEL-879.json appended with the rework scope; regression at this head: pytest 341/341, ruff clean except 1 pre-existing error identical at 7f0a739, web typecheck 0 errors / lint 0 errors 1 pre-existing warning / vitest 88/88 / build passes (CSS index-BpZaybfD.css unchanged), voice chain 8/8, budget split 10/10, release offline R1-R7, http pagination 7/7, real-service browser 9/9 with zero non-loopback outbound, pinned-SDK 16/16+12/12+6/6+7/7+12/12, requirements checks 4/4 (origin/main and c121c42, each with/without handoff)

Co-authored-by: multica-agent <github@multica.ai>
This commit is contained in:
zonggong
2026-10-27 04:27:04 +08:00
co-authored by multica-agent
parent 78a5cfd8d7
commit 7c73d392b9
21 changed files with 567 additions and 94 deletions
+1
View File
@@ -1,2 +1,3 @@
__pycache__/
*.pyc
web/node_modules
+37 -12
View File
@@ -28,6 +28,16 @@ HEL-881 已审核的主动留言前端(`bf234570`)装成一个统一候选
## 0. 精确 head 与整合方式
> **HEL-879 返修勘误(2026-10-27)**:本节以下原文记录的是 **HEL-895/896 历史
> 候选**(分支 `hel-870-assembly`,PR #11 未合并),其 299 pytest / 55 vitest 等
> 验证数字属于那个历史 head,**不是当前发布候选**。当前统一发布候选是分支
> `hel-879-assembly`(在 7f0a739 之后正常追加返修提交,不强推、不并入 PR #11),
> 其精确 head、pytest/vitest/build 全量数字与证据以**交付评论与
> `docs/requirements/handoff-HEL-879.json` 记录为准**;本文件的安装/检查入口
> (§2/§4/§5/§6)继续适用于当前候选,产物清单见
> `docs/rework/hel879/sdk-audit/` 与 `docs/rework/hel879/release-artifacts.json`
> (`rework_head` 字段)。历史叙述保留原样,不冒充、不改写。
- **候选 head**:见交付评论(分支 `hel-870-assembly`,PR #11 的正常追加提交,
未强推、未合并)。第一父为 HEL-894 通过复审的 `152479b3503c3d1ab27681170e6bfd592c54380a`,
合并入 HEL-881 已审核的 `bf234570c0b6595a72f8dbc79e42c63685e08e01`
@@ -129,13 +139,22 @@ weather/materials/backup=false。**主动留言前端已并入本候选:生活
```
不一致即停;不得改用索引 `mem0ai==2.2.1` wheel 冒充固定源(audit 已证明两者
身份不可互证)。
- **第 2 步 · 固定源码构建轮**:`python3 -m pip wheel --no-deps --no-index
--no-build-isolation -w wheels/ mem0-2c81af3.tar.gz`。**前置缺口如实保留**:
build backend `hatchling` 当前不在任何本机缓存(audit 实测),未获批不联网补齐;
hatchling 落位后本命令完全离线,构建出的 wheel 逐项 sha256 留证。
- **第 2 步 · 固定源码构建轮(HEL-879 返修:已完成可离线构建)**:此前此处写
「hatchling 当前不在任何本机缓存、待补」——经总管只读核查与本卡复核**勘误**:
uv wheels-v6/wheels-v7 均有 hatchling **1.32.4** 缓存(`release-artifacts.json`
`build_backend` 节逐路径留证)。固定源 tarball 已在 3.11.16 + `uv build --wheel
--offline` 下**离线构建出轮**(零下载、零安装、不混 3.10 site-packages):
`mem0ai-2.2.1-py3-none-any.whl`,
sha256 `698284b6083ab8b7761454d65876a6d1bb983d278ad21a7bee38d760cb20e9db`。
发布卡在目标机重跑同一命令并核对该哈希:
```bash
tar xzf <hel857-data>/mem0-2c81af3.tar.gz && cd mem0-2c81af3*/
uv build --wheel --offline --python 3.11 -o wheels/
sha256sum wheels/mem0ai-2.2.1-py3-none-any.whl
```
- **第 3 步 · 目标 cp311 依赖准备**:41 项缺项中**缓存今天即可复用 3 项**
(greenlet 3.5.6 cp311、pillow 12.3.0 cp311、truststore 0.10.5 py3-none-any,
uv wheels-v6/v7 缓存实测,HEL-879 重跑核实仍命中);其余 37 项 + hatchling
uv wheels-v6/v7 缓存实测,HEL-879 重跑核实仍命中);其余 37 项
**由总管获批后发布窗口拉取**(`python3 -m pip download --only-binary :all:
--implementation cp --python-version 3.11 --platform manylinux2014_x86_64
--abi cp311 -r <缺项清单> -d wheels/`),逐项 sha256 留证;本卡零下载、零联网。
@@ -156,7 +175,8 @@ weather/materials/backup=false。**主动留言前端已并入本候选:生活
产品 venv 目前 `import mem0/qdrant_client/fastembed` 均缺、产品代码导入不受影响;
在 wheel 落位且 co-import 通过前,不得以 stub/FTS 冒充真实 Mem0 体验就绪。
真缺的下载(37 项 + hatchling)仍待主卡授权,本卡不为补命令联网。
真缺的下载(37 项运行闭包;hatchling 已勘误为缓存命中并完成离线构建,不在缺单)
仍待主卡授权,本卡不为补命令联网。
## 5. 停用与保留数据回退
@@ -165,18 +185,23 @@ weather/materials/backup=false。**主动留言前端已并入本候选:生活
`systemctl stop` → 数据目录原样保留 → 切回上一 release/上一提交(R4 迁移全部
增量新表,旧代码可安全打开同一数据库);彻底撤销留数据档不删。
**HEL-896 归档/回退修订 + HEL-879 收口(2026-10-27)**:在线库只复制主 `.db` 会丢
WAL 里已提交的资料(总管复现件连 `companion` 表都不在)。发布归档一律二选一:
**停服务 + `PRAGMA wal_checkpoint(TRUNCATE)` 后整目录归档**(推荐),或**在线用
SQLite backup API 对显式单库做一致性快照**。工具已按收口语义强制执行(v2):
**HEL-896 归档/回退修订 + HEL-879 收口(2026-10-27,v3 返修)**:在线库只复制主
`.db` 会丢 WAL 里已提交的资料(总管复现件连 `companion` 表都不在)。发布归档一律
二选一:**停服务 + `PRAGMA wal_checkpoint(TRUNCATE)` 后整目录归档**(推荐),或
**在线用 SQLite backup API 对显式单库做一致性快照**。工具已按收口语义强制执行
(v3;v2 的两处已证缺陷由总管独立复核提出并修复):
- checkpoint 返回 busy≠0 或源/快照行数不一致 → CLI 非 0、不产生可交付归档
(「先停服」是前提,不是忽略失败结果的理由);
- 目录内真实 SQLite(history_root 的 `mem0_public_history.db`、向量目录内库等,
按文件头魔数递归识别)在停服口径一并 checkpoint+逐表核对;
- 在线模式只接受显式 `--db`(backup API);传入含 SQLite 的 `--file` 目录直接拒绝;
- `verify` 拒绝记录了 `rows_match=False` 的旧包,回退演练按源路径映射解包到隔离
新目录、实际打开各库核对行数与哈希,输出 rollback_plan。
- `verify` 要求**三个计数直接相等**(manifest 源行数 = manifest 快照行数 = 恢复
实测;`rows_match` 只是额外约束——v2 的 `rows_match is True or …` 允许记录值
绕过源计数比较,源 2/快照 1 仍 ok,已废除);回退演练按源路径映射**实际恢复**
到归档旁的持久独立目标树、打开恢复库核对行数与哈希,输出 rollback_plan;
- 归档侧目标名无冲突映射:不同目录的同名 `ledger.db` 不再互相覆盖(v2 后写覆盖
前写仍先交成功包);同一源重复传入直接拒绝。
照抄命令:
+5 -2
View File
@@ -126,8 +126,11 @@ HEL-857 的 60 次实验授权);B/C 需白栖知明确批准。
3. **旧测试数据不会转成用户伴侣**:测试档案、聊天、生活数据只存在于团队实例库与
归档;用户实例是全新空库,由用户自己创建档案;产品无任何「测试库导入用户库」
路径,发布卡明令禁止把 8360 数据目录复制/合并进用户实例数据目录。
4. 后续任何团队复检 = 新批准 + 新实例/新库(或在 8360 实例上以新批准抬
`total_requests`),绝不续在用户账上。
4. 后续任何团队复检 = **新批准 + 全新隔离实例/新库**,绝不续在用户账上,也
**绝不在已封账的 8360 库上抬 `total_requests` 重开**(HEL-879 返修勘误:本节
旧版括注「或在 8360 实例上以新批准抬 total_requests」与「无解除封账路径」
自相矛盾——封账标记随库持久,抬 cap 不能也不得绕过它;该括注废除)。旧
8360 库及其封账标记原样归档留存,作为真实用量的证据链。
### 6.3 B/C 的开始与日常
+56 -23
View File
@@ -1,33 +1,66 @@
{
"baseline_version": "1.11",
"read_commit": "c121c42e39174e0f627f129e7f7e5700f33acf26",
"task": "HEL-879 双职责一次交付:A) HEL-896 发布工具四项有限收口(总管独立复核清单)——①归档一致性强制:checkpoint busy 或源/快照行数不一致一律 CLI 非0、不形成可交付包,verify 拒绝 rows_match=False 旧包并按源路径映射做真实回退演练(解包隔离目录、实开各库核行数与哈希),自测 9/9 先复现旧失败形状再证修复;②目录内真实 SQLite(history_root/mem0_public_history.db 等)停服口径递归走 checkpoint+逐表核对,在线模式仅显式单库 backup API、含 SQLite 目录直接拒绝;③提前封账可执行:PersistentBudget.sealed()/seal() 原子写封账标记(真实用量保留不伪造不清零),acquire 首查封账(budget_sealed:51/55),跨重启/backup 归档恢复均拒绝、重复 seal 幂等、无解封路径,tools/seal_budget_hel879.py 为显式关闭命令,S6 负例(51/55 提前收尾、误重启、归档恢复、日顶有余量仍拒)并入 verify_budget_split 10/10;④安装入口唯一:hel895-release-candidate.md §2 全 offline 自足安装、§4 五步固定 SDK 入口(tarball 哈希→固定源构建→cp311 备产→仅本地轮→co-import),hel874-release.md §2/§4 标注被取代,mem0-stack.lock 的 mem0ai 行只作版本记录,audit 工具 head 动态化+证据目录可重定向,新证据 docs/rework/hel879/{sdk-audit,release-artifacts.json}。B) 统一语音候选隔离整合:hel-879-assembly 分支 = c121c42 + 发布收口(01ff919) + 语音后台 aba2aeb + 语音前端 c61d9c9(原作者 web/src 逐字节保留,CSS 哈希变化仅原作者 components.css +21 行),语音适配器测试对齐主线 HEL-882 硬闸(engineering_budget,不改产品门),全电池在该 head 实跑:pytest 324/324(299 主线+25 语音)、ruff 干净、web typecheck 0 错/lint 0 错1既有警告/vitest 88/88/build 通过、真实服务浏览器 9/9(零权限调用、零非回环出站,证据 docs/rework/hel879/browser/)、verify_hel877_voice_chain 8/8、.12 真SDK stdin 检查 8/8 ALL PASS(零写入零网络)、check_release_offline R1-R7、固定SDK回归 16/16+12/12+6/6+7/7+12/12。零真实 LLM/嵌入/ASR/TTS、零下载、零麦克风、未启动/停止任何服务、不部署、不合并 PR、PR#11 与 hel-870-assembly 未动、权威账与冻结未写、真实 cap 保持 0",
"requirement_ids": ["CG-006", "CG-008", "CG-009", "CG-010", "CG-011", "CG-012", "CG-013", "CG-014", "CG-015", "CG-016", "CG-018", "CG-021", "CG-023", "CG-029", "CG-030", "CG-031", "VIS-013", "AM-001", "AM-002", "AM-003", "UX-001", "UX-005", "UX-006", "GOV-001", "GOV-002", "GOV-003", "GOV-004", "GOV-005", "GOV-006", "DEL-001"],
"deliverable": "分支 hel-879-assembly(独立候选,未入 PR#11):发布收口 tools/release_snapshot_hel896.py v2(强制一致性+回退演练)、src/cybergril/life/model.py 封账(sealed/seal/acquire 首查)、tools/seal_budget_hel879.py、tools/verify_budget_split_hel896.py S6、tools/audit_sdk_offline_hel896.py head 动态化、deploy/hel895-release-candidate.md §0/§2/§4/§5 唯一入口、deploy/hel874-release.md §2/§4 取代标注、deploy/mem0-stack.lock 注释收口、docs/budget-package-hel895.md §6.2 可执行封账;语音整合:aba2aeb 后台模块 + c61d9c9 前端(原作者视觉逐字节保留)合并入候选,测试对齐主线硬闸;证据 docs/rework/hel879/{release-snapshot/selftest.json,sdk-audit/,release-artifacts.json,browser/,release-check/,regression-*.json}",
"task": "HEL-879 \u53cc\u804c\u8d23\u4e00\u6b21\u4ea4\u4ed8\uff1aA) HEL-896 \u53d1\u5e03\u5de5\u5177\u56db\u9879\u6709\u9650\u6536\u53e3\uff08\u603b\u7ba1\u72ec\u7acb\u590d\u6838\u6e05\u5355\uff09\u2014\u2014\u2460\u5f52\u6863\u4e00\u81f4\u6027\u5f3a\u5236\uff1acheckpoint busy \u6216\u6e90/\u5feb\u7167\u884c\u6570\u4e0d\u4e00\u81f4\u4e00\u5f8b CLI \u975e0\u3001\u4e0d\u5f62\u6210\u53ef\u4ea4\u4ed8\u5305\uff0cverify \u62d2\u7edd rows_match=False \u65e7\u5305\u5e76\u6309\u6e90\u8def\u5f84\u6620\u5c04\u505a\u771f\u5b9e\u56de\u9000\u6f14\u7ec3\uff08\u89e3\u5305\u9694\u79bb\u76ee\u5f55\u3001\u5b9e\u5f00\u5404\u5e93\u6838\u884c\u6570\u4e0e\u54c8\u5e0c\uff09\uff0c\u81ea\u6d4b 9/9 \u5148\u590d\u73b0\u65e7\u5931\u8d25\u5f62\u72b6\u518d\u8bc1\u4fee\u590d\uff1b\u2461\u76ee\u5f55\u5185\u771f\u5b9e SQLite\uff08history_root/mem0_public_history.db \u7b49\uff09\u505c\u670d\u53e3\u5f84\u9012\u5f52\u8d70 checkpoint+\u9010\u8868\u6838\u5bf9\uff0c\u5728\u7ebf\u6a21\u5f0f\u4ec5\u663e\u5f0f\u5355\u5e93 backup API\u3001\u542b SQLite \u76ee\u5f55\u76f4\u63a5\u62d2\u7edd\uff1b\u2462\u63d0\u524d\u5c01\u8d26\u53ef\u6267\u884c\uff1aPersistentBudget.sealed()/seal() \u539f\u5b50\u5199\u5c01\u8d26\u6807\u8bb0\uff08\u771f\u5b9e\u7528\u91cf\u4fdd\u7559\u4e0d\u4f2a\u9020\u4e0d\u6e05\u96f6\uff09\uff0cacquire \u9996\u67e5\u5c01\u8d26\uff08budget_sealed:51/55\uff09\uff0c\u8de8\u91cd\u542f/backup \u5f52\u6863\u6062\u590d\u5747\u62d2\u7edd\u3001\u91cd\u590d seal \u5e42\u7b49\u3001\u65e0\u89e3\u5c01\u8def\u5f84\uff0ctools/seal_budget_hel879.py \u4e3a\u663e\u5f0f\u5173\u95ed\u547d\u4ee4\uff0cS6 \u8d1f\u4f8b\uff0851/55 \u63d0\u524d\u6536\u5c3e\u3001\u8bef\u91cd\u542f\u3001\u5f52\u6863\u6062\u590d\u3001\u65e5\u9876\u6709\u4f59\u91cf\u4ecd\u62d2\uff09\u5e76\u5165 verify_budget_split 10/10\uff1b\u2463\u5b89\u88c5\u5165\u53e3\u552f\u4e00\uff1ahel895-release-candidate.md \u00a72 \u5168 offline \u81ea\u8db3\u5b89\u88c5\u3001\u00a74 \u4e94\u6b65\u56fa\u5b9a SDK \u5165\u53e3\uff08tarball \u54c8\u5e0c\u2192\u56fa\u5b9a\u6e90\u6784\u5efa\u2192cp311 \u5907\u4ea7\u2192\u4ec5\u672c\u5730\u8f6e\u2192co-import\uff09\uff0chel874-release.md \u00a72/\u00a74 \u6807\u6ce8\u88ab\u53d6\u4ee3\uff0cmem0-stack.lock \u7684 mem0ai \u884c\u53ea\u4f5c\u7248\u672c\u8bb0\u5f55\uff0caudit \u5de5\u5177 head \u52a8\u6001\u5316+\u8bc1\u636e\u76ee\u5f55\u53ef\u91cd\u5b9a\u5411\uff0c\u65b0\u8bc1\u636e docs/rework/hel879/{sdk-audit,release-artifacts.json}\u3002B) \u7edf\u4e00\u8bed\u97f3\u5019\u9009\u9694\u79bb\u6574\u5408\uff1ahel-879-assembly \u5206\u652f = c121c42 + \u53d1\u5e03\u6536\u53e3(01ff919) + \u8bed\u97f3\u540e\u53f0 aba2aeb + \u8bed\u97f3\u524d\u7aef c61d9c9\uff08\u539f\u4f5c\u8005 web/src \u9010\u5b57\u8282\u4fdd\u7559\uff0cCSS \u54c8\u5e0c\u53d8\u5316\u4ec5\u539f\u4f5c\u8005 components.css +21 \u884c\uff09\uff0c\u8bed\u97f3\u9002\u914d\u5668\u6d4b\u8bd5\u5bf9\u9f50\u4e3b\u7ebf HEL-882 \u786c\u95f8\uff08engineering_budget\uff0c\u4e0d\u6539\u4ea7\u54c1\u95e8\uff09\uff0c\u5168\u7535\u6c60\u5728\u8be5 head \u5b9e\u8dd1\uff1apytest 324/324\uff08299 \u4e3b\u7ebf+25 \u8bed\u97f3\uff09\u3001ruff \u5e72\u51c0\u3001web typecheck 0 \u9519/lint 0 \u95191\u65e2\u6709\u8b66\u544a/vitest 88/88/build \u901a\u8fc7\u3001\u771f\u5b9e\u670d\u52a1\u6d4f\u89c8\u5668 9/9\uff08\u96f6\u6743\u9650\u8c03\u7528\u3001\u96f6\u975e\u56de\u73af\u51fa\u7ad9\uff0c\u8bc1\u636e docs/rework/hel879/browser/\uff09\u3001verify_hel877_voice_chain 8/8\u3001.12 \u771fSDK stdin \u68c0\u67e5 8/8 ALL PASS\uff08\u96f6\u5199\u5165\u96f6\u7f51\u7edc\uff09\u3001check_release_offline R1-R7\u3001\u56fa\u5b9aSDK\u56de\u5f52 16/16+12/12+6/6+7/7+12/12\u3002\u96f6\u771f\u5b9e LLM/\u5d4c\u5165/ASR/TTS\u3001\u96f6\u4e0b\u8f7d\u3001\u96f6\u9ea6\u514b\u98ce\u3001\u672a\u542f\u52a8/\u505c\u6b62\u4efb\u4f55\u670d\u52a1\u3001\u4e0d\u90e8\u7f72\u3001\u4e0d\u5408\u5e76 PR\u3001PR#11 \u4e0e hel-870-assembly \u672a\u52a8\u3001\u6743\u5a01\u8d26\u4e0e\u51bb\u7ed3\u672a\u5199\u3001\u771f\u5b9e cap \u4fdd\u6301 0",
"requirement_ids": [
"CG-006",
"CG-008",
"CG-009",
"CG-010",
"CG-011",
"CG-012",
"CG-013",
"CG-014",
"CG-015",
"CG-016",
"CG-018",
"CG-021",
"CG-023",
"CG-029",
"CG-030",
"CG-031",
"VIS-013",
"AM-001",
"AM-002",
"AM-003",
"UX-001",
"UX-005",
"UX-006",
"GOV-001",
"GOV-002",
"GOV-003",
"GOV-004",
"GOV-005",
"GOV-006",
"DEL-001"
],
"deliverable": "\u5206\u652f hel-879-assembly\uff08\u72ec\u7acb\u5019\u9009\uff0c\u672a\u5165 PR#11\uff09\uff1a\u53d1\u5e03\u6536\u53e3 tools/release_snapshot_hel896.py v2\uff08\u5f3a\u5236\u4e00\u81f4\u6027+\u56de\u9000\u6f14\u7ec3\uff09\u3001src/cybergril/life/model.py \u5c01\u8d26\uff08sealed/seal/acquire \u9996\u67e5\uff09\u3001tools/seal_budget_hel879.py\u3001tools/verify_budget_split_hel896.py S6\u3001tools/audit_sdk_offline_hel896.py head \u52a8\u6001\u5316\u3001deploy/hel895-release-candidate.md \u00a70/\u00a72/\u00a74/\u00a75 \u552f\u4e00\u5165\u53e3\u3001deploy/hel874-release.md \u00a72/\u00a74 \u53d6\u4ee3\u6807\u6ce8\u3001deploy/mem0-stack.lock \u6ce8\u91ca\u6536\u53e3\u3001docs/budget-package-hel895.md \u00a76.2 \u53ef\u6267\u884c\u5c01\u8d26\uff1b\u8bed\u97f3\u6574\u5408\uff1aaba2aeb \u540e\u53f0\u6a21\u5757 + c61d9c9 \u524d\u7aef\uff08\u539f\u4f5c\u8005\u89c6\u89c9\u9010\u5b57\u8282\u4fdd\u7559\uff09\u5408\u5e76\u5165\u5019\u9009\uff0c\u6d4b\u8bd5\u5bf9\u9f50\u4e3b\u7ebf\u786c\u95f8\uff1b\u8bc1\u636e docs/rework/hel879/{release-snapshot/selftest.json,sdk-audit/,release-artifacts.json,browser/,release-check/,regression-*.json}\uff1bHEL-879 \u8fd4\u4fee\uff08\u603b\u7ba1\u72ec\u7acb\u590d\u6838\u56db edges\uff0c78a5cfd \u8d77\uff09\uff1a\u2460deploy/voice/serve_dual_8360_8361.py \u5355\u5c5e\u4e3b\u751f\u547d\u5468\u671f\uff08uvicorn lifespan=off\uff0c\u4efb\u4e00\u76d1\u542c\u9000\u51fa\u5148\u505c\u53e6\u4e00\u4e2a\u518d\u5173\u5e93\uff1bapp lifespan \u91cd\u5165\u95e8\u536b fail-closed\uff09\uff1b\u2461voice/session.py \u623f\u95f4\u5f52\u5c5e\u6e05\u7406\u8d26\uff08\u5220\u9664\u6210\u529f\u624d\u51fa\u8d26\u3001\u5931\u8d25\u4fdd\u7559\u53ef\u91cd\u8bd5\u3001\u5230\u671f\u8f6c\u6e05\u7406\u8d26\u771f\u5b9e\u5220\u623f\u3001\u91cd\u542f\u6309\u6301\u4e45\u8d26\u6709\u754c\u8865\u507f\u4ec5\u672c\u5b9e\u4f8b\u623f\u95f4\u3001404=\u5df2\u5220\u5e42\u7b49\u3001\u8def\u7531\u5931\u8d25 503 \u4e0d\u5192\u5145 404\uff09\uff1b\u2462receipt.py TurnLedger \u663e\u5f0f\u7ed1\u5b9a\uff08\u65e0\u751f\u6210\u7684\u8f6e\u4e0d\u541e\u4e0b\u4e00\u8f6e\u6d41/\u56de\u6267\uff0cworker \u5148\u5224\u6253\u65ad/\u5931\u8d25\u518d\u6d88\u8d39\uff09\uff1b\u2463tools/release_snapshot_hel896.py v3\uff08\u4e09\u65b9\u8ba1\u6570\u76f4\u63a5\u76f8\u7b49\u3001rows_match \u53ea\u662f\u989d\u5916\u7ea6\u675f\u3001\u6309\u6e90\u8def\u5f84\u5b9e\u9645\u6062\u590d\u5230\u6301\u4e45\u76ee\u6807\u6811\u3001\u540c\u540d\u5e93\u65e0\u51b2\u7a81\u6620\u5c04\u3001\u91cd\u590d\u6e90\u62d2\u7edd\uff09\uff1bhatchling \u52d8\u8bef\uff08uv v6/v7 \u6709 1.32.4 \u7f13\u5b58\uff09+ \u56fa\u5b9a\u6e90\u79bb\u7ebf\u6784\u5efa mem0ai-2.2.1 \u8f6e\uff08sha256 698284b6\u2026\uff0c\u672a\u5b89\u88c5\u672a\u8054\u7f51\uff09\uff1bhel895 \u53d1\u5e03\u6587\u6863 \u00a70 \u5386\u53f2\u4e0e\u5f53\u524d\u5206\u79bb\u3001\u00a74/\u00a75 \u66f4\u65b0\u3001budget \u00a76.2.4 \u5c01\u8d26\u5e93\u4e0d\u53ef\u62ac cap \u91cd\u5f00\u52d8\u6b63\uff1brunbook \u00a73.3/\u00a73.5/\u00a73.6/\u00a74.4/\u00a74.5 \u4e0e\u524d\u7aef session.ts \u6ce8\u91ca\u52d8\u6b63\uff08\u6ce8\u91ca\u7ea7\uff0c\u65e0\u903b\u8f91/\u6837\u5f0f\u6539\u52a8\uff09\uff1bCG-011 \u4e3b\u52a8\u5f00\u53e3\u4e0e assistant_interim \u589e\u91cf\u5b57\u5e55\u6700\u5c0f\u540e\u53f0\u63a5\u7f1d\uff08src/cybergril/voice/seam.py+worker/llm_chat_api \u63a5\u7ebf\uff0c\u4e3b\u52a8\u5f00\u53e3\u9ed8\u8ba4\u5173\uff1b\u63a5\u53e3\u4e0e\u9a8c\u6536 docs/rework/hel879/voice-seam-interfaces.md\uff09\uff1b.12 \u771f SDK \u68c0\u67e5\u6269\u5c55\u4e3a 10 \u9879\uff08\u65b0\u589e worker \u5b9e\u9645\u56de\u8c03\u8def\u5f84\u4e0e interim seam\uff09\uff1b\u56de\u5f52 tests/test_voice_rework_hel879.py 17 \u4f8b",
"acceptance": [
"归档负例:busy checkpoint(复现 checkpoint=(1,9,8))与行数不一致均失败且零残留产物;rows_match=False 旧包 verify 拒绝;停服口径目录内 SQLite 逐表核对(history=1);在线模式含 SQLite 目录拒绝;verify 输出源路径 rollback_plan",
"封账负例:51/55 提前收尾后任何类别拒绝 budget_sealed:51/55 且用量保持 51;误重启拒绝;backup 归档恢复拒绝;重复 seal 幂等(sealed_at 不变);拒绝不落账",
"seal_budget_hel879.py 端到端:封账→自检 acquire 被拒→CLI ok=true",
"整合后全电池:pytest 324/324、vitest 88/88、typecheck/lint/build、真实服务浏览器 9/9(含零权限/零非回环出站)、语音链 8/8、.12 真SDK 8/8、R1-R7、固定SDK五套回归全绿",
"原作者前端逐字节保留:git diff c61d9c9 HEAD -- web/src 为空;后台 voice 模块 diff aba2aeb 为空"
"\u5f52\u6863\u8d1f\u4f8b\uff1abusy checkpoint\uff08\u590d\u73b0 checkpoint=(1,9,8)\uff09\u4e0e\u884c\u6570\u4e0d\u4e00\u81f4\u5747\u5931\u8d25\u4e14\u96f6\u6b8b\u7559\u4ea7\u7269\uff1brows_match=False \u65e7\u5305 verify \u62d2\u7edd\uff1b\u505c\u670d\u53e3\u5f84\u76ee\u5f55\u5185 SQLite \u9010\u8868\u6838\u5bf9\uff08history=1\uff09\uff1b\u5728\u7ebf\u6a21\u5f0f\u542b SQLite \u76ee\u5f55\u62d2\u7edd\uff1bverify \u8f93\u51fa\u6e90\u8def\u5f84 rollback_plan",
"\u5c01\u8d26\u8d1f\u4f8b\uff1a51/55 \u63d0\u524d\u6536\u5c3e\u540e\u4efb\u4f55\u7c7b\u522b\u62d2\u7edd budget_sealed:51/55 \u4e14\u7528\u91cf\u4fdd\u6301 51\uff1b\u8bef\u91cd\u542f\u62d2\u7edd\uff1bbackup \u5f52\u6863\u6062\u590d\u62d2\u7edd\uff1b\u91cd\u590d seal \u5e42\u7b49\uff08sealed_at \u4e0d\u53d8\uff09\uff1b\u62d2\u7edd\u4e0d\u843d\u8d26",
"seal_budget_hel879.py \u7aef\u5230\u7aef\uff1a\u5c01\u8d26\u2192\u81ea\u68c0 acquire \u88ab\u62d2\u2192CLI ok=true",
"\u6574\u5408\u540e\u5168\u7535\u6c60\uff1apytest 324/324\u3001vitest 88/88\u3001typecheck/lint/build\u3001\u771f\u5b9e\u670d\u52a1\u6d4f\u89c8\u5668 9/9\uff08\u542b\u96f6\u6743\u9650/\u96f6\u975e\u56de\u73af\u51fa\u7ad9\uff09\u3001\u8bed\u97f3\u94fe 8/8\u3001.12 \u771fSDK 8/8\u3001R1-R7\u3001\u56fa\u5b9aSDK\u4e94\u5957\u56de\u5f52\u5168\u7eff",
"\u539f\u4f5c\u8005\u524d\u7aef\u9010\u5b57\u8282\u4fdd\u7559\uff1agit diff c61d9c9 HEAD -- web/src \u4e3a\u7a7a\uff1b\u540e\u53f0 voice \u6a21\u5757 diff aba2aeb \u4e3a\u7a7a",
"\u8fd4\u4feeedges\uff1a\u53cc\u7aef\u53e3\u540c\u8fdb\u7a0b\u5355\u6b21\u521d\u59cb\u5316\uff08\u53cc\u7aef\u540c epoch\u3001Store \u5355\u5b9e\u4f8b\u3001\u76d1\u542c\u5168\u90e8\u9000\u51fa\u540e\u624d\u5173\u5e93\u4e14\u53ea\u5173\u4e00\u6b21\uff09\uff1b\u5220\u623f\u5931\u8d25\u2192503 \u4fdd\u7559\u5f52\u5c5e\u3001\u91cd\u8bd5\u771f\u5b9e\u518d\u5220\uff08\u22652 \u6b21\u5c1d\u8bd5\uff09\u3001\u5230\u671f\u7aef\u5230\u7aef\u771f\u5b9e\u5220\u623f\uff08\u65e7\u7248 0 \u6b21\uff09\uff1bH1 \u65e0\u751f\u6210/H2 \u6709 S2 \u4ea4\u9519\u65f6 H1 \u5f97 None\u3001H2 \u5f97 S2\uff08.12 \u771f SpeechHandle/SpeechCreatedEvent \u5b9e\u8dd1\uff09\uff1brows_match=true+\u6e902/\u5feb\u71671 \u7684\u5305 verify \u62d2\u7edd\uff1b\u540c\u540d ledger.db \u5feb\u7167\u4e0d\u4e92\u76f8\u8986\u76d6\u4e14\u6062\u590d\u6811\u6309\u6e90\u8def\u5f84\u5404\u81ea\u843d\u4f4d",
"\u63a5\u7f1d\u9a8c\u6536\uff08\u79bb\u7ebf\uff09\uff1aassistant_interim \u7d2f\u79ef\u66ff\u6362+reset \u4e0d\u8de8\u8f6e\uff1bproactive \u53ea\u9009\u5df2\u843d\u5e93 proactive=1 sent companion \u884c\u6700\u65b0\u4e00\u6761\u4e14\u672c\u623f\u95f4\u672a\u5ff5\u8fc7\uff1b\u5747\u4e0d\u65b0\u589e\u6743\u9650/\u51fa\u7ad9"
],
"deferred": [
"真实通话验收(连续≥3轮、1秒开口打断、结束即停麦、无旧残音、断网清理、重开同档案):真实调用/D1音色/可信HTTPS设备路径/预算上限未获批,待主卡一次申请",
"会话到期/API重启后 LiveKit 房间与 worker 真实释放证据:_prune 仅删内存登记、end_session 有 delete_room,但『重启房间自然消亡』需真实环境验证,未测不冒充",
"增量字幕(worker 仅 final,interim 契约缺口):R5 字幕先行与完整产品要求不降级",
"CG-011 语音主动开口仍为显式 no-op 接缝",
"R6 天气/素材/每日与手动完整备份、R7 有条件观察:继续主卡承接",
"固定 SDK 真缺下载(37 项+hatchling)与 A/B/C 预算授权:待总管主卡一次申请",
"产品 PR#4、旧小样 PR#6、新小样 PR#8、发布 PR#11 均未合并未替换正式界面"
"\u771f\u5b9e\u901a\u8bdd\u9a8c\u6536\uff08\u8fde\u7eed\u22653\u8f6e\u30011\u79d2\u5f00\u53e3\u6253\u65ad\u3001\u7ed3\u675f\u5373\u505c\u9ea6\u3001\u65e0\u65e7\u6b8b\u97f3\u3001\u65ad\u7f51\u6e05\u7406\u3001\u91cd\u5f00\u540c\u6863\u6848\uff09\uff1a\u771f\u5b9e\u8c03\u7528/D1\u97f3\u8272/\u53ef\u4fe1HTTPS\u8bbe\u5907\u8def\u5f84/\u9884\u7b97\u4e0a\u9650\u672a\u83b7\u6279\uff0c\u5f85\u4e3b\u5361\u4e00\u6b21\u7533\u8bf7",
"\u4f1a\u8bdd\u5230\u671f/API\u91cd\u542f\u540e LiveKit \u623f\u95f4\u4e0e worker \u771f\u5b9e\u91ca\u653e\u8bc1\u636e\uff1a_prune \u4ec5\u5220\u5185\u5b58\u767b\u8bb0\u3001end_session \u6709 delete_room\uff0c\u4f46\u300e\u91cd\u542f\u623f\u95f4\u81ea\u7136\u6d88\u4ea1\u300f\u9700\u771f\u5b9e\u73af\u5883\u9a8c\u8bc1\uff0c\u672a\u6d4b\u4e0d\u5192\u5145",
"\u589e\u91cf\u5b57\u5e55\uff08worker \u4ec5 final\uff0cinterim \u5951\u7ea6\u7f3a\u53e3\uff09\uff1aR5 \u5b57\u5e55\u5148\u884c\u4e0e\u5b8c\u6574\u4ea7\u54c1\u8981\u6c42\u4e0d\u964d\u7ea7",
"CG-011 \u8bed\u97f3\u4e3b\u52a8\u5f00\u53e3\u4ecd\u4e3a\u663e\u5f0f no-op \u63a5\u7f1d",
"R6 \u5929\u6c14/\u7d20\u6750/\u6bcf\u65e5\u4e0e\u624b\u52a8\u5b8c\u6574\u5907\u4efd\u3001R7 \u6709\u6761\u4ef6\u89c2\u5bdf\uff1a\u7ee7\u7eed\u4e3b\u5361\u627f\u63a5",
"\u56fa\u5b9a SDK \u771f\u7f3a\u4e0b\u8f7d\uff0837 \u9879+hatchling\uff09\u4e0e A/B/C \u9884\u7b97\u6388\u6743\uff1a\u5f85\u603b\u7ba1\u4e3b\u5361\u4e00\u6b21\u7533\u8bf7",
"\u4ea7\u54c1 PR#4\u3001\u65e7\u5c0f\u6837 PR#6\u3001\u65b0\u5c0f\u6837 PR#8\u3001\u53d1\u5e03 PR#11 \u5747\u672a\u5408\u5e76\u672a\u66ff\u6362\u6b63\u5f0f\u754c\u9762"
],
"requirement_changes": [],
"verification": [
"docs/rework/hel879/release-snapshot/selftest.json(9/9,先复现旧失败形状再证修复)",
"docs/rework/hel896/budget-split/budget-split.json(10/10 含 S6 提前封账负例,本 head 重跑)",
"docs/rework/hel879/sdk-audit/ 与 release-artifacts.json(闭包 55/缺 41/可复用 3,tarball 哈希实测=lock,精确提交)",
"docs/rework/hel879/browser/real-browser.json(9/9 真实服务浏览器,零权限调用、零非回环出站)",
"docs/rework/hel879/release-check/hel882-release-check.json(R1-R7)与 regression-*.json(固定SDK 16/16、12/12、6/6、7/7、12/12)",
".12 livekit-agents 1.8.8 真 SDK stdin 检查 8/8 ALL PASS(零写入零网络,输出在运行日志)",
"未验证:真机/Safari/真实通话/部署环境;工程检查不代表用户体验验收"
"docs/rework/hel879/release-snapshot/selftest.json\uff089/9\uff0c\u5148\u590d\u73b0\u65e7\u5931\u8d25\u5f62\u72b6\u518d\u8bc1\u4fee\u590d\uff09",
"docs/rework/hel896/budget-split/budget-split.json\uff0810/10 \u542b S6 \u63d0\u524d\u5c01\u8d26\u8d1f\u4f8b\uff0c\u672c head \u91cd\u8dd1\uff09",
"docs/rework/hel879/sdk-audit/ \u4e0e release-artifacts.json\uff08\u95ed\u5305 55/\u7f3a 41/\u53ef\u590d\u7528 3\uff0ctarball \u54c8\u5e0c\u5b9e\u6d4b=lock\uff0c\u7cbe\u786e\u63d0\u4ea4\uff09",
"docs/rework/hel879/browser/real-browser.json\uff089/9 \u771f\u5b9e\u670d\u52a1\u6d4f\u89c8\u5668\uff0c\u96f6\u6743\u9650\u8c03\u7528\u3001\u96f6\u975e\u56de\u73af\u51fa\u7ad9\uff09",
"docs/rework/hel879/release-check/hel882-release-check.json\uff08R1-R7\uff09\u4e0e regression-*.json\uff08\u56fa\u5b9aSDK 16/16\u300112/12\u30016/6\u30017/7\u300112/12\uff09",
".12 livekit-agents 1.8.8 \u771f SDK stdin \u68c0\u67e5 8/8 ALL PASS\uff08\u96f6\u5199\u5165\u96f6\u7f51\u7edc\uff0c\u8f93\u51fa\u5728\u8fd0\u884c\u65e5\u5fd7\uff09",
"\u672a\u9a8c\u8bc1\uff1a\u771f\u673a/Safari/\u771f\u5b9e\u901a\u8bdd/\u90e8\u7f72\u73af\u5883\uff1b\u5de5\u7a0b\u68c0\u67e5\u4e0d\u4ee3\u8868\u7528\u6237\u4f53\u9a8c\u9a8c\u6536"
]
}
}
Binary file not shown.

Before

Width:  |  Height:  |  Size: 438 KiB

After

Width:  |  Height:  |  Size: 438 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 441 KiB

After

Width:  |  Height:  |  Size: 441 KiB

+22 -2
View File
@@ -2,6 +2,7 @@
"card": "HEL-879",
"generated_by": "release-artifacts inventory (offline, zero downloads)",
"release_code_commit": "01ff91985920162cddabc5f190d146d86793627d",
"rework_head": "see delivery comment (branch hel-879-assembly, appended after 7f0a739; this inventory refreshed on that head)",
"audit_evidence": "docs/rework/hel879/sdk-audit/sdk-audit.json (head c121c42e39174e0f627f129e7f7e5700f33acf26)",
"single_install_entry": "deploy/hel895-release-candidate.md #4 (supersedes deploy/hel874-release.md #4)",
"fixed_source": {
@@ -115,9 +116,28 @@
]
}
],
"build_backend_gap": {
"build_backend": {
"hatchling_cached_or_local": true,
"note": "固定源码构建仍缺 hatchling;如实保留,未获批不联网补齐"
"hatchling_version": "1.32.4",
"hatchling_cache_evidence": [
"uv wheels-v6: ~/.cache/uv/wheels-v6/pypi/hatchling/1.32.4-py3-none-any",
"uv wheels-v7: ~/.cache/uv/wheels-v7/pypi/hatchling/1.32.4-py3-none-any",
"uv archive-v0 unpacked: hatchling-1.32.4.dist-info (wheels-v6 + wheels-v7 linked copies)"
],
"offline_wheel_built": {
"built_at": "2026-10-27T04:10:00Z",
"command": "cd <extracted mem0-2c81af3 tarball> && uv build --wheel --offline --python 3.11 -o <out>",
"tool": "uv 0.13.5, uv-managed CPython 3.11.16, build backend hatchling from the offline cache only",
"source_tarball_sha256": "9dcef9303ebcec116eec6739f01b8b35bd24459de6a569686b4d19b9412dda23",
"source_commit": "2c81af3bbe27d9bccb09c772d583df9e9be72ee5",
"wheel": "mem0ai-2.2.1-py3-none-any.whl",
"wheel_sha256": "698284b6083ab8b7761454d65876a6d1bb983d278ad21a7bee38d760cb20e9db",
"wheel_bytes": 352586,
"wheel_files": 153,
"installed_anywhere": false,
"network_used": false,
"note": "HEL-879 勘误:v1 清单一面写 hatchling_cached_or_local=true 一面又称本机缺 hatchling,并把 hatchling 列入待下载——总管只读核查指出 uv v6/v7 均有 1.32.4 缓存。已核实并直接完成可离线构建:固定源码 tarball(sha 与 lock 一致)经缓存 hatchling 离线构建出上面这只 wheel,未安装、未联网、未混 3.10 site-packages。待下载清单据此只余 41 项运行闭包(不含 hatchling)。"
}
},
"fastembed_models": {
"cache_dir": "/home/xiaomo/multica_workspaces/hello-af23464d222e/hel-857-2cf6dc7dfc87/workdir/hel857-data/fastembed-cache",
+1 -1
View File
@@ -1,5 +1,5 @@
{
"head": "c121c42e39174e0f627f129e7f7e5700f33acf26",
"head": "78a5cfd8d75e3cfd00c60dc5c3592eb08cc757a1",
"scope": "只读审计:3.10 固定栈安装元数据按 3.11 Linux markers+extras 求闭包,对照产品 3.11 venv 与本机 uv/pip 缓存;这是依赖闭包清单,不是已完成的 cp311 解析或下载结果",
"read_only": true,
"zero_downloads_this_card": true,
@@ -0,0 +1,16 @@
# HEL-879 rework: real-SDK check regenerated from THIS head's voice sources
# head: 78a5cfd8d75e3cfd00c60dc5c3592eb08cc757a1
# run: 2026-10-26T20:16:05Z, .12 /opt/voice-agent/agent/venv/bin/python (livekit-agents 1.8.8), stdin-only, zero writes zero network, no service touched
# generator: scripts/gen_hel877_sdk_check.py (10 checks; #9/#10 new: worker callback path on real SpeechHandle/SpeechCreatedEvent; assistant_interim seam through real LLMStream)
HEL-877/879 real-SDK check on livekit-agents 1.8.8: ALL PASS
OK CyberGrillLLM/ChatApiLLMStream subclass real livekit-agents 1.8.8 LLM/LLMStream
OK latest_user_text reads a real ChatContext (items/role/text_content)
OK fake-SSE turn through real LLMStream emits ChatChunks, final text and receipt
OK chat.error phi is spoken verbatim via ChatChunk and carries no receipt
OK mint_token claims byte-parity with livekit.api.AccessToken (video/iss/sub/keys)
OK mint_server_token matches SDK no-grant auth header claims
OK worker.py SDK surface (SpeechHandle, UserInputTranscribedEvent.is_final) present
OK barge-in task cancel closes the in-flight HTTP stream immediately
OK worker callback path on real SpeechHandle/SpeechCreatedEvent: no-generation handle discards, next turn keeps its own stream (explicit binding)
OK assistant_interim seam: SSE deltas through real LLMStream feed her incremental subtitle payloads (replace semantics, reset works)
@@ -0,0 +1,80 @@
# HEL-879 · 语音接缝接口与验收(交原视觉作者接线;总工不改已认可 web/src 视觉)
> 背景:总管独立复核指出「CG-011 语音主动开口 no-op、她的增量字幕缺失」是
> **实现缺口**,不能归为「等音色/预算就能自动完成」。本文件给出后台已落地的
> 最小接缝、前端需要补的**精确接口**与**验收标准**。代码基点:分支
> `hel-879-assembly`(见交付评论精确 head);后台实现
> `src/cybergril/voice/seam.py` + `worker.py` 接线。
## A. 她的增量回复字幕(assistant_interim)
### 现状与缺口
- 用户侧 ASR 字幕已齐:`interim`(ASR 草稿)与 `user_final`(纠错终稿)在
`web/src/voice/session.ts` 已渲染(现有 `interim` 分支当「听到用户在说」处理,
**不能复用来渲染她的回复**——那是另一个语义)。
- 缺的是**她**的回复在 TTS 首包前/播放中的增量文字。后台现已补齐:worker 把
/api/chat SSE 的每个 delta 累积后发布到同一 `cg.subtitle` 通道。
### 后台已交付(无需前端改动即生效的数据)
- 数据通道:topic `cg.subtitle`(不变)。
- 新 kind:`assistant_interim`,`role: "assistant"`,`text` 为**截至当前的完整
回复文本**(替换语义,同用户 interim;发布时机=SSE 分片到达,先于/伴随 TTS)。
- 既有 kind 不变:`assistant_final`(已落库的完整回复,播放完成且未打断后发)、
`error`(φ 原句,未落库)、`interim`/`user_final`(用户侧)。
- fail-closed 语义不变:打断/失败/无回执的轮**只有 interim,不会有 final**——
前端必须把无 final 收尾的 interim 按「这轮没有成为她的正式回复」处理。
### 前端需补(原视觉作者;具体视觉由其定)
1. `web/src/voice/session.ts` 字幕分支:新增 `assistant_interim` 处理(当前
`if (s.kind === 'interim')` 只覆盖用户草稿)。
2. 渲染位置/样式:与 `assistant_final` 同一气泡位(建议替换式过渡),与用户
`heard` 视觉可区分;**不进入正式聊天记录**(只有 final 落库)。
3. 收尾规则:`assistant_final` 到达 → interim 消失、final 生效;`error` 到达 →
interim 消失、按现有 error 呈现;被打断(无任何收尾)→ 下一次 interim 或
新轮开始时清掉;挂断 → 清掉。
### 验收(离线可测,无需真实通话)
- [ ] 用假 LiveKit/假音频脚本回放 `cg.subtitle` 序列
`interim(user) → user_final → assistant_interim("她在") →
assistant_interim("她在打字中") → assistant_final("她在打字中。")`,
页面按序呈现且 interim 被 final 原子替换。
- [ ] 打断负例:`assistant_interim` 后直接新的 `interim(user)`(无 final/error),
她的 interim 残影不越过新用户轮。
- [ ] φ 负例:`assistant_interim` → `error`,error 文案呈现且不落正式记录。
- [ ] 全程零新增权限申请、零非回环出站(沿用 HEL-896 浏览器检查口径)。
## B. CG-011 语音主动开口(最小接缝,默认关闭)
### 后台已交付
- `worker.py _maybe_open_proactive`(真实代码路径,`CYBERGRIL_PROACTIVE_VOICE=1`
才启用;**默认关**,等接线卡与呈现批准):
- 数据来源:与文字收件箱同一 `GET /api/messages`(`ChatApiClient.recent_messages`),
只选**服务端已落库**(`proactive=1`、`role=companion`、`status=sent`、非空、
本房间未念过)的行,最新优先,每会话 ≤1 条(`PROACTIVE_PER_SESSION`)。
- 播报:`session.say(text, allow_interruptions=True)`——可被用户打断;
无新模型调用、无第二人格、**无第二条回执通道**(文字回执规则独立且已存在)。
- 失败 fail-closed:接缝任何异常只记日志跳过,不影响会话开启。
- 选择逻辑独立在 `seam.py pick_proactive/pending_proactive`(离线可测,
`tests/test_voice_rework_hel879.py` 三例覆盖)。
### 前端/接线卡需定(原视觉作者 + 总管,经用户批准后启用)
1. 入口呈现:她主动开口时页面如何呈现(字幕走 `assistant_final` 同位?
是否复用留言卡「回她」入口语义?未读标记如何联动——**worker 不代标已读**,
阅读态仍归页面)。
2. 节奏:会话开启后何时念(现在=开启即查一次、每会话最多一条);是否需要在
会话中轮询新 proactive(后续卡,不默记完成)。
3. 打断呈现:用户开口打断她的主动播报时,字幕按打断负例处理(无 final 收尾)。
### 验收(启用后)
- [ ] 预置一条落库 proactive 行 → 开语音会话 → 她原文念出该行(与文字收件箱
同一行、一字不差),字幕按定稿呈现。
- [ ] 播报中用户开口 → 立即被打断、无残音;该行不被标记已读(除非用户在页面
读它)、无回执伪造。
- [ ] 无 proactive 行 → 会话正常开启,静默。
- [ ] API 不可达 → 接缝跳过,语音会话不受影响。
## 边界
- 本文件只交接口与验收;**总工未改任何已认可 web/src 视觉**(本卡 web/src 仅
勘正 session.ts 一处无证据注释,无逻辑/样式改动,diff 见交付评论)。
- R5 真机验收(≥3 轮、1 秒打断、停麦无残音、可信 HTTPS/WSS、D1 音色、有限
预算)仍待主卡集中批准,接缝通过≠R5 完成。
+1 -1
View File
@@ -37,5 +37,5 @@
}
],
"failures": [],
"service_stderr_tail": "INFO: Started server process [1535952]\nINFO: Waiting for application startup.\nINFO: Application startup complete.\nINFO: Uvicorn running on http://127.0.0.1:8395 (Press CTRL+C to quit)\nINFO: Shutting down\nINFO: Waiting for application shutdown.\nINFO: Application shutdown complete.\nINFO: Finished server process [1535952]\n"
"service_stderr_tail": "INFO: Started server process [1595966]\nINFO: Waiting for application startup.\nINFO: Application startup complete.\nINFO: Uvicorn running on http://127.0.0.1:8395 (Press CTRL+C to quit)\nINFO: Shutting down\nINFO: Waiting for application shutdown.\nINFO: Application shutdown complete.\nINFO: Finished server process [1595966]\n"
}
@@ -1,5 +1,5 @@
{
"head": "7f66015ac854b7f513a35a42b680a143058561bb",
"head": "78a5cfd8d75e3cfd00c60dc5c3592eb08cc757a1",
"no_provider_calls": true,
"temp_only": true,
"scenes": {
@@ -65,12 +65,12 @@
"marker": {
"requests": 51,
"tokens": 510,
"sealed_at": 1793043424
"sealed_at": 1793045944
},
"next_after_seal": "budget_sealed:51/55(封账于 1793043424,真实用量保留,不伪造、不清零)",
"other_scene_after_seal": "budget_sealed:51/55(封账于 1793043424,真实用量保留,不伪造、不清零)",
"after_restart": "budget_sealed:51/55(封账于 1793043424,真实用量保留,不伪造、不清零)",
"after_archive_restore": "budget_sealed:51/55(封账于 1793043424,真实用量保留,不伪造、不清零)",
"next_after_seal": "budget_sealed:51/55(封账于 1793045944,真实用量保留,不伪造、不清零)",
"other_scene_after_seal": "budget_sealed:51/55(封账于 1793045944,真实用量保留,不伪造、不清零)",
"after_restart": "budget_sealed:51/55(封账于 1793045944,真实用量保留,不伪造、不清零)",
"after_archive_restore": "budget_sealed:51/55(封账于 1793045944,真实用量保留,不伪造、不清零)",
"idempotent_reseal": true
},
"S3_user_instance": {
@@ -120,12 +120,12 @@
{
"name": "S6a_early_finish_51_seals_real_usage_no_fake_no_zero",
"ok": true,
"detail": "used=51 dialogue_next=budget_sealed:51/55(封账于 1793043424,真实用量保留,不伪造、不清零) semantic_next=budget_sealed:51/55(封账于 1793043424,真实用量保留,不伪造、不清零) after=51 dialogue_daily=19/60"
"detail": "used=51 dialogue_next=budget_sealed:51/55(封账于 1793045944,真实用量保留,不伪造、不清零) semantic_next=budget_sealed:51/55(封账于 1793045944,真实用量保留,不伪造、不清零) after=51 dialogue_daily=19/60"
},
{
"name": "S6b_seal_survives_restart_and_archive_restore",
"ok": true,
"detail": "restart=budget_sealed:51/55(封账于 1793043424,真实用量保留,不伪造、不清零) archive=budget_sealed:51/55(封账于 1793043424,真实用量保留,不伪造、不清零) arch_used=51 marker={'requests': 51, 'tokens': 510, 'sealed_at': 1793043424}"
"detail": "restart=budget_sealed:51/55(封账于 1793045944,真实用量保留,不伪造、不清零) archive=budget_sealed:51/55(封账于 1793045944,真实用量保留,不伪造、不清零) arch_used=51 marker={'requests': 51, 'tokens': 510, 'sealed_at': 1793045944}"
},
{
"name": "S3_user_instance_B_and_C_unblocked_after_A",
+42 -17
View File
@@ -34,7 +34,8 @@
- **回执**:`chat.final.receipt` 只在 speech handle `wait_for_playout()` 完成、未 `interrupted`、
无异常、轮次完整时 POST `/api/chat/received`(`receipt.py should_ack` 全负例有测试);
服务端仍独立校验 token/hash/过期(fail-closed 双保险)。
- **主动开口(CG-011 接缝)**:`worker.py _maybe_open_proactive()` 为空操作占位,契约见 §3.6;
- **主动开口(CG-011 接缝,HEL-879)**:`worker.py _maybe_open_proactive()` 为
真实最小接缝(默认关闭,`CYBERGRIL_PROACTIVE_VOICE=1` 启用),契约见 §3.6;
要求:仅已开启会话内、只念服务端已落库 proactive 行、可打断、不新造第二条回执通道。
## 3. 前端契约(交视觉总监接线)
@@ -52,9 +53,14 @@
### 3.3 字幕
- worker 在房间数据通道 topic `cg.subtitle` 发布 JSON:
`{kind: "interim"|"user_final"|"assistant_final"|"error", role: "user"|"assistant", text}`。
interim 是 ASR 草稿(可频繁覆盖),user_final 是纠错终稿,assistant_final 是她的话(已落库),
error 是 φ 原句(未落库,前端不得当作她说过的话进入正式记录)。
`{kind: "interim"|"user_final"|"assistant_interim"|"assistant_final"|"error",
role: "user"|"assistant", text}`。
interim 是用户 ASR 草稿(可频繁覆盖),user_final 是纠错终稿;
**assistant_interim(HEL-879 接缝)是她的回复在 TTS 首包前/播放中的增量文字
(累积替换语义,不落库,最终被 assistant_final 或 error 收尾,打断则无收尾)**;
assistant_final 是她的话(已落库),error 是 φ 原句(未落库,前端不得当作她
说过的话进入正式记录)。前端接线契约与验收:
`docs/rework/hel879/voice-seam-interfaces.md`。
### 3.4 失败 / 打断 / 挂断
- 失败:听到 φ + `error` 字幕;草稿保留;用户可开口重试(新 turn)。
@@ -64,13 +70,26 @@
前端仍应 stop 本地 track 立即停麦。
### 3.5 会话边界
- 一房一会话;重复 POST 得到新房间新 token(旧房不受影响)。结束/失效后 session_id 再用 → 404。
- 会话登记内存态、随进程;实例重启后房间自然消亡,前端按 503/404 如实处理。
- 一房一会话;重复 POST 得到新房间新 token(旧房不受影响)。结束/失效后 session_id 再用 → 404;
**删除失败时的 503 不是 404**——房间仍在服务端的清理账上,浏览器继续保留欠账
DELETE,重试会真实再删(HEL-879 返修:旧版先删登记再删远端,失败后重试直接
404、房间从此没人删)。
- 会话登记随进程,另有**持久清理账**(实例数据目录 `<db>-voice-sessions.json`,
HEL-879 返修):房间从创建起即归属本实例,删除成功才出账;到期/掉线/关闭/
重启由有界补偿清理(次数与 TTL+宽限期双上限,超限记 `abandoned` 原因留证、
不再重试),且只删本实例自己记录的房间,不碰通用 worker 或其他实例。
~~实例重启后房间自然消亡~~ **勘误**:旧版该句无证据——重启后补偿只删自己
登记过的房间、且给存活通话留到 TTL;LiveKit 房间/worker 在 API 重启后的真实
释放仍待获批环境实测,不以本句冒充。
### 3.6 主动开口接缝(本卡不实现)
- 后续接线卡方案:会话开启后 worker 经统一 API 取「已落库、proactive=1、未读」的 companion 行,
`session.say()` 原文念出(allow_interruptions 开启),可被打断;不新起模型调用、不伪造新经历、
不新建回执通道(文字回执规则独立、已存在)。呈现节奏由总管/视觉总监定,未经批准不启用。
### 3.6 主动开口接缝(HEL-879:真实代码路径,默认关闭)
- `worker.py _maybe_open_proactive`(`seam.py` 提供可离线测试的选择逻辑):开启
`CYBERGRIL_PROACTIVE_VOICE=1` 后,会话开启即经统一 `GET /api/messages` 取
「已落库、proactive=1、status=sent、本房间未念过」的 companion 行(最新一条),
`session.say()` 原文念出(allow_interruptions 可打断);不新起模型调用、不伪造
新经历、不新建回执通道(文字回执规则独立、已存在)、不代页面标已读;接缝
异常只跳过不伤会话。入口呈现、节奏与启用由总管/视觉总监在接线卡定
(`docs/rework/hel879/voice-seam-interfaces.md`),未经批准保持默认关闭。
## 4. 部署草案(本卡未执行;总工执行,逐条核对授权)
@@ -101,17 +120,23 @@ CosyVoice 9880。**不改 /opt/voice-agent 任何文件,不动 8090 与通用
- 停止仅停本 worker;回滚不影响语音底座其他组件。
### 4.4 HTTP 8360 与 HTTPS 入口同进程(硬要求)
`deploy/voice/serve_dual_8360_8361.py` 在一个事件循环里跑两个 uvicorn Server 指向**同一个**
FastAPI 应用对象:同一 epoch、同一 `chat_lock`、同一 store、同一语音会话登记——
绝不许两个写同一 DB 的独立实例。自签证书按 8090 已验证流程签一张覆盖 `192.168.200.12`
的证书( openssl req -x509 … subjectAltName=IP:192.168.200.12 ),存
`/opt/cybergril-voice-certs/`(600)。本卡已在本地 18360/18361 用一次性自签证书冒烟验证
同进程双入口(单 pid、同 epoch、两端诚实拒答),**未在 .12 执行**。
`deploy/voice/serve_dual_8360_8361.py` 在一个事件循环里跑两个 uvicorn Server 指向
**同一个** FastAPI 应用对象,且**应用生命周期只由该启动器进入一次**(两个 Server
以 `lifespan="off"` 只负责监听;HEL-879 返修:旧版两个 Server 默认各进一次 lifespan,
epoch 1→2、Store/锁全部被第二次初始化替换;应用 lifespan 现带重入门卫,二次进入
直接报错)。同一 epoch、同一 `chat_lock`、同一 store、同一语音会话登记;任一监听
退出先停另一个、再关生命周期,绝不许两个写同一 DB 的独立实例。自签证书按 8090 已
验证流程签一张覆盖 `192.168.200.12` 的证书( openssl req -x509 …
subjectAltName=IP:192.168.200.12 ),存 `/opt/cybergril-voice-certs/`(600)。
本卡已在本地 18360/18361 用一次性自签证书冒烟验证同进程双入口(单次初始化、双端
同 epoch、退出先停监听再关库),**未在 .12 执行**。
### 4.5 回滚
1. 停专属 worker(4.3);2. API 侧移除/改名 `config/voice.yaml` → `/api/voice/*` 如实 503,
其余功能不受影响;3. 如需整体回退:停双入口进程 → 数据目录原样保留 → 切回上一 release。
语音不写任何新表:会话登记在内存,receipt 走既有 sharing_attempt,无迁移无残留。
语音不写产品库新表:会话登记在内存 + 实例数据目录旁的清理账 JSON
(HEL-879 返修,只记录本实例房间归属),receipt 走既有 sharing_attempt,
无迁移;回滚时清理账文件随数据目录原样保留或随实例删除,不留悬挂资源。
## 5. 自测与证据(全部零真实请求)
+89 -3
View File
@@ -1,9 +1,14 @@
#!/usr/bin/env python3
"""Generate the HEL-877 real-SDK compatibility check for the .12 agent venv.
"""Generate the HEL-877/879 real-SDK compatibility check for the .12 agent venv.
Embeds the repo voice-module sources in a self-contained stdin script (no files
written to .12, no network, no service touched) and runs it with
/opt/voice-agent/agent/venv/bin/python (livekit-agents 1.8.8, livekit 1.1.20).
HEL-879 additions: the check drives the WORKER'S ACTUAL callback path with real
SpeechHandle/SpeechCreatedEvent objects — the handle-without-generation and
late-cleanup interleavings from the manager's independent review — and verifies
the assistant_interim delta seam through the real LLMStream machinery.
"""
from __future__ import annotations
@@ -12,7 +17,7 @@ import sys
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
MODULES = ["chat_api_client", "receipt", "llm_chat_api"]
MODULES = ["chat_api_client", "receipt", "seam", "llm_chat_api"]
TEMPLATE = r'''
import asyncio, base64, json, sys, types
@@ -174,7 +179,88 @@ async def cancel_case():
asyncio.run(cancel_case())
ok.append("barge-in task cancel closes the in-flight HTTP stream immediately")
print("HEL-877 real-SDK check on livekit-agents", end=" ")
# 9. HEL-879: the worker's ACTUAL callback path on real SpeechHandle objects —
# the manager's two interleavings (handle without generation consuming the
# next turn's stream; late cleanup) plus interrupt/failure discard order,
# driven exactly like worker.entrypoint wires them.
from livekit.agents.voice.speech_handle import SpeechHandle
from livekit.agents.voice.events import SpeechCreatedEvent
receipt_mod = sys.modules["cybergril.voice.receipt"]
seam_mod = sys.modules["cybergril.voice.seam"]
async def worker_callback_path():
ledger = receipt_mod.TurnLedger()
done_futures = []
def on_speech_created(ev): # same guard + wiring as worker._on_speech_created
if not ev.user_initiated:
return
ledger.note_handle(ev.speech_handle, ev.created_at)
ev.speech_handle.add_done_callback(
lambda handle=ev.speech_handle: asyncio.get_running_loop().create_task(
after_playout(handle)
)
)
async def after_playout(handle): # same order as worker._after_playout
await handle.wait_for_playout()
failed = handle.exception() is not None
if handle.interrupted or failed:
ledger.discard(handle)
done_futures.append(("discarded", handle))
return
stream = ledger.stream_for(handle)
done_futures.append((stream, handle))
# H1: real handle, its turn is interrupted BEFORE any LLM stream starts.
h1 = SpeechHandle.create()
ev1 = SpeechCreatedEvent(user_initiated=True, source="generate_reply",
speech_handle=h1, created_at=1.0)
on_speech_created(ev1)
# H2: the next turn does start a generation (real handle + noted stream).
h2 = SpeechHandle.create()
ev2 = SpeechCreatedEvent(user_initiated=True, source="generate_reply",
speech_handle=h2, created_at=2.0)
on_speech_created(ev2)
s2 = types.SimpleNamespace(turn_id="new", receipt={"message_id": 2})
ledger.note_stream(s2, 2.1)
# Complete both handles through the SDK's own done-future machinery:
# H1 was interrupted (public interrupt()) before any generation started;
# H2 played out cleanly (done, no error).
h1.interrupt()
h1._mark_done()
h2._mark_done()
await asyncio.sleep(0.05) # let the scheduled done callbacks run
outcomes = {id(handle): (stream, handle) for stream, handle in done_futures}
assert outcomes[id(h1)][0] == "discarded", "interrupted handle must discard fail-closed"
assert outcomes[id(h2)][0] is s2, "the real turn must get its OWN stream"
# The manager's exact inputs, re-checked through stream_for directly:
assert ledger.stream_for(h1) is None
asyncio.run(worker_callback_path())
ok.append("worker callback path on real SpeechHandle/SpeechCreatedEvent: no-generation "
"handle discards, next turn keeps its own stream (explicit binding)")
# 10. HEL-879: assistant_interim seam through the REAL LLMStream machinery.
interim_payloads = []
async def interim_seam():
publisher = seam_mod.AssistantInterimPublisher(interim_payloads.append)
adapter = llm_mod.CyberGrillLLM("http://x", client=llm_mod.ChatApiClient(
"http://x", transport=httpx.MockTransport(handler)),
on_assistant_delta=publisher.feed)
publisher.reset()
stream = adapter.chat(chat_ctx=ctx)
async for _ in stream:
pass
assert [p["text"] for p in interim_payloads] == ["真实链路上", "真实链路上的一句完整回复。"]
assert all(p["kind"] == "assistant_interim" and p["role"] == "assistant"
for p in interim_payloads)
asyncio.run(interim_seam())
ok.append("assistant_interim seam: SSE deltas through real LLMStream feed her "
"incremental subtitle payloads (replace semantics, reset works)")
print("HEL-877/879 real-SDK check on livekit-agents", end=" ")
import importlib.metadata as md
print(md.version("livekit-agents") + ":", "ALL PASS")
for line in ok:
+10
View File
@@ -66,6 +66,16 @@ class ChatApiClient:
raise ChatApiConnectionError("health response missing epoch")
return epoch
async def recent_messages(self, limit: int = 20) -> list[dict[str, Any]]:
"""Newest message page from the unified archive (HEL-879 CG-011 seam:
proactive rows are read exactly as the text inbox reads them)."""
response = await self._client.get("/api/messages", params={"limit": limit})
response.raise_for_status()
messages = response.json().get("messages")
if not isinstance(messages, list):
raise ChatApiConnectionError("messages response malformed")
return messages
async def send_turn(
self,
text: str,
+9
View File
@@ -13,6 +13,7 @@ never does. Verified against livekit-agents 1.8.8 source on
from __future__ import annotations
import contextlib
import time
from collections.abc import Callable
from typing import Any
@@ -75,6 +76,12 @@ class ChatApiLLMStream(LLMStream):
self.completed = False
def _emit(self, content: str) -> None:
# HEL-879 seam: raw deltas also feed HER incremental subtitles
# (assistant_interim) — same stream, no second channel, and failures
# in the seam callback must never break the spoken turn.
if self._llm.on_assistant_delta is not None:
with contextlib.suppress(Exception):
self._llm.on_assistant_delta(content)
self._event_ch.send_nowait(
ChatChunk(id=self.turn_id, delta=ChoiceDelta(role="assistant", content=content))
)
@@ -116,10 +123,12 @@ class CyberGrillLLM(LLM):
*,
client: ChatApiClient | None = None,
on_stream_started: Callable[[ChatApiLLMStream], None] | None = None,
on_assistant_delta: Callable[[str], None] | None = None,
) -> None:
super().__init__()
self.client = client or ChatApiClient(api_base)
self._on_stream_started = on_stream_started
self.on_assistant_delta = on_assistant_delta
@property
def provider(self) -> str:
+80
View File
@@ -0,0 +1,80 @@
"""Minimal backend seams for CG-011 proactive voice and HER incremental reply
subtitles (HEL-879 rework: these are implementation gaps, not things that
"just need a voice/budget decision").
This module is deliberately free of livekit imports (same rule as
chat_api_client) so both seams are exercised offline by the product test
suite; worker.py only wires them into the AgentSession.
Seam A — assistant_interim subtitles: the unified /api/chat SSE stream already
carries her reply deltas before CosyVoice's first audio packet. The worker
publishes the accumulated text as `{"kind": "assistant_interim", ...}` on the
`cg.subtitle` topic so the page can show her answer while TTS is still warming
up. The existing user `interim` kind is untouched.
Seam B — proactive speech (CG-011): rows the server has ALREADY archived with
proactive=1 (the same rows the text inbox shows as reach-outs) can be spoken
once inside an open voice session via session.say(allow_interruptions=True).
No new model call, no second persona, no second receipt channel; disabled by
default (CYBERGRIL_PROACTIVE_VOICE=1 enables it in the wiring card, after the
visual author defines the entrance presentation).
"""
from __future__ import annotations
from collections.abc import Callable
from typing import Any
from .chat_api_client import ChatApiClient
class AssistantInterimPublisher:
"""Accumulates /api/chat deltas into `assistant_interim` subtitle payloads.
One instance per voice session; `reset()` on every new generation so a
later turn never starts with the previous turn's text. Payload text is the
FULL text so far (replace semantics, same as the user interim kind).
"""
def __init__(self, publish: Callable[[dict], None]) -> None:
self._publish = publish
self._text = ""
def reset(self) -> None:
self._text = ""
def feed(self, delta: str) -> dict | None:
"""One SSE delta in; the payload to publish (or None for no-op)."""
if not delta:
return None
self._text += delta
payload = {"kind": "assistant_interim", "role": "assistant",
"text": self._text}
self._publish(payload)
return payload
def pick_proactive(messages: list[dict[str, Any]], *, already_spoken: set[int],
limit: int = 1) -> list[dict[str, Any]]:
"""Pure selection: server-archived proactive rows this voice session may
speak — companion role, sent, proactive, non-empty, not spoken here yet,
newest first, bounded by `limit`. The page keeps its own unread state; the
worker never marks rows read (no second receipt/read channel)."""
candidates = [
m for m in messages
if m.get("proactive") is True and m.get("role") == "companion"
and m.get("status") == "sent"
and (m.get("text") or "").strip()
and m.get("id") not in already_spoken
]
candidates.sort(key=lambda m: m.get("id") or 0, reverse=True)
return candidates[:limit]
async def pending_proactive(client: ChatApiClient, *, already_spoken: set[int],
limit: int = 1,
fetch_limit: int = 20) -> list[dict[str, Any]]:
"""Fetch the newest message page from the unified API and select the
proactive rows the session may speak (see pick_proactive)."""
messages = await client.recent_messages(limit=fetch_limit)
return pick_proactive(messages, already_spoken=already_spoken, limit=limit)
+2 -2
View File
@@ -126,7 +126,7 @@ class VoiceSession:
}
@classmethod
def from_state(cls, data: dict) -> "VoiceSession":
def from_state(cls, data: dict) -> VoiceSession:
return cls(
session_id=str(data["session_id"]), room=str(data["room"]),
identity=str(data.get("identity", "")), created_at=float(data.get("created_at", 0)),
@@ -152,7 +152,7 @@ class _CleanupDebt:
"abandoned": self.abandoned, "eligible_at": self.eligible_at}
@classmethod
def from_state(cls, data: dict) -> "_CleanupDebt":
def from_state(cls, data: dict) -> _CleanupDebt:
return cls(
session=VoiceSession.from_state(data.get("session", {})),
attempts=int(data.get("attempts", 0)),
+43 -15
View File
@@ -35,6 +35,7 @@ from livekit.plugins.silero import VAD
from .llm_chat_api import CyberGrillLLM
from .receipt import ReceiptSender, TurnLedger, should_ack
from .seam import AssistantInterimPublisher, pending_proactive
from .stt_funasr import FunASRSTT
from .tts_cosyvoice import CosyVoiceTTS
@@ -46,6 +47,10 @@ VOICE_STATE = Path(
)
)
WORKER_HEALTH_PORT = int(os.environ.get("CYBERGRIL_WORKER_HEALTH_PORT", "8082"))
# CG-011 语音主动开口(HEL-879 最小接缝):默认关闭,接线卡与视觉作者定好
# 入口呈现并经批准后才置 1。开启后只念服务端已落库 proactive=1 的行。
PROACTIVE_VOICE = os.environ.get("CYBERGRIL_PROACTIVE_VOICE", "") == "1"
PROACTIVE_PER_SESSION = 1
SUBTOPIC = "cg.subtitle"
# 占位指令:真正的人格由统一服务在 /api/chat 服务端组装。适配器忽略
@@ -66,15 +71,27 @@ def prewarm(proc: JobProcess) -> None:
proc.userdata["vad"] = VAD.load()
async def _maybe_open_proactive(session: AgentSession, room) -> None:
"""CG-011 主动开口接缝(本卡不实现,留明确边界,不丢需求)。
async def _maybe_open_proactive(session: AgentSession, room, client=None,
already_spoken: set[int] | None = None) -> list[int]:
"""CG-011 主动开口最小接缝(HEL-879:真实代码路径,默认关闭).
语音里的主动开口必须:仅在已开启的语音会话内、走同一条业务链(只念
服务端已落库、标记 proactive=1 的 companion 行,不新起模型调用)、可被
用户打断、不新造第二条回执通道。具体呈现与节奏由总管/视觉总监在接线
卡定;在此之前保持空操作。
仅在已开启的语音会话内、只念服务端已落库、标记 proactive=1、未在本房间
念过的 companion 行(同一 GET /api/messages 入口,无第二人格/无新模型调用),
`session.say(..., allow_interruptions=True)` 可被用户打断,不新建回执通道
(文字回执规则独立且已存在)。每会话有界(PROACTIVE_PER_SESSION)。
入口呈现与节奏由总管/视觉总监在接线卡定;批准前置 CYBERGRIL_PROACTIVE_VOICE=1。
返回本次念出的消息 id(接线/验收用;未启用返回空)。
"""
return None
if not PROACTIVE_VOICE:
return []
spoken: set[int] = already_spoken if already_spoken is not None else set()
rows = await pending_proactive(client, already_spoken=spoken,
limit=PROACTIVE_PER_SESSION)
spoken_ids: list[int] = []
for row in rows:
await session.say(row["text"], allow_interruptions=True)
spoken_ids.append(row["id"])
return spoken_ids
async def entrypoint(ctx: JobContext) -> None:
@@ -82,12 +99,22 @@ async def entrypoint(ctx: JobContext) -> None:
# agent 说话期间短文本/相似文本视为回声丢弃(同通用 worker 的实测做法)
stt.agent_speaking = False
stt.agent_recent_text = ""
def subtitle(payload: dict) -> None:
data = json.dumps(payload, ensure_ascii=False).encode()
asyncio.get_running_loop().create_task(
ctx.room.local_participant.publish_data(data, topic=SUBTOPIC, reliable=False)
)
ledger = TurnLedger()
interim = AssistantInterimPublisher(subtitle)
def note_stream(stream) -> None:
interim.reset() # a new generation must not inherit the old text
ledger.note_stream(stream, stream.created_at)
llm = CyberGrillLLM(API_BASE, on_stream_started=note_stream)
llm = CyberGrillLLM(API_BASE, on_stream_started=note_stream,
on_assistant_delta=interim.feed)
receipts = ReceiptSender(llm.client)
session = AgentSession(
@@ -101,12 +128,6 @@ async def entrypoint(ctx: JobContext) -> None:
},
)
def subtitle(payload: dict) -> None:
data = json.dumps(payload, ensure_ascii=False).encode()
asyncio.get_running_loop().create_task(
ctx.room.local_participant.publish_data(data, topic=SUBTOPIC, reliable=False)
)
@session.on("user_input_transcribed")
def _on_transcript(ev) -> None:
if ev.transcript.strip():
@@ -175,7 +196,14 @@ async def entrypoint(ctx: JobContext) -> None:
await ctx.connect()
await session.start(room=ctx.room, agent=Agent(instructions=INSTRUCTIONS_PLACEHOLDER))
await _maybe_open_proactive(session, ctx.room)
spoken_proactive: set[int] = set()
try:
spoken = await _maybe_open_proactive(session, ctx.room, client=llm.client,
already_spoken=spoken_proactive)
spoken_proactive.update(spoken)
except Exception as exc: # seam failure never breaks the session start
print(f"[cybergril-worker] proactive seam skipped: {type(exc).__name__}: {exc}",
flush=True)
print(
f"[cybergril-worker] session started (api={API_BASE}, "
f"voice={read_default_voice()}, agent_name={AGENT_NAME})",
+61 -6
View File
@@ -16,6 +16,7 @@ Zero network beyond 127.0.0.1; fake LiveKit/TTS transports throughout.
from __future__ import annotations
import asyncio
import contextlib
import json
import socket
import ssl
@@ -40,9 +41,12 @@ from cybergril.think.router import build_router # noqa: E402
from cybergril.think.scenes import Tier # noqa: E402
from cybergril.voice import livekit_wire # noqa: E402
from cybergril.voice.receipt import TurnLedger # noqa: E402
from cybergril.voice.seam import ( # noqa: E402
AssistantInterimPublisher,
pick_proactive,
)
from cybergril.voice.session import VoiceConfig, VoiceSessionService # noqa: E402
# ---------------------------------------------------------------- TurnLedger
def _stream(turn_id: str) -> SimpleNamespace:
@@ -103,7 +107,9 @@ def _proto_field1(data: bytes) -> str:
"""Decode varint-prefixed field 1 (room) from a livekit proto body."""
if not data or (data[0] >> 3) != 1 or (data[0] & 7) != 2:
return ""
length, index, shift, value = 0, 1, 0, 0
length = 0
index = 1
shift = 0
while True:
byte = data[index]
length |= (byte & 0x7F) << shift
@@ -253,7 +259,7 @@ async def test_cleanup_is_bounded_then_recorded_abandoned(tmp_path):
try:
session = await service.open_session(epoch=1)
now[0] += service.config.session_ttl_seconds + 1
with pytest.raises(Exception):
with pytest.raises(livekit_wire.RoomDeleteError):
await service.end_session(session.session_id)
for _ in range(200):
debt = service.cleanup_debt(session.session_id)
@@ -381,6 +387,57 @@ def test_router_delete_failure_is_503_and_keeps_room_owned():
assert again.status_code == 404
# ------------------------------------------------- CG-011 seam (HEL-879)
def test_assistant_interim_publisher_accumulates_and_resets():
published: list[dict] = []
publisher = AssistantInterimPublisher(published.append)
assert publisher.feed("") is None
assert publisher.feed("她在") is not None
publisher.feed("打字中")
assert published[-1] == {"kind": "assistant_interim", "role": "assistant",
"text": "她在打字中"}
publisher.reset()
publisher.feed("新的一轮")
assert published[-1]["text"] == "新的一轮", "no inheritance across turns"
def test_proactive_selection_is_archived_newest_bounded():
messages = [
{"id": 1, "role": "user", "status": "sent", "proactive": False, "text": "hi"},
{"id": 2, "role": "companion", "status": "sent", "proactive": True, "text": "旧主动"},
{"id": 3, "role": "companion", "status": "sent", "proactive": True, "text": "新主动"},
{"id": 4, "role": "companion", "status": "queued", "proactive": True, "text": "未落库"},
{"id": 5, "role": "companion", "status": "sent", "proactive": True, "text": " "},
{"id": 6, "role": "companion", "status": "sent", "proactive": False, "text": "普通回复"},
]
picked = pick_proactive(messages, already_spoken=set(), limit=1)
assert [m["id"] for m in picked] == [3], "newest eligible proactive row only"
again = pick_proactive(messages, already_spoken={3}, limit=1)
assert [m["id"] for m in again] == [2]
assert pick_proactive(messages, already_spoken={2, 3}, limit=1) == []
@pytest.mark.asyncio
async def test_pending_proactive_reads_unified_messages_page():
from cybergril.voice.chat_api_client import ChatApiClient
def handler(request: httpx.Request) -> httpx.Response:
assert request.url.path == "/api/messages"
assert request.url.params["limit"] == "20"
return httpx.Response(200, json={"messages": [
{"id": 9, "role": "companion", "status": "sent",
"proactive": True, "text": "落库的主动留言"}], "epoch": 1})
client = ChatApiClient("http://api.test", transport=httpx.MockTransport(handler))
try:
rows = await client.recent_messages()
picked = pick_proactive(rows, already_spoken=set(), limit=1)
assert picked[0]["id"] == 9
finally:
await client.aclose()
# ---------------------------------------------------- dual-listener lifecycle
def _free_port() -> int:
@@ -461,10 +518,8 @@ async def test_dual_listeners_share_one_lifecycle_and_close_in_order(
assert len(set(store_inits)) == 1, "the app must be initialized exactly once"
finally:
serve_task.cancel()
try:
with contextlib.suppress(asyncio.CancelledError):
await serve_task
except asyncio.CancelledError:
pass
await client.aclose()
# Exit boundary: both listeners fully shut down BEFORE the store closes,
+4 -2
View File
@@ -246,8 +246,10 @@ export class VoiceController {
await Promise.all([closing, ending]);
}
// Kept in this browser (not only in memory), so leaving the conversation or reloading does not forget them. Until
// one gets through, the server side still ends on its own: the worker's job ends when the page's participant is
// gone from the room, and the session registry expires (runbook-hel877-voice §3.4/§3.5).
// one gets through, the server keeps its own bounded cleanup ledger for the rooms it opened (retrying its delete,
// also across restarts, up to a bound), and the worker's job ends when the page's participant is gone from the
// room; an unanswered DELETE is NOT proof the room is gone — 404 means settled, anything else keeps the debt here
// (runbook-hel877-voice §3.4/§3.5, HEL-879: the old "the server side still ends on its own" was an unproven claim).
private owe(session: string, on: boolean) {
const list = new Set(owedSessions());
if (on) list.add(session); else list.delete(session);