authoring-brain-pages

能力目标

让 Agent 把一份工作场景的知识建成一个结构合规的 brain：每个页面按 Compiled Truth（当前最准结论、可重写）+ --- + Timeline（append-only 证据流）双区结构写好，批量 import 入库，并能在有新证据时正确地演进知识（改结论、加证据、提交、同步）而不丢历史。

前置

• brain 是一个目录，页面按 people/ companies/ meetings/ concepts/ 分子目录放置；页面类型由 frontmatter type: 声明。
• 「markdown 是真相源、git 是审计轨迹、DB 是二者的物化视图」——所有改动先落 markdown、经 git commit 留痕、再由 sync 回放进 DB。
• gbrain 命令用 timeout -k 5 30 gbrain ... 包裹（exit 124 正常）；读输出用 > /tmp/out.txt 2>&1; cat，不要 pipe。

实操流程

1. 建目录骨架：

   BRAIN_DIR="/path/to/your-brain"
   mkdir -p "$BRAIN_DIR/people" "$BRAIN_DIR/companies" "$BRAIN_DIR/meetings" "$BRAIN_DIR/concepts"
   

2. 按双区结构写页面。每个页面 = frontmatter → # Compiled Truth → --- → # Timeline。frontmatter 绝不写 slug: 字段（见陷阱）：

   cat > "$BRAIN_DIR/people/alice-chen.md" << 'EOF'
   ---
   type: person
   aliases: ["Alice", "@alice_chen"]
   ---
   # Compiled Truth
   Founder of [[companies/acme-ai|founded]]. Previously [[companies/google-brain|works_at]] staff engineer.
   
   ## Open Threads
   - Prepare for Series A outreach
   
   ---
   
   # Timeline
   - <YYYY-MM-DD> | Meeting — discussed compiler IR design with Bob and Carol
   - <YYYY-MM-DD> | X — replied to dev-tools thread
   EOF
   

   结构要点：Compiled Truth 存当前最准结论（可整段重写）；中部只含 --- 的一行（前后空行）是双区分隔符，识别它的就是 markdown 水平线；Timeline 每条 日期 | 来源类型 | 描述、只追加不改写。wikilink 写完整路径形式 [[companies/acme-ai|founded]]、竖线后是关系类型，不写短 slug。

3. git init + 首次 commit（sync 依赖 git 历史，从一开始就跟踪）：

   cd "$BRAIN_DIR" && git init && git add . \
     && git commit -m "initial brain pages"
   # 若在 macOS 外置 exFAT 卷上，过滤 AppleDouble 元数据文件再计数
   find "$BRAIN_DIR" -name "*.md" ! -name "._*" | wc -l
   

4. import 入库。先用 --no-embed 只看结构是否完整（省 embedding quota、先确认 page/chunk/link 正确再决定是否向量化）：

   timeout -k 5 120 gbrain import "$BRAIN_DIR/" --no-embed > /tmp/import.txt 2>&1
   cat /tmp/import.txt
   timeout -k 5 30 gbrain stats
   

   gbrain stats 的 Links: 0 是预期——import 阶段不提取 wikilink，要到 sync 才建 typed-link。

5. 演进知识：新证据到达时，Compiled Truth 重写 + Timeline 追加两处都改。例如某人从 Founder 改任 CEO：

   sed -i '' 's/^Founder of /CEO of /' "$BRAIN_DIR/people/alice-chen.md"          # 重写上半区
   echo "- <YYYY-MM-DD> | Email — confirmed title update: now CEO" \
     >> "$BRAIN_DIR/people/alice-chen.md"                                          # 追加下半区
   git -C "$BRAIN_DIR" diff people/alice-chen.md
   

   diff 应呈现「Compiled Truth 一删一加（重写）+ Timeline 纯 +（追加）」。只改一处都不合规：只改 Compiled Truth 丢了证据，只改 Timeline 让结论仍显示旧值。

6. 回流 DB：必须 commit 后再 sync。sync 基于 git commit hash 范围（last_sync_commit..HEAD）做增量，未 commit 的改动 sync 视为「已是最新」、相当于未发生：

   git -C "$BRAIN_DIR" add -A && git -C "$BRAIN_DIR" commit -m "alice-chen Founder→CEO"
   timeout -k 5 60 gbrain sync > /tmp/sync.txt 2>&1
   cat /tmp/sync.txt
   

   sync 成功输出含 Synced <hash>..<hash>: ~1 modified、Extracted: N links（此刻才提取 typed wikilink）、Embedded: N page。

校验回路

• gbrain stats 的 Pages 数 = 写入的 page 数、skipped 为 0（skipped > 0 多半是 frontmatter 残留 slug: 字段）。By type 分布符合预期。
• gbrain get people/alice-chen 返回完整页面：frontmatter + Compiled Truth + --- + Timeline 四段齐全（get 也会 exit 124、内容已写入文件，正常）。
• 演进后再 gbrain get，Compiled Truth 显示新结论、Timeline 累积新条目、--- 仍在原位。
• sync 输出的 Extracted: N links 说明 typed wikilink 被正确识别。

常见陷阱

• frontmatter 写了 slug: → import 静默跳过整页：GBrain 从「文件相对 brain 根目录的路径去掉 .md」派生 slug（people/alice-chen.md → people/alice-chen）；frontmatter 若声明短 slug（如 slug: alice-chen）与派生值不一致，import 不报错、只在统计里 +1 skipped。修复：删掉所有 slug: 行 find "$BRAIN_DIR" -name "*.md" ! -name "._*" | xargs sed -i '' '/^slug:/d'，重 commit + 重 import。
• 改了 markdown 但 sync 说 Already up to date：没 commit。保存即同步在这里不成立，必须提交即同步——git add && git commit 后重跑 sync。
• 把 Timeline 当 Compiled Truth 用：每来一条事实就往 Compiled Truth 追加，页面很快被噪声淹没；反过来直接编辑 Timeline 历史条目则丢掉审计能力。双区职责必须分离。
• macOS 外置 exFAT 卷的 ._* 幽灵文件：find / wc / grep 会把 AppleDouble 元数据算进去让计数翻倍，所有遍历命令加 ! -name "._*" 过滤。
• title 字段是 import 自动派生的：从文件名转 Title Case 写进 pages 表 frontmatter JSONB 列，写入时不必手写。frontmatter 只放与 schema 对齐的 metadata、不塞业务字段。