Files
CyberGril/docs/runbook-hel870.md
T
zonggongandmultica-agent 152479b350 HEL-894 rework: a cancelled close owns nothing it did not start — aclose cancellation is now a two-phase ownership protocol - the manager's independent pinned-SDK review of ceb0f35 reproduced two combo holes in the HEL-889 close path: (1) cancelling aclose AFTER backend.aclose began made the shielded finish keep running unowned in the background while the outer except already released the lock and cleared closing — the layer was reported reusable (closing=false/closed=false/client usable), a new tick claimed a batch onto real HTTP, then the orphaned finish closed Qdrant under it (SDK-only branch: batch failed on 'QdrantLocal instance is closed' with row_done=0/llm_used=1; with the caller closing the store afterwards the late worker died on ProgrammingError 'Cannot operate on a closed database' and the reopened batch sat pending), and (2) cancelling a SECOND aclose that was still WAITING for the close lock ran the same except and cleared the FIRST closer's flag (first close still pending but signal=false, a new batch ran to done while the original worker was still on the wire). SemanticMemory.aclose now states the revocation boundary explicitly: the DRAIN phase (nothing closed yet) stays revocable — a cancelled caller leaves everything open, resets the closing signal and the layer remains usable (HEL-889 semantics preserved); the FINISH phase (backend.aclose begun) is irreversible — a cancelled caller keeps the closing markers (a half-closed layer is never reported usable, ticks keep refusing), keeps the lock, and waits — repeated cancels only re-shield — for the layer-owned close task it started (self._close_task, created exactly once with asyncio.create_task and stored on the layer, never dropped to the background) to land before propagating CancelledError, so resources close exactly once; _finish_close also joins this layer's OWN executor via asyncio.to_thread so a cancelled caller can never block the event loop on a synchronous shutdown wait (caller-injected executors stay caller-owned), and signal reset is ownership-gated by owns_close: only the call that actually acquired the lock and set the signal may clear it, and only while no close task exists — a lock waiter cancelled on acquisition touches nothing; module docstring, aclose docstring and the app lifespan comment state the same contract; verification: 299 python tests pass on 3.11.16 venv + requirements.lock offline (5 new tests/test_rework_hel894.py cases, all barrier-driven real product paths: finish-phase cancel keeps ownership and refuses new work with zero sends and zero budget / repeated cancels during finish land the close exactly once / a same-phase second aclose waits then returns idempotently while a third cancelled lock-waiter touches nothing / waiter-cancel + owner draining + refused new tick + original worker completing combo / drain-phase cancel still re-arms for reuse), ruff clean (src/tests/tools), no frontend changes (frontend checks not re-run, stated honestly); pinned mem0 2.2.1 on the deterministic boundary (512-dim stand-in before TextEmbedding construction, loopback-only): new tools/verify_close_ownership_hel894.py 16/16 reruns the manager's two negatives in the same shape with assertions restated for the new protocol (F1 SDK-only: after the cancel closing=true/closed=false/client usable and the cancelled caller does not return before its close lands; the new tick is refused with zero gateway arrivals, batch queued/owner NULL/attempts 0 and llm_used=0; after the gate the close lands exactly once with live_workers=0 and the reopened batch is intact queued/row_done=0/llm_used=0 — before the fix the same run gave closing=false, a claimed batch, QdrantLocal instance is closed, failed/pending with row_done=0/llm_used=1; F2 + store-close branch: same shape and no late error — before: ProgrammingError; W waiter cancel: closing stays set, the new batch stays queued, the original worker completes done/row_done=1 after release and the owner's close then lands once); the manager's review_hel889_cancel.py re-run VERBATIM on the pristine ceb0f35 first reproduced both defects exactly (docs/rework/hel894/before-ceb0f35.json matches the manager's independent JSON), and on the fixed tree stops honestly at its own premise assert server.arrived — 'a finish-phase-cancelled layer still starts new real HTTP' is structurally gone because tick refuses while closing is held (verbatim-after-fix.log; original negative and baseline kept); regressions all green: verify_shutdown_queued_hel889.py 12/12 (queued cancel, timeout drain, between-rows resume, drain-cancel re-arm, concurrent close all preserved), verify_inflight_lifecycle_hel886.py 6/6, verify_semantic_recovery_hel885.py 7/7, verify_mem0_real_hel874.py 12/12, check_release_offline_hel882.py R1-R7 15/15, both manager review_hel882_{partial,extra}.py scripts re-run verbatim pass (extra's uv rc=2 is its own expected negative), HEL-889 same-shape rerun review_hel886_edges_rerun_hel889.py passes; crash semantics unchanged and still honest (unknown wire outcomes billed, proof-gated retries, strict-once not claimed); runbook §4 gains the HEL-894 cancellation-ownership paragraph, docs/requirements/handoff-HEL-894.json written, dual-target requirement checks 4/4 (origin/main and origin/agent/agent/de8874a3803b, with and without handoff); zero real LLM, zero real embeddings, zero non-loopback outbound, authoritative ledgers and freezes untouched, not deployed, PR not merged, no visual changes
Co-authored-by: multica-agent <github@multica.ai>
2026-10-27 01:43:54 +08:00

13 KiB
Raw Blame History

HEL-870 总装运行手册(统一候选实例)

分支 hel-870-assembly(自 origin/hel-857-mem0-spike @ 5671946 建立,包含 v1.11 治理、R1–R3 产品代码与原作者前端)。本手册覆盖:启动、锁定依赖、脱敏配置、健康版本、独立数据目录、停用与保留数据回退、体验链路清单、真实预算申请、R1–R7 承接。本候选未获合并/部署授权;不触 8300/8310/8320/8340/8350 与共享语音/口型服务。

1. 启动(统一实例)

# Python 3.11 + 锁定依赖(requirements.lock,uv 离线缓存可装)
uv venv --python 3.11 .venv311
uv pip install --python .venv311/bin/python -r requirements.lock
# 前端(原作者界面,仅机械构建,未改视觉)
cd web && npm ci && npm run build && cd ..

# 启动(独立数据目录;新体验入口必须用全新空库,不导入演示/测试档案)
# 注意 PYTHONPATH=src:requirements.lock 只装依赖,产品代码经 PYTHONPATH
# 进入进程(HEL-882;与 deploy/cybergril-hel874-8360.service.example 一致)
mkdir -p /opt/cybergril-hel870-data
CYBERGRIL_DB=/opt/cybergril-hel870-data/companion.db \
CYBERGRIL_R2_ENABLED=1 \
CYBERGRIL_SEMANTIC=stub \
PYTHONPATH=src .venv311/bin/python -m uvicorn cybergril.api.app:create_app \
  --factory --host 0.0.0.0 --port 8360
  • CYBERGRIL_SEMANTIC=off(默认)关闭语义层,检索回落 R3 词面 FTS;stub 为编排自测后端;mem0 为真实固定源(见 §4)。
  • 部署建议沿用独立 review 流程:独立 systemd 单元 + 独立端口 + 独立数据目录,由后续审核卡执行,不动现有服务。

2. 健康版本与验证

GET /api/health → version: "R4-assembly";backend 报告 mood/reach_out/semantic 接线;capabilities.proactive=true(生活循环开启时);capabilities.semantic_memory 为后端名或 null。本机冒烟证据:web 根 200,health 全绿,生活循环 waiting_for_companion(见交付评论)。

3. 停用与保留数据回退

  • 停语义层:CYBERGRIL_SEMANTIC=off 重启即可;sem_batch/sem_covered 表保留,重开续跑不重复发送。
  • 停主动联系:CYBERGRIL_R2_ENABLED=0(与生活循环同开关,符合已批准范围)。
  • 回退整个实例:停服务 → 数据目录 /opt/cybergril-hel870-data/ 原样保留(含全部聊天/记忆/生活/情绪/关系状态)→ 切回上一 release。R4 迁移全部为增量新表(r4.sql),旧代码可安全打开同一数据库(新增列/表被忽略)。

4. 真实 Mem0 通道(需预算批准后启用)

  1. 固定安装复用:mem0ai 2.2.1(源码提交 2c81af3bbe27d9bccb09c772d583df9e9be72ee5)。 HEL-882 准确缺项:已有固定 venv(hel857-venv)是 Python 3.10.12,产品 进程是 3.11.16,site-packages 不能混用,本机缓存亦无 3.11 版 mem0 栈 wheel。 发布卡按 deploy/hel874-release.md §4 用 deploy/mem0-stack.lock 落 wheel 后离线并入同一发布 venv(不 fork 上游,本卡零下载)。
  2. cp config/semantic.example.yaml config/semantic.yaml,由总管按批准值填 embed_cap/llm_cap(B 部分累计)、embed_daily/llm_daily(C 部分日顶) (>0 才会放行任何真实嵌入/内部提取 LLM);账本指向唯一权威 embed_ledger.sqlite3 续账(llm_ops 同库新表,独立 cap),authority 冻结前缀块保留——新空文件绕过 498/500 冻结会被直接拒绝。
  3. CYBERGRIL_SEMANTIC=mem0 重启。任何未批预算的嵌入或内部 LLM 调用都 fail-closed 拒绝(semantic_embed/llm_budget_not_approved/exhausted/daily_exhausted), 不会碰 498/500 冻结余额;SDK 内部提取 LLM 同时过统一请求闸(semantic 类别 + 日 token 池,发送前预占)。

HEL-874/882 实测接线事实(docs/rework/hel874/,固定安装本体验证): mem0 2.2.1 拒绝同路径第二个 QdrantClient(旧适配层构造即死,已改走 SDK 自带 client);search 必须带 user_id 过滤且 top_k 才是有效形参(limit 被静默忽略); 每次 search 恰好 1 条嵌入记账(旧外层+包装双记已移除);SDK 内部提取 LLM 已过 独立闸并计数;并发预占不越 cap;embed_cap=0/llm_cap=0 时出站 LLM 为 0。 单行 add 实测开销:1 次提取 LLM + 2–3 条嵌入(查询/提取批/实体 upsert)。 HEL-882 追加:SDK 隐藏重试禁用(max_retries=0)与被应答失败照实入账;预算 拒绝重排队不丢行;stub→mem0 覆盖按后端区分;嵌入证据口径勘正见 docs/rework/hel874/erratum-hel882.json(旧 runs 有真实本地嵌入,下限 12 条)。

HEL-886 处理中生命周期与收尾语义(docs/rework/hel886/,固定安装本体验证):

  • 取消/租约不再把「仍在运行的 worker」当死亡。批次的最终状态由 worker 线程 自己写(asyncio.to_thread 中的真实调用不可中断,取消只取消等待协程); 活跃批次登记在进程内注册表,租约到期但 worker 仍活跃时不回收、并发 tick 不重发同一行;关闭时先排空仍在运行的 worker 再关向量库 client 与 SQLite。
  • 真死进程(崩溃/重启后租约过期)的恢复语义如实保守:旧尝试的出站结果未知 ——其账本预占保持计费(HEL-885 口径),重试只发没有完成证明的行(向量锚点 ∪ sem_row_done)。不宣称远端无幂等支持下任意崩溃的严格一次。
  • 已全完成的批次收尾不再要新余额:所有行都有完成证明时,重启后零新 HTTP/零新嵌入/cap 不变即 done 且 entry_ids 完整;仍有缺行时维持原硬闸拒绝, 不为收尾加 cap 或退款未知预占。

HEL-889 关闭所有权与排队取消(docs/rework/hel889/,固定安装本体验证):

  • aclose 绝不在仍可能写入的 worker 下关资源:批 worker 跑在本层专用执行器, 关闭先置信号(拒新领、只在行边界前停、未启动项按 concurrent.futures CANCELLED 权威取消——从未运行即零发送,可安全回队),再等所有活跃 worker 真实退出才关向量库 client 与执行器;drain_timeout 只界定礼貌阶段(超时后 如实告警并继续等),网关客户端超时(gateway_timeout,默认 60 秒)保证 等待有界。被取消的关闭什么都不关;并发关闭串行化且幂等。
  • 排队阶段取消不再永久假活跃:取消等待协程时以 future.cancelled() 区分 「从未运行」(立即释放注册项、批次回 queued、attempts 复原,进程内即可 recover+tick 完成,无需重启)与「已开始」(维持单发语义,worker 线程自己 写终态)。真崩溃仍保守留账,不宣称严格一次。

HEL-894 关闭取消的所有权(docs/rework/hel894/,固定安装本体验证):

  • aclose 的取消语义分两阶段:排空阶段可撤销(尚未关任何资源——取消 什么都不关、closing 复位、层次可续用,与 HEL-889 口径一致);提交阶段 不可撤销(backend.aclose() 已开始——被取消的调用方不清 closing、不放 行 tick(半关闭绝不宣称可用)、不释放锁,等待自己启动的层持有关闭任务 (_close_task 创建恰一次、从不丢后台、重复取消只重新 shield)落成后才 传播取消,资源恰关一次;本层自有执行器 shutdown 走 to_thread,不用同步 join 阻塞事件循环)。只有真正取得锁并置位信号的调用才可复位信号:等锁 者被取消不改持锁关闭者的任何状态(总管复现过等锁者清掉第一关闭的 closing、新批在原 worker 未放行时跑完)。app lifespan 注释同步该口径; 真崩溃语义不变(保守留账、只发无证明行、不宣称严格一次)。

5. 体验链路清单(按用户实际体验顺序;只有实际能力标已接)

# 步骤 状态 说明
1 打开入口 → 无档案正常创建(名字/生日/时辰/关系,AM-002/003/CG-012) 已接 /api/companion;出生底色四柱+解释空间(UX-004/CG-013–015),创建时生成自主诠释与初始习惯
2 与她文字对话(真实传输接口,SSE 流式) 已接(真实模型网关 .11:8731) 每轮供给底色/诠释/成长/情绪词/关系提示;近 20 轮+预算内历史
3 原话与记忆写入 → 回忆页 已接 R3 主档案+gist;回忆页仅显示过门公开条目。HEL-874:记忆回读原话优先——FTS 与语义两条检索通道都把命中原话(含角色与时间)有界注入模型输入,不再只给 120 字摘要(tests/test_readback_hel874.py 用真实 provider 输入捕获证明)
4 她的生活(后台 4 槽/天,活动延续/打断/恢复) 已接(同 2 的真实网关) 日子页只显示她讲过的(AM-001);未分享内容服务器侧裁剪
5 情绪与关系真实接线 已接 事件推动情绪(方程持久化、重启恢复);对话累计亲密/信任;模型只见一个词与行为指令
6 主动联系(网页内留言,R4 批准参数) 已接(真实网关生成措辞) 间隔≥6h、8–23 点、显著度≥0.6、唤醒≥0.5、亲密≥0.4;有真实已公开依据;关页积累、回来可见;缺席不武器化;不重复
7 关闭重开 → 相同状态与未读主动消息 已接 epoch 同步+全量消息重放;主动消息带「她主动说的」标记
8 语义记忆检索(Mem0) 已接线、待预算激活 预分组+锚点+fail-closed 门已进产品路径;mem0 模式需批准嵌入预算(§4);未激活时回落词面 FTS
9 语音连续对话(R5) 未接 /opt/voice-agent 底座与 8090/8081 端口在 .12 存活(本卡只读核实监听);端到端可用性待 R5 卡验证
10 天气/城市(R6) 未接 界面如实显示「天气尚未接通」;open-meteo 出网待测
11 素材包/真实视频/口型(CG-029/030、R5/R7) 未接 人物仍为参考静帧;不伪装已接入
12 完整备份恢复(CG-009/R6) 未接 数据目录可整体复制(SQLite WAL 单文件+语义目录);产品化导出/校验/恢复在 R6 卡

没有任何按钮或字幕假装存在未接能力;未接项在界面保持既有诚实文案。

6. 真实整体检查预算(有确定上限的执行表)

以 docs/budget-plan-hel874.md 为准(A 一次性团队检查 55 请求/0 嵌入; B 首周语义激活 ≤60 提取 LLM/≤180 嵌入;C 用户日常逐项日顶)。本节原 「20–30 次请求 / 100–200 条嵌入」仅为历史估算,不构成已批准额度; 三部分独立账本与授权来源见该表;本卡零真实调用,冻结余额不挪用。

7. R1–R7 承接与立即可派工范围

  • 前端原作者接线(视觉总监):界面已支持主动消息标记(proactive 契约已通,web/src/adapters/real.ts 仅机械透传);主动消息在打开页面期间的呈现节奏、未读提示的视觉表达交视觉总监按已认可语言设计;总工未改任何视觉。
  • 独立审核发布(审核卡):按已批准独立测试发布流程部署本候选(建议端口 8360、独立数据目录),验证 §5 清单 1–7 + 隐私负例 + 重启恢复;不动现有服务。
  • R5 语音:底座 /opt/voice-agent 在 .12 存活(8090/8081 监听核实,端到端未验证);接 CyberGril 专属 worker 需先核定音色(D1)与 HTTPS 路径。
  • R6 天气/素材/备份:open-meteo 出网连通性测试;素材包 manifest 导入校验;备份导出/恢复产品化(身份指纹比对已具备 Persona.fingerprint)。
  • R7 视觉观察:默认关;需白栖知明确授权 + 4080 使用决策(D4),本卡未触碰。
  • 语义层真实激活与 HEL-835 解闸均待预算/授权,本卡未动三账与冻结余额。

8. 环境事实(如实记录)

  • 本运行环境仅有 Python 3.10(产品需 ≥3.11);测试用 uv 离线缓存的 3.11.16 venv + requirements.lock 完成(无新增下载)。系统 python3.10 下与 asyncio.timeout 相关的既有用例会失败,属环境版本差异,非本卡回归。
  • .11:8731 网关从本运行环境可达(health 探活 ok,未发对话请求)。
  • 服务器 .12 只读核实(未触任何服务):cybergril-api(8310)/hel822(8320)/hel829(8340)/hel835(8350, guarded)/S1 web 均运行中;8090(音色管理)、8081(历史口型试验件)监听存在;/opt/voice-agent 存在。端到端语音可用性未验证,不以监听存在冒充服务可用。
  • HEL-874/882 真实 SDK 验证环境:hel857-venv(Python 3.10.12 + mem0ai 2.2.1 固定安装)。LLM 走 127.0.0.1 确定性假网关,账本全在临时目录并在清理前把逐笔账落进证据 JSON,权威三账零写入。嵌入边界:e978e87 版读取已有缓存做过真实本地嵌入(勘正与下限见 docs/rework/hel874/erratum-hel882.json);HEL-882 起在 TextEmbedding 构造前替换确定性 512 维替身 + socket 禁非回环,零真实嵌入零下载。证据 docs/rework/hel874/。
  • HEL-882 预算硬闸环境:固定 mem0 栈无法装入产品 3.11 venv(缓存无 wheel),所有 mem0 侧行为以假 SDK 镜像测试 + 3.10 固定安装上的确定性替身实跑验证;A/C 请求闸与 token 预占在产品 3.11 venv 全量 pytest 验证。