Grain Crawler Free

SKILL.md

---
slug: grain-crawler-free
name: grain-crawler-free
version: 1.0.0
displayName: 归档检索(免费版)
summary: 本地 Granola 归档检索，支持笔记搜索、详情查看、新鲜度检查。
license: Proprietary
edition: free
description: '本地 Granola 归档检索，支持笔记搜索、详情查看、新鲜度检查。核心能力：

  - 基于本地归档数据优先检索，避免频繁联网

  - 笔记关键词搜索与详情读取

  - 归档新鲜度检查，提示是否需要刷新

  - 结构化 JSON 输出，便于 Agent 后续格式化


  适用场景：

  - 会议笔记与要点快速检索

  - 个人知识库离线查询

  - 团队会议纪要归档管理

  - 研究资料片段定位


  差异化：优先使用本地缓存降低外部依赖，配合新鲜度提示让用户决定何时刷新，免费版聚焦"查得到、读得快"的核心场景'
tags:
- 集成工具
- 知识管理
- 个人效率
tools:
- - read
- exec
homepage: https://skillhub.cn
pricing_tier: "L2-标准级"
pricing_model: per_use
suggested_price: "19.9 CNY/per_use"
tools: ["read", "exec", "glob", "grep"]
tags: "工具,效率,自动化"
---
# 归档检索（免费版）

## 概述

本 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 执行任务，依赖本地归档数据