在 Claude Code 里调 Obsidian CLI 读写知识库
Obsidian v1.12.4 起官方 CLI 全量上线,让 Agent 通过 Bash 直接调 obsidian 命令毫秒级读写 vault,附 Agent 提示词模板与对比 MCP 路径的取舍
在 CLI Agent 里接入第三方工具的决策框架 —— 何时直接 Bash 调外部 CLI,何时走 MCP server,含主流工具速查表
内容摘要
把"让 AI Agent 操作第三方工具(飞书、Obsidian、GitHub、Notion …)"这件事拆开看,2026 年现实里**只有两种被反复使用、能撑起生产场景**的集成路径:
把"让 AI Agent 操作第三方工具(飞书、Obsidian、GitHub、Notion …)"这件事拆开看,2026 年现实里只有两种被反复使用、能撑起生产场景的集成路径:
这两条路不是「替代关系」,更像是 「同一个能力,按客户端形态做的两种适配」。它们的工作方式差别很大:
两条路的核心机制差别可以浓缩成三句话:
CLAUDE.md / Skills 里被告知,就知道怎么用;调不动时还能 --help 现场学。MCP 下,工具列表在握手阶段就喂给模型,常驻在每次请求的上下文里。这两条路也不是 2026 年才出现的发明。CLI 直调一直是 Unix 工具组合的传统玩法,只是过去 AI Agent 不擅长,最近一年模型对命令行参数的理解能力质变之后才成为主流;MCP 则是 Anthropic 2024-11 发布的开放协议,目标是解决「N 个 AI 应用 × M 种数据源」的 N×M 集成困境。本卡讨论的是站在 CLI Agent 用户的视角,怎么选。
| 要素 | CLI 直调路径 | MCP server 路径 |
|---|---|---|
| 发现机制 | 模型先验知识 + CLAUDE.md / Skills 提示 + 现场 --help | 启动时 tools/list 注册到上下文 |
| 常驻 token 成本 | 几乎零,按需调用才进上下文 | 工具 schema 持续占用,工具越多越贵 |
| 跨客户端能力 | 只支持有 Bash 工具的终端 Agent | 任意 MCP Host 都能复用 |
| 状态/鉴权 | CLI 自己管,通常用 OS Keychain / 本地配置文件 | Server 自己管,可以接 OAuth、Token、本地配置 |
| 链路长度 | Agent → Bash → CLI → 服务,最短 | Agent → MCP Client → MCP Server → 服务,多一跳 |
| 错误处理 | 看 stdout/stderr,模型自己解析 | Server 返回结构化错误,模型按 schema 处理 |
| 更新节奏 | 工具方一发版本就有,命令向后兼容性高 | 要等 server 跟进,schema 变更可能破坏现有调用 |
不要一上来就纠结"哪条路更好"。用下面的五问法跑一遍,答案自然出来:
逐问解释一下:
① 工具有官方 CLI 吗?
有,且 Agent 能跑 Bash,CLI 就是默认选项。2026 年起官方 CLI 的设计开始大量为 Agent 优化(--help 自描述、--dry-run 预演、结构化输出),调用成功率比早些年高得多。注意"官方"二字——社区 CLI 可以试,但要先看维护活跃度,否则后期升级要痛苦地自己 fork。
② 是否需要跨多个 AI 客户端复用? 团队里既有 Claude Code 用户、又有 Cursor / Claude Desktop 用户时,「让所有人都能用」往往比「让 CLI Agent 用得最快」优先级更高。MCP 的核心价值就是这个——一个 server 喂所有 Host。如果你只有 Claude Code 一种客户端,这一问可以直接跳过。
③ 调用是否需要 LLM 二次推理结果? CLI 直调返回的是 stdout 字符串,模型直接读;MCP 返回结构化 content(含 type/mimeType),适合直接当成「另一个工具的输入」继续推理。如果你要做的是"查多维表 → 模型理解 → 再写一行回去"这种链式操作,MCP 的结构化返回更顺;如果只是"列出 5 个文件名给我看看",CLI 直接 echo 就够用。
④ 是否需要语义检索 / 向量? 向量检索、跨文档理解这类「重 LLM 推理」的能力,MCP server 内部可以预处理(embed、rerank、压缩),把已经"消化过"的结果回给模型;纯 CLI 通常只能返回 raw 文本,模型自己消化。这种场景 MCP 占优。
⑤ 性能 / 延迟敏感度? 本地链路(Obsidian、文件系统、git)几乎都是毫秒级,MCP 多一跳的影响很小,但 CLI 链路更短、token 更省(参考 Maksym Prokopov 在 4663 篇 vault 实测:CLI search 0.32s vs grep 1.95s,orphan 检测 token 从 ~7M 降到 ~100,便宜 70000 倍)。远程服务(GitHub、Notion)两条路差别不大,主要看接口质量。
记不住流程图也没关系,记住这组口诀就够日常用:
具体到主流工具,看下一节的速查表。
把视野放宽一点,"在 Agent 里接入第三方工具"其实有四种可能:CLI 直调、MCP server、直调 OpenAPI、Skills 自定义工具。下面这张表是本卡的主对比表:
| 维度 | CLI 直调 | MCP server | 直调 OpenAPI / SDK | Skills 自定义工具 |
|---|---|---|---|---|
| 协议层 | OS shell + 子进程 | JSON-RPC 2.0 over stdio / Streamable HTTP | HTTP / SDK call | 文本 prompt + 内嵌工具调用 |
| 谁先知道有什么工具 | 模型先验 + Skills/CLAUDE.md 提示,必要时 --help 现场学 | Host 启动时 tools/list 拉到上下文 | 由你写的胶水代码决定 | Skills 文件描述 + 调用约定 |
| 工具描述常驻 token | 几乎不占(只在被提示时进入) | 占用大,工具越多越显著 | 看你怎么写,通常不进 | 描述常驻(短),脚本只在需要时执行 |
| 跨客户端复用 | 仅终端 Agent(Claude Code / Codex CLI / Gemini CLI) | 任意 MCP Host | 你包一层就跨 | Claude Code 生态内通用,跨客户端要适配 |
| 链路长度 | Agent → Bash → CLI(最短) | Agent → MCP Client → MCP Server → 服务 | Agent → 你的脚本 → HTTP 调用 → 服务 | Agent → Skill 脚本 → CLI / API |
| 典型用途 | 本地工具、个人场景、性能敏感 | 跨客户端、需结构化语义返回、企业 SaaS | 开发自己的后端服务时 | 把多步流程封装成一条命令 |
| 维护谁出力 | 工具方 | 工具方或社区 | 你 | 你(或团队共享) |
| 失败成本 | 低,stdout 可读 | 中,要看 server 实现质量 | 看你写的胶水 | 看你写的 Skill 质量 |
| 何时最值** | 有官方 CLI + 终端 Agent | 跨客户端 + 需要 schema 结构化 | 自建服务 + 不依赖 Agent 标准 | 把高频组合操作沉淀给团队复用 |
核心区别一句话:
/feishu-weekly-digest 入口。下面这张表覆盖 10 个最常被问"该走哪条路"的工具,官方 CLI / 官方 MCP / 推荐路径 / 理由四列:
| 工具 | 官方 CLI | 官方 MCP | 推荐路径 | 理由 |
|---|---|---|---|---|
| Obsidian | ✅ v1.12.4(2026-02-27 GA) | ⚠️ 仅社区(cyanheads/obsidian-mcp-server) | CLI 优先 | 本地 vault + 本地 Agent,IPC 毫秒级;token 比 grep 便宜 ~70000 倍。详见 /cli/cards/obsidian-from-cli-agent |
| 飞书 / Lark | ✅ @larksuite/cli v1.0.16(2026-03-28 开源,200+ 命令、22 个 AI Skills) | ✅ larksuite/lark-openapi-mcp | CLI 优先(终端 Agent)/ MCP(其他客户端) | 官方明确两者互补:CLI 给 Claude Code/Codex;MCP 给 Cursor/Desktop。详见 /cli/cards/feishu-from-cli-agent |
| GitHub | ✅ gh CLI(成熟,多年迭代) | ✅ 官方 GitHub MCP Server | gh CLI 优先 | gh 自描述能力强、--json 输出友好、和本地 git 仓库天然耦合;只在 Cursor/Desktop 场景才回 MCP |
| Linear | ✅ linear-cli(社区为主,覆盖核心功能) | ✅ 官方 MCP | 二选一,看客户端形态 | 终端 Agent 用 CLI,跨客户端团队走 MCP;MCP 的 schema 对 Linear 的字段建模更清晰 |
| Notion | ❌ 仅 SDK,无成熟用户级 CLI | ✅ 官方 + 多个社区 MCP | MCP 优先 | 没有官方 CLI 这条路根本不存在;MCP 服务端能把"页面/数据库"的结构 schema 清楚 |
| Slack | ❌ 无开发者用户级 CLI(仅有内部运维 CLI) | ✅ 社区 MCP(Slack 官方 SDK 之上) | MCP 优先 | 同 Notion,CLI 路径不可达;Slack 这种"流式消息源"也更适合 server 端预处理 |
| Git | ✅ 系统命令(成熟到不需要解释) | ✅ 社区 MCP(实际罕用) | 直接调命令 | 模型对 git 命令的先验知识极强,连 --help 都很少要看;MCP 包装是过度设计 |
| 文件系统 | ✅ 系统命令(ls/cat/grep/find)+ ripgrep | ✅ Anthropic 官方 filesystem MCP server | CLI 优先(终端 Agent)/ MCP(Claude Desktop 等) | Claude Code 自带 Read/Edit/Glob/Grep 工具,已经是文件系统的"内置 CLI";Desktop 没这套,才需要 MCP |
| PostgreSQL | ✅ psql | ✅ 社区 MCP | 看任务:探索/写脚本用 psql;让 Agent 自助跑 SQL 用 MCP | psql 适合写好脚本批量跑;MCP 适合"模型理解 schema 后构造 SQL 再回写"的链式推理 |
| 浏览器(Playwright) | ✅ Playwright CLI / npx playwright codegen | ✅ 微软官方 Playwright MCP | MCP 优先 | 浏览器是"长期会话 + 结构化 DOM 反馈",MCP 的 server 能维持浏览器实例,CLI 起停成本太高 |
读这张表的方式:先看"有/无官方 CLI",再看"客户端能不能 spawn shell",剩下的细节按场景判断。
| 误区 | 准确理解 |
|---|---|
| 以为有了 MCP 就不再需要 CLI | 完全不对。MCP 解决"跨客户端 + 标准化发现",不解决"链路最短 / token 最省"。CLI Agent 在本地工具上仍然是 CLI 直调更优。两者是互补,不是替代 |
| 以为 CLI 直调没有"工具描述"模型就不会用 | 现代模型对常见 CLI(git/gh/ls/curl)有强先验;不熟的工具可以靠 CLAUDE.md / Skills 提示,或者运行时 tool --help 现学。真正的瓶颈是工具方有没有写出"Agent 友好"的 --help,不是机制本身 |
| 以为 MCP 一定更安全 | MCP 协议本身只规定通信格式,安全模型靠 Host 实现,不同客户端的权限粒度差异巨大。CLI 直调的安全性依赖 OS 用户/sandbox 边界,反而是更成熟的体系。两条路都可能踩坑,关键看你 review 工具/Server 源码的能力 |
| 以为 Skills 是 MCP 的替代品 | Skills 不是替代,是"组合层"。一个 Skill 内部可以调 CLI、可以调 MCP、可以两者都调。Skills 解决的是"高频多步流程的 prompt 沉淀 + 团队共享",和"工具发现协议"不在同一层 |
| 以为"工具描述常驻"是 MCP 的硬伤 | 在工具数 < 30 的小项目里几乎察觉不到。问题出在工具数膨胀(一个 Host 挂 10 个 server,每个 server 30 个工具,加起来上下文吃几千 token);这种场景才需要主动"按需启用 server"或者把高频流程沉到 Skills |
| 以为飞书 / Obsidian 这种工具方"该统一只做一条路" | 2026 年起趋势相反——头部工具方都在同时做 CLI 和 MCP,对应不同客户端形态。飞书官方明确 lark-cli 和 lark-openapi-mcp 是两条互补路线;Obsidian 虽然 MCP 是社区在做,但官方 CLI 优先的态度也很明确 |
| 以为社区 MCP / 社区 CLI 和官方一样可信 | 社区项目的更新节奏、安全审计、breaking change 频率都和官方差距很大。生产场景优先用官方实现;社区项目用之前至少 review 一遍 source、看一眼 issue 列表 |
if 工具方有官方 CLI and 你的 Agent 能 spawn shell:
if 跨客户端复用是核心需求:
两条路都装;CLI 给终端 Agent、MCP 给其他客户端
else:
默认 CLI(更短、更便宜、更原生)
elif 工具方有 MCP(官方或可信社区):
走 MCP
else:
直调 OpenAPI / 自己包一层 / 写 Skill
参考答案:
--json 输出能直接进 jq 管道,本地仓库天然集成,几乎不需要额外学习成本。Cursor/Desktop 那边再补 MCP 就行。通过这三个例子能看出五问法的实际样子:①②都是 yes 时按客户端分发,①是 yes 但只有一种客户端时走 CLI,①no 时走 MCP。
参考答案:两条路并行,按客户端分发,不要为了"统一"强制所有人走 MCP。
具体方案:
CLAUDE.md 里写明 lark-cli 命令速查表(参考 feishu-from-cli-agent 的"Agent 提示词模板"一节),让他们装 @larksuite/cli + npx skills add larksuite/cli -y -g。这是最快、最省 token 的路径。mcp.json 模板里挂 larksuite/lark-openapi-mcp,配上团队的飞书自建应用凭证。这是他们唯一能走的路径。为什么不"统一走 MCP"?因为这样会让 5 个 Claude Code 用户白白付出 token 成本和延迟,而 MCP 暴露的能力还是 lark-cli 的子集。CLI Wiki 反复强调的核心立场就是这条:有官方 CLI 时,对能调 Bash 的客户端走 CLI 是最优解,对不能调 Bash 的客户端兜底走 MCP,不要为了一致性强行降级。
参考答案:
反例一:超高频、固定参数的内部脚本
如果一个组合操作你每天要让 Agent 执行 50 次,而且参数模式很固定(比如"每次都把今天的 GitHub PR 拉出来 → 同步到飞书 → 更新多维表"),与其让 Agent 反复推理"该调哪个工具、参数怎么填",不如写一个 Skill 或 shell 函数把这套流程固化。Skill 内部完全可以同时调 gh CLI 和 lark-cli,对 Agent 暴露的只是一个简化入口。这种场景"集成路径"已经不是问题,问题是"组合层"。
反例二:极端 token / 性能敏感的场景
某些场景两条路都太贵:比如要让 Agent 实时分析一个 50 GB 的本地数据库,CLI 输出会瞬间打爆 context window,MCP server 也会陷入"序列化 → 反序列化"的开销。这种场景该走的是**"让 Agent 写脚本 → Bash 跑 → 只把摘要回流"**,而不是任何形式的"工具调用"。本质是把"AI 推理"和"重计算"在工程上彻底分离,工具集成的两条路都不适用。
反例三:工具方主动反对自动化
某些 SaaS(包括部分国内企业 IM)会通过 ToS / API 限速 / 鉴权策略主动反对"未经授权的自动化客户端"。如果硬接 CLI 或 MCP,可能违反服务条款、被风控封号。这种场景的"集成路径"应该是"先做合规评估 → 如有必要走官方机器人 + Webhook 这种被允许的扩展点",而不是技术层面挑两条路。
总结一下,"CLI vs MCP"这个问题的预设是 "工具能被自动化、且场景适合让 LLM 直接驱动"。当这个预设不成立时,再纠结这两条路的取舍就走偏了——该想的是"要不要把这个能力做成 Skill"、"要不要把它从 LLM 推理里彻底拿出来"、"要不要走另一条合规通道"。
优先展示同分类且标签更接近的内容,方便继续串联学习。
Obsidian v1.12.4 起官方 CLI 全量上线,让 Agent 通过 Bash 直接调 obsidian 命令毫秒级读写 vault,附 Agent 提示词模板与对比 MCP 路径的取舍
飞书 2026-03 开源官方 lark-cli(200+ 命令、20+ AI Skills)让 Agent 操作消息/文档/多维表,对比官方 lark-openapi-mcp 的取舍
用 git worktree 跑多个并行 CLI Agent,避免分支切换打断上下文,含 worktree 管理、Agent 隔离与合并策略