我意外地构建了一个前线部署工程师的野外工具包

一年前，我从一个项目中删除了 @anthropic-ai/sdk，并写了大约150行 TypeScript 来替代它。

我给自己找的理由既诚实又无聊。该 SDK 通过一个 agent-toolset 模块引入了 node:fs/promises，这破坏了浏览器打包。我可以等待一个浏览器兼容的入口点。但我选择手写一个 SSE 解析器，并为此写了一篇文章。

我当时把这归结为打包工具的问题。

然后，我读到一篇关于前线部署工程师工具的文章——那些被派到客户现场，让 AI 部署真正运行起来的人。大致意思是：每个框架依赖都是客户安全团队会过问的东西，而裸机代码在非自己掌控的环境中更容易调试。

同样的决策。同样的推理。不同的领域，不同的职位，完全不同的问题——但问题其实并不不同。

我当初解决的并不是一个打包工具问题。我解决的是一个部署问题，只是从未给它命名，所以我把这误认为是品味问题。

这篇文章是我回顾我所交付的五个工具中的每一个架构决策，并问自己一个从未问过的问题的结果：这里真正在起作用的约束是什么？

TL;DR

• 五个工具，全部浏览器端运行，全部自带密钥（BYOK），没有一个后端。我当时选择这些是基于偏好和一点点懒惰。
• 它们几乎完全符合在他人监管环境中工作的约束：无需安装任何东西，没有数据离开边界，安全团队无需进行威胁建模，需要防御的依赖面最小。
• 约束会趋同。解决同一形状问题的两个领域，即使不交流，也会得出相同的工程决策。
• 对照 FDE 工具通常被划分的四个类别——可观测性、评估、编排、护栏——我有三个。第四个缺失了，假装不是这样会是最无趣的事情。
• 可迁移的部分不是我的仓库。而是：一个明确的约束是区分工具和玩具的关键，而大多数业余项目从未明确过这个约束。

决策及其背后的原因

关于那个 SDK 调用，我当时理解错了。

我当时的表述是：SDK 在我的环境中无法工作，所以我写一个最小可用的替代品。合理。我实际做的是将工具的依赖面缩减到 fetch 和 TextDecoder——而这件事的后果，我甚至从未想过，是整个运行时都是可检查的。没有任何框架在我的代码和网络之间做巧妙的事情。当流异常终止时，我读的是自己的解析器。

这个特性在你自己的笔记本电脑上调试时毫无价值——你有调试器，时间充足。

但当你与别人的工程师通话，在别人的网络里，他们问为什么响应被截断，而真实的答案需要在接下来的90秒内给出时，这个特性就是一切。

我当初并不是为此而构建的。但事实就是如此。

另外四个决策，同样的模式

一旦我开始观察，这个模式就没停过。

BYOK —— 自带密钥。我对自己说：我不想运行代理，不想持有任何人的凭据，也不想为陌生人的 token 付费。都是实话。但实际上：客户的密钥从不出浏览器，他们的提示词永远不会触及我控制的基础设施。无需协商数据处理协议，因为没有数据处理。“我懒得运行后端”的版本和“这能通过合规审查”的版本是同一个架构。

完全没有后端。我对自己说：静态托管免费，我不想为业余项目维护服务器。但实际上：没有服务器需要威胁建模，没有攻击面需要文档化，没有可用性故事需要讲述，也没有需要六周才能清除的供应商安全问卷。安全团队能最快批准的东西，就是不存在的东西。

每个工具都是一个 URL。我对自己说：分享链接比让人克隆仓库并运行 npm install 更容易。但实际上：零安装。没有任何东西进入客户的机器。最需要诊断工具的人，恰恰是最不被允许安装工具的人。

成本实时显示，而不是记录。我对自己说：这个数字很有趣，我想看到它变化。但实际上：批准续费的人可以无需询问任何人就读取它。我写了整个关于提示缓存是未被衡量的最廉价优化的论点，但仍然把它框定为工程卫生问题。不是。这是信任问题，而信任决定了一个部署能否存活。

四个决策。四个我当时给出的理由，真实但肤浅。它们背后有一个共同的约束，我从未说出口。

浏览器端运行的实际代价

我不想让这听起来比实际更干净，所以让我反驳自己一下。

浏览器端运行对于很多软件来说确实是个糟糕的选择。你无法处理服务器端密钥。你需要不断应对 CORS——对于某些供应商，你干脆就输了，因为他们不发送头部，你从浏览器标签页无法做任何事。你没有真正意义上的持久存储，没有定时任务，没有后台处理，无法做任何计算密集型的事情。你无法这样构建产品。我不会假装你可以。

