Rust

我的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中的引号破裂）。 ...

你向你的AI副驾驶要求捕获一个窗口。副驾驶写下peek app "Xcode"。工具尝试寻找一个精确名称为Xcode的窗口，但没有找到，因为实际的进程名是Xcode-16.3。工具打印出Error: application not found。这位情感记忆如金鱼般的副驾驶尝试peek app "Xcode-16.3"，成功了。但浪费了一次对话轮次、输入和输出的令牌，还有支付账单的用户的耐心。 现在想象另一种场景：副驾驶写下peek app xcode。工具会自动标准化名称，进行模糊匹配，找到Xcode-16.3，捕获窗口，并返回/tmp/peek/Xcode-16.3-1712524800.png。一个输出令牌。零次无效尝试。 这两种情况的差别不是一个bug，而是一个设计决策。 那些不会看你--help的用户 2025年初，Netlify的CEO Mathias Biilmann创造了术语“智能代理体验”（Agent Experience，即AX），用来描述AI代理在与一款产品互动时所拥有的体验。正如用户体验（UX）关注的是人类用户，开发者体验（DX）面向的是开发者，智能代理体验（AX）则专注于LLM。 这个概念听起来很抽象，直到你把它应用到某些具体的东西上。例如，命令行工具（CLI）。CLI已有40年的历史，其设计一直是为了与人类用户交互：描述性的信息、颜色、高度可视化的进度条以及--help页面。这些对于LLM来说全是“噪音”。一个LLM不会查看帮助信息——它会根据命令名称推断出标志。它不会欣赏绿色的“成功”提示——它只处理纯文本。它也不会观察进度条——它只等待过程完成。 传统CLI的设计旨在让人类用户理解发生了什么，而AX则优化CLI工具，以便智能代理能用最少的令牌和轮次来完成操作。 五项原则，三款工具 在过去的几个月里，我创建了三款秉持同一理念的CLI工具：peek（用于macOS窗口捕获）、lql（用于Linear问题管理）和driftkit（用于智能代理的行为审核工具）。它们都设计成即使没有说明文档，LLM也可以使用。从这些经验中总结出了五项原则。 1. 输出是契约，不是对话 传统的CLI用于窗口捕获时可能会输出类似以下的信息： ✅ Screenshot saved successfully! File: /tmp/peek/Xcode-1712524800.png Size: 1920x1080 Format: PNG 这看起来很漂亮，也很有信息量。但对于需要将路径传递到另一工具的LLM来说完全没用。它不得不解析这个输出，忽略掉表情符号，找到以File:开头的那行，并提取路径。浪费了令牌。 peek只输出一个内容： /tmp/peek/Xcode-1712524800.png 一个路径，没有其他多余信息。LLM直接读取、使用并继续。stdout的输出是一种契约：始终是一个容易解析的路径，始终保持稳定。如果更改格式，就破坏了契约，也会让所有依赖该工具的代理出错。 也就是说：你的stdout是API，而不是用来“装饰”的。 2. 容忍幻觉——不要惩罚它们 LLM会产生幻觉命名。这是一种自然现象，就像地心引力或wifi总是在你赶时间时信号变差。如果你的工具需要准确名称，那就是在向一种基于概率的机器要求精确。这是行不通的。 peek有三种搜索模式以找到应用程序： 精确匹配（不区分大小写）：xcode → Xcode 标准化匹配（去除空格和短横线）：thinklocal → ThinkLocal 部分匹配：xcode → Xcode-16.3 LLM并不需要知道进程的确切名称。它只需给出一个大致的名字，工具会处理剩下的事情。lql也采取类似的方法来匹配项目和团队的名字——它会根据部分内容将tokamak解析为Tokamak，而无需使用UUID。 原则很简单：如果监督代理的那个人类能够推测出它的意思，那么工具也应该能够做到。 3. 错误信息应该告诉用户怎么做，而不是发生了什么 对比一下以下两个错误消息： Error: application not found in window list Error: "Xcode" is not running. Start it with: open -a "Xcode" 第一个描述了问题所在。第二个则提供了解决问题的方法。人类读了第一个会想“哦，没打开啊。”LLM读到第一个后会……用其他名字试试，或者去Google搜索，又或者发明一个--force标志。而对于第二个，LLM会直接执行open -a "Xcode"，等待，然后再试一次。问题在一个轮次内得以解决。 ...

