Files
CyberGril/docs/requirements/sources/integration-plan-v1.md
T
白栖知andmultica-agent 003d8c2cae HEL-822: land HEL-821 A1+A2 source onto PR#4 base (db571ba)
- 13 modified / 8 added / 1 deleted per CHANGES.json (author package 76bc120b)
- docs/requirements v1.10 + prototypes/hel-799 + PROVENANCE from bundle, verified byte-identical to 63799f0
- AGENTS.md + scripts/check_requirements.py restored from governance commit 63799f0

Co-authored-by: multica-agent <github@multica.ai>
2026-10-24 06:10:53 +08:00

23 KiB
Raw Blame History

CyberGril 真实服务核查与功能接入批次方案(HEL-778 · v1)

依据:main 合并提交 498429399812a0776dadd4b56662d31b455a9ea5(第二父提交为已审核前端 6c3b09e6936881fb3e0681ce40bf6069d2c250ac,已核对无误);HEL-738 结构方案(本卡附件,不重复其内容,冲突处以本文为准);《整套设计验收与施工裁定-v1》;需求确认记录 v1.6。 性质:只读核查 + 实施方案。本轮未写产品代码、未改任何服务、未访问 4080、未输出任何凭据。所有尚未实施的接口均标【拟议】。 核查手段:main 源码全量阅读;Python 测试复跑(78 passed);对 .11 LLM 网关只读 GET;经既有授权 SSH 对 .12 做 systemctl / ss / docker / 进程 / 本机 HTTP 只读探测;对 8300/8090 只读 HTTP 探测。


0. 一页结论

  1. 第一批该干什么已经清楚了:把 B1 与 S2 合并为一批(本方案称 R1),让白栖知用普通入口在服务器上创建唯一真实档案,并与 .11 的真实模型流式文字对话。服务器是唯一事实源,重开/换设备都是同一位她。不动语音、不做生活循环、不做口型。
  2. 比 HEL-738 写方案时多出一个重大事实:.12 上已有一套端到端验证过的全双工语音底座 /opt/voice-agent(FunASR 流式 ASR + CosyVoice3 流式 TTS + LiveKit + silero VAD 打断,2026-10-16 实测可用,含可用 HTTPS 自签通话页 8090)。语音批次(R5)从"从零接线"变成"复用已验证底座换上她的人格与记忆",风险大幅下降。
  3. LLM 网关 .11:8731 实测可用:OpenAI 兼容,无需鉴权,单模型 halogen-qwen3.8-flash-next(262K 上下文)。现有 providers/llm/openai_compat.py + think/wiring.py 只改 config/models.yaml 即可接上,代码零改动。
  4. S1 前端把接缝留对了:ChatAdapter 接口 + TurnGate(turn_id/epoch/abort 三重门槛)就是为换真实传输准备的;真实模式只需要新增一个适配器和普通入口路由,演示模式代码路径完全不动。

1. 核查证据表

1.1 前端(S1,6c3b09e,已合并 main)

事实 证据 结论
聊天传输是可替换接口:send(text, turnId, epoch, signal, emit, fail?) web/src/adapters/demo.ts:2-3 【已有可复用】R1 新增 RealChatAdapter 实现同接口即可,ChatPanel.tsx:26 只改 useRef(new DemoAdapter()) 一处注入
旧轮隔离门槛:事件必须同时匹配 turn_id + epoch 且未 abort,非协作适配器的迟到事件同样被拒 web/src/adapters/demo.ts:25-33(TurnGate),ChatPanel.tsx:57 每事件过 gate.accepts 【已有可复用】真实 SSE 流直接受益,无需重写
服务端事件形状 chat.delta / chat.final(带 epoch + turn_id) web/src/domain/model.ts:61-74 【已有可复用】R1 服务端 SSE 事件与它一字不差,前端模型层零改动
隐私 fail-closed 裁剪:未分享事件及其关联回忆、消息全部过滤,未知引用默认拒绝 web/src/domain/privacy.ts:4-11 【已有可复用·仅前端】按裁定,真实后端必须在响应前裁剪(R2 起服务端强制),前端过滤不构成权限控制
创建守卫:名字 1–20 字无尖括号/控制符、日期合法且满 18 岁、关系必选不预选 web/src/domain/model.ts:76-86(validateCreation),CreationWizard.tsx:43 关系无预选 【已有可复用】R1 服务端必须同规则复验(不信任客户端)
演示档案存 localStorage key cybergril.demo.v1,导入走严格 schema 重建 web/src/adapters/storage.ts:2,6-32 【已有可复用】真实模式使用独立数据源(服务器),key 不冲突
普通入口(非 ?demo=1)显示"服务尚未接通"卡 + 演示入口链接,不读档案 web/src/app/App.tsx:13,99 【需改】R1 在此分岔:可达且有档案→主界面;可达无档案→创建向导;不可达→维持现状卡
S1 全程零网络请求、不碰 getUserMedia docs/frontend/IMPLEMENTATION.md + 源码通读(无 fetch/XHR/WS) 【已验证】演示隔离的基线成立
演示模式全局开关 ?demo=1,演示剧本与页面分离 App.tsx:13、web/src/demo/fixtures.ts 【已有可复用】真实模式上线后演示路径原样保留

