vps-work 1.0.0

package/skills/vps-v-drive/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: vps-v-drive
+description: 使用 `vps-work drive +…` 管理账号级云端 V盘中的普通文件和文件夹；文件内容存储于 OSS，并与 VPS Desktop、手机端共用同一份数据。
+metadata:
+  requires:
+    bins: ["vps-work"]
+  cliHelp: "vps-work drive --help"
+---
+
+# VPS V盘文件管理
+
+开始前先读取 `../vps-shared/SKILL.md`，遵循其中的认证、当前用户与 `+` 快捷约定。Hermes 使用宿主注入的 Agent Key 和当前用户身份；V盘不依赖 Odoo Session。
+
+本技能通过 `/v1/v-drive` 操作账号级云端 V盘，文件内容直传阿里云 OSS，元数据由服务端统一管理。它与 VPS Desktop、手机端共用同一份数据，不得绕过 API 写入本地 `v-drive/files/`。命令默认输出 JSON，Hermes 必须从返回值读取 `item.id`，不得根据文件名猜 ID。
+
+V盘中的企业云文档、智能表格及其共享权限由 `vps-documents` 技能和 `vps-work docs +…` 管理；本技能不修改云文档。共享空间成员和安全策略目前也不通过本命令管理。
+
+## 命令选择
+
+| 用户意图 | 命令 |
+|---|---|
+| 查看根目录 | `vps-work drive +list` |
+| 查看文件夹 | `vps-work drive +list --parent-id <id>` |
+| 递归搜索 | `vps-work drive +list --recursive --query <关键词>` |
+| 查看单项元数据 | `vps-work drive +info --item-id <id>` |
+| 新建文件夹 | `vps-work drive +mkdir --name <名称> [--parent-id <id>]` |
+| 新建文本文件 | `vps-work drive +create-file --name <文件名> [--content-file <path>]` |
+| 上传本地文件 | `vps-work drive +upload --source <path> [--source <path> ...]` |
+| 读取小文件 | `vps-work drive +read --item-id <id>` |
+| 覆盖文本内容 | `vps-work drive +write --item-id <id> --content-file <path>` |
+| 下载到本地 | `vps-work drive +download --item-id <id> --output <path>` |
+| 重命名 | `vps-work drive +rename --item-id <id> --name <新名称>` |
+| 移动到文件夹 | `vps-work drive +move --item-id <id> --parent-id <文件夹id>` |
+| 移动到根目录 | `vps-work drive +move --item-id <id> --parent-id root` |
+| 移入回收站 | `vps-work drive +remove --item-id <id>` |
+| 查看回收站 | `vps-work drive +trash` |
+| 恢复 | `vps-work drive +restore --item-id <id>` |
+| 永久删除 | `vps-work drive +purge --item-id <id>` |
+| 清空回收站 | `vps-work drive +empty-trash` |
+| 查看传输记录 | `vps-work drive +transfers` |
+| 迁移旧版本地 V盘 | `vps-work drive +migrate-local [--root <旧目录>]` |
+
+执行前可用 `vps-work drive <命令> --help` 核对参数。`vdrive` 和 `v-drive` 是 `drive` 的兼容别名，Hermes 应固定使用 `drive`。
+
+## 标准操作流程
+
+1. 先运行 `+list` 或 `+trash`，从 JSON 返回中取得准确的 `id`、`kind`、`parentId`。
+2. 文件夹层级操作使用 ID，不使用路径或同名文件推断。
+3. 写操作完成后检查返回的 `item`；需要确认目录结果时再运行一次 `+list`。
+4. `+read` 默认最多输出 1 MiB UTF-8 内容。二进制文件用 `--encoding base64`；大文件用 `+download`。
+
+## 账号与旧数据迁移
+
+普通命令使用当前 `vps-work` 登录账号或 Agent 绑定账号，并支持 `--base-url` 指定 Vertu 服务。只有 `+migrate-local` 会读取旧版数据目录：
+
+- macOS：`~/Library/Application Support/vertu-im-desktop/v-drive`
+- Windows：`%APPDATA%\vertu-im-desktop\v-drive`
+- Linux：`${XDG_CONFIG_HOME:-~/.config}/vertu-im-desktop/v-drive`
+
+`+migrate-local` 会把旧文件和文件夹上传到 OSS，并用 `oss-migration-v1.json` 记录进度以支持断点续传；迁移不会删除本地源文件。`--root` 和 `VERTU_V_DRIVE_ROOT` 只影响迁移命令，不影响云端 V盘的普通操作。
+
+## 写入与删除安全
+
+- `+upload` 会把源文件上传到 OSS，源文件保持不变。
+- `+create-file` 和 `+write` 只写 UTF-8 文本；`+write` 会覆盖已有内容，必须符合用户明确意图。
+- `+download` 默认拒绝覆盖已有目标文件；只有用户明确允许覆盖时才传 `--overwrite`。
+- `+remove` 只是移入回收站，可以用 `+restore` 恢复。
+- `+purge` 和 `+empty-trash` 会永久删除实际文件。只有用户明确要求永久删除或清空回收站时才可执行；不得把“删除”自动解释为永久删除。
+- 所有写操作都通过服务端鉴权和账号隔离；不要把 OSS 签名地址或认证凭据写入回复。
+
+## 示例
+
+```bash
+vps-work drive +list --recursive --query "周报"
+vps-work drive +mkdir --name "项目资料"
+vps-work drive +upload --parent-id <folder-id> --source ./方案.pdf --source ./预算.xlsx
+printf '# 周报\n\n本周完成' | vps-work drive +create-file --name "周报.md" --content-file -
+vps-work drive +read --item-id <file-id>
+vps-work drive +download --item-id <file-id> --output ./downloads/
+vps-work drive +remove --item-id <item-id>
+vps-work drive +restore --item-id <item-id>
+```