但这些限制对于诊断工具来说都不构成约束。

万用表不需要数据库。告诉你系统为何行为异常的工具，不是系统本身。它必须可信、可移植、可读——并且必须在所有更重的东西对你不利时，在确切时刻工作。我列出的每一个代价约束都与此任务无关，其中两个（无存储、无服务器）正是它能在拒绝真正部署的地方被使用的理由。

限制和资格是同一事实的两个侧面。

地图

FDE 工具通常被分为四个类别：Agent 编排、评估、护栏和可观测性。我把我的东西放进了这些框里。

| 类别 | 工具 | 功能 | | --- | --- | --- | | 可观测性 | claudoscope | 对实时调用进行 X 光检查——token 组成、缓存读写、成本，在响应流式传输时 | | 可观测性/调试 | agent-replay | 将完成的 agent 追踪回放为时间线，而不是嵌套的 JSON 墙 | | 预检 | context-lens | 在发送前统计提示词——窗口位置、成本、缓存边界 | | 评估 | prompt-lab | 两个提示词，一个输入，并排显示输出、延迟和成本 | | 编排 | tool-lab | 沙盒化工具使用循环——定义工具、模拟响应、手动驱动 | | 护栏 | — | — |

三个类别覆盖了，一个预检福利，一个缺口。

我想谨慎一点，因为这篇文章可能会变成带着 FDE 帽子巡览作品集，那样毫无价值。所以：我没有计划这张地图。这是事后的回顾。这些工具是一个接一个在几个周末里构建的，我当时能说出的唯一主线是“让 Claude API 变得可读”。这些类别来自别人的领域。匹配是真实的，但也是偶然的，两者可以同时成立。

无法掩盖的缺口

护栏缺失了，而这正是现场最需要的东西。

护栏是让模型输出保持在代码可以安全消费的形状内的层。你要求 {"risk": "high"|"medium"|"low", "score": 0-100}。但实际返回的，在足够多的调用中：

• 用 Markdown 围栏包裹的 JSON
• "HIGH" 而不是 "high" —— 枚举漂移
• "very high" —— 一个不存在的枚举值，现场编造
• "score": "85" 作为字符串，悄无声息地破坏下游算术
• score 完全缺失
• JSON 之前的一段散文

每一个都会导致你的解析器崩溃，或者更糟——不会崩溃，而是悄悄地给某人的仪表板贴上一个错误分类。

这需要工具而不是单元测试的原因是，这些失败是分布式的。你运行一次，它工作，你发布。然后每四十次调用中就有一个返回幻想的枚举，你永远看不到，因为你只看了样本。你需要的是失败率，按失败类型细分，运行五十次。这是一个与“它是否工作”不同的问题。

所以这就是第六个工具，也是下一个要构建的诚实工具：定义一个模式，对 N 次运行一个提示词，展示它出错的分布方式。与其余工具相同的约束——浏览器端、BYOK、无后端，因为现在这些已经不是偏好，而是规格。

这一切为何能推广

去掉我的仓库，只剩下一个值得保留的想法。

大多数业余项目没有约束。这就是为什么它们读起来像玩具——不是因为它们小或未完成，而是因为没有任何东西是被迫的。任何决策本可以走向另一个方向，什么都不会坏。读者能感受到这一点。

一个有明确约束的工具读起来完全不同，即使只有五十行。“这个在标签页中运行，因为它必须在无法安装任何东西的地方工作”是一个设计简报。“这是一个 React 应用”则不是。前者告诉你作者面对的是什么；后者告诉你他们打了什么字。

让我感到不舒服的是，我始终拥有这个约束，却无法命名它。我在一个无意识遵循的规则下交付了五个东西，因为我从未说出来，所以我也无法告诉别人这项工作证明了什么。它看起来像五个小工具。实际上是一个立场。

如果你是一个前端工程师，看着当前 AI 招聘市场，想知道如何让你变得可读：你很可能已经在仓库里有了约束形状的工作。关键不是构建新东西，而是回去搞清楚你实际在解决什么，然后写在 README 里。

我的这个过程花了一年，再加上一个陌生人关于安全团队的一句话。

这是关于企业 AI 最后一公里的系列第二部分。第一部分是《没有人的模型失败了。是接口失败了》。第三部分是关于我一直挂在嘴边但尚未充分辩护的东西——在这种工作中，交付物不是提示词，而是评估。