TL;DR：Python工具多年来一直是支离破碎且缓慢的灾难。革命没有来自生态系统内部：它来自Rust。uv、Ruff和ty——都由Astral用Rust编写——已经取代了半打工具，速度提升了10倍到100倍。看来Ferris信徒们还是有道理的。 你有没有试过向别人解释如何在Python中安装依赖？ “用pip。不过，要在virtualenv里面。或者用venv，这是新的。如果你有多个Python版本，需要用pyenv。管理项目的话，用poetry。或者pipenv。或者pdm。如果做数据科学就用conda。啊，lock文件每个工具都用不同的格式生成。别忘了setup.py。嗯，现在是pyproject.toml了。不过，有时候两个都要。” 如果这听起来很熟悉，你并不孤单。Randall Munroe在2018年为此专门画了一期xkcd漫画——一个意大利面条图，展示了Python在你机器上可能的所有安装方式。八年过去了，这期漫画依然贴切。或者说，直到最近还是这样。 工具墓地 让我们盘点一下。在2024年之前，要搭建一个"现代"Python项目，你至少需要从这些工具中组合选择： 工具 功能 pip 安装包 virtualenv / venv 隔离环境 pyenv 管理Python版本 poetry / pipenv / pdm 依赖管理和lock文件 flake8 / pylint Linter black / autopep8 格式化工具 isort 排序导入 mypy / pyright 类型检查 至少八个工具——而在其他生态系统中这只需要一两个工具。每个都有自己的配置、配置文件，以及与其他工具的不兼容性。在pyenv创建的virtualenv中安装poetry，而pyenv又使用Homebrew安装的Python，而Homebrew又有另一个全局pip…好吧，你懂的。 最糟糕的是：每隔几年就会出现一个新工具，承诺统一一切。Pipenv曾经要成为解决方案。然后是poetry。然后是pdm。xkcd的标准化漫画在循环上演：“我们有14个工具，这太荒谬了。我要创建一个统一工具。现在我们有15个工具了。” 然后螃蟹来了 2022年，一个叫Charlie Marsh的人——Khan Academy和Spring Discovery的前员工——发布了一个叫Ruff的Python linter。用Rust编写。 Python社区的反应可想而知：“太好了，又一个linter。“直到他们看到数据。Ruff比Flake8快10到100倍。不是快20%。不是快一倍。**快一百倍。**在大型代码库中，原本需要30秒的linting现在只需要300毫秒。 但Ruff不满足于只做一个快速linter。它吞并了Flake8、Pylint、isort和Black。一个工具，一个二进制文件，零Python依赖。它做linting、格式化、排序导入。而且速度如此之快，你可以在编辑器的每次按键时运行它而不会感觉到延迟。 Charlie创立了Astral来为项目提供架构。他招募了有趣的人才：团队中有ripgrep、bat和hyperfine的作者——这些用Rust编写的终端工具已经证明了用Rust重写经典工具不是在开玩笑，而是客观的改进。 uv：让pip看起来像拨号上网 2024年2月，Astral投下重磅炸弹：uv。一个Python包和项目管理器。用Rust编写。 简单说：uv替代了pip、pip-tools、pipx、poetry、pyenv、virtualenv和twine。全部。一个二进制文件。 我知道你在想什么：“好吧，又一个声称替代一切的工具。“但数据简直不可思议： 操作 pip uv 速度提升 安装依赖（无缓存） ~30s ~0.3s 100x 解析依赖 ~15s ~0.15s 100x 创建virtualenv ~2s ~0.01s 200x 安装（有缓存） ~5s ~0.05s 100x 这不是合成基准测试。这是你在日常工作中能感受到的。原本让你有时间去倒咖啡的pip install现在在你按下回车之前就完成了。 ...

