gstack GBrain Sync 错误手册BRAIN_SYNC 每条报错的问题、原因与源码级修复路径【免费下载链接】gstackUse Garry Tans exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA项目地址: https://gitcode.com/GitHub_Trending/gs/gstackgstack 的 GBrain sync 会把~/.gstack/下的一份精选记忆learnings、plans、designs、retros推送到私有 git 仓库实现跨机器的记忆同步。由于同步链路涉及队列、git 认证、密钥扫描和 egress 收据等多层机制失败形态也比较多。本文以仓库内的 docs/gbrain-sync-errors.md 为骨架逐条覆盖每条报错的 Problem / Cause / Fix并对照 bin/gstack-brain-sync、bin/gstack-brain-restore、bin/gstack-artifacts-init、lib/egress-receipt.ts 等源码说明每条报错实际由哪段逻辑触发、修复命令背后的状态文件是什么方便你在排障时直接定位。如何检索错误信息docs/gbrain-sync-errors.md 本身就是一个错误索引按BRAIN_SYNC:前缀冒号后的关键字或命令输出中的二进制名来检索。需要说明两点检索前提并非所有消息都带BRAIN_SYNC:前缀。密钥扫描与 push 失败由gstack-brain-sync打印并保留BRAIN_SYNC:前缀见 bin/gstack-brain-sync 与 bin/gstack-brain-sync而 egress 收据失败以gstack: brain-sync push NOT sent开头init/restore 失败则以各自的命令名开头。跨机器的“检测到远端仓库”提示在当前源码的 preamblebin/gstack-skill-start中已打印为ARTIFACTS_SYNC: artifacts repo detected: url并附带run gstack-brain-restore的指引文档中记录的BRAIN_SYNC: brain repo detected: url是该提示的历史前缀。两者指的是同一事件检索时都可能出现。排查任何同步问题时先运行gstack-brain-sync --status它输出最近一次状态JSON 格式的~/.gstack/.brain-sync-status.json由 write_status 写入、队列深度、最近一次成功 push 的时间和当前隐私模式。状态码包括idle空队列、ok推送成功、blocked密钥扫描命中、push_failed含EGRESS_RECEIPT_FAILED等失败细节。错误一BRAIN_SYNC: brain repo detected: url问题。这台机器上存在~/.gstack-artifacts-remote.txt或其从别的机器拷贝来的旧名~/.gstack-brain-remote.txt但本地~/.gstack/.git还不存在。原因。你在另一台机器上已经配置过 GBrain syncgstack-artifacts-init会把远端 URL 写到该 txt 文件而这台机器的 gstack 状态尚未恢复。修复。gstack-brain-restore它会克隆仓库到暂存目录、校验仓库形状、把被跟踪文件拷入~/.gstack/、把.git挪到位并重新注册合并驱动器源码见 bin/gstack-brain-restore。如果不希望在这台机器上恢复可以用配置键永久忽略提示gstack-config set artifacts_sync_mode_prompted true该键在 bin/gstack-config 中有默认值false另外注意当前 preamble 的检测分支只在“URL 文件存在 且~/.gstack/.git缺失 且artifacts_sync_mode为off”三者同时成立时才打印这条提示bin/gstack-skill-start其提示文案也提供了另一种永久关闭方式gstack-config set artifacts_sync_mode off。错误二BRAIN_SYNC: blocked: pattern-family:snippet问题。密钥扫描器在某个已暂存文件里发现了凭证形态的内容同步中止队列被完整保留什么都没被 push。原因。提交前的密钥模式之一命中了文件内容——通常是 AWS key、GitHub token、OpenAI key、PEM 块、JWT 或嵌在 JSON 里的 bearer token。源码证据。扫描器是 secret_scan_stdin它对git diff --cached的增量内容逐模式匹配命中时输出family:snippetsnippet 截断到 30 字符。六个模式族分别是模式族正则覆盖aws-access-keyAKIA 16 位大写字母数字github-tokenghp_/gho_/ghu_/ghs_/ghr_前缀或github_pat_openai-keysk-前缀pem-block-----BEGIN ... -----jwteyJ...三段式bearer-token-jsonJSON 中authorization/api_key/apikey/token/secret/password字段后的 16 位以上值可选Bearer/Basic/Token前缀命中后的处理路径在 bin/gstack-brain-syncgit reset HEAD -- .撤销暂存、写blocked状态、把BRAIN_SYNC: blocked: ...打到 stderr 并退出 0——所以 skill 本身不会崩溃只是这一轮同步跳过。修复三选一。确属真实密钥编辑该文件删掉密钥然后重新运行任意 skill 触发重试。误报例如你的 learnings 里本来就包含一段想发布的 GitHub token 示例字符串gstack-brain-sync --skip-file path该命令把路径追加进~/.gstack/.brain-skip.txt去重见 subcmd_skip_file永久排除此路径未来的 writer 不再入队它已入队的记录在下一轮 drain 时被丢弃归类为dropped.skipped。放弃整批同步推倒重来gstack-brain-sync --drop-queue --yes清空 spool 队列~/.gstack/.brain-queue.d/下每个记录一个文件以及遗留的单文件队列不做任何提交后续的写入会正常重新填充队列subcmd_drop_queue。另外gstack-brain-restore和 init 都会往~/.gstack/.git/hooks/pre-commit装一个同源模式的钩子bin/gstack-brain-restore所以即使你绕过 skill 手动git commit这个仓库同样的扫描也会拦住。错误三BRAIN_SYNC: push failed: auth.问题。git push 被拒原因是你对远端的认证过期或缺失。原因。当前凭据下远端不可达token 过期、SSH key 未配置、账号被移除等。源码证据。push 失败后脚本先检查错误文本是否匹配auth|permission|403|401|forbiddenbin/gstack-brain-sync命中则跳过重试按 origin URL 给出针对性提示——remote_auth_hint 对github.com/github.*建议gh auth status必要时gh auth refresh对gitlab建议glab auth status其余建议检查git remote -v与凭据助手。修复。按你的远端刷新认证GitHubgh auth status需要时gh auth refreshGitLabglab auth status其他git remote -v检查 SSH key 或 credential helper修复后运行任意 skill 即可自动重试——注意被 auth 卡住的 push 并不会丢数据本地 commit 仍然存在且脚本开头有一个“未推送 commit 检测器”bin/gstack-brain-sync会在后续边界以至少 10 分钟节流自动重推前提是未推送的 commit 全部由gstack-brain-sync自己创建。错误四BRAIN_SYNC: push failed: first-line-of-error问题。非 auth 原因的 push 失败冒号后面是 git 错误输出的第一行。原因。可能是网络问题、被拒的 push远端领先比如另一台机器先推了、服务器 500、或仓库权限被回收。源码证据。失败处理链在 bin/gstack-brain-sync先尝试一次 fetch merge --no-edit origin/branch再重推JSONL 文件有专门的jsonl-append合并驱动器、markdown 用 union 合并见 bin/gstack-brain-restore 注册的 git config仍失败才落到这条状态。每次 fetch/重推也都是“收据先行、失败即拒”的 egress 操作。修复。看~/.gstack/.brain-sync-status.json里的完整消息或者手动执行cd ~/.gstack git status git push origin HEAD以查看 git 的完整报错。队列在任何 push 尝试后都会清空记录移交给本地 commit本地 commit 仍然在下一次 skill 运行会重试 push。错误五gstack: brain-sync push NOT sent — the egress receipt could not be written问题。push 在离开本机之前就被拒绝了。每次 brain-sync push 在发送前都会向 egress ledger~/.gstack/security/egress.jsonl写一条防篡改收据这是 fail-closed 的收据写不进去就什么都不发送、不做本地 commit、队列完整保留下次运行整体重试。gstack-brain-sync --status会把失败细节标为EGRESS_RECEIPT_FAILED。原因。~/.gstack/security/不可写收据写入器会在目录缺失时创建它所以单纯缺失不是原因、磁盘满、或GSTACK_HOME指向了只读位置。源码证据。这条消息来自 bash 侧的拒发打印函数 _gstack_egress_refusal被拒的调用点在 bin/gstack-brain-sync——收据先于 commit 写入写失败就 exit 1队列原样保留。收据本体的实现在 lib/egress-receipt.tsledger 路径为home/security/egress.jsonl文件权限强制 0600egressLedgerPath、appendChained每条记录带prev字段上一行原始内容的 sha256第一行为空串形成哈希链verifyLedger会重算全链verifyLedger收据是内容无关的content-free只记录 sink、host、payload class、字节数与 sha256git 场景下 sha256 为 nullgit 进程持有字节所有字段长度上限 512 字节、尾部读取窗口 4KB保证哈希链永远能完整取到上一行lib/egress-receipt.ts。修复。mkdir -p ~/.gstack/security chmod -R uw ~/.gstack/security然后运行任意 skill或gstack-brain-sync --once重试。之后可以用gstack-egress list查看 ledger 内容、gstack-egress verify校验哈希链bin/gstack-egressverify检测到篡改时以退出码 3 结束注意它检测的是就地编辑、重排和链中删除不检测尾部截断或整个文件被删——这是文档明确声明的威胁模型边界。错误六gstack-artifacts-init: ~/.gstack/ is already a git repo pointing at: url问题。你试图用一个与现有远端不一致的 URL 执行 init命令拒绝覆盖。原因。你之前已经用另一个远端跑过gstack-artifacts-init。源码证据。冲突判断在 bin/gstack-artifacts-init它把两边 URL 各自规范化为 HTTPS 形式后再比较存的远端通常是 SSH 形态输入通常是 HTTPS 形态规范化后同库不同写法不会误报冲突确属不同仓库才打印本错误并给出git -C ~/.gstack remote set-url origin url的建议。修复二选一。沿用现有远端不带--remote运行gstack-artifacts-init或传入匹配的 URL切换远端git -C ~/.gstack remote set-url origin url命令自己的建议或先gstack-brain-uninstall再用新 URL 重新 init。两种方式都不会删除你的数据。错误七Remote not reachable via SSH: url问题。init 阶段无法连通 git 远端来验证可达性。原因。URL 拼写错误、缺少认证、或网络问题。修复。手动测试git ls-remote url如果失败依次检查URL 拼写GitHub 的gh auth statusGitLab 的glab auth status私有网络 / VPN / DNS。错误八Failed to create or find name. Try --remote url.问题。通过gh repo create自动建仓失败且gh repo view也找不到该仓库。原因。gh未认证、同名仓库已属于他人、或账号触达配额限制。源码证据。这条消息在 GitHub 路径bin/gstack-artifacts-init和 GitLab 路径bin/gstack-artifacts-init各打印一次repo create失败后先回退尝试repo view取 URL仓库可能早已存在拿不到 URL 才报此错。修复。gh auth status未认证就gh auth login。若是仓库名冲突换一个名字gstack-artifacts-init --remote gitgithub.com:YOURUSER/custom-name.git--remote显式给定时会跳过整个自动建仓流程见 bin/gstack-artifacts-init 的参数解析。错误九gstack-brain-restore: ~/.gstack/.git already points at url问题。你试图从一个与现有 git 配置不一致的 URL 恢复。原因。之前用别的远端 init 过留下了过期的.git。源码证据。安全门在 bin/gstack-brain-restore~/.gstack/.git已存在且 origin 与新 URL 不一致时直接拒绝防止覆盖。修复。先gstack-brain-uninstall再重新执行gstack-brain-restore url。如果.git已存在且远端匹配restore 会退化为 fetch fast-forward见 bin/gstack-brain-restore。错误十gstack-brain-restore: ~/.gstack/ has existing allowlisted files that would be clobbered问题。你要执行 restore但~/.gstack/里已经有会被覆盖的 learnings 或 plans。原因。两种可能(a) 这台机器在开启 sync 之前就积累了本地状态(b) 一次失败的 restore 留下了部分状态。源码证据。restore 用 Python 遍历~/.gstack/把本地文件与远端.brain-allowlist的 glob 逐一匹配列出最多 5 个冲突路径bin/gstack-brain-restore。修复三选一。这台机器的状态应该成为新真相改用gstack-artifacts-init而不是 restore——它会以本机状态为基础创建一个全新的 brain 仓库想采用远端、丢弃本机状态先备份~/.gstack/projects/删除冲突文件后重跑 restore想合并没有自动合并。手动把~/.gstack/里的 learnings 拷到一台已开启 sync 的机器上运行中的 gstack再回来执行 restore。错误十一gstack-brain-restore: url does not look like a gstack-brain repo问题。克隆成功了但仓库缺少.brain-allowlist和.gitattributes。原因。你把 restore 指向了一个普通 git 仓库或者有人把 brain 仓库里的规范配置删掉了。源码证据。形状校验在 bin/gstack-brain-restore两个文件缺一不可否则拒绝继续。修复。核实 URL。若 URL 正确运行gstack-artifacts-init --remote url重新播种规范配置。不是报错但常见明明该同步却什么都没同步文档专门把这种“无错误信息”的静默状态列为一个 gotcha排查顺序如下gstack-brain-sync --status—— 模式是否为offoff时 sync_active 直接返回假--once是静默 no-op。~/.gstack/.git是否存在gstack-config get artifacts_sync_mode—— 应为full或artifacts-only。你期望同步的文件是否在 allowlist 内cat ~/.gstack/.brain-allowlist隐私类别过滤——若模式是artifacts-only行为类文件timelines、developer-profile被刻意跳过。以上都没问题再强制排干一次gstack-brain-sync --discover-new gstack-brain-sync --once--discover-new按 allowlist 遍历~/.gstack/用mtime:size游标~/.gstack/.brain-discover-cursor发现变更并入队subcmd_discover_new--once走完整 drain迁移遗留队列 → 快照 spool → 分类skip/allowlist/隐私模式/存在性四道过滤见 compute_paths_to_stage→ 暂存 → 密钥扫描 → egress 收据 → commit → push。值得注意的两个静默点分类阶段如果隐私地图文件损坏脚本会“持有一切、什么都不暂存”宁可不同步也不猜测会打一条 warning空队列是常态--once在空队列时直接写idle状态退出正常耗时小于 1 秒。附录状态文件速查排障时高频用到的~/.gstack/下状态文件前缀均可被GSTACK_HOME环境变量覆盖文件作用.brain-sync-status.json最近一次 drain 的状态idle/ok/blocked/push_failed 消息--status直接读它.brain-queue.d/同步队列 spool每记录一个epoch-pid-uniq.json文件quarantine/子目录存放不可解析的记录.brain-allowlist允许同步的 glob 白名单凭据、机器态、question-preferences 等一律不在其中.brain-skip.txt--skip-file写入的永久排除路径.brain-privacy-map.json文件 →artifact/behavioral类别映射供隐私模式过滤.brain-last-push/.brain-last-pull最近成功 push / 每日 pull 的时间戳pull 节流 24 小时.brain-worktree-last-advancegbrain 索引 worktree 的每日推进节流戳security/egress.jsonlegress 收据 ledger0600哈希链gstack-egress list/verify查看这些机制的设计背景白名单而非黑名单、skill 边界同步而非守护进程、JSONL 合并驱动器、一次性隐私询问门可继续参阅 docs/gbrain-sync.md收据链路的完整单元测试见 test/egress-receipt.test.ts 与 test/egress-receipt-wiring.test.ts后者固定了哪些 sink 必须写收据。【免费下载链接】gstackUse Garry Tans exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA项目地址: https://gitcode.com/GitHub_Trending/gs/gstack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考