7.9 KiB
7.9 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 ..
# 启动（独立数据目录；新体验入口必须用全新空库，不导入演示/测试档案）
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）独立 venv（HEL-857 已建，hel857-venv）；产品进程需能 import 该包（部署卡决定合入产品 venv 或 venv 合并方案，不 fork 上游）。 cp config/semantic.example.yaml config/semantic.yaml，由总管按批准值填embed_cap（>0 才会放行任何真实嵌入）；账本指向唯一权威embed_ledger.sqlite3续账。CYBERGRIL_SEMANTIC=mem0重启。任何未批预算的嵌入调用都会 fail-closed 拒绝（semantic_embed_budget_not_approved/exhausted），不会碰 498/500 冻结余额。
5. 体验链路清单（按用户实际体验顺序；只有实际能力标已接）
| # | 步骤 | 状态 | 说明 |
|---|---|---|---|
| 1 | 打开入口 → 无档案正常创建（名字/生日/时辰/关系，AM-002/003/CG-012） | 已接 | /api/companion；出生底色四柱+解释空间（UX-004/CG-013–015），创建时生成自主诠释与初始习惯 |
| 2 | 与她文字对话（真实传输接口，SSE 流式） | 已接（真实模型网关 .11:8731） | 每轮供给底色/诠释/成长/情绪词/关系提示；近 20 轮+预算内历史 |
| 3 | 原话与记忆写入 → 回忆页 | 已接 | R3 主档案+gist；回忆页仅显示过门公开条目 |
| 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. 真实整体冒烟预算申请（交总管核定；与用户日常使用预算分开）
- 一次性冒烟（隔离空库、非用户档案）：创建+诠释 1 次、对话 6–8 轮（含主动消息 1–2 次措辞）、生活槽 4 次、分享判定/成长/ gist 若干（约 6 次）、合计约 20–30 次真实请求（.11:8731 网关，HEL-857 的 60 次授权不含本产品环境；需总管明确本轮来源与上限）。
- 语义层激活（如批准）：每公开轮 1 次提取（LLM）+ 每条 1 嵌入 + 每次查询 1 嵌入；首周估计 约 100–200 条嵌入——当前权威账 498/500 冻结，需按 HEL-869 §6.1 由白栖知决定提高上限或另批独立账。
- 日常使用预算模型（参考，供核定）：轻使用约 20–40 请求/天 + 15–30 嵌入/天。
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 存在。端到端语音可用性未验证，不以监听存在冒充服务可用。