gety-cli

用法

/gety-cli <natural language query>

示例

/gety-cli What docx files have I updated in the last 24 hours?
/gety-cli Find meeting notes about the Q1 roadmap
/gety-cli Search for PDF documents related to security review in my Work folder
/gety-cli What's in my notes about the design system?
/gety-cli Show me the latest documents I've worked on
/gety-cli What data sources do I have connected?
/gety-cli Add ~/Documents/projects as a data source

工作流

- [ ] Step 1: Verify gety and discover data sources ⛔ BLOCKING
- [ ] Step 2: Translate query to gety command(s)
- [ ] Step 3: Execute and iterate
- [ ] Step 4: Read specific documents (conditional)
- [ ] Step 5: Synthesize findings ⚠️ REQUIRED

步骤 1：验证 gety 并发现数据源 ⛔ 阻塞

运行 gety connector list（或运行 gety connector list --kind all 以查看文件夹和自定义连接器）。

• 有输出 → 继续。保留返回的连接器名称，供后续步骤用作 -c 筛选值。
• 找不到命令 → 告诉用户从 Gety 桌面应用设置中安装 Gety CLI。不要尝试运行任何 gety 命令。
• 没有连接器 → 告诉用户先添加数据源（文件夹使用 gety connector add <path>，自定义连接器使用 gety connector install <dir>）。

步骤 2：将查询转换为 gety 命令

解析用户的自然语言查询，并将其映射到 gety CLI 标志：

用户意图	对应参数
文件类型（“docx 文件”“PDF”）	-e <ext>
数据源（“来自 Work 文件夹”“在我的笔记中”）	-c "<connector_name>"
时间范围（“过去 24 小时”“本周”）	--update-time-from / --update-time-to（ISO 8601）
最近程度（“最近”“最新”）	--sort-by update_time --sort-order descending
主题或关键词	<query> 字符串
按标题搜索（“名为 X”“标题为 X”）	--match-scope title
列出数据源	→ gety connector list（--kind fs / --kind custom / --kind all）
查看连接器详情	→ gety connector show <id>
添加文件夹数据源	→ gety connector add <path> [--name <name>]
安装自定义连接器	→ gety connector install <directory> [--config <file>]
配置连接器	→ gety connector configure <id> [options]
重启连接器	→ gety connector restart <id>
同步 / 轮询连接器	→ gety connector poll <id>
启用 / 禁用连接器	→ gety connector enable <id> / gety connector disable <id>
移除数据源	→ gety connector remove <id> ⚠️ 先向用户确认

时间计算：如果查询提及相对时间（“过去 24 小时”“本周”），请根据当前日期 / 时间计算 ISO 8601 时间戳。

转换示例

查询	命令
“过去 24 小时内我更新了哪些 docx 文件？”	gety search "" -e docx --sort-by update_time --sort-order descending --update-time-from <24h ago>
“查找有关 Q1 roadmap 的会议记录”	gety search "Q1 roadmap meeting notes"
“Work 文件夹中有关 security 的 PDF”	gety search "security" -c "Folder: Work" -e pdf
“我有哪些数据源？”	gety connector list --kind all
“检查自定义连接器状态”	gety connector show <connector_id>

步骤 3：执行并迭代

运行转换后的命令。如果结果不理想：

• 无关结果太多 → 添加筛选条件（-c、-e、--match-scope）
• 结果太少 → 扩大查询范围，尝试同义词，移除筛选条件
• 需要更多结果 → 使用 --offset 翻页
• 需要结构化数据以供后续处理 → 添加 --json 并将输出通过管道传给 jq

步骤 4：读取特定文档（按需）

需要文档内容时：

gety doc <connector_id> <doc_id>

• 从搜索结果中提取 connector_id 和 doc_id
• 只读取能补充现有信息的文档
• 对于大量结果，先读取最相关的前 3-5 个

⚠️ 处理大型文档（上下文窗口保护）

gety doc 会输出完整文档内容。大型文件（篇幅很长的 PDF、书籍、日志、大型数据转储）可能会产生海量输出，占满上下文并浪费 token。

处理大型文件的最佳实践：

1. 保存到临时文件，然后使用工具搜索（推荐）： 将输出重定向到文件，并使用 grep、rg 或 head 查看相关部分：

   gety doc <connector_id> <doc_id> > /tmp/gety_doc.txt
   grep -i -C 3 "keyword" /tmp/gety_doc.txt
   head -n 50 /tmp/gety_doc.txt
   

2. 对分页文档使用页面范围： 如果文档有页面（例如 PDF），使用 --page-start 和 --page-end 限定范围：

   gety doc <connector_id> <doc_id> --page-start 1 --page-end 5
   

3. 片段足够时避免读取全文： 如果 gety search 的搜索结果已提供足够的上下文，就不要获取完整文档。

第 5 步：综合整理结果 ⚠️ REQUIRED

• 整合多份文档中的信息，形成连贯的回答
• 引用来源文档（名称或路径），让用户了解信息的出处
• 如果没有找到相关结果，请明确说明，并建议其他搜索词
• 切勿粘贴原始 gety 输出——始终用自然语言进行综合整理

反面模式

• ❌ 不经综合整理，直接倾倒原始 gety 输出
• ❌ 将大型文档的全部内容倾倒到对话上下文中——应保存到文件，然后使用 grep 搜索，或通过 --page-start/--page-end 分页
• ❌ 阅读搜索结果中的每一份文档——只阅读所需内容
• ❌ 只尝试一次搜索就放弃——尝试其他查询和筛选条件
• ❌ 使用 CLI 范围之外的命令（仅限 search、doc、connector）
• ❌ 要求用户手动运行 gety 命令——直接运行

参考资料

加载 references/cli-capabilities.md，查看完整的 CLI 选项、标志和示例。