gbrain 脑库文件归档规则（Repo Architecture）：以主题为中心的文件归档决策协议

• 人工智能
• RAG
• Agent 记忆
• MCP 服务
• 知识管理

导读

repo-architecture是 gbrain 技能体系中专门回答"这份新内容该归档到哪里"的技能：无论是从 PDF、邮件、会议记录还是原始数据导入中产生的脑库页面（brain page），它都强制按**内容的首要主题（primary subject）**决定归档目录，而不是按文件格式或来源。读完本文，你将掌握 gbrain 脑库的完整归档决策树、sources/目录的边界与特许例外、反向链接（back-linking）与引用（citation）铁律，以及从技能契约到src/core/filing-audit.ts源码级的自动化校验机制。

一、技能定位：脑库写作技能的公共参考

repo-architecture技能的完整定义位于 plugin/skills/repo-architecture/SKILL.md（与 skills/repo-architecture/SKILL.md 内容一致），它在技能清单 skills/manifest.json 中被描述为"Where new brain files go. Filing rules and directory conventions"（新脑库文件去哪：归档规则与目录约定），并被定位为所有脑库写作技能的参考基准。

该技能的前置元数据定义了它的触发场景与运行方式：

name: repo-architecture version: 1.0.0 description: | Where new brain files go. Decision protocol for filing brain pages by primary subject, not by format or source. Reference for all brain-writing skills. triggers: - "where does this go" - "filing rules" - "create new page" - "which directory" tools: - search - get_page - list_pages mutating: false

注意mutating: false：该技能本身不写脑库页面，它只做分类建议，因此不会触发 src/core/filing-audit.ts 中对writes_pages: true技能的归档目录审计。

从路由角度看，skills/RESOLVER.md 将触发词 "Where does a new file go? / Filing rules" 映射到本技能；而更贴近"脑库分类学家"语义的触发词（"where does this brain page go"、"taxonomy check"、"refile brain page"）则路由到 skills/brain-taxonomist/SKILL.md —— 后者是写时归档门（filing gate），repo-architecture则在其"Integration with Other Skills"一节被明确记录为"delegates the filing decision to this skill"（将归档决策委托给 brain-taxonomist）。

二、核心契约（Contract）

该技能承诺保证以下三条，这是所有脑库写入方（ingest、meeting-ingestion、idea-ingest、capture 等）都必须遵守的底线：

1. 每个新页面按首要主题归档，而不是按格式（"它是 PDF 所以进 sources/"）或按来源（"它来自邮件所以进 sources/"）；
2. 歧义情况必须走决策协议，而不是随机猜测；
3. 常见错误归档模式会被识别并拦截（即下文"反模式"）。

三、归档决策协议（Phases / Decision Tree）

技能的四个阶段完整如下：

1. 识别首要主题（Identify the primary subject）：问自己——"如果未来要再找到这个页面，你会用什么关键词搜索？"
2. 走决策树（Walk the decision tree）：
   • 关于某个人 →people/{name-slug}.md
   • 关于某家公司 →companies/{name-slug}.md
   • 可复用的概念/框架 →concepts/{slug}.md
   • 原创想法 →originals/{slug}.md
   • 一场会议 →meetings/{slug}.md
   • 媒体内容 →media/{type}/{slug}.md
   • 原始数据导入 →sources/{slug}.md
3. 交叉链接（Cross-link）：从相关目录反向链接到本页面；
4. 可注明性检查（Check notability）：见 skills/conventions/quality.md 的 notability gate。

这套简化的七分支决策树，在 skills/_brain-filing-rules.json 中被扩展为更完整的机器可读规则集（下文第五节详述），包括：people/、companies/、deals/、meetings/、concepts/、projects/、analysis/、civic/、writing/、guides/、tech/、finance/、personal/、ideas/、research/、originals/、voice-notes/、openclaw/、daily/、media/、conversations/，以及特殊目录sources/。

四、输出格式：Advisory（建议而非执行）

技能规定，输出必须是一种建议性陈述，明确给出归档目标与理由：

Advisory: "File this at{type}/{slug}.mdbecause the primary subject is {reason}."

例如：

File this atcompanies/acme-corp.mdbecause the primary subject is a company (Acme Corp), not the PDF it came from.

这条建议由 brain-taxonomist 实现为更结构化的推荐块（见 skills/brain-taxonomist/SKILL.md），包含 File at / Reasoning / Matched page_type / Active pack / Source 五个字段；当歧义时，通过skills/ask-user/向用户呈现 2 个候选，绝不静默替用户做决定。

五、完整归档规则库：_brain-filing-rules.md详解

技能正文引用 skills/_brain-filing-rules.md 作为完整规则源，这份文件对所有写入脑库的技能都是**强制（MANDATORY）**的。其核心规则只有一句话：

内容的 PRIMARY SUBJECT 决定它归档到哪里。不是格式，不是来源，也不是正在运行的技能。

5.1 决策协议（Decision Protocol）

1. 识别首要主题（一个人？公司？概念？政策议题？）；
2. 归档到与主题匹配的目录；
3. 从相关目录交叉链接；
4. 拿不准时：问自己"以后会用什么关键词再找到这个页面？"

5.2sources/的真正用途

sources/只用于：

• 批量数据导入（API 转储、CSV 导出、快照）；
• 喂给多个脑库页面的原始数据（如访客导出、联系人同步）；
• 周期性捕获（季度快照、同步导出）。

如果内容有一个明确的主题（人、公司、概念、政策议题），它就绝不属于sources/。

5.3 可注明性门槛（Notability Gate）

不是所有内容都值得建脑库页面。在创建新实体页面前必须检查：

• 人物：你以后还会与其互动吗？与你的工作相关吗？
• 公司：与你的工作或兴趣相关吗？
• 概念：这是未来值得引用的可复用心智模型吗？
• 拿不准就不建：缺失的页面以后可以补建；而垃圾页面会浪费注意力并降低搜索质量。

skills/conventions/quality.md 给出了同样的门槛判定，并补充了一个现实例子："一个只有 400 粉丝、只发过一条推文的人不足以建页"。

5.4 反向链接铁律（Iron Law: Back-Linking）

每一条提及了"已有脑库页面的人或公司"的记录，都必须在被提及实体的页面上创建反向链接——这是双向的：新页面链接到实体，实体的页面也要链接回来。

反向链接格式（追加到 Timeline 或 See Also）：

- **YYYY-MM-DD** | Referenced in page title -- brief context

规则的最后一句话是："An unlinked mention is a broken brain. The graph is the intelligence."（未链接的提及就是断裂的大脑，图谱即智能。）skills/conventions/quality.md 以同样措辞强制了这一要求。

5.5 引用要求（Citation Requirements）

写入脑库页面的每个事实都必须携带内联[Source: ...]引用，三种格式：

• 直接归因：[Source: User, {context}, YYYY-MM-DD]
• API/外部：[Source: {provider}, YYYY-MM-DD]或[Source: {publication}, {URL}]
• 综合：[Source: compiled from {list of sources}]

来源优先级（高到低）：① 用户的直接陈述（最高权威）→ ② 已编译事实（既有脑库综合）→ ③ 时间线条目（原始证据）→ ④ 外部来源（API 增强、网络搜索，最低）。当来源冲突时，同时标注双方引用，不得静默二选一。

5.6 原始来源保存（Raw Source Preservation）

每条被摄取的内容都应保留原始来源以保证溯源（provenance），按大小自动路由（通过gbrain files upload-raw实现）：

• < 100 MB 的文本/PDF：留在脑库 git 仓库中，以.raw/边车目录与脑库页面并列存放；
• >= 100 MB 或媒体文件（视频、音频、图片）：上传到云存储（Supabase Storage、S3 等），在脑库仓库中留下.redirect.yaml指针；>= 100 MB 的文件使用 TUS 断点续传（6 MB 分块 + 重试）。

上传命令：

gbrain files upload-raw <file> --page <page-slug> --type <type>

返回 JSON：小文件为{storage: "git"}，云存储为{storage: "supabase", storagePath, reference}。

.redirect.yaml指针格式：

target: supabase://brain-files/page-slug/filename.mp4 bucket: brain-files storage_path: page-slug/filename.mp4 size: 524288000 size_human: 500 MB hash: sha256:abc123... mime: video/mp4 uploaded: 2026-04-11T... type: transcript

访问已存储文件：

gbrain files signed-url <storage-path> # 生成 1 小时有效期的签名 URL gbrain files restore <dir> # 下载回本地

这样任何派生脑库页面都能追溯回原始来源，且大文件不会撑爆 git 仓库。

六、常见错误归档模式（Anti-Patterns）

技能正文明确列出的反模式：

• 按格式归档（"它是 PDF，所以进 sources/"）；
• 按来源归档（"它来自邮件，所以进 sources/"）；
• 不先检查是否已存在就创建页面；
• 把sources/用于原始数据转储之外的任何内容。

skills/_brain-filing-rules.md 将反模式扩展为一张对照表，每条都给出"错 → 对 → 原因"：

七、特许例外：综合输出 sui generis（synthesis output）

"按首要主题归档"是原始摄取（raw ingest）的规则。对于一对一、单源且面向特定读者的综合输出（如个性化书籍镜像 book-mirror、绑定到单一问题的战略阅读 playbook），按主题归档会丢失"这就是那本书"的维度，按作者归档又会混淆作者页与综合页。因此media/<format>/<slug>格式前缀路径是特许例外：

• media/books/<slug>-personalized.md（book-mirror 输出）
• media/articles/<slug>-personalized.md（长文个性化）

media/<format>/用于原始摄取仍然是反模式；例外很窄：综合的、一对一的、单源 sui generis 输出。

八、Dream-cycle 综合/模式目录（v0.23 起）

gbrain dream的synthesize与patterns阶段只能写入固定允许清单（allow-list），该清单由 skills/_brain-filing-rules.json 的dream_synthesize_paths.globs数组定义。编辑该 JSON 是添加综合子代理可写目录的唯一方式：

综合输出的六条铁律：① 逐字引用用户，引号只用于可精确复现的片段（dream.synthesize.quote_verify默认开启，写入后以零 LLM 的机械化校验重查每个引用片段）；② 强制交叉引用，每个新页面必须链接到既有脑库内容；③ slug 纪律——仅小写字母数字与连字符、斜杠分隔，禁止下划线与扩展名；④ 编辑过的转录必须产生新 slug（内容哈希后缀变化），绝不静默覆盖旧反思；⑤ 保留具体事实（数字、日期、金额、姓名、谁决定什么），不做例行后勤记录；⑥ 每条论断都要有来源依据，推测必须标注为推测。

九、Takes 归属规则（v0.32+）

当写入<!--- gbrain:takes:begin -->栅栏时，holder 列记录的是"谁相信这条论断"，而不是"这条论断关于谁"。跨模态评测对 10 万条生产 takes 的归属打分仅为 6.5/10，holder/subject 混淆是第一错误源。完整规则见 docs/takes-vs-facts.md，六条契约如下：

1. Holder ≠ Subject：此人是否说过或明确暗示过？是 →holder = people/<slug>；否（是你对 TA 的分析）→holder = brain。例如 "Garry 有英雄/救赎者模式" →holder=brain（是对 Garry 的分析，不是 Garry 自己说的）；
2. 原子化论断：复合行拆成多行，每行一条论断；
3. 转发 ≠ 背书：仅转发信号上限weight 0.55；
4. 自述 ≠ 已验证："Saif 自报 7 位数收入" →holder=people/saif,weight=0.75，而非holder=world/1.0；
5. 不要虚假精度：只用 0.05 步进（0.35、0.55、0.75），引擎层插入时会四舍五入到该网格；
6. "So what" 测试：跳过元数据式琐事（Twitter 账号、粉丝数、显而易见的个人资料字段），一条 take 必须对未来某个查询有承载价值。

Holder 合法格式（v0.32 起为解析器警告，v0.33+ 为错误）：world（共识事实，无个人声称者）、brain（AI 推断，holder 确实模糊）、people/<slug>（个人陈述的信念）、companies/<slug>（机构事实，无个人声称者）。Slug 使用标准文法[a-z0-9._-]+，Garry、people/Garry-Tan、world/garry-tan均校验失败。另有创始人描述自家公司规则：创始人说"我们能到 $10M ARR" →holder=people/bo-lu，而不是holder=companies/clipboard-health——公司不说话，员工才说话。

十、机器可读规则与源码级校验

10.1_brain-filing-rules.json：规则的单一事实来源

skills/_brain-filing-rules.json 是机器可读的规范化归档规则（companion 字段指向人类可读的 .md 版），其头部注明：This JSON is what gbrain check-resolvable audits against（这是gbrain check-resolvable审计的依据）。除rules[]数组（每种 kind 对应 directory、examples、description）与sources_dir约束外，它还承载了上一节的dream_synthesize_paths允许清单——注意其描述：synthesize 阶段读取该清单并作为allowed_slug_prefixes线程传给每个子代理，put_page 在服务端强制执行。

10.2filing-audit.ts：技能清单层面的确定性审计

src/core/filing-audit.ts 是技能化检查清单（skillify checklist）第 6 项的实现。它对每个声明writes_pages: true的技能做声明级审计：

1. 技能必须在 frontmatter 声明非空的writes_to: [dir, ...]；
2. writes_to:中的每个目录必须是 skills/_brain-filing-rules.json 中的合法归档目标（sources/被显式放行，因为批量数据捕获是合法归档目标）。

其源码注释特别区分了两个易混字段：mutating: true表示"有副作用"（cron、配置、报告写入等任何副作用），而writes_pages: true表示"向语义目录写脑库页面"——cron/配置/报告类技能只设mutating: true而不设writes_pages: true，从而正确豁免于归档审计噪音（对应设计决策 D-CX-7）。

审计逻辑（runFilingAudit）对skillsDir下每个含SKILL.md的子目录：解析 frontmatter → 过滤出writes_pages: true的技能 → 检查writes_to缺失（filing_missing_writes_to）或目录不在allowedDirectories集合内（filing_unknown_directory），两者均为 warning 级并给出可执行的修复建议（修改SKILL.md的writes_to或在 JSON 的rules[]中新增目录）。目录归一化函数normalizeDir将people、people/、/people、/people/统一为people/以便比较。

10.3 与相邻技能的协作边界

• skills/brain-taxonomist/SKILL.md：写时归档门。它没有硬编码目录表，每个决策都通过gbrain schema show --json读取当前激活的 schema pack（gbrain-recommended或用户自定义 pack），这比repo-architecture的固定决策树更进一步——支持多脑用户（Persona B）通过--source <id>获得按源不同的归档建议；
• skills/eiirp/SKILL.md："Everything In Its Right Place"——工作会话结束后的 7 阶段总整理器，其中 Phase 2 TAXONOMY 对清单中每个输出调用 brain-taxonomist；
• skills/_AGENT_README.md：代理调用技能时的契约——若技能 frontmatter 声明writes_pages:/writes_to:，必须查阅 skills/_brain-filing-rules.md 确认文件路径是被认可的。

十一、实战流程示例：一次完整的归档决策

假设你刚通过邮件收到一份某家公司的季度研究分析，需要决定归档位置：

1. 识别首要主题：主题是那家公司（分析对象），不是邮件，也不是 PDF；
2. 走决策树："关于某家公司" →companies/，而不是"来自邮件" →sources/或"是 PDF" →media/；
3. 归档：companies/acme-corp.md，frontmatter 携带匹配的type:，正文每个事实带[Source: ...]引用；
4. 交叉链接：新页面链接到相关概念页、人物页，同时在companies/acme-corp.md的时间线追加反向链接条目（- **YYYY-MM-DD** | Referenced in 研究分析 -- 季度研究）；
5. 保留原始来源：邮件里的 PDF 若 < 100 MB 留在.raw/边车目录，否则走gbrain files upload-raw上云并留.redirect.yaml指针；
6. 可注明性检查：这家公司与你工作相关吗？若只是偶然出现的一次性实体，遵守"拿不准就不建"。

结语

repo-architecture看似只有一页决策树，背后却是一套完整的分层归档治理体系：技能正文提供面向所有写作技能的简短决策协议，skills/_brain-filing-rules.md 承载人类可读的完整规则（反向链接、引用、原始来源、综合例外、dream-cycle 路径、takes 归属），skills/_brain-filing-rules.json 提供机器可读的规范事实源，而 src/core/filing-audit.ts 在技能声明层面自动拦截不合规的writes_to目录。三者共同保证 gbrain 脑库"按主题、可追溯、可链接"的图结构不被混乱归档侵蚀——这正是"图谱即智能"的工程化落点。

• 人工智能
• RAG
• Agent 记忆
• MCP 服务
• 知识管理