capture

capture — 唯一的内容录入入口

当用户想保存一个想法、一段文章摘录、一段转录片段或任何文本到自己的 brain 中时，运行 gbrain capture。不要使用 gbrain put 或先提交再同步的流程。capture 是统一的入口，本地安装和瘦客户端安装的处理方式相同。

约定

• 输入： 要保存的内容（行内参数、--file PATH 或 --stdin）。
• 输出： brain 数据库中的一个页面，以及位于 <sync.repo_path>/<slug>.md 的 Markdown 文件。回执打印到标准输出。
• 副作用： 该页面可立即通过 gbrain query、gbrain search 或任何绑定 MCP 的 Agent 进行查询。
• 幂等性： 相同内容生成相同的 inbox/YYYY-MM-DD-<hash8> slug。守护进程的 24 小时内容哈希去重会拦截重复捕获。
• 信任： 通过此技能进行的所有捕获均为本地 CLI 信任（remote: false）。不受信任的 webhook 录入需通过 POST /ingest，而不是此命令。

何时调用

• "捕获这个想法" / "保存这个" / "放进我的 brain" / "记住这个"
• 用户粘贴内容并要求保存
• 会议纪要、研究笔记或任何应成为 brain 页面的综合内容之后

功能说明

gbrain capture 会解析为一次 put_page 调用（本地）或一次远程 MCP 调用（瘦客户端）。无论哪种方式，页面都会通过 v0.38 的写穿透机制一次性同时写入数据库和磁盘。默认 slug 为 inbox/YYYY-MM-DD-<hash8>，使捕获内容集中在可预测的分拣位置。

使用方法

gbrain capture "the thought I want to remember"
gbrain capture --file ./notes/today.md
echo "from a pipe" | gbrain capture --stdin
gbrain capture "..." --slug daily/2026-05-21
gbrain capture "..." --type idea --source voice-whisper
gbrain capture "..." --quiet          # script-friendly: prints just the slug
gbrain capture "..." --json           # structured output for agents

默认值

• Slug： inbox/YYYY-MM-DD-<hash8>（相同内容保持稳定；守护进程的 24 小时去重会拦截重复捕获）。
• 类型： note（可用 --type idea 等覆盖）。
• Frontmatter 标记： captured_via: capture-cli、captured_at: <ISO>。
• 标题： 正文中第一个非空行，最多 80 个字符（截断时追加 …）。

输出格式

默认输出一个 5 行的回执：

captured:
  slug:          inbox/2026-05-21-abcdef12
  status:        created_or_updated
  content_hash:  f3a7b9c0d1e2f3a4…
  file:          /Users/you/brain/inbox/2026-05-21-abcdef12.md
  captured_at:   2026-05-21T04:15:00.000Z

--quiet 仅输出 slug（用于 SLUG=$(gbrain capture "..." --quiet)）。 --json 输出结构化结果，供下游工具使用。

失败处理

对于任何 gbrain 错误 code、退出码、[AGENT] 块或提示块，请遵循Agent 操作协议。针对本技能的具体情况：

• 退出码 10（write_pending）：内容已被接受，且可能仍会提交。告知用户已保存且待处理，并轮询 gbrain write-request <request_id>；切勿重复捕获。
• 敏感信息扫描或 slug 围栏拒绝：内容未保存。告知用户被拒绝的原因；不要为绕过扫描器而修改内容。
• 通过 MCP 出现 source_binding_required 或 insufficient_scope：此连接无法写入目标来源；告知用户哪个来源需要 brain 主机运维人员授权。

反模式

• 不要使用 gbrain put。 这是旧的单页原语，不了解默认 slug 生成、内容类型启发式规则或回执块。capture 是面向用户的封装。
• 不要通过循环调用 gbrain capture 批量导入数十个文件。 这应使用 gbrain sync（或 gbrain import）。Capture 仅用于单个想法、单条笔记、单段转录。
• 如无必要，不要自行为内容预先添加 frontmatter。 Capture 会为纯文本散文添加合适的 frontmatter（类型 + 标题 + captured_via + captured_at），正文变为 # 标题\n\n<你的正文>。如果你已有格式完整的 Markdown 文件，请传入 --file PATH。
• 不要将敏感信息作为行内内容传入。 行内参数会进入 shell 历史记录。请改用 --file 或 --stdin。

何时不使用此技能

• 批量导入大量文件 → 改用 skills/media-ingest/SKILL.md 或 gbrain sync
• 带有作者和出版元数据的文章/链接 → 改用 skills/idea-ingest/SKILL.md（它知道如何建立人物页面）
• 会议记录 → 改用 skills/meeting-ingestion/SKILL.md（参会人信息补充）

本技能适用于简单的"我有一个想法，把它保存下来"的场景。专门的导入路径会自行处理 slug 生成和交叉引用。