gbrain voice-note-ingest 技能实战：语音备忘的逐字保真捕获、路由归档与脑图回链

gbrain voice-note-ingest 技能实战：语音备忘的逐字保真捕获、路由归档与脑图回链

【免费下载链接】gbrainGarry's Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain

本指南以 gbrain 仓库plugin-variants/gbrain-daily/skills/voice-note-ingest/SKILL.md为核心，讲解如何把一条音频/语音备忘完整地"吞进"个人知识脑：原始音频先入库，转录文本逐字保真（绝不改写），再按决策树路由到originals/、concepts/、people/、companies/、ideas/、personal/或兜底的voice-notes/目录，最后为提到的每个人/公司执行 Iron Law 反向回链。读完本文，你将掌握该技能的完整调用协议、七级路由决策树、脑页骨架格式、命名与引用规范，以及它与_brain-filing-rules.md、quality.md等仓库级约定之间的强制关系，可直接在 gbrain 插件环境中落地运行。

技能定位：语音是未经修饰的原始信号

voice-note-ingest是 gbrain 的gbrain-daily（daily-driver 人格）变体插件中用于语音备忘摄取的核心技能。它的设计前提非常明确：语音备忘与打字不同——人们说话时不会自我编辑，脱口而出的句式、犹豫、语气词恰恰是思考过程的真实切片。因此该技能的核心约束（Iron Law）是：

用户的原话就是洞见本身。绝不改写、绝不"清理"。那些生动、未经打磨、意识流式的措辞，恰恰承载着被"顺过一遍"的书面语所丢失的信息。转录文本必须原样保留在 block quote 中；Analysis 部分可以解读，但转录区是神圣不可动的。

技能文档用一对正反例把这条铁律钉死：

• ✅"The ambition-to-lifespan ratio has never been more fucked"
• ❌User noted the tension between ambition and mortality

前者保留语气与冲击力，后者是典型的"转述污染"。这一原则在 gbrain 中并非孤例：skills/signal-detector/SKILL.md（文本渠道的主动信号捕获）同样要求"以用户精确措辞捕获（绝不转述）"，skills/idea-ingest/SKILL.md（打字输入的思路摄取）也继承了同一模式。三个技能共享同一条"原话即资产"的哲学，voice-note-ingest 只是把它应用到音频场景。

技能声明与触发条件

该技能 frontmatter 声明了名称、版本、描述、触发词与写权限范围（见 voice-note-ingest SKILL.md）：

• name:voice-note-ingest，version:0.1.0
• triggers（触发词，命中即唤起）:"voice note"、"ingest this voice memo"、"transcribe and file"、"voice note ingest"、"save this audio note"、"audio message"
• mutating: true、writes_pages: true——这是一个会写脑库页面的变更型技能
• writes_to:voice-notes/、originals/、concepts/、people/、companies/、ideas/、personal/

配套的 routing-eval.jsonl 是路由评测夹具，每条 intent 都至少包含一个触发词子串（满足结构匹配器的要求），同时保留了真实用户措辞的多样性，例如：

{"intent":"Please ingest this voice memo I just sent and file it into my brain","expected_skill":"voice-note-ingest"} {"intent":"Save this audio note as a brain page with the original audio attached","expected_skill":"voice-note-ingest","ambiguous_with":["idea-ingest"]} {"intent":"Run voice note ingest on what I just sent — preserve my words verbatim","expected_skill":"voice-note-ingest"}

注意最后一条评测用例将本技能与idea-ingest标记为ambiguous_with：当用户说"把这个音频存成脑页"时，路由可能同时命中"保存"与"语音"两类语义，评测要求 agent 能正确分派到 voice-note-ingest。

调用时机：什么场景唤起本技能

技能文档定义的唤起场景是：用户通过任意渠道（Telegram、语音备忘上传、openclaw 音频附件）发送一段音频或语音消息。此时：

1. 宿主 agent 通常会随消息提供转录文本（transcript）；
2. 若未提供，则由 agent 自己调用宿主平台的转录工具完成转写。

文档对转录工具给出了明确的性价比建议：

• Groq Whisper：快且便宜，优先选择；
• OpenAI Whisper：同样可用；
• 音频超过25MB时，先用ffmpeg切分后再转录。

这一"STORE 之后立刻 TRANSCRIBE"的先后顺序非常重要：转录不是终点，原始音频必须先行入库（见下一节的管道），因为脑页中的🔊 [Audio]链接要指回这份原始文件，任何后续的重新转写或校对都以原始音频为基准。

五步摄取管道：STORE → TRANSCRIBE → ROUTE → WRITE → CROSS-LINK

技能文档给出了完整管道，每一步职责明确：

1. STORE → 将原始音频上传到 gbrain 存储后端 (S3 / Supabase Storage / local —— 按 src/core/storage.ts 可插拔)。 2. TRANSCRIBE → 优先原样使用 agent 提供的转录文本；若未提供， 自行转录音频（见上文"调用时机"）。 3. ROUTE → 应用下面的决策树，找到目标归档目录。 4. WRITE → 创建/更新目标脑页；把逐字转录文本保留在 block-quoted 的 "User's Words" 小节。 5. CROSS-LINK → 对提到的每个实体（人、公司），从"他们的脑页" 向"本页"追加时间线回链（依据 conventions/quality.md 的 Iron Law）。

