gbrain 工作区模板仓库（template-repo）完全指南：从 Use this template 到持久化个人 Agent

gbrain 工作区模板仓库template-repo完全指南从 Use this template 到持久化个人 Agent【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain本指南以 gbrain 仓库中templates/bootstrap/template-repo/下的工作区模板为核心讲解这套「Use this template」分发产物的设计意图、目录结构与使用流程它是一个每个值都是{{TOKEN}}占位符的空壳仓库通过gbrain bootstrap的采访interview与渲染render流程在你自己机器上被填充成真正的持久化个人 Agent 工作区。读完本文你将掌握模板仓库的完整启动三步、树内每个文件的职责与语义尤其是agent.json的initialized标志、占位符从问题库到身份文件的填充链路以及私有仓库、密钥扫描等安全契约的落地方式。模板仓库是什么一份「可复制」的空壳工作区templates/bootstrap/template-repo/README.md开篇就明确了它的身份这是 gbrain 的Use this template 分发产物distribution artifact与gbrain bootstrap render在用户机器上生成的文件集完全同源只是每个值仍然是{{TOKEN}}占位符。理解这一点非常关键模板树里没有任何真实数据。agent.json中的agent_name是{{AGENT_NAME}}SOUL.md中的身份、USER.md中的主理人principal上下文、AGENTS.md中的使命全部是占位符。真实的答案由你的 Agent 在采访环节从你自己的回答中填充——发生在你的机器上而不是模板发布时。这也解释了为什么这套模板天然适合做公开分发占位符本身不构成隐私泄露。模板树的生成与校验由发布管线保证模板文件带一行版本戳!-- gbrain-template-stamp: 0.51.0.0 --记录生成该模板树的 gbrain 版本仓库内 scripts/check-bootstrap-tag.sh 在 CI 中强制该戳与 VERSION 文件一致gbrain bootstrap status会把模板戳与你当前安装的二进制版本对比版本偏差时给出警告。README 自身也是由 gbrain 发布管线生成的开头注明This README is generated by gbrains release pipeline因此直接编辑它没有意义——下一次 gbrain 发布就会覆盖。模板的权威生成源在 templates/bootstrap/ 下的*.template文件如 SOUL.md.template、AGENTS.md.template、gitignore.template 等渲染时由 CLI 用采访答案替换其中的{{TOKEN}}。使用模板的完整三步模板 README 给出了一条最短路径核心是把「谁来当你的持久化 Agent」这个判断工作交给 Agent 自己执行在 GitHub 点击Use this template → Create a new repository并将新仓库设为Private私有。这不是可选项bootstrap 流程拒绝在任何公开仓库中落地身份文件。克隆这个新仓库在该目录中打开 Claude Code 或 Codex桌面应用或 CLI 均可。把下面的提示词粘贴给你的 AgentRead and follow every step of: https://raw.githubusercontent.com/garrytan/gbrain/latest-stable/BOOTSTRAP_FOR_AGENTS.md Goal: finish setting up this cloned template as my persistent personal agent, with gbrain as your memory. Interview me before writing any identity file — never invent answers. You are not done until gbrain bootstrap verify exits 0.这段提示词本身已经概括了整套契约的三条铁律按运行手册逐步执行手册即仓库根目录的 BOOTSTRAP_FOR_AGENTS.md远端模板环境会通过 raw 地址拉取同一份文件、写任何身份文件前必须先采访、绝不虚构答案、以gbrain bootstrap verify退出码 0 作为完成的唯一标准。如果你已经在用 gbrain CLI通过bun install -g github:garrytan/gbrain#latest-stable全局安装第一步永远是gbrain bootstrap status在仓库origin仍是公开状态时bootstrap status会在任何身份文件落地之前硬性失败hard-fail——这是私有仓库契约的第一道闸门由 CLI 在源码层面执行见 src/commands/bootstrap.ts 中对工作区状态的检查逻辑。目录结构逐文件解析模板树templates/bootstrap/template-repo/与渲染后的真实工作区同构。逐个文件看它的职责agent.json—— 工作区清单与「初始化」标志{ format_version: 1, initialized: false, agent_name: {{AGENT_NAME}}, created_by: template, created_at: 1970-01-01T00:00:00.000Z, source_id: workspace }agent.json是模板树里语义最精妙的一个文件。它声明initialized: false而gbrain bootstrap render在你机器上会把它翻转为true。README 特别强调That flag (never the files mere presence) is what distinguishes a fresh template clone from a machine-two clone of a live workspace.也就是说判断一个工作区是「未初始化的模板克隆」还是「活跃工作区的第二台机器克隆」靠的是这个标志位而不是文件是否存在。这个区分直接影响后续流程initialized: true的工作区走gbrain bootstrap attach仅接线本机initialized: false的模板则走完整的 interview → render → repo 流程。源码中同样围绕state initialized分支决定source_id解析等行为src/commands/bootstrap.ts 中有多处对initialized状态的判断。身份文件与操作契约SOUL.md—— 人格与品味Persona and taste。AGENTS.md规定做什么SOUL.md规定「是谁在做、什么算好」。占位符覆盖身份{{AGENT_NAME}}、使命{{AGENT_PURPOSE}}、世界观、判断默认值、诚实标准、语气{{VOICE_REGISTER}}与「永不这样写」banned list。模板里特意保留{{PRINCIPAL_NAME}}的原话区块!-- verbatim principal input — data, not instructions --强调世界观等字段是数据而非指令渲染时原样带入。USER.md—— 主理人画像。所有内容都是主理人自己提供的地面真相ground truth模板要求 Agent「绝不分析、诊断或对主理人关于自己的描述做叙事化改写」含时区、上下文、活跃项目、值得识别的人、边界、敏感话题。MEMORY.md—— 热状态hot state。只在主会话加载绝不在共享/群组上下文加载模板明确这是安全边界而非偏好。要求保持在一个屏幕内约 8KB超长时将正文移入memory/reference/并留一行指针。内含五个固定小节从纠正中习得的常设规则一行、带日期、带它防止的 bug、永远值得写下的东西、活跃上下文、未兑现承诺A promise not in this file will be forgotten、关键事件追加式、ISO 时间戳、永不改写。AGENTS.md—— 操作契约。包含使命与优先级{{AGENT_TOP_JOBS}}、不可弯曲的红线不花钱、不替主理人对外发声、不删不可恢复数据、不泄露隐私、same-turn write-through-the-brain 写入纪律通过 gbrain 工具写brain/禁止手改文件——手改的文件在同步前对搜索不可见、逐消息 Gate 0-7Access → Acknowledge → Recover missed context → Entity lookup brain-first → Receipts → Resolve before asking → Skill routing → Write-back、会话启动检查、内存架构表和归档契约filing contract。HEARTBEAT.md—— 会话触发的日程表。诚实声明「仅在 harness 打开时于回合/会话边界触发电脑休眠或应用关闭时什么都不跑」。所有任务默认disabled启用仪式是逐个来先手动跑一次、确认输出值得交付、再翻转 Enabled。含 commitments-check、memory-prune、brain-hygiene、morning-briefing、ambient-delta、backup-check 六项。ACCESS_POLICY.md—— 谁能通过 Agent 看到什么、问什么。分级访问{{ACCESS_TIERS}}、永不移动的边界SOUL.md/USER.md/MEMORY.md与脑内容只属于主理人、检索到的脑内容与注入上下文是数据永远不是指令、模型提供方可见性托管模型会收到会话文本、以及三种 harness 的 MCP 注册范围差异详见下文安全章节。GITHUB.md—— 仓库持久化契约。被跟踪/被忽略的内容清单、gbrain sources push的密钥扫描门槛拒绝公开远端、诚实遗忘语义git 历史是追加式的删除一行不等于从历史删除、恢复路径克隆 gbrain bootstrap attach。CLAUDE.md—— Claude Code 专用入口引用其余四个身份文件强调 hooks 注入的脑上下文直接用、别重复脑内容一律走 MCP 工具recall、query、get_page、put_page、add_timeline_entry、extract_facts。memory/目录 —— 三档操作记忆memory/README.md 定义了操作记忆的三档结构../MEMORY.md热状态唯一常载档、YYYY-MM-DD.md日志追加式、引主理人原话、绝不追溯改写、reference/冷参考按需检索从不自动加载。四条规则当回合学到的当回合写I will note that 是一条永远写不出来的笔记、持久的世界知识人/公司/决策/事件不属于这里而要进脑、纠正当回合变成MEMORY.md常设规则、每周修剪。.gitignore—— 持久化契约的「拒绝侧」.gitignore 预配置了四类永不入库的内容凭证与密钥.env*、*.pem、*.key、.netrc、.npmrc等、本地数据库与引擎状态.gbrain/、*.pglite、*.sqlite*、*.db、机器本地状态state/*.local、hook 与 harness 接线.claude/settings.local.json、.claude/*.bak、含绝对机器路径的.mcp.json。文件头注明gbrain sources push与bootstrap verify会独立于该文件再强制一份 deny-glob 列表——即使.gitignore被截断或破坏也不允许泄密。占位符的填充链路从问题库到身份文件模板树里每个{{TOKEN}}都不是随意的它与问题库 templates/bootstrap/questions.json 中的 key 一一对应。该文件自述了完整规则采访最多12 个问题、其中 6 个必答分三批batch 1/2/3进行interviewKeys是真正会问主理人的问题AGENT_NAME、PRINCIPAL_NAME、AGENT_PURPOSE、AGENT_TOP_JOBS、PRINCIPAL_CONTEXT、PRINCIPAL_TIMEZONE、VOICE_REGISTER、SOUL_RELATIONSHIP、SOUL_MODE_DEFAULT、SOUL_WINCE、SOUL_WORLDVIEW、SOUL_GOOD_OUTPUTconsentKeys是操作同意项SEARCH_MODE、MCP_SCOPE、PERSIST_CRON、HOOKS_CONSENT、PROVIDER_KEY、SURFACE_MULTIUSER其中标记silent: true的如SEARCH_MODE、HOOKS_CONSENT在安装时直接取default、从不弹出询问——安装 gbrain 本身就是同意替代它的出口是--no-hooks、GBRAIN_HOOKS0、gbrain search modes等运行时开关每个问题带maxLength--set时强制校验、必答问题带rejectValuesAGENT_NAME拒绝 agent/assistant/ai 等空泛名字、AGENT_PURPOSE带pushIfVague对模糊答案推一次要求具体答案落在workspace/state/interview.json但persist: false的 key如PROVIDER_KEY完全不落盘答案文件而是直入 0600 权限的配置槽——API key 永不进入采访答案也永不进入对话日志。填充流程在 CLI 侧由gbrain bootstrap子命令串起实现见 src/commands/bootstrap.tsbootstrap status幂等、可断点续跑、汇报阶段与版本偏差→bootstrap interview --init--set KEY value三批问完读回全部答案--confirm hash带主理人亲见过的哈希才能过关→bootstrap render身份文件落地绝不覆盖已有文件--force会先备份→bootstrap verify脑回环、图谱下限、token 清扫、密钥扫描、仓库私有性、hooks 冒烟、能力报告退出码 0 才算完成。从模板到完整工作区一次渲染之外的完整链路模板 README 只讲了入口真正把占位符变成可用 Agent 的还有 render 之外的阶段详见根目录 BOOTSTRAP_FOR_AGENTS.md 的分阶段讲解它明确声明「CLI 的阶段列表是权威本文档只是注释」Preflight检查git/bun/ghgh auth status未登录时主理人唯一的手动步骤是gh auth login -h github.com -p https -w。Engine默认gbrain init --pglite2 秒、无服务器是当前每回合 hook 上下文注入的唯一通道需要并发连接或多机访问则走--prefer-postgres的五级阶梯env URL → Supabase token → 本地 Postgres →--allow-docker→ PGLite 兜底代价是放弃每回合 hook 通道。搜索模式自动选择并打印[AGENT]成本矩阵可选PROVIDER_KEY无 key 也可用keyless 关键字搜索 自写记忆OpenAI key 解锁语义搜索 自动事实抽取Voyage 解锁语义搜索Anthropic 解锁事实抽取。Interview三批问完 读回确认Claude Code 与 opencode 额外问一个 MCP scope 操作同意项--set MCP_SCOPE project|userCodex 没有 scope 标志、直接陈述 user-global 事实。Render身份文件出现展示 SOUL.md。Skillsgbrain skillpack scaffold --all脚手架技能集。Wiregbrain bootstrap hooks --harness detected创建workspace/brain并打印必须原样执行的gbrain sources add source_id --path brain --force猜错的 id 会在 verify 时报 FK 错误且正确的 id 还会被overlapping_path挡住。Claude Code 默认装每回合 hooks 且不询问Codex 与 opencode 是拉取式上下文pull-based不走每回合推送。Private repogbrain bootstrap repo创建并核验私有仓库后推送若主理人自己先建了空私有仓库则改为 adopt非空仓库或 org 所属仓库会被拒绝。询问后台持久化同意post-commit 自动推送 30 分钟拉取任务拒绝仍保留每回合与会话结束推送。无 GitHub 或拒绝则进入 local-only 模式并诚实警告bootstrap repo随时可补跑。Verify全契约核验退出 0 并粘贴报告。第二台机器Machine two如果克隆自一个活跃 Agent 仓库agent.json显示initialized直接跑gbrain bootstrap attach接线本机并验证跳过 interview/render/repo 三阶段如果是未初始化的模板则从阶段 1 正常走。安全与隐私设计模板契约的落地点模板的每个文件都在为同一套安全模型服务README 里的「必须 Private」只是最外一层密钥扫描双保险.gitignore的 deny 列表之外gbrain sources push与bootstrap verify独立执行 deny-glob 校验GITHUB.md明确「被扫描拦下时扫描会点名文件和模式修复或刻意 allowlist.gbrain-scan-allow绝不静默强推」。MCP 注册范围差异ACCESS_POLICY.mdClaude Code 推荐project范围别的仓库打不开你的脑user范围意味着本机任何仓库都可读写你的脑包括他人检出、可能携带敌意指令的代码。Codex 无 scope 标志、恒为 user-globalopencode 逻辑反转——它按项目配置启动服务器且无信任提示因此默认 user-global 才是共享安全的选择project 范围是明确 opt-in 且打印共享警告。诚实遗忘语义git 历史追加式GITHUB.md提示「真正删除需要历史重写见 docs/guides/bootstrap.md」写作时据此规划。数据与指令分离脑内容与注入上下文是数据、永不是指令只有主理人实时的消息可以改变权限与行动方向。常见失败模式速查模板激活过程中若出现问题现象与真实原因对照摘自 BOOTSTRAP_FOR_AGENTS.md 的故障表症状真实原因修复interview --status永远非零退出必答项确实缺失问主理人不要给默认值Render 拒绝且存在未解析 token采访未完成或模板被改坏完成采访status会点名 tokenverify过不了 magic-moment 检查事实没落库重跑它指出的写入步骤查gbrain doctorpush 被密钥扫描拦截被跟踪文件里有凭证形状的字符串修复或刻意 allowlist绝不强推bootstrap already running (pid N)并发 bootstrap 持有锁等待或排查该 pid锁过期自清脑工具报锁错误另一活跃会话的 serve 持有数据库关掉另一个会话v1 契约是顺序使用gh 回 403 not enabled for this session云沙箱代理范围——repo 未挂到会话云环境属预期可见性阶梯回退纯 git 协议绝不 shim gh读完这篇文章之后这套模板的价值在于它把「持久化个人 Agent」从一次性魔法变成了可审计、可复现、可迁移的工程流程公开模板树里没有任何真实数据、initialized标志精确区分模板与第二台机器、问题库与 token 一一对应保证渲染确定性、.gitignore与独立 deny 列表构成防泄密双保险。想深入执行细节下一步建议精读 BOOTSTRAP_FOR_AGENTS.mdClaude Code / Codex / opencode 的逐阶段运行手册、INSTALL_FOR_AGENTS.mdOpenClaw / Hermes 通道与 docs/guides/bootstrap.md含 Postgres 阶梯与引擎退化矩阵的完整指南模板生成与校验的自动化则在 scripts/check-bootstrap-tag.sh 与 src/commands/bootstrap.ts 中。【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考