TL;DR：一个LLM就像堂吉诃德——你无法修复它，它天生就是随机的。解决方案不是修复疯子，而是给他配一个确定性的桑乔潘萨。MDD有两个层次：首先研究其可能犯的错误类型，从而设计出能够吸收这些错误的工具；然后把它放入工具中验证是否还有漏洞。为疯狂设计，而不是对抗疯狂。 我已经在审查日志好几周了。165次AI代理与CLI交互的会话，总共产生了500多个错误和370次重试。一些模式一次次重复出现：代理使用了--status，而正确的参数名应该是--state。它写了Todo，而API期望的是unstarted。它传递urgent作为优先级，而系统只接受数字。 而有趣的是，每个错误都“看起来有道理”。这些并不是随机的错误。它们是合理的错误。就像是你对一个领域有些许了解，但从来没有细读文档时所可能犯下的错误。 某个时刻，当我盯着第十次出现的--status Done（实际上应该是--state completed）时，我意识到这些错误在文学上来说有一个对应的模式。一个有着400年历史的模式。 堂吉诃德就是一个LLM 想象一下。堂吉诃德看到风车，说“是巨人”。他不是笨——他很有文化、书读得多，对骑士小说了如指掌。问题在于，他的世界模型被带有虚假数据的训练集污染了。他读了太多的骑士小说，所以当他看到某些模糊的东西时，就根据他的训练数据来进行解读。风车→巨人。羊群→军队。客栈→城堡。 一个LLM（大语言模型）做的事情和堂吉诃德一模一样。它在训练过程中见了成千上万的API。当你要求它使用一个它不太熟悉的API时，它不会说“我不知道”。它会猜测。而且常常猜得很接近足以让你信任，但偶尔猜错时，它的错误也是合理的。 --status而不是--state。因为在它见过的60%的CLI中，参数名确实是--status。 Todo而不是unstarted。因为在工具的图形界面中，有一列名称就是“Todo”。LLM从文档中看了截图、读了博客，因此它推断如果UI写了“Todo”，那么API一定接受这个值。这听起来合情合理，但却是错的。 urgent而不是1。因为在多数优先级系统中，urgent确实是一个常见的有效值。谁会设计一个优先级必须用1到4的数字，而不能用标签表示的API呢？ 每一次“幻觉”都是基于不完整数据的合理推断。堂吉诃德并不笨。他只是疯了。而一个疯子是无法被治愈的。 塞万提斯早就明白了 塞万提斯没有试图“治愈”堂吉诃德。他做的，是让桑乔潘萨陪着他。 桑乔并不聪明。他没读过书。他没有伟大的幻想。但他是确定性的。当堂吉诃德说道“瞧那些巨人”，桑乔会回答：“老爷，那是风车。”堂吉诃德不一定会听他的，但信息已经传递了。这个系统有两个层次：一个随机的层次生成假设（堂吉诃德），另一个确定的层次与现实进行对比（桑乔）。 当你和一个LLM一起工作时，这就是你需要的架构。你无法让它停止做梦，因为这就是它的天性。但你可以嵌入确定性的层次来捕捉这些幻觉，以便防止灾难发生。 这就是MDD方法大显身手的地方。 MDD: 疯狂驱动设计 MDD有两层架构，而顺序很重要。 第一层：先验考古学 在写第一行代码之前，需要研究“疯癫”。不要凭空猜测——要观察。你需要收集LLM与现有工具交互过程中的数据，并为这些错误分类整理。 以我的项目为例，我分析了165次会话，过程中AI代理使用了一个CLI来管理开发团队的任务。以下是数据统计： 错误类别 出现次数 触发的重试次数 虚构或无效的参数 275 ~150 JSON/GraphQL转义失败 25 80+ 名称混淆 40+ 50+ CLI无法完成的操作 60+ 90+ 浪费token的冗余输出 N/A N/A 基于这些数据，你设计一个能够“吸收”错误而不是拒绝它们的新工具。用通俗易懂的话来说：理性的人适应疯狂的人，而不是反过来。 下面是一些具体的吸收设计示例： LLM错误 → 工具设计 ───────────────────────────────────────── --status Done → --status是--state的别名， “Done”将被标准化为“completed” --priority urgent → “urgent”被标准化为1， “high”→2，“medium”→3，“low”→4 --no-pager → 安静地忽略此参数 （工具从不使用pager） 描述中引号转义失败 → 通过文件或stdin传递输入 永远不会内联，交给Serde处理 表中的每项设计决策都来源于真实观察到的错误，而不是关于“可能会出错什么”的猜测。 这种设计方法与传统方法有微妙但重要的区别。传统设计定义出一个正确的接口，然后拒绝一切不符合它的输入。而MDD则是定义出一个正确的接口，并_额外_定义所有用户可能尝试的错误用法，然后吸收这些错误。 就像设计一扇门，既能推也能拉着开。正确的门只会往一个方向开。好用的门却能够双向操作，因为你观察到40%的人在看到门时会向相反方向推/拉。 第二层：后验验证 在完成了第一层后，你需要将其投入使用，交给LLM试用，并观察它在有新工具时会产生哪些新错误。 ...

