# 我可能看错了 Agentool

**Summary:** 一篇个人自动化复盘：我曾经构建 agentool，希望让 AI CI 工作流更轻；后来意识到真正的成本可能是功能维护、编排复杂度，以及追逐 Claude Agent SDK 和 Codex SDK 已经承担的 SDK 行为。

- Canonical: https://markhuang.ai/zh/blog/i-might-be-wrong-about-agentool
- Language: zh-CN
- Author: [Mark Huang](https://markhuang.ai/about)
- Published: 2026-06-20
- Section: AI 与 LLM
- Tags: agentool, claude-code, Codex, AI 智能体, 自动化, CI
- License: https://creativecommons.org/licenses/by-nc/4.0/

---

![开发者对比轻量 CI 自动化机器和更大的维护工作堆](https://cdn.markhuang.ai/blog/i-might-be-wrong-about-agentool/hero.webp)

*轻量机器是真的。那堆我没算进去的维护工作也是真的。*

我做 [agentool](https://github.com/markhuangai/agentool)，是因为觉得自己找到了一个漂亮的优化点。

Claude Code 的内部机制变成公开学习对象之后，我就想要一个类似 Claude Code、但更贴近 [Vercel AI SDK](https://ai-sdk.dev/docs/introduction) 生态的东西。文件操作、shell 执行、搜索、网页抓取、记忆、智能体、输出验证、上下文压缩——这些基础组件足够跑起有用的自动化，又不用每次都拉一个很重的完整 agent 运行时。

目标很实际：我想让 GitHub Actions 工作流更轻、更快。如果依赖面足够小，也许就能自动化更多事情、更频繁地跑，然后把时间花在有意思的工作上，而不是天天盯着 pipeline。

这是当时的假设。

现在我没那么确定了。

## 答案快照

到了 2026 年，我现在的答案是：**我可能优化错了层**。agentool 那 23 个 Vercel AI SDK 工具接口仍然有用，尤其是严格的输出验证。但更广义的 agent loop，也许更适合交给有人维护的 SDK。

| 最初押注                                    | 后来变了什么                  | 现在的做法                            |
| --------------------------------------- | ----------------------- | -------------------------------- |
| 更轻的 CI 依赖能省下有意义的时间                      | 运行时间不如维护成本和 review 质量重要 | 当更重的 SDK 更擅长掌管 agent loop 时，就用它们 |
| 围绕 Vercel AI SDK 工具构建类似 Claude Code 的行为 | agent 平台不断增加我也得追的功能     | 让 agentool 保持更窄的定位，而不是变成平台       |
| skills 和 prompts 可以约束工作流形状              | 长工作流需要硬性的 schema 边界     | 保留 `output_validator` 和明确的交接契约   |

## 我当时追的优化

我的心智模型很简单：依赖越轻，CI job 越快；CI job 越快，自动化越便宜；自动化越便宜，我就能自动化更多工作。

这个逻辑没错，只是不完整。

工作流跑一次的时候，运行成本很容易看见。job 要五分钟还是十二分钟，package install 是轻还是重，container 启动是快还是慢。这些数字很具体，所以很诱人。

维护成本更难看见。它来得晚一些，而且一次只来一个功能。

后来功能需求不再是假设了。我想要更干净地把工作分发给多个 agents。我想要能暂停并检查运行记录，而不是读一堆日志。我想要权限规则不会把每个工作流都变成定制的 prompt 契约。agentool 不是做不到这些，但每个缺失的部分都把我拖回去维护库本身，而不是让我完成原本想做的自动化。

每一个近似实现，最后都变成了我要 own 的代码。

这就是数学不再成立的地方。CI 快几分钟，抵不过我追赶那些已经有团队在维护的产品层所花的小时数。

## 我仍然相信的部分

![结构化输出验证器关卡把格式错误的工作流数据和干净交接对象分开](https://cdn.markhuang.ai/blog/i-might-be-wrong-about-agentool/validator-gate.webp)

*验证器是混乱交接泄漏到下一阶段之前的拦截点。*

对我来说，agentool 最强的部分仍然是 `output_validator`。

长自动化工作流的脆弱点在边界。第一阶段产出某个东西，第二阶段假设这个东西有特定形状，第三阶段假设第二阶段保住了契约。如果前面某一步返回差一点正确的 JSON，失败可能到很后面才显现，而那时调试成本已经高得多。

Skills 可以描述工作流。它们能说 assistant 应该做什么、检查哪些文件、运行哪些检查、用什么输出格式。但 skill 不能保证模型的输出满足复杂的 schema。

Validator 可以。

这部分我不想交给 prompt 自觉。如果下一阶段期待一个带精确字段、discriminated variants、数组、enum 值和恢复指令的嵌套 JSON 对象，前一阶段就应该先证明它确实有这个形状，再让任何东西碰它。

所以我没有离开 agentool。Validator 模式仍然有价值，我仍然希望工作流的边界足够硬。

## 那个让人不舒服的问题

我反复问自己的问题是：剩下的部分值得吗？

更具体一点：我的 CI job 跑得有多快，真的那么重要吗？

有时候重要。但没有我以为的那么重要。

如果一个工作流已经异步运行、开 PR、等 review，省下几分钟 setup 时间并不是我最在意的。我在意的是一个糟糕的 draft 现在要我来 review，一个静默失败早在三步之前就发生了，或者我发现改一个阶段意味着要重建 agent 运行时的另一块。

让人不舒服的地方在这里：我优化了 job 重量，但账单以功能所有权的形式来了。

## 为什么 SDK 开始显得合理

![开发者把工作流模块从自定义工具包移动到维护中的智能体 SDK 工作台](https://cdn.markhuang.ai/blog/i-might-be-wrong-about-agentool/sdk-handoff.webp)

*我现在更信任的分工：我的 repo 负责配置和契约，SDK 负责动态的 agent 机制。*

[Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview) 和 [Codex SDK](https://developers.openai.com/codex/sdk) 改变了我的计算。

它们更重，这是真的。但它们也带着 agent loop、context 管理、工具行为和产品级功能——这些正是我从外部不断试图重建的东西。Codex 的文档明确把 SDK 定位给 CI/CD pipeline 和内部工具。Claude 的 Agent SDK 允许用 TypeScript 或 Python 编程访问和 Claude Code 同类的 coding agent 行为。

我不想把晚上都花在重建那一层上。

我当前的搭建也让这个拆分更实际。Claude 的 SDK 可以通过我的个人 proxy 连接，Codex 的 SDK 可以通过我的 ChatGPT 订阅连接。与其逼一个轻量库变成我想要的所有 agent 运行时，不如让有人维护的系统负责 agent 工作，我自己的代码专注于配置、工作流边界和验证。

某种意义上这没那么优雅。要协调的部件更多，auth 更多，配置更多，vendor-specific 的行为也更多。

但它也更诚实。问题不是我能不能再写一层工具包装，而是我是不是想不小心维护一个竞争性的 agent 平台。

## 我正在走向的新分工

我开始这样看边界：

| 关注点                     | 留在近处                                 | 委托出去                         |
| ----------------------- | ------------------------------------ | ---------------------------- |
| 严格的结构化输出                | Validators、schemas、repair loops、交接契约 | 模型自我约束                       |
| Agent loop 和 coding 工作流 | 配置、acceptance gates、repo-specific 规则 | Claude Agent SDK 或 Codex SDK |
| CI 速度                   | 缓存、隔离、避免不必要的 install                 | 不要让它支配架构                     |
| 新的 agent 功能             | 结果真的改变时再采用                           | 不要重做每个平台功能                   |
| 自定义 Vercel AI SDK 实验    | agentool 在这里仍然有用                     | 完整的 coding agent 行为          |

这张表不是最终教条，只是我今天的想法。

这是我想保留的边界。agentool 可以继续是一个带严格输出验证的轻量工具集合。它不必追逐更丰富的 coding agent 产品的每个功能。

## 新方向的风险

新方向也有陷阱。

Vendor gravity 是明显的风险。如果我把太多东西移进 Claude-specific 或 Codex-specific 的工作流，自动化会更难移植、更难本地测试，也更容易受产品变化影响。我能控制的是 adapter 边界。Prompts、schemas、环境搭建和 acceptance checks 应该留在我的 repo 里，而不是消失在某个 vendor-specific 的黑盒里。

Auth 是无聊的陷阱，通常也就是最先坏的地方。依赖个人订阅 auth 或 proxy 的工作流，会以普通 API key job 不会有的方式失败。我需要明确的配置检查、清晰的失败消息、必要时同步 secrets，并且不能有假装工作流正确运行的静默 fallback。

最容易犯的错，是放弃 agentool 真正有价值的部分。如果我把一切都委托给 agent SDKs，却不再强制结构化交接，我会在更重的包里重建同一种长工作流的脆弱性。Validators 必须留在边界。让 SDKs 驱动，但不要让它把脏数据交给下一阶段。

## 我想通的事

我想通的不是"agentool 是错的"。

更窄一点：我一直在用 agentool 解决错误层的问题。

我想要更轻的 CI，是因为我想要更多自动化。但更多自动化的限制因素不总是 job 运行时间。有时是我自己要维护多少平台行为。有时正确答案是付出依赖成本，停止重建那些有人维护的 SDK 已经处理好的运转部件。

所以我开始把自动化工作流往 Claude Agent SDK 和 Codex SDK 移。我宁愿把时间花在设计工作流、定义交接契约、决定什么叫"完成"，也不想扫描地平线，看下一个 agent 功能又需要我重做什么。

我不喜欢更多配置。但相比不小心 own 平台维护，我更喜欢它。

## 我现在用的规则

规则很无聊，这可能是好迹象：我构建那些强制执行自己工作流的部分，把跟上 agent 平台变化的部分委托出去。

对我来说，这意味着 validators、schemas、acceptance gates、repo 规则、工作流意图留得近一点。Agent loops、工具编排、context 行为和快速变化的平台功能，可以交给已经存在的 SDKs。

我也可能继续错。没关系。

我没有得出"轻量工具不好"的结论。我得到的是更窄的东西：优化目标会过期。当成本模型变了，继续忠于旧目标就会变成过度工程。

我做 agentool 是为了省时间。如果继续把它放在中心开始比它节省的时间更贵，那诚实的做法就是换中心。