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 子命令、登录与会话（vertu-cli / vertu-onboard） | | 身份 | 当前用户、部门、上级与组织上下文（vps-current-user-identity） | | 销售与经营 | 公司总销日报、部门下钻、目标达成、OKR 达成、销售人效与 PK（vps-sales 等） | | 人力资源 | 组织架构、人员档案、上下级、岗位、工龄、合同、工资条（vps-hr） | | 产品与供应链 | 库存、商品价格、发货、齐套物料、机头库存（vps-product） | | 研发与 OKR | 任务中心任务/待办、部门与个人 OKR（vps-task-management-assistant、vps-okr） | | 日报 | 打卡未交比对、员工日报与 OKR、我的日报、提交与助手同步（vps-daily-report-assistant） | | 审批 | 待办队列与处理指引（vps-approval） | | 协作 | IM、站内信、Vemory 会议（vps-im / vps-mail / vps-vemory） |

完整 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。

配置与使用

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；login 可能需要用户在终端完成交互或提供账号。

第 1 步 — 安装 CLI

npx vertu-cli@latest install

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

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

第 3 步 — 登录

vertu-cli auth login

第 4 步 — 验证

vertu-cli auth status
vertu-cli --version
vertu-cli sales +headline-kpi --validate-only

升级 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 装好。

从源码安装（贡献者）

需要本仓库源码时：

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

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

Agent Skills

| Skill | 说明 | |-------|------| | vps-shared | 登录、身份、+ 约定（其他业务 skill 的前置阅读） | | vertu-cli | CLI 安装、skill 子命令、排错 | | vertu-onboard | 新机器：装 CLI、铺 skill、登录自检 | | vps-sales | 销售日报、部门 KPI、OKR 达成、人效与 PK | | vps-hr | 薪酬、工资条、人员信息 | | vps-product | 库存、商品价格、发货、齐套、机头库存 | | vps-approval | 待办审批 | | vps-daily-report-assistant | 打卡未交比对、员工日报与 OKR、我的日报、提交与同步 | | vps-task-management-assistant | 任务中心任务、待办、OKR | | vps-im / vps-mail / vps-vemory | IM、站内信、会议回顾 |

vertu-cli skill list
vertu-cli skill install vps-sales vps-hr --agent cursor
vertu-cli skill install --all --agent all
vertu-cli skill update
vertu-cli skill uninstall vps-sales --agent cursor

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

认证

| 命令 | 说明 | |------|------| | 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 本地预览请求载荷。

| 域 | 示例 | |----|------| | sales | vertu-cli sales +headline-kpi · +orders · +dept-breakdown · +target-achievement · +per-person-kpi | | hr | vertu-cli hr +me · +org-tree · +profile · +subordinates · +manager · +job-details · +contracts · +payslip | | product | vertu-cli product +inventory · +price · +delivery · +kit-materials · +phone-head-inventory | | 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 · +user-summary · +mine · +tasks · +submit · +sync | | im / mail / vemory | vertu-cli im +channels · +departments · mail +send · vemory +meetings |

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

常见查询示例：

vertu-cli sales +dept-breakdown --period this_month --group-by dept_l1
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 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 目标默认使用 Supabase vps_okr_* 数据；只有排查旧 PMS/BI 口径时才加 --okr-source legacy。

进阶用法

凭据与路径

| 类型 | 默认位置 | |------|----------| | 钥匙串 | 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