@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 退出。
常用命令速查
| 命令 | 说明 |
|---|---|
ad init [dir] | 初始化 Action Package 项目脚手架 |
ad add <package> | 安装并锁定 Action 依赖，更新 actiondock.lock.json 并提供原子回滚保护 |
ad remove <package> | 卸载并更新锁定依赖，提供原子回滚保护 |
ad info [patterns...] | 检索包元数据与能力清单，支持模式匹配与树形展示 |
ad list [patterns...] | 列出包内所有已注册的 Action |
ad describe <id> | 编码顾问：查看 Action 的详情、模式字段明细、Flat 编码指引、建议赋值与输出选择契约 |
ad run <id> | 本地或远程执行指定 Action（规范语法 ad run <id> [options] -- <assignments...>，支持 --stdin-field 绑定原始文本、--text-field 提取正文与 --json 输出标准信封） |
ad validate [id] | 校验 Action 规范、模式规范与输出选择契约 |
ad doctor | 执行运行环境与项目结构健康诊断 |
ad action create <id> | 创建新 Action 源码 |
ad playbook list / show | 查看智能体操作规程 Playbook |
ad config list / get / set | 管理包运行时配置与环境变量绑定 |
ad state list / get / set / delete / clear | 查看与维护 SQLite 持久化状态 |
ad runs list / show / watch / clear | 查询任务执行历史、阻塞等待运行终态聚合退出，或按时间与数量策略清理历史数据；list 支持 --request-id 过滤，watch 支持按 --request-id 反查等待（后台派工场景主控无 runId 时使用） |
ad test | 执行快速单元测试 |
ad build | 构建 Node.js 目录交付产物（支持 --vendor-deps 与 --archive） |
ad pack | 打包为标准 npm tarball（.tgz），支持 --dry-run |
ad export skill | 导出 Agent Skill 资产（默认单包源码浅导出，支持 --standalone 免全局工具自包含导出与 --bundle-deps 物化依赖） |
ad link / unlink | 注册或注销工作区全局路由与符号链接 |
ad profile | 管理远程执行节点凭证与环境配置 |
ad serve | 启动远程 HTTP/HTTPS 执行调度微服务（支持 -P 包白名单与 -A 动作白名单细粒度权限控制，原生支持 --https 自签名与生产证书） |
ad mcp | 以 STDIO 或 HTTP 协议启动 MCP 服务 |
架构集成
作为顶层门面与独立运行分发器，@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 开源协议。