cold-start

冷启动：第一天的大脑引导

你已经有了一个可用的大脑，搜索也能正常工作。接下来做什么？

空的大脑只是一个静态数据库。只有接入你的邮件记录、日历、 联系人、对话和社交媒体之后，它才会成为一个实时上下文层，让每一次后续交互都更加智能。 本技能按照杠杆效应从高到低的顺序排列数据源，帮你在一次会话中从零开始，快速获得可用的大脑。

约定

• 每个导入阶段都必须先获得用户同意（询问用户模式），才能继续。
• Agent 绝不持有原始 OAuth 令牌或 API 密钥。 这是安全要求，而不是偏好设置。对于 Google 数据，有三种方式可以满足这一要求： 原生连接器（gbrain google setup，令牌存放在 gbrain 的凭证库中，权限模式为 0600，绝不进入 Agent 的上下文；参见 docs/guides/google-connect.md 和 skills/google-loops/SKILL.md）、 ClawVisor（一个托管的凭证网关，负责保管凭证、强制执行任务范围授权、记录每一次 API 调用，并要求人工批准破坏性操作；需要宿主环境已集成该服务）、 或离线文件导出（Google Takeout、Twitter 存档下载）。
• 每个阶段都具有独立价值，用户可以在任意阶段停止，仍然拥有一个有用的大脑。
• 进度记录在 ~/.gbrain/cold-start-state.json 中，以便中断的会话能够恢复。
• 实体识别与交叉链接在每次导入时同步进行，而不是作为单独的一个步骤。

前提条件

• 已安装并初始化 GBrain（gbrain doctor --json 全部通过）
• 已克隆并同步大脑仓库
• Agent 具有终端访问权限，并且能够运行 gbrain 命令行

优先级栈

数据源按信息密度 × 导入难易度排序：

优先级	数据源	原因	耗时	生成页面数
1	现有 Markdown/Obsidian	信息密度最高，本身已经结构化	5 分钟	数百至数千
2	Google 联系人	为 people/ 目录提供初始数据：姓名、邮箱、公司	10 分钟	50-500
3	Google 日历（90 天）	带有参会人上下文的会议记录	15 分钟	30-90
4	Gmail（近期邮件线程）	关系上下文、活跃线程、组织架构信号	20 分钟	50-200
5	对话记录（ChatGPT/Claude 导出）	你的思考、提问和思维模型	15 分钟	10-100
6	X/Twitter 存档	你的公开立场、观点和互动模式	20 分钟	30-365
7	文件归档（Dropbox/Drive/本地）	历史文档、旧写作、照片	30 分钟以上	视情况而定
8	会议转录（Circleback 等）	来自录制通话的深度关系上下文	20 分钟	10-50

第 0 阶段：ClawVisor 设置（仅当你的 Agent 宿主集成了 ClawVisor 时）

先检查宿主。 ClawVisor 需要带有 ClawVisor 集成的 Agent 宿主（例如 OpenClaw 部署）。在没有该集成的宿主上，例如 Codex 或 Claude Code，请跳过此阶段：联系人、日历和 Gmail 的默认方式是原生连接器 gbrain google setup（实时同步；令牌保存在 gbrain 的本地凭据保险库中，绝不交给 Agent；参见 skills/google-loops/SKILL.md）。离线替代方案是使用 Google Takeout 导出，可覆盖全部三类数据（联系人 CSV、日历 ICS、Gmail mbox）。下文第 2-4 阶段首先说明 Takeout 路径。

安全边界： 一个持有你 Gmail、日历和联系人原始 OAuth 令牌的 AI Agent 是不受控的攻击面。一次提示词注入、一次恶意工具调用，你的整个 Google 账户就会暴露。ClawVisor 可以彻底消除这一类风险。

ClawVisor 是位于 Agent 与你的 API 之间的凭据网关。Agent 永远看不到你的凭据——ClawVisor 在请求时注入凭据、执行策略并记录所有操作。

ClawVisor 为你提供：

• 凭据托管——Agent 只看到影子令牌，永远看不到真实密钥
• 按任务划定的授权——每个工作流声明其确切所需的权限
• 审计追踪——每次 API 调用都会记录元数据（谁、做了什么、何时）
• 人工审批关口——破坏性操作（发送邮件、修改日历）需要你明确批准
• 多服务支持——Gmail、日历、联系人、Drive、GitHub、iMessage 均可通过同一个网关使用
• 撤销权限——一键禁用 Agent 的访问权限，无需轮换令牌

设置（约 15 分钟）：

