LangGraph – 码农练功房

说明：Hermes 仓库里没有一句明确写下「我们不用 LangChain 因为……」的声明。
本文分两层：行业层面的普遍原因（通用分析）与 Hermes 代码中可实证看到的取向（有源码依据，标注出处）。

1. 前提：agent 循环的内核其实很简单

很多人以为编排 agent 必须依赖一个「框架」，但核心循环本质上只是一个 while：

while 未达终止条件:
    resp = llm(messages, tools)
    if resp.tool_calls:
        执行工具，把结果 append 回 messages
    else:
        return resp.content

Hermes 的 run_conversation（agent/conversation_loop.py）本质就是这个。

真正难的不是这个循环本身，而是它周边的工程细节：流式输出、中断、预算控制、上下文压缩、prompt 缓存、provider 故障切换、并发工具执行、错误分类与重试……而这些恰恰是通用框架抽象得最浅、最容易「挡路」的地方。这是理解「为什么很多项目不用框架」的关键。

2. 行业层面：流行 agent 项目常绕开框架的普遍原因

适用于多数自研循环的项目（Hermes、OpenHands、Aider、Codex CLI、Claude Code 等）：

抽象与控制权错配。框架把 LLM 调用 / 消息 / 记忆 / 工具封装成对象（Chain / Runnable / Graph 节点）。但生产级 agent 需要对「发给模型的每一个 byte」精确控制——例如 Anthropic 的 cache_control 打在哪条消息、reasoning content 如何存、报错时怎样降级到 fallback 模型。框架抽象让这「最后一公里」更难做，常被迫绕过框架 monkey-patch。打个比方：框架像一台万能遥控器，常见电器都能控，但你家那台带最新功能的机器它偏偏少了一个键，你只能拆开后盖直接接线。
多 provider 的 API 形态差异。需要同时支持 OpenAI chat.completions、Anthropic Messages、Bedrock、Codex Responses 等不同 API 形态时，框架的「统一 LLM 接口」往往滞后于各家最新特性（新模型、新参数、reasoning、prompt caching），追新被动。就像翻译软件总比原文晚一步：各家模型刚发布的新能力，框架要等下一个版本才支持，而你想第一时间用上。
调试与可读性。自研循环的 stack trace 直达自身代码；框架常是多层抽象 + 回调，报错栈深、行为隐式。长期维护项目更看重可读性。
依赖与供应链风险。框架本身是庞大的传递依赖树，版本变动频繁、API 不稳定，放大供应链攻击面。
版本 churn。LangChain 早期 API 变动剧烈（LLMChain → LCEL → LangGraph），把核心逻辑绑在快速变动的框架上，迁移成本高。

3. Hermes 代码中可实证看到的取向（有据可查）

极致依赖最小化 + 供应链防御。pyproject.toml 有大段注释说明：核心依赖全部精确钉死版本（==X.Y.Z，不用范围），起因是 2026-05 的 Mini Shai-Hulud 蠕虫攻击；并明确写道 “smaller dependencies = smaller blast radius for the next supply-chain attack”，provider 专属依赖一律惰性安装（tools/lazy_deps.py）。一个把「依赖面积」当一等公民管理的项目，自然不会引入 LangChain 这种重依赖。
唯一的 LLM SDK 是 openai==2.24.0，其余多 provider 全靠自研 Transport / Adapter 层（agent/transports/、agent/*_adapter.py）适配，统一以 OpenAI 消息格式为中间表示。
循环周边大量自研工程：中断检查、agent/iteration_budget.py、agent/error_classifier.py（故障切换）、agent/context_compressor.py、agent/prompt_caching.py、agent/tool_executor.py（并发工具执行）。仅 run_agent.py 单文件就有约 5300 行，循环相关模块合计上万行，说明他们刻意投入去拥有这个循环，而非外包给框架。
并非「什么都自己造」。当愿意把控制权交出去时（如把工具循环交给 OpenAI Codex app-server），Hermes 会显式集成；它反对的是「用通用框架替代自己的核心循环」，而非反对一切集成。

概括 Hermes 的「理由」：把可控性与供应链安全当第一优先级，而 agent 核心循环又足够简单，自研的收益 > 框架带来的便利。

4. 深入：极致依赖最小化 + 供应链防御

Hermes 的供应链防御不是口号，而是落在 pyproject.toml + 四个具体模块里的多层机制。理解这套纪律，就能明白「不用框架」为何是它的必然推论而非口味选择。

触发这套设计的真实攻击

hermes_cli/security_advisories.py 与 pyproject.toml 注释都点名了同一起事件：

Mini Shai-Hulud worm（2026-05） —— 在 PyPI 上投毒了 mistralai 2.4.6。这是一类「自我传播的供应链蠕虫」：攻陷某维护者账号 → 发布带恶意代码的新版本 → 恶意代码在安装/运行时窃取更多凭证 → 用偷来的凭证投毒更多包，滚雪球扩散。

pyproject.toml 写得很直白：若当时 mistralai 用 >=2.3.0,<3 这种范围声明，则在该恶意版本被隔离前的几小时内，每一次 install 都会自动拉到投毒版本。这就是钉死版本的直接动机。

攻击类型 → 防御策略对照

把 Hermes 的防御逐条拆开，每条都对应一类具体攻击场景：

PyPI 投毒新版本（蠕虫或被劫持账号发布恶意 X.Y.Z+1）。对应策略：核心依赖全部精确钉死 ==X.Y.Z，配 uv.lock 锁定传递依赖；新版本只能通过「人为改 pin + 重新 lock + code review」进入。证据：pyproject.toml 注释 +[project.dependencies] 全是 ==。
传递依赖爆炸面（直接依赖虽少，但间接拉进上百个包，任一被投毒都中招）。对应策略：核心依赖最小化，只有「每个 session 都用到」的包进 core；provider/搜索/TTS/消息平台等专属依赖踢出核心，改为惰性安装。证据：pyproject.toml 的「Scope rule」注释 + tools/lazy_deps.py 里的 LAZY_DEPS。
[all] 连坐失败（某 extra 的传递依赖被隔离，导致整个 [all] 解析失败，新装用户静默退化丢功能）。对应策略：把可选 backend 从 [all] 移到 lazy-install，单包隔离只影响该功能，不连累其它。证据：tools/lazy_deps.py docstring 的「Fragility」段 + [all] 注释。
恶意 MCP 扩展包（npx/uvx 拉的第三方 MCP server 可能是投毒包）。对应策略：启动前查 OSV 数据库，命中 MAL-* 恶意软件公告就 BLOCK——只拦确认的恶意软件、不拦普通 CVE，且网络失败时放行（fail-open）。证据：tools/osv_check.py::check_package_for_malware。
配置劫持安装源（恶意 config 把安装重定向到攻击者镜像、git 或本地路径）。对应策略：lazy-install 只允许从 PyPI 按包名装，不支持 --index-url/git+https/file:，只能装白名单 spec，且仅作用于当前 venv，绝不碰系统 Python。证据：tools/lazy_deps.py 的「Security model」段。
已知 CVE 的依赖。对应策略：在钉死版本上逐条标注 CVE（requests/aiohttp/starlette/PyJWT/anthropic 等），升级有意为之。证据：pyproject.toml 内联的 # CVE-2026-xxxxx 注释。
投毒包已装进用户环境（防线突破后的检测兜底）。对应策略：每次 CLI/gateway 启动用 importlib.metadata.version() 比对已知被攻陷版本清单，命中即告警 + 给修复指引；用户可 hermes doctor --ack <id> 确认并持久化。证据：hermes_cli/security_advisories.py 的 ADVISORIES。

关键策略再展开

钉死版本 + lockfile（策略 1）：范围声明把「何时拉到新版本」的决定权交给 PyPI 和时间；钉死则收回到「一次显式人工提交」。代价是手动 uv lock，收益是攻击者没有自动到达用户的通道。pyproject 明确要求：升级必须同时改 pin 并重新生成 uv.lock，「不要在没有书面理由时把范围加回来」。
最小化 + 惰性安装（策略 2、3）—— “blast radius” 的核心：原文 “smaller dependencies = smaller blast radius for the next supply-chain attack” 的工程含义是：核心依赖列表越短，下次供应链攻击波及你的概率越低。所以 anthropic、firecrawl、edge-tts、modal、mautrix、elevenlabs 等几十个 provider 专属包全部移出 core，改由 lazy_deps.ensure("feature.name") 在首次用到时现装。只用一家模型的用户，永远不会把其它几十家 provider 的依赖树拉进攻击面。
OSV 恶意软件拦截（策略 4）：唯一一处「主动外呼查询」——在 agent 真正 npx/uvx 启动 MCP server 之前，先问 Google OSV API「这个包有没有 MAL-* 公告」。它故意只拦确认恶意软件、不拦普通 CVE（避免误杀），且 fail-open（网络失败放行，不阻断正常使用）。灵感来自 Block/goose 的扩展检查。

为什么这套纪律天然排斥 LangChain

把上面串起来：LangChain/LangGraph 是重依赖，自身又拖一棵庞大且高频变动的传递依赖树。对一个把「core 依赖必须短、每个包都要能 CVE 标注、可选依赖一律惰性化」当硬规矩的项目，引入这种框架等于一次性破坏策略 1/2/3/6——blast radius 直接爆炸。所以「不用框架」不是孤立的口味，而是这套供应链纪律的必然推论。

补充：依赖只是其中一层

SECURITY.md 的 trust model 显示供应链只是防御的一部分。Hermes 把所有「进入 agent 上下文的内容」（web 抓取、邮件、gateway 消息、文件、MCP 响应、工具结果）都列为不可信输入面；另有 tools/url_safety.py、tools/threat_patterns.py、tools/skills_guard.py、tools/skills_ast_audit.py、tools/tirith_security.py 处理 prompt 注入与技能代码审计。依赖最小化解决「你装进来的代码可信吗」，这些模块解决「跑起来后喂给模型的数据可信吗」。

5. 不用框架的优缺点

优点

完全控制 prompt / 消息 / 缓存 / 重试 / 降级，能第一时间用上各家模型新特性。
依赖少、攻击面小、构建可复现、长期可维护。
调试直观，栈短，行为显式。
不受框架版本升级牵连。

缺点

要自己造很多轮子：重试、压缩、记忆、工具 schema、并发、可观测性——Hermes 为此写了上万行，成本真实存在。
缺少生态即插即用：LangChain 有海量现成 retriever / loader / 集成，自研要逐个接。
概念需自己沉淀：图编排、状态机、checkpoint 等 LangGraph 直接提供的能力要自行设计（Hermes 用 Kanban + delegate 自实现了类似能力）。
团队上手曲线：没有通用框架的共同词汇，新人要读项目私有抽象。

6. 什么时候反而该用框架

平衡地看，框架并非没价值：
– 快速原型 / Demo / 一次性脚本：现成集成省时间。
– 需要复杂、可视化的有状态编排且不想自研：LangGraph 的图 / checkpoint / human-in-the-loop 是真实价值。
– 团队不愿维护底层循环，愿用抽象约束换取速度。

经验法则：探索期用框架跑得快；一旦产品要长期演进、要精细控制模型行为、要控依赖与安全，多数严肃项目会像 Hermes 一样收敛回「自研瘦核心循环 + OpenAI SDK」。这也是 Aider、Codex CLI、Claude Code 等流行 coding agent 同样不依赖 LangChain / LangGraph 的原因。

7. 一句话总结

agent 的核心循环简单到不值得用重框架去封装，而循环周边真正难的工程（缓存 / 降级 / 压缩 / 多 provider / 供应链）又恰恰是框架抽象会挡路的地方——所以 Hermes 选择自研瘦核心循环，用依赖最小化换取可控性与安全性。

如果觉得这篇文章对你有帮助，欢迎点赞、收藏加关注。后续持续分享更多有价值的内容。你的支持是我创作的最大动力！

标签： LangGraph

设计取舍：为什么 Hermes（以及很多流行 agent）不用 LangChain / LangGraph