@actiondock/cli

ActionDock 2.x 官方命令行门面工具链。

@actiondock/cli 提供 ad 命令行接口，用于开发、测试、构建、分发和运行 AI 智能体工具与技能。

运行环境

• 原生基于 Node.js >=24.12.0 运行，充分依托原生类型擦除、内置 SQLite 与原生 HTTP 特性。
• 支持 npm、pnpm 与 yarn 标准包管理器进行全局安装与项目级管理。
• 日常开发、调试、测试、构建、打包、MCP 服务启动与 HTTP 部署完全基于 Node.js 与 npm 标准工作流，无需安装外部编译器。

安装方式

使用标准包管理器全局安装：

npm install -g @actiondock/cli

也可以在项目中通过 npx 临时调用：

npx ad --help

快速上手流程

• 初始化项目脚手架：

ad init my-tools
cd my-tools
npm install

• 安装并锁定依赖（基于 actiondock.lock.json 与原子事务）：

ad add @actiondock/example-tools

• 本地执行 Action：

# 扁平参数赋值（规范语法，推荐）
ad run sample.greet -- name=Alice

# 传递 JSON 标量与结构（数值校验为有限数）
ad run sample.greet -- name=Alice count:=1

# 复杂参数或对象从文件读取（与扁平参数互斥）
ad run sample.greet --input-file input.json

# 原始文本管道绑定（假定已注册 summarize 动作且 text 是字符串入参）
# 可与扁平赋值组合，与 --input / --input-file 互斥
printf '这是一段正文' | ad run summarize --stdin-field text -- style=brief

# 自动化与脚本通过标准输入传递
cat input.json | ad run sample.greet --input-file -

• 运行单元测试：

ad test

• 启动为 MCP 协议服务：

ad mcp

• 导出为便携式 Agent Skill 资产：

# 默认源码模式浅导出（保留 uses 逻辑契约）
ad export skill

# 独立自包含 Node.js 目录型导出（免全局 ad 命令行）
ad export skill --standalone --vendor-deps

# 显式物化外部依赖导出（展开为微型工作区）
ad export skill --bundle-deps

• 构建 Node.js 目录交付产物：

ad build

• 打包为标准 npm tarball：

ad pack

通用选项与调用契约

所有 CLI 子命令均支持传入通用控制选项：

• -v, -V, --version：打印版本号并退出。
• -h, --help：打印命令帮助并退出。
• --json：以标准 JSON 格式输出结果。
• --data-dir <path>：指定运行时数据库存储目录（包级 runtime.db、全局 global.db 与目录排他锁），实现多测试或多任务运行数据隔离。注意：本选项仅隔离 SQLite 数据文件，环境配置（profile）与全局注册表（registry）属于用户根目录资产，不受 --data-dir 影响。
• ACTIONDOCK_HOME=<path>（环境变量）：指定 ActionDock 用户根目录基准（默认对应操作系统的用户主目录）。如需隔离环境配置 profiles.json、全局注册表 registry.json 或本地证书，请通过设置此环境变量实现沙箱与自动化测试隔离。

严格目标解析机制

• 严格目标定位：通过 -P, --package <id|path> 指定目标包。系统严格区分物理路径与注册表包标识符，若目标不存在则不向当前目录或父级目录隐式回退，直接以参数校验错误退出。
• 多目标检索契约：在执行多目标检索（如 ad info 或 ad list）时，若无任何匹配项，在机器模式下始终返回确定性空数组结构并以状态码 0 退出，不因空搜索产生异常中断。
• 服务端细粒度白名单：通过 ad serve 启动微服务时，支持通过 -P, --package <package-id> 与 -A, --action <action-ref> 分别指定包白名单与动作白名单（支持短名与全限定名，可多次指定或逗号分隔）。同时配置时取权限交集。未授权动作的详情调阅与执行均被阻断并返回 403 错误（错误码 ACTION_FORBIDDEN），历史运行记录与 MCP 协议工具暴露同步过滤。

Action 执行入参契约

执行 Action 推荐使用扁平参数赋值协议，同时支持传统选项，三者之间严格互斥：

• 规范调用语法：ad run <action> [control-options] -- <assignments...>。
• 协议边界：-- 分隔符作为控制平面选项（如 --json、--config、--data-dir、--profile 等）与数据平面（Action 入参）的协议边界。
• 两种赋值操作符语义：
  • path=value：严格保留为字符串，不执行 JSON 解析与类型猜测。
  • path:=json：严格解析为 JSON 值，递归校验所有数值为有限数（Number.isFinite）。
