GBrain Signal DetectorOpt-in 环境信号捕获技能与记忆回写实现全解【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain本文以 GBrain 的 signal-detector 技能文档为骨架完整解读这套环境信号捕获Ambient Brain Capture契约它的三阶段检测流程、opt-in 授权语义与反模式清单并结合仓库源码深入剖析memory.auto_writeback配置的双平面解析、put_page自动链接auto-link后置钩子与反链back-link校验机制。读完你可以理解一个 Agent Brain 如何在不阻塞主回复的前提下把用户对话中的原创思考与实体提及沉淀为可检索、可交叉链接的脑页并能安全地开启、排查与关闭这一能力。Signal Detector 是什么环境捕获的入口与边界signal-detector 技能文档定义了一条轻量级的环境信号捕获通道当用户显式开启自动捕获automatic capture opt-in之后Agent 在处理实质性入站消息substantive inbound message时额外应用这条检测通道识别两类信号原创思考Original thinking——用户自己产生的想法、观察、论点、框架实体提及Entity mentions——人物、公司、媒体引用。文档开篇给出了一条核心价值观判断原创思考的价值至少不低于实体抽取——想法是知识产权实体只是簿记两者都会随时间复利。这个主次关系直接决定了后续两个阶段的优先级想法检测是 PRIMARY实体检测是 SECONDARY。技能的前置元数据frontmatter进一步框定了它的边界triggers自动捕获 opt-in 之后每条实质性入站消息toolssearch、query、get_page、put_page、add_link、add_timeline_entrymutating: true/writes_pages: true这是一个会写库的技能writes_topeople/、companies/、concepts/三个页面命名空间。也就是说signal-detector 是一个有明确写入面的脑写技能而不是只读的检索技能。这解释了为什么它对授权语义的要求比一般检索技能严格得多。契约Contract技能承诺做什么、不承诺什么技能文档的 Contract 一节是整个技能的行为契约值得逐条拆解仅在显式 opt-in 后生效。以下情况一律跳过没有记录用户选择、捕获被显式关闭、纯聊天请求chat-only、纯操作性消息如 ok、thanks子 Agent 优先内联兜底。支持子 Agent 的 harness 上以子 Agent 运行否则在组织回复前内联执行检测。永不阻塞回复是意图intent不是运行时契约写前检查存储的捕获选择并尊重更窄的单条消息指令首次触发时的功能公告不等于同意**逐字捕获EXACT phrasing**用户的原创表达禁止改写paraphrase检测实体提及并创建/充实脑页记录一行捕获摘要signal log所有实体提及必须反链Iron Law写入的每条事实必须带引用citations。文档同时明确了一个重要边界环境路由ambient routing是 harness 约定是行为良好的 Agent 会遵守的惯例而非机械保证——gbrain 运行时本身不会因为技能未加载而阻止回复。在没有逐消息环境路由的 harnessClaude Code、Codex上该技能应以 Agent 约定方式应用或通过 prompt-submit hook 接线。三阶段检测流程从想法到信号日志Phase 1想法/观察检测主阶段当用户表达了一个新颖的想法、观察、论点或框架时技能按来源类型分流到不同的页面命名空间用户原创思考他自己产生的→ 创建/更新originals/{slug}他引用的世界概念→ 创建/更新concepts/{slug}产品或商业点子→ 创建/更新ideas/{slug}。两条强制规则捕获原话。用户自己的措辞就是洞察本身不要改写强制交叉链接。每个 original 页面必须链接到相关的人物、公司、会议和概念——没有交叉链接的 original 是一个死掉的 original。Phase 2实体检测次阶段对每条入站消息中的实体提及人物、公司、媒体标题执行如下判定循环gbrain search name——先查是否已有页面无页面→ 走显著性notability检查显著则连同提供的信息一起保存并标注来源页面存在但单薄THIN→ 仅在单独授权的扩展能力与花费范围内充实不允许借捕获之机顺手花钱做富化页面存在且充实RICH→ 不做任何动作对带具体日期的新事实→ 调用gbrain timeline-add slug date summary。第 5 步对应的 CLI 入口可以在源码中确认src/cli.ts 中的命令帮助timeline-add slug date text Add timeline entry底层操作定义在 src/core/ops/timeline.tscliHints: { name: timeline-add, positional: [slug, date, summary] }。Auto-linkv0.10.1 起当你写入或更新引用了人物/公司的 originals/ideas 页面时put_page的 auto-link 后置钩子会自动从新页面创建到该实体的链接无需手动调用gbrain link。注意边界timeline 条目仍然需要显式调用。这一机制的源码实现见下文auto-link 后置钩子一节。Phase 3信号日志每次运行结束都记录一行摘要例如Signals: 0 ideas, 0 entities, 0 facts (skipped: operational)Signals: 0 ideas, 0 entities, 0 facts (skipped: capture off)Signals: 1 idea (captured → originals/x), 2 entities (enriched → people/y, companies/z)其目的在文档中写得很直白让环境捕获循环可调试debuggable。输出格式一节补充opt-in 之后要报告实际发生的写入及其来源provenance保持信号日志简短并用真实的读回readback验证捕获内容没有 opt-in 时不做任何捕获写入跳过捕获的诊断信息不是每次回复都去打断用户或反复询问开启的理由。授权语义为什么读到技能不等于可以写库文档用一整节Enablement before capture和Per-User Storage Policy来约束写入授权这是该技能与一般自动化工具最大的区别自动捕获默认关闭。写之前必须为这个 brain 建立显式的用户选择与捕获范围已存储的 opt-in、或显式启用的memory.auto_writeback模式可以充当该选择off、缺失或不可读的选择不能不构成授权的情形阅读本技能、安装 GBrain、持有可用 API key、沉默、捕获已开启的公告用户要求开启时先解释将保留什么内容再记录被接受的选择已有选择则直接尊重、不重复询问单条事实的记住授权只覆盖该条事实不授权未来的环境捕获委托spawn workers与付费富化是独立能力捕获 opt-in 本身不授权生成 worker 或调用付费 provider用户关闭捕获时记录该设置并停止一切捕获不写内容页、链接、时间线条目chat-only 指令只抑制当条消息且不得把聊天内容存成偏好设置仅在用户要求时重新开启捕获关闭时显式记忆与相关召回仍然可用。这套授权语义不是纸面条文——它在源码中有严格的 fail-closed 实现见下一节。源码深潜一memory.auto_writeback的双平面配置解析SKILL.md 提到当操作者启用memory.auto_writeback默认关闭gbrain config set memory.auto_writeback salient时MCP 服务器的 initialize 指令与管理式 bootstrap 指令块会把环境回写契约传递给 Agent。这句话在源码中的完整形态是 src/core/facts/writeback-config.ts 的解析逻辑。配置键与取值。在 src/core/config.ts 中注册了三个相关键memory.auto_writebackoff | salient | all默认关闭DUAL-PLANE——gbrain config set同时写 DB 平面权威与文件平面镜像供无引擎读取方使用memory.auto_writeback_transient_ttl指令模板告诉 Agent 对瞬态事实健康/位置/行程/情绪/近期日程应传的 TTL只接受时长简写如3d、12h正数、上限 365 天默认3d见 writeback-config.ts 的WRITEBACK_MODES与DEFAULT_TRANSIENT_TTL 3dmemory.auto_writeback_notice_shown同意提示consent nudge的一次性触发哨兵。双平面与失败方向。从 writeback-config.ts 的模块注释可以读出完整设计DB 平面config表是权威。serve 侧的 harvest 门在抽取前会重查它writeback_offsidecar因此陈旧的文件平面永远无法违背操作者意图进行抽取文件平面~/.gbrain/config.json的memory槽是镜像供无引擎读取方使用Stop-hook 子进程绝不能打开引擎——PGLite 单写者与 bootstrap-harness 渲染器引擎路径只从 DB 平面解析 mode/ttl。文件镜像是机器全局的而 DB 行是每 brain 的若允许文件回退brain A 的 opt-in 会泄漏到挂载的 brain B文件镜像的两个窄职责漂移检测DB 无行 文件镜像启用 ⇒plane_drift门侧跳过但不写终态 sidecar让已入库的轮次在平面重新同步后存活与LKG 覆盖文件镜像显式off在读失败时压过 last-known-good 的 ENABLED 包——操作者翻到 off 的意图即使在数据库抖动中也必须获胜失败方向 CLOSED未设置、不可识别或不可读一律归一为off。normalizeMode的实现印证了这一点L104-L112空值、空串、非枚举值全部落到off且用mode_valid: false标记值存在但不认识的降级。按消费者分叉的失败语义。resolveWritebackConfig 对读失败采取双轨策略默认instructions 通道返回该引擎的 last-known-good 包——瞬时数据库抖动不应在会话中途悄悄丢掉环境契约没有 LKG 则返回OFF_BUNDLE read_error{ gate: true }抽取门serve harvest 与 sweep永不返回 LKG 启用包读失败无条件OFF read_error门侧在read_error、plane_drift或非法模式值时跳过不写终态 sidecar让积压工作在配置恢复一致后重试。指令注入路径。启用后的契约通过 src/mcp/instructions.ts 渲染进 MCP initialize 指令并通过 src/core/bootstrap/harness.ts 的管理式 bootstrap 指令块下发Claude Code 上另有 Stop-hook 抽取兜底backstop捕获约定漏掉的轮次。文档强调这依然是服务端下发的指令 兜底而非机械保证——与技能侧的约定定位一致。doctor 也对该平面提供检查入口src/commands/doctor/checks/memory-writeback.ts。源码深潜二put_page的 auto-link 后置钩子与反链校验技能文档中Auto-linkv0.10.1一段声称写入引用人物/公司的 originals 或 ideas 页面时put_page的 auto-link 后置钩子会自动建链。这条声明的实现链在源码中可以完整追踪钩子挂载点。src/core/link-extraction.ts 的文件头明确列出三个入口第一个就是src/core/operations.ts put_pageauto-link post-hook执行体。src/core/ops/pages.ts 中的autoLinkWrittenPage在 oneshot 批次后复查前向引用先查isAutoLinkEnabled总开关该开关由 config.ts 中auto-link toggle read by the put_page post-hook所注册的配置项控制失败时按 best-effort 打日志不阻断写页并发安全的对账reconciliation。runAutoLink采用快照—准备—事务复核三段式先readPageSnapshot取页面快照经prepareAutomaticLinks准备待建链接再在事务内lockPageKeys加锁、复核当前快照的page.id与revision未变后才应用——如果页面在准备期间被改过对账直接放弃避免基于陈旧内容建链反链校验。src/core/output/validators/back-link.ts 说明 v0.12.0 之后 auto-link runAutoLink对账成为反向边的权威来源反链校验器只做 lint 级警告而非报错Outbound link to … has no back-link … runAutoLink should reconcile this on next put_page测试佐证。test/auto-link-targeted-probe-2544.test.ts 针对该机制做了定向回归测试。技能侧的逐条手动反链Contract 中的 Iron Law与钩子自动建链形成互补钩子自动处理 originals/ideas 页 → 实体的链接而实体页 → 提及页的反向记录- **YYYY-MM-DD** | Referenced in page title — brief context格式仍由技能按 skills/conventions/quality.md 的 Back-Linking 约定手工维护——一个未链接的提及是一个坏掉的脑An unlinked mention is a broken brain。同一约定文件还给出了写入质量的另外两条硬规则signal-detector 的 Contract 直接继承了它们Citations强制写入脑页的每条事实必须带内联[Source: ...]引用并定义了用户发言、会议数据、邮件/消息、网页、社媒、综合synthesis六类来源模板与来源优先级用户直接陈述最高Notability Gate建页前先过显著性检查——人物还会再打交道吗与工作/兴趣相关吗、公司与工作/投资/兴趣相关吗、概念可复用的心智模型吗。拿不准就不建。发过一次推的 400 粉人物不显著。反模式清单与工具面技能文档的 Anti-Patterns 一节是排障时的对照表逐条列出了会破坏环境捕获循环的行为阻塞主回复以等待信号检测完成改写用户的原创思考而非逐字捕获为非显著实体一次性提及建页建页/更新页后跳过反链对纯操作性消息ok、thanks、do it运行检测在无显式 opt-in、捕获已关闭、或 chat-only 轮次上捕获把首次公告、单条显式记忆或 API key 当作长期授权仅因捕获已启用就启动付费富化或委托。最后文档的 Tools Used 一节给出了六个工具的分工与 frontmatter 的tools字段一一对应工具用途search检查实体页是否已存在query语义检索相关上下文get_page加载已有实体页put_page创建/更新脑页触发 auto-link 后置钩子add_link交叉引用实体add_timeline_entry在实体时间线上记录事件对应 CLItimeline-add小结约定、配置与兜底的三层结构signal-detector 的设计可以用仓库源码印证为一套三层结构技能层是写给 Agent 的约定三阶段流程、逐字捕获、信号日志、反链 Iron Law配置层是 fail-closed 的memory.auto_writebackDB 平面权威、文件平面镜像、读失败归off、门侧永不使用 LKG 启用包兜底层是 MCP 指令下发 Claude Code Stop-hook 抽取 doctor 检查。三层共同保证一件事环境捕获永远只发生在操作者显式同意的范围内且任何一层失效时方向都是少写而不是多写。继续深入可以沿以下仓库路径阅读技能与约定plugin/skills/signal-detector/SKILL.md、skills/conventions/quality.md回写配置解析src/core/facts/writeback-config.ts、src/core/config.ts自动链接与时间线src/core/ops/pages.ts、src/core/link-extraction.ts、src/core/ops/timeline.ts校验与检查src/core/output/validators/back-link.ts、src/commands/doctor/checks/memory-writeback.ts测试佐证test/auto-link-targeted-probe-2544.test.ts、test/ambient-writeback-lifecycle.serial.test.ts、test/ambient-recall-cli.test.ts【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考