第一步背后的实现支撑：可插拔存储层

管道第一步指向的src/core/storage.ts在仓库中真实存在（见 src/core/storage.ts），印证了"存储后端可插拔"的表述——S3、Supabase Storage 与本地文件系统都是可选的实现后端。这与仓库级归档规则 skills/_brain-filing-rules.md 中的"Raw Source Preservation"机制相衔接：

• 小于100MB的文本/PDF：留在脑仓库中（git 跟踪），以.raw/侧车目录与脑页并存；
• ≥100MB 或媒体文件（视频、音频、图片）：上传到云存储（Supabase Storage、S3 等），在脑仓库中留一个.redirect.yaml指针；≥100MB 的文件走 TUS 断点续传（6MB 分块 + 重试）。

对应的上传命令为：

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

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

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

voice-note-ingest 的"STORE"步骤正是这条机制在音频场景的直接落地——音频是媒体文件，按规则应当上传云存储并以.redirect.yaml指针留痕，脑页中的🔊 [Audio]链接指向该存储路径。这样的设计保证了任何派生脑页都能追溯回原始来源，同时大文件不会撑爆 git 仓库。

七级决策树：内容往哪里归档

路由是整个技能最关键的判断环节。文档规定：按顺序依次匹配，先命中者胜；若同时命中多个类别，则归入主目录并向其他类别交叉链接。

多类别命中时的规则：创建主页面，然后向所有其他类别交叉链接。例如一条语音同时涉及"一个人 + 一个新想法"，就既要创建originals/页面，也要更新该人物的时间线。

这套决策树与仓库级归档协议 skills/_brain-filing-rules.md 高度一致。后者规定的一条核心原则是：内容的"主要主体"决定它去哪，而不是格式、来源或运行中的技能决定。该文件还列出了一张常见的错误归档对照表，voice-note-ingest 的决策树可以视为这张表在语音场景的具体化：

Notability Gate：不是所有内容都值得建页

在创建任何新实体页之前，归档规则要求过一道"可记性门禁"：

• 人：你还会再与他互动吗？与你的工作/兴趣相关吗？
• 公司：与你的工作或兴趣相关吗？
• 概念：这是值得日后引用的可复用思维模型吗？
• 拿不准就不要建：缺页可以日后补，垃圾页只会浪费注意力并拉低搜索质量。

这条门禁同样约束着 voice-note-ingest 的 3、4 两步：为某人/某公司建页或更新时间线前，先确认其可记性。

脑页骨架：所有语音派生页面统一格式

技能文档为所有语音派生的脑页规定了统一骨架，包含 YAML frontmatter 与固定章节。完整模板如下：

--- title: "[Title derived from content]" type: [original | concept | voice-note | ...] created: YYYY-MM-DD updated: YYYY-MM-DD tags: [voice-note, relevant-tags] sources: voice-note: type: voice_note storage_path: "[gbrain storage URL or relative path]" acquired: YYYY-MM-DD acquired_via: "voice note from <channel>" --- # Title > Executive summary of what was said and why it matters. ## User's Words > "Exact transcript, verbatim, preserving every word, hesitation, and verbal > tic. This is the primary source material. Do not edit." 🔊 Audio ## Analysis [What this means, why it matters, connections to other thinking. The analysis is the agent's interpretation; the transcript above is sacred.] ## See Also - [Related brain pages with relative links] --- ## Timeline - **YYYY-MM-DD** | voice note from <channel> — [Brief description]

逐段拆解各要素的作用：

• frontmatter：type标记页面类别；sources.voice-note块记录来源类型、存储路径、获取日期与渠道（acquired_via），这是溯源的关键元数据；
• Executive summary：一句"说了什么、为什么重要"的引述式导语；
• User's Words：神圣区。逐字转录，保留每一个词、每一次犹豫、每一个口头禅，"这是主要来源材料，不得编辑"；
• 🔊 [Audio]链接：指回第一步 STORE 存入的原始音频，让声音本身永远可回放；
• Analysis：agent 的解读——含义、重要性、与其他思考的连接。文档明确强调："分析是 agent 的解读；上面的转录是神圣的"，二者边界不可混淆；
• See Also：指向相关脑页的相对链接；
• Timeline：以YYYY-MM-DD开头的条目，记录"某日来自某渠道的语音备忘"。

引用格式：每条事实必须带 Source 标注

技能文档规定语音场景的标准引用格式：

[Source: voice note, <channel>, YYYY-MM-DD]

当音频带时间戳时，追加时间：

[Source: voice note, <channel>, YYYY-MM-DD HH:MM PT]

这一格式是仓库级引用制度在语音场景的实例化。skills/conventions/quality.md（cross-cutting 质量约定，所有写脑库的技能都必须遵守）要求每条写入脑页的事实都必须携带内联[Source: ...]引用，并定义了完整格式谱系：