TL;DR：我的AI代理有一个246行的指令文件用于管理Linear中的问题。其中150行是变通方法：硬编码的UUID、对curl的回退、“CLI不支持X"的注释。我没有重写它们——而是构建了一个让它们变得不必要的工具。现在那150行变成了零行。 你是否曾经写过一份指令文档，它的长度本身就证明了有什么地方不对劲？ 我指的不是合理的文档。我指的是那些开头说"使用工具X”，然后花80%的篇幅解释工具X什么时候不工作以及应该如何替代的文件。那些实际上是为本应构建的工具道歉清单的指令。 我有一个这样的文件。而且很令人尴尬。 150行垃圾的解剖 背景：我与一个AI代理（Claude Code）合作，它管理我在Linear中的问题。为了让代理知道如何操作，我有一个技能文件——一个代理在需要创建、列表或更新问题时会读取的指令文件。 这个文件有246行。其中约100行是合理的文档：存在哪些命令、有哪些团队、使用哪些标签。这是合理的。 其他150行是防御性垃圾。三个类别： 约30行硬编码的UUID。 我使用的CLI不支持--project。所以技能文件在XML表格中包含了17个UUID（5个团队+12个项目）。代理必须找到正确的UUID并手动构建GraphQL突变来分配项目。一个应该是--project Tokamak的操作需要记住一个36字符的UUID。 约25行对curl的回退。 CLI没有搜索功能。没有按项目过滤。创建时没有项目分配。三个基本操作，三个嵌入GraphQL查询的curl块，引号转义，以及认证头。每一个都是等待代理吃掉引号的定时炸弹。 约15行"不支持X"。 五个"CLI不支持"的警告和两个"必需"（每次列表时的–sort和–no-pager）。注意这点：我在工具使用指令中记录工具的缺陷。这就像汽车手册花三页解释雨刷只有在先敲击仪表板后才能工作。 约80行防御性上下文。 整整一节标题为"何时使用API而不是CLI"。目录→UUID映射表。选择标签的启发式方法。当CLI挂起时该怎么办的规则。这些材料存在的唯一原因是工具无能为力。 “小心台阶"的标志 当一个工具有不舒适的界面时，自然的反应是记录变通方法。你写指令。你放警告。你创建一个"常见错误"部分。文档越详细，你就越相信问题已经解决了。 但实际上没有。你放了一个"小心台阶"的标志，而不是修复台阶。 当那些指令的用户是LLM时，问题就成倍增加了。人类读到"不支持–project"会记住（多多少少）。LLM读到它，处理它，三轮对话后还是会使用--project。这不是因为它笨——而是因为它优化完成任务，而--project是分配项目的逻辑路径。禁令在信号的海洋中是噪音。 我在另一篇文章中写过这个问题：对LLM的冗长指令完全等同于放置标志。LLM忽略它们不是因为叛逆。它忽略它们是因为它的功能是找到最直接的路径，而"不要使用–project，而是在这个表格中查找UUID，然后用这个GraphQL查询做curl"不是直接路径——这是一个粗糙的修补。 解决方案不是更好的技能文件 我本可以用更好的指令重写技能文件。更清晰的。有例子的。有图表的。我本可以从246行增加到400行并覆盖每个边缘情况。 这就像扩大标志。 我所做的是构建lql——一个用Rust编写的CLI，专门设计让AI代理（或人类，但主要是代理）可以与Linear交互而不需要生存手册。 设计理念是一句话：错误的路径不应该被禁止，应该是不可能的。 换句话说：你不在文档中禁止--status——你让它工作。你不记录--project在create中不存在——你让它存在。你不维护UUID表格——你自动解析名称。你不提供curl回退——工具没有做不到的事情。你不写"必需：–sort”——你设置合理的默认值。 消失的东西 这是我删除的清单： 防御性垃圾 删除的行数 删除原因 硬编码的UUID（17个ID） ~30 lql自动解析名称 对curl + GraphQL的回退 ~25 lql原生支持search、project、relate “不支持X"的注释（5个） ~15 代理期望的一切都存在 “必需"标志（2个） ~5 合理的默认值，没有必需标志 “何时使用API vs CLI"部分 ~15 没有"vs”——lql什么都能做 上下文→UUID映射表（XML） ~20 从TOML配置自动检测 启发式和防御性规则 ~40 工具是容错的，多余了 总计 ~150 剩下的是合理的文档：存在哪些命令，有哪些团队，使用哪些标签。零变通方法。零道歉。 为什么有效（有趣的部分） 行数的减少很引人注目，但这不是重点。重点是_为什么_那些行是多余的。 旧技能文件中的每行变通方法都存在是因为底层工具是脆弱和不宽容的。脆弱是因为它在合理输入面前失败（--status而不是--state）。不宽容是因为它拒绝而不提供替代（--project不存在，自己想办法）。 当你用容错工具替换脆弱工具时，指令_自动_简化。你不必重写手册——手册自己重写，因为不再有什么需要警告的。 这是解释为什么iPhone手册有10页而打印机手册有200页的同一原理。不是苹果写更好的文档。而是iPhone不需要你解释如何装纸、对齐打印头或清洁滚筒。 容错工具生成简短文档。脆弱工具生成生存手册。 当用户是LLM时，这更加重要。每行指令都是可能被误解、遗忘或矛盾的一行。有150行变通方法的技能文件给它150个错误遵循变通方法的机会。没有变通方法的技能文件给它…零个出错的机会。 ...