1.2 Python 核心(自 1e9b08a 起未变:git diff 1e9b08a..main -- src/ config/ tests/ 为空;78 测试通过)

模块 关键接口(证据) 结论
八字编译 pillars_from_lunar()、compile_pillars()→Derived、Derived.traits_text() 白话倾向(core/bazi.py:271,310,159) 【已有可复用】R1 创建时服务端排盘 + 底色白话直接产出
LLM 适配 OpenAICompatLLM.stream()(SSE 流式)、health()(GET /models 探活)(providers/llm/openai_compat.py:71-76,78-134) 【已有可复用】对 .11:8731 协议完全匹配
模型路由 build_llm() / build_router_from_config():配置→provider→router 唯一接缝(think/wiring.py:30,100;config/models.yaml) 【已有可复用】换模型只改 yaml,业务代码不碰
记忆存储 Store:add_episodic/decay_accessibility/reinforce/search_fts(FTS5 已建,向量表在 schema.sql:183 注释)(memory/store.py) 表结构可用;R1 需增量补一张 chat_message 表(schema 无聊天记录表);检索/整合【需补实现】(R3)
关系账本 dyad/ledger.py:Dyad.apply/tick_daily_regression/behavior_hints 【已有可复用】R4 起用
情绪/投影 core/mood.py 全套衰减方程;core/projection.py Projector 【已有可复用】R2/R4 起用
服务器 api/ 不存在(src/cybergril/ 下无 api 目录) 【需补实现】R1 新建
tick/生活/reach_out 循环、检索/整合、表达管道、天气、备份 无任何代码(HEL-738 §1.2 结论仍成立,本轮复核确认) 【需补实现】R2 起分批

1.3 授权服务实测结果(本轮只读探测)

服务 地址/端口 实测结果 证据
LLM 网关(halogen) http://192.168.200.11:8731 GET /v1/models → 200,无鉴权头也 200;单模型 halogen-qwen3.8-flash-next,上下文 262144,max_tokens 上限 65536/默认 32768 本轮 curl 实测;且 /opt/voice-agent/README.md 记载语音栈已于 2026-10-16 用它端到端验证(OpenAI 兼容)
ASR(FunASR 2pass 流式) .12 :10095(docker voice-funasr,funasr-runtime-sdk-online-cpu-0.1.13,0.0.0.0) WS 协议,流式 ~600ms + 离线纠错;已知问题:长句偶发被切成两次 final(两次触发回复),可切 mode=online 或调 VAD 尾点 docker ps、ss -tlnp、/opt/voice-agent/agent/stt_funasr.py:29、README"已知限制"
TTS(CosyVoice3 流式) .12 :9880(/opt/voice-agent/cosyvoice/server.py,GPU ~5.6GB 显存) FastAPI:/health + POST /tts → 24k int16 PCM 字节流;首包 1.7–2.5s(官方 150ms 需 vLLM 后端,未开);voices.json 零样本音色注册 + 热加载 + 网页音色管理 curl /openapi.json → ['/health','/tts']、tts_cosyvoice.py:22、README
LiveKit SFU .12 :7880/:7881(docker voice-livekit,host 网络) 运行中;配套 livekit-agents 1.8.8 worker(.12:8081)内置 silero VAD,打断判定 min_silence 0.55s 已含在链路 docker ps、ps(agent.py start)、README
HTTPS 通话页(先例) https://192.168.200.12:8090(/opt/voice-agent/web) 自签证书,TLS 200;浏览器"高级→继续"后麦克风可用;token 由服务端签发,密钥不进浏览器 ss、curl -k 实测、README"浏览器通话"
S1 演示站 .12 :8300(systemd cybergril-s1-web.service,/opt/cybergril-s1/current 指向 6c3b09e 构建,releases/current 结构) 200 正常;静态 http.server;回滚=切符号链接 systemctl cat、curl 实测。本轮未做任何变更
口型试验(遗产) .12 :8010(systemd cybergril-musetalk-test.service:MuseTalk + WebRTC + cosyvoice TTS) 运行中,为口型独立线的既有验证件 systemctl list-units。按边界不动
旧原型页 .12 :18080/:18081(含 HEL-711 卧室分层校准等) 存在且运行 按边界保留不动
摄像头/视觉 4080 未访问 按本轮边界继续禁止访问,仅列 R7 独立决策 —

