vps-work 1.0.0

package/skills/vps-hr-compensation-documents/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: vps-hr-compensation-documents
+description: |
+  员工月度工资条只读查询（VPS 原生 HR，vps_tenant_payslips）。本人可查本人已发放工资条，企业管理员可查本企业成员。取数通过 `vps-work hr +payslip`。
+metadata:
+  requires:
+    bins: ["vps-work"]
+  cliHelp: "vps-work hr --help"
+---
+
+# 员工工资条
+
+**CRITICAL — 读取 [`references/runtime-and-helpers.md`](references/runtime-and-helpers.md)**。
+
+## 命令
+
+| 想做什么 | 快捷命令 | 数据源 |
+|----------|----------|--------|
+| 月工资条 | `vps-work hr +payslip --salary-month YYYY-MM` | VPS 原生 `vps_tenant_payslips`（已发放） |
+
+员工定位：`--my` 查本人；`--employee-id` 用 `vps-work hr +me` / `hr +personnel-info` 返回的 `employee_id`；`--name` 需在本企业内唯一。
+
+```bash
+vps-work hr +payslip --my --salary-month 2026-04
+vps-work hr +payslip --employee-id 4726 --salary-month 2026-04-01
+vps-work hr +payslip --name "孔健" --salary-month 2026-04
+```
+
+共用：`--name` / `--employee-id` / `--my` 三选一；`--base-url` 指向目标 vps-service。
+
+## 硬约束
+
+- 工资条只来自 VPS 原生 HR，**不再**读取 Odoo `employee.salary` / `human.resource.salary`，也不要走 `vps-work odoo` 通道查工资
+- 只返回 `status=published` 的工资条；草稿、已撤回不可见
+- 查他人需要企业管理员（owner / manager）身份，否则服务端返回 403，不要绕行
+- 取数走 CLI 封装：`vps-work hr +payslip`，不要自行拼 SQL 或调用其它接口
+- 禁止 `skills/**/scripts/*.py`
+
+返回字段见 [`reference.md`](reference.md)。
+
+## 关联技能
+
+- **vps-hr** — 身份、档案、组织架构
+- **vps-pending-approval-assistant** — 薪酬相关审批的轨迹与待办
+
+---
+
+## Feedback protocol (mandatory before answering)
+
+```
+POST /ai/skills/v1/feedback
+{
+  "skill_key": 'vps-hr-compensation-documents',
+  "severity": 'warn',
+  "tag": 'detour',
+  "summary": '<one-liner>',
+  "proposed_fix": '<SKILL.md / references/*.md>'
+}
+```
+
+发现口径或参数问题时，直接更新对应 skill/reference 文档。

package/skills/vps-hr-compensation-documents/reference.md

@@ -0,0 +1,68 @@
+# reference.md — 工资条（VPS 原生 HR）
+
+路由与 CLI 示例优先见 **`references/+payslip.md`** 与 **`SKILL.md`**。
+
+## 1. 数据来源
+
+工资条由企业管理员在 VPS「工资条」应用中按月录入、发布，落在 VPS 原生表 `vps_tenant_payslips`（按企业 tenant 隔离，RLS 强制）。
+`vps-work hr +payslip` → vps-service `POST /v1/execute`（`skill_key=vps-hr-compensation-documents`，`script_key=payslip`）→ 原生表。
+不再依赖 Odoo `vt_salary` 模块。
+
+## 2. 访问规则
+
+| 查询对象 | 要求 |
+|----------|------|
+| 本人（`--my` 或不指定） | 任意企业成员 |
+| 他人（`--employee-id` / `--name`） | 企业管理员（`membership_role` 为 owner / manager） |
+
+只返回 `status = published` 的工资条；草稿 / 已撤回对成员不可见。服务级 API Key 无企业上下文，返回 403。
+
+## 3. 参数
+
+| 参数 | 说明 |
+|------|------|
+| `salary_month` | `YYYY-MM` 或 `YYYY-MM-DD`，统一按月归一 |
+| `my` | `true` 时查本人 |
+| `employee_id` | 本企业员工号：内部企业为 Odoo 兼容员工号，外部企业为 VPS 分配号；来源 `hr +me` / `hr +personnel-info` |
+| `name` | 姓名，需在本企业成员中唯一，否则 409，请改用 `employee_id` |
+
+## 4. 返回结构
+
+```json
+{
+  "source": "vps-service",
+  "data_source": "vps-native-payslips",
+  "salary_month": "2026-04-01",
+  "employee": "孔健",
+  "employee_id": 4726,
+  "rows": [
+    {
+      "salary_month": "2026-04",
+      "employee": "孔健",
+      "department": "线下事业部",
+      "total_payable": "18000.00",
+      "actual_salary": "15230.50",
+      "items": [{ "name": "基本工资", "amount": "12000.00", "section": "应发" }],
+      "amounts": { "total_payable": "18000.00", "actual_salary": "15230.50" },
+      "note": "",
+      "status": "published",
+      "published_at": "2026-05-08T02:00:00.000Z",
+      "confirmed_at": null
+    }
+  ],
+  "notes": []
+}
+```
+
+`rows` 为空时 `notes` 给出 `Empty result: 该月没有已发放的工资条。`；`items` 为应发/扣款明细数组，`amounts` 为按字段 key 展开的金额映射。
+
+## 5. 常见错误
+
+| 状态 | 含义 |
+|------|------|
+| 400 | `salary_month` 格式错误 |
+| 403 | 查他人但非企业管理员；或当前会话无企业身份 |
+| 404 | `employee_id` / `name` 未匹配到企业成员 |
+| 409 | `name` 匹配多人 |
+
+缺口 → `POST /ai/skills/v1/feedback`。