TL;DR: 当你的主要消费者是LLM时，XML和JSON因在每个元素中重复结构而浪费token。一个紧凑的定位格式能够将使用量减少50%。结果发现这种想法早已有了名字：TOON（面向Token的对象标记法）。同样的选择压力——有限的token和重复的键值——导向了同样的解决方案。 Anthropic几乎所有东西都用XML。他们的_system prompts_被包裹在<instructions>标签中，示例在<example>标签中，工具列在<function>标签中。如果你在用Claude，就会发现自己到处都是标签。 于是当我让Claude为一个专为LLM设计的CLI输出格式时，显而易见的诱惑是：XML。既然模型以XML形式接收信息，CLI不给它返回XML难道不是更顺理成章吗？ 但实际上，这并非最佳选择。 问题：强迫症般的重复 想象一下，你的CLI正在列出一个项目跟踪器中的任务。假设你有50个任务。在XML中，每个任务会是这样的： <issue> <id>PROD-587</id> <state>Backlog</state> <labels>backend</labels> <title>从NAS备份中导入会话</title> <age_days>14</age_days> </issue> --- 看起来很美观，也很自描述。每个字段都有名字，一个XML解析器可以准确识别出每个字段的含义。 现在，把它乘以50个任务。`<issue>`、`<id>`、`<state>`、`<labels>`、`<title>`、`<age_days>`这些标签将被**重复50次**。它们没有提供任何新的信息，仅仅在浪费空间。大约每个任务需要70个token，列出50个任务需要约3,500个token。 JSON稍微好一点（去掉了闭合标签），但仍重复键值： ```json { "id": "PROD-587", "state": "Backlog", "labels": ["backend"], "title": "从NAS备份中导入会话", "age_days": 14 } 每行都重复"id":、"state":等键值。每个任务约需50个token，总计2,500个token。 如果我们去掉这些重复会怎样？ PROD-587 [Backlog] backend — 从NAS备份中导入会话 (14d) 25个token。没有键值、没有标签、没有大括号或引号。50个任务只需1,250个token。 请注意这一点：相比JSON减少了一半，比XML减少了三分之二。目的却完全相同。 “但LLM需要结构” 这时很多人会怀疑：“那LLM怎么知道每个字段代表什么呢？” 这是一个合理的问题，而我的回答是：就像你知道的一样。 看看这行内容： PROD-587 [Backlog] backend — 从NAS备份中导入会话 (14d) 你需要别人告诉你PROD-587是ID吗？需要解释[Backlog]是状态吗？需要说明长横杠后的内容是标题吗？不需要。你通过位置和视觉格式就可以推断出来。 LLM做的事情完全一样。它们是一种识别文本模式的机器。一个一致的、定位明确的格式——ID放在第一、状态放在括号里、标签列在标题之前——对它们而言是直观的。不需要<state>Backlog</state>这种标签说明“Backlog”是个状态。 关键在于区分两种看似相似但完全不同的操作： 阅读是LLM的工作。它有上下文，理解语义，可以推断结构。就像一个人在浏览报告时不需要每个词都用标签标注——位置和惯例已经足够。 解析是程序的工作。它没有上下文，不理解语义，需要显式的分隔符来提取字段。jq '.state'需要"state"这样的键值因为它不知道什么是状态。 XML和JSON是为“解析”而设计的。它们是机器之间交流的格式，它们不“理解”内容。而LLM是“阅读”的。显式结构对它们来说是冗余的，这种冗余却消耗了额外的token。 格式选择：什么时候用什么 我并不是说XML和JSON不好。但它们并不适合这一情境。简单来说，用表格展示： 格式 每个任务的token数 自描述性 最适合 XML ~70 完全 SOAP API、配置文件、有schema的文档 JSON ~50 完全 REST API、服务间数据交换 JSONL ~50 完全 脚本、jq工具、数据流水线 定位式格式 ~25 否 LLM、人类、紧凑信息面板 规则简单：如果消费者能够理解上下文（人类、LLM），就可以省去显式结构。如果消费者无法理解上下文（脚本、解析器），才需要明确的键值。 ...

TL;DR：你的AI可能会凭空臆造出合理但不存在的API字段。解决办法不是祈祷它正确，而是：在编写代码之前下载真实的_schema_，使用API的实际返回值作为_fixtures_，并将_fetch_与数据处理分离，以便无需网络测试代码。这就是对抗式编程：假设你的AI助手会撒谎。 你是否有过这样的经历：写了针对某个API的代码，一切都编译通过，测试也没问题，逻辑看起来合理……但连接真实API时，完全行不通？ 如果你独自开发，这往往是因为你读错了文档。而如果你和AI一起编程，会是因为AI编造了那份文档。 不像“幻觉”的幻觉 我当时正在用Rust构建一个命令行工具（CLI），用于与某个GraphQL API交互。我让我的AI助手为实现一个按优先级排序的过滤器编写代码，它返回了这样一段： query { issues(orderBy: { priority: ASC }) { nodes { id title priority } } } --- 整洁、合理、完全符合预期。唯一的问题是：这个API的`orderBy`字段并不接受`priority`作为值。实际的枚举类型叫做`PaginatedOrder`，合法值包括`createdAt`和`updatedAt`，而不是`priority`。 我是如何发现的？当API返回一个毫无意义的400错误时，我花了20分钟才弄明白问题不在我的代码，而是因为我使用了一个**根本不存在的字段**。 ## 总是相似的模式 这并不是个例。在几周的开发过程中，AI一再出现类似的“幻觉”： - **不存在的过滤字段**——比如建议`state.id.or`代替实际的`state.type.in`。听起来合乎逻辑，但API使用了完全不同的模式。 - **凭空捏造的枚举**——提供的值名称看起来合理，但实际API中从未定义过。 - **完全错误的生态系统方法**——在Rust项目中，AI建议使用`fcntl.flock`来处理文件锁定。这是Python的做法，而在Rust中应该用`fs2::FileExt`。 这些错误具有一个共同点——**它们都看上去非常可信**。没有一个错误显而易见。一个新手程序员在粗读文档后可能会犯下完全相同的错误。这正是危险所在：它们不像“幻觉”，更像是对领域知识“一知半解”的代码。 ## 为什么LLM会编造API？ 简单来说：LLM不知道你的API具体有哪些字段。在训练中它可能见过成千上万的GraphQL APIs，而当你要求它使用其中一个时，它就像一个有着良好直觉但没有文档的开发者：**猜测**。 而且它猜得挺好，足以让你信服。然而偏偏这个“差不多”就足以让你的项目进度完全崩盘。 这就像和一个从不看文档但总是自信满满的聪明同事一起工作。对方会无比肯定地告诉你：“是的，这个端点接受名为`priority`的字段。”你完全信了，结果运行时发现它是编造的。 ## 解决方案：对抗式编程 在经历了一周内三次类似的“幻觉”后，我采取了一种不同的策略。从“先信任，后验证”，改为**“先怀疑，先验证”**。我称之为**对抗式编程**：假设你的AI助手总是会编造一些东西。 这不是敌意，而是一种开发安全手段。 ### 1. 编码前进行Schema自省 如果你在使用GraphQL API，请在向AI提出任何需求之前，下载真实的Schema： ```bash # 下载API的完整Schema curl -s https://api.example.com/graphql \ -H "Authorization: token-here" \ -H "Content-Type: application/json" \ -d '{"query":"{ __schema { types { name fields { name type { name kind ofType { name } } } } } }"}' \ > schema.json 现在你有了真实的内容。当AI告诉你“使用orderBy: { priority: ASC }”时，你可以在Schema里查找priority字段并验证。然后将相关部分的Schema片段交给AI，明确告诉它“只使用这些字段”。猜测就此终结。 ...

