Files
CyberGril/deploy/hel874-release.md
T
zonggongandmultica-agent 01ff919859 HEL-879 release closure: the four HEL-896 audit findings become enforced behavior - (1) archive consistency: tools/release_snapshot_hel896.py v2 checks the wal_checkpoint(TRUNCATE) return (busy!=0 = hard failure, no deliverable tar, half-built dir removed - 'stopped service first' is a precondition, never a reason to ignore an actual failed result), aborts packaging on any source-vs-snapshot table-count mismatch instead of recording rows_match=False and shipping anyway, and verify_archive now rejects legacy packages that recorded rows_match=False while mapping a real rollback drill (unpack to an isolated dir, open every DB, check rows AND hashes against both recorded source and snapshot counts, emit a source-path rollback_plan - no more tar-internal self-attestation); selftest 9/9 reproduces every old failure shape first (naive WAL copy loses companion, held-reader checkpoint=(1,9,8) leaves the copied image malformed/missing the events row, the manager's rows_match=False legacy package verifying ok) then proves each fix (busy fails with zero artifacts, stale-snapshot mismatch fails with zero artifacts, online mode refuses --file dirs containing SQLite by magic-header scan, stop mode recursively takes embedded SQLite like history_root/mem0_public_history.db through checkpoint+per-table verification, verify maps source paths and passes); (2) early-finish seal: PersistentBudget gains sealed()/seal() writing sealed/sealed_requests/sealed_tokens/sealed_at atomically into budget_total beside the real usage (never faking 55, never zeroing), acquire checks the seal FIRST so every category and every remaining allowance rejects budget_sealed:51/55, the marker survives restart and backup-API archive/restore, reseal is idempotent, and there is deliberately no unseal path (re-test = new approval + new instance per budget-package 6.2.4); tools/seal_budget_hel879.py makes the closure an explicit auditable operator command with a post-seal rejection self-check; verify_budget_split_hel896.py gains S6 (51/55 experience chain completes -> seal keeps usage 51 -> 52nd and cross-category rejected with dialogue daily still 19/60 proving it is the seal not the caps, mistaken restart rejected, archive restore rejected, marker requests=51 intact) now 10/10, HEAD made dynamic instead of hardcoded 04eff61; budget-package-hel895.md 6.2 rewritten to the executable seal order (stop -> seal -> consistency snapshot); (3) single install entry: deploy/hel895-release-candidate.md 2 is now the only copy-paste install (uv --offline, npm --offline, cache-miss = stop and record, network only inside an authorized release window with per-item sha256) and 4 is the only fixed-SDK entry as a five-step chain (verify tarball sha256 9dcef930...dda23 against mem0-stack.lock -> build the wheel from the fixed source with hatchling honestly listed as the missing build backend -> cp311 dependency prep with greenlet/pillow/truststore confirmed cache-reusable on re-run -> local-wheels-only --no-index install where mem0ai must come from the fixed-source wheel, the lock line is version-only -> same-process co-import plus the 92MB fastembed cache placement); deploy/hel874-release.md 2/4 carry superseded banners pointing here, mem0-stack.lock no longer routes installs through the index mem0ai==2.2.1 wheel; (4) exact-commit honesty: audit_sdk_offline_hel896.py derives head from git rev-parse and accepts an output dir, fresh evidence written to docs/rework/hel879/sdk-audit/ (hel896 evidence left untouched) recording closure 55 / missing 41 (28 pure + 13 native) / cache-reusable [greenlet, pillow, truststore] / tarball-matches-lock at c121c42; regression on this head: pytest 299/299, ruff clean (src/tests/tools), release-snapshot selftest 9/9, budget-split 10/10 including the new S6 negatives; zero provider calls, zero downloads, authoritative ledgers/freezes/HEL-835 gate untouched, not deployed, PR#11 untouched
Co-authored-by: multica-agent <github@multica.ai>
2026-10-27 03:26:30 +08:00

157 lines
9.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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。