1.4 普通入口如何进入真实模式;演示如何隔离;演示档案不会被当成真实伴侣

  • 普通入口(R1 后):非 ?demo=1 打开 → 前端 GET /api/health:可达 → 按 GET /api/companion 结果分岔(404→创建向导;200→主界面+服务器历史消息);不可达 → 维持现在的"服务尚未接通"卡。真实档案创建只写服务器 SQLite,浏览器不再持有权威状态。
  • 演示隔离:?demo=1 路径、localStorage key cybergril.demo.v1、演示剧本、演示角标全部原样保留;演示模式继续零网络请求。
  • 不自动上传:真实模式代码从不读取 cybergril.demo.v1,也不提供"演示档案转真实"入口;R1 验收含 Network 面板核验。浏览器里的演示数据与服务器上的她是两个世界,互不可见。

2. 第一批施工卡正文(R1:真实档案 + 真实文字对话,可直接交施工员)

即 HEL-738 切片 B1+S2 的合并最小版。目标一句话:白栖知用普通入口创建唯一真实档案,和真实模型流式文字聊天,关掉浏览器再开(换设备也一样)还是同一位她。

2.1 做(范围)

A. 后端 src/cybergril/api/(拟议,FastAPI + uvicorn,单进程 systemd 服务)

端点【拟议】 行为 错误语义
GET /api/health {ok, version, epoch, companion_created, llm:{ok, model}};llm 探活用 OpenAICompatLLM.health()(GET /models,5s 超时,结果缓存 30s) 永远 200(状态在体里)
GET /api/companion 档案:名字、生辰+时辰、关系、称呼、八字只读白话(compile_pillars().traits_text() 输出);不含内部数值向量 404 未创建
POST /api/companion body {name, birth, hour, relation, nickname?}。服务端复验(规则与前端 validateCreation 一致:名字 1–20 字不含尖括号/控制符、日期合法且已满 18 岁、≥1900、relation ∈ {朋友,恋人} 且必选——不设默认值);排盘入 bazi_core(单行表);写档案 409 已有一位(单伴侣守卫);422 字段级中文错误;birth/derived 不提供任何修改端点(八字只读守卫)
PATCH /api/relation body {relation};只改关系字段,其余不动;"再次确认"交互由前端承担 404 / 422
POST /api/chat body {text, turn_id} → SSE(text/event-stream)。事件复用前端 ServerEvent 形状:chat.delta {epoch, turn_id, delta}、chat.final {epoch, turn_id, utterance{text, speech_tags}},另加 chat.error {epoch, turn_id, phi, retryable}。客户端断开(AbortController)即关闭上游 LLM 流 503 映射为 chat.error(phi:"她这会儿没接上话,稍后再试试",retryable:true)
GET /api/messages?limit=200 重开/换设备恢复历史(升序返回) —