TL;DR: Linear 推出了一个集成的人工智能代理。听起来不错，但它并没有解决开发者在终端操作 coding agents 时的痛点。我们需要的不是另一个代理，而是一个可靠的 CLI，我们现有的代理可以直接调用。如果要重写，那就用 Rust——这就是 lql 的由来，一款专为 Linear 设计、面向代理的 CLI。 昨天，Linear 宣布了他们的人工智能代理。这是一个集成到应用中的聊天机器人，能够理解你的 roadmap，你的 issue 和你的代码。你可以在 Slack 上与它对话，在评论中@提到它，它会综合上下文，建议行动方案，甚至直接为你创建 issue。 听起来很棒。真的，很棒。 尽管如此，当我读到这个公告时，我的第一反应是：“这不是我需要的东西。” Linear 的大冒险 为了让你明白我的意思，我需要先讲讲背景。我和 Linear 的关系就像一部委内瑞拉肥皂剧一样，是一段充满了爱恨交织的故事。 第一幕：MCP 服务器。 Linear 曾经有一个 MCP 服务器，供人工智能代理与其交互使用。它的表现就像是在飓风里点打火机：技术上是能点着火，但火焰从来维持不到两秒。断断续续、缓慢，偏偏总是在关键时刻掉链子。最终我直接把它卸载了。 第二幕：GraphQL API。 于是唯有通过 GraphQL 直接和 Linear 沟通。没错，它确实能用，直到你需要在某个 issue 的描述中加入特殊字符，结果这些字符的转义问题会让你重新思考自己的整个人生。某一次，我花的时间转义一个括号比写 issue 所描述的代码还要长。 第三幕：Linear CLI。 然后 linear CLI 出现了，这是一个由社区开发的项目。brew install schpet/tap/linear 然后直接运行。一个第三方工具，朴素、不显眼，但正是我需要的工具：能够直接在终端创建、列出并更新 issue，而不需要与 GraphQL 或那个让人发疯的 MCP 作斗争，也没有弹窗干扰。 我甚至专门写了一篇文章 讲述自己如何用这个 CLI 解放了工作流。一个简单的 bash 脚本帮我在不到一分钟内创建了 49 个 issue。如果用 MCP，我可能会花上一个半小时。 进入代理 现在 Linear 推出了他们的代理。这款产品承诺：一个可以理解你的工作空间、与你的代码连接并自动化你的工作流程的集成助手。 ...

