vertu-cli

安装 · AI Agent Skills · 认证 · 快捷命令 · 进阶 · 常见问题

Vertu 业务数据本地 CLI，并把随 npm 包分发的 Agent Skills 安装到 Cursor / Claude Code / Trae / OpenClaw / Hermes 等用户目录（设计对齐 larksuite/cli）。Skill 为静态文件，安装 skill 无需登录；业务取数需登录 Vertu 账号。

• npm：vertu-cli
• 全局命令：vertu-cli

为什么选 vertu-cli？

• 为 Agent 设计 — 域级 SKILL.md + vertu-cli <域> +… 快捷命令，参数与契约面向 AI 调用优化
• 安装简单 — npx vertu-cli@latest install 装 CLI，并自动铺设到本机已检测到的 Agent 目录
• 覆盖面广 — 销售、人资、产品供应链/价格、审批、任务/OKR、日报、IM/站内信/会议等
• 三层粒度 — 域快捷命令（+）→ 内置固定命令树 → Vertu 业务服务能力（无需远端拉 manifest）
• 凭据可控 — 系统钥匙串或 ~/.vertu/config.json；CI 可用 VERTU_BOT_INBOUND_KEY / App Key

功能

| 类别 | 能力 | |------|------| | 平台 | CLI 安装升级、skill 子命令、登录会话与 OSS 公共工具（vertu-cli / vertu-onboard / vps-tools） | | 身份 | 当前用户、部门、上级与组织上下文（vps-current-user-identity） | | 销售与经营 | 公司总销日报、部门下钻、目标达成、OKR 达成、销售人效与 PK（sale-performance-query 等） | | 人力资源 | 组织架构、人员档案、上下级、岗位、工龄、合同、工资条（vps-hr） | | 产品与供应链 | 库存、商品价格、发货、齐套物料、机头库存（vps-product） | | 内容创作 | AI 生图、生视频、文字转语音与音乐生成，返回可下载附件链接（vps-creative） | | 研发与 OKR | 任务中心任务/待办、部门与个人 OKR（vps-task-management-assistant、vps-okr） | | 日报 | 打卡未交比对、统一日报查询、提交与助手同步（vps-daily-report-assistant） | | 审批 | 待办队列与处理指引（vps-approval） | | 协作 | 日程与日历、IM 消息及会话附件下载、站内信、会议录音与纪要（vps-calendar / vps-im / vps-mail / vps-meeting） | | Agent 弹窗 | 向当前绑定用户的 VPS 手机端投递可配置的一次性弹窗 | | V盘文件 | 与桌面端、手机端一致的账号级 OSS V盘（vps-v-drive） |

完整 skill 列表：vertu-cli skill list 或仓库 skills/ 目录。

安装与快速开始

环境要求

• Node.js 20+（node -v）
• npm / npx

快速开始（人类用户）

给 AI 助手： 若你正在帮用户安装，请直接执行 快速开始（AI Agent） 中的步骤。

安装

任选其一：

npx vertu-cli@latest install

npm install -g vertu-cli@latest
vertu-cli skill install --all --agent all   # 全局安装时如需补铺 skill

install 会在装包后自动把公开 skill 写入本机已存在的 Agent 目录；不需要时可加 --no-skills。

配置与使用

以下账号密码登录仅供人工用户在交互终端执行。Agent / Bot / Hermes 应使用宿主注入的 app_key，不得执行登录命令或接触用户密码；Hermes 固定使用 app_id=vertu-hermes-agent。

vertu-cli auth login
vertu-cli auth status
vertu-cli sales +headline-kpi
vertu-cli --help

默认连接 Vertu 正式环境；如需本地或测试环境，可用 vertu-cli auth login --service-url / --base-url 覆盖。更多示例见 USAGE.md、examples/README.md。

从旧包迁移： 若曾安装旧版包或全局命令 vertu，先卸载旧包，再安装 vertu-cli（全局命令名为 vertu-cli）。

快速开始（AI Agent）

以下步骤面向 AI Agent。Agent 不得执行账号密码登录或要求用户提供密码；宿主应在启动前完成 app_key 注入。

第 1 步 — 安装 CLI

npx vertu-cli@latest install

第 2 步 — 同步 Skills（若未自动铺设）

vertu-cli skill list
vertu-cli skill install --all --agent all

第 3 步 — 验证宿主凭证

vertu-cli auth status

第 4 步 — 验证

vertu-cli auth status
vertu-cli --version
vertu-cli sales +headline-kpi --validate-only
vertu-cli hr +headcount --dry-run

升级 CLI 后覆盖同步 skill：vertu-cli skill update。

可选：先落盘 vertu-onboard 再让 Agent 自举

