# @actiondock/cli 中文文档

规范地址：https://npmcn.com/package/%40actiondock/cli/

版本：2\.22\.0
npm 元数据更新时间：2026-10-29T09:01:51.859Z
中文译文更新时间：2026-11-07T07:47:59.091Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40actiondock/cli
原文对照：https://npmcn.com/package/%40actiondock/cli/?lang=original
项目主页：https://github.com/team4u/actiondock#readme
源码仓库：https://github.com/team4u/actiondock

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：486 kB，121 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.12\.0
- 运行依赖：6 个
- 首次发布：2026-09-02T08:50:39.704Z
- 最新版本发布：2026-10-29T09:01:51.432Z
- 近 30 天下载量：2005（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：47（近 12 个月 47 个）

## 中文简介

ActionDock CLI 用于开发、测试、建设和出口独立代理 动作和技能

## 安装

```sh
npm install @actiondock/cli
```

也可以使用：`pnpm add @actiondock/cli`、`yarn add @actiondock/cli`、`bun add @actiondock/cli`

## README

# @actiondock/cli

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

[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D24.12.0-green?logo=node.js)](https://nodejs.org/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?logo=typescript)](https://www.typescriptlang.org/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

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

* * *

## 运行环境

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

* * *

## 安装方式

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

```bash
npm install -g @actiondock/cli
```

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

```bash
npx ad --help
```

* * *

## 快速上手流程

-   初始化项目脚手架：

```bash
ad init my-tools
cd my-tools
npm install
```

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

```bash
ad add @actiondock/example-tools
```

-   本地执行 Action：

```bash
# 扁平参数赋值（规范语法，推荐）
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 -
```

-   运行单元测试：

```bash
ad test
```

-   启动为 MCP 协议服务：

```bash
ad mcp
```

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

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

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

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

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

```bash
ad build
```

-   打包为标准 npm tarball：

```bash
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 中可执行：

```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](https://npmcn.com/package/%40actiondock/core/README.md)，统一对接标准服务端口体系（`DiscoveryPort`、`ExecutionPort`、`RunsPort`、`ConfigPort`、`StatePort`）与统一服务门面（`createActionDock`、`connectActionDock`），承载原生运行时、存储驱动与受管进程治理。
-   构建与打包：依赖 [@actiondock/builder](https://npmcn.com/package/%40actiondock/builder/README.md)，完成依赖闭包规划、Node 目录交付产物构建、npm 打包与 Agent Skill 资产导出。
-   协议服务：通过 [@actiondock/mcp](https://npmcn.com/package/%40actiondock/mcp/README.md) 启动 Model Context Protocol 协议监听与适配。

* * *

## 开源协议

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

## 常见问题

### @actiondock/cli 是什么？

ActionDock CLI 用于开发、测试、建设和出口独立代理 动作和技能

### 如何安装 @actiondock/cli？

在项目目录运行 npm install @actiondock/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 ad、actiondock，可以用 npx ad 直接运行。

### @actiondock/cli 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @actiondock/cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @actiondock/cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @actiondock/cli 可以商用吗？

@actiondock/cli 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @actiondock/cli 的下载量有多少？

根据 npm 官方下载统计，@actiondock/cli 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,005 次，日均约 67 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @actiondock/cli 还在维护吗？

最新版本 2\.22\.0 发布于 2026/10/29（9 天前）；至今共发布 47 个版本，其中过去 12 个月发布了 47 个；首次发布于 2026/09/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。