• 路径语法规则：
  • 命名段（^[A-Za-z_][A-Za-z0-9_-]*$）表示对象属性。
  • 纯数字段（^(0|[1-9][0-9]*)$）表示数组索引，数组索引必须从 0 开始连续编号，拒绝稀疏数组。
  • 根节点始终物化为对象。
  • 路径冲突（叶节点与容器冲突、对象与数组冲突、重复赋值）严格拒绝（INPUT_PATH_CONFLICT）。
  • 拦截原型污染敏感属性（__proto__、constructor、prototype）。
• 三种输入模式互斥：扁平参数、--input 与 --input-file 严格互斥，不可混用（INPUT_CONFLICT）；未指定输入时默认为 {}。
• 原始文本管道绑定：printf '正文' | ad run <action> --stdin-field <field> [-- <assignments...>] 将 stdin 完整正文原样绑定为指定顶层字段的字符串值（不解析类型、不剥 BOM、不修剪空白、空输入为空字符串）；可与扁平赋值组合，与 --input / --input-file 互斥；stdin 源字节与绑定后的最终入参序列化大小各自受默认 10MiB 上限约束，分别超限报 INPUT_LIMIT_EXCEEDED 与 FLAT_INPUT_LIMIT_EXCEEDED，JSON 转义放大也计入最终大小；严格 UTF-8 校验失败报读取错误。管道非事务，高风险写入先完整生成并校验再执行。
• 传统输入选项：
  • 简单内联参数：使用 --input <json> 直接解析 JSON 字符串。
  • 复杂对象文件：使用 --input-file <path> 读取文件并解析 JSON，避免各类终端的引号转义损坏。
  • 标准输入管道：使用 --input-file - 从标准输入读取全部数据并解析 JSON。
  • 统一解析：JSON 输入在解析前剔除 UTF-8 BOM，默认大小上限为 10MiB；改用文件不会解除限制。原始文本绑定保留正文 BOM。

Windows 与多终端传参建议

针对 Windows PowerShell、cmd 以及各终端中复杂 JSON 容易遇到的双引号转义问题，推荐按以下规范传参：

• 扁平参数传参（推荐）：使用 -- 分隔并传参，如 ad run greet -- name=Alice 或 ad run greet -- name=Alice count:=1。
• 复杂结构：推荐先保存为 JSON 文件并使用 --input-file，如 ad run complex-action --input-file input.json。
• 动态生成输入：通过管道输出配合 --input-file - 传递，在 PowerShell 中可执行：

$data = @{
  name = "Alice"
  options = @{
    lang = "zh-CN"
  }
}
$data | ConvertTo-Json -Depth 100 | ad run complex-action --input-file -

Action 输出模式与机器模式

• 默认纯文本输出：ad run 默认采用纯文本模式。标量直接输出；结构化对象完整输出为标准 JSON 格式到 stdout；不进行私有业务字段自动嗅探。
• 显式正文输出与默认注解：
  • 显式指定正文字段：通过 ad run <id> --text-field <field> -- ... 提取结果中特定顶层自有字符串字段输出至 stdout（保留真实换行且无 JSON 转义），其余字段以 JSON 对象形式输出至 stderr（元数据为空时不输出）。
  • 声明式默认正文：Action 清单中声明 annotations["actiondock.cli"] = { "textField": "<field>" } 时，未指定 --text-field 时自动按声明提取正文与元数据；显式 --text-field 优先于默认注解。
  • 严格校验与契约闭环：正文字段缺失、非字符串或返回数据非对象时，明确输出错误并以退出码 1 退出，不静默回退，不改写运行记录。契约通过 ad describe 呈现通道语义与覆盖指引，并通过 ad validate 进行纯静态元数据合规校验。
  • 参数互斥：--text-field 与 --json、--async 严格互斥，在执行前校验并以退出码 2 退出。
• 机器模式（--json）：当需要以程序化方式消费、获取完整结构化数据或被外部系统集成时，传入 --json。此时始终输出完整执行信封（包含 ok、runId、data 或 error），忽略默认正文注解；若参数解析出错输出标准错误信封并以退出码 2 退出。

常用命令速查

架构集成

作为顶层门面与独立运行分发器，@actiondock/cli 串联以下子包：

• 领域内核与运行时：依赖 @actiondock/core，统一对接标准服务端口体系（DiscoveryPort、ExecutionPort、RunsPort、ConfigPort、StatePort）与统一服务门面（createActionDock、connectActionDock），承载原生运行时、存储驱动与受管进程治理。
• 构建与打包：依赖 @actiondock/builder，完成依赖闭包规划、Node 目录交付产物构建、npm 打包与 Agent Skill 资产导出。
• 协议服务：通过 @actiondock/mcp 启动 Model Context Protocol 协议监听与适配。

开源协议

本项目采用 Apache-2.0 开源协议。