# @anna-ai/cli 中文文档

规范地址：https://npmcn.com/package/%40anna-ai/cli/

版本：0\.1\.64
npm 元数据更新时间：2026-11-06T10:27:50.762Z
中文译文更新时间：2026-11-06T23:49:42.940Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40anna-ai/cli
原文对照：https://npmcn.com/package/%40anna-ai/cli/?lang=original

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

- 包体积（解压后）：529 kB，97 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：8 个
- 首次发布：2026-04-30T08:31:42.496Z
- 最新版本发布：2026-11-06T10:27:50.567Z
- 近 30 天下载量：2151（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：46（近 12 个月 46 个）

## 中文简介

Anna App开发商CLI:脚手架,验证,取用(第2阶段MVP:init +验证).

## 安装

```sh
npm install @anna-ai/cli
```

也可以使用：`pnpm add @anna-ai/cli`、`yarn add @anna-ai/cli`、`bun add @anna-ai/cli`

## README

# @anna-ai/ cli (韩语)

Anna App 开发者 CLI — scolfold, 验证, 运行本地 Dev 牵引, 驱动 基于固定式回归测试,以及针对来自 `vitest`编号 :`pytest`第二阶段至第九阶段已经完成.

## 安装

最终用户安装( 在第一个 npm 发布后):

```bash
npm i -g @anna-ai/cli
anna-app --help
```

这个 `dev` 财务报告和审定财务报表 `fixture replay` 命令透明地获取被绑定的 Python 运行时间通过 `uvx` (无需矩阵-nexus的取出). 安装 [页:1](https://docs.astral.sh/uv/) 一次:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

本地 dev( 此重播) :

```bash
pnpm install
pnpm build
node dist/cli.js --help
```

## 图标

### `anna-app init <dir> [--slug <slug>] [--template minimal] [--force]`

脚手架 一个新的 Anna App 项目( 明显 + 捆绑 + stdio 插件) 模板). `__TOOL_ID__` 变成 `tool-dev-<slug>`。 。 。 .

```bash
anna-app init my-app --slug my-app
cd my-app
anna-app validate
```

### `anna-app validate [--manifest manifest.json] [--bundle bundle] [--strict]`

分层故障快速检查:遗产正常化(方案1 - 3显示为 折叠到计划 4 及其已退役的球场—— `permissions`, (中文(简体) ), `host_capabilities`,则 `ui.host_api` 方法清单——报告为 _警告_——杰森·斯克马 `ui` 静态 — 交叉文件 `tool_id` 内插( 与 Evenshtein-1 typo 检测) → 浏览器版面用法 vs `ui.browser_permissions` (警告:例如. `getUserMedia` 无 `"microphone"` 被 Dashboard 权限政策拒绝 – 论坛 # 395 → `--strict` `allowed_tools` 字数对 `ui.host_api.agent.tools`。 。 。 .

没有方法级主机 API 允许列表: 安装 App 是 用户的同意,以及 `anna.<ns>.<method>` 可供安装 App. (英语). 一个表单只宣布了三种能力 涉及第二次 校长:

| 声明 | 含义 |
| --- | --- |
| `ui.host_api.credentials: ["google"]` | app可能通过下列方式读取的第三方账户: `credentials.*` |
| `ui.host_api.agent.tools: ["fs_read_file"]` | 主机- kit 工具( e)`fs_*` 编号 : `exec_*` 编号 : `browser_*`可使用沙盒代理会话; `["*"]` = 总数 |
| `storage.scopes: {"user": "rw"}` | 跨App数据(`user` 编号 : `tool` / 另一个App's `app` 桶; App 的自带 `app` 范围不需要声明 |

### `anna-app dev [--manifest …] [--bundle …] [--port 5180] [--matrix-nexus-root <path>] [--executa <spec>…]`

搭便车:

-   喷出Python `anna-app-bridge` (生产调度器通过 `WindowStoreProtocol`) (中文(简体) ).
-   模拟仪表板 `http://localhost:<port>/`。 。 。 .
-   自动发现 `<manifest-dir>/executas/<name>/` 插件( Python /) 节点.js / go / 预建 二进制),并在程序中注册它们 `ExecutaPool`。见下文“多语言执行”.
-   热重装入磁盘更改上的捆绑( 使用) `--no-watch` 用于禁用).
-   嘲讽 **实时语音会话** (单位:千美元)`anna.audio.session`, SDK − 0.21.0) (中文(简体) ) 在仪表板页面中:通过浏览器的 ASR `SpeechRecognition` (Chrome) LLM通过当地 `agent.session`通过 `speechSynthesis` (无) `tts_audio` 帧——应用程序的玩家保持闲置. 活动/ `setContext` 编号 : `say` / 驳入/ `end()` 跟着制作 协议.
-   应用 **与生产相同的权限政策门**: 线框 `allow` 属性和捆绑 `Permissions-Policy` 信头都来自 运行时间( e)`ui.browser_permissions` 隐含 `audio: ["session"]` ⇒ `microphone` ∪ `frame-src` {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}请回放 一个没有记录的应用程序 声明 `"microphone"` 局部失败 完全像失败一样 盘子 - `validate` 告诉你原因.
-   镜像 **主机主题/ locale** (SDK = 0.24.0): iframe URL载体 `?theme=&themeMode=&lang=` 并播放标题栏 QQ/QQ和 EN/ `theme.changed` 编号 : `locale.changed` 事件,所以 `anna.onThemeChange()` 编号 : `anna.onLocaleChange()` 可以在没有生产主机的情况下行使.
-   前进 `agent.session.run` 逐字到关系账户,所以 可选每次运行 `maxTokens` (发送者为 0.30.0 / SDK 为 0.26.0) 添加剂 `run_meta.max_output_tokens` 编号 : `task_complete.{stop_reason,truncated}` 帧的表现与生产时完全相同.

