我可能看错了 Agentool

我做 agentool，是因为我以为自己找到了一个干净的优化点。

Claude Code 的内部机制变成公开学习对象之后，我想要一个有点像 Claude Code、但更靠近 Vercel AI SDK 世界的东西。文件操作、shell 执行、搜索、网页抓取、记忆、智能体、输出验证、上下文压缩：这些基础组件足够跑有用的自动化，又不用每次都拉一个很重的完整智能体运行时。

目标很实际。我想让自己的 GitHub Actions 工作流更轻、更快。如果依赖面足够小，也许我可以自动化更多事、更频繁地跑，然后把时间花在有意思的工作上，而不是照看流水线。

这是当时的假设。

现在我没那么确定。

答案快照

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

最初押注	后来变了什么	现在的动作
更轻的 CI 依赖会节省有意义时间	运行时间不如维护成本和审查质量重要	当较重的 SDK 更擅长掌管智能体循环时，就用它们
围绕 Vercel AI SDK 工具构建类似 Claude Code 的行为	智能体平台不断增加我也得追的功能	让 agentool 保持更窄，而不是变成平台
技能和提示词可以约束工作流形状	长工作流需要硬模式边界	保留 output_validator 和明确交接契约

我当时追的优化

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

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

工作流跑一次时，运行成本很容易看见。任务要五分钟还是十二分钟，安装包是轻还是重，容器启动是快还是慢。这些数字很具体，所以很诱人。

维护成本更难看见。它会晚一点到来，而且一次来一个功能。

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

每个近似实现都会变成我拥有的代码。

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

我仍然相信的部分

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

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

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

验证器可以。

这部分我不想交给提示词自觉。如果下一阶段期待一个带精确字段、判别式变体、数组、枚举值和恢复指令的嵌套 JSON 对象，前一阶段就应该先证明它有这个形状，再让任何东西碰它。

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

不舒服的问题

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

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

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

如果一个工作流已经异步运行、打开 PR、等待审查，省下几分钟搭建不是我最在意的。我在意的是一个糟糕草稿现在要我审查，一个静默失败早在三步前发生，或者我发现改一个阶段意味着要重建智能体运行时的另一片。

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

为什么 SDK 开始显得合理

Claude Agent SDK 和 Codex SDK 改变了我的计算。

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

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

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

某种意义上它没那么优雅。需要协调的部件更多，认证更多，配置更多，供应商特定状态也更多。

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

我正在走向的新分工

我开始这样看边界：

关注点	留在近处	委托出去
严格结构化输出	验证器、模式、修复循环、交接契约	模型自我约束
智能体循环和编码工作流	配置、验收关卡、代码库特定规则	Claude Agent SDK 或 Codex SDK
CI 速度	缓存、隔离、避免不必要安装	不要让它支配架构
新的智能体功能	结果真的改变时再采用	不要重做每个平台功能
自定义 Vercel AI SDK 实验	agentool 在这里仍然有用	完整代码智能体行为

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

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

新方向的风险

新方向也有陷阱。

供应商引力是明显风险。如果我把太多东西移进 Claude 专属或 Codex 专属工作流，自动化会更难移植、更难本地测试，也更容易受产品变化影响。我能控制的是适配器边界。提示词、模式、环境搭建和验收检查应该留在我的代码库里，而不是消失在某个供应商专属的黑盒里。

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

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

我想通的事

我想通的不是 “agentool 是错的”。

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

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

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

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

我现在用的规则

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

对我来说，这意味着验证器、模式、验收关卡、代码库规则、工作流意图留近一点。智能体循环、工具编排、上下文行为和快速变化的平台功能，可以交给已经存在的 SDK。

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

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

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