building-typed-link-graph

能力目标

让 Agent 把一份含 wikilink 互引的 brain 自动建成一张带类型的知识图谱——每条页面间关系被推断为 founded / invested_in / advises / works_at / mentions / attended 之一，写入 links 表——并能用 graph-query 做多跳遍历、用 backlinks 做反向查询，同时会在数据设计层规避 per-edge context 的类型污染。

前置

• brain 页面已写好且含 wikilink（写法与 import 见 authoring-brain-pages）。bare 形式 [[companies/acme-ai]] 的类型由 cascade 推断（默认 mentions，meeting 页面默认 attended）；typed 形式 [[companies/acme-ai|founded]] 竖线后是 display，cascade 仍在该位置取 context 感知 verb 关键词。
• typed-link 的类型不是 LLM 抽的，是 6 条手写正则按固定优先级匹配 context 里的 verb 关键词，每页 < 50ms、零 token、结果确定。
• gbrain 命令用 timeout -k 5 30 gbrain ... 包裹（长命令如 import 用 -k 5 300，exit 124 正常），读输出用 > /tmp/out.txt 2>&1; cat。

实操流程

1. import 页面（建基础 link）：

   BRAIN_DIR="/path/to/your-brain"
   timeout -k 5 300 gbrain import "$BRAIN_DIR/" > /tmp/import.txt 2>&1; cat /tmp/import.txt
   

2. 触发完整 verb-based cascade——用 gbrain put，不要依赖 gbrain extract ... --source db。extract --source db 在已有 link 的页面上因 content-hash 短路直接返回 0 links（对未改动页面无差量）；--source fs 走的是按目录粗判的简化路径（person→company 默认 works_at、不跑 cascade）。只有 put 从 stdin 重写页面时才调完整 inferLinkType() cascade：

   # 对需要验证 cascade 的 key page 逐个 put
   timeout -k 5 30 gbrain put people/alice-chen < "$BRAIN_DIR/people/alice-chen.md"
   # 批量（数据量大时只对 key page 跑）
   for slug in $(find "$BRAIN_DIR/" -name "*.md" ! -name "._*" | sed "s|$BRAIN_DIR/||; s|\.md$||"); do
     timeout -k 5 30 gbrain put "$slug" < "$BRAIN_DIR/$slug.md"
   done
   timeout -k 5 30 gbrain stats   # 看 Links 计数
   

3. 查一个实体的邻居图谱（outgoing 方向、看它连到谁）：

   timeout -k 5 30 gbrain graph-query people/alice-chen --depth 1 > /tmp/g1.txt 2>&1; cat /tmp/g1.txt
   timeout -k 5 30 gbrain graph-query people/alice-chen --depth 2 > /tmp/g2.txt 2>&1; cat /tmp/g2.txt
   

   输出 ASCII 树 --<type>-> <to-slug> (depth N)。flag：--depth N（hop 数）、--type T（只看某类型）、--direction in|out|both（默认 out）。depth 2 能看到「通过中间节点发现的间接关系」，是知识图谱相对向量检索的结构性优势。

4. 反向查询（incoming 方向、看谁指向某实体），返回结构化 JSON、适合喂给下游程序：

   timeout -k 5 30 gbrain backlinks companies/acme-ai > /tmp/bl.txt 2>&1; cat /tmp/bl.txt
   

   每条 entry 含 from_slug / to_slug / link_type / context（240 字符窗口节选）/ link_source（markdown=body wikilink，frontmatter=显式声明）。同一条 (from,to,type) 记录既能 graph-query from outgoing 取到、也能 backlinks to incoming 取到。

5. 验证 meeting 页面的 ATTENDED 特殊路径：type: meeting 的页面，其内所有 wikilink（bare 或 typed）在 cascade 之前就 early-return attended、不进 5 主 cascade——无需在 markdown 里写 |attended：

   timeout -k 5 30 gbrain graph-query meetings/roadmap-sync --depth 1
   # meeting 页面的 bare wikilink 自动 emit attended
   

校验回路

• gbrain stats 的 Links 达到预期量级（wikilink 数量级）；By type 页面分布正确。
• graph-query --depth 1 输出的每条边类型与页面 context 里的 verb 关键词对得上：含 founded 关键词的位置 emit founded、含 advises emit advises。
• backlinks <slug> 返回 JSON 数组、每条 entry 的 5 个核心字段（from_slug / to_slug / link_type / context / link_source）齐全。
• meeting 页面的 bare wikilink 在 graph-query 里显示为 --attended->。

常见陷阱

• extract --source db 返回 0 links 误以为建图没生效：这是 content-hash 短路的预期行为，基础 link 已在 import 阶段建好。真正跑 verb cascade 要用 gbrain put。
• per-edge context 240 字符窗口的类型污染：每条 typed-link 单独取当前位置左右各 120 字符作 context，相邻位置的 verb 会互相污染。典型现象：Worked on [[concepts/inference-optimization|mentions]] before founding acme-ai 里的 founding 落进 inference-optimization 的 context 窗口，使它被 emit 成 founded 而非 mentions。这不是 bug，是 cascade 给更宽 context 的代价。规避靠数据设计：让不同类型的 entity ref 用独立 section 隔离（如把过往关系拆到独立 ## Past Work 小节），使 context 窗口无交集。
• cascade 优先级是固定的 if 顺序：FOUNDED > INVESTED_IN > ADVISES > WORKS_AT > MENTIONS，第一个匹配的 verb 赢，从最强语义到最弱语义降级，无 verb 命中兜底 mentions。同一页面不同 target 因 context 独立而可拿不同类型。
• 反向 founded / 自环边：depth-2 遍历里会出现 acme-ai --founded-> alice-chen 这类反向边、以及指向自己的 self-reference 边——link 是单向有方向的（from→to），同一对实体可同时存在两个方向、类型各由自己页面的 context 决定，属正常行为。
• 什么时候升级到 LLM：关系类型可枚举、verb 收敛（企业知识库、日志解析、配置匹配）用 regex cascade；关系开放、需语义理解（开放域 NER、意图分类）才升级 LLM；混合场景两层串行——先 cascade 抽稳的、剩下的未识别 wikilink 再交 LLM。