#### 多语言执行器

每一子目录 `<manifest-dir>/executas/` 根据 第一个匹配的哨兵:

| {\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0} | 哨兵队 | 类型 | 默认发射 |
| --- | --- | --- | --- |
| 0 个 | `executa.json` | (任何一个) | `command` 字段,下面有其它类型的默认值 |
| 1个 | `pyproject.toml` | `python` | `uv run --project <dir> <tool_id>` |
| 2个 | `package.json` | `node` | `node <bin[tool_id] | bin | main | module>` |
| 3个 | `go.mod` (独行) | `go` | 需求 `executa.json` 声明 `type: "go"` |
| 页:1 | `bin/<dirname>` 执行 | `binary` | 直接运行可执行文件 |

`executa.json` (建议明确,GO和预建所需) 二进制工具 :

```jsonc
{
  "tool_id": "tool-yourhandle-foo-abcd1234",
  "type":    "python" | "node" | "go" | "binary",
  "command": ["…"],          // optional; full override of type defaults
  "enabled": true             // optional; default true. Set false to skip
                              // (useful when shipping multiple language
                              // flavours of the same tool_id).
}
```

这个 `--executa <spec>` 旗帜( 可换行) 登记树外 executa,或完全覆盖运行时的自动发现. 光谱语法 :

```bash
# Auto-detect from the dir (same rules as in-tree discovery):
anna-app dev --executa dir=./vendor/external-tool

# Force type when there's no executa.json:
anna-app dev --executa dir=./executas/foo,type=go

# Fully explicit:
anna-app dev --executa dir=./executas/foo,tool_id=tool-h-foo-12345678,command="node plugin.js"
```

