# @vention/vention-cli 中文文档

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

版本：0\.38\.21
npm 元数据更新时间：2026-11-02T19:43:30.124Z
中文译文更新时间：2026-11-02T20:19:26.547Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40vention/vention-cli
原文对照：https://npmcn.com/package/%40vention/vention-cli/?lang=original
源码仓库：https://github.com/VentionCo/machine-cloud

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

- 包体积（解压后）：495 kB，42 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：4 个
- 首次发布：2025-06-11T14:31:29.700Z
- 最新版本发布：2026-11-02T19:43:29.932Z
- 已发布版本数：220（近 12 个月 202 个）

## 中文简介

用于Vention应用程序的CLI工具

## 安装

```sh
npm install @vention/vention-cli
```

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

## README

# Vention CLI

> **⚠️需要升级。** Vention CLI 0.37.0或更高版本需要为您的MachineLogic Python应用程序拉，推和读取日志。旧版本报告您的设计未打开。运行 `npm install -g @vention/vention-cli@latest`,然后 `vention login`． 看到 [升级](https://npmcn.com/package/%40vention/vention-cli/#readme-upgrade).

> 一个命令行工具，可以在本地开发MachineLogic Python应用程序，并在IDE和MachineBuilder之间进行双向同步。

* * *

## 目录表

-   [✨特性](https://npmcn.com/package/%40vention/vention-cli/#readme--features)
-   [🧠概念与概述](https://npmcn.com/package/%40vention/vention-cli/#readme--concepts--overview)
-   [⚙️安装与设置](https://npmcn.com/package/%40vention/vention-cli/#readme--installation--setup)
    -   [升级](https://npmcn.com/package/%40vention/vention-cli/#readme-upgrade)
-   [🚀快速入门教程](https://npmcn.com/package/%40vention/vention-cli/#readme--quickstart-tutorial)
-   [推荐操作指南](https://npmcn.com/package/%40vention/vention-cli/#readme--how-to-guides)
-   [📖API参考](https://npmcn.com/package/%40vention/vention-cli/#readme--api-reference)
-   [🔍故障处理与FAQ](https://npmcn.com/package/%40vention/vention-cli/#readme--troubleshooting--faq)

## ✨特性

-   **本地IDE开发**：在您首选的IDE中编辑MachineLogic Python应用程序，并提供完整的工具支持
-   **双向同步**：从MachineBuilder中拉应用程序并无缝地将更改推回来
-   **主动设计检测**：自动找到并连接到设计与MachineLogic选项卡打开
-   **应用程序日志**：在不离开终端的情况下从数字孪生中获取应用程序的日志
-   **智能文件处理**：自动忽略构建工件、虚拟环境和公共开发文件
-   **会话管理**：使用安全令牌存储的持久身份验证
-   **多应用支持**：在同一设计中链接和切换不同的应用程序

* * *

## 🧠概念与概述

### 活动设计

ventioncli连接到 **活动设计** -在MachineBuilder中打开MachineLogic选项卡的设计。此活动会话使CLI能够发现用于同步操作的可用设计和应用程序。

### 链接状态

当您拉取或链接一个应用程序时，CLI会创建一个 `.machine-code-app-directory-info.json` 文件在您的项目根目录。该文件维护本地目录和特定设计/应用组合之间的连接，实现无缝的推/拉操作，无需重新选择。

### 文件同步

-   **拉**：从MachineBuilder下载应用程序的源文件，并将它们写入本地目录
-   **推**：序列化本地文件并将其上传到MachineBuilder中的活动设计
-   **忽略模式**： `venv`， `.venv`， `node_modules`， `dist`， `build`， `__pycache__`， `.claude`， `.agents`， `.git`， `*.egg-info`， `.machine-code-app-directory-info.json`， `.vention-design-scene-assets.json`， `.vention-design-configuration.json`

### 只读配置和场景资产

每一个 `vention pull` 还写入两个只读的引用文件到app目录，从active设计中获取：

-   `.vention-design-configuration.json`：设计的MachineMotion配置
-   `.vention-design-scene-assets.json`：设计的库资产，如果设计有库（否则省略）

两个文件都被chmodded为只读(`0o444`)，并被排除在外 `push` 通过上面忽略的模式—它们是仅供参考的本地快照，而不是CLI同步回MachineBuilder的东西。

### 身份验证流

基于oauth的身份验证打开一个浏览器窗口，用于安全登录。会话令牌存储在 `~/.vention-cli-config.json` 用于后续的CLI操作。

* * *

## ⚙️安装与设置

**要求:**

-   Node.js 18或更高版本
-   NPM或纱线
-   活动的MachineBuilder会话与MachineLogic选项卡打开
-   ventioncli 0.37.0或更高版本为您的MachineLogic Python应用程序拉，推送和读取日志(参见 [升级](https://npmcn.com/package/%40vention/vention-cli/#readme-upgrade)）

**通过npm全局安装：**

命令行在npm上发布为 [`@vention/vention-cli`](https://www.npmjs.com/package/@vention/vention-cli).

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

**验证安装:**

```bash
vention --version
```

在Windows上，如果 `vention` 如果安装后没有找到npm全局文件夹，则说明PATH中缺少npm全局文件夹。添加文件夹 `npm prefix -g` 打印到您的PATH并打开一个新终端。在那之前, `npx -y @vention/vention-cli <command>` 运行相同的命令。

**命令别名:** 使用 `vention` 或者 `vn` 作为命令前缀。

**了解更多有关MachineLogic Python应用程序结构的信息：** [https://docs.vention.com/docs/machinelogic-python-programming-guide](https://docs.vention.com/docs/machinelogic-python-programming-guide)

### 升级

安装最新版本，检查后再登录：

```bash
npm install -g @vention/vention-cli@latest
vention --version
vention login
```

`npm update -g` 可能会让你使用旧版本，因为NPM将全局安装的包固定到一个插入符范围。总是使用上面的命令。

* * *

## 🚀快速入门教程

本教程展示了从身份验证到同步第一个应用程序的完整工作流程。

**步骤1：打开你的设计** 在MachineBuilder中打开您的设计，然后选择 **MachineLogic选项卡**。这激活了CLI访问的设计。

**步骤2：验证**

```bash
vention login
```

这将打开一个浏览器窗口，用于安全OAuth登录。

**步骤3：将应用放到本地**

```bash
vention pull
```

命令行将：

-   展示可用的主动设计
-   让你选择一个设计
-   在该设计中显示MachineLogic Python应用程序
-   让你选择一个应用程序拉
-   创建一个以应用程序命名的文件夹，其中包含所有源文件（名称中的特殊字符将被下划线替换）

**步骤4：本地编辑** 在IDE中打开创建的文件夹并编辑如下文件 `main.py` 或者 `project.json`.

**第五步：把改变推回去**

```bash
vention push
```

您的更改现在上传到MachineBuilder。

**第六步：在MachineBuilder中运行** 使用MachineBuilder中的MachineLogic面板来运行和测试更新后的应用程序。

* * *

## 推荐操作指南

### 链接一个现有目录而不拉取文件

如果你在本地已经有了应用程序文件，只是想建立链接：

```bash
cd my-existing-app
vention link
```

这写 `.machine-code-app-directory-info.json` 不覆盖您的文件。

### 更新一个已经链接的应用

如果你的目录已经被链接了，只需再次运行pull命令来更新文件：

```bash
vention pull
```

CLI检测现有链接并更新项目，而无需创建新文件夹。

### 在不同的应用程序之间切换

将当前目录链接到另一个应用程序：

1.  删除 `.machine-code-app-directory-info.json` 文件
2.  运行 `vention link` 或者 `vention pull` 然后选择新的应用程序

### 查看应用程序的日志

如果你的目录被链接并且设计在MachineBuilder中是活动的：

```bash
vention logs
```

这将从数字孪生中获取应用程序的日志并将其打印到您的终端。

### 查看任何命令的帮助

```bash
vention --help
vention pull --help
vention push --help
```

### 在多种环境下工作

CLI存储环境(`local`， `demo`，或者 `prod`)在链接元数据文件中。环境是在登录时设置的，默认为 `prod`.

* * *

## 📖API参考

### 全局选项

```bash
vention --help          # Display help information
vention --version       # Display CLI version
vention --verbose       # Enable verbose output for debugging (use with any command)
```

### `vention login`

**描述:** 使用OAuth对您的Vention帐户进行身份验证。

**用法:**

```bash
vention login
```

**行为:**

-   打开浏览器窗口进行安全OAuth身份验证
-   将会话令牌存储在 `~/.vention-cli-config.json`
-   令牌在终端会话中持续存在，并自动刷新

**退出代码:**

-   `0`：认证成功
-   `1`：认证失败或取消

* * *

### `vention pull`

**描述:** 从你的活动设计中获取一个MachineLogic Python应用到当前目录中。

**用法:**

```bash
vention pull
```

**行为:**

-   如果目录没有链接：提示设计和应用程序选择，创建一个新文件夹
-   如果目录已经被链接：使用存储的链接元数据更新文件
-   下载所有源文件，除了被忽略的模式
-   写只读 `.vention-design-configuration.json` 和 `.vention-design-scene-assets.json` 参考文件（后者仅当设计有场景资产时）
-   写/更新 `.machine-code-app-directory-info.json`
-   更新 `lastPulledAt` 时间戳

**先决条件:**

-   用户必须登录(`vention login`）
-   目标设计必须在MachineBuilder中打开MachineLogic选项卡
-   目标应用必须是一个MachineLogic Python应用（不支持无代码应用）

**退出代码:**

-   `0`：拉成功
-   `1`：未登录，未找到活动设计，或拉出失败

* * *

### `vention push`

**描述:** 将本地更改从链接的目录上载到活动设计。

**用法:**

```bash
vention push
```

**行为:**

-   如果目录没有链接：则提供将其链接到应用程序并继续推送
-   读取 `.machine-code-app-directory-info.json` 识别目标设计/应用
-   序列化所有本地文件，除了被忽略的模式
-   上传到machinbuilder
-   更新 `lastPushedAt` 时间戳

**先决条件:**

-   用户必须登录
-   相同的设计必须在MachineBuilder中激活（MachineLogic选项卡打开）

**退出代码:**

-   `0`：推送成功，或链接提示取消推送
-   `1`：未登录、设计未激活或推送失败

* * *

### `vention link`

**描述:** 将当前目录链接到design +应用程序，而不需要拉出文件。

**用法:**

```bash
vention link
```

**行为:**

-   提示设计和应用程序选择
-   写 `.machine-code-app-directory-info.json` 使用链接元数据
-   不下载或修改现有文件

**用例:** 当你已经有了应用程序文件，只想建立推送操作的连接时非常有用。

**退出代码:**

-   `0`：链接成功
-   `1`：未登录、未找到活动设计或链接失败

* * *

### `vention logs`

**描述:** 从链接的数字孪生中获取应用程序日志。

**用法:**

```bash
vention logs
```

**行为:**

-   读取 `.machine-code-app-directory-info.json` 识别目标设计/应用
-   从数字孪生中获取应用程序的日志
-   将日志打印到终端

**先决条件:**

-   目录必须被链接(包含 `.machine-code-app-directory-info.json`）
-   用户必须登录
-   相同的设计必须在MachineBuilder中激活（MachineLogic选项卡打开）

**退出代码:**

-   `0`：日志已成功获取
-   `1`：未链接、未登录、设计未激活或获取失败

* * *

### `vention skills`

**描述:** 为您的编码代理安装Vention技能，使其保持最新，并列出已安装的技能。

**用法:**

```bash
vention skills install [--agent <claude-code|codex|cursor|copilot>] [--scope <user|project>]
vention skills update
vention skills status
```

**行为:**

-   `install` 询问您使用哪个代理，除非 `--agent` 给出。克劳德代码和法典安装 `vention` 插件通过自己的插件管理器从 `vention-skills` 目录在 `https://assets.vention.com/vention-skills/marketplace.json`； 光标和副驾驶从 `@vention/vention-skills` NPM package into `.agents/skills`
-   `--scope` 默认为 `user`； Codex总是为您的用户帐户安装
-   `update` 找到所有拥有该技能的代理，并将其更新到npm上的最新版本： `claude plugin update` 对于Claude Code，重新运行Codex的安装，并在光标和副驾驶的安装范围内重新解包。它打印每个代理的新旧版本。手工复制成的技能 `.claude/skills` 都是孤独的
-   `status` 列出磁盘上的每个Vention技能及其版本和位置，紧挨着npm上的最新版本。如果无法联系到npm，它仍然会列出它们，并说无法检查最新版本

**先决条件:**

-   Node.js和npm，加上代理自己的CLI用于Claude Code（2.1.277或更高版本）或Codex

* * *

### 链路元数据文件

**地点:** `.machine-code-app-directory-info.json` (项目根目录)

**模式:**

```json
{
  "appName": "My App",
  "designId": 12345,
  "applicationId": "abcdef",
  "uuid": "optional-app-uuid",
  "environment": "prod",
  "lastPulledAt": "2025-01-01T12:34:56.789Z",
  "lastPushedAt": "2025-01-02T09:10:11.123Z"
}
```

**字段:**

-   `appName` （string）：人类可读的应用程序名称
-   `designId` （数字）：唯一的设计标识符
-   `applicationId` （string）：唯一的应用程序标识符
-   `uuid` （string，可选）：应用UUID（如果可用）
-   `environment` （string）：目标环境（其中之一） `local`， `demo`， `prod`）
-   `lastPulledAt` （ISO 8601时间戳）：最后一次成功拉取时间（也在目录第一次链接时设置）
-   `lastPushedAt` （ISO 8601时间戳）：最后一次成功推送的时间

* * *

## 🔍故障处理与FAQ

### 常见的错误

**“没有登录。请先运行“登录”。**

-   **原因:** 未找到身份验证令牌或已过期
-   **解决方案:** 运行 `vention login` 来认证

**“没有找到活动分配…”或“对不起，您似乎没有打开该设计…”**

-   **原因:** 没有设计在MachineBuilder中打开MachineLogic选项卡
-   **解决方案:** 在MachineBuilder中打开目标设计，然后单击MachineLogic选项卡来激活它

**相同的两条消息，尽管设计是用MachineLogic选项卡打开的**

-   **原因:** CLI版本大于0.37.0。旧版本不能再访问您的MachineLogic Python应用程序，因此它们报告设计未打开。
-   **解决方案:** 运行 `vention --version`。低于0.37.0，继续 [升级](https://npmcn.com/package/%40vention/vention-cli/#readme-upgrade) 并重试。在0.37.0或更高版本，请联系Vention技术支持，并提供运行失败命令的输出 `vention --verbose`.

**“这个目录没有链接…”**

-   **原因:** 目录没有 `.machine-code-app-directory-info.json`
-   **解决方案:** 运行 `vention link` 或者 `vention pull` 建立链接。在 `push`，命令行将提供链接目录并自动继续。

**推送失败，身份验证错误**

-   **原因:** 会话令牌过期
-   **解决方案:** 运行 `vention login` 刷新身份验证

**“目录已经存在”（在拉取过程中）**

-   **原因:** 带有应用名称的文件夹已经存在
-   **解决方案:** :
    -   `cd` 到现有目录中并运行 `vention pull` （更新到位）
    -   重命名或删除冲突的文件夹
    -   运行 `vention link` 而不创建新文件夹进行链接

### 常见问题解答

**问：我可以在无代码的MachineLogic程序中使用这个功能吗？**  
答：不，只支持MachineLogic Python应用程序。

**问：在本地编辑时，我需要保持MachineBuilder打开吗？**  
答：不，你只需要在运行时打开MachineBuilder（与MachineLogic标签激活） `pull`， `push`，或者 `logs` 命令。

**问：我的身份验证令牌存储在哪里？**  
答:在 `~/.vention-cli-config.json` 在您的主目录中。

**问：如何查看CLI版本和升级？**  
答: `vention --version` 打印它。看到 [升级](https://npmcn.com/package/%40vention/vention-cli/#readme-upgrade) 用于单行升级命令。

**问：我可以同时使用多个应用程序吗？**  
答：是的，每个应用文件夹都有自己的链接元数据。您可以有多个链接目录。

**Q：哪些文件在推送过程中会被忽略？**  
答: `venv`， `.venv`， `node_modules`， `dist`， `build`， `__pycache__`， `*.egg-info`， `.machine-code-app-directory-info.json`， `.vention-design-scene-assets.json`, `.vention-design-configuration.json`.

**问：我可以添加自定义忽略模式吗？**  
答：目前没有。忽略列表内置于CLI中。

**问：如果我在MachineBuilder和本地编辑同一个应用程序会发生什么？**  
A：最后一个推/拉赢。没有冲突解决或合并。我们建议对本地副本使用版本控制（Git）。

**问：这是否适用于MachineMotion应用？**  
答：CLI专门针对MachineLogic Python应用程序。关于MachineMotion的开发，请参阅MachineMotion SDK文档。

## 常见问题

### @vention/vention-cli 是什么？

用于Vention应用程序的CLI工具

### 如何安装 @vention/vention-cli？

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

### @vention/vention-cli 支持 TypeScript 吗？

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

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

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

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

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

### @vention/vention-cli 可以商用吗？

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

### @vention/vention-cli 还在维护吗？

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