B. 服务端状态与持久化

  • SQLite WAL:/opt/cybergril-data/cybergril.db【拟议路径】。复用 Store;增量新增 chat_message 表(id, ts, role, text, turn_id, status;CREATE TABLE IF NOT EXISTS 迁移,不动既有表)。bazi_core 存排盘;meta 表存 epoch(服务每次启动 +1 并持久)。
  • chat 上下文组装(最小版):系统提示 = 她的名字 + 关系 + 称呼 + 八字白话 traits_text + 世界红线(不出戏、不假装有物理身体、不把"等了你很久"当武器)+ 最近 20 轮消息 + 用户文本。经 ModelRouter 的 dialogue_main 场景(high 档)。
  • config/models.yaml【拟议改法】:三档先全指 http://192.168.200.11:8731/v1 + halogen-qwen3.8-flash-next(api_key_env: null;high temperature 沿 0.85,standard 0.7,low 0.4,timeout 沿用);budget 沿用(200 万 token/天,0.7 警告,0.95 硬停)。

C. 前端(真实模式)

  • 新增 web/src/adapters/real.ts【拟议】:RealChatAdapter implements ChatAdapter——fetch POST /api/chat + ReadableStream 解析 SSE,signal 直通 TurnGate 的 AbortController;fail 参数忽略。
  • 普通入口路由按 1.4 节分岔;创建向导复用四步流程,去掉"本机演示"文案,第 2 步"底色"展示服务端真实排盘白话(替换现在的"示例底色"),确认步的三段动画对应真实排盘/建档。
  • 关系修改接 PATCH /api/relation;管理页其余(城市/素材/备份)保持演示/占位态不变。

2.2 不做(R1 边界)

语音、生活循环、记忆检索、主动消息、天气、素材、备份、口型、视觉、多用户、鉴权体系(内网 + 单伴侣 409 守卫先行)、WebSocket(文字轮次 SSE 足够,语音批次再上 WS/RTC)。不以口型或生活引擎作为前置。

2.3 验收清单(总工复核用)

  1. 全新浏览器普通入口 → 四步创建(关系不选无法下一步)→ 服务器 DB 出现 bazi_core + 档案;重复创建 → 409。
  2. 发送文字:真实流式回复(非演示固定句"我听见了…");中途"取消本轮回复"立即停止;马上提新问题,旧流残句不串台。
  3. 关浏览器重开 / 换另一台设备打开:同一位她、历史消息完整恢复(服务器为唯一事实源)。
  4. systemctl restart cybergril-api → epoch +1,前端后续请求自动重同步,无旧事件混入。
  5. LLM 不可达(验收时用 health 面板状态 + 一次真实 503 路径验证)→ φ 文案、草稿保留、重试可成功。
  6. ?demo=1 演示功能与现在完全一致;Network 面板确认演示模式零外发请求、真实模式从不读取 cybergril.demo.v1。
  7. curl :8310/api/health 返回可读服务状态(含 llm.ok 与模型名)。
  8. web build 通过;Python 78 测试不回归;新增端点有对应测试。

2.4 停止条件

若 halogen 模型对话质量明显不可用(连续乱码/系统性拒答/超时 >30s 成为常态):停止验收,记录请求与响应证据,回报总管,不自行换模型、不开调参循环。

2.5 部署与回滚(总工执行)

  • 部署:/opt/cybergril-api/releases/<ts>/ + current 符号链接;systemd cybergril-api.service;端口 8310(当前空闲,部署时复核);前端构建由同一服务以 StaticFiles 同源挂载(API 走 /api 前缀)——同源避免 CORS 与混合内容;SSE 需关闭代理缓冲(uvicorn 直连即可)。
  • 回滚:systemctl stop cybergril-api + 符号链接切回上一 release + start;数据目录 /opt/cybergril-data/ 永不随回滚删除。8300 演示服务与浏览器演示档案全程不动。
  • 用户验收通过后,是否把 8300 切到新构建或以 8310 为正式入口,由总管与白栖知确认后执行。

3. 后续有限批次

依赖关系:R1 → {R2, R3};R2+R3 → R4;R5 依赖 R1(可并行于 R2–R4);R6 依赖 R1;R7 依赖 R5 的 HTTPS 路径 + 用户明确授权。

