GBrain data-research 技能实战：用 7 阶段流水线把邮件、网页与 API 变成结构化追踪器
GBrain data-research 技能实战：用 7 阶段流水线把邮件、网页与 API 变成结构化追踪器
本篇技术指南围绕 GBrain 内置技能 data-research（v1.1.0）展开，讲解其"一套技能、参数化配方"的 7 阶段结构化研究流水线：从定义研究配方、多源检索、确定性分类，到带完整性保障的抽取、原文归档、去重与规范追踪器更新。读者读完将掌握如何用它搭建 investor-updates、expense-tracker、company-updates 等任意"邮件到结构化数据"管道，并理解 put_raw_data、回链与 cron 定时采集在仓库源码中的落点。
技能定位：一套技能覆盖所有"邮件到结构化数据"场景
data-research 是 GBrain 技能库中处理结构化数据研究的核心技能。其 frontmatter 定义（见 plugin-variants/gbrain-daily/skills/data-research/SKILL.md）给出了清晰的职责边界：
- 名称：
data-research，版本1.1.0，mutating: true（会写入大脑）； - 触发词：
research、track、extract from email、investor updates、donations、build a tracker、data dig； - 工具面：
search、query、get_page、put_page、add_link、add_timeline_entry、put_raw_data、file_upload。
技能的核心主张（Contract）是：追踪投资人更新、费用、公司指标这些看似不同的任务，本质上是同一条 7 阶段流水线，唯一的差异只有三处——搜索查询（search queries）、抽取模式（extraction schemas）、追踪器页面格式（tracker page format）。这三处差异通过 YAML 配方（recipe）参数化，因此一套技能可以服务任意"邮件/网页/API → 结构化数据"管道。
在技能树中，本技能同时存在于完整技能库 skills/data-research/SKILL.md 与日常使用变体 plugin-variants/gbrain-daily/skills/data-research/SKILL.md 中，后者属于 gbrain-daily 变体的 19 个精选技能之一（见 plugin-variants/gbrain-daily/README.md），面向"个人知识大脑日常使用：会议、任务、简报、阅读、研究"。
适用场景：什么时候该调用 data-research
根据 SKILL.md 的"When to Use"章节，以下情况应触发本技能：
- 用户想从邮件、网页或 API 源追踪结构化数据；
- 用户说出 "research"、"track"、"extract from email"、"build a tracker" 等关键词；
- 用户提到投资人更新（investor updates）、捐款（donations）、公司指标（company metrics）、监管文件（filings）；
- 用户希望建立周期性数据采集（需要 cron 配方配合，见下文"定时采集"）。
7 阶段流水线深度拆解
Phase 1：定义研究配方（Research Recipe）
第一步是从上下文推断研究目标：结合对话上下文、近期大脑活动、活跃任务（ops/tasks.md）与记忆文件。若请求有歧义，优先基于用户近期工作内容给出最可能的解读，仅在上下文确实不足时才向用户询问澄清。
配方的选择有两种方式：
- 直接选用内置配方：
investor-updates、expense-tracker、company-updates； - 自定义配方，字段包括：源查询（source queries）、分类规则（classification rules）、抽取模式（extraction schema）、追踪器页面路径（tracker page path）、追踪器格式（tracker format）。
配方是存放在 ~/.gbrain/recipes/{name}.yaml 的 YAML 文件。新建配方的标准做法是复制一个内置配方文件再修改字段——这与反模式清单中"在管道代码里硬编码源特定模式"形成对照，配方化是硬性要求。
Phase 2：检索源（Search Sources）
检索遵循 brain-first 原则：先查大脑本身——也许数据早已存在。然后才按配方定义扩展检索面：
- 邮件：经 credential gateway（凭据网关）访问，使用窗口化查询（季度为窗口，若被截断则缩小到月度）；
- 网页：通过 search 检索公开文件、新闻稿、监管数据；
- API：配方定义的任何结构化数据源；
- 附件：PDF 抽取、HTML 去标签。
邮件这一路的依赖值得展开：凭据网关在仓库中由 recipes/credential-gateway.md 文档化，推荐使用原生连接器 gbrain google connect 走完整 OAuth 流程，令牌只存在于本地凭据保险库（~/.gbrain/credentials.json，权限 0600），email-to-brain 等管道依赖它才能访问 Gmail。
Phase 3：分类（Classify）
分类采用确定性优先、LLM 兜底的策略：
- 先用配方中的正则模式（regex patterns）做确定性分类；
- 正则未命中时降级到 LLM 分类；
- 每次 LLM 兜底都必须记录日志，用于后续改进正则——即"失败即改进"（fail-improve loop）闭环；
- 依据配方的分类规则跳过营销邮件、newsletter 与噪音。
这个设计把"可枚举的规则交给确定性逻辑、把模糊判断交给模型、把模型误判沉淀回规则"形成一个持续自优化的数据面。
Phase 4：抽取结构化数据（Extract Structured Data）
这是全技能最强调正确性的阶段，SKILL.md 专门给出"抽取完整性规则"（EXTRACTION INTEGRITY RULE），共 4 条：
- 立即保存原始源（在任何抽取之前）；
- 先用确定性正则抽取字段，LLM 兜底；
- 汇总批次结果时，必须从已保存的文件重新读取；
- 批处理后绝不信任 LLM 工作记忆。
该规则直接源于一次已知幻觉缺陷：批处理过的金额数据从 LLM 工作记忆读取时 13/13 条全部错误，而保存下来的文件内容是正确的。也就是说，"批量处理 → 凭记忆汇总"是经过实测的失效模式，规则要求在记忆与文件之间永远以文件为准。
Phase 5：归档原始源（Archive Raw Sources）
原始材料必须进入大脑，规则如下：
put_raw_data：存储邮件正文、API 响应；file_upload：存储 PDF 附件、文档；- 大文件：创建
.redirect.yaml指针指向存储中的大文件； - 每条追踪器条目必须链接回其原始源。
从源码看，put_raw_data 是 GBrain 操作集中的一个真实操作（见 src/core/ops/raw-data.ts），其参数为 slug（要挂载原始数据的页面）、source（数据源标识，如 crustdata、happenstance）、data（原始数据对象），mutating: true、scope: 'write'，写入时还会带上 sourceId 溯源上下文。同文件还定义了 get_raw_data 用于读取，且原始数据遵循页面的软删除语义——被 tombstone 的页面返回空数组，私有页面的原始数据对不受信任的调用方读取结果与不存在完全一致（无存在性探测），这是隐私边界设计的落地。
Phase 6：去重（Deduplicate）
写入追踪器之前必须去重，三种判定：
| 判定 | 条件 | 动作 |
|---|---|---|
| 精确匹配 | 关键字段完全相同 | 跳过 |
| 模糊匹配 | 同一实体 + 同一日期 + 金额在容差内相近 | 标记待人工复核 |
| 金额冲突 | 同一实体 + 日期但金额不同 | 照常添加并加注（可能是更正） |
反模式清单明确警告："无去重运行会导致条目重复计数（double-counted entries）"。
Phase 7：更新规范追踪器并回链（Update Canonical Tracker + Backlink）
收尾阶段做四件事：
- 解析现有追踪器页面（Markdown 表格）；
- 按正确小节追加新条目（按年/季度/实体分组）；
- 计算累计合计（running totals）；
- 回链每个提及的实体（人 →
people/页面，公司 →companies/页面），实体页由 enrichment（增强）服务维护。
回链不是可选项。按 skills/conventions/quality.md 的规定，任何提到某个人或公司的事实，都必须在其实体页建立指向提及页面的反向链接，格式为：
- **YYYY-MM-DD** | Referenced in page title -- context
该文档还强调"无链接的提及即坏掉的大脑"（An unlinked mention is a broken brain）。同时，每条写入大脑的事实必须携带内联引用 [Source: ...]，例如邮件类 [Source: email from {name} re: {subject}, YYYY-MM-DD]、网页类 [Source: {publication}, {URL}, YYYY-MM-DD]；源优先级从高到低为用户直接陈述 > 编译后的综合真值 > 时间线条目（原始证据）> 外部来源。在创建新实体页前还要过"可记载性门槛"（notability gate）：此人/公司/概念是否还会再接触、与工作或兴趣相关、值得再次引用——存疑就不建页。
内置配方：三种开箱即用的追踪器
GBrain 随技能提供三个示例配方（见 ~/.gbrain/recipes/）：
- investor-updates（投资人更新）：从投资人更新邮件中抽取 MRR、ARR、增速、烧钱率（burn）、跑道（runway）、人数（headcount）；
- expense-tracker（费用追踪）：从收据邮件中抽取金额、收款方、平台（订阅、服务、周期性扣费）；
- company-updates（公司更新）：从投资组合公司更新邮件中抽取收入、用户数、关键指标。
新场景（如 donations 捐款追踪）的做法是复制其中一个配方文件，替换搜索查询、分类规则与抽取模式——三者的差异即全部差异。
输出格式：规范追踪器页面
流水线产出写入配方 tracker_page 路径指定的大脑页面，采用 Markdown 表格，例如：
### 2026
| Date | Company | MRR | ARR | Growth | Status |
|------|---------|-----|-----|--------|--------|
| 2026-04-01 | Example Co | $188K | $2.3M | +14.7% MoM | Source |
约束有两点：每个条目都链回其原始源（呼应 Phase 5 的归档规则）；每个小节底部有累计合计。
反模式清单：四条红线
SKILL.md 明确列出必须避免的四个反模式，可与前文一一对应：
- 批量处理后信任 LLM 工作记忆来汇总金额——应始终遵循抽取完整性规则（Phase 4）；
- 创建无原始源链接的追踪器条目——破坏溯源链（Phase 5）；
- 无去重直接运行——导致重复计数（Phase 6）；
- 在管道代码中硬编码源特定模式——应一律使用配方（Phase 1）。
定时采集：用 cron 配方驱动周期运行
SKILL.md 提到用户可能希望"设置周期性数据采集（cron 配方）"。在 GBrain 的部署约定中，定时触发的工作应作为 Minion 任务执行，而非直接调用 agentTurn——后者有 300 秒超时、无持久性、无转录（见 skills/conventions/cron-via-minions.md）。推荐的调度写法如下：
# Postgres 环境：带幂等键的即发即弃提交，队列层去重长时运行的重叠任务
gbrain jobs submit ea-inbox-sweep \
--params '{"slot":"$(date -u +%Y-%m-%dT%H:%M)"}' \
--idempotency-key ea-inbox-sweep:$(date -u +%Y-%m-%dT%H:%M)
# PGLite 环境：文件排他锁阻断独立 worker，直接内联执行
gbrain jobs submit ea-inbox-sweep --params '{}' --follow
这样做的收益是：网关重启后 worker 自动拾取任务（持久性）、gbrain jobs list 与 gbrain jobs get <id> 提供完整可观测性、运行中任务可接收转向指令、幂等键防止慢任务叠加（5 分钟 cron 跑 8 分钟任务若无幂等键会稳态叠出 4 份重叠副本）。注意：GBrain 只会重写与 gbrain 内置 handler（sync、embed、lint、import、extract、backlinks、autopilot-cycle）同名的 cron 条目，宿主自定义 handler 由宿主平台以代码形式提供。若用户将 minion_mode 设为 off（~/.gbrain/preferences.json），则继续使用 agentTurn，不做自动改写。
从技能到源码：data-research 的仓库落点
要在实际安装中运行本技能，可围绕以下路径深入仓库：
- 技能定义：plugin-variants/gbrain-daily/skills/data-research/SKILL.md（日常变体）与 skills/data-research/SKILL.md（完整技能库），两者内容一致；
- 抽取/归档操作：src/core/ops/raw-data.ts 中
put_raw_data/get_raw_data的参数契约、写作用例与隐私语义； - 引用与回链规则：skills/conventions/quality.md 的强制引用格式、回链格式与可记载性门槛；
- 邮件接入：recipes/credential-gateway.md 的
gbrain google connect原生连接器与 ClawVisor 网关两种方案； - 定时调度：skills/conventions/cron-via-minions.md 的 Minion 任务提交写法与幂等键约定。
整体来看，data-research 的价值在于把"搜集 → 分类 → 抽取 → 归档 → 去重 → 汇总 → 回链"这条高频重复的研究链路固化成确定性流程：能用规则的地方用规则，需要模型的地方让模型兜底，并用"失败即改进"循环与"保存原始源优先"规则把正确性做成系统能力，而不是寄望于模型的偶然表现。