Agentic体验：1,324次调用我的CLI，15.9%的错误率
我的CLI最常见的用户并不是我自己 lql 是一个用 Rust 开发的CLI工具，用于管理Linear的问题任务。我开发这个工具是因为现有的替代方案并不能满足我的实际使用需求：让一个自主的AI代理来管理问题任务。 为什么我必须开发自己的CLI Linear的MCP服务是我的第一个尝试。这个想法很优雅：搭建一个MCP服务器，从而直接向代理公开Linear的API。但是在实际使用中，它的运行速度很慢且非常不稳定，每次调用时，代理都需要从头开始构建GraphQL查询。这增加了在每次调用中引发不存在字段的机会。用了一两周后，我把这个方案卸载了。 社区版CLI（schpet 的 linear）是我的第二个尝试。这个工具主要是为人类用户设计的，带有交互式菜单、箭头选择以及确认提示。但问题是，一个代理不能操作交互式菜单。也不适合。 Linear 的“智能代理”功能。 2026年3月，Linear 发布了一个集成了 AI 的智能代理。乍一看听起来很理想，直到你发现其局限性：它仅能在Linear的Web界面内使用，没有终端调用功能，没有API，也无法与外部工具集成。它就是一个嵌在自己用户界面中的聊天机器人。如果你的工作流包括“编程的代理也需要管理问题”，Linear 的代理功能无法满足需求。 基于数据的设计：初步分析 在开发 lql 之前，我解析了Claude Code与Linear交互时165次会话中的每一个错误。结果表明，共记录了500多个错误，370次重试，并估算出每月约有700,000个token被浪费。--sort忘记使用40次；写成了--state "Todo" 而非 --state unstarted共12次；--no-interactive未添加导致CLI挂起，等待键盘输入64次。（全套数据细节见原始文章。） 基于这些数据，我设计了 lql 的用户界面。我并没有猜测一个代理需要什么，而是使用测量得到的数据。这形成了一些基础设计决策：输出格式为精简化版本TOON（每个问题约25个token，而不是繁多的JSON格式），为LLM容易混淆的选项添加别名（例如--status → --state），对值进行标准化（比如Todo 转化为 unstarted，urgent 转化为 1），并提供建议正确命令的错误提示信息，而不是简单地显示“未知选项”。 当时我并不清楚，实际上自己是在应用Postel法则。这是后来才意识到的。 第二次分析：lql在生产环境中的一个月 lql上线已经一个月。Claude Code每天会调用它30到50次，用于创建问题、更新状态、链接依赖、查询细节等。我自己从来不手动使用它，因为对我而言，手动管理问题不是兴趣所在。我有代理来解决这些事情。如果哪天我必须亲自执行lql，那说明出了严重的问题。 lql唯一的用户是一个LLM。这让整个设计变得完全不同。 所以我再次解析了Claude Code调用lql的会话日志，搜寻错误。 指标 数值 分析的会话数 200 lql 的调用次数 1,324 错误数 (is_error: true) 210 错误率 15.9% 15.9%的错误率未包括因为并行调用失败且被Claude取消的调用。这里只计算CLI实际发生的错误。 错误分类 并非所有错误都是一样的。有些表明缺乏约定，而有些则表明需要添加操作。 错误 频率 实例 未找到Label 20 --label tokamak (在该团队中不存在) --title 用作 create 的选项 8 lql create --title "Epic: ..." --team PROD 将 show/get 写成 view 6 lql show PROD-911 relate 参数顺序错误 12 lql relate PROD-834 PROD-833 blocked-by 尝试 update --team (移动问题任务) 超过15次 lql update PRIV-32 --team PROD relates 写成 related 2 lql relate PROD-912 relates PROD-910 --body 用于 comment 1 lql comment PROD-926 --body "文本" --comments 用于 view 1 lql view PROD-824 --comments 其余是Linear的API错误、1Password认证问题、或shell错误（长heredocs中的引号破裂）。 ...