MCLI 本地命令行使用指南

在终端中使用与右侧 AI Copilot 相同的受控工具、工作区权限和确认流程。

名称说明：帮助中心使用“MCLI”作为创业OS本地命令行入口的检索名称；实际安装包是 @xaiverdeng/upos，执行命令统一为 upos，不存在第二个名为 mcli 的二进制程序。

什么时候使用 MCLI

场景建议入口
在当前业务页面旁查询库存、读写 Excel右侧 AI Copilot
在终端执行可复现的上传、查询或批处理MCLI（upos）
让 Codex、Claude Code、Cursor 等 Agent 自动发现工具MCP 接入

安装与登录

需要 Node.js 20.19 或更高版本。CLI 仅通过浏览器 OAuth 2.0 + PKCE 登录，不接受密码、API Key 或手工粘贴的访问令牌。

  1. 安装公开 CLI：
    npm install -g @xaiverdeng/upos@latest
  2. 启动登录并在浏览器选择工作区：
    upos login
  3. 查看当前版本支持的入口：
    upos --help

只有明确需要重新选择工作区或更新授权时才使用 upos login --force。请求权限不会提升你在工作区中的角色权限。

发现并执行本地命令

签名 Desktop 运行时提供受控本地命令目录。先列出当前可用命令，再按返回的结构化参数调用；没有 Desktop bridge 或目录授权时会直接拒绝，不会降级为任意 Shell。

upos local tools
upos local <command_id> --cwd <approved-directory> --input '<json>'

云端业务命令同样来自服务端工具清单，通用格式为：

upos <command> --input '<json>'

上传业务资料

需要让 AI 读取真实 Excel、合同或附件时，可先上传文件，再把返回的文件标识交给当前工作区中的工具。上传不会自动记账、修改原件或提交外部系统。

upos upload ./库存台账.xlsx
upos upload ./业务资料 --recursive

确认写操作

读取类工具可以直接执行；修改 Excel、创建凭证等写操作会先生成 Action Plan。核对工具名称、工作区、文件版本、变更范围和幂等键后，再确认或取消：

upos action-plan confirm <plan-id>
upos action-plan cancel <plan-id>

Excel 修改会生成不可变的新版本，不覆盖原文件。发现文件 SHA、版本号或目标单元格与预期不一致时，应取消方案并重新读取。

一条命令接入 Agent

如果还需要把同一套工具接入本机 Agent，可在目标项目目录执行：

upos setup --auto

该命令会配置 MCP bridge 并安装统一 Skill；具体写入位置、支持客户端和排障方式见MCP 接入指南。

常见问题

现象处理
终端提示找不到 upos重新打开终端，并确认 npm 全局 bin 目录在 PATH 中；也可使用 npx -y @xaiverdeng/upos@latest --help 临时运行。
没有目标工作区或工具确认账号已加入工作区并具有对应权限；重新执行 upos login 仅会更新授权，不会扩大角色权限。
本地命令被拒绝确认签名 Desktop 正在运行、目录已获批准、命令 ID 来自 upos local tools。
写操作没有立即生效检查输出中的 Action Plan，并由有权限的用户明确确认。

相关页面