Agent 编排层薄自建优先于重型框架

更新于 2026-07-20

**给本地优先的桌面 App 接 Agent，先自建一层很薄的编排层，不要直接引入 LangChain / LangGraph / AutoGen 这类重型框架 —— 当能力边界很明确（读笔记、读文件、写笔记）时，权限边界比「框架功能丰富」更重要。** 这里的「自建」不是自己训练模型，也不是从零写 LLM，而是自己定义工具、权限、上下文与错误处理。

薄自建层要自己定义什么

  • Agent 能调用哪些工具：list_notes、read_note、read_file、write_note
  • 工具怎么接 Tauri / vault / 文件系统
  • 写入前要不要用户确认
  • 上下文怎么塞：当前笔记、选中文件、搜索结果
  • 错误怎么显示：没权限、文件太大、笔记冲突、写入失败

优点是贴合「本地优先、文件是真相源、写笔记走现有 vault 契约、API key 运行时配置」，代码量可控，第一版不被框架抽象绑住。代价是高级能力要自己补：多步计划、任务队列、长程记忆、工具重试。

开源框架的适用面与代价

框架的价值在复杂任务流：例如「扫描整个知识库 → 找主题 → 生成报告 → 拆成多篇笔记 → 反复修订」，这时 agent graph、memory、workflow、multi-agent、观测调试确实省事。

代价是：多数框架默认服务端 / 云端思路，和 Tauri 桌面、本地文件权限、vault 原子写入、前端状态机不完全贴合；还会引入依赖、抽象层与调试成本。最危险的是写文件 / 写笔记这类能力被框架包装得太深后，权限边界会变模糊。

推荐路线：混合

  • 不接完整开源 Agent App，也不引入重型 agent framework
  • 复用现有 AI SDK / 模型的 tool calling 能力
  • 自己定义工具层、权限层、笔记读写层、UI 状态
  • 将来真要复杂工作流，再单独评估是否引入「流程图式编排」（如 LangGraph）

这样第一版能快，架构也不会死。

要不要做「统一 engine」：按 provider × 平台定价

同一个判断在「多 agent 接入」上的翻版：抽象层的成本正比于「要覆盖的 provider 数 × 平台数」，而不是正比于「架构看起来是否优雅」。 只有 Claude Code + Codex 两个 provider、电脑 server + 手机 App 两个入口时，做完整 engine（provider 切换、平台 adapter、command engine）是过度设计；保留两个原生 bridge、只抽极小的共享 helper 就够。反过来，要做 10+ agent、13 个平台、多用户权限时，engine 才回本。

判据：先数清楚要覆盖的组合数，再决定抽象层级；抽象本身不产生价值，覆盖组合数才产生价值。

修正：复用成熟 harness 的底层，只自建业务边界

后续讨论把「薄自建」的边界校准得更精确 —— 判据是这项能力是不是业务专属：

  • 不该自建（直接复用底层）：多 provider 协议、流式输出、tool call / tool result 标准化、参数校验、思考等级、provider 重试与超时、prompt cache、token 用量与成本计算、API Key / OAuth 凭据管理、fake provider 测试。自己写一遍只会把时间耗在各家 tool calling 的差异上。
  • 必须自建：Skill 注册与权限、用户权限、Action 提案与确认、删除到废纸篓之类的业务规则、数据库状态、prompt 与可观测、产品专属上下文检索。
  • 仍然不要做的：把整个系统交给 LangGraph / Mastra 全家桶。它们功能全，但会和已有的 PostgreSQL 对话 / Action / Cron / 可观测平台形成两套状态系统，而这里要跑的并不是数小时的复杂研究 Agent。

另一条容易误判的边界：「调用了别人的 Tool Loop」不等于「有了自己的 harness」。 ToolLoopAgent + 固定系统提示词 + 硬编码工具，只是调用了框架提供的 loop；harness 的其余部分（记忆、技能注册表、上下文工程、运行生命周期）仍然是缺的（见 Agent Harness 不只是 Tool Loop）。

相关