vps-work 1.0.0

package/USAGE.md

@@ -0,0 +1,289 @@
+# vps-work 用户使用手册
+
+版本：随 `vps-work` 当前 npm 包。本包取代已弃用的 `vertu-cli`。
+
+---
+
+## 一、安装前提
+
+确保已安装 **Node.js 20 或更高版本**：
+
+```bash
+node -v   # 输出应为 v20.x.x 或更高
+```
+
+---
+
+## 二、安装
+
+```bash
+npx vps-work@latest install
+# 或：npm install -g vps-work@latest
+```
+
+装包后会**自动**把公开 skill 铺到本机已检测到的 Agent 目录（`~/.cursor/skills` 等）；不需要可传：
+
+```bash
+npx vps-work@latest install --no-skills
+```
+
+验证：
+
+```bash
+vps-work --version
+vps-work --help
+```
+
+### keytar 编译失败？
+
+```bash
+npm install -g vps-work --no-optional
+```
+
+未装 keytar 时会自动用 `~/.vps-work/config.json` 存会话，功能一致。
+
+---
+
+## 三、登录与身份
+
+业务取数需要有效凭证。以下账号密码登录仅供人工用户在交互终端执行；Agent / Bot / Hermes 必须使用宿主注入的 app_key，不得执行登录命令或接触用户密码。Hermes 固定使用 `app_id=vertu-hermes-agent`。
+
+```bash
+vps-work auth login
+vps-work auth login --login your@email.com --password '***'
+
+vps-work auth status
+vps-work auth status --json   # 仅 uid / login 等极简字段
+vps-work hr +me               # 完整组织身份（部门链、上级等）
+vps-work hr +org-tree         # 组织结构，默认一级/二级部门
+vps-work hr +profile          # 本人人事档案、岗位、工龄、合同
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--service-url` | Vertu 服务地址；通常使用默认正式环境即可 |
+| `--login` / `--password` | 企业账号 |
+
+退出：
+
+```bash
+vps-work auth logout
+vps-work auth logout --forget
+```
+
+```bash
+vps-work auth tenants
+vps-work auth use --tenant <uuid>   # 仅人工/宿主；Agent 不得自行切换企业
+```
+
+> 遗留 Odoo 动态 CLI（`--legacy-odoo-cli`）仅供人工兼容排障。Agent / Bot / Hermes 禁止使用。
+
+---
+
+## 四、活目录与通用执行
+
+本机 `--help` 只反映已打包的 `+` 糖衣。当前企业身份能用哪些脚本，以服务端目录为准：
+
+```bash
+vps-work catalog --json
+vps-work catalog --domain sales --json
+vps-work exec --skill vps-dealer-ops --script sales --param period=this_month
+```
+
+`transport=execute` 的条目用 `exec`；不要编造 catalog 里没有的 `script_key`。
+
+条目的 `provider` 字段标明数据归属：`odoo` 表示来自第三方应用 Odoo ERP（销售 / 门店 / 商品 / 经销商运营 / 审批），为空表示 VPS 原生能力（HR 档案、工资条、IM、云文档等）。企业停用 Odoo ERP 后，响应中的 `disabled_third_party_apps` 会包含 `odoo`，相关条目被隐藏且 `exec` 返回 403。
+
+---
+
+## 五、常用命令（领域 `+` 快捷）
+
+命令树内置本机糖衣，用 `--help` 查看。服务端新增脚本不必等本机发版，优先走上一节 `catalog` / `exec`。
+
+```bash
+vps-work sales --help
+vps-work sales +headline-kpi
+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 sales +target-achievement --period this_month --okr-source postgres --limit 50 # 显式核对 Postgres 新目标表
+vps-work sales +dept-breakdown --period this_month --group-by salesperson --limit 10
+
+vps-work hr +me
+vps-work hr +org-tree --max-depth 2
+vps-work hr +profile
+vps-work hr +subordinates
+vps-work hr +manager
+vps-work hr +job-details --department-l1 "线下事业部" --job "销售"
+vps-work hr +contracts --contract-status open
+vps-work hr +payslip --name "张三" --salary-month 2026-04
+
+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 +business-list --kind business-policy
+vps-work corporate +regulation-list
+vps-work corporate +attachments --record-type regulation --record-id 53
+
+vps-work product +inventory --product-name "AGENT Q"
+vps-work product +inventory --product-subcategory "VERTU ALPHAFOLD" --product-material 小牛皮 --product-color 黑色 --group-by store_detail
+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
+# 上述三个设备异常命令只允许授权中心已分配 vps_device_abnormal_analyst 角色的在职内部员工访问
+vps-work attendance +daily --from-date 2026-08-01 --to-date 2026-08-25
+vps-work attendance +daily --from-date 2026-08-01 --to-date 2026-08-25 --managed-departments
+vps-work attendance +daily --from-date 2026-08-01 --to-date 2026-08-25 --employee-id 123
+vps-work attendance +daily --from-date 2026-08-01 --to-date 2026-08-25 --department-path "总部 / 研发"
+vps-work attendance +daily --from-date 2026-08-01 --to-date 2026-08-25 --all
+vps-work attendance +schedule-rules
+vps-work attendance +schedule-shifts --rule-id <rule-id> --availability all
+vps-work attendance +schedule-members --rule-id <rule-id> --from-date 2026-08-26 --to-date 2026-08-31
+vps-work attendance +schedules --rule-id <rule-id> --from-date 2026-08-26 --to-date 2026-08-31 --employee-id 123
+vps-work attendance +schedule-preview --rule-id <rule-id> --employee-ids 123,456 --from-date 2026-08-26 --to-date 2026-08-31 --shift-template-id <shift-id>
+vps-work attendance +schedule-apply --rule-id <rule-id> --items-file ./schedule-plan.json --mode fill_missing --preview-token <token> --client-request-id <uuid>
+vps-work creative +models --type image
+vps-work creative +image --model <id> --prompt "一只金丝猴在雪山上" --aspect-ratio 16:9
+vps-work creative +video --model <id> --prompt "..." --ratio 16:9 --duration 5 --wait
+vps-work creative +video-status --model <id> --task-id <task_id>
+vps-work creative +tts --model <id> --text "你好，欢迎使用"
+vps-work creative +music --model <id> --prompt "轻松愉快的爵士乐"
+vps-work calendar +mine --start-date 2026-07-20 --end-date 2026-07-26
+vps-work calendar +person --name "张三" --start-date 2026-07-23
+vps-work calendar +create --title "项目评审" --starts-at "2026-07-24 09:00" --ends-at "2026-07-24 10:00" --reminder-minutes 15m,1h
+vps-work calendar +update --event-id <uuid> --location "深圳办公室"
+vps-work calendar +respond --event-id <uuid> --status accepted
+vps-work calendar +calendars
+vps-work calendar +availability --user-ids 12708,12556 --start-date 2026-07-23
+vps-work drive +list --recursive
+vps-work drive +mkdir --name "项目资料"
+vps-work drive +upload --parent-id <uuid> --source ./方案.pdf
+vps-work drive +read --item-id <uuid>
+vps-work drive +download --item-id <uuid> --output ./downloads/
+vps-work popup +send --title "今日提醒" --content "还有 2 个待办即将到期。" --gradient-start "#FCEBE4" --gradient-end "#FFFBFA" --button-text "立即查看"
+vps-work popup +send --user-id 12708 --title "管理员提醒" --content "请及时查看新的工作安排。"
+vps-work im +departments --query "线上事业部"
+vps-work im +send-user --user-id 12708 --body '你好'
+vps-work im +history --channel-id <channel_id> --limit 20
+vps-work im +attachment-download --url "/v1/im/files/..." --output "./downloads/附件.png"
+vps-work tools +oss-upload --file ./report.pdf
+vps-work tools +oss-upload --file ./logo.png --visibility public
+```
+
+部门销售目标默认与管理端“部门业绩目标”页面一致，读取 `部门OKR_1`；需要核对 Postgres 新目标表时传 `--okr-source postgres`。个人 OKR 仍默认使用 Postgres。
+
+### 共享参数
+
+考勤日报日期为闭区间，单次最多 93 天，`--page-size` 最大 200。`--managed-departments`、`--employee-id`、`--department-path`、`--all` 互斥；都不提供时查询本人。部门负责人权限随组织同步自动变化，显式部门管理员授权可继续保留。
+
+排班短命令只提供授权范围内的规则、班次、人员与现有排班事实，不生成排班建议。智能体先调用 `+schedule-rules`、`+schedule-shifts` 和 `+schedule-members`/`+schedules` 获取决策材料，再用 `+schedule-preview` 校验计划并取得短期令牌，最后用完全相同的计划、令牌和唯一 `client_request_id` 调用 `+schedule-apply`。默认 `fill_missing` 不覆盖已有排班；只有明确传 `--mode replace` 才允许替换。一次应用全量成功或全量失败，历史日期仍走既有纠错流程。
+
+`--items-file` 内容是 JSON 数组；写入只接受查询接口返回的员工、规则和班次 ID：
+
+```json
+[
+  {"employee_id": 123, "work_date": "2026-08-26", "shift_template_id": "shift-id", "remark": "智能体排班"},
+  {"employee_id": 456, "work_date": "2026-08-26", "shift_template_id": "shift-id"}
+]
+```
+
+- `--params <json>` / `--params-file <path>` / `@file` / `@-`：合并 JSON 到快捷默认参数
+- `--validate-only` / `--dry-run`：只校验不执行
+- `--no-json`：纯文本输出
+
+### PowerShell 传 JSON
+
+优先写文件再引用，避免引号被吞：
+
+```powershell
+'{"period":"last_month"}' | Set-Content -Encoding utf8 ./p.json
+vps-work sales +headline-kpi --params '@./p.json'
+```
+
+业务语义与参数表见仓库 `skills/vps-*/SKILL.md` 与 `references/`。
+
+---
+
+## 六、公开 Skill（Agent）
+
+所有 `vps-*` skill **随 npm 包分发**，**无需登录**即可安装到 Cursor / Claude Code / Trae / Hermes 等：
+
+```bash
+vps-work skill list
+vps-work skill install --all --agent all
+vps-work skill install sale-performance-query vps-im --agent cursor
+vps-work skill install --all --dir ~/my-agent/skills
+
+vps-work skill update      # 升级 CLI 后覆盖式重同步
+vps-work skill uninstall sale-performance-query --agent cursor
+```
+
+`--agent`：`cursor` / `claude-code` / `trae` / `trae-cn` / `openclaw` / `hermes` / `all`。
+
+### Agent 新建和维护个人技能
+
+这些命令使用当前人工会话或宿主注入的 `VERTU_APP_ID` / `VERTU_APP_KEY`，不签发临时令牌：
+
+```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
+```
+
+- `--slug` 必须是小写字母、数字和单连字符组成的稳定机器名。
+- `--skill-md` 与 `--instructions` 支持 `@file`、`@-`；两者不能同时提供。
+- 新建、更新都会自动生成或校正 YAML frontmatter：`name` 固定为 slug，`description` 自动补齐，其他字段保留。
+- 只能更新、分类、申请公开或删除自己创建的个人技能；公开技能由审核流程管理。
+
+---
+
+## 七、环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `VERTU_APP_ID` / `VERTU_APP_KEY` | Agent 接入（app key） |
+| `VERTU_BOT_INBOUND_KEY` | Bot Bearer（CI） |
+| `VERTU_DISABLE_KEYTAR=1` | 强制文件存会话 |
+| `VERTU_DEBUG=1` | 调试输出 |
+
+---
+
+## 八、本机路径
+
+| 类型 | 位置 |
+|------|------|
+| 配置 | `~/.vps-work/config.json`（Windows：`%USERPROFILE%\.vps-work\`） |
+| Cursor Skill | `~/.cursor/skills/<skill_key>/` |
+| Claude Code | `~/.claude/skills/<skill_key>/` |
+| Trae 国际 / 国内 | `~/.trae/skills/` / `~/.trae-cn/skills/` |
+| OpenClaw / Hermes | `~/.openclaw/skills/` / `~/.hermes/skills/` |
+
+---
+
+## 九、常见问题
+
+**Q：提示未登录？**
+
+`vps-work auth status` 检查凭证。Agent/Bot/Hermes 凭证无效时联系管理员刷新宿主 app_key；仅人工用户可交互执行 `vps-work auth login`。
+
+**Q：CI 怎么用？**
+
+设置 `VERTU_BOT_INBOUND_KEY`，然后直接跑 `vps-work sales +headline-kpi` 等。
+
+**Q：Trae 国际版和国内版目录？**
+
+分开；`skill install --all` 会写两份，只用一版时用 `--agent trae` 或 `--agent trae-cn`。
+
+---
+
+## 十、卸载
+
+本包会话在 `~/.vps-work`。若机器上还留有已弃用的 `vertu-cli`，一并执行 `npm uninstall -g vertu-cli` 并删除 `~/.vertu`。
+
+```bash
+npm uninstall -g vps-work
+```