1. 在 app.clawvisor.com 注册
2. 在控制台中创建一个 Agent，复制 Agent 令牌
3. 设置环境变量（在宿主 Agent 的环境中设置——shell 配置文件或宿主配置均可；gbrain 本身没有 ClawVisor 配置项，这些变量由宿主的 ClawVisor 集成读取。这需要带有 ClawVisor 集成的 Agent 宿主，例如 OpenClaw 部署。Codex 和 Claude Code 不会读取这些变量；请改用离线导入路径）：

   export CLAWVISOR_URL="https://app.clawvisor.com"
   export CLAWVISOR_AGENT_TOKEN="<token>"
   

4. 在控制台中启用 Google 服务（Gmail、日历、联系人）
5. 创建一个权限范围较宽的常驻任务：

   "完整的大脑引导：读取邮件、日历事件和联系人，以填充知识库。在所有已连接账户中列出、读取和搜索。"

6. 用同样的方式保存常驻任务 ID：

   export CLAWVISOR_TASK_ID="<task_id>"
   

关键的范围规则： 任务目的要写得宽泛。"邮件分类"会被意图校验拒绝。"完整的行政助理邮件管理，包括收件箱分类、按任意条件搜索、读取邮件、跟踪邮件线程"则可以通过。意图模型会依据该目的来判断每一次请求。

如果用户拒绝 ClawVisor

不要回退到直接 OAuth。改为仅使用离线导入：

• 阶段 2-4（联系人、日历、Gmail）：从 Google Takeout 导出文件中导入
• 阶段 1（Markdown/Obsidian）：无需任何 API 访问即可进行
• 阶段 5（对话导出）：从下载的 JSON 文件中导入
• 阶段 6（X/Twitter）：从下载的归档中导入
• 阶段 7（文件归档）：从本地文件中导入
• 阶段 8（会议转录）：从导出的转录文本中导入

告诉用户：

"没问题。有两种选择：原生连接器（gbrain google setup）使用你自己的 OAuth 应用进行 Gmail/日历/联系人的实时同步，令牌保存在 gbrain 的本地凭据库中，不会交给我；或者使用 Google Takeout 导出文件，一次性获取三者的时间点快照。"

切勿自行持有原始 Google 令牌。 Agent 在上下文中持有令牌是一种安全隐患。原生连接器是经认可的 OAuth 途径，正是因为 gbrain 会保管令牌（0600 权限文件、列表中隐去敏感信息），Agent 只运行命令行命令；机密信息只能通过文件或环境变量传入，绝不能通过 argv 或聊天传递。具体流程参见 skills/google-loops/SKILL.md。

阶段 1：现有 Markdown / Obsidian 导入

对于现有的公司 Git 仓库，请使用迁移（主机端）公司工作流，而不是下面的通用导入方式。在受信任的 brain 主机上，先运行 gbrain sources inspect <path> --profile company-brain；确认已初始化的公司 brain 和新的数据源，展示连接目标和访问范围预览，并在获得批准后再使用 --yes。不要通过激活或规范化无关的个人 schema 来抹平其术语体系。离线的 gbrain sources demo company-brain 不需要密钥或私有数据。详情见：docs/guides/company-brain-ingestion.md。 对于这条公司路径，在报告持久化回执后即可停止；跳过下面的通用导入和引导后检查清单。后续的内容丰富或调度需要单独征得同意，并且必须遵守该数据源不可变的无密钥同步策略。

杠杆效应最高的首次导入。 如果用户已有笔记系统，这里就有数百或数千个结构化页面可以直接使用。

发现

