企业官网建设流程全解析

GBrain Signal Detector：Opt-in 环境信号捕获技能与记忆回写实现全解

【免费下载链接】gbrainGarry's 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）时，额外应用这条检测通道，识别两类信号：

1. 原创思考（Original thinking）——用户自己产生的想法、观察、论点、框架；
2. 实体提及（Entity mentions）——人物、公司、媒体引用。

文档开篇给出了一条核心价值观判断：原创思考的价值至少不低于实体抽取——"想法是知识产权，实体只是簿记，两者都会随时间复利"。这个主次关系直接决定了后续两个阶段的优先级：想法检测是 PRIMARY，实体检测是 SECONDARY。

技能的前置元数据（frontmatter）进一步框定了它的边界：

• triggers：自动捕获 opt-in 之后，每条实质性入站消息；
• tools：search、query、get_page、put_page、add_link、add_timeline_entry；
• mutating: true/writes_pages: true：这是一个会写库的技能；
• writes_to：people/、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 运行时本身不会因为技能未加载而阻止回复。在没有逐消息环境路由的 harness（Claude Code、Codex）上，该技能应以 Agent 约定方式应用，或通过 prompt-submit hook 接线。

三阶段检测流程：从想法到信号日志

Phase 1：想法/观察检测（主阶段）

当用户表达了一个新颖的想法、观察、论点或框架时，技能按来源类型分流到不同的页面命名空间：

• 用户原创思考（他自己产生的）→ 创建/更新originals/{slug}；
• 他引用的世界概念→ 创建/更新concepts/{slug}；
• 产品或商业点子→ 创建/更新ideas/{slug}。

两条强制规则：

1. 捕获原话。用户自己的措辞就是洞察本身，不要改写；
2. 强制交叉链接。每个 original 页面必须链接到相关的人物、公司、会议和概念——"没有交叉链接的 original 是一个死掉的 original"。

Phase 2：实体检测（次阶段）

对每条入站消息中的实体提及（人物、公司、媒体标题），执行如下判定循环：

1. gbrain search "name"——先查是否已有页面；
2. 无页面→ 走显著性（notability）检查，显著则连同提供的信息一起保存并标注来源；
3. 页面存在但单薄（THIN）→ 仅在"单独授权的扩展能力与花费"范围内充实，不允许借捕获之机顺手花钱做富化；
4. 页面存在且充实（RICH）→ 不做任何动作；
5. 对带具体日期的新事实→ 调用gbrain timeline-add <slug> <date> "<summary>"。

第 5 步对应的 CLI 入口可以在源码中确认：src/cli.ts 中的命令帮助timeline-add <slug> <date> <text> Add timeline entry，底层操作定义在 src/core/ops/timeline.ts（cliHints: { name: 'timeline-add', positional: ['slug', 'date', 'summary'] }）。

Auto-link（v0.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_writeback：off | 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 = '3d'）；
• memory.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-link（v0.10.1）"一段声称：写入引用人物/公司的 originals 或 ideas 页面时，put_page的 auto-link 后置钩子会自动建链。这条声明的实现链在源码中可以完整追踪：

1. 钩子挂载点。src/core/link-extraction.ts 的文件头明确列出三个入口，第一个就是src/core/operations.ts put_page（auto-link post-hook）；
2. 执行体。src/core/ops/pages.ts 中的autoLinkWrittenPage在 oneshot 批次后复查前向引用，先查isAutoLinkEnabled总开关（该开关由 config.ts 中"auto-link toggle read by the put_page post-hook"所注册的配置项控制），失败时按 best-effort 打日志不阻断写页；
3. 并发安全的对账（reconciliation）。runAutoLink采用"快照—准备—事务复核"三段式：先readPageSnapshot取页面快照，经prepareAutomaticLinks准备待建链接，再在事务内lockPageKeys加锁、复核当前快照的page.id与revision未变后才应用——如果页面在准备期间被改过，对账直接放弃，避免基于陈旧内容建链；
4. 反链校验。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"；
5. 测试佐证。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字段一一对应：

小结：约定、配置与兜底的三层结构

signal-detector 的设计可以用仓库源码印证为一套三层结构：技能层是写给 Agent 的约定（三阶段流程、逐字捕获、信号日志、反链 Iron Law），配置层是 fail-closed 的memory.auto_writeback（DB 平面权威、文件平面镜像、读失败归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

【免费下载链接】gbrainGarry's Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain