brain-ingest-gate

Brain Ingest Gate — 在任何内容进入 Brain 前先解析并去重

**约定：**参见 conventions/brain-first.md — 查找链（gbrain entity → search → query → get）与此门禁在每次写入前运行的 查找链相同。

**约定：**参见 _brain-filing-rules.md — 当门禁的判定为“写入”时，由主要主题决定目录。

约定：skills/conventions/quality.md 负责跨页面规则 （引用、Iron Law 反向链接、显著性）——门禁允许通过的每个页面都必须遵循这些规则。 门禁特有的区别：门禁只决定写入／链接／跳过；准入的技能在写入时应用质量规则。

规则

任何内容进入 Brain 前都必须通过此门禁。直接将内容 cp 或 mv 到 Brain 仓库属于错误。

一条洞见，只放一处。如果内容已经存在，就链接到它——不要克隆。 写入任何新页面之前（文件迁移、批量导入、手动执行 gbrain put、子 Agent 输出），按顺序执行两项检查：

1. 命名实体解析门禁 — 这是关于某个已有页面的命名实体吗？
2. 去重门禁 — Brain 是否已经在某处记录了这条洞见？

**范围说明：**此门禁是一项路由约定——当符合导入特征的意图出现时，运行框架会将其解析到上下文中，行为良好的 Agent 会遵循它。如果技能没有加载，gbrain 运行时不会通过机制阻止未补充上下文或重复写入。

为什么 gbrain 需要此门禁

原生管道不会替你进行语义去重：

• gbrain import / gbrain sync 只会跳过 frontmatter ID 相同的内容。 不同 slug 或 ID 下的相同内容会被重复索引——每个重复项都会成为第二条搜索结果，与规范页面竞争。
• gbrain capture 的去重依据是 24 小时内精确匹配的内容哈希——它能捕捉相同字节的重复采集，不会捕捉改写后的相同洞见。
• remember 动词去重的是事实，而不是页面。

语义去重和命名实体解析完全由此技能负责。

此门禁何时触发

1. 文件迁移 — 将工作区中已有的文件移入 Brain 仓库（“将这个移到 Brain”）。
2. 批量导入 — 任何形式的批量内容移入 Brain 目录，都必须在 gbrain sync 或 gbrain import 建立索引前执行。对于批次，还需阅读 conventions/test-before-bulk.md： 先对 3-5 个项目执行门禁并检查判定，再处理其余项目。
3. 手动写入 — 对丰富内容执行 gbrain put 或 gbrain capture，或直接将文件写入 Brain 仓库。
4. 子 Agent 输出 — 后台 Agent 将笔记或页面写入 Brain。

此门禁负责什么，以及委托什么

此技能是一个门禁，不是管道。它负责以下写入前检查。 “写入”判定之后的所有步骤都委托给已提供的技能——不要在此重述或内联这些步骤：

事项	委托给
路由新的外部内容（会议、文章、媒体）	ingest
检测传入内容中的实体并判断显著性	signal-detector
创建／更新人物和公司页面、分层投入、反向链接	enrich
概念页面、分层、集群综合	concept-synthesis
强制执行反向链接（Iron Law）	conventions/quality.md
页面所属目录	_brain-filing-rules.md

命名实体解析关卡（最先运行）

只要内容涉及一个有名称的项目、地点、公司、人物，或任何有人“想要构建／创立／制作”的事物，就会触发。

不能仅凭向量相似度来识别有名称的重复项：以选定名称存储的页面，不会与某人碰巧用来描述它的通用英文短语形成接近的嵌入。典型的失败情况是：搜索一个描述性短语时，规范名称页面的得分低于正文阈值，于是一个重复的占位页面覆盖了已有多年的页面。内容按命名含义存储，却尝试通过字面上的通用短语检索。

规则

1. 先查注册表，而不是通用短语。 gbrain 的原生注册表就是实体入口：

   gbrain entity "<name>"        # zero-LLM card: page, aka list, near-miss suggestions
   

   命中卡片就表示页面已存在——停止操作，添加链接，不要克隆。若未命中（或对于概念类名词），则继续运行 gbrain query "<name>" --limit 3。如果知识库还维护着明确的命名计划索引（例如 concepts/ 下的页面），在断定一切都是新的之前，先阅读该索引。

2. 搜索前先扩展别名。 命名页面应包含 aliases: frontmatter 列表（通用标签 + 选定名称 + 任意昵称 + 标志性短语）。逐一搜索每个别名和通用标签，而不只是用户碰巧说出的短语。

3. 向量得分是正文的阈值，绝不是命名实体的关卡。 只要有任何合理的命名匹配，就打开并阅读候选页面（gbrain get <slug>），再判断它是否不存在。对于命名页面，即使得分低到足以让正文明确判为未命中，它仍可能是正确答案。

4. 出现新的命名实体时，在同一次写入中加入其别名。 创建页面时提供完整的 aliases: 列表，让所有未来的同义表达都能通过 gbrain entity 解析。一个 frontmatter 列表即可覆盖今后的所有说法——O(1)，而不是针对每个实例单独提醒。

为什么要设关卡，而不是记忆提醒

记忆提醒（“查询真实名称，而不是通用短语”）只是针对单个实例的便笺：只有当它恰好在当轮处于热上下文中时才有效，无法推广到下一个命名实体，而且会逐渐失效。这项技能会在摄取类任务路由到此处时加载。流程规则应放在触发式关卡中，而不是热记忆里。

去重关卡（第二步运行）

在编写任何新页面之前（对于命名实体，先运行上述解析关卡并以其结果为准）：

1. 提取核心主张——用 1–2 句话概括新内容的新意。

2. 搜索相关内容：

   gbrain search "<core claim>" --limit 5
   

3. 打开并阅读排名最高的结果（gbrain get <slug>）。绝不能仅凭得分判断。供体系统会为此步骤发布余弦相似度阈值——不要照搬：gbrain search 返回的是融合混合排名分数，而不是余弦相似度，且不存在可跨系统映射的数值阈值。判断依据是阅读内容，而不是数字。

4. 划分档位：

   档位	含义	操作
   明确重复	排名最高的结果已针对同一主题陈述了相同见解	停止。链接到现有页面（gbrain link / gbrain timeline-add），不要写入。
   可能重复	属于同一领域；可能提供了新的角度	完整阅读两者。见解相同 → 添加链接，不要写入。确实有新角度 → 写入，并添加指向现有页面的交叉链接。
   明确无重复	排名靠前的结果均未涵盖该主张	通过委派的增强技能正常写入。

决策树

New content to write
  ├─ Named thing? → Named-Entity Resolution Gate first
  │    (entity card → alias-expanded search → READ the candidate)
  ├─ Extract core claim (1-2 sentences)
  ├─ gbrain search "<core claim>" --limit 5
  └─ OPEN AND READ the top hit (gbrain get <slug>)
      ├─ clear-dup     → STOP. Link to existing. Report "duplicate".
      ├─ plausible-dup → Read both. Same insight?
      │    ├─ yes → STOP. Link to existing. Report "duplicate".
      │    └─ no  → Write with cross-link. Report "new angle".
      └─ clear         → Write via enrichment skills. Report "unique".

可跳过去重的情况

• 运维／状态文件——时间序列记录，不是知识。
• 会议记录——每场会议按定义都是独一无二的（其中的实体仍须通过委派技能经过命名实体关卡）。
• 现有页面上的时间线条目——反向链接是增补，不是重复。
• 媒体文件——按文件名／哈希去重，而非按语义相似度。

验证

批次完成后，验证门控的输出是否符合要求：

gbrain check-backlinks check            # mentioned entities link back (fix with: check-backlinks fix)
gbrain backlinks <new-slug>             # each new page has inbound links
gbrain search "<core claim>" --limit 3  # the insight has exactly ONE home

如果 check-backlinks check 报告门控刚刚放行的页面存在缺口，则说明跳过了补充委派——在宣布导入完成前，先转到 补充。

合约

此技能保证：

• 通过此技能的流程进入大脑的每个新页面，都会先运行命名实体解析检查和去重检查。
• 每个“重复”判定都会指出匹配的 slug，并生成链接或时间线条目，而不是克隆页面。
• 新建的命名实体页面会在创建页面的同一次写入中包含 aliases: frontmatter 列表。
• 去重分档通过阅读排名最高的结果来确定，绝不只依据分数；不会对 gbrain 的融合分数使用数值相似度阈值。
• 补充工作委派给已发布的技能（ingest、enrich、signal-detector、concept-synthesis），绝不在内联内容中重述或重新实现。
• 批次结束时会执行 gbrain check-backlinks check 验证。
• 路由与 frontmatter 中的规范触发条件相符。
• 输出写入 writes_to: 中列出的目录。
• 保留隐私合约：不包含真实姓名、特定分支的文件系统路径字面量或上游分支引用。

完整的行为合约记录在上文各部分中；本节用于一致性测试。

输出格式

每个已检查项目输出一行判定，然后输出验证结果：

Ingest gate — 3 item(s) checked

| item | entity resolution | band | action |
|---|---|---|---|
| notes-on-widget-co.md | resolved: companies/widget-co | clear-dup | linked (timeline entry on companies/widget-co) |
| pricing-thesis.md | n/a (prose) | plausible-dup | new angle — written to concepts/ with cross-link to concepts/pricing-power |
| charlie-example-intro.md | miss (near-miss: people/charlie-example) | — | read near-miss; same person → linked, no new page |

Verification: check-backlinks check → 0 gaps on admitted pages

每个“已链接”或“重复”行都必须指出匹配的 slug。如果有任何行显示“已写入”，则应能从对话中追溯补充委派由哪个技能处理。

失败时

对于任何 gbrain 错误 code、退出代码、[AGENT] 块或 notice 块，请遵循Agent 操作员协议。此技能特有的情况：

• “大脑中是否已有此内容？”搜索结果为空，但出现降级通知：仅关键词搜索的空结果并不能证明内容缺失。导入前，请按 slug、URL 或准确标题进行检查。
• gbrain capture / put 返回 write_pending（退出代码 10）：内容已被接受。轮询 gbrain write-request <request_id>；不要再次捕获。
• MCP 写入出现 source_binding_required 或 insufficient_scope：此连接无法写入该来源。告知用户缺少哪个来源和权限范围；由大脑主机的操作员授予。

反模式

• ❌ cp file.md <brain-repo>/concepts/ — 直接复制，没有门控，也没有补充。
• ❌ 将整个文件夹批量 mv 到大脑仓库，然后运行 gbrain sync — sync 会照常为每个重复项建立索引；匹配 ID 跳过机制无法挽救这种情况。
• ❌ 将较低的向量分数视为某个命名实体没有对应页面的证据——命名实体页面不会与对它们的泛化描述嵌入得很接近。
• ❌ 不打开排名最高的结果，仅凭搜索分数进行分档。
• ❌ 将其他系统中的数值去重阈值套用到 gbrain 的融合分数上。
• ❌ 创建新的命名实体页面时不添加 aliases: 列表——下一个同义词就会产生下一个重复项。
• ❌ 不委派给已发布的技能，而是在内联内容中重新实现实体检测、反向链接或概念链接。
• ❌ 因为只是通过 gbrain put 写入“一个页面”就跳过门控——重复的空壳页面往往源自单次手动写入。

去重（明确边界）

• capture — 快速保存入口；其去重机制会对完全相同的字节进行 24h 精确内容哈希检查。本关卡负责语义 + 命名实体层，处理以真实页面形式进入知识库的内容（迁移、批量导入、从收件箱转正）。“捕捉这个想法” → capture；“将这些文件迁移到知识库” → 本关卡。
• ingest — 新外部内容（会议、文章、媒体）的路由器及其增强流水线。ingest 决定如何处理内容；本关卡决定页面是否应该存在。本关卡在写入前触发；ingest 及其专用技能负责“写入”判定之后的一切。
• enrich — 本关卡判定“写入”或“链接”之后的页面创建/更新机制（层级、引用、时间线、反向链接）。
• concept-synthesis — 对已经漏网的概念占位页进行追溯式、大规模去重。本关卡是在写入时预防；concept-synthesis 则是清理流程。“为我已有的概念去重” → concept-synthesis。
• frontmatter-guard（主机端） — 沿正交维度采用相同的独立关卡模式：检查写入内容的结构有效性；而本关卡检查内容的新颖性，以决定是否写入。
• bulk-ingestion — 批量处理的配套流程。其流水线去重键（source + source_id）只能确保重复运行具备幂等性；无法检测跨来源重复项，也无法解析命名实体。本关卡负责语义 + 命名实体层，供 bulk-ingestion 应用于第 3 阶段的试验条目，并纳入其规范化流水线（第 1d/6 阶段）。“构建大规模语料库流水线” → bulk-ingestion；“写入前确认此页面是否已存在” → 本关卡。
• data-loss-gate — 反向关卡：未经确认，阻止数据离开知识库；本关卡则阻止数据未经判定与去重就进入知识库。