R2 生活循环(最小版)+ 未分享裁剪 + 日子页接真

  • 输入:R1 档案与 DB;character.yaml(day_start_hour=7、每天 1–4 条、reach_out 参数)。
  • 做:API 进程内 asyncio 定时任务(或独立 worker 服务)每日生成 life_event(low 档生成、过投影 φ 成世界内陈述、记 salience、told=0);"她讲过"最小机制:对话中引用该事件即置 told=1;GET /api/life?since= 分页,只返回 told=1 的事件,且响应前裁剪其一切关联引用(回忆 lifeIds、消息 lifeIds 一并剥离,覆盖列表/详情/摘要/搜索路径——服务器侧强制,对应前端 publicView 的服务端版);日子页数据源换 real 标签。
  • 不做:记忆整合、主动消息、素材视频(仍静帧+文字)、生活事件编辑/删除。
  • 验收:连续 3 天每天 1–4 条;curl 逐端点核验未 told 事件及引用零泄漏;网页关闭期间照常生成(服务端循环,非浏览器假数据);LLM 故障时循环降级跳过或模板句,不伪造生活。
  • 停止条件:事件质量持续荒谬或预算异常 → 停循环回报。

R3 记忆最小版 + 对话记忆

  • 做:每轮对话后写 mem_episodic(raw + low 档 gist 压缩 + affect 粗估);chat 上下文加 FTS top-k 检索("她记得");reinforce/decay_accessibility 定期跑批;回忆页 episodic 层接真。
  • 不做:向量检索(mem_vec 仍注释)、语义/关系层整合、identity promotion。
  • 验收:隔天提及前日话题,回复体现记忆;回忆页展示与对话一致;FTS 命中有日志可查。
  • 停止条件:检索噪声导致人设漂移 → 关检索开关回报(可配置降级为纯近轮上下文)。

R4 主动消息 + 返回同步

  • 做:reach_out 规则引擎(间隔≥6h、8–23 点、salience≥0.6,参数照 character.yaml);GET /api/sync?since= 统一游标(life + messages + reach_out 增量);页内轻提醒 + "你不在的时候"列表;措辞过 φ(缺席可被提及、不可被武器化)。
  • 不做:手机推送、危机通道。
  • 验收:构造高显著已分享事件后,规则窗口内收到主动消息且来源可点回;离线消息语气符合红线。

R5 语音连续对话(复用 /opt/voice-agent 底座)

  • 前置:HTTPS 方案落地(见第 5 节)+ 用户选音色(见第 4 节 D1)。
  • 做:新增一个 CyberGril 专属 agent worker(参照现有 agent.py 组装:FunASR STT + halogen LLM + CosyVoice TTS + silero VAD),system prompt 换成她的人格 + R1/R3 的档案与记忆上下文;前端聊天面板语音模式接 LiveKit client(HTTPS 页面内);字幕走 asr partial;打断沿用 VAD(0.55s 判定 + 清流);结束即停麦释放;文字模式全程并存。
  • 不做:口型(MuseTalk 8010 试验件为独立可替换线,不阻塞)、手机推送、副语言标签。
  • 已知限制内置缓解:TTS 首包 1.7–2.5s 期间显示"在想"+字幕先行;FunASR 双 final 出现频率记录,影响体验时切 mode=online。
  • 验收:连续对话 ≥3 轮;用户开口她 ~1s 内停声;结束即停收音;打断后无旧音频残留。
  • 停止条件:打断常态 >2s 或首包常态 >5s → 记录参数与日志回报总管,不重开旧无限调参流程。

R6 城市/天气 + 素材包 + 真备份

  • 做:城市存档 + GET /api/env(时段/天气);天气源按 D2 决定(推荐 open-meteo,先实测 .12 出网连通);素材包 manifest v1 导入校验(结构/时长/命名),只换 appearance_id,身份卡不变;备份:POST /api/backup/export(zip:DB+设定+素材引用)与 restore(上传→版本兼容+八字指纹比对=同一位她→恢复前自动先导出当前→确认执行);systemd timer 每日自动备份(7 份滚动,拟议)。
  • 验收:F7/F8/F9 全走通;恢复后记忆与关系保留、身份唯一;换素材档案不变;备份空间受控。