关于全部发现/ `executa.json` 参考文献,参见 [`anna-executa-examples/docs/multi-language-anna-apps.md`](https://github.com/openclaw/anna-executa-examples/blob/main/docs/multi-language-anna-apps.md)。 。 。 .

两个运行时间模式( 自动选择) :

| 模式 | 何时 | 命令 |
| --- | --- | --- |
| `uvx` (默认) | 附近没有矩阵- nexus 检查 | `uvx --from anna-app-runtime-local@<pinned> anna-app-bridge` |
| `nexus-source` | `--matrix-nexus-root` 设定, `$ANNA_NEXUS_ROOT` 设置, 或从内侧取出 | `uv run --project <root> python -m anna_app_runtime_local.bridge` |

被绑定的轮子版本导出为 `PINNED_RUNTIME_VERSION` 从 [斜/斜/桥](https://npmcn.com/package/%40anna-ai/cli/src/harness/bridge.ts) - 撞上锁与 `packages/VERSIONS.md` 在矩阵内.

### `anna-app doctor [--matrix-nexus-root <path>]`

环境清醒度检查 : `uv` 在路径上, `uvx` 被绑定的缓存状态 运行时间,可选矩阵-nexus取出, dev 签名密钥权限. 退出 `0` 如果所有需要的检查证.

### `anna-app fixture verify <file.jsonl>`

严格合成+语义验证所记录的固定(信封) 命令 响应 请求对齐).

### `anna-app fixture summarize <file.jsonl>`

漂亮的统计数: 计数 `(ns, method)`,错误分解,事件总计.

### `anna-app fixture replay <file.jsonl> [--manifest …]`

干跑重放( MVP): 重执行记录的请求序列 新鲜的 `LocalDispatcherSession` 并显示每个响应。 现场执行 重新召集被推迟到未来的未成年人.

## 程序操纵(最优)

```ts
import { mountBundle } from "@anna-ai/cli/test";

const h = await mountBundle({
  manifest: "./examples/hello/manifest.json",
  bundle:   "./examples/hello/bundle",
});
await h.call("storage", "set", { key: "k", value: 1 });
const events = h.drainEvents();
await h.close();
```

见 [标准/测试/指数.ts](https://npmcn.com/package/%40anna-ai/cli/src/test/index.ts) 为整个地表。 电话是 与清单中的能力申报完全相同 生产量`tools.invoke` \* 已申报的执行、非自存范围 `storage.scopes`, (中文(简体) ), `credentials.*` → `ui.host_api.credentials`)没有 方法级 ACL.

## Pytest 插件 (E)`anna-executa-test`(中文(简体) )

对于执行作者。 生活在矩阵-正数 `packages/anna-executa-test/`提供 `executa_session` 编号 : `executa_invoke` 固定装置——见该包的README.

## Schema 捆绑

[`@anna-ai/app-schema`](https://www.npmjs.com/package/@anna-ai/app-schema) 是 npm 常规依赖。 设定 `ANNA_APP_SCHEMA_DIR` 指向一个 本地检出( 例如 ). `matrix-nexus/packages/anna-app-schema/`改为: 在协议上标注而不发布.

## 浏览器 SDK

终端用户应用程序捆绑装入 `AnnaAppRuntime` 从 `/static/anna-apps/_sdk/<version>/index.js`。两个矩阵-nexus 生产服务器和CLI的用具服务于来自 公共 npm 软件包 [`@anna-ai/app-runtime`](https://www.npmjs.com/package/@anna-ai/app-runtime), (中文(简体) ), 被宣布为正常依赖。 没有卖出副本, 没有同步 步骤.

## 持续储存(APS)

Anna 1.2+ 暴露了JSON-RPC在下方的每个用户存储表面 `storage/*` 名称空间。 每个安装的Executa都收到一个 `storage_token` 为其自身服务 `tool` 范围——安装是同意的,并非给予什么。 还要 触摸整个用户 `user` 范围 :

1.  在插件描述的显示中宣告它的结构 `"storage": {"scopes": {"user": "rw"}}` (或遗产) `host_capabilities: ["aps.scope.user.read", "aps.scope.user.write"]` 字符串; `aps.kv` 编号 : `aps.files` 只有自我范围.
2.  谈判 `client_capabilities.storage = {}` 期间 `initialize`。 。 。 .

`anna-app executa dev --storage real` 薄荷金币 和这些 范围(`tool` +已声明),镜像平台薄荷.

见协议和最佳做法指南 [anna-executa-examples/docs/persent-surversent-surverage.md 互联网档案馆的存檔,存档日期2013-12-02](https://github.com/openclaw/anna-executa-examples/blob/main/docs/persistent-storage.md) 用于线条格式、出错代码和工作过的OCR-cache示例。 这个 当地 `dev` lande 默认模拟 APS 所以端到端测试不 需要网络访问.

## 路线图

| 阶段 | 状态 | 范围 |
| --- | --- | --- |
| 2 - 时间: `init` + 键 `validate` | ✅ MVP | Schema/ACL检查 |
| 3 - 3 (英语) `dev` 绳子 | ✅ MVP | Stdio桥、仪表板、热重装 |
| 4 - 4 (中文(简体) ) `@anna-ai/cli/test` | ✅ MVP | 程序化 `mountBundle` |
| 5 - 5 (英语) `anna-executa-test` (pystest) (英语) | ✅ MVP | 从矩阵- nexus 运出插件 |
| 6 - 说明 `fixture {verify,summarize,replay}` | QQ MVP (干跑重放) (英语) | 直播延期 |
| 7——出版发行 | 已经完成 | uvx 默认 + 满 `anna-app-core@0.2.0a1` 取出; 最终用户不再需要矩阵- nexus 退出 |
| 8 - 国家 `manifest.dev` 块 + init 模板 + 4 文件 | 已经完成 | 见 [矩阵-nexus/docs/开发商/应用程序/](https://github.com/openclaw/matrix-nexus/tree/main/docs/developers/apps)数字 : `local-dev.md`, (中文(简体) ), `testing-bundle.md`, (中文(简体) ), `testing-plugin.md`, (中文(简体) ), `recording-replay.md` |
| 9 — 参考实例升级 | 已经完成 | [`anna-executa-examples/examples/anna-app-focus-flow`](https://github.com/openclaw/anna-executa-examples/tree/main/examples/anna-app-focus-flow) 船舶 `tests/{bundle,plugin}/`固定装置,以及 `.github/workflows/anna-app.yml` |

## 固定版本

-   `PINNED_RUNTIME_VERSION = "0.2.0a1"` (单位:千美元)[斜/斜/桥](https://npmcn.com/package/%40anna-ai/cli/src/harness/bridge.ts)(中文(简体) )
-   见 `matrix-nexus/packages/VERSIONS.md` 用于完整的工具链矩阵.

## 测试

```bash
pnpm test
```

## 常见问题

### @anna-ai/cli 是什么？

Anna App开发商CLI:脚手架,验证,取用\(第2阶段MVP:init \+验证\)\.

### 如何安装 @anna-ai/cli？

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

### @anna-ai/cli 支持 TypeScript 吗？

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

### @anna-ai/cli 支持 ESM 还是 CommonJS？

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

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

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

### @anna-ai/cli 可以商用吗？

@anna-ai/cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @anna-ai/cli 的下载量有多少？

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

### @anna-ai/cli 还在维护吗？

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