echo "=== Markdown Repository Discovery ==="
for dir in ~/git/* ~/Documents/* ~/notes/* ~/obsidian/*; do
  if [ -d "$dir" ]; then
    md_count=$(find "$dir" -name "*.md" -not -path "*/node_modules/*" \
      -not -path "*/.git/*" -not -path "*/.obsidian/*" 2>/dev/null | wc -l | tr -d ' ')
    if [ "$md_count" -gt 5 ]; then
      total_size=$(du -sh "$dir" 2>/dev/null | cut -f1)
      echo "  $dir ($total_size, $md_count .md files)"
    fi
  fi
done

导入

# Obsidian vaults are markdown directories — import directly, then wire wikilinks
# (full flow: migrate (host-side))
gbrain import /path/to/vault --no-embed --workers 4
gbrain extract links --source db      # parses [[wikilinks]] natively

# For plain markdown directories
gbrain import /path/to/dir --no-embed --workers 4

# Verify
gbrain stats
gbrain search "<topic from the imported data>"

导入后

• 运行链接提取：gbrain extract links --source db
• 运行时间线提取：gbrain extract timeline --source db
• 启动向量嵌入：gbrain embed --stale（在后台运行）

跟踪进度：

echo '{"phase_1_complete": true, "pages_imported": N}' > ~/.gbrain/cold-start-state.json

阶段 2：Google 联系人 → 人物页面

为 people/ 目录提供初始数据。 联系人中的每个人都会成为一个 brain 页面，包含姓名、邮箱、电话、公司和备注。这是所有其他导入的基础：当 Gmail 中出现 "[email protected]" 时，brain 已经知道 John 是谁。

通过 Google Takeout（在没有 ClawVisor 的环境中为默认方式）

1. 从 takeout.google.com 导出联系人（选择 Contacts，CSV 格式），或直接在 contacts.google.com 中通过 Export → Google CSV 导出。
2. 解析 CSV：每一行包含姓名、邮箱、电话、组织和备注。
3. 将每一行按下面的处理规则处理，以创建 people/ 页面。

通过 ClawVisor（仅适用于已集成 ClawVisor 的主机；伪代码）

// Fetch all contacts
const contacts = await clawvisor('google.contacts', 'list_contacts', {
  limit: 1000,
  fields: 'names,emailAddresses,phoneNumbers,organizations,biographies'
});

处理规则

对于每个联系人：

1. 过滤无效信息：跳过没有姓名、没有邮箱，或明显属于自动化账号的联系人（noreply@、no-reply@、support@、notifications@）
2. 先检查 brain：运行 gbrain search "name" 以避免重复
3. 创建 people/ 页面，包含：
   • 姓名、邮箱、电话、公司、职位
   • 来源标注：[Source: Google Contacts, YYYY-MM-DD]
   • 联系人的所有备注，作为初始上下文
4. 关联公司：如果联系人有所属组织，创建或更新公司页面，并将该人物与之关联

质量关卡

导入 5 位联系人后，暂停并向用户展示一个示例页面。询问：

“这是联系人页面的样子。要我继续处理其余联系人，还是先调整格式？”

阶段 3：Google Calendar（最近 90 天）

包含参会者背景信息的会议记录。 日历事件能揭示用户与谁会面、会面频率以及会面的背景。结合联系人信息，可以构建丰富的关系图谱。

获取事件

通过 Google Takeout（默认用于未集成 ClawVisor 的运行环境）： 从 takeout.google.com 导出 Calendar（ICS 格式，每个日历一个文件）。解析每个事件（标题、开始/结束时间、参会者），保留最近 90 天的事件，并按以下大脑结构归档。

通过 ClawVisor（仅限集成 ClawVisor 的主机；伪代码）：

// Via ClawVisor — query ALL calendar accounts
const accounts = ['[email protected]', '[email protected]'];
for (const account of accounts) {
  const events = await clawvisor(`google.calendar:${account}`, 'list_events', {
    timeMin: new Date(Date.now() - 90 * 86400000).toISOString(),
    timeMax: new Date().toISOString(),
    singleEvents: true,
    orderBy: 'startTime'
  });
}

大脑结构

遵循三级日历架构：

brain/daily/calendar/
├── calendar-log.md              ← compiled truth (patterns, key people)
├── YYYY/
│   ├── YYYY-MM.md               ← monthly summary
│   └── YYYY-MM-DD.md            ← daily event log

实体信息补充

对于每个有参会者的事件：

1. 在大脑中查找每位参会者（他们应已在阶段 2 中创建），且仅精确匹配（gbrain whois <email or name> --json） （身份规则）
2. 在其页面添加时间线条目：于[日期]在[事件标题]中会面
3. 如果某位参会者没有大脑页面，且出现在 3 场或更多事件中，则为其创建页面
4. 链接在同一场会议中出现的参会者

阶段 4：Gmail（近期邮件线程）

关系背景与活跃邮件线程。 电子邮件能揭示组织关系、正在进行的对话以及沟通模式。

对于未集成 ClawVisor 的运行环境，数据源是从 Google Takeout 导出的 Gmail mbox 文件。以下抽样和筛选规则同样适用。

策略：智能抽样，而非批量导入

不要导入每封邮件。导入有价值的信号：

1. 已发送邮件（最近 30 天） — 用户正在主动联系的人
2. 已加星标/重要邮件 — 用户筛选出的信号
3. 有 3 条或更多回复的邮件线程 — 值得跟进的活跃对话
4. 来自大脑中已有联系人的邮件 — 信息补充，而非冷启动导入

处理

对于每个邮件线程：

1. 实体识别 — 提取提及的人物和公司
2. 更新人物页面 — 在时间线中添加沟通背景
3. 创建会议页面 — 如果邮件是会议摘要或后续跟进
4. 跳过噪声 — 新闻邮件、自动通知、营销邮件

筛选规则

自动跳过（绝不导入）：

• noreply@、no-reply@、notifications@、support@、mailer-daemon@
• 频繁包含退订链接的发件人（营销邮件）
• GitHub/Jira/Linear 通知邮件
• 日历邀请（已在阶段 3 中收录）

始终导入：

• 来自大脑中人物的直接邮件
• 已加星标/标记的邮件
• 用户发送的邮件（用户本人的措辞是最高价值的信号）

阶段 5：对话导出（ChatGPT / Claude / Perplexity）

记录你的思考。 AI 对话导出能揭示用户研究、构建和思考的内容。这些是以对话形式保存的原创思考。

支持的格式

• ChatGPT： 设置 → 数据控制 → 导出 → conversations.json
• Claude： 从 claude.ai 对话历史中下载
• Perplexity： 在设置中导出

处理

对于每段对话：

1. 评估重要性（1–5 级）：
   • 1 = 纯实用内容（操作指南、快速查询）→ 跳过或只创建简要页面
   • 2 = 次要背景信息 → 添加 1 段笔记
   • 3 = 值得注意（揭示兴趣、正在构建的内容）→ 创建完整页面
   • 4 = 重要（深入的个人思考、战略性思考）→ 创建内容丰富的页面
   • 5 = 定义性内容（身份探索、突破性见解）→ 完整记录
2. 提取实体 — 讨论的人物、公司和概念
3. 记录原创思考 — 用户的原话就是信号。绝不要改述。
4. 按主要主题归档 — 不要全部丢进“conversations/”文件夹。关于某个人的对话归入 people/，关于某个概念的对话归入 concepts/，依此类推。

质量规则

仅导入评分为 3+ 的对话。大脑要传递信号，而不是噪声。

阶段 6：X/Twitter 档案

你的公开立场和互动模式。 Twitter 能揭示用户的想法、互动对象，以及他们正在公开探讨的观点。

数据来源

1. Twitter 数据导出（Settings → Your Account → Download Archive）
   • 包含所有推文、点赞、私信和书签
2. 实时 API（如可用）——近期推文和互动
3. 书签——经过筛选的信号，价值很高

大脑结构

brain/media/x/{handle}/
├── x-log.md                     ← compiled truth (themes, voice, key threads)
├── daily/YYYY-MM-DD.md          ← daily tweet log
├── monthly/YYYY-MM.md           ← monthly rollup
└── bookmarks/                   ← saved/bookmarked content

处理

• 原创推文 → 完整记录上下文，提取实体
• 引用推文 → 记录用户的评论和原推文
• 串文 → 重构为一个完整叙事
• 书签 → 高信号筛选内容，导入时添加标签
• 点赞——信号较弱，除非用户需要，否则跳过

阶段 7：文件档案

历史文档、旧作品、带元数据的照片。 这是长尾内容——结构较松散，但可能极具价值（旧日记、信件、早期作品）。

交由 archive-crawler 技能处理。它负责：

• 遍历目录结构
• 筛选高价值内容（用户自己的作品，而非安装程序）
• 从 PDF、图像（OCR）和文档中提取文本
• 提取实体并创建大脑页面

安全检查： 遍历档案可能耗时较长，并创建大量页面。 archive-crawler 是一项技能，而非 CLI 命令——除非 gbrain.yml 中存在明确的 archive-crawler.scan_paths: 允许列表，否则它不会运行。将档案路径添加到允许列表，先运行该技能的扫描流程，并在继续完整导入前向用户展示清单。

支持的数据源：

• 本地目录（Dropbox 同步文件夹、Google Drive、旧硬盘）
• 通过挂载路径访问的云存储（Backblaze B2、S3）
• 邮件档案（PST、mbox、EML、Google Takeout）
• 数据导出（LinkedIn、Facebook 等）

阶段 8：会议转录文本

从录制通话中获取深入的关系背景。 如果用户使用会议录制服务（Circleback、Otter、Fireflies、Read.ai），请导入近期转录文本。

交由 meeting-ingestion 技能处理。关键规则：

• 始终获取完整转录文本，而不仅是 AI 摘要
• 实体传播是强制要求——每位参会者都要更新时间线
• 只有更新所有实体页面后，会议才算完成导入

引导完成后的检查清单

完成所有可用阶段后：

1. 检查大脑状态：

   gbrain doctor --json
   gbrain stats
   

2. 测试检索：

   gbrain query "who do I meet with most often?"
   gbrain query "what am I working on?"
   gbrain search "<person from contacts>"
   

3. 设置实时同步（如尚未设置）：

   • 日历：每日 cron
   • 邮件：定期扫描（4-8 小时）
   • X：每日导入
   • 大脑仓库：每 5-30 分钟运行一次 gbrain sync --repo <path>。托管式大脑（gbrain sources writer status --json 显示 "mode": "managed"）不允许使用该命令：请按照 skills/cron-scheduler/SKILL.md（“Managed brain”）中的托管方案，使用 --source <id>，例如每 15 分钟在所有者主机上运行一次 gbrain sources refresh <id>; gbrain sync --source <id> --no-pull --hard-deadline 13m

4. 跟踪状态：

   // ~/.gbrain/cold-start-state.json
   {
     "started": "2026-01-15T10:00:00Z",
     "credential_gateway": "clawvisor",
     "phases_completed": [1, 2, 3, 4],
     "phases_skipped": [6, 7],
     "total_pages_created": 847,
     "total_entities_linked": 1203,
     "next_phase": 5
   }
   

5. 告知用户接下来该做什么：

   “你的大脑中有 N 个页面，涵盖人物、日历、邮件和对话。 已为 [sources] 配置实时同步。接下来：

   • signal-detector 会从每次对话中捕获实体
   • briefing 技能可以汇总每日背景信息
   • daily-task-prep 技能负责规划每日安排
   • 说‘enrich [person]’即可深入了解任何联系人”

出错时如何处理

对于任何 gbrain 错误 code、退出码、[AGENT] 块或提示块，请遵循 agent operator protocol。本技能的具体要求如下：

• 每个导入阶段都由用户选择：当命令以退出码 3（confirmation_required）退出或打印 [AGENT] 询问时，转述 [SHOW USER] 块并等待；不要使用 --yes 连锁执行各阶段。
• gbrain google setup 会打印 [SHOW USER] 步骤：请原样转述，并等待用户完成授权确认点击。凭证错误会附带各自的 fix，请遵照执行。
• 导入后首次执行 gbrain query 时若结果为空并带有降级提示，说明嵌入功能已关闭或仍在回填，导入可能已成功。在告诉用户导入失败之前，请先检查 gbrain doctor --json。

反模式

• 向 Agent 提供原始 OAuth 令牌。 这是头号反模式。持有原始 Gmail/Calendar 令牌的 Agent 是不受控的攻击面，一次提示词注入就可能让整个 Google 账户暴露。请使用 ClawVisor。如果用户拒绝 ClawVisor，则跳到离线导入。切勿将直接 OAuth 作为备选方案提出。
• 不加筛选地批量导入所有内容。 知识库应收录信号，而非噪声。应过滤掉自动化发件人、营销邮件和无用的对话。
• 导入时不做实体交叉关联。 每次导入都应识别实体，并更新已有的知识库页面。孤立的导入无法产生累积效果。
• 未征得用户同意即执行。 每个阶段都应作为一项选择呈现给用户。用户可能不希望导入其私信或心理咨询对话。
• 将所有内容都按显著性 1 导入。 并非每段对话都值得创建知识库页面。请使用显著性量表，跳过无用内容。
• 为自动化发件人创建人物页面。 Sentry、GitHub 通知、新闻邮件平台都不是人。请根据阶段 4 中的规则进行过滤。

恢复流程

如果会话中断：

1. 读取 ~/.gbrain/cold-start-state.json
2. 跳过已完成的阶段
3. 从 next_phase 恢复
4. 用户无需重复凭证设置，也无需重新导入已完成的数据源

输出格式

每个阶段完成后：

PHASE N COMPLETE: [source name]
================================

Pages created: N
Pages updated: N
Entities linked: N
Time elapsed: N min

Sample pages:
- people/jane-smith.md (created — 3 emails, 5 meetings)
- companies/acme-corp.md (updated — 2 new employees linked)

Next: Phase N+1 — [description]. Ready to proceed?

所用工具

• search — 创建前检查是否已有页面
• query — 用于实体去重的混合搜索
• get_page — 读取已有页面以做合并决策
• put_page — 创建和更新知识库页面
• add_link — 交叉引用实体
• add_timeline_entry — 在实体时间线上记录事件
• sync_brain — 每个阶段完成后将变更同步到索引