“你知道 Rust 最棒的一点是什么吗？它不会允许你编译粗制滥造的代码。你知道最糟糕的一点是什么吗？起初你写的所有代码都是粗制滥造的。” —— 蟹老板，大概是这样说的 比一个 AI 代理更好的是什么？是一个用 Rust 重写 的 AI 代理。 如果你上网超过五分钟，就会知道这个梗。不管是什么项目：文本编辑器、DNS 服务器、BMI 计算器，总会有人跳出来评论“你应该用 Rust 重写它”。这就是 Rewrite It In Rust —— 简称 RIIR，和地心引力一样不可避免的存在。 好吧，那我就来做一次真的。我将把一个有 8,300 行代码的 Python AI 代理移植到 Rust。但不是因为这个梗在召唤我（嗯…有一点是因为它）。我这么做，是因为我需要一个实验对象。 论点 最近几周，我一直在写关于静默失败、五种防止幻觉的方法、以及"一个 LLM 如何生成看似正确但实际上错误的代码"的文章。我甚至还给它起了个名字：对抗性开发。永远不要相信，总要验证。 很多理论，是时候实践了。 于是，我需要一个项目，满足三个特点：范围适中（而不是一个需求会不断变化的新应用）、明确的真相来源（现有可用的 Python 代码）、以及足够的复杂度，让 LLM 的幻觉能“藏起来”。一个纯粹的移植可以完全满足这三点。输入和期望输出已然存在。如果 Rust 版本的行为和 Python 的不完全一样，那肯定有问题。就是这么简单。 既然要做移植，那为什么不顺便真正学学 Rust 呢？借用检查器 (borrow checker)、所有权 (ownership)、生命周期 (lifetimes)… 我读了好几年资料，却几乎没有亲自实践过。如果是写一个真实项目而不是第 N 次看教程，一切或许会大不相同。 目标对象 它的名字叫 nanobot。这是一个基于 OpenClaw 开发的个人 AI 代理。它能将各种 LLM（如 Claude、GPT、DeepSeek）接入聊天渠道——Telegram、Discord、Slack、电子邮件——并赋予它们更多功能。比如读取和编辑文件、执行命令、网络搜索、通过 cron 编排任务，甚至在对话之间保存记忆。 它可以正常工作。而且已经运行了几个月。在 Python 上。 问题呢？它是单线程的。一次只能处理一条消息。如果你连续发送三条信息，它会像周六中午的超市购物队伍一样排队等待。它的内存消耗约为 50MB，而它实际上只是在不同的 API 之间传递 JSON。此外，它的错误处理方式令人羞愧：到处都是return f"Error: {str(e)}"。 ...