R7 视觉观察(独立决策,默认关)

  • 前置:R5 的 HTTPS 路径已跑通 + 白栖知明确授权摄像头 + 4080 使用决策(D4)。
  • 做:观察摘要带时效(前端 30s 过期演示逻辑的真实版);关闭显示"窗户关上了";隐私边界写入服务端。
  • 验收:开关生效、摘要时效、关闭后无任何采集。

4. 必须白栖知拍板的问题(均已给推荐答案,其余技术取舍由小队自行决定不升级)

# 问题 影响批次 推荐
D1 她的声音用哪支音色 R5 前 在 8090 音色管理页试听现有中文女声;都不满意就录一段 5–20s 中文参考音频做零样本克隆(页面已支持,这是"像不像"的关键)
D2 天气数据源 R6 前 open-meteo(免费、无 key);若 .12 出网不可达则暂用固定显示,不买付费接口
D3 手机/电脑麦克风的可信访问方式 R5 前 自签证书 + 每台设备首次"高级→继续"信任一次(8090 页已验证此路可行);不建内网 CA、不买域名公网证书、不改防火墙
D4 是否开启视觉观察(摄像头"一扇窗"),及 4080 小视觉服务的使用方式 R7 前 默认关闭;确认开启后再单独决策时段/帧率

5. 可信访问(HTTPS)核查结论与最少影响方案

  • 事实:浏览器麦克风/摄像头要求安全上下文;8090 通话页已用自签证书在局域网内验证过麦克风可用(浏览器手动信任一次)。
  • 推荐:R1 纯文字阶段无需 HTTPS;R5 前为正式入口(8310 或正式端口)按同一流程签一张覆盖 192.168.200.12 的自签证书即可。不改证书体系、不动防火墙、不影响任何现有服务;若未来要消除手动信任,再评估内网 CA(首版不做)。

6. 风险表

风险 影响 缓解
halogen 单模型、无 SLA、质量未实测 R1 回复质量不达标 R1 验收实测 + 明确停止条件;路由/预算框架已支持随时换模型(只改 yaml)
.11:8731 无鉴权、内网明文 同网段任何人可调用 保持内网边界;产品侧不内置 key;后续可加访问口令(建议项,不阻塞)
单用户 API 无鉴权,LAN 内他人可创建/聊天 档案被抢先创建 单伴侣 409 守卫 + 内网边界;访问口令列为 R2 建议项
.12 GPU 显存共享(CosyVoice ~5.6G + musetalk 试验 + 未来视觉) R5/R7 显存不足 R5/R7 开工前 nvidia-smi 核算;口型试验件可停(有启停记录)
FunASR 双 final、TTS 首包 1.7–2.5s 语音体验打折 已知限制,R5 方案内置缓解;vLLM TTS 后端列为后续优化
SSE 被代理缓冲 流式变一次性 uvicorn 直连;如加反代显式关缓冲
epoch/游标边界设计错误 状态串台 TurnGate 已守客户端;R1 验收专测重启/换设备场景
演示与真实模式混淆 用户误以为已接通 存储 key 分离、无自动上传、普通入口显式状态、演示角标保留
生活循环用假数据冒充 违反"不伪装运行"红线 R2 验收明确服务端生成证据(DB 记录 + LLM 调用日志)

7. 测试部署与回滚总安排

  • 每批均走 HEL-749 已验证的模式:/opt/cybergril-*/releases/<ts> + current 符号链接 + 独立 systemd 服务 + 独立端口 + 数据目录与代码分离;8300 演示站在白栖知明确验收前不动。
  • 回滚通式:systemctl stop <svc> && ln -sfn releases/<prev> current && systemctl start <svc>;数据目录永不删除;Git 侧对应回退 + 重新部署。
  • 各批验收含"服务状态可验证"(/api/health + 日志位置 + 启停命令写入部署记录)。

HEL-778 · 总工 · 2026-10-22 · 本轮只读核查 + 方案;未写产品代码、未改 .11/.12 任何服务与配置、未访问 4080、未输出凭据、未创建施工卡。