# @happyvertical/smrt-app-cli 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/smrt-app-cli/

版本：0\.62\.1
npm 元数据更新时间：2026-11-17T07:56:05.667Z
中文译文更新时间：2026-11-17T10:03:44.383Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：152 kB，44 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=26\.0\.0
- 运行依赖：3 个
- 首次发布：2026-06-23T01:18:28.621Z
- 最新版本发布：2026-11-17T07:56:05.441Z
- 近 30 天下载量：14909（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：366（近 12 个月 366 个）

## 中文简介

SMRT应用程序的可再使用的CLI工厂——品牌 `<name> <resource> <command>` CLI + 有装饰器驱动的 MCP 桥

## 安装

```sh
npm install @happyvertical/smrt-app-cli
```

也可以使用：`pnpm add @happyvertical/smrt-app-cli`、`yarn add @happyvertical/smrt-app-cli`、`bun add @happyvertical/smrt-app-cli`

## README

# @happyvertical/smrt-app-cli (英语)

可再用,应用程序品牌的CLI支持 s-m-r-t app. 结合资源 、 生成命令引用、 设备编码认证、 本地 配置,以及没有将 CLI 连接到一个应用的 MCP stdio 桥.

当部署的 s-m-r-t 应用程序显示品牌时使用此软件包 `<app> <resource> <command>` CLI(英语:CLI). 使用 [`@happyvertical/smrt-cli`](https://npmcn.com/package/%40happyvertical/cli/README.md) 框架发展, 和代码生成命令.

## 安装

```bash
pnpm add @happyvertical/smrt-app-cli
```

需要26号节点或更新.

已发布软件包还显示配置驱动 `smrt-app` 二进制. 它让政策运行者 和应用程序操作员使用 CLI 外部 消费者存放处不保留品牌包装:

```bash
SMRT_APP_NAME=work \
SMRT_APP_ENV_PREFIX=WORK \
SMRT_APP_CONFIG_DIR=happyvertical-work \
SMRT_APP_DEFAULT_SERVER_URL=https://work.example \
pnpm dlx --package @happyvertical/smrt-app-cli@X.Y.Z \
  smrt-app -- auth status
```

在自动化中将已公布的软件包的准确版本固定下来。 四份申请 需要设置且非机密; 命令参数 : `--` 为: 转发至 `createAppCli`。可以传递与 `--name`, (中文(简体) ), `--env-prefix`, (中文(简体) ), `--config-dir`,以及 `--default-server-url` 之前 断取者. 在 CLI 执行前无效或不完整的配置失败 网络或证书访问。 可执行文件还应用了 HTTPS/ roopback 从应用程序特定环境选择的有效服务器 URL或 持续配置,以及命令级服务器覆盖.

运行相同的CLI的stdio MCP桥,配置其明确的身份和 选择桥模式 :

```bash
SMRT_APP_NAME=work \
SMRT_APP_ENV_PREFIX=WORK \
SMRT_APP_CONFIG_DIR=happyvertical-work \
SMRT_APP_DEFAULT_SERVER_URL=https://work.example \
SMRT_APP_MCP_SERVER_NAME=work-mcp \
SMRT_APP_MCP_SERVER_VERSION=1.0.0 \
smrt-app --stdio-mcp
```

`SMRT_APP_*` 用于非秘密可执行配置。 运行时间 证书继续使用特定应用环境/配置分辨率 执行 `createAppCli`;从不通过无记名符号作为可执行选项.

## 快开始

```ts
#!/usr/bin/env node
import { createAppCli } from '@happyvertical/smrt-app-cli';

const cli = createAppCli({
  name: 'acme',
  defaultServerUrl: 'https://app.acme.test',
});

await cli.run(process.argv.slice(2));
```

由此产生的国家综合倡议包括:

```text
acme auth login [--server <url>] [--no-open]
acme auth status
acme auth logout
acme resources [--json] [--debug]
acme mcp
acme <resource> <command> [flags]
```

资源及其命令是从应用程序中找到的 `/_resources` 表面。 JSON Schema 成为 CLI 旗帜, 而不支持的图案形状是 而不是默默猜测.

## 发现符合规定的文物

`createResourceListHandler()` 包含 `artifact` 在兼容的旁边 `user`, (中文(简体) ), `warnings`,以及 `resources` 反应字段。 文物有个马厩 计划选择器,版本,条形命令,和 a `sha256:<hex>` 消化系统 这个 在使用其嵌入式发现有效载荷之前,CLI对其进行验证.

对于发布在下游的应用软件,安装所发布的确切信息 `@happyvertical/smrt-users` 像这样被俘的文物:

```ts
import {
  validateDiscoveryConformanceArtifact,
} from '@happyvertical/smrt-users/app-contract';

const response = await fetch('https://app.example/api/_resources');
const body = await response.json();
const artifact = validateDiscoveryConformanceArtifact(body.artifact);

console.log(artifact.schema, artifact.version, artifact.integrity.digest);
// Store all three selectors and the canonical JSON in your packaged-runtime test.
```

产品名称中包含的结果合同 `code`, (中文(简体) ), `message`, (中文(简体) ), `details`, (中文(简体) ), `retryable`, (中文(简体) ), `correlationId`, (中文(简体) ), `idempotencyKey`,以及 `expectedVersion` 元数据. `mcp tools` 财务报告和审定财务报表 `mcp call` 将此打印为 JSON 成功/错误信封。 HTTP 失败可能使用常规顶级 元对象或 `{ error: metadata }`两者都符合同样的形状. 生成动作失败使用后一种形式 `{ error: { ok: false, code, message, status, ... } }`;CLI报告: HTTP 状态与普通元数据相邻. 石桥在MCP里载着它 `_meta` 下级 `io.happyvertical/smrt`。它故意不合成 MCP `structuredContent`。 。 。 .

## 远程 MCP 客户端命令

`<app> mcp tools` 清单和清单 `<app> mcp call <tool> '<json>'` 引用工具于 a 已部署的应用程序的现代 MCP 端点( 精确的 Streamable HTTP ) `/api/mcp`,或 `mcpPath`),打印出JSON结果. 旗帜 :

-   `--url <server>` 目标为所配置服务器以外的服务器.
-   `--token-env <NAME>` 从环境变量读取无记名符号. 代币从未被打印出来,而是被从"出""出""出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 错误只命名变量 。 明确符号需要 HTTPS(或 循环) `--url`。没有它,将使用存储的登录符.
-   `--mcp-path <path>` 覆盖同一服务器 MCP 路由.
-   `--legacy-rest` 选择使用已贬值的 `<mcpPath>/tools` 财务报告和审定财务报表 `<mcpPath>/call` REST路线及其结果信封.
-   `--confirm` (单位:千美元)`mcp call` (仅)套 `confirm: true` 在呼叫参数中 外出或破坏性工具。 除非通过,否则永远不会增加 参数必须是 JSON 对象。 A 类 `"confirm": true` 已经存在 jSON没有改变.

```bash
WORK_OWNER_TOKEN=... acme mcp call send_invoice '{"id":"inv_1"}' \
  --url https://work.example.com --token-env WORK_OWNER_TOKEN --confirm
```

## 添加特定应用程序的命令

```ts
const cli = createAppCli({
  name: 'acme',
  extraCommands: [
    {
      name: 'doctor',
      description: 'Check the deployed app',
      async run(_args, context) {
        const health = await context.requestJson('/api/health');
        context.stdout.write(`${JSON.stringify(health, null, 2)}\n`);
      },
    },
  ],
});
```

App特定命令胜出内置. 避免名称可能与 发现资源流.

## MCP桥

同样的应用程序 CLI 可以向本地曝光应用程序的 MCP 表面 stdio 客户端 :

```ts
await cli.startMcpBridge({ name: 'acme-mcp', version: '1.0.0' });
```

大桥往前走 `/api/mcp` 默认。 当应用程序挂载其 MCP 设置 `mcpPath` 打开 `createAppCli()` 或通过它每个呼叫 (单位:千美元)`startMcpBridge({ mcpPath: '/mcp' })`) (中文(简体) ). 二进制 `--mcp-path=/mcp` (单位:千美元)`smrt-mcp-bridge`,或 `SMRT_MCP_PATH`和 `--mcp-path` 编号 : `SMRT_APP_MCP_PATH` (单位:千美元)`smrt-app`) (中文(简体) ). 路径必须是相同的服务器和绝对的.

对本地的S-m-r-t应用,薄荷 证书与 `smrt app token --scopes <scope>` 在应用程序检查。 记号印出 一次 一次吗 然后把回回回回回的服务器和信使通过 app的环境前缀. 这个 Claude 桌面条目是一个实例 :

```json
{
  "mcpServers": {
    "notes": {
      "command": "npx",
      "args": ["smrt-mcp-bridge", "--env-prefix=NOTES", "--mcp-path=/mcp"],
      "env": {
        "NOTES_SERVER_URL": "http://127.0.0.1:5173",
        "NOTES_TOKEN": "smrt_mcp_…"
      }
    }
  }
}
```

只有在 `<PREFIX>_SERVER_URL` 匹配目标服务器. 用 `smrt app token revoke <id>`。 。 。 .

包裹还装了通用的 `smrt-mcp-bridge` 二进制. 远程应用程序 表面一般被挂载 [`@happyvertical/smrt-app-mcp`](https://npmcn.com/package/%40happyvertical/smrt-app-mcp/README.md)。 。 。 . 二进制在解析或解析前拒绝非回放平方文本 HTTP 源头 发送已存储的证书; 远程应用服务器使用 HTTPS .

默认本地 MCP 桥保存上游工具目录顺序并转发 `tools/list`, (中文(简体) ), `tools/call`, (中文(简体) ), `resources/list`,以及 `resources/read` 通过 SDK v2. 工具目录和资源响应使用零 TTL 与 `private` 缓存范围 因此,随后的请求重新检查上游授权。 该桥使用 配置本地应用程序证书, 并且从不选择共享缓存 .

只有明确的 `transport: 'legacy-rest'` 兼容模式排序其 `tools/list` 按工具名称分类并发布一天 `private` 缓存寿命 . 该模式使用REST形状的工具端点,不转发资源.

## 配置和认证

-   `name` 提供显示名称和默认环境可变前缀.
-   `envPrefix` 覆盖前缀; `configDir` 覆盖本地配置 名称空间.
-   `defaultServerUrl` 仅在环境或存储配置中使用 提供服务器.
-   设备编码登录在等待批准、到期、瞬态网络区分 失败 和强烈的拒绝.
-   Tokens和服务器配置保留在应用程序特定的本地配置路径中.
-   设备流程响应可以识别其发行者. 托肯斯是按键 准确 发行器,在配置的服务器更改时不重复使用.

基于标准的远程 MCP OAuth 注册,使用 `registerMcpClient()` (计算机ID元数据文档,可执行 RFC 7591) DCR 倒计时 `application_type`并遵循 [远程 MCP 授权指南](https://npmcn.com/package/docs/content/architecture/remote-mcp-authorization.md)。 。 。 .

## 公共 API

| 导出 | 目的 |
| --- | --- |
| `createAppCli()` | 建造有品牌的CLI和MCP桥 |
| `createMcpStdioBridge()` 编号 : `runMcpStdioBridge()` | 低级桥梁控制 |
| `fetchResourceList()` | 获取已部署的资源目录 |
| `invokeCommand()` | 启动一个生成的资源命令 |
| `buildFlagParser()` | 将支持的 JSON Schema 转换为旗帜 |
| `loadCliConfig()` 编号 : `saveCliConfig()` | 读取并写入命名空间 CLI 配置 |
| `resolveMcpClientRegistration()` | 检查选中的客户端 ID 元数据或 DCR 路径 |
| `registerMcpClient()` | 使用客户端ID元数据或执行 DCR 倒置 |

## 发展

```bash
pnpm --filter @happyvertical/smrt-app-cli test
pnpm --filter @happyvertical/smrt-app-cli typecheck
pnpm --filter @happyvertical/smrt-app-cli build
```

维护者模式和认证变量记录在 [`AGENTS.md`](https://npmcn.com/package/%40happyvertical/smrt-app-cli/AGENTS.md)。 。 。 .

用于安装已知 OAuth 发行器的远程部署 `CliConfigContext.expectedCredentialIssuer` 以精确的标识。 存储 证书必须匹配服务器和签发者;环境证书也必须匹配 需求 `${PREFIX}_TOKEN_ISSUER`。这不会取代终端设备 与浏览器 OAuth 相通。 见 [远程授权合同](https://npmcn.com/package/docs/content/architecture/remote-mcp-authorization.md)。 。 。 .

### 生成本地桌面插件元数据

使用 `generateDesktopPluginArtifacts` 在产品的包装步骤。 过 便携式插件列表中的公共产品元数据,例如 [厨房清单](https://npmcn.com/package/plugins/smrt-kitchen/plugin.json)编辑 需要的字段为 `name` (小写字母、数字和单连字符), `version` (SemVer), (英语), `description`,以及 `author.name`选项 `extensions["com.openai"].interface.displayName` 默认为 `name`。 。 。 .

```ts
import { generateDesktopPluginArtifacts } from '@happyvertical/smrt-app-cli';

const files = generateDesktopPluginArtifacts(productManifest, {
  platform: 'darwin',
  executable: 'server/smrt-mcp-launcher',
});
```

结果绘制出分布-根基-相对路径来决定UTF-8 JSON. 将文件在新的中转目录中实现物质化 。 将可执行文件放入 同样的 `server/` 每个插件目录中的路径。 运行生成器 目标平台(`darwin`, (中文(简体) ), `win32`,或 `linux`),使用一个 `.exe` 发射器 windows 的文件名 。 发射装置 必须解决已安装的应用程序捆绑的运行时间并获得本地授权 在发射时。 生成器只读取公共元数据,没有环境, MCP参数,端点,或认证配置.

-   `claude-desktop/<name>/manifest.json` 二进制扩展显示于 运行目录 `mcpb pack`。在包装时包含可执行文件. 明细表宣布目标平台 并解决发射装置 已安装扩展目录. [Claude 桌面扩展](https://www.anthropic.com/research/desktop-extensions) • 妇女 [MCPB 显示格式](https://github.com/modelcontextprotocol/mcpb/blob/main/MANIFEST.md)
-   `plugins/<name>/plugin.json` 财务报告和审定财务报表 `mcp.json` 是可移动的 ChatGPT 桌面插件, 列出于 `.agents/plugins/marketplace.json`。 。 。 . [OpenAI 插件包装](https://developers.openai.com/plugins/build/plugins) • 妇女 [只用于桌面的插件](https://developers.openai.com/plugins/deploy/desktop-only) • 妇女 [代理插件 stdio 路径规则](https://agent-plugins.org/plugin-authors/mcp-servers#stdio-commands-and-paths)
-   `plugins/<name>/.claude-plugin/plugin.json` 财务报告和审定财务报表 `.claude-plugin/marketplace.json` 提供 Claude 代码市场 兼容性。 Claude 桌面从分离处安装 MCPB 扩展 运行目录 . [克劳德代码市场](https://code.claude.com/docs/en/plugin-marketplaces)

每个生成的目录包含一个条目. 对于共享目录,合并 输入由包装器维护的目录。 现场安装和 在 Claude 桌面和 ChatGPT 桌面中执行需要制作 发射器和单独的主机验证.

### 生成本地客户端设置

`generateLocalMcpSetup({name,command,args})` 让克洛德代码的贝壳引用 `claude mcp add`, 克劳德桌面/`.mcp.json` 用于已有的 JSON 和 Codex TOML 拥有者授权的Stdio发射器。 只通过公共可执行文件/ 发射器路径, 从来没有一个携带者. `CliConfigContext.configPath` 让应用程序私自写作 直接通过 `saveCliConfig` 不改变进程环境. 现代桥梁广告 `tools.listChanged` 并调查上游无国籍者 每两秒编目(包括页). 更改的描述、撤销和 恢复无效发现; 关闭清除计时器。 没有共享目录缓存 .

## 常见问题

### @happyvertical/smrt-app-cli 是什么？

SMRT应用程序的可再使用的CLI工厂——品牌 \<name\> \<resource\> \<command\> CLI \+ 有装饰器驱动的 MCP 桥

### 如何安装 @happyvertical/smrt-app-cli？

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

### @happyvertical/smrt-app-cli 支持 TypeScript 吗？

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

### @happyvertical/smrt-app-cli 支持 ESM 还是 CommonJS？

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

### @happyvertical/smrt-app-cli 需要什么版本的 Node\.js？

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

### @happyvertical/smrt-app-cli 可以商用吗？

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

### @happyvertical/smrt-app-cli 的下载量有多少？

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

### @happyvertical/smrt-app-cli 还在维护吗？

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

