157 lines
9.9 KiB
Markdown
157 lines
9.9 KiB
Markdown
# HEL-874/882 · 8360 隔离发布包(离线核验过,未执行部署)
|
||
|
||
**状态:审核通过与预算批准前不启动面向用户的真实循环、不部署、不合并 PR、
|
||
不向用户交体验地址。**本文件是发布卡照抄即可执行的包;不触 8300/8310/8320/
|
||
8340/8350 与共享 ASR/TTS/口型,不访问 4080,不导入演示/测试档案为用户伴侣。
|
||
|
||
HEL-882 修正:空目录 checkout、服务 import(PYTHONPATH)、服务账号/权限、
|
||
mem0 同进程导入的准确缺项与不下载解决路径、空账初始化、请求上限随包默认 0。
|
||
离线核验命令见 §6(tools/check_release_offline_hel882.py,仅回环、echo 替身、
|
||
临时目录,零真实网关请求)。
|
||
|
||
## 1. 交付物清单
|
||
|
||
- 代码:分支 `hel-870-assembly`(PR #11,head 见交付评论),含
|
||
`deploy/cybergril-hel874-8360.service.example`、`tools/check_release_offline_hel882.py`
|
||
与本文件。
|
||
- 依赖:Python 3.11 + `requirements.lock`(uv 离线可装);前端 `web/` 原作者
|
||
构建产物(`npm ci && npm run build`);语义真实模式另需固定 mem0 栈(§4,
|
||
需先落 wheel,当前缓存没有 3.11 版)。
|
||
|
||
## 2. 安装命令(发布卡执行)
|
||
|
||
> **已被取代(HEL-879,2026-10-27)**:本节安装命令缺 `--offline`/`--no-index`
|
||
> 强制项。唯一照抄入口改为 `deploy/hel895-release-candidate.md` §2。本文件其余
|
||
> 内容作为历史交付证据保留原样。
|
||
|
||
```bash
|
||
# 全新目录,逐条照抄;任何一步失败即停
|
||
# 2.1 服务账号与目录(独立可写数据路径,权限边界明确)
|
||
useradd --system --home-dir /opt/cybergril-hel874 --shell /usr/sbin/nologin cybergril || true
|
||
mkdir -p /opt/cybergril-hel874/data # data 必须为空:新账从零初始化
|
||
chown -R cybergril:cybergril /opt/cybergril-hel874
|
||
|
||
# 2.2 代码 checkout:current 必须是全新空目录后 clone(空目录里没有仓库,
|
||
# 不能直接 git fetch —— HEL-882 修正)
|
||
git clone ssh://git@192.168.200.36:222/leefer/CyberGril.git /opt/cybergril-hel874/current
|
||
git -C /opt/cybergril-hel874/current checkout <交付评论中的精确head>
|
||
|
||
# 2.3 依赖与前端(复用 uv/npm 离线缓存;缓存缺失时此步需要内网源,发布卡留证)
|
||
cd /opt/cybergril-hel874/current
|
||
uv venv --python 3.11 .venv311
|
||
uv pip install --python .venv311/bin/python -r requirements.lock
|
||
(cd web && npm ci && npm run build)
|
||
|
||
# 2.4 服务单元(单元内已带 PYTHONPATH=<current>/src:requirements.lock 只装依赖,
|
||
# 产品代码经 PYTHONPATH 进程内可 import —— HEL-882 修正)
|
||
cp deploy/cybergril-hel874-8360.service.example /etc/systemd/system/cybergril-hel874.service
|
||
systemctl daemon-reload && systemctl enable --now cybergril-hel874
|
||
curl -s http://127.0.0.1:8360/api/health | python3 -m json.tool
|
||
```
|
||
|
||
随包 `config/models.yaml` 的请求上限全部为 0(未批准即拒绝):在总管写入批准
|
||
值(A 部分一次性总量或 C 部分类别日顶)之前,创建/对话/生活/gist/主动措辞/
|
||
Mem0 提取都会在发送前被硬闸拒绝(`budget_*_exhausted`)——这是设计行为,
|
||
不是故障;批准值的写入位置与口径见 `docs/budget-plan-hel874.md`。
|
||
|
||
## 3. 健康能力矩阵(/api/health 预期)
|
||
|
||
| 字段 | 预期 | 说明 |
|
||
| --- | --- | --- |
|
||
| version | `R4-assembly` | |
|
||
| backend.mood / reach_out / semantic | true | 情绪/关系/生活/主动联系接线 |
|
||
| backend.semantic_backend | `stub`(发布初期) | 真实 mem0 待 B 部分预算批准(§4) |
|
||
| capabilities.proactive | true | 生活循环开启时 |
|
||
| capabilities.semantic_memory | `stub` | 不冒充语义 |
|
||
| voice / vision / weather / materials / backup | false | 界面诚实文案,不伪装 |
|
||
|
||
## 4. 真实语义激活前置(B 部分批准后;准确缺项与不下载路径)
|
||
|
||
> **已被取代(HEL-879,2026-10-27)**:本节 4.1/4.2 按索引拉 `mem0ai==2.2.1`
|
||
> 同名 wheel,不能保证固定源码身份 2c81af3;固定 SDK 激活的唯一照抄入口改为
|
||
> `deploy/hel895-release-candidate.md` §4(固定 tarball 哈希 → 固定源码构建轮 →
|
||
> cp311 依赖准备 → 仅本地轮安装 → 同进程 co-import)。以下保留为历史证据。
|
||
|
||
**当前事实(HEL-882 离线核实,tools/check_release_offline_hel882.py R6):**
|
||
固定安装 hel857-venv 是 Python 3.10.12,产品发布 venv 是 3.11.16,两者
|
||
site-packages 不能混用;本机 uv/pip 缓存里没有 mem0ai/fastembed/qdrant-client
|
||
的 3.11 wheel,本卡不下载。因此发布卡要在 **B 部分批准后** 先落 wheel 再激活。
|
||
|
||
**HEL-885 命令勘误:旧版此处的 `uv pip download …` 在本机 uv(0.13.5)不存在
|
||
(`uv pip download --help` 退出 2:unrecognized subcommand 'download',已复测,
|
||
见 docs/rework/hel885/)。本机确实可用的落 wheel 工具是 pip 的 download 子命令
|
||
(`python3 -m pip download --help` 退出 0)。发布 venv 由 uv 创建、不带 pip,
|
||
这不影响:下载在任一装有 pip 的 Python 上执行即可,wheel 按目标平台解析。**
|
||
|
||
```bash
|
||
# 4.1 在有内网源权限的环境把固定栈拉全(发布卡执行并留证;不在本卡执行、
|
||
# 不下载)。先核对目标机平台:uname -m 必须与 --platform 一致(当前
|
||
# 部署机为 x86_64 Linux)。
|
||
uname -m # 预期 x86_64;不符则改 --platform
|
||
mkdir -p /opt/cybergril-hel874/wheels
|
||
python3 -m pip download -r deploy/mem0-stack.lock -d /opt/cybergril-hel874/wheels \
|
||
--only-binary :all: --implementation cp --python-version 3.11 \
|
||
--platform manylinux2014_x86_64 --abi cp311
|
||
# 4.1b 固定源身份与哈希留证:下载当时逐 wheel 记录 sha256(与发布评论一并
|
||
# 存档;mem0ai 的源码身份 2c81af3 / tarball SHA256 见 deploy/mem0-stack.lock
|
||
# 注释——如需从源码 tarball 侧核对,比对 lock 注释中的值)。
|
||
sha256sum /opt/cybergril-hel874/wheels/*.whl | tee /opt/cybergril-hel874/wheels/SHA256SUMS
|
||
# 4.2 同一发布进程离线并入(一个 venv 同时 import 产品与 mem0 —— 唯一被认可形态;
|
||
# uv pip install 是本机确实存在的子命令,--no-index 离线装)
|
||
uv pip install --python .venv311/bin/python --no-index \
|
||
--find-links /opt/cybergril-hel874/wheels -r deploy/mem0-stack.lock
|
||
.venv311/bin/python -c "import cybergril.api, mem0, qdrant_client, fastembed; print('co-import ok')"
|
||
```
|
||
|
||
**准确缺项与如实上报(HEL-885):** 本机当前没有这些 3.11 wheel,本卡零下载,
|
||
`wheels/` 目录与 SHA256SUMS 均不存在——发布卡执行 4.1 时才能产生。若某个固定
|
||
版本在 cp311/manylinux2014_x86_64 没有 wheel(`--only-binary :all:` 会直接报错
|
||
指出包名),按 lock 注释如实上报缺项,不得换版本号冒充固定安装、不得改用 sdist
|
||
混装。4.2 的 co-import 是最终判据:任何一个 import 失败即未完成,不得以 stub/
|
||
FTS 降级包冒充用户的真实完整记忆体验(体验交付必须等本节全部完成 + 新增预算
|
||
批准)。发布前可先跑 `python3 tools/check_release_offline_hel882.py` 的 R7
|
||
核验本节两条命令的工具面(pip download 存在、uv pip download 不存在)。
|
||
|
||
激活步骤(wheel 落好之后):
|
||
|
||
1. `cp config/semantic.example.yaml config/semantic.yaml`,总管填批准值:
|
||
`embed_cap`/`llm_cap`(B 部分累计,换算算式见示例文件与执行表 §2——
|
||
500+增量,不是把增量直接填进累计上限)、`embed_daily`/`llm_daily`
|
||
(C 部分日顶)、`embed_reserve`;`ledger_path` 指向唯一权威
|
||
`embed_ledger.sqlite3` 续账(`llm_ops` 同库新表),并**填写** `authority`
|
||
冻结前缀块(HEL-885 起必填:缺/空/错一律在构造前拒绝
|
||
`ledger_authority_required`,指向新空文件绕过 498/500 冻结同样被拒)。
|
||
2. `CYBERGRIL_SEMANTIC=mem0` 重启。任何未批调用 fail-closed
|
||
(`semantic_*_budget_not_approved/exhausted/daily_exhausted`);SDK 内部
|
||
提取 LLM 同时过统一请求闸(`semantic` 类别 + 日 token 池,发送前预占)。
|
||
|
||
## 5. 停用与保留数据回退
|
||
|
||
- 停语义层:`CYBERGRIL_SEMANTIC=off`(或 stub)重启;`sem_batch/sem_covered/
|
||
sem_row_done` 按后端区分保留,重开续跑不重发已完成行(逐行锚点+逐行完成
|
||
记录,HEL-885),stub 批次不阻塞真实重建。
|
||
- 停主动联系/生活:`CYBERGRIL_R2_ENABLED=0`。
|
||
- 整实例回退:`systemctl stop cybergril-hel874` → 数据目录
|
||
`/opt/cybergril-hel874/data/` 原样保留(聊天/记忆/生活/情绪/关系全量 +
|
||
请求/token 硬闸计数,SQLite WAL 单文件可整体复制)→ 切回上一 release /
|
||
上一提交。R4 迁移全部为增量新表(r4.sql:语义/活动/主动/硬闸计数),
|
||
旧代码可安全打开同一数据库。
|
||
- 彻底撤销:`systemctl disable --now cybergril-hel874 && rm /etc/systemd/system/
|
||
cybergril-hel874.service`;数据目录留档不删(用户资料不重置边界)。
|
||
|
||
## 6. 发布前必过检查(发布卡执行并留证)
|
||
|
||
1. 离线可执行检查(本卡已跑通,证据见交付评论;发布卡在目标机重跑):
|
||
`python3 tools/check_release_offline_hel882.py --venv <发布venv>/bin/python`
|
||
—— R1 空目录 checkout、R2 服务 import+health、R3 未批上限 fail-closed、
|
||
R4 批准后全链(echo 替身)、R5 停止后数据保留/重开 epoch+1、
|
||
R6 mem0 同进程导入现状(缺什么、怎么补,§4)。
|
||
2. `python3 scripts/check_requirements.py --base-ref origin/main --handoff
|
||
docs/requirements/handoff-HEL-882.json` 及 `--base-ref
|
||
origin/agent/agent/de8874a3803b`(双目标各含/不含 handoff)。
|
||
3. 3.11 venv 全量 pytest + ruff + web typecheck/test/build。
|
||
4. 隐私负例(未分享伴侣行不出现在任何 provider 输入/DTO/页面)与重开恢复
|
||
(epoch+1、消息一致、主动消息带标记)。
|
||
5. A 部分预算未批前:`semantic.yaml` 缺省即 cap=0,`/api/health` 的
|
||
semantic_backend 必须仍为 stub;`models.yaml` 请求上限未批前必须全 0。
|