Grain Crawler Free

基于本地Granola归档数据，支持会议笔记关键词搜索、详情查看及归档新鲜度检查，优先本地响应避免频繁联网。

归档检索（免费版）

概述

本 Skill 帮助 Agent 基于本地 Granola 归档数据完成笔记检索与详情查看。核心理念是"本地优先"：先用本地缓存响应查询，仅在数据过期或用户明确要求时才触发同步。免费版聚焦个人用户"快速查到会议要点"的场景，提供搜索、详情、新鲜度三大基础能力。

核心能力

能力	说明	免费版支持
本地优先检索	先用本地归档响应，避免联网	是
笔记搜索	关键词检索笔记列表	是
笔记详情	读取单条笔记完整内容	是
新鲜度检查	检测归档是否过期	是
结构化输出	JSON 格式输出	是
数据同步	从云端拉取最新归档	否（专业版）
SQL 查询	跨笔记 SQL 统计	否（专业版）
转录稿读取	读取会议转录稿	否（专业版）
面板数据	读取侧边面板内容	否（专业版）
批量导出	批量导出笔记	否（专业版）

核心功能执行

用input_params参数进行配置。

输入: 用户提供核心功能执行所需的指令和必要参数。 处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回核心功能执行的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置。

输入: 用户提供参数配置与调用所需的指令和必要参数。 处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志。

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置。

输入: 用户提供结果处理与输出所需的指令和必要参数。 处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志。

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：Granola、归档检索、支持笔记搜索、详情查看、核心能力、基于本地归档数据、避免频繁联网、笔记关键词搜索与、详情读取、归档新鲜度检查、提示是否需要刷新、Agent、后续格式化等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

1. 会议要点快速回顾：开会前用关键词检索上次同主题会议笔记，快速回顾决议与待办。
2. 个人知识库离线查询：在无网络环境下检索已同步的笔记，不受网络波动影响。
3. 研究资料片段定位：跨多份会议转录稿定位某个技术话题的讨论片段。
4. 团队纪要归档查阅：查阅历史团队会议纪要，定位责任人与时间节点。

不适用场景

以下场景归档检索(免费版)不适合处理：

• 实时流数据处理
• 小规模数据手动分析
• 非结构化文本情感分析

触发条件

需要数据分析、报表生成、统计洞察、数据可视化时使用。不适用于非本工具能力范围的需求。

快速开始

上手时间：< 60 秒。本 Skill 假设本地已存在 Granola 归档数据。

Step 1：检查归档新鲜度

bash

grain-crawler doctor --json
grain-crawler status --json

Step 2：搜索笔记

bash

grain-crawler search "季度规划"

Step 3：读取笔记详情

bash

grain-crawler note get <note-id>

Step 4：查看输出结构

搜索返回 JSON 数组，每个元素包含笔记 ID、标题、更新时间与摘要片段。

示例

常用命令速查

命令	用途	示例
doctor	环境与健康检查	grain-crawler doctor --json
status	归档新鲜度状态	grain-crawler status --json
search	关键词搜索	grain-crawler search "关键词"
note get	读取单条笔记	grain-crawler note get <id>

输出字段说明

字段	类型	说明
note_id	string	笔记唯一标识
title	string	笔记标题
updated_at	string	最后更新时间（ISO 8601）
summary	string	内容摘要片段
source	string	数据来源（local-cache / desktop-cache）

搜索返回示例

json

[
  {
    "note_id": "n_2026_0718_001",
    "title": "季度规划评审会议",
    "updated_at": "2026-07-18T10:30:00Z",
    "summary": "讨论 Q3 季度目标与资源分配...",
    "source": "desktop-cache"
  }
]

响应中 source 字段帮助判断数据新鲜度：desktop-cache 表示来自桌面端缓存，local-cache 表示来自本地归档。

最佳实践

