deploying-gbrain-runtime

能力目标

在一台干净机器上把 GBrain 装好、初始化一个 PGLite brain、把 DashScope embedding 链路打通，最终跑通 gbrain put 写入 + gbrain search / gbrain query 检索命中，得到一个可用的 second-brain 运行时。

前置

• 运行时是 Bun（用 Zig 写的 JS/TS 一体化运行时兼包管理器）。若未装：curl -fsSL https://bun.sh/install | bash，然后确认 echo $PATH | grep .bun 有输出（非交互 shell 需手动 export PATH="$HOME/.bun/bin:$PATH"）。
• 需要 DashScope（阿里百炼）API key 做 embedding；DashScope 有 embedding，DeepSeek 只有 chat 没有 embedding，检索链路必须用 DashScope。
• 全部状态集中在 ~/.gbrain/ 单目录（PGLite 数据库、config.json、凭证）。

运行约定（所有 gbrain 命令都适用）：gbrain CLI 在 PGLite 下写完结果后常不主动退出、持有写锁，用 timeout -k 5 30 gbrain ... 包裹，exit code 124 是 SIGTERM 强制结束的正常退出、结果已完整写出；不要用 gbrain xxx | head/tail/grep（EPIPE 会让进程卡死），改用 gbrain xxx > /tmp/out.txt 2>&1; cat /tmp/out.txt。

实操流程

1. 进入零起点：备份挪走旧 brain（不直接 rm，留回滚），确认 ~/.gbrain 不存在：

   mv ~/.gbrain ~/.gbrain.backup-$(date +%Y%m%d-%H%M%S) 2>/dev/null
   ls ~/.gbrain 2>&1 || echo 'fresh-zero state'
   

2. 装 GBrain——但曾装过的机器不能直接跑 bun install -g github:garrytan/gbrain：Bun 全局包走 git ref 缓存，二次安装会命中旧 commit（缓存命中约 88ms，真下载约 9s，从耗时就能分辨）。强制刷新三连：

   bun remove -g gbrain
   rm -rf ~/.bun/install/cache/_g* ~/.bun/install/cache/garrytan-gbrain* 2>/dev/null
   bun install -g 'github:garrytan/gbrain#master' --force
   gbrain --version
   

   bun pm cache rm 是项目级命令（要在含 package.json 的目录跑），清全局缓存只能 rm -rf ~/.bun/install/cache/... 直接删目录。

3. 初始化 PGLite brain，在 init 时就把 embedding provider 与维度传全（否则 gbrain init 会重写 config.json 只留 engine/database_path、并把 DB vector 列锁死成 1536 维，事后改 config 无效）：

   timeout -k 5 60 gbrain init --pglite \
     --embedding-model dashscope:text-embedding-v3 \
     --embedding-dimensions 1024
   cat ~/.gbrain/config.json   # 应含 embedding_model + embedding_dimensions:1024
   

   --model dashscope（短 ID）是等价简写、内部按 recipe 补齐 text-embedding-v3 + 1024 维；但 init 只接收 provider 短 ID，--model dashscope:text-embedding-v3 复合写法会报 Unknown provider。带冒号的复合写法只用于 init 之后的 gbrain config set embedding_model。

4. 打 DashScope 国内端点补丁：DashScope recipe 默认走国际站 dashscope-intl.aliyuncs.com，国内申请的 key 无国际站权限、会被判 Incorrect API key；config 层任何 override（config set / 改 config.json 的 base_urls / provider_base_urls）都不生效，唯一生效路径是改本机 recipe 源码默认值：

   RECIPE=~/.bun/install/global/node_modules/gbrain/src/core/ai/recipes/dashscope.ts
   sed -i.bak 's|dashscope-intl.aliyuncs.com|dashscope.aliyuncs.com|g' "$RECIPE"
   grep base_url_default "$RECIPE"   # 应显示 dashscope.aliyuncs.com（无 -intl）
   

   .bak 后缀保留原文件备份。这个补丁是脆性的：每次 bun install -g ... --force 或 gbrain upgrade 都会覆盖回去，需重打——把这条 sed 写进安装自动化脚本的 post-install hook。海外 key 无需此补丁。

5. 校验 embedding 链路：先导出 key，再让 doctor 打一次真实 embedding probe：

   export DASHSCOPE_API_KEY='<你的 DashScope key>'
   gbrain providers test --model dashscope:text-embedding-v3
   

   看到 ✓ ... 1024 dims / All probes green 即打通。若仍报 Incorrect API key，先用 curl 直连国内原生端点隔离验证「key 本身有效 vs 端点选错」：

   curl --noproxy '*' -sw '\nHTTP: %{http_code}\n' \
     -X POST 'https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding' \
     -H "Authorization: Bearer $DASHSCOPE_API_KEY" -H 'Content-Type: application/json' \
     -d '{"model":"text-embedding-v3","input":{"texts":["hello"]},"parameters":{"text_type":"document"}}'
   

   HTTP 200 + 返回 1024 维数组 = key 有效、问题在端点，回第 4 步确认补丁已打。

6. 首次写入 + 检索验证（brain 内容建模细节见 authoring-brain-pages）。用 gbrain put <slug> 从 stdin 写入 markdown、gbrain stats 看计数、两条检索：

   printf -- '---\ntype: company\n---\n# Acme AI\nAcme AI builds retrieval tools in San Francisco.\n' \
     | gbrain put companies/acme-ai
   timeout -k 5 30 gbrain stats
   timeout -k 5 30 gbrain search 'Acme AI' --limit 5
   timeout -k 5 30 gbrain query 'what does acme ai build' --no-expand
   

   --no-expand 关掉 LLM query expansion，避免长 query 走 expand 路径把候选全过滤掉、也避免 30s+ 延迟。

校验回路

• gbrain --version 输出的版本号与 GitHub master HEAD 一致（不是旧缓存版本）。
• cat ~/.gbrain/config.json 含 embedding_model: dashscope:text-embedding-v3 与 embedding_dimensions: 1024。
• gbrain doctor 中 embedding_provider 从 [WARN] Incorrect API key 变为 [OK] ✓ ... 1024 dims, DB aligned。空 brain 的 brain_score: 0/100 是预期、写入数据后自然涨；大量 skill resolver 类 WARN 不阻塞主路径。
• gbrain search / gbrain query 对已写入的 page 返回带 slug + score 的命中结果。

常见陷阱

• bun install -g 装到旧版本且无察觉：升级场景高危，从未装过的机器不会踩（无缓存必走真下载）。装完必须 gbrain --version 核对，不对就走强制刷新三连。
• gbrain init 悄悄重写 config.json：每次 init 都清空 embedding 配置、并按默认 1536 维建 vector 列。必须在 init 命令里就传 --embedding-model + --embedding-dimensions 1024；已经建错维度只能 rm -rf ~/.gbrain/brain.pglite 后带正确 flag 重 init。
• 对着「KEY 无效」盲改 key：工具报 KEY 无效 ≠ KEY 真的无效。先用 curl 直连原生端点隔离，确认是端点问题再改 recipe，别去申请新 key / 换账号。
• doctor 里 alternative_providers: openai ready 是误报：GBrain 静态 detect 路径不实际 probe，没配 OPENAI_API_KEY 也显示 ready，不能当 fallback 救命稻草。
• 命令卡死 / 卡 30s：exit 124 当正常退出处理；避免 pipe；query 加 --no-expand。