在传统代理框架中，工具集通常是预先定义并一次性注入的，模型的工具表面随着功能增加而不断膨胀，导致选择困难和上下文污染。Tendril 作为一种自扩展代理运行时，采用了一种根本不同的策略：让模型在运行时自主发现能力缺口、动态构建新工具并注册到持久化注册表中，从而实现「一次构建、长期复用」的正向循环。本文将深入剖析这一自扩展机制的核心组件，探讨动态工具构建的工程细节、运行时注册协议的设计考量以及版本化工具链的管理实践。
自扩展代理的核心设计理念
Tendril 的设计灵感来源于「能力发现」而非「工具堆砌」。当用户提出请求时，代理首先查询本地能力注册表，如果所需工具已存在则直接执行，否则模型将自行编写工具代码、注册并执行。这种模式的核心优势在于：模型的可见工具集始终保持精简，仅包含三个引导工具（listCapabilities、registerCapability、executeCode），而实际能力则通过注册表动态扩展。注册表采用工作区内的纯文件存储结构，index.json 负责维护能力元数据，tools/ 目录存放各工具的 TypeScript 实现。每次会话结束后，新构建的工具会被持久化到磁盘，下次启动时自动加载，实现跨会话的能力累积。
这种设计解决了传统代理框架中的「工具过多」问题。在大多数框架中，开发者倾向于将所有可能用到的工具一次性暴露给模型，期望模型能够正确选择，但随着工具数量增长，模型的选择准确率显著下降。Tendril 逆转了这一局面：模型始终只看到三个引导工具，需要什么能力时自行构建，注册表随之膨胀而工具表面保持不变。这种「能力即服务」的架构使得代理能够像生物体一样通过学习不断强化自身，适应复杂多变的任务需求。
动态工具构建的运行时机制
动态工具构建是自扩展代理的核心能力，其实现依赖于三个引导工具的协作。第一个工具 listCapabilities 负责查询注册表中已存在的能力，接受自然语言查询并返回匹配的工具列表及其元数据（名称、描述、触发条件等）。第二个工具 registerCapability 负责将新构建的工具注册到系统中，它接受工具名称、能力描述、触发词和代码实现，将这些信息写入 index.json 并在 tools/ 目录下创建对应的 TypeScript 文件。第三个工具 executeCode 负责在沙箱环境中执行任意代码，接受工具名称和参数，加载对应工具的实现并通过 Deno 子进程执行。
动态构建的执行流程遵循严格的顺序：模型接收到用户请求后，首先调用 listCapabilities 搜索现有工具，如果返回结果为空则进入工具构建阶段。模型根据任务需求编写 TypeScript 代码，通过 registerCapability 完成注册，然后调用 executeCode 执行新工具。整个过程对用户完全透明，模型不会询问「是否需要创建工具」，而是自主决策并执行。这种无干扰的自主行为来自于系统提示词的约束：规则明确要求模型在发现能力缺失时必须自行构建工具，而非请求用户确认。
工具代码的运行环境由 Deno 子进程提供，采用受限的权限控制。配置文件中的 sandbox.timeoutMs 参数控制单次执行超时时间（默认 45000 毫秒），allowedDomains 数组限制网络访问范围，空数组表示无限制。这一设计确保了动态构建的工具不会对系统造成安全风险，同时提供了足够的灵活性支持各类网络请求和数据处理任务。
运行时注册协议与数据模型
运行时注册协议建立在 JSON-RPC 2.0 之上，通过 NDJSON（换行分隔的 JSON）格式在 stdin/stdout 上传输。Tauri 主机作为 ACP（Agent Integrator Specification）协议的 host 端，通过 spawn 启动 Node.js SEA（Single Executable Application）构建的代理进程，双方通过 JSON-RPC 消息进行双向通信。这种设计将代理实现与桌面外壳解耦，代理本身是独立可执行的进程，宿主应用只需关注协议解析和事件转发。
能力注册表的数据模型设计兼顾了灵活性和可维护性。每个能力条目包含四个核心字段：name（蛇形命名的唯一标识符）、capability（一句话能力描述）、triggers（触发词数组，用于自然语言匹配）和 suppression（抑制条件数组，用于防止误触发）。当模型调用 listCapabilities 时，注册表会根据查询词与 triggers 字段的匹配程度返回候选工具列表。触发词的设计使得模型能够通过自然语言描述快速定位所需能力，而抑制条件则用于处理边界情况，例如在特定上下文下禁用某个工具。
注册表文件存储在用户选定的工作区目录中，采用纯文本格式便于人工检查和版本控制。index.json 作为注册表索引记录所有能力的元数据，tools/ 目录下的每个 TypeScript 文件对应一个可执行工具。这种文件化的存储方式允许用户直接编辑、删除或迁移工具，而无需通过专用接口。对于团队协作场景，注册表文件可以纳入版本控制系统，实现工具能力的共享和追溯。
版本化工具链管理的工程实践
虽然 Tendril 的当前实现侧重于工具的动态构建和注册，但在生产环境中，版本化工具链管理仍然是确保系统稳定性的关键因素。动态构建的工具可能存在缺陷，错误修改可能导致已有功能失效，因此需要建立完善的版本控制和回滚机制。基于 Tendril 的架构设计，工具版本化管理可以在以下几个层面实现：注册表层面的版本字段、工具文件的历史快照以及注册表的 Git 化管理。
在注册表层面，可以在 index.json 的每个能力条目中增加 version 字段和 changelog 字段。version 采用语义化版本号（主版本。次版本。补丁版本），每次通过 registerCapability 更新工具时自动递增。changelog 记录每次更新的变更描述，便于追踪工具能力的变化。这种轻量级的版本元数据方案无需额外的存储开销，却能为调试和回滚提供必要的信息支持。
工具文件的历史快照可以通过将工作区目录纳入 Git 版本控制实现。每次工具构建或更新时，Git 自动记录变更历史，出现问题时可以快速回退到任意历史状态。对于更细粒度的版本管理，可以考虑在工具代码中嵌入版本声明，例如通过 JSDoc 注释或专用配置文件记录工具的创建时间、作者和依赖信息。这些元数据在工具数量增长后对于维护工作的顺利进行至关重要。
在监控和告警层面，建议对注册表的变更操作进行日志记录。每次 registerCapability 调用成功后，记录操作类型（创建 / 更新）、工具名称、时间戳和操作用户，这些日志可以存储在专用文件中或推送到集中式日志系统。通过对注册表变更频率和失败率的监控，可以及时发现异常情况，例如短时间内大量工具注册可能表明模型进入了不稳定的自扩展循环。
工程落地的关键参数与监控点
将自扩展代理运行时部署到生产环境时，需要关注以下关键配置参数和监控指标。超时控制方面，sandbox.timeoutMs 建议设置为 30000 到 60000 毫秒之间，具体取值取决于预期工具的复杂程度。对于涉及大量网络请求的工具，可以适当调高超时阈值；对于本地计算密集型任务，可以降低阈值以加快失败检测。allowedDomains 配置在初始阶段建议设置为空数组以获取最大灵活性，待系统稳定后根据实际需求限制为特定域名列表。
注册表规模监控是另一个重要维度。可以通过定期检查 index.json 中能力条目的数量，设定阈值告警。当注册表规模超过预期（例如超过 100 个工具）时，可能需要考虑对工具进行分类整理或清理冗余能力。工具执行成功率和平均执行时间也是关键指标，用于评估动态构建工具的质量和性能表现。如果某个工具的失败率持续高企，可能表明代码存在缺陷或依赖环境变化，需要人工介入检查。
安全监控方面，建议对 executeCode 的调用进行审计日志记录，包括调用者、执行的工具名称、参数摘要和执行结果。对于涉及网络请求的工具，还需要监控出站流量的异常模式，防止动态构建的工具被恶意用于数据泄露或攻击外部系统。Deno 沙箱的权限边界应定期审查，确保没有因配置错误而导致权限逃逸。
总结
自扩展代理运行时代表了代理系统设计的一次范式转变，从预先定义的工具集转向动态生长的能力注册表。Tendril 通过三个引导工具和持久化注册表实现了模型自主构建和复用工具的完整生命周期管理，其基于 JSON-RPC over NDJSON 的运行时协议和 Deno 沙箱执行环境为动态工具构建提供了安全可控的基础设施。在工程实践中，超时控制、注册表规模监控和执行审计是确保系统稳定运行的关键，而版本化工具链管理则需要在架构层面提前规划以支持长期演进。
资料来源：本文技术细节主要来源于 Tendril 开源项目（https://github.com/serverless-dna/tendril），该项目展示了自扩展代理的完整实现架构。