在 Hacker News 上展示：Aclif – 代理CLI框架：统一语法，跨SaaS的规范名称

# aclif：代理CLI框架 来源：https://www.aclif.ai/ aclif 为AI代理构建命令行工具。代理获得一个单一工具，该工具在所有SaaS提供商间提供统一抽象：统一语法规则，以及在任何平台上都能通过相同名称访问相同记录的规范名称。 ## 立即试用 安装二进制文件，列出提供商，并阅读命令的模式、示例和安全元数据。 ``` npm install -g @aclif/core aclif discover --json aclif learn salesforce --json aclif learn servicenow --json aclif salesforce data query --schema aclif salesforce data query --examples aclif salesforce data query --query "SELECT Id FROM Account LIMIT 3" --dry-run aclif servicenow data query --table incident --query "active=true^priority=1" --dry-run ``` 入门指南 (https://www.aclif.ai/getting-started.html) | GitHub (https://github.com/agent-cli-framework/aclif) ## 为何代理需要自己的CLI MCP服务器发布固定的工具列表，列表中的每个工具在每一轮对话中都会占用代理的上下文空间。服务器构建时，作者在覆盖率与成本之间进行权衡。发布所有操作（一个典型API有数百个定义）使得整个API可达，但每一轮都会消耗所有对应的令牌。发布少数宽泛操作可以保持令牌数量较少，但作者未列入列表的任何操作对代理都不可达。跨多个平台的代理需要为每个平台配备服务器、登录机制、语法规则、错误格式和一套命名规范。 aclif仅在代理请求时才加载命令定义，因此每个提供商的整个API都可在无需长期上下文成本的情况下访问。一种语法、一个信封和一套错误词汇表覆盖所有提供商，因此无论代理访问一个还是五个平台，其上下文规模基本保持不变。 执行定义工作流的代理可以完全不依赖模型参与调用。人员或创作工具在设计时制定确切命令，并将其作为字符串嵌入工作流。运行时，代理将该字符串作为普通代码执行，无需加载工具定义，也无需推理。命令在设计时选定，而运行它的权限、凭证、操作身份和策略则在运行时由运行它的任何组件提供。双方都无需同时持有两者。 ## 每个命令提供的特性 ### 统一语法 所有提供商采用统一的命令结构、JSON信封和错误词汇表。代理只需学习一次工具，新平台可通过增加命令而无需改变语法来扩展功能。JSON清单可以通过同一个HTTP端点增加命令，无需编写代码。 ### 规范名称 别名集将`customer`映射到某个Salesforce实例中的`Account`，以及ServiceNow中的`core_company`。租户目录在部署时从每个实例捕获，使CLI能学习每个实例的自定义对象和字段，无需更改提供商配置。 ### 代理可处理的错误 代理可在单轮对话中恢复。每个错误都明确命名故障类型、修复该故障的命令，以及当提供商的分类器有针对该错误的重写规则时，包含可直接重发的修正后输入。分类器是纯代码，不依赖模型。在设计时于Shell中验证的命令，在运行时任何主机下都返回相同的错误，因为相同的命令类在两种环境下运行。 ### 无需执行的内省 `--schema`、`--examples`、`--shape` 及另外四个标志在命令执行前返回结果，无需凭证，且不消耗任何API配额。代理可在速率受限的实例上进行发现、学习、内省和预览，而不产生任何开销。 ### 可嵌入的运行时 相同的命令类在提供凭证、身份和策略的主机进程内运行，主机保持连接活跃，并缓存每个实例的高成本登录。基于此构建的网关可与企业自身身份提供商和密钥库协同工作。 ### 声明式安全 每个命令都声明了可变性、影响范围、可逆性和幂等性。策略检查可在命令代码加载前拒绝执行。每个接受`--dry-run`的变更操作，在元数据说明时要求`--confirm`，并在每次运行后写入审计日志行。 ## 内省优先的工作流 代理无需二进制文件以外的文档，且在最后一步之前无需接触API。 ``` aclif discover --json # 所有提供商、其层级、凭证是否已配置 aclif learn salesforce --json # 简报：主题、关键字段、查询语法、认证路径 aclif salesforce data query --schema # 标志、参数、安全元数据，不执行 aclif salesforce data query --examples # 可运行示例及其产生的响应 aclif salesforce data query --query "SELECT Id, Name FROM Account LIMIT 5" --dry-run aclif salesforce data query --query "SELECT Id, Name FROM Account LIMIT 5" --json ``` 信封的`_context`块包含分页信息，精确的下一个命令、可用字段以及值得运行的相关命令。退出代码为 0、1（API）、2（用法）、3（认证）。合约及其JSON模式见 CONTRACT.md (https://github.com/agent-cli-framework/aclif/blob/main/docs/CONTRACT.md)。 ## 三种运行方式 厂商CLI针对单一部署构建：安装在机器上，由键盘前的用户登录，每个命令一个进程。在网关后失败。每次调用生成一个进程并重新登录，操作用户身份无法转发，无命令功能声明，审计不统一。aclif的命令类在三种场景下不变地运行，运行它们的任何组件决定谁提供凭证、执行策略并维护审计追踪。 - **由代理运行。**代理进程生成二进制文件，执行命令，并读取其返回的JSON。凭证来自标志、环境变量或代理自身环境中的配置文件。当一个代理、一个操作员和一组凭证共享信任边界时使用此方式。 - **由主机应用程序运行，即设计时场景。**应用程序位于模型和aclif之间并持有凭证。模型调用应用程序定义的工具，应用程序执行命令（在进程内或通过将命令字符串传递给CLI）。人员或创作工具使用此方式让模型发现提供商、内省命令，并验证将要写入代理的确切命令。当模型必须永远不持有凭证且工具定义必须保持在其上下文之外时使用此方式。 - **由网关运行，即运行时场景。**已部署的代理提交命令，一个长期运行的进程为多个此类代理服务。网关在每次请求时从企业密钥库解析凭证，根据操作用户检查策略，记录每次调用，并保持连接活跃。代理不持有提供商凭证，且无法扩大自身权限范围。当多个代理共享提供商且需要一个集中位置管理策略和审计时使用此方式。 | 运行方式 | 由代理运行 | 由主机应用程序运行 | 由网关运行 | | :--- | :--- | :--- | :--- | | **凭证** | 标志、环境变量、`config.yaml` | 主机提供的解析器 | 密钥库支持的解析器，每次请求 | | **策略** | `config.yaml` | `capabilityGate`钩子 | `capabilityGate` 加上主机的中间件 | | **身份** | `--identity-token` 或环境变量 | 调用时的操作用户 | 请求中的操作用户和SSO声明 | | **审计** | 每次运行的stderr行 | 报告程序事件 | 报告程序事件，由主机记录 | | **连接** | 文件会话缓存 | 运行时池 | 运行时池，按实例和身份键控 | 详细信息请见嵌入页面 (https://www.aclif.ai/embedding.html)。 ## 网关部署 长期、可嵌入的部署支持网关拓扑结构，可实施额外的安全策略。一个企业运营的进程为每个代理执行每个命令，该部署提供： - **凭证集中管理。**在网关内根据每次请求从企业密钥库解析。代理不持有任何凭证。 - **企业范围的规范名称。**租户目录和别名集由网关持有，因此每个代理在所有提供商和实例中对相同记录使用相同名称。 - **每次调用归属到人。**操作用户的身份随每次调用进入策略检查和审计记录，即使通过共享服务账户。 - **策略执行一次。**每个命令声明其功能，网关在命令代码加载前检查该声明。代理无法扩大自身权限范围。 - **统一审计追踪。**来自每个代理的每个命令的相同事件，记录用户、命令和结果。 ## 安装或自行构建 ``` npm install -g @aclif/core # 您组织的My Domain URL，不带尾部斜杠 export SF_INSTANCE_URL=https://example.my.salesforce.com # 来自Salesforce CLI的会话令牌（如需要，先执行 sf org login web） export SF_ACCESS_TOKEN=$(sf org auth show-access-token -o [email protected] --json | jq -r .result.accessToken) aclif salesforce data query --query "SELECT Id, Name FROM Account LIMIT 3" --json ``` 无需Salesforce CLI，可使用API用户。Salesforce在设置或重置密码时会通过邮件发送安全令牌： ``` export SF_INSTANCE_URL=https://example.my.salesforce.com [email protected] SF_PASSWORD=... SF_SECURITY_TOKEN=... aclif salesforce data query --query "SELECT Id, Name FROM Account LIMIT 3" --json ``` `aclif`二进制文件包含所有内置提供商，需要Node 22或更高版本。您分发的二进制文件属于您：一个脚手架命令即可生成具有自身名称、配置目录、环境变量和所选提供商的CLI。参见入门指南 (https://www.aclif.ai/getting-started.html) 和构建CLI (https://www.aclif.ai/build-a-cli.html)。 ## 提供商 Salesforce、ServiceNow、DocuSign和Agentforce是原生提供商，包含在每个版本中。Google Workspace（Gmail、Calendar）由社区贡献。私有层级保存Fork版本保留的提供商，位于上游永远不会提交的路径下。编写提供商工作量很小：只需将平台的API规范直接映射到命令接口，编码代理可从仓库中的示例提示词完成此工作，合规套件会检查结果。参见提供商列表 (https://www.aclif.ai/providers.html)。 aclif采用MIT许可证。贡献请遵循CONTRIBUTING.md (https://github.com/agent-cli-framework/aclif/blob/main/CONTRIBUTING.md)；指导人员和编码代理修改框架的指南是AGENTS.md (https://github.com/agent-cli-framework/aclif/blob/main/AGENTS.md)。