package/skills/vps-vemory/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: vps-vemory
+version: 1.1.0
+description: 旧版 Vemory 会议查询兼容入口。新调用应使用 `vps-meeting` 与 `vps-work meeting +list`。
+metadata:
+  requires:
+    bins: ['vps-work']
+  cliHelp: 'vps-work vemory --help'
+---
+
+# vemory
+
+**MUST Read [`../vps-shared/SKILL.md`](../vps-shared/SKILL.md)**
+
+这是旧产品名称的兼容技能。新任务必须优先读取
+[`../vps-meeting/SKILL.md`](../vps-meeting/SKILL.md) 并使用 `vps-work meeting +list`。
+
+| Shortcut | 契约 |
+|----------|------|
+| `+meetings` | 见 `vps-work vemory --help` |
+
+## 按员工姓名查询
+
+用户指定员工姓名时，必须将姓名原样传给 `--employee-name`：
+
+```bash
+vps-work vemory +meetings --employee-name "温若琪" --start-date 2026-07-09 --end-date 2026-07-15
+```
+
+- 不要把按姓名查询改写为 `--scope mine` 或 `--scope team`。
+- `--keyword` 只搜索会议主题、摘要、章节和待办，不搜索员工姓名。
+- 命令直接返回结构化 JSON；不要追加 `jq`、`grep` 等二次处理命令。
+- 成功的按姓名查询返回 `scope: "person"`、`target_user_id` 和 `target_name`。