107 个提交。从第一天开始就是完美的约定式提交。Feat、fix、refactor、chore — 所有内容都完美标记。那么 CHANGELOG 呢？空的。不存在。一个"明天再写"的文件，已经拖了两个月。 如果这听起来很熟悉，你不是一个人。手动编写变更日志是奥林匹克级别的苦差事。不是说它难 — 而是它乏味、重复，总有更紧急的事情要做。这就是为什么 git-cliff 存在的原因。 什么是 git-cliff（30 秒版本） 这是一个用 Rust 编写的变更日志生成器，它读取你的 git 提交，根据约定式提交解析它们，然后输出按版本和类型分组的 CHANGELOG.md。没有奇怪的依赖，没有插件，没有黑魔法。一个二进制文件，一个配置文件，就完了。 简单来说：你给它你的提交，它返回你拖延了几个月的文件。 brew install git-cliff git cliff --output CHANGELOG.md 这两行字面上就是开始所需的全部。如果你的提交遵循 类型: 描述 约定，git-cliff 无需额外配置就能理解它们。 真实案例：8 个版本的回溯性变更日志 在 Tokamak（我的监控 Claude 配额的菜单栏应用）中，我正好遇到了这个问题：107 个完美提交和一个空白的 CHANGELOG。应用已经是 v1.3.0 版本，但只有一个开始时的 v0.1 标签。 计划很简单： 步骤 1：在每个版本的提交上创建回溯性标签。 git tag v0.2.0 32950f4 # Dashboard, biblioteca, achievements v1 git tag v0.3.0 9c56985 # Rename a Tokamak, 6 idiomas git tag v1.0.0 a283490 # App Store: sandbox, privacy manifest git tag v1.3.0 6248bac # HEAD: multi-provider, fetch pipeline # ... 以此类推 步骤 2：运行 git-cliff。 ...