5.8 KiB
HEL-780 · R1 实现与安装运行说明
基准为 main 498429399812a0776dadd4b56662d31b455a9ea5，保留原前端两主题与统一样式，未增加 CSS 或运行中的服务。代码审核后由总工决定部署；施工阶段未登录部署服务器、未占用8310，也未修改8300、模型服务或用户档案。
src/cybergril/api/app.py：单进程 FastAPI 工厂；字段中文复验、无副作用真实排盘预览、唯一档案、只允许关系/称呼/边界修改、历史游标分页和 SSE。复用Store、八字编译器、ModelRouter与OpenAICompatLLM。memory/schema.sql：只增companion、api_meta、chat_message及索引；既有八字/生活/记忆/关系表保留。WAL；启动自动加 epoch，并把上次意外退出遗留的 pending 标记 cancelled。web/src/adapters/real.ts、app/RealApp.tsx：普通入口只读服务器数据，404首建；复用创建、聊天、管理和人物静帧组件。真实入口不读/写cybergril.demo.v1，草稿使用独立cg.real.draft。?demo=1仍由原 App 与 DemoAdapter 处理，零 API 请求。- 创建第二步通过
POST /api/companion/preview排盘，不写档案；仅最终确认 POST 才在一个事务内写唯一档案和八字。SQLite 单行主键与事务保证并发只成功一次。生辰按 Asia/Shanghai、公历、1900年起、满18岁复验；时辰映射为对应双小时内偶数点，不引入出生地点/真太阳时规则。 - SSE 使用同一
turn_id和持久epoch。前端每次发送先同步 epoch，并可处理发送前恰逢重启的409。轮次门槛继续拒绝旧事件；取消/退出直接 abort；服务端取消并等待上游结束后才开始新轮。响应缺少完成标志、空回答、异常或60秒超时均作为失败。部分回答丢弃，用户消息标 failed/cancelled，失败与取消的轮次不进下一轮上下文。成功回答可按同一 turn_id 回放，重试不会重复用户记录或重新生成已完成回答；并发相同轮次也只生成一次。 - 模型三档均使用批准网关与模型，保留原 temperature、provider timeout 与预算。dialogue_main 路由限制最近20轮，再按档位上下文预算保留完整近轮；不截断当前用户消息。每轮最多默认1024输出 token，usage 缺失时按字符数保守估算计账，沿用原预算降档策略。原 BudgetGuard 的预算是进程内运维量，重启重置；不是持久化费用账本。
API 契约：
| API | 成功/错误 |
|---|---|
GET /api/health |
200；epoch、是否已创建、模型探测与能力声明。模型 /models 2xx且包含配置模型才为真；5秒上限、30秒缓存、并发探测合并；不返回地址或凭据 |
GET /api/companion |
200档案（含只读四柱/白话），404未创建 |
POST /api/companion/preview |
{name,birth,hour}→只读底色，422中文字段错误 |
POST /api/companion |
{name,birth,hour,relation,nickname?}→201，409已有档案，422字段错误；拒绝额外字段 |
PATCH /api/relation |
{relation,nickname?,boundary?}→更新后档案；404/422；无任何生辰/底色修改入口 |
GET /api/messages?limit=200&before=<id> |
升序 messages、next_before、epoch；每页1–200条；按id稳定排序；前端逐页恢复 |
POST /api/chat |
{text,turn_id,epoch}；UUID turn_id；1–4000字；SSE chat.delta/final/error；404/409/422。chat.error带中文phi和retryable |
已接通：真实唯一档案、排盘、文字流式对话、服务器聊天历史、关系修改。尚未接通：生活循环、长期记忆检索/整合、主动消息、语音、视觉、天气、素材包与服务器备份。真实页面明确不可用，不填示例经历或伪造执行结果。当前只有近轮对话上下文，不把它说成长期记忆。
安装（Python ≥3.11；隔离环境，Node/npm用于构建）：
python3.11 -m venv .venv
.venv/bin/pip install -r requirements.lock
.venv/bin/pip install --no-deps .
npm ci --prefix web
npm run build --prefix web
requirements.lock 固定本轮已解析的运行时依赖；开发检查另装 pip install -e '.[dev]'。默认 Python 3.10 不满足项目要求。服务不自动读取 .env，变量需由启动环境或 systemd 提供：
export CYBERGRIL_DB=/absolute/separate/test-data/companion.db
export CYBERGRIL_HOST=127.0.0.1
export CYBERGRIL_PORT=18310
.venv/bin/python -m cybergril.api
从仓库根目录启动；默认模型配置 config/models.yaml、静态产物 web/dist，可分别通过 CYBERGRIL_MODELS / CYBERGRIL_WEB 指定绝对路径。本地默认数据库在用户 .local/share/cybergril/，生产必须显式指定独立数据目录。单进程单worker，不启用reload或多worker。 8310由总工部署时使用，本地测试脚本使用随机loopback端口、临时数据库并在结束时关闭服务。
自测：
.venv/bin/pytest -q
.venv/bin/ruff check src/cybergril/api src/cybergril/providers/llm/openai_compat.py tests/test_api.py
npm run typecheck --prefix web
npm run lint --prefix web
npm test --prefix web
npm run build --prefix web
# 下列为可选浏览器工具，只装在测试虚拟环境：
.venv/bin/pip install playwright
.venv/bin/python -m playwright install chromium
.venv/bin/python web/tests/real_browser_check.py
.venv/bin/python web/tests/browser_check.py 1440
.venv/bin/python web/tests/browser_check.py 390
浏览器脚本启动/关闭自己的HTTP服务。真实脚本只向批准网关发两轮完整对话和一轮中途取消；随后切同源隔离桩验证失败、重启和立即新轮，结果区分真实模型与桩。环境若需额外浏览器运行库，应使用现有用户级库，不改系统/GPU环境。本轮复用 /home/xiaomo/pwlibs/root/usr/lib/x86_64-linux-gnu 设置 LD_LIBRARY_PATH；它不是部署依赖。