将 onboard skill 写到本机 Agent 目录（与装包无关，适合「只说一句话让 Agent 装好」）：

macOS / Linux：

curl -fsSL https://unpkg.com/vertu-cli@latest/scripts/install-onboard-skill.sh | bash

Windows PowerShell：

irm https://unpkg.com/vertu-cli@latest/scripts/install-onboard-skill.ps1 | iex

自定义 skill 源地址可设 VERTU_ONBOARD_RAW（默认从当前 npm 包版本拉取 skills/vertu-onboard/SKILL.md）。然后对 Agent 说：用 vertu-onboard 把 vertu-cli 装好。

从源码安装（贡献者）

需要本仓库源码时：

git clone https://gitee.com/he-linyan/vps-cli.git
cd vps-cli
make install            # 依赖 → 构建 → npm link
make install-vps-skills # 铺设 skill 到各 Agent 目录

vertu-cli npm 包位于 packages/vertu-cli/。直接维护包时：

cd packages/vertu-cli
npm install
npm run build

改 packages/vertu-cli/src/ 后执行 npm run build 即可让已 npm link 的全局命令生效。

Agent Skills

| Skill | 说明 | |-------|------| | vps-shared | 登录、身份、+ 约定（其他业务 skill 的前置阅读） | | vertu-cli | CLI 安装、skill 子命令、排错 | | vertu-onboard | 新机器：装 CLI、铺 skill、登录自检 | | sale-performance-query | 销售日报、部门 KPI、OKR 达成、人效与 PK | | vps-hr | 薪酬、工资条、人员信息 | | vps-product | 库存、商品价格、发货、齐套、机头库存 | | vps-creative | 内容创作画布：AI 生图、生视频、文字转语音、音乐生成与模型列表 | | vps-tools | 平台公共工具：上传文件到 OSS，返回公开或限时签名访问地址 | | vps-corporate | 合作企业档案、文件用印、业务管理、规章制度及附件 | | vps-approval | 待办审批 | | vps-daily-report-assistant | 打卡未交比对、统一日报查询、提交与同步 | | vps-task-management-assistant | 任务中心任务、待办、PDCA 协助人、OKR | | vps-documents | 企业云文档、智能表格与文件夹的查询、创建、单元格更新、导出、共享及 VPS IM 卡片投递 | | vps-v-drive | 账号级 OSS V盘普通文件、文件夹、传输记录与回收站 | | vps-im / vps-mail / vps-meeting | IM 消息与会话附件原文件下载、站内信、会议录音与纪要 |

vertu-cli skill list
vertu-cli skill install sale-performance-query vps-hr --agent cursor
vertu-cli skill install --all --agent all
vertu-cli skill update
vertu-cli skill uninstall sale-performance-query --agent cursor

--agent：cursor / claude / claude-code / trae / trae-cn / openclaw / hermes / all。--dir <path> 可装到自定义目录（可重复）。布局说明见 skills/README.md。

Agent 管理自己的个人技能使用带 + 的业务命令；它们复用宿主注入的 app_key，不需要临时令牌：

vertu-cli skill +create-personal --slug sales-follow-up --title "销售跟进" --description "生成客户跟进计划" --instructions @instructions.md
vertu-cli skill +update-personal --slug sales-follow-up --skill-md @SKILL.md --note "补充输出格式"
vertu-cli skill +change-category --slug sales-follow-up --category sales
vertu-cli skill +request-publication --slug sales-follow-up --note "申请企业公开"
vertu-cli skill +delete-personal --slug sales-follow-up

+create-personal 和 +update-personal 会自动补齐并校正 SKILL.md 的 YAML frontmatter，固定以 --slug 作为 name，同时保留其他 YAML 字段。skill update 仍表示同步随包公开技能，二者语义不变。

认证

| 命令 | 说明 | |------|------| | vertu-cli auth login | 登录 Vertu 账号，会话写入钥匙串或 ~/.vertu/config.json | | vertu-cli auth logout [--forget] | 登出；--forget 清理整个 profile | | vertu-cli auth status [--json] | 当前会话、角色与凭据来源 | | vertu-cli install [--tag latest] | 执行 npm install -g vertu-cli@<tag>（与 npx vertu-cli@latest install 等价） |

CI / 自动化常用环境变量：VERTU_BOT_INBOUND_KEY（Bearer）、VERTU_APP_ID + VERTU_APP_KEY（App Key）。

快捷命令

域入口与 lark-cli 类似：<域> +<子命令>，支持 --validate-only / --dry-run 本地预览请求载荷；execute 类 shortcut 会直接打印 skill_key / script_key / params，不发网络请求。

| 域 | 示例 | |----|------| | sales | vertu-cli sales +headline-kpi · +orders · +dept-breakdown · +customer-mix · +target-achievement · +per-person-kpi | | hr | vertu-cli hr +me · +org-tree · +headcount · +profile · +subordinates · +manager · +job-details · +contracts · +payslip | | product | vertu-cli product +inventory · +price · +delivery · +kit-materials · +phone-head-inventory | | creative | vertu-cli creative +models · +image · +video · +video-status · +tts · +music | | corporate | vertu-cli corporate +partner-list · +seal-list · +business-list · +regulation-list · +attachments | | approval | vertu-cli approval +wait · +pass / +reject | | task | vertu-cli task +tc-tasks · +tc-todos · +tc-todo-create | | okr | vertu-cli okr +org-tree · +dept-okr | | report | vertu-cli report +checkin-missing · +mine · +tasks · +submit · +sync | | calendar | vertu-cli calendar +mine · +person · +calendar · +create · +update · +response · +respond · +calendars · +availability | | docs | vertu-cli docs +list · +get · +create · +rename · +sheet-get · +sheet-set-cells · +share · +send · +duplicate · +export-markdown | | drive | vertu-cli drive +list · +mkdir · +create-file · +upload · +read · +write · +download · +move · +remove · +restore | | popup | vertu-cli popup +send --title "提醒" --content "正文"；管理员可加 --user-id / --login 推送给他人 | | im / mail / meeting | vertu-cli im +channels · +departments · mail +send · meeting +list（轻量列表）· meeting +detail（单场详情）· meeting +statistics（会议、待办闭环、日程来源，可按部门/模版分组） |

完整列表：vertu-cli sales --help（各域同理）。

常见查询示例：

vertu-cli sales +dept-breakdown --period this_month --group-by dept_l1
vertu-cli sales +customer-mix --period this_month
vertu-cli sales +target-achievement --period this_month --params '{"group_by":"dept_l1","limit":500}'
vertu-cli sales +dept-monthly-okr --period this_month --limit 100 --page 1
vertu-cli hr +headcount
vertu-cli hr +subordinates --direct
vertu-cli corporate +partner-list --search "深圳"
vertu-cli corporate +seal-list --kind contract --status finished
vertu-cli corporate +seal-list --kind contract --end-date-from 2025-08-13 --end-date-to 2026-08-12 --all
vertu-cli corporate +regulation-list
vertu-cli product +inventory --product-subcategory "VERTU ALPHAFOLD" --product-material 小牛皮 --product-color 黑色 --group-by store_detail
vertu-cli product +price --product-name "VERTU ALPHAFOLD-黑品质套装款-鳄鱼皮-樱花粉-1TB-国内" --limit 20
vertu-cli product +price --product-subcategory "VERTU ALPHAFOLD" --product-material 鳄鱼皮 --price-region overseas

部门销售目标默认使用管理端“部门业绩目标”相同的 部门OKR_1 数据；需要核对迁移后的 Postgres 目标表时显式传 --okr-source postgres。个人 OKR 仍默认使用 Postgres vps_okr_* 数据。

进阶用法

凭据与路径

| 类型 | 默认位置 | |------|----------| | 钥匙串 | service=vertu，account=session:<base_url> / bearer:<base_url> | | 配置文件（无钥匙串时） | ~/.vertu/config.json（Windows：%USERPROFILE%\.vertu\config.json），权限 0600 | | Skill 目录 | ~/.cursor/skills · ~/.claude/skills · ~/.trae/skills · ~/.trae-cn/skills · ~/.openclaw/skills · ~/.hermes/skills |

环境变量

| 变量 | 说明 | |------|------| | VERTU_BOT_INBOUND_KEY | Bot Bearer（CI） | | VERTU_APP_ID / VERTU_APP_KEY | Agent App Key | | VERTU_DISABLE_KEYTAR=1 | 强制文件存储 | | VERTU_DEBUG=1 | 调试输出 |

升级 / 卸载

npm update -g vertu-cli
npm uninstall -g vertu-cli

常见问题

1. npm install 时 keytar 编译失败？ keytar 为可选依赖。使用 npm install -g vertu-cli --no-optional 或设置 VERTU_DISABLE_KEYTAR=1，CLI 会降级到 ~/.vertu/config.json。

2. Trae 国际版与国内版 skill 目录冲突吗？ 不冲突：国际版 ~/.trae/skills/，国内版 ~/.trae-cn/skills/。skill install --all 默认写入两者；只需其一时用 --agent trae 或 --agent trae-cn。

3. npm 上的 README 与仓库不一致？ 以 npm 包页 与当前发布的 README.md 为准；源码协作见 Gitee 仓库 he-linyan/vps-cli。

开发

npm install
npm run dev -- --help
npm run typecheck
npm test
npm run build

许可证

MIT