• 用户陈述：[Source: User, {context}, YYYY-MM-DD]
• 会议数据：[Source: Meeting "{title}", YYYY-MM-DD]
• 邮件/消息：[Source: email from {name} re: {subject}, YYYY-MM-DD]
• 网页内容：[Source: {publication}, {URL}, YYYY-MM-DD]
• 综合结论：[Source: compiled from {sources}]

来源优先级（高 → 低）：用户直接陈述 > 编译事实（脑内既有综合）> 时间线条目（原始证据）> 外部来源（API 增强、网络搜索）。来源冲突时，同时标注矛盾双方，不静默二选一。

命名规范与单条处理约束

命名约定

• 音频文件：YYYY-MM-DD-<brief-slug>.<ext>，例如2026-04-13-rick-rubin-creative-philosophy.ogg；
• 脑页：与目标目录的 slug 保持一致。

slug 的日期前缀让语音备忘天然按时间排序，便于日后回溯"那天我说了什么"。

Bulk vs. single：一次只处理一条

该技能明确不支持批量：一次处理一条语音备忘，每条都是独立的摄取周期（ingest cycle）。这保证了逐字保真与路由判断的质量——批量处理必然诱使 agent 压缩、概括、牺牲细节，与 Iron Law 直接冲突。

反模式清单：最容易犯的四个错误

技能文档列出了四条必须避开的反模式，逐条对应其核心约束：

1. ❌转述转录文本——原话就是信号；
2. ❌清理犹豫或口头语（"um"、"like"、"you know"）——这些"质感"很重要；
3. ❌提到了人物/公司却建了一个没有实体交叉链接的页面——Iron Law 失败；
4. ❌跳过音频存储步骤——必须始终上传原始文件，脑页要有指向它的🔊 [Audio]链接。

其中第 3 条直接呼应 Iron Law 回链机制。skills/conventions/quality.md 对该机制的定义是：

每提到一个有脑页的人或公司，都必须从该实体的页面创建指向提到他们的页面的回链。格式：- **YYYY-MM-DD** | Referenced in page title -- context。一条未链接的提及就是一个残缺的脑；图就是智能本身。

skills/_brain-filing-rules.md 也重申了这一点：回链是双向的——新页面链向实体，实体的页面也要链回来。这正是 voice-note-ingest 管道第五步 CROSS-LINK 的理论依据。

与相邻技能的分工协作

• skills/signal-detector/SKILL.md：环境中的主动信号捕获（需显式 opt-in），对文本渠道的思路捕获应用同一套精确措辞模式；
• skills/idea-ingest/SKILL.md：打字输入的思路摄取（链接、文章、推文），含作者人页创建与原始素材上传；
• skills/conventions/quality.md：引用 + 回链规则的权威来源；
• skills/_brain-filing-rules.md：归档决策协议的权威来源。

三者共同构成 gbrain 的"捕获家族"：语音（voice-note-ingest）、文本（idea-ingest）、环境信号（signal-detector），共享同一套精确措辞、实体回链与引用纪律。

技能契约与一致性保障

技能文档末尾的 Contract 部分明确了该技能对宿主 agent 的保证：

• 路由与 frontmatter 中的规范化触发词一致；
• 输出写入writes_to:列出的目录（适用时）；
• 遵守所引用的约定（quality.md、brain-first.md、_brain-filing-rules.md）；
• 维护隐私契约：不出现真实姓名、不出现 fork 专属的文件系统路径字面量、不出现上游 fork 引用。

文档特别说明：Contract与Output Format这两个字面小节标题是为一致性测试（conformance test，见test/skills-conformance.test.ts）保留的锚点。这体现了 gbrain 技能体系的工程化保障思路——技能不止是给 agent 的自然语言指令，还要接受结构化的路由评测（如routing-eval.jsonl）与一致性测试的自动校验，确保技能声明、触发词、写入目录与约定引用始终同步，不会随迭代漂移。

总结

voice-note-ingest 是 gbrain 语音摄取管线的完整封装，其设计可以概括为五条不可妥协的原则：

1. 原话神圣：转录逐字保真，Analysis 只能解读、不能改写；
2. 音频必存：原始文件先行入库，脑页永远保留🔊 [Audio]回放链接；
3. 按主体归档：七级决策树 + 主目录/交叉链接规则，与_brain-filing-rules.md的主主体原则一致；
4. 实体必回链：提到的人/公司双向链接，未链接的提及即残缺；
5. 事实必溯源：每条事实携带[Source: voice note, <channel>, YYYY-MM-DD]引用，遵循 quality.md 的来源优先级。

配合src/core/storage.ts的可插拔存储后端、gbrain files upload-raw的原始素材上传机制以及路由评测夹具的持续校验，这条管道让"随口一说"真正沉淀为可检索、可追溯、可回放的脑资产——而这一切的前提，是尊重用户那句话原本的样子。

【免费下载链接】gbrainGarry's Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain