让开源，少一点语言距离。
npm包中文文档

@vention/vention-cli

中文文档
0.38.21发布于 2026/11/03MITTypeScriptES Module

用于Vention应用程序的CLI工具

中文使用文档
中文原文
文档目录30 节
  1. 目录表
  2. ✨特性
  3. 🧠概念与概述
  4. 活动设计
  5. 链接状态
  6. 文件同步
  7. 只读配置和场景资产
  8. 身份验证流
  9. ⚙️安装与设置
  10. 升级
  11. 🚀快速入门教程
  12. 推荐操作指南
  13. 链接一个现有目录而不拉取文件
  14. 更新一个已经链接的应用
  15. 在不同的应用程序之间切换
  16. 查看应用程序的日志
  17. 查看任何命令的帮助
  18. 在多种环境下工作
  19. 📖API参考
  20. 全局选项
  21. vention login
  22. vention pull
  23. vention push
  24. vention link
  25. vention logs
  26. vention skills
  27. 链路元数据文件
  28. 🔍故障处理与FAQ
  29. 常见的错误
  30. 常见问题解答

Vention CLI

⚠️需要升级。 Vention CLI 0.37.0或更高版本需要为您的MachineLogic Python应用程序拉，推和读取日志。旧版本报告您的设计未打开。运行 npm install -g @vention/vention-cli@latest,然后 vention login． 看到 升级.

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

目录表

✨特性

  • 本地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应用程序拉，推送和读取日志(参见 升级）

通过npm全局安装：

命令行在npm上发布为 @vention/vention-cli.

npm install -g @vention/vention-cli

验证安装:

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

升级

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

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

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

🚀快速入门教程

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

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

步骤2：验证

vention login

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

步骤3：将应用放到本地

vention pull

命令行将：

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

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

第五步：把改变推回去

vention push

您的更改现在上传到MachineBuilder。

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

推荐操作指南

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

cd my-existing-app
vention link

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

更新一个已经链接的应用

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

vention pull

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

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

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

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

查看应用程序的日志

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

vention logs

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

查看任何命令的帮助

vention --help
vention pull --help
vention push --help

在多种环境下工作

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

📖API参考

全局选项

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帐户进行身份验证。

用法:

vention login

行为:

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

退出代码:

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

vention pull

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

用法:

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

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

用法:

vention push

行为:

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

先决条件:

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

退出代码:

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

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

用法:

vention link

行为:

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

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

退出代码:

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

vention logs

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

用法:

vention logs

行为:

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

先决条件:

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

退出代码:

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

vention skills

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

用法:

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 (项目根目录)

模式:

{
  "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，继续 升级 并重试。在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 打印它。看到 升级 用于单行升级命令。

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

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 共发布 220 个版本，首次发布于 2025/06/11；过去 12 个月发布了 202 个版本。

版本发布日期距今
0.38.21latest2026/11/03今天
0.38.202026/10/313 天前
0.38.192026/10/304 天前
0.38.182026/10/295 天前
0.38.172026/10/295 天前
0.38.162026/10/295 天前

关于 @vention/vention-cli 的常见问题

@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 和提交记录判断。