Phase 2.5: Structured Graph Updates (auto-link)

Phase 2.5: Structured Graph Updates (auto-link)【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrainAuto-link reconciliation extracts entity references from a page and writes them to the graph (linkstable) with inferred relationship types; stale links (refs no longer in the page text) are removed. WHO runs it depends on the write path:Trusted local writes(gbrain put,gbrain capture,gbrain call put_page) auto-link inline and returnauto_links: { created, removed, errors }.MCP callers (stdio AND HTTP)returnauto_links: { skipped: remote, hint }andauto_timeline: { skipped: remote }. Body wikilinks are saved as text; edges are reconciled asynchronously by the serves maintenance sweep (at startup and on 10-minute idle ticks), or on demand withgbrain sweep --once/gbrain extract links --source db. Useadd_linkfor relationships you need immediately. Untrusted body text can plant ranking-boosting edges, which is why the inline path is local-only.Inferred link types:attended(meeting - person),works_at,invested_in,founded,advises,source(frontmatter),mentions(default).To disable:gbrain config set auto_link false. Default is on.Timeline entries with specific dates still need explicitgbrain timeline-add(or batch viagbrain extract timeline --source db).**同时更新 Iron Law 小节。** 如果你的分叉仍写着无任何限定的 Back-links maintained on every brain write (Iron Law)请追加 markdown **v0.12.0 update:** Auto-link satisfies the Iron Law for entity-reference links on every put_page (inline for trusted local writes; for MCP writes, once the serve maintenance sweep runs). The agents Iron Law obligation is now: include the entity reference in the page content (e.g., Alice); auto-link handles the structured row. Manual add_link calls are reserved for relationships you cant express in markdown content.底层实现佐证auto-link 如何工作从源码看auto-link 由 src/core/link-extraction.ts 提供纯函数式抽取工具模块头注释明确其被三处消费src/commands/extract.ts 的批量 DB/FS 抽取、src/commands/backlinks.ts 的旧式文件系统扫描、以及src/core/operations.ts的put_pageauto-link post-hook这些函数不访问数据库只把页面内容转成候选边由调用方通过 engine 方法持久化。值得注意的实现细节链接类型由确定性正则启发式推断零 LLM 调用。inferLinkType的优先级为founded invested_in advises works_at role prior mentionsmeeting 类型页面里对人物的引用推断为attended其余默认落到mentions。这正是文档中带类型推断的底层来源。冲突键包含link_type(from_page_id, to_page_id, link_type)UNIQUE 约束让回填幂等同时注释也提醒重跑会在一行已带类型如works_at的边旁边新增一条mentions插入采用ON CONFLICT DO NOTHING且不清理旧边——语义整理是维护者单独决策。该文件还维护LINK_EXTRACTOR_VERSION_TS水印当前为2026-09-09T00:00:00Zgbrain extract --stale会据此判定过期页面并重新抽取是links_extraction_lagdoctor 检查的基础。局部写入路径不处理远程边是刻意的安全设计不受信任的正文文本可能植入提升排名的边因此内联路径仅限本地。2.meeting-ingestion/SKILL.md消除按参会者手工gbrain link位置一追加到### Phase 3: Attendee enrichment末尾。原因消除对每个参会者重复的gbrain link调用当会议页把参会者引用为Name时auto-link 会处理它们。**Note (v0.12.0):** Once the meeting page is written via gbrain put, the auto-link post-hook automatically creates attended links from the meeting to each attendee whose page is referenced as Name. You dont need to call gbrain link for attendees. You DO still need gbrain timeline-add for dated events (auto-link only handles links, not timeline entries).位置二在### Phase 4: Entity propagation中将 Back-link from entity page to meeting page 这一行替换为4. Entity references in the meeting page body auto-create the link via auto-link. For incoming references on the entity page (entity page → meeting page), edit the entity page to mention the meeting and put_page it — auto-link handles the rest.3.signal-detector/SKILL.md原始页/想法页的自动连线位置追加到### Phase 2: Entity Detection末尾。原因与 brain-ops 同理——消除在写入引用人物或公司的 originals/ideas 页面后手工gbrain link。**Auto-link (v0.12.0):** When you write/update an originals or ideas page that references a person or company, the auto-link post-hook on put_page automatically creates the link from the new page to that entity. You dont need to call gbrain link manually. Timeline entries still need explicit calls.4.enrich/SKILL.md把 Step 7 改为内容交叉引用语义位置用下面的代码块替换### Step 7: Cross-reference。原因有了 auto-link相关实体页之间的建链是自动的。Step 7 关注的是内容更新而非建链。旧版删除### Step 7: Cross-reference - Update company pages from person enrichment (and vice versa) - Update related project/deal pages if relevant context surfaced - Check index files if the brain uses them - Add back-links manually via gbrain link for any new entity references新版粘贴### Step 7: Cross-reference - Update company pages from person enrichment (and vice versa) - Update related project/deal pages if relevant context surfaced - Check index files if the brain uses them **Note (v0.12.0):** Links between brain pages are auto-created on every put_page call (auto-link post-hook). Step 7 focuses on content cross-references (updating related pages compiled truth with new signal from this enrichment), not on creating links. On a trusted local write the put_page response carries auto_links: { created, removed, errors }; MCP writes (stdio and HTTP) return auto_links: { skipped: remote, hint } instead — edges are reconciled by the serve maintenance sweep or gbrain sweep --once, and add_link covers an edge you need immediately. Timeline entries still need explicit gbrain timeline-add calls.四个 diff 全部应用之后升级每个分叉文件顶部的版本横幅# Based on gbrain v0.12.0 skills/skill-name, extended with your-agent-specific config运行 v0.12.0 回填为已有 brain 填充图数据gbrain post-upgradepost-upgrade会自动调用apply-migrations --yes运行v0_12_0编排器schema → 配置检查 →extract links --source db→extract timeline --source db→ verify。幂等无待办时开销极小。其编排器实现位于 src/commands/migrations/v0_12_0.ts各阶段均可安全重跑配置检查会尊重auto_link配置用户显式设为false则跳过回填阶段。完整参考见 skills/migrations/v0.12.0.md。验证 auto-link 生效让 Agent 写一个引用Some Person的测试页确认 put_page 响应包含auto_links: { created: 1, removed: 0, errors: 0 }。本地 CLI 写入MCP 写入返回auto_links: { skipped: remote }——先跑gbrain sweep --once再用gbrain graph-query检查边。验证图遍历可用gbrain graph-query people/some-well-connected-person --depth 2应返回一棵带类型边的缩进树。v0.12.2 热修复数据正确性无技能改动v0.12.2 是 Postgres 数据正确性热修复。分叉技能文件无需任何改动技能契约不变但必须跑迁移并且有一条 markdown 解析行为需要知晓。1. 运行迁移Postgres 存储的 braingbrain upgradev0_12_2编排器自动运行gbrain repair-jsonb重写jsonb_typeof string的行涉及pages.frontmatter、raw_data.data、ingest_log.pages_updated、files.metadata、page_versions.frontmatter。幂等可安全重跑PGLite brain 干净地 no-op。升级后验证gbrain repair-jsonb --dry-run --json # 期望 totalRepaired: 02. 恢复被截断的 wiki 文章如果你的 brain 在 v0.12.2 之前导入过 wiki 风格 markdown部分页面曾被静默截断正文中任何独立的---都被当作 timeline 分隔符。从源头重新导入gbrain sync --fullsplitBody会重建正确的compiled_truth。3. splitBody 契约splitBody要求显式的 timeline 哨兵。可识别标记按优先级!-- timeline --首选——serializeMarkdown输出的正是它--- timeline ---装饰分隔线## Timeline/## History标题正上方的---向后兼容正文中的裸---是 markdown 水平线不是 timeline 分隔符。如果 Agent 用裸---写页面请迁移到!-- timeline --——serializeMarkdown助手会输出它。4. wiki 子类型自动判定inferType把五种目录模式识别为独立页面类型而非concept路径模式类型/wiki/analysis/analysis/wiki/guides/guide/wiki/hardware/hardware/wiki/architecture/architecture/writing/writing如果你的技能或查询按typeconcept过滤并期望该桶内包含 wiki 内容请更新过滤条件纳入这些类型。v0.13.0 — Frontmatter 关系索引结论大部分技能无需任何操作。v0.13 把 YAML frontmatter 字段投影为图中的类型化边。写入 API 不变——继续按今天的方式用 frontmatter 调用put_page即可图会在后台自动填充。三个技能可选新增一个阶段用于消费新的auto_links.unresolved响应字段。不消费时无法解析的 frontmatter 名称会静默跳过。1.meeting-ingestion/SKILL.md可选位置在 Phase 3: Write Meeting Page 之后新增一节。### Phase 3.5: Check for unresolved attendees (v0.13) After put_page, inspect response.auto_links.unresolved — an array of frontmatter references that did not resolve to existing pages. For meetings, this usually means attendees you havent created a person page for yet. If unresolved.length 0: - Option 1 (create pages now): trigger an enrichment pass to build the missing people pages. - Option 2 (defer): log the unresolved names to the enrichment queue for later. - Option 3 (accept the gap): the attendee edge will not be created until a page exists. Re-running gbrain extract links --source db --include-frontmatter after creating the page fills in the missing edges.2.enrich/SKILL.md可选位置追加到 enrichment 触发清单。### Drain unresolved frontmatter names (v0.13) If any put_page response includes auto_links.unresolved entries, the enrichment tier should pick up those (field, name) pairs and try to create the missing entity pages. Example flow: 1. signal-detector captures a meeting with attendees: [Alice Known, Unknown Person] 2. put_page returns auto_links.unresolved [{field: attendees, name: Unknown Person}] 3. enrichment tier consumes Unknown Person → web search → creates people/unknown-person.md 4. The next put_page (or a backfill run) wires up the attended edge automatically3.idea-ingest/SKILL.md可选位置与 meeting-ingestion 同模式——put_page后检查auto_links.unresolved把名称路由到 enrichment。无需改动的技能brain-ops/SKILL.md—— auto-link 机制是内部的写入路径不变signal-detector/SKILL.md—— 信号捕获路径不变query/SKILL.md——traverse_graph自动返回 frontmatter 派生的边daily-task-manager、briefing、citation-fixer、media-ingest—— 不变。可在图查询中过滤的边类型frontmatter 派生的边携带以下link_type值。若你的分叉有按类型过滤的 graph-query 技能这些均可使用works_atperson → company——来自company:、companies:或key_people:foundedperson → company——来自founded:invested_ininvestor → deal/company——来自investors:或lead:led_roundlead → deal——来自lead:yc_partnerpartner → company——来自partner:attendedperson → meeting——来自attendees:discussed_insource → page——来自sources:sourcepage → source——来自source:related_topage → target——来自related:或see_also:完整的字段 → 类型 → 方向映射表见 skills/migrations/v0.13.0.md。该迁移还引入了link_source区分markdown/frontmatter/manual边与origin_page_id记录哪一页的 frontmatter 产生了这条边两列put_page上的对账只触碰本页 frontmatter 创建的边绝不干扰其他页的边。迁移时机gbrain upgrade在 46K 页规模的 brain 上耗时 2-5 分钟一次性通过gbrain post-upgrade在进程外执行。如果你的 Agent 在升级期间持有 DB 连接升级后重连即可否则保持服务。类型名归一化抽取器输出attended和mentions。如果你的分叉图查询还在按旧拼写attendee或mention过滤请放宽为两者都匹配以便两种命名下写入的行都能被返回。v0.14.0 shell 任务可选采用无技能改动新增 Minionsshell任务类型让确定性 cron 脚本API 抓取、token 刷新、抓取写入离开 LLM 网关。每次触发零 token 消耗在典型规模下约释放 60% 的网关 CPU 余量。默认关闭未选择启用的安装完全不受影响。采用方式见 skills/migrations/v0.14.0.md要点用gbrain jobs work --allow-shell-jobs启动 worker等价于在 worker 进程导出GBRAIN_ALLOW_SHELL_JOBS1注意 worker 目录下的.env不能设置它Postgres。PGLite 上每条 crontab 调用都用--follow做内联执行无持久 worker。逐一给宿主机的 cron 条目分类需要 LLM 的留在网关vs 确定性的shell 候选。典型拆分确定性 → shellycli-token-refresh、x-oauth2-refresh、x-garrytan-unified、calendar-sync-to-brain、github-pulse、frameio-scan、flight-tracker、x-raw-json-backfill。需要 LLM → 保留social-radar、content-ideas、adversary-vacuum、ea-inbox-sweep、morning-briefing、brain-maintenance。每个确定性 cron 重写为3 13,16,19,22,1,4,7,10 * * * \ gbrain jobs submit shell \ --params {cmd:node scripts/your-script.mjs,cwd:/data/.openclaw/workspace} \ --max-attempts 3 --timeout-ms 300000每次触发后用gbrain jobs get id观察 exit_code / stdout_tail / stderr_tail与迁移前行为对比后再批准下一批。无需技能改动。handler 在 worker 侧运行技能文件不变宿主通过插件契约暴露的自定义 handler 也原样工作。铁律绝不自动重写运维人员的 crontab。每次重写都是逐 cron、人工批准、带 diff 的。gbrain 不附带任何 crontab 重写助手每次重写都是手动的。v0.16.0持久化 Agent 运行时gbrain 提供gbrain agent run/gbrain agent logs、Minions 的subagenthandler 类型以及宿主仓库 subagent 定义的插件契约。现有技能无需手术。下游 Agent 要回答的问题是如何采用这一运行时而非如何修补破坏性变更。1. 用 Anthropic 密钥运行 workersubagent与subagent_aggregatorhandler 在 worker 上总是注册的无单独 opt-in 标志——ANTHROPIC_API_KEY是天然的成本闸门无密钥则 SDK 调用在第一轮即失败且谁可提交已受保护PROTECTED_JOB_NAMES trusted-submitMCP 调用者得到permission_denied只有gbrain agent run能插入这些行。ANTHROPIC_API_KEYsk-ant-... gbrain jobs workworker 启动时打印[minion worker] subagent handlers enabled。2. 把 subagent 作为插件发布OpenClaw 及同类把自定义 subagent 定义从 gbrain 分叉移入你自己的仓库作为插件~/your-agent/gbrain-plugin/ ├── gbrain.plugin.json └── subagents/ ├── meeting-ingestion.md ├── signal-detector.md └── daily-task-prep.mdgbrain.plugin.json{ name: your-openclaw, version: 2026.4.20, plugin_version: gbrain-plugin-v1 }每个subagents/*.md都是纯文本 Agent 定义——YAML frontmatter 作为系统提示词的正文。可识别的 frontmatter 字段name、model、max_turns、allowed_tools必须是派生 brain 工具注册表的子集。启用export GBRAIN_PLUGIN_PATH$HOME/your-agent/gbrain-pluginworker 启动时每个插件打印[plugin-loader] loaded name vver (N subagents)任何拒绝坏清单、allowed_tools里的未知工具、版本不匹配都会在启动时以响亮警告出现而不是静默的分发期失败。完整契约见 docs/guides/plugin-authors.md。3. 用持久化 subagent 替换临时运行如果你的 Agent 目前为应能在崩溃、休眠或 worker 重启后存活的工作派生临时 subagentOpenClawAgent()、临时 Anthropic API 调用等迁移到gbrain agent run。持久性免费gbrain agent run analyze my last 50 journal pages for recurring themes \ --subagent-def analyzer --fanout-manifest manifests/journal-pages.json每一轮都持久化到subagent_messages每个工具调用都是两阶段账本gbrain agent logs job显示它死在哪里 最后一次成功调用返回了什么。不再有因为会话上下文蒸发而从头重跑。4. subagent 的put_page写入 Agent 命名空间如果采用 subagent 运行时注意来自 subagent 工具分发的put_page调用必须指向wiki/agents/subagent_id/...。呈现给模型的 schema 在第一次尝试时就强制这一点服务端 fail-closed 检查拒绝任何其他路径。这不影响技能文件、CLI put_page 或 MCP put_page——只影响 LLM 循环内的工具分发写入。聚合输出最终所有 N 个子代理发现了什么的 brain 页走独立的受信 CLI 路径而非 subagent 工具调用因此可以写到任何位置。铁律绝不让 Agent 获得超出其命名空间的写权限。服务端检查的存在是因为分发器 bug 时有发生把它当作纵深防御而非主要边界。v0.22.4 — frontmatter-guard 采用1. 停止手写 frontmatter 校验器如果你的分叉有直接调用js-yaml校验 brain 页 frontmatter 的脚本改用gbrain frontmatter validate。该 CLI 覆盖七类规范错误并携带跨版本稳定的--json信封。- # Custom validator script - node scripts/validate-frontmatter.mjs path gbrain frontmatter validate path --json需要在其他脚本中内嵌校验器的消费方改为从 gbrain 的markdown导出导入而不是复制逻辑import { parseMarkdown } from gbrain/markdown; const parsed parseMarkdown(content, filePath, { validate: true, expectedSlug }); for (const err of parsed.errors ?? []) { // err.code: MISSING_OPEN | MISSING_CLOSE | YAML_PARSE | SLUG_MISMATCH | // NULL_BYTES | NESTED_QUOTES | EMPTY_FRONTMARGER }2. 删除任何lib/brain-writer.mjs引用如果分叉的技能或脚本引用了理想化的lib/brain-writer.mjsgbrain 并不提供请用 gbrain CLI 替换这些引用。frontmatter-guard技能位于 skills/frontmatter-guard/SKILL.md指向gbrain frontmatter validate/audit/install-hook。从该技能的现状看audit按 source 分组输出错误码计数errors_by_code、per_sourcevalidate path --json以退出码 0/1 区分干净/有错适合 CI 或 pre-commit 场景。3. 把 doctor 子检查接入健康管线gbrain doctor自动报告frontmatter_integrity。如果你的分叉有自定义健康管线如每天发 Slack 播报 brain 健康从gbrain doctor --json拉取并展示frontmatter_integrity行的计数。4. 可选在 brain 仓库安装 pre-commit 钩子对 git 支撑的 sourcegbrain frontmatter install-hook会放置一个阻止提交格式错误 frontmatter 的 pre-commit 脚本gbrain frontmatter install-hook若 brain 不是 git 仓库或你的下游 Agent 已在写入时强制校验可跳过。完整配方见 docs/integrations/pre-commit.md。5. 迁移人机工效——读取 pending-host-work.jsonlgbrain apply-migrations --yes运行 v0.22.4 audit 后Agent 应读取~/.gbrain/migrations/pending-host-work.jsonl过滤migration 0.22.4并逐条读取command字段。每条指向一个按 source 的gbrain frontmatter validate source_path --fix命令——把计数呈现给用户获得明确同意后再运行。迁移是只审计的。apply-migrations期间它绝不改动 brain 内容修复命令由 Agent 在用户同意后执行。更晚的版本与我的分叉缺了什么v0.36.5.0 之后的版本diff 存放在 skills/migrations每个需要 Agent 侧操作的发布对应一个文件和 CHANGELOG.md。本节保留前述内容方便一次追平多个版本。检查分叉缺少什么diff (grep -A3 Based on gbrain ~/your-fork/skills/brain-ops/SKILL.md) \ (grep v[0-9] ~/gbrain/skills/migrations/ | tail -3)v0.36.5.0 — shell 任务调用gbrainCLI 的免表单密钥继承它是什么。shell 任务参数接受inherit:字段。传入任意 snake_case 配置键名worker 在子进程派生时从自己的loadConfig()解析该值并注入子进程环境。名称落行值绝不因inherit:而持久化。校验在两条提交路径CLI submit_jobop上都是入队前执行的因此畸形 payload 永远不会落进minion_jobs.data。其校验器实现在src/core/minions/handlers/shell-validate.ts迁移文件 skills/migrations/v0.36.5.0.md 明确其为新增文件。为什么需要它。没有它从 shell 任务调用gbrain的 Agent 要么把database_url以明文写进~/.gbrain/config.json要么每次任务传env: { GBRAIN_DATABASE_URL: ... }——两者都会把明文密钥留在磁盘或 DB 行里。inherit:让名称留在行内、值在派生时解析。Agent 能做什么。inherit:是自由表单的可传任意配置键{ cmd: gbrain sync --skip-failed gbrain embed --stale, cwd: /data/gbrain, inherit: [database_url, anthropic_api_key, voyage_api_key] }子进程中的环境键名由配置键大写派生database_url→GBRAIN_DATABASE_URLanthropic_api_key→ANTHROPIC_API_KEYvoyage_api_key→VOYAGE_API_KEY以此类推。校验器不限定你继承哪些配置键——Agent 与 worker 同 uid这是 Agent 自己的决定。另有原型污染防御snake_case 正则挡掉__proto__/ 前导下划线 / 大写值解析用Object.hasOwn。你仍可以用env:。inherit:不禁止env:{ 任意值 }。若有理由把某个值以明文放进行内非机密关联 token或你确定可持久化的密钥走env:。想要值不落行时优先inherit:。worker 配置每宿主机一次性gbrain config set database_url postgresql://...—— 文件平面路由写入~/.gbrain/config.json这正是 inherit 的loadConfig()解析所看的位置即使 DB 不可达也能工作。供应商 API 键anthropic_api_key、voyage_api_key等同样路由到文件平面其他配置键写入 DB 平面而loadConfig()不读 DB 平面——那些键请直接放入文件或环境或直接把键写进~/.gbrain/config.json或在 worker 进程上设置GBRAIN_DATABASE_URL/DATABASE_URL/ 各供应商环境变量若 worker 无法解析请求的名称校验器会在提交时 fail-fast并给出可直接粘贴的gbrain config set X提示而不是提交数分钟后在子进程 stderr 里出现静默的 No database URL 失败。相关检查。gbrain doctor的home_dir_in_worktree检查会在~/.gbrain/位于 git worktree 内时告警。每次saveConfig()调用以及gbrain post-upgrade都会铺下一份~/.gbrain/.gitignore单行*因此既有安装无需重跑gbrain init也能获得覆盖。诚实的边界该.gitignore覆盖的是日常git add不覆盖已跟踪文件、截图、备份或git add -f。策略框架。对于 Agent 到 gbrain 的调用规范指南是 docs/guides/agent-to-gbrain.md。两个不同面带 OAuth 的 HTTP MCP 用于有 MCP 等价物的操作search、query、put_page等shell 任务 inherit:用于localOnly管理操作sync、embed、dream、doctor等。不是回退层级——按操作选择。需要处理的错误Agent 提交 shell 任务时请把这些清晰地呈现出来错误含义Agent 动作shell: inherit must be an array of config-key namesinherit不是数组传inherit: [database_url, ...]shell: inherit entries must be non-empty strings元素为空、非字符串或 null使用 snake_case 配置键名shell: inherit name X must match [a-z][a-z0-9_]*名称未通过 snake_case 正则大写、前导下划线等逐字使用配置键——database_url而非DATABASE_URLshell: inherit requested X but worker has no X configuredworker 无法从其loadConfig()解析该名称在 worker 宿主上运行gbrain config set X value验证按迁移文件的 Verify 段# 1. 新模式在你的 worker 上可用 gbrain jobs submit shell --params \ {cmd:gbrain stats,cwd:/tmp,inherit:[database_url]} --follow # 期望页数、exit 0。 # 2. doctor 在存在风险时呈现 worktree 风险 gbrain doctor --json | grep -A1 home_dir_in_worktree # 3. 追溯 gitignore 已落地 test -f ~/.gbrain/.gitignore cat ~/.gbrain/.gitignore # 期望文件存在内容为 *\n # 4. 审计日志记录名称而非值 tail -1 ~/.gbrain/audit/shell-jobs-*.jsonl | grep -o inherit:\[[^]]*\] # 期望[database_url]无 URL 值【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考