10 KiB
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 通道（需预算批准后启用）
- 固定安装复用：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 上游，本卡零下载）。 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 冻结会被直接拒绝。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 条）。
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 验证。