vps-work

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

VPS Work CLI 是 Vertu VPS 平台的官方命令行，命令名为 vps-work，取代已弃用的 vertu-cli。登录会话使用独立目录 ~/.vps-work 与钥匙串服务名 vps-work；服务端只识别 vps-work 渠道，旧 vertu-cli 不再受支持。

Skill 为静态文件，安装 skill 无需登录；业务取数需登录 Vertu 账号。

• npm 包：vps-work
• 全局命令：vps-work（不提供 vertu-cli 别名）

为什么选 vps-work？

• 为 Agent 设计 — 域级 SKILL.md + vps-work <域> +… 快捷命令，参数与契约面向 AI 调用优化
• 安装简单 — npx vps-work@latest install 装 CLI，并自动铺设到本机已检测到的 Agent 目录
• 覆盖面广 — 销售、人资、产品供应链/价格、审批、任务/OKR、日报、IM/站内信/会议等
• 三层粒度 — catalog 活目录 → exec 通用执行 → 本机 + 快捷命令糖衣
• 凭据可控 — 系统钥匙串或 ~/.vps-work/config.json；CI 可用 VERTU_BOT_INBOUND_KEY / App Key

功能

| 类别 | 能力 | |------|------| | 平台 | CLI 安装升级、skill 子命令、登录会话与 OSS 公共工具（vps-work / vps-work-onboard / vps-tools） | | 身份 | 当前用户、部门、上级与组织上下文（vps-current-user-identity） | | 销售与经营 | 公司总销日报、已对账销售收款、部门下钻、目标达成、OKR 达成、销售人效与 PK（sale-performance-query 等） | | 人力资源 | 组织架构、人员档案、上下级、岗位、工龄、合同、工资条、入职、转正、调岗与离职办理（vps-hr） | | 考勤 | 日报、排班、假期余额及请假、出差、外勤、加班、补卡、换班申请（vps-attendance） | | 知识库 | 知识库、V盘资料导入、检索、问答与知识图谱（vps-knowledge） | | 产品与供应链 | 库存、商品价格、发货、齐套物料、机头库存、在库激活与异常 IMEI（vps-product、vps-device-abnormal-statistics） | | 内容创作 | 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 列表：vps-work skill list 或仓库 skills/ 目录。

安装与快速开始

环境要求

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

快速开始（人类用户）

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

安装

任选其一：

npx vps-work@latest install

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

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

业务 skill 目录名仍是 vps-im / vps-hr 等，skill install / skill update 覆盖式同步，并自动删除旧包遗留的 vertu-cli / vertu-onboard 引导 skill。

配置与使用

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

vps-work auth login
vps-work auth status
vps-work sales +headline-kpi
vps-work --help

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

vertu-cli 已弃用：安装 vps-work 后请执行 npm uninstall -g vertu-cli 并删除 ~/.vertu。

快速开始（AI Agent）

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

第 1 步 — 安装 CLI

npx vps-work@latest install

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

vps-work skill list
vps-work skill install --all --agent all

第 3 步 — 验证宿主凭证

vps-work auth status

第 4 步 — 验证

vps-work auth status
vps-work --version
vps-work sales +headline-kpi --validate-only
vps-work hr +headcount --dry-run

升级 CLI 后覆盖同步 skill：vps-work skill update。

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

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

macOS / Linux：

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

Windows PowerShell：

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

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

从源码安装（贡献者）

需要本仓库源码时：

git clone https://gitee.com/he-linyan/vps-cli.git
cd vps-cli
cd packages/vps-work
npm install && npm run build && npm link

vps-work npm 包位于 packages/vps-work/。直接维护包时：

cd packages/vps-work
npm install
npm run build

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

Agent Skills

| Skill | 说明 | |-------|------| | vps-shared | 登录、身份、+ 约定（其他业务 skill 的前置阅读） | | vps-work | CLI 安装、skill 子命令、排错 | | vps-work-onboard | 新机器：装 CLI、铺 skill、登录自检 | | sale-performance-query | 销售日报、部门 KPI、OKR 达成、人效与 PK | | vps-hr | 人员信息、薪酬、工资条与新人事办理 | | vps-attendance | 考勤日报、排班、余额与业务申请 | | vps-knowledge | 企业知识库、检索、问答与知识图谱 | | vps-product | 库存、商品价格、发货、齐套、机头库存，并路由设备异常查询 | | vps-device-abnormal-statistics | 仓位在库激活、异常 IMEI 与未处理异常原因下钻 | | 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 消息与会话附件原文件下载、站内信、会议录音与纪要 |

vps-work skill list
vps-work skill install sale-performance-query vps-hr --agent cursor
vps-work skill install --all --agent all
vps-work skill update
vps-work 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，不需要临时令牌：

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

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

认证