package/skills/vps-work/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: vps-work
+description: |
+  VPS Work CLI（npm 包 vps-work，全局命令 vps-work）的安装、登录、使用、升级与卸载引导。
+  当用户提到「装 vps-work」「vps-work 命令找不到 / not recognized / command not found」「vps-work auth login 报错」
+  「升级 vertu / 升级 vps-work」「装其它 skill 但还没 vps-work」
+  「Cursor / Claude Code / Trae / OpenClaw / Hermes 怎么接 vps skill」时使用本技能。
+  本 skill 不依赖任何已登录会话，可被 agent 直接 wget / curl 拿到、按文档逐步执行。
+  公开下载地址：https://admin.vertu.cn/ai_skills/static/skills/vps-work/SKILL.md
+---
+
+# vps-work 引导
+
+## 何时使用
+
+只要用户的诉求落在下面任一条，就**先**读完本 SKILL.md 再执行，不要凭记忆拼命令：
+
+- 还没装 `vps-work` —— 第一次用、换机器、CI/容器里跑
+- `vps-work` 装了但 `vps-work --version` / `vps-work auth login` / `vps-work <域> +…` 报错
+- 想把随包分发的公开 skill 一键装到 Cursor / Claude Code / Trae 国际版 / Trae 国内版 / OpenClaw / Hermes 或自定义目录
+- 升级 / 卸载 / 重装 vps-work 自身
+- 用户问「这个 ERP 怎么从命令行查数据 / 调 skill / 接 AI agent」
+
+> 本 skill 是 **bootstrap**：执行成功后，按 `vps-work skill list` 看到的业务 skill（如 `sale-performance-query`、`vps-im`）继续工作。
+
+当 Agent 需要新建、更新、分类、申请公开或删除当前用户自己的个人技能时，使用本文 §5.1 的 `vps-work skill +…` 命令；不得直接拼接 Hermes 管理接口。
+
+## 前置
+
+- **Node.js ≥ 20**（包内 `engines.node` 已声明）
+  - Windows：建议从 nodejs.org 装 LTS，或 `winget install OpenJS.NodeJS.LTS`
+  - macOS：`brew install node@20` 或 nvm
+  - Linux：`nvm install 20 && nvm use 20`
+- **网络**能访问 `https://registry.npmjs.org/`（国内可换 `npm config set registry https://registry.npmmirror.com`，但生产稳定性建议用官方源）
+- **shell**：Windows 用 PowerShell（本仓库默认）；macOS / Linux 用 bash / zsh
+
+## 1. 安装
+
+```powershell
+# Windows PowerShell
+npm install -g vps-work
+vps-work --version
+```
+
+```bash
+# macOS / Linux
+npm install -g vps-work
+vps-work --version
+```
+
+`vps-work --help` 能正常打印命令树即为安装成功。旧 `vertu-cli` 已弃用，服务端不再识别其渠道；如已安装，执行 `npm uninstall -g vertu-cli` 并删除 `~/.vertu`。
+
+**keytar 编译失败时**（Windows 没装 build tools / 容器里没 python）：
+
+```powershell
+$env:VERTU_DISABLE_KEYTAR = '1'
+npm install -g vps-work --no-optional
+```
+
+CLI 会自动降级到文件存储（`~/.vps-work/config.json`，POSIX 0600），功能完全等价，只是 session 不进系统钥匙串。
+
+## 2. 认证边界
+
+**Agent / Bot / Hermes 禁止执行账号密码登录、`reauth` 或 legacy Odoo 登录，也不得索取、猜测或在 Prompt/命令中传递密码。** Agent 应使用宿主注入的 app_key；Hermes 固定使用 `app_id=vertu-hermes-agent`。
+
+若用户明确需要人工账号密码登录或 legacy Odoo 兼容排障，只引导用户阅读包内 `README.md` / `USAGE.md` 并由用户在交互终端操作；Agent 不得代为执行。
+
+**CI / Bot 模式**（无密码、走 inbound bot key）：
+
+```powershell
+$env:VERTU_BOT_INBOUND_KEY = 'xxxxxxxxxxxxxxxxxxxxxxxx'
+vps-work auth status     # 直接验证；不需要 vps-work auth login
+```
+
+> Bearer 与 session 同时存在时 **Bearer 优先**，会掩盖用户会话。开发期请用 `vps-work auth logout --forget` 清掉残留 session 后再用 Bearer，避免审计记到错的人头上。
+
+验证：
+
+```powershell
+vps-work auth status            # 查看当前会话：企业 / 角色 / agent
+vps-work auth status --json     # 机读
+vps-work catalog --json         # 当前企业身份可见的命令清单
+```
+
+### 2.1 IM / 通讯类命令走 Vertu 原生 IM
+
+通讯类命令（`vps-work im +…`、`vps-work mail +send` 等）统一走 Vertu 原生 IM，与主登录共用同一份会话，**不再需要单独登录任何 Odoo IM 端点**（旧的「im 次端点联动登录」已下线）。
+
+只要 `vps-work auth status` 显示会话有效即可使用：
+
+```powershell
+vps-work auth status
+vps-work im +channels --limit 1   # 200 + 频道 → IM 可用；401 → 见 §2.2
+```
+
+### 2.2 IM 命令报 401 的修复
+
+Agent / Bot / Hermes 必须停止重试并提示管理员刷新宿主 app_key。人工会话问题由用户在交互终端处理；Agent 不提供或执行密码登录命令。
+
+## 3. 命令清单
+
+稳定原语是 `catalog` / `exec` / `auth`。业务快捷命令可以继续用 `+`，但**当前身份能用哪些脚本以服务端目录为准**：
+
+```powershell
+vps-work catalog --json                 # 当前企业身份可见的命令
+vps-work catalog --domain sales --json
+vps-work exec --skill vps-dealer-ops --script sales --param period=this_month
+vps-work --help                         # 本机命令糖衣
+vps-work sales --help
+```
+
+> 新快捷命令只需服务端登记，不必升级 npm。本地 `+` 命令树不是全集。
+
+## 4. 用法骨架
+
+### Agent 主动弹出手机端弹窗
+
+Agent 默认向当前 `app_key` 绑定用户投递一次性声明式弹窗；管理员可通过 `--user-id`
+或 `--login` 指定其他用户。前台用户约 0–10 秒展示，离线用户下次打开 VPS 手机端时展示。
+禁止下发 HTML、JavaScript 或非 HTTPS 链接。
+
+```bash
+vps-work popup +send \
+  --user-id 12708 \
+  --title "今日提醒" \
+  --content "还有 2 个待办即将到期。" \
+  --height 0.68 \
+  --gradient-start "#FCEBE4" \
+  --gradient-end "#FFFBFA" \
+  --button-text "立即查看" \
+  --button-style filled \
+  --button-background-color "#1F1D1A" \
+  --button-text-color "#FFFFFF" \
+  --button-url "https://vps.vertu.cn/todos"
+```
+
+可通过 `--background-color` 设置纯色背景，或通过 `--background-image-url` 设置 HTTPS
+背景图；长正文使用 `--content-file <path>`。`--user-id` 与 `--login` 二选一，普通用户
+只能向自己推送。执行前可加 `--dry-run` 检查完整请求。
+
+### 4.1 通用形态
+
+```powershell
+vps-work <program> <segment...> [--<flag-kebab-case> ...]
+```
+
+- flag 名是 schema key 的 **kebab-case**：`salary_month` → `--salary-month`，`start_date` → `--start-date`（snake_case 也接受，会归一化）
+- 错名会得到上下文提示：`--month` → `(Did you mean one of --salary-month, --salary-month-file?)`
+- 单 `required: string` 字段的 leaf 支持 **positional shorthand**：
+
+```powershell
+vps-work <域> +<shortcut> "<值>"
+# 等价 vps-work <域> +<shortcut> --<对应必填参数> "<值>"
+```
+
+### 4.2 三个最常用范例
+
+```powershell
+# 业务取数（专项域命令）
+vps-work sales +headline-kpi --period this_month
+vps-work sales +headline-kpi --period this_month --dry-run
+vps-work hr +headcount
+
+# 发一条 IM 消息
+vps-work im +send --channel-id 1024 --body "今天的报价已更新"
+```
+
+### 4.2.1 请求另一名员工的 VPS Harness Agent
+
+```powershell
+vps-work im +users --query "张三"
+vps-work agent ask --user-id 12708 --message "请汇总今天的客户跟进风险"
+vps-work agent ask --user-id 12708 --message @request.md --duration-minutes 30
+```
+
+对方需在线并在 VPS Harness 设置中开启 Agent 联系开关。双方会话列表会显示真实的 Harness Bot 协作会话，消息以 Bot 身份发送，不占用员工私聊。不带截止时间时只执行一轮；使用 `--stop-at` 或 `--duration-minutes` 后会循环协作，到点自动停止。收到首轮答复时命令立即返回，后续轮次由桌面端后台继续。普通 IM 消息不会触发 Harness；完整用法见 `vps-work agent ask --help`。
+
+### 4.2.2 让我的 VPS Harness Agent 联系员工
+
+```powershell
+vps-work im +users --query "张三"
+vps-work agent message-user --user-id 12708 --message "请确认今天 16:00 的评审时间"
+```
+
+消息以当前用户的 VPS Harness Bot 身份发送到独立机器人私聊。对方以普通员工身份回复后，当前用户桌面端会使用 VPS Harness 设置中选定的 Agent Preset 回复；一条员工消息只触发一次，不会自行循环。当前用户需保持桌面端在线并开启 Agent 联系开关。完整用法见 `vps-work agent message-user --help`。
+
+### 4.2.3 让任意自建机器人联系员工
+
+```powershell
+vps-work im +bots
+vps-work im +bot-send-user --app-id vbot_xxx --user-id 12708 --body "请提交今日销售数据"
+```
+
+该命令只允许使用当前用户自己的机器人，并复用宿主登录会话或 Agent Key，不需要 App Secret。员工回复会进入机器人已有的 webhook 或内置 Agent 处理链路；它不受 VPS Harness 开关和 Agent Preset 控制。正文、附件、引用和幂等参数见 `vps-work im +bot-send-user --help`。
+
+### 4.2.4 使用平台公共工具上传 OSS
+
+```powershell
+vps-work tools +oss-upload --file ./report.pdf
+vps-work tools +oss-upload --file ./logo.png --visibility public
+```
+
+默认使用私有对象并返回限时签名 URL；只有用户明确要求公开访问时才传 `--visibility public`。完整安全边界与参数见 `vps-tools` Skill 和 `vps-work tools +oss-upload --help`。
+
+### 4.3 PowerShell 引号约定（重要，AI 高频踩坑）
+
+- domain 这种**外层 PowerShell 字符串**用**单引号**包裹，**内层** Python 字面量保持**双引号**：
+  - 正确：`--domain '[("active","=",True)]'`
+  - 错误：`--domain "[('active','=',True)]"`（双引号在 PowerShell 里会被字符串展开吃掉）
+- 复杂 JSON 走文件：`--params (Get-Content .\params.json -Raw)`
+
+## 5. 装公开 skill 到各 Agent 目录
+
+所有 skill 都**随 npm 包静态分发、完全公开**，`vps-work skill *` 直接把包内 `skills/` 拷贝到 AI Agent 的用户级 skills 目录——**无需登录、不连任何服务端**。
+
+```powershell
+vps-work skill list                                  # 列出随包分发的公开 skill
+vps-work skill install                               # 不传参 → 装全部到已检测到的 Agent
+vps-work skill install vps-im sale-performance-query --agent cursor   # 显式装到指定 agent
+vps-work skill install --all --agent all             # 一把全装（cursor + claude-code + trae + trae-cn + openclaw + hermes）
+vps-work skill install vps-im --dir ~/work/my-agent/skills   # 自定义目录
+vps-work skill update                                # 覆盖式重同步到全部已检测到的 Agent
+vps-work skill uninstall <key>                       # 从已检测到的 Agent 移除
+```
+
+`vps-work install` 在装包成功后会**自动**把公开 skill 铺到检测到的 Agent 目录（可用 `--no-skills` 关闭）。
+
+### 5.1 Agent 管理当前用户自己的技能
+
+```bash
+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
+```
+
+- 这组命令复用宿主注入的 app_key；Agent 不登录、不索取密码，也不申请临时令牌。
+- 新建和更新必须通过 `--skill-md` 或 `--instructions` 提供内容，支持 `@file` / `@-`。
+- CLI 与服务端都会补齐并校正 YAML frontmatter；`name` 使用稳定 slug，`description` 自动补齐，扩展字段保留。
+- 只能管理当前身份自己创建的个人技能。`+request-publication` 只提交审核，不会绕过审核直接公开。
+
+支持的 `--agent` id（用逗号或空格分隔；`all` 表示全部）：
+
+| id | 安装路径 |
+|---|---|
+| `cursor` | `~/.cursor/skills/<key>/` |
+| `claude-code`（别名 `claude`） | `~/.claude/skills/<key>/` |
+| `trae` | `~/.trae/skills/<key>/`（国际版） |
+| `trae-cn` | `~/.trae-cn/skills/<key>/`（国内版） |
+| `openclaw`（别名 `open-claw` / `claw`） | `~/.openclaw/skills/<key>/` |
+| `hermes`（别名 `hermes-agent` / `nous`） | `~/.hermes/skills/<key>/` |
+
+`--dir <path>` 与 `--agent` 可混用，路径支持 `~` 展开；同一物理路径只写一次。
+
+## 6. 升级 vps-work 自身
+
+### 6.1 常规升级（之前就是从 npm registry 装的）
+
+```powershell
+npm update -g vps-work
+vps-work --version
+vps-work skill update         # 把新版随包分发的 skill 重新同步到所有 agent
+```
+
+### 6.2 tarball / npm link 装的（`npm update` 拉不到最新版）
+
+旧 `vertu-cli` 已弃用。排障时若发现 `vertu-cli` 仍在 PATH 中干扰，直接 `npm uninstall -g vertu-cli`。
+
+**先判断**：
+
+```powershell
+# Windows PowerShell
+npm list -g --depth=0 | Select-String 'vps-work'
+where.exe vps-work
+(Get-Item "$(npm root -g)\vps-work" -ErrorAction SilentlyContinue).LinkType
+# 期望：列表中只有一条 vps-work@<最新版>，LinkType 为空（非 Junction/SymbolicLink）
+# LinkType=Junction 或 SymbolicLink → 是源码 npm link 的工作区，不会跟 registry 升级
+```
+
+```bash
+# macOS / Linux
+npm list -g --depth=0 | grep vps-work
+which vps-work
+readlink -f "$(npm root -g)/vps-work"
+```
+
+**只重装本包**：
+
+```powershell
+# Windows PowerShell
+npm uninstall -g vps-work
+npm install -g vps-work
+vps-work --version
+vps-work skill update
+```
+
+```bash
+# macOS / Linux
+npm uninstall -g vps-work
+npm install -g vps-work
+vps-work --version
+vps-work skill update
+```
+
+> **判断口径**：只要 `npm update -g vps-work` 跑完后 `vps-work --version`
+> 没动，就走本节流程。
+>
+> **贡献者注意**：如果你本来就是 `npm link` 的工作区开发者，**不要**走本节
+> uninstall 流程。直接 `cd packages/vps-work && git pull && npm install && npm run build` 即可。
+
+## 7. 卸载
+
+会话目录是 `~/.vps-work`，钥匙串服务名是 `vps-work`。可选清理会话：`Remove-Item $HOME\.vps-work -Recurse -Force`；旧 `vertu-cli` 的 `~/.vertu` 也可一并删除。
+
+```powershell
+# 1. 先把本包铺到各 agent 的 skill 清掉（可选）
+vps-work skill uninstall --agent all
+
+# 2. 卸载 vps-work（如仍有已弃用的 vertu-cli 也一并卸载）
+npm uninstall -g vps-work
+```
+
+## 8. 一行 bootstrap
+
+Agent 自举只安装并检查宿主凭证，不执行登录：
+
+```powershell
+# Windows PowerShell（install 会自动铺公开 skill）
+npm install -g vps-work; vps-work skill install --all --agent all; vps-work auth status
+```
+
+```bash
+# macOS / Linux
+npm install -g vps-work && vps-work skill install --all --agent all && vps-work auth status
+```
+
+CI（无交互）：
+
+```bash
+export VERTU_BOT_INBOUND_KEY=xxx
+npm install -g vps-work && vps-work auth status && vps-work skill install --all --agent all
+```
+
+## 9. 常见坑点
+
+| 现象 | 根因 | 正确做法 |
+|---|---|---|
+| `vps-work : 无法将 ... 识别为 cmdlet` / `command not found: vps-work` | 全局 `npm bin` 不在 `PATH` | `npm config get prefix` 看到的目录加进 `PATH`；或重开终端；Windows 上注意 `where.exe vps-work` 是否找到 |
+| `npm install` 卡在 keytar 编译 | 无 build tools / 无 python | `$env:VERTU_DISABLE_KEYTAR='1'` + `--no-optional` 重装 |
+| `npm update -g vps-work` 跑完 `vps-work --version` 还是旧值 | 之前装的是 tarball 或 `npm link` 的工作区拷贝，与 registry 包**不在同一更新链** | 走 §6.2：重装 `vps-work` |
+| 人工执行 `vps-work auth login` 返回 401 | 用户名 / 密码错；或服务地址打错 | 仅由人工确认账号与地址；Agent 不得索取或重试密码 |
+| `vps-work im +…` / `vps-work vemory +…` / `vps-work mail +send` 报 401 | 凭证无效 | Agent/Bot/Hermes 停止并提示管理员刷新宿主 app_key；人工用户可交互重新登录 |
+| `--model` 写错了被提示 `Did you mean --model-name` | flag 必须 kebab-case | 改成 `--model-name`，AI 不要凭记忆缩写 |
+| 单引号 / 双引号在 PowerShell 里串起来字符乱了 | PowerShell 双引号会展开 `$` 与单引号字面量 | 外层用单引号，内层 Python 字面量保留双引号；复杂 JSON 走 `--params (Get-Content .\x.json -Raw)` |
+| Trae 国际版装了 skill，国内版没看到 | 两版**互不共享** SKILL 目录（`~/.trae` vs `~/.trae-cn`） | `vps-work skill install --agent trae,trae-cn` 同时装；或 `--agent all` |
+| `~/.cursor/skills/...` 与新版包不一致 | 升级后未重新铺设 | `vps-work skill update`（覆盖式重同步全部公开 skill） |
+| 用了 Bearer 后 `auth status` 显示的是机器人不是自己 | Bearer 优先级高于 session | 取消 `$env:VERTU_BOT_INBOUND_KEY` 或换新 shell |
+| 项目级 `.cursor/rules/*.mdc` / `AGENTS.md` 没收到 skill | 当前 vps-work 仅覆盖**用户级**目录 | 项目级整合需求请提 issue，暂未支持 |
+
+## 10. 关联
+
+- **vps-work 仓库与 issue**：https://gitee.com/he-linyan/vps-cli
+- **CLI 网关后端契约**：`vertu-erp/vertu_addons/ai_cli/README.md`（HTTP 路由、auth、execute payload 形态）
+- **Skill 体系后端契约**：`vertu-erp/vertu_addons/ai_skills/README.md`（catalog / execute / skill_file / scripts 路由、frontmatter 规则、feedback 协议）
+- 装好后：`vps-work skill list` 看随包分发的公开 skill 全集；优先用专项 skill（如 `sale-performance-query`、`vps-im`），用 `vps-work <域> +…` 操作

