larkdoc

README

larkdoc

飞书文档全文搜索 CLI：把你有权限的全部飞书文档（云盘 + 知识库 + 他人分享）连同正文同步到本地，然后交互式模糊搜索标题和正文，回车直接在浏览器打开。

安装

Windows（推荐）

从 Releases 下载 larkdoc_<版本>_windows_amd64_setup.exe 并运行。安装程序会自动把 larkdoc 加入当前用户的 PATH，无需手动配置；安装完成后重新打开命令提示符或 PowerShell，即可直接运行：

larkdoc version

也可以在 PowerShell 中一键安装最新版（同样会自动配置用户 PATH）：

irm https://raw.githubusercontent.com/ChrisZou/larkdoc/main/scripts/install.ps1 | iex

PATH 变更会立即作用于安装脚本所在的 PowerShell；已经打开的其他终端需要重新打开。

macOS / Linux / Go

go install github.com/chriszou/larkdoc@latest

或从源码构建：

go build -ldflags "-s -w" -o larkdoc .

依赖

• lark-cli：同步时通过它调用飞书接口

npm install -g @larksuite/cli
lark-cli auth login   # 按提示完成飞书授权

使用

larkdoc          # 交互式全文搜索（启动时后台自动增量同步，状态栏显示进度，完成后热更新结果）
larkdoc sync     # 增量同步元数据 + 正文到 ~/.larkdoc/（只核对/拉取有变化的文档）
larkdoc sync --full  # 全量重建索引（清理已删除/取消共享的文档时使用）
larkdoc list     # 以 TSV 打印索引：title / type / updated / url
larkdoc alfred [query]  # 输出 Alfred Script Filter JSON（供 Alfred workflow 调用）

搜索界面（输入框在顶部）：

• 启动即可搜（用本地旧索引），后台增量同步，状态栏显示 ⟳ 进度 / ✓ 结果 / ⚠ 失败，同步到变化后自动热重载索引并保持当前搜索词
• 输入即过滤，多个关键词用空格分隔，AND 语义、大小写不敏感，同时匹配标题和正文
• 排序两级：命中标题的关键词数（标题命中永远优先）→ 更新时间倒序（同层里最近改过的靠前）；空查询按更新时间倒序
• 左侧结果列表，右侧预览窗显示文档信息 + 命中行上下文（关键词高亮，▶ 标记命中行）
• ↑↓ / Ctrl-P/N 选择，Enter 打开文档并打印 URL，Esc 退出

Alfred workflow

./alfred/build.sh            # 生成 larkdoc.alfredworkflow
open larkdoc.alfredworkflow  # 导入 Alfred

• lk <关键词>：全文搜索（空格分隔多关键词，AND 语义），回车打开文档，⌘↩ 复制链接；空查询按更新时间列出最近文档
• lksync：手动增量同步，完成后弹系统通知
• 索引超过 30 分钟未更新时，搜索会自动在后台拉起一次增量同步（10 分钟冷却，避免反复触发）
• workflow 内置 PATH 探测：~/.local/bin、~/go/bin、Homebrew 路径下的 larkdoc 均可被找到

开发

go test ./...

实现说明

• 元数据走 lark-cli drive +search --query ""（空查询按过滤器浏览）+ page_token 分页
• 元数据增量：本地已有索引时加 --sort edit_time 按编辑时间倒序翻页，翻到整页都是已知且未变化的文档即提前停止，结果合并进旧索引；增量感知不到删除/取消共享，也可能漏掉“很久没编辑但新共享给我”的文档，定期 sync --full 纠正
• 正文走 lark-cli docs +fetch --doc-format markdown，只拉 DOCX 类型（多维表格/电子表格/文件仅标题可搜）；wiki 节点 token 可直接 fetch
• 正文缓存在 ~/.larkdoc/content/<token>.md，按 update_time 增量同步，manifest 记录在 content-meta.json
• 飞书接口有频率限制（99991400）：3 并发 + 每请求 200ms 间隔 + 指数退避重试（最多 6 次）；lark-cli 出错时错误 JSON 在 stderr，成功结果在 stdout
• 个别文档标题含裸控制字符，JSON 解析前先清洗
• TUI 用 bubbletea 实现；对带 ANSI 颜色的文本先截断/补齐再上色，避免宽度计算错乱（CJK 宽度用 go-runewidth）

License

MIT