1. 本地优先策略：所有查询默认走本地归档，仅在 doctor 显示数据过期超过 24 小时时提示用户刷新。
2. 关键词精炼：搜索时使用 2-4 个字的关键词，命中率高于长句。专业术语建议用英文原名。
3. 新鲜度提示：回答涉及"最近""最新"等时间敏感问题时，先运行 status 确认数据新鲜度，并在回答中标注数据截止时间。
4. 报告绝对日期：输出时间时使用绝对日期范围（如"2026-07-15 至 2026-07-18"），避免"昨天""上周"等相对表述造成歧义。
5. 读操作有界：单次读取笔记数控制在 20 条以内，避免一次性加载过多数据影响响应速度。
6. 优先标题检索：笔记标题通常含核心主题，标题匹配的命中率高于全文模糊匹配，建议先用标题关键词搜索。
7. 标注数据来源：回答中标注数据来自 local-cache 还是 desktop-cache，让用户了解数据新鲜度可信度。
8. 分段返回长文：笔记正文较长时分段输出，避免单次响应超长，便于用户逐段阅读。
9. 结合时间范围筛选：搜索时如能预知大致时间，先用 status 确认覆盖范围，避免遗漏过期数据。

常见问题

Q1：doctor 报告归档为空怎么办？

A：(1) 确认本地已安装 Granola 客户端并登录；(2) 至少完成一次桌面端缓存生成；(3) 免费版不支持主动同步，需在 Granola 桌面端手动刷新后重试。

Q2：搜索结果为空但笔记确实存在？

A：(1) 检查关键词拼写与大小写；(2) 尝试用笔记标题中的核心词搜索；(3) 本地索引可能未更新，建议在桌面端重新打开笔记触发索引刷新。

Q3：note get 报错 note-id 不存在？

A：(1) 确认 ID 从 search 结果中复制完整；(2) 笔记可能已被删除，重新搜索获取最新列表。

Q4：数据新鲜度如何判断？

A：status --json 返回 last_sync 字段，与当前时间差超过 24 小时视为"可能过期"。免费版会在回答中提示"数据可能非最新，建议刷新"。

Q5：免费版能否查看转录稿和面板？

A：免费版仅支持笔记正文检索。转录稿与面板数据需使用专业版。

Q6：本地缓存数据存储在哪里？

A：缓存路径由 Granola 桌面端决定，通常位于用户数据目录。doctor --json 会输出缓存路径与大小，可用于排查空间问题。

Q7：免费版支持多人共享归档吗？

A：免费版仅支持本地单用户检索。多人共享需使用专业版的云端同步与权限管理。

Q8：如何批量检索多个关键词？

A：免费版需逐个执行 search 命令。如需批量检索与结果合并，请使用专业版。

错误处理

错误场景(现象)	可能原因	解决步骤	优先级
归档为空	未登录 / 未生成缓存	桌面端登录并打开笔记生成缓存	P1
搜索无结果	关键词不匹配 / 索引未更新	调整关键词，桌面端重新打开笔记	P2
note get 报错	ID 不完整或已删除	重新搜索获取最新 ID	P2
数据过期提示	last_sync 超过 24 小时	桌面端手动刷新后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令	P3
doctor 异常	桌面端未运行	启动 Granola 桌面端	P1

已知限制

本免费体验版限制以下高级功能：

• 云端数据同步（专业版支持 private-api 与 desktop-cache 两种来源）
• 跨笔记 SQL 统计查询（专业版支持只读 SQL）
• 会议转录稿读取（专业版支持 transcripts get）
• 侧边面板数据读取（专业版支持 panels get）
• 批量导出与增量更新（专业版支持）

解锁全部功能请使用专业版：grain-crawler-pro

• 当前为免费版本,如需完整功能请升级到付费版获取全部能力

依赖说明

运行环境

• Agent 平台：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统：Windows / macOS / Linux（macOS 与 Granola 桌面端兼容性最佳）
• Python：3.8+（用于运行命令行工具，若使用 Python 封装）

依赖详情

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由 Agent 平台内置 LLM 提供
Granola 桌面端	应用	必需	官方渠道下载安装，用于生成本地缓存
grain-crawler CLI	命令行工具	必需	随 Skill 附带或按文档安装
Python 标准库	运行时	必需	Python 自带（json / subprocess）

API Key 配置

• Granola 账号：在桌面端登录即可，免费版无需额外 API Key
• 云端同步 Key（可选）：免费版不使用云端同步，无需配置 private-api 凭证

可用性分类

• 分类：MD+EXEC（纯 Markdown 指令，部分功能需要 exec 命令行执行能力）
• 说明：基于 Markdown 的 AI Skill，通过自然语言指令驱动 Agent 执行任务，依赖本地归档数据