package/skills/vps-work-onboard/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: vps-work-onboard
+version: 2.0.0
+description: "新机器安装 vps-work、登录，并把随包分发的公开 vps-* 业务 skill 铺到各 Agent 目录。触发词：装 vps-work、onboard、初始化 vps-work、装 Vertu skills。"
+metadata:
+  requires:
+    bins: ["vps-work"]
+---
+
+# vps-work 一键自举（agent 引导）
+
+## 何时使用
+
+新机器/新账号首次落地。**业务 skill 随 npm 包静态分发、完全公开**，无需登录即可安装。
+
+## Step 1 — Node 20+
+
+```bash
+node -v
+```
+
+## Step 2 — 安装 vps-work（装包后会自动铺公开 skill）
+
+```bash
+npx vps-work@latest install
+# 关闭自动铺设：加 --no-skills
+```
+
+## Step 3 — 安装/同步公开业务 skill 到各 Agent
+
+```bash
+vps-work skill list                         # 看公开 skill 全集
+vps-work skill install --all --agent all    # 铺到 cursor / claude-code / hermes 等
+```
+
+## Step 4 — 验证宿主凭证（取数需要）
+
+Agent / Bot / Hermes **禁止**执行账号密码登录、索取密码或把密码写入 Prompt/命令。Hermes 宿主必须注入 `app_id=vertu-hermes-agent` 对应的 app_key：
+
+```bash
+vps-work auth status
+```
+
+若凭证无效，停止并提示人工管理员刷新。`vps-work auth login` 仅供人工用户在交互终端使用。
+
+## Step 5 — 自检
+
+```bash
+vps-work --help            # 命令树内置固定
+vps-work skill list
+```
+
+日常同步：`vps-work skill update`（覆盖式重同步全部公开 skill）。