package/skills/vps-hr-compensation-documents/references/+payslip.md

@@ -0,0 +1,29 @@
+# +payslip（工资条）
+
+数据源 **VPS 原生 `vps_tenant_payslips`**（员工 × 月一条，仅已发放）。
+
+## 何时用
+
+- 某月应发 / 实发 / 明细 / 发放与确认状态
+- **不要**再查 Odoo `employee.salary` / `human.resource.salary`
+
+## 关键字段
+
+`salary_month`（`YYYY-MM`）、`total_payable`、`actual_salary`、`items[]`（明细）、`status`（published）、`published_at`、`confirmed_at`。
+
+## CLI（推荐快捷命令）
+
+```bash
+# 本人工资条（--salary-month 可写 2026-04，自动归一到当月）
+vps-work hr +payslip --my --salary-month 2026-04
+
+# 企业管理员查成员
+vps-work hr +payslip --employee-id 4726 --salary-month 2026-04-01
+vps-work hr +payslip --name "孔健" --salary-month 2026-04
+```
+
+无行时先确认该月工资条是否已发布；403 表示无权查他人，不要绕行。
+
+## 员工定位
+
+用 `vps-work hr +me` 取本人 `employee_id`，或用 `hr +personnel-info` 查到目标 `employee_id`。

package/skills/vps-hr-compensation-documents/references/runtime-and-helpers.md

@@ -0,0 +1,24 @@
+# 运行时（工资条）
+
+## 数据路径
+
+本 skill 查数统一走 **`vps-work hr +payslip`** → vps-service `execute(vps-hr-compensation-documents/payslip)` → VPS 原生 `vps_tenant_payslips`。
+访问控制在服务端：本人可查；查他人需企业管理员。
+
+## 仓库约束
+
+- 仅 `SKILL.md` + `references/+payslip.md` + `reference.md`；**禁止** `scripts/*.py`。
+- 字段不确定 → 读本 skill `reference.md` / `references/+payslip.md`。
+
+## 快捷命令一览
+
+| 需求 | 命令 |
+|------|------|
+| 定位员工 | `vps-work hr +me`（本人）或 `hr +personnel-info` 取 `employee_id` |
+| 月工资条 | `vps-work hr +payslip --my --salary-month YYYY-MM` |
+
+契约细节见同目录 [`+payslip.md`](+payslip.md)。
+
+## 勿混淆
+
+- 工资条数据在 VPS 原生 HR，与 Odoo 薪酬模块（`vt_salary`）无关；Odoo 现为第三方应用，只承载销售 / 商品 / 审批等业务数据。

