实现原理 / 工具 DSL：语法、运行机制与 Agent 生成指南

shenyubao · 2026/10/22

AntTools 的工具由 JSON 定义的界面与状态，以及 本地 QuickJS 沙箱中的 JavaScript 组成。Agent 生成完整的 .anttool.json 工具包，宿主负责校验、渲染、事件分发和执行，无需为每个工具创建 React 页面。

本文对应 DSL v1（schemaVersion: 1）。为避免 Agent 提示、开发文档与 Blog 分别维护后产生差异，下面的关键章节直接引用仓库中的统一 Markdown。协议细节、SDK 参数及可运行示例只维护一份；文章提供同一版本的原文入口，适合直接交给 Agent 使用。

1. 从定义到运行

工具包：definition + script
        ↓
结构与状态路径校验
        ↓
共享 DSL 渲染器：显示控件、接收输入与动作
        ↓
本地 QuickJS Worker：run({action,state},sdk)
        ↓
宿主应用 patch，刷新输出

definition 描述状态、控件、双语标签、样例与测试；script 只描述计算逻辑。脚本不能创建 React 组件、调用宿主剪贴板或执行任意系统命令。工具输入、密钥和文件保留在本地，生成工具时只使用合成数据。

2. 统一的界面标准

输入栏统一为 系统操作 | 工具控件：剪贴板、示例、清空和文件读取由宿主管理；单行输入、Select、单选/复选项和执行按钮归入工具控件。宽度足够时显示一行，空间不足时自然换行，标签与输入保持完整。宿主统一提供分隔符、26px 控件高度及交互样式，工具不自行注入 CSS。

多行源文本继续使用编辑器。JSON 输出直接使用宿主的统一查看器，获得高亮、折叠、搜索、格式化与复制/保存等能力，不再分别生成文本和树形面板，也不重复拼装按钮。

3. Agent 规范与完整文档

以下关键章节由发布流程从 docs/tool-agent-guide.md 展开；包结构、组件、全部 SDK 操作及事件协议见完整 Markdown 原文。应用内 Agent 提示使用完整原文。修改规范后应重新生成、验证和发布，下面的哈希可用于核对具体版本。目标客户端是否支持某项能力，以实际发布版本为准；工作区中的实现不代表线上已开放所有功能。

原文：下载 Markdown 原文

文档版本（SHA-256）：e943388c0eb0c2228bc8170e810098a055ea94a17ed317bebe300b34f14005e8。

AntTools 工具生成规范（Agent Guide）

适用于 AntTools DSL v1。宿主提示和 Blog 从本文件生成。可用能力以客户端发布版本为准。

中文采用短句、单条指令和固定术语。维护规则见 docs/tool-agent-guide-style.md。

2. 输入栏与样式

使用共享 DSL 生成界面。禁止工具 ID 专属页面。

输入栏使用 type: "toolbar", props: {role: "input"}：

输入：剪贴板 示例 清空 文件读取 | 工具输入、选项、执行按钮

区域	内容
系统操作	`host.*` 按钮
工具控件	单行输入、选项、设置入口及 `generate`、`now`、`sign` 等动作
输出区域	展示选项、复制、保存和 JSON 操作

将短文本输入放入所属输入栏。
使用 showLabel: true 保持标签与输入框完整。
将多行文本放入 editor。
多输入工具为各区域提供粘贴和清空按钮。
全局示例按钮只保留一个。
生成器将参数和执行按钮放入输入栏。
高级配置可使用 group.props.settings。
条件控件可使用 props.visibleWhen。

宿主提供 |、26px 控件样式和交互状态。没有可见工具控件时，宿主隐藏 |。宽窗口显示一行。窄窗口允许换行。

禁止自建 Select 或注入 CSS。禁止手动插入 |。输出编辑器已有操作栏，禁止重复添加操作按钮。

5. 系统动作与安全

系统动作	行为
`host.sample`	合并初始状态与第一个样例，执行 change
`host.clear`	恢复初始状态，取消执行，不重新执行
`host.empty.<field>`	清空字段，执行绑定修改
`host.paste.<field>`	粘贴文本，执行 change
`host.copy.<field>`	复制完整字段值
`host.use.<field>`	将结果作为 input
`host.image.<field>`	读取本地图片 data URL，动作名 image
`host.binary.<field>`	读取本地文件 base64，动作名为字段路径
`host.pasteImage.<field>`	粘贴图片 data URL，动作名 image
`host.saveImage.<field>`	保存图片 data URL

系统动作由用户触发。禁止脚本调用系统动作。禁止生成 host.quick。

脚本在本地 QuickJS Worker 中执行。SDK 通过参数传入。

仅使用宿主支持的组件和 SDK 操作。
禁止外部 import、fetch、DOM、Node/process、Tauri 和 shell。
禁止网络图片、任意文件访问和宿主凭据访问。
禁止访问 macOS Keychain 或依赖 keyring。
将真实输入、密钥和文件保留在本地。
禁止向远程 Agent 发送真实数据。
样例和测试仅使用合成数据。

剪贴板权限由宿主管理。宿主将选定文件的内容写入本地绑定。脚本不获得文件路径权限。

7. 样例与验证

为创建器提供 1–3 个合成样例和 1–3 个确定性测试。普通 DSL 允许空样例或空测试数组。

测试字段	规则
`state`	与初始状态合并
`expect`	匹配本次补丁；创建器禁止空预期
对象	递归子集匹配
数组	完整值匹配
点分补丁键	使用相同的键字符串

禁止为时钟或随机值编写固定值断言。预期失败的输入使用独立断言验证。

校验工具包结构。
执行初始状态。
执行全部样例和测试。
在浏览器和原生宿主检查输入、选项、双语、换行及导出。

初次执行、样例和定义内测试必须成功。未执行验证时，禁止声称测试通过。宿主诊断可能仅含代码和测试序号。

4. 如何验证和交付

先校验包结构，再运行初始状态、全部合成样例和确定性测试。tests.expect 检查本次返回的 patch；对象采用递归子集匹配，数组按完整值比较。预期报错的输入应另做执行断言，不混入创建器要求通过的测试。

最后在真实宿主检查输入修改、参数切换、示例、清空、双语标签、窄窗口换行、复制与本地文件操作。Node 沙箱测试只能验证计算逻辑，不能代替浏览器和原生 UI 验收。未实际执行验证时，不要声称测试已通过。

仓库保留了 content/blog/examples/text-case.anttool.json 与 content/blog/examples/json-view.anttool.json 两个补充示例。前者演示大小写、选项和点分 patch，后者演示 JSON5 SDK 调用、无效输入清理和共享 JSON 查看器。统一规范中的完整示例也可直接保存为工具包后校验。

5. 源码与版本边界

包结构与 JSON Schema 以 libs/tools/schema.ts、docs/tool-package.schema.json 为准；节点行为以共享渲染器为准；SDK 白名单以 sdk.ts、extended-sdk.ts、spider-sdk.ts 为准。创建器额外约束由 creator.ts、creator-validation.ts 校验。

现有 DSL 组合可以复用同一个渲染器和本地运行时。新增组件、SDK 操作或平台能力，需要修改并发布宿主框架；不要用任意脚本突破这些边界。