| 命令 | 说明 | |------|------| | vps-work auth login | 登录 Vertu 账号，会话写入钥匙串或 ~/.vps-work/config.json | | vps-work auth logout [--forget] | 登出；--forget 清理整个 profile | | vps-work auth status [--json] | 当前会话、企业 tenant_type / 产品包与凭据来源 | | vps-work auth tenants | 列出当前账号可访问的企业（仅人工/宿主切换） | | vps-work auth use --tenant <uuid> | 切换当前企业；Agent 不得自行执行 | | vps-work catalog [--domain sales] | 当前企业身份可见的活目录（服务端裁剪） | | vps-work exec --skill <key> --script <key> | 按 catalog 执行，不必为每个新脚本发 npm | | vps-work install [--tag latest] | 执行 npm install -g vps-work@<tag>（与 npx vps-work@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 | vps-work sales +headline-kpi · +orders · +reconciled-receipts · +dept-breakdown · +customer-mix · +target-achievement · +per-person-kpi | | hr | vps-work hr +me · +org-tree · +headcount · +profile · +contracts · +payslip · +business-list · +onboarding · +transfer · +resignation | | attendance | vps-work attendance +daily · +schedule-* · +applications · +application-preview · +application-submit | | knowledge | vps-work knowledge +list · +documents · +import-vdrive · +search · +ask · +graph | | product | vps-work product +inventory · +price · +delivery · +kit-materials · +phone-head-inventory · +abnormal-location · +abnormal-location-list · +abnormal-details | | creative | vps-work creative +models · +image · +video · +video-status · +tts · +music | | corporate | vps-work corporate +partner-list · +seal-list · +business-list · +regulation-list · +attachments | | approval | vps-work approval +wait · +pending --scope department\|all · +pass / +reject | | task | vps-work task +tc-tasks · +tc-todos · +tc-department-overview · +tc-todo-create | | okr | vps-work okr +org-tree · +dept-okr | | report | vps-work report +checkin-missing · +mine · +tasks · +submit · +sync | | calendar | vps-work calendar +mine · +person · +calendar · +create · +update · +response · +respond · +calendars · +availability | | docs | vps-work docs +list · +get · +create · +rename · +sheet-get · +sheet-set-cells · +share · +send · +duplicate · +export-markdown | | drive | vps-work drive +list · +mkdir · +create-file · +upload · +read · +write · +download · +move · +remove · +restore | | popup | vps-work popup +send --title "提醒" --content "正文"；管理员可加 --user-id / --login 推送给他人 | | im / mail / meeting | vps-work im +channels · +departments · mail +send · meeting +list（轻量列表）· meeting +detail（单场详情）· meeting +statistics（会议、待办闭环、日程来源，可按部门/模版分组） |

完整列表：vps-work sales --help（各域同理）。

常见查询示例：

vps-work sales +dept-breakdown --period this_month --group-by dept_l1
vps-work sales +customer-mix --period this_month
vps-work sales +reconciled-receipts --order-types sale,service --invoiced true --limit 100
vps-work sales +target-achievement --period this_month --params '{"group_by":"dept_l1","limit":500}'
vps-work sales +dept-monthly-okr --period this_month --limit 100 --page 1
vps-work hr +headcount
vps-work hr +subordinates --direct
vps-work corporate +partner-list --search "深圳"
vps-work corporate +seal-list --kind contract --status finished
vps-work corporate +seal-list --kind contract --end-date-from 2025-08-13 --end-date-to 2026-08-12 --all
vps-work corporate +regulation-list
vps-work product +inventory --product-subcategory "VERTU ALPHAFOLD" --product-material 小牛皮 --product-color 黑色 --group-by store_detail
vps-work product +price --product-name "VERTU ALPHAFOLD-黑品质套装款-鳄鱼皮-樱花粉-1TB-国内" --limit 20
vps-work product +price --product-subcategory "VERTU ALPHAFOLD" --product-material 鳄鱼皮 --price-region overseas
vps-work product +abnormal-location --default-selected
vps-work product +abnormal-details --imeis 860000000000001,860000000000002 --stat-date 2025-09-01 --end-date 2026-07-02

设备异常三个命令经 vps-service 鉴权代理访问，只允许授权中心已明确分配 vps_device_abnormal_analyst（VPS 设备异常分析）角色、具备 product.device_abnormal:read 的在职内部员工使用；外部/经销商账号和仅有 admin:* 的管理员不放行。

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

进阶用法

凭据与路径

| 类型 | 默认位置 | |------|----------| | 钥匙串 | service=vps-work，account=session:<base_url> / bearer:<base_url> | | 配置文件（无钥匙串时） | ~/.vps-work/config.json（Windows：%USERPROFILE%\.vps-work\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 vps-work
npm uninstall -g vps-work

常见问题

1. npm install 时 keytar 编译失败？ keytar 为可选依赖。使用 npm install -g vps-work --no-optional 或设置 VERTU_DISABLE_KEYTAR=1，CLI 会降级到 ~/.vps-work/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 run lint
npm test
npm run build

许可证

MIT