package/skills/vps-im/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: vps-im
+version: 1.2.0
+description: "Vertu IM：读取与发送消息、下载会话图片/附件原文件、私聊/群聊/组织群、员工 VPS Harness Agent 互相请求或以机器人身份联系人、群发、撤回、互动卡片、群成员管理、机器人、语音视频通话。当用户需要查看会话列表、读历史消息、获取或下载聊天图片/附件、监听新消息、让另一名员工的 Harness Agent 协作、让自己的 Harness Agent 联系员工、给某人或某群发消息、群发通知、发审批卡片、撤回、建群拉人、管理机器人或发起通话时使用。入口 `vps-work im +…`、`vps-work agent ask` 与 `vps-work agent message-user`。触发词：聊天图片、聊天附件、附件下载、Agent 协作、员工 Agent、机器人私聊、发消息、私聊、群聊、群发、通知、撤回、会话、历史消息、监听、机器人、语音通话、视频通话、IM。"
+metadata:
+  requires:
+    bins: ["vps-work"]
+  cliHelp: "vps-work im --help"
+---
+
+# im（Vertu IM）
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../vps-shared/SKILL.md`](../vps-shared/SKILL.md)，其中包含认证、当前用户与 `+` 快捷约定。**
+
+IM 走 Vertu 原生通讯能力，与主登录共用同一份会话/agent key，无需单独登录任何端点。Agent 模式下注入 `VERTU_APP_ID` / `VERTU_APP_KEY` / `VERTU_USER_LOGIN` 即可读写消息。所有命令默认输出 JSON，便于解析。
+
+## 典型流程
+
+1. 找人/会话：`+me` 看自己身份 → `+users` 搜组织成员拿 `user_id` → `+channels` 拿会话 `channel_id`。
+2. 读消息：`+history`（历史）/ `+sync`（按游标增量）/ `+watch`（持续轮询推送）。
+3. 发消息：`+send`（已知 channel）/ `+send-user`（只知道对方 user_id，自动建私聊）/ `+broadcast`（群发）。
+
+## Shortcuts（推荐优先使用）
+
+### 读取消息 → [`references/vps-im-read.md`](references/vps-im-read.md)
+
+| Shortcut | 说明 |
+|----------|------|
+| `+me` | 当前 IM 身份 |
+| `+users` | 按姓名/工号/登录名/部门搜组织成员 |
+| `+departments` | 组织部门树；默认一级/二级，`--max-depth 0` 查看全量 |
+| `+channels` | 我的会话列表 |
+| `+history` | 查本人所在会话的消息历史（时间区间、关键字、分页） |
+| `+all-chat-records` | 凭独立权限按必填日期区间分页查询全域聊天记录 |
+| `+attachments` | 凭独立附件权限按发送人精确查询最近附件，不读取聊天正文 |
+| `+attachment-content` | 凭独立附件权限并记录访问事由，把已知聊天附件解析为 Markdown |
+| `+attachment-download` | 下载本人有权访问的会话图片或附件原文件，不覆盖已有文件 |
+| `+sync` | 按游标拉取增量事件（拉一次） |
+| `+watch` | 持续轮询增量事件，命令行实时推送 |
+
+### 发送与互动 → [`references/vps-im-send.md`](references/vps-im-send.md)
+
+| Shortcut | 说明 |
+|----------|------|
+| `+send` | 向指定会话发消息（文本/富文本/附件） |
+| `+send-user` | 给某人发消息（自动创建/复用私聊） |
+| `+agent-notify` | 专家智能体主动消息；默认 auto，有 `channel_id` 写入 IM，否则回退 Hermes session |
+| `+broadcast` | 群发（按 user_ids 或部门路径） |
+| `+send-approval-card` | 发送审批类互动卡片 |
+| `+revoke` | 撤回消息 |
+| `+interact` | 对消息执行互动：表情/审批按钮/卡片按钮/确认 |
+
+### 会话与成员 → [`references/vps-im-channels.md`](references/vps-im-channels.md)
+
+| Shortcut | 说明 |
+|----------|------|
+| `+chat` | 获取或创建私聊 |
+| `+create-group` | 创建群聊 |
+| `+create-org-group` | 按组织架构创建群聊 |
+| `+channel-update` | 更新群名/头像/公告（乐观锁 `--expected-version`） |
+| `+add-members` / `+set-role` / `+remove-member` | 成员增删与角色调整 |
+
+### 机器人 → [`references/vps-im-bots.md`](references/vps-im-bots.md)
+
+| Shortcut | 说明 |
+|----------|------|
+| `+bots` / `+bot-channels` / `+bot-create` / `+bot-update` / `+add-bot` | 机器人列表 / 所在群 / 创建 / 公开范围 / 加入普通群或组织群 |
+| `+bot-send-user` | 以自己名下的指定机器人身份给员工发起私聊；支持正文和附件 |
+
+### 语音视频通话 → [`references/vps-im-calls.md`](references/vps-im-calls.md)
+
+| Shortcut | 说明 |
+|----------|------|
+| `+call-start` / `+call-join` / `+call-leave` / `+call-end` | 通话生命周期 |
+| `+call-signal` / `+call-signals` | WebRTC 信令发送 / 拉取 |
+
+共享参数（正文、附件、幂等、user_id 列表）见 [`references/vps-im-shared-params.md`](references/vps-im-shared-params.md)。
+
+## 专家智能体主动消息
+
+当 Hermes 专家需要把结论、提醒、后续进度主动发送到“添加专家智能体并进行对话”的当前会话时，使用：
+
+```bash
+vps-work im +agent-notify --body "要发送给用户的内容"
+```
+
+如果当前运行环境没有自动注入 `VERTU_AGENT_SLUG` / `VERTU_AGENT_ODOO_USER_ID`，必须显式传当前运行上下文中的参数：
+
+```bash
+vps-work im +agent-notify --target auto \
+  --agent-slug "<当前专家 agent_slug>" \
+  --user-id "<当前用户 odoo_user_id>" \
+  --session-id "<当前 Hermes session_id>" \
+  --channel-id "<自动补齐或已绑定的 IM channel_id>" \
+  --hermes-base-url "<Hermes Agent Admin URL，如 http://127.0.0.1:5175>" \
+  --body "要发送给用户的内容"
+```
+
+不要直接调用 webhook。默认 `--target auto`：运行环境存在 `VERTU_AGENT_CHANNEL_ID` 或显式 `--channel-id` 时主写统一 IM 会话，并在迁移期镜像追加到当前 Hermes `session_id`，保证旧专家聊天页仍可读取；cron / 无头环境必须显式带 `--channel-id` 和 `--hermes-base-url`，不要依赖环境变量。没有 channel 时回退追加到 `agent_chat_sessions / agent_chat_messages`。迁移期老会话缺少 `im_channel_id` 时，后端会按 `user_id + agent_slug` 自动创建/复用专家 IM 会话并补齐。有稳定业务事件时才显式传 `--event-id`。
+
+## 员工 VPS Harness Agent 协作
+
+先用 `vps-work im +users --query "姓名或工号"` 获取对方 `user_id`，再发起一次请求并等待答复：
+
+```bash
+vps-work agent ask --user-id 12708 --message "请核对今天的项目进展并给出三个风险点"
+```
+
+长请求可用 `--message @request.md`。不指定截止时间时是一问一答；需要双方循环推进时，指定截止时间或持续分钟数：
+
+```bash
+vps-work agent ask --user-id 12708 --message @request.md --stop-at "2026-08-21T18:00:00+08:00"
+vps-work agent ask --user-id 12708 --message @request.md --duration-minutes 30
+```
+
+服务端会为双方创建真实的 Harness Bot 身份和一个稳定的机器人协作会话；会话列表显示“员工 A · VPS Harness ↔ 员工 B · VPS Harness”，消息使用 `sender_type=bot`，不会混入员工私聊。截止前每轮答复会触发对方下一轮，截止后的下一条答复自动结束循环。命令收到对方首轮答复后会立即返回给当前 Agent，后续循环由双方桌面端在后台继续；`--timeout` 只控制等待首轮答复的时间。对方必须在线，并已在 VPS Harness 设置中开启“允许其他员工的 VPS Harness Agent 联系我”。普通聊天不会触发 Harness。
+
+需要让当前用户的 Harness Agent 直接联系一名员工时，使用：
+
+```bash
+vps-work agent message-user --user-id 12708 --message "请确认今天 16:00 的评审是否可以参加"
+```
+
+该命令以当前用户的真实 VPS Harness Bot 身份创建或复用与对方的机器人私聊，并立即返回 `channel_id`。对方作为普通员工直接在会话中回复；当前用户桌面端开启 Agent 联系开关时，会由设置中选定的 Agent Preset 接管并回复。每条员工回复只触发一次，不会自动形成机器人循环。长消息同样支持 `--message @file`。
+
+## 通用机器人与员工私聊
+
+任意当前用户自己创建的机器人都可以主动联系员工，不限于 VPS Harness：
+
+```bash
+vps-work im +bots
+vps-work im +bot-send-user --app-id vbot_xxx --user-id 12708 --body "请提交今日销售数据"
+vps-work im +bot-send-user --app-id vbot_xxx --user-id 12708 --body "请查收附件" --attach ./通知.pdf
+```
+
+命令复用当前登录会话或 Agent Key，只允许使用自己的机器人，不需要也不应传 App Secret。服务端会创建或复用该机器人和员工的 `bot_dm`。员工的每条回复都会产生 `direct` 机器人事件：配置了 webhook 的机器人会收到回调，启用了内置 Agent 的机器人由 Agent 处理。通用机器人不会使用 VPS Harness 的开关或 Agent Preset。
+
+## Skill Resources
+
+```bash
+vps-work im --help
+vps-work im +channels --help
+vps-work auth status        # 期望 logged_in=true；401 见 vps-work skill §2.2
+```
+
+## 权限与限制
+
+| 项 | 说明 |
+|----|------|
+| 鉴权 | 与主登录共用 Vertu 会话/agent key，无需单独登录 IM |
+| 全域聊天记录 | `+all-chat-records` 必须显式拥有 `im.messages.all:read`，管理员身份不自动放行 |
+| 全域附件内容 | 仅 `vertu-hermes-agent` 可调用；只需独立的 `im.attachments.all:read` 并传 `access_reason`，不要求 `im.messages.all:read` |
+| 发送幂等 | `--client-message-id` / `--idempotency-key` 默认自动生成 UUID，可安全重试 |
+| 未封装能力 | 个人资料、会话设置/免打扰、收藏、语音转写凭证、文件上传等服务端已有但 CLI 暂无 `+` 入口，需要时走桌面端或提需求 |

package/skills/vps-im/references/vps-im-bots.md

@@ -0,0 +1,25 @@
+# 机器人
+
+| Shortcut | 独有参数 | 说明 |
+|----------|----------|------|
+| `+bots` | `--include-public` | 查询自己的机器人；可同时查询其他人的公开机器人 |
+| `+bot-channels` | — | 使用当前登录身份查询名下全部机器人所在群及群 ID |
+| `+bot-send-user` | `--app-id` `--user-id`，以及正文/附件公共参数 | 以自己名下的指定机器人身份发起或继续员工私聊 |
+| `+bot-create` | `--name`(必填) `--description` `--webhook-url` `--public` | 创建 IM 机器人，可直接设为公开 |
+| `+bot-update` | `--app-id`(必填) `--public` 或 `--private` | 更新机器人公开范围 |
+| `+add-bot` | `--channel-id` `--app-id` | 把自己的机器人或他人的公开机器人加入普通群、部门群或全员群 |
+
+## 示例
+
+```bash
+vps-work im +bots
+vps-work im +bot-channels
+vps-work im +bot-send-user --app-id vbot_xxx --user-id 12708 --body "请提交今日销售数据"
+vps-work im +bot-send-user --app-id vbot_xxx --user-id 12708 --body "请查收" --attach ./通知.pdf
+vps-work im +bots --include-public
+vps-work im +bot-create --name 销售播报 --webhook-url https://example.com/hook --public
+vps-work im +bot-update --app-id vbot_xxx --public
+vps-work im +add-bot --channel-id 1024 --app-id vbot_xxx
+```
+
+`+bot-channels` 不需要 App ID 或 App Secret，返回机器人 App ID/名称、群 ID、群名称、群类型、部门路径和加入时间。`+bot-send-user` 使用当前登录身份或 Agent Key 校验机器人所有权，不暴露 App Secret；对方回复会以 `direct` 事件投递给机器人的 webhook 或内置 Agent。添加他人的机器人前，机器人所有者必须先将其设为公开。机器人加入会话后，可通过用户机器人推送接口发送结构化消息。

package/skills/vps-im/references/vps-im-calls.md

@@ -0,0 +1,28 @@
+# 语音视频通话
+
+支持 1v1 与群通话，信令走 WebRTC。
+
+## 生命周期
+
+| Shortcut | 独有参数 | 说明 |
+|----------|----------|------|
+| `+call-start` | `--channel-id`(必填) `--call-type`(audio) `--user-ids` `--title` `--device-id` `--audio-enabled`(true) `--video-enabled`(false) `--metadata-json` | 发起；省略 `--user-ids` 则邀请会话内全员 |
+| `+call-join` | `--call-id`(必填) `--device-id` `--audio-enabled`(true) `--video-enabled`(false) | 加入 |
+| `+call-leave` | `--call-id`(必填) `--status`(left) | 离开/拒绝，状态 ∈ `left`/`declined`/`failed` |
+| `+call-end` | `--call-id`(必填) `--status`(ended) `--reason` | 结束，状态 ∈ `ended`/`cancelled`/`missed`/`failed` |
+
+## 信令
+
+| Shortcut | 独有参数 | 说明 |
+|----------|----------|------|
+| `+call-signal` | `--call-id`(必填) `--signal-type`(必填) `--recipient-user-id` `--payload-json` `--client-signal-id` | 发送信令；`--signal-type` ∈ offer/answer/ice_candidate/heartbeat 等；省略 recipient 即广播 |
+| `+call-signals` | `--call-id`(必填) `--cursor` `--limit`(100) | 按 created_at 游标拉取信令 |
+
+## 示例
+
+```bash
+vps-work im +call-start --channel-id 1024 --call-type video --title "需求评审"
+vps-work im +call-join --call-id 555 --video-enabled
+vps-work im +call-signals --call-id 555 --limit 50
+vps-work im +call-end --call-id 555 --status ended --reason 会议结束
+```

package/skills/vps-im/references/vps-im-channels.md

@@ -0,0 +1,32 @@
+# 会话与成员
+
+`--user-ids` 列表格式见 [`vps-im-shared-params.md`](vps-im-shared-params.md)。
+
+## 创建/获取会话
+
+| Shortcut | 独有参数 | 说明 |
+|----------|----------|------|
+| `+chat` | `--user-id`(必填) | 获取或复用与某人的私聊 |
+| `+create-group` | `--name`(必填) `--user-ids`(必填) `--description` | 创建群聊 |
+| `+create-org-group` | `--department-path`(必填) `--name` `--include-children`(true) | 按组织架构建群 |
+| `+channel-update` | `--channel-id`(必填) `--name` `--description` `--avatar-url` `--announcement` `--group-nature` `--expected-version` | 改群资料；`--group-nature daily_report`/`日报群` 仅群创建者可设置，传空字符串取消日报群，已是其他性质的群不可修改；`--expected-version` 为乐观锁版本号 |
+
+## 成员管理
+
+| Shortcut | 独有参数 | 说明 |
+|----------|----------|------|
+| `+add-members` | `--channel-id` `--user-ids` | 添加群成员 |
+| `+set-role` | `--channel-id` `--user-id` `--role` | 角色 ∈ `owner`/`admin`/`member` |
+| `+remove-member` | `--channel-id` `--user-id` | 移除成员 |
+
+## 示例
+
+```bash
+vps-work im +chat --user-id 88
+vps-work im +create-group --name "Q3 项目组" --user-ids 12,34,56 --description "Q3 推进"
+vps-work im +create-org-group --department-path 销售中心/华东大区 --name 华东全员
+vps-work im +channel-update --channel-id 1024 --group-nature daily_report
+vps-work im +channel-update --channel-id 1024 --group-nature ""
+vps-work im +add-members --channel-id 1024 --user-ids 77,78
+vps-work im +set-role --channel-id 1024 --user-id 77 --role admin
+```

package/skills/vps-im/references/vps-im-read.md

@@ -0,0 +1,105 @@
+# 读取消息
+
+定位人/会话，再读历史或监听增量。
+
+## +me / +users / +channels
+
+| Shortcut | 独有参数 | 说明 |
+|----------|----------|------|
+| `+me` | — | 当前 IM 身份（user/employee 等） |
+| `+users` | `--query` `--department-path` `--include-children` `--limit`(30) | 搜组织成员拿 `user_id` |
+| `+channels` | `--limit`(50) | 我的会话列表，拿 `channel_id` |
+
+`+users` 的人员记录还包含 `employment_started_at`（Odoo 入职日期换算的上海时区起始边界）和
+`employment_ended_at`（Odoo 离职日期换算的就业有效期结束边界；仍在职时为 `null`），均为 ISO 8601，
+不代表真实事件发生时刻。
+
+## +history（历史消息）
+
+| CLI | 默认 | 说明 |
+|-----|------|------|
+| `--channel-id <id>` | 必填 | 会话 id |
+| `--date-from` / `--date-to <iso>` | — | 时间区间 |
+| `--keyword <text>` | — | 正文关键字 |
+| `--limit <n>` | 50 | 数量 |
+| `--offset <n>` | — | 分页偏移 |
+
+## +all-chat-records（全域聊天审计）
+
+该命令与普通 `+history` 完全隔离，仅用于获得独立权限的审计人员。必须显式拥有
+`im.messages.all:read`；管理员身份本身不会自动获得此权限。返回原始服务端记录，包含已撤回标记，
+不应用任一用户的“清空记录”或“删除会话”视图过滤。
+
+| CLI | 默认 | 说明 |
+|-----|------|------|
+| `--start-date <ymd>` | 必填 | 起始日期，YYYY-MM-DD，中国时区自然日 |
+| `--end-date <ymd>` | 必填 | 结束日期，YYYY-MM-DD；区间最多 31 天 |
+| `--page <n>` | 必填 | 页码，从 1 开始 |
+| `--page-size <n>` | 必填 | 每页条数，1-100 |
+
+## +attachment-content（审计附件转 Markdown）
+
+适用于复核、调查、合规检查、业务分析等有明确事由的授权场景。调用方必须是 `vertu-hermes-agent`，只需独立的
+`im.attachments.all:read`，不要求 `im.messages.all:read`。服务端复用 Agent 上传文件的解析流程：
+文本直接读取，PDF、Office、HTML 与图片通过 MinerU 转换为 Markdown。每次准备和读取都会记录
+`access_reason`、附件、消息、频道和文档状态。
+
+| CLI | 默认 | 说明 |
+|-----|------|------|
+| `--attachment-id <id>` | 必填 | `+all-chat-records` 返回的 `attachments[].id` |
+| `--access-reason <text>` | 必填 | 本次读取附件内容的具体业务事由 |
+| `--wait-seconds <n>` | 120 | 等待解析完成；0 表示只发起解析，最大 900 |
+| `--poll-interval-ms <n>` | 2000 | 轮询间隔，500-10000 |
+
+不要保存 MinerU 或 OSS 的临时签名 URL。命令输出包含来源消息、发送人、附件元数据、解析状态及
+`content` Markdown；超长内容会设置 `content_truncated: true`。
+
+该权限只负责读取已知 `attachment_id`。如需通过 `+all-chat-records` 在全域聊天中发现附件，消息列表查询仍需
+独立的 `im.messages.all:read`。
+
+也可以使用同一附件权限通过 `+attachments` 按发送人姓名精确查询最近附件，不读取聊天正文：
+
+```bash
+vps-work im +attachments --sender-name "温若琪" --limit 20 --access-reason "检查温若琪最近的附件"
+```
+
+## +attachment-download（下载会话附件原文件）
+
+下载当前账号有权访问的聊天图片或附件。普通账号必须是附件所在会话的成员；命令不会绕过服务端权限校验，
+也不会覆盖已存在的本地文件。`--output` 应放在当前 Harness 工作区或其临时目录内，避免被文件沙箱拒绝。
+
+从 `+history` 结果的 `attachments[]` 取 `url` 或 `storage_key`，二选一：
+
+```bash
+vps-work im +attachment-download \
+  --url "/v1/im/files/im/2026/08/example.png" \
+  --output "./downloads/example.png"
+
+vps-work im +attachment-download \
+  --storage-key "im/2026/08/example.pdf" \
+  --output "./downloads/example.pdf"
+```
+
+该命令下载原始字节；需要读取 PDF、Office 或图片中的文字时，使用具有独立审计权限的
+`+attachment-content`。全域审计附件的原文件下载不由此命令扩大授权。
+
+## +sync / +watch（增量事件）
+
+按游标拉取 IM 增量事件（新消息、撤回、成员变更等）。返回体含 `next_cursor`，下次带上即可续拉。
+
+| Shortcut | 独有参数 | 说明 |
+|----------|----------|------|
+| `+sync` | `--cursor`(0) `--limit`(100) | 拉一次 |
+| `+watch` | `--cursor`(0) `--limit`(100) `--interval-ms`(3000) `--once` | 持续轮询，自动推进游标；`--once` 等价单次 |
+
+## 示例
+
+```bash
+vps-work im +channels --limit 20
+vps-work im +users --query 张伟 --limit 5
+vps-work im +history --channel-id 1024 --limit 30 --keyword 报价
+vps-work im +all-chat-records --start-date 2026-07-01 --end-date 2026-07-15 --page 1 --page-size 50
+vps-work im +attachment-content --attachment-id <uuid> --access-reason "检查温若琪最近的合同附件"
+vps-work im +watch --cursor 0 --interval-ms 3000      # 命令行实时收消息
+vps-work im +sync --cursor 8830 --once                # 拉一批增量后退出
+```

package/skills/vps-im/references/vps-im-send.md

@@ -0,0 +1,57 @@
+# 发送与互动
+
+正文/附件/幂等等共享参数见 [`vps-im-shared-params.md`](vps-im-shared-params.md)。
+
+## +send（已知会话）
+
+| CLI | 说明 |
+|-----|------|
+| `--channel-id <id>` | 必填，会话 id |
+| 正文/附件/幂等 | 见共享参数 |
+
+## +send-user（只知道对方）
+
+| CLI | 说明 |
+|-----|------|
+| `--user-id <id>` | 必填，对方 user_id；自动创建/复用私聊后发送 |
+| 正文/附件/幂等 | 见共享参数 |
+
+## +broadcast（群发）
+
+收件人二选一：显式 `--user-ids`，或按 `--department-path` 部门群发。
+
+| CLI | 默认 | 说明 |
+|-----|------|------|
+| `--user-ids <list>` | — | 收件人 user_id 列表 |
+| `--department-path <path>` | — | 按部门路径群发 |
+| `--include-children` | true | 部门含子部门 |
+| `--name <text>` | — | 群发会话名称 |
+| `--limit <n>` | 1000 | 部门群发人数上限 |
+
+## +send-approval-card（审批卡片）
+
+| CLI | 说明 |
+|-----|------|
+| `--channel-id <id>` | 必填 |
+| `--title <text>` | 必填，审批标题 |
+| `--summary <text>` | 审批摘要 |
+| `--approval-id <id>` | 外部审批单 id |
+| `--actions-json <json>` | 按钮动作数组；默认 `[同意, 拒绝]` |
+
+## +revoke / +interact
+
+| Shortcut | 独有参数 | 说明 |
+|----------|----------|------|
+| `+revoke` | `--channel-id` `--message-id` | 撤回消息 |
+| `+interact` | `--channel-id` `--message-id` `--interaction-type` `--value` `--metadata-json` | 互动类型 ∈ `reaction`/`approval_action`/`card_action`/`ack`，`--value` 如 `approve`/`reject`/`👍` |
+
+## 示例
+
+```bash
+vps-work im +send --channel-id 1024 --body "今天的报价已更新"
+vps-work im +send-user --user-id 88 --body "请查收附件" --attach ./quote.pdf
+vps-work im +broadcast --department-path 销售中心/华东大区 --body "周会改到 15:00"
+vps-work im +send-approval-card --channel-id 1024 --title "差旅报销 ¥1200" --approval-id EXP-2026-001
+vps-work im +interact --channel-id 1024 --message-id 99 --interaction-type approval_action --value approve
+vps-work im +revoke --channel-id 1024 --message-id 99
+```

package/skills/vps-im/references/vps-im-shared-params.md

@@ -0,0 +1,42 @@
+# IM 共享参数
+
+`vps-work im +…` 多个 Shortcut 共用下列参数（execute/HTTP 侧为 snake_case）。
+
+## 消息正文（发送类共用）
+
+发送类（`+send` / `+send-user` / `+broadcast` / `+send-approval-card`）共用：
+
+| CLI | 说明 |
+|-----|------|
+| `--body <text>` | 消息正文 |
+| `--body-file <path>` | 从文件读正文；`-` 表示 stdin；`@file` 表示展开文件 token |
+| `--message-type <type>` | `text` / `rich_text` / `image` / `file` / `audio` / `video` / `link` / `emoji` |
+| `--parent-message-id <id>` | 回复某条消息 |
+| `--quote-message-id <id>` | 引用某条消息 |
+| `--metadata-json <json>` | 消息 metadata JSON 对象 |
+
+正文与附件至少提供其一，否则报错。
+
+## 附件
+
+| CLI | 说明 |
+|-----|------|
+| `--attach <path>` | 本地文件，可重复；自动算 mime/sha256，base64 入 metadata |
+| `--attachments-json <json>` | 附件 JSON 数组；每项必含 `name`，`attachment_type` ∈ image/file/audio/video/link/emoji/other |
+
+## 幂等（发送类共用）
+
+| CLI | 说明 |
+|-----|------|
+| `--client-message-id <id>` | 客户端消息 id，并发幂等；省略自动 UUID |
+| `--idempotency-key <key>` | 幂等键；省略复用 client-message-id |
+
+> 重试发送务必复用同一 `--client-message-id`，服务端据此去重，避免重复发送。
+
+## user_id 列表
+
+`--user-ids` 接受逗号分隔（`12,34,56`）或 JSON 数组（`[12,34]`），元素须为正整数。
+
+## 通用输出
+
+默认输出格式化 JSON；`--json false` 时尽量打印原始字符串。`--base-url <url>` 覆盖 Vertu 服务地址（通常不需要）。

package/skills/vps-mail/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: vps-mail
+version: 1.0.0
+description: 站内信发送。`vps-work mail +…`。
+metadata:
+  requires:
+    bins: ['vps-work']
+  cliHelp: 'vps-work mail --help'
+---
+
+# mail
+
+**MUST Read [`../vps-shared/SKILL.md`](../vps-shared/SKILL.md)**
+
+| Shortcut | 契约 |
+|----------|------|
+| `+send` | 见 `vps-work mail --help`（Vertu 原生 IM 私聊发送） |