vps-work 1.0.0

package/examples/README.md

@@ -0,0 +1,94 @@
+# vps-work - quickstart walkthrough
+
+End-to-end demonstration of using `vps-work` against Vertu business APIs, then
+propagating the bundled public skills to Cursor / Claude Code / Trae / Hermes.
+
+## 0. Build (or `npm link`) the CLI
+
+```bash
+cd vps-cli
+cd packages/vps-work
+npm install
+npm run build
+node dist/vps-work.cjs --help
+# or, for a globally callable binary while developing:
+npm link
+vps-work --help
+```
+
+## 1. Login once per deployment
+
+This password login is for a human operator in an interactive terminal only. Agent/Bot/Hermes must use host-injected app_key credentials and must not request or pass a user password.
+
+```bash
+vps-work auth login
+# → prompts for login + password, then stores the session in the OS keychain
+#   (falls back to ~/.vps-work/config.json with mode 0600 if keytar is unavailable)
+
+vps-work auth status
+# Service     : Vertu
+# Auth mode   : user
+# User        : alice@example.com (uid=7)
+# Session src : keychain
+```
+
+## 2. Run domain shortcuts
+
+```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 +target-achievement --period this_month --params '{"group_by":"dept_l1","limit":500}'
+vps-work sales +dept-breakdown --period this_month --group-by salesperson --limit 10
+
+vps-work hr +me
+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
+
+# manage the same local V Drive files as VPS Desktop
+vps-work drive +list --recursive
+vps-work drive +upload --source ./方案.pdf
+
+# preview the payload without executing
+vps-work sales +headline-kpi --validate-only
+```
+
+## 3. Install bundled public skills (no login required)
+
+```bash
+vps-work skill list                                # list all bundled public skills
+vps-work skill install --all --agent all           # cursor / claude-code / trae / hermes / ...
+vps-work skill install sale-performance-query vps-im --agent cursor
+vps-work skill install --all --dir ~/work/my-agent/skills   # custom dir for a non-builtin agent
+
+vps-work skill update                              # overwrite-resync after upgrading the CLI
+vps-work skill uninstall sale-performance-query --agent cursor
+```
+
+## 4. Where things land on disk
+
+| Agent | Directory | Notes |
+|-------|-----------|-------|
+| Cursor (user-level) | `~/.cursor/skills/<skill_key>/` | Adds `disable-model-invocation: false` to frontmatter |
+| Claude Code (user-level) | `~/.claude/skills/<skill_key>/` | Adds `allowed-tools: [Bash]` so the model may invoke `vps-work` |
+| Trae international | `~/.trae/skills/<skill_key>/` | International edition only |
+| Trae China | `~/.trae-cn/skills/<skill_key>/` | CN edition uses a separate `.trae-cn` user folder |
+| OpenClaw | `~/.openclaw/skills/<skill_key>/` | Managed/local skill root |
+| Hermes (Nous Research) | `~/.hermes/skills/<skill_key>/` | Hermes Agent's source-of-truth skills root |
+| Custom (`--dir`) | `<path>/<skill_key>/` | Any not-yet-builtin agent |
+
+Skills are static files copied recursively from the package `skills/` directory —
+no remote fetch, no cache, no manifest. `vps-work skill update` simply re-copies
+the bundled files (overwrite).
+
+## 5. CI / non-interactive use (Bot Bearer)
+
+```bash
+export VERTU_BOT_INBOUND_KEY=<inbound_api_key>
+vps-work auth status
+vps-work sales +headline-kpi
+```
+
+When `VERTU_BOT_INBOUND_KEY` is set the CLI sends `Authorization: Bearer ...`.
+Agent integrations can instead set `VERTU_APP_ID` / `VERTU_APP_KEY`.

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "vps-work",
+  "version": "1.0.0",
+  "description": "VPS Work CLI - tenant-aware domain shortcuts and bundled agent skills for Cursor / Claude Code / Trae.",
+  "license": "MIT",
+  "author": "he-linyan",
+  "homepage": "https://gitee.com/he-linyan/vps-cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/he-linyan/vps-cli.git",
+    "directory": "packages/vps-work"
+  },
+  "bugs": {
+    "url": "https://gitee.com/he-linyan/vps-cli/issues"
+  },
+  "keywords": [
+    "odoo",
+    "cli",
+    "ai-skills",
+    "ai-cli",
+    "agent",
+    "cursor",
+    "claude-code",
+    "trae",
+    "vps-work"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "vps-work": "dist/vps-work.cjs"
+  },
+  "files": [
+    "dist",
+    "skills",
+    ".well-known",
+    "scripts",
+    "README.md",
+    "USAGE.md",
+    "examples/README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "dev": "tsx src/bin/vps-work.ts",
+    "build": "tsup",
+    "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.2.0",
+    "commander": "^13.0.0",
+    "undici": "^7.2.0",
+    "yaml": "^2.6.1",
+    "zod": "^3.24.1"
+  },
+  "optionalDependencies": {
+    "keytar": "^7.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "@typescript-eslint/eslint-plugin": "^8.20.0",
+    "@typescript-eslint/parser": "^8.20.0",
+    "eslint": "^9.18.0",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.0"
+  }
+}

package/scripts/install-onboard-skill.ps1

@@ -0,0 +1,77 @@
+# vps-work-onboard skill installer (PowerShell)
+# Usage:
+#   irm https://unpkg.com/vps-work@latest/scripts/install-onboard-skill.ps1 | iex
+#
+# Behavior:
+#   - Downloads vps-work-onboard/SKILL.md from the npm package on unpkg (override via $env:VERTU_ONBOARD_RAW)
+#   - Detects which AI agent root directories already exist under $HOME and writes
+#     <agent>/skills/vps-work-onboard/SKILL.md into each
+#   - Falls back to ~/.cursor/skills/vps-work-onboard/ when no agent root is detected
+#   - Idempotent: re-running just rewrites the SKILL.md (whatever was on disk is overwritten)
+#
+# After running, tell your AI agent (Cursor / Claude Code / Trae / ...) something like:
+#   "Use the vps-work-onboard skill to install vps-work on this machine."
+
+$ErrorActionPreference = 'Stop'
+
+$Raw = if ($env:VERTU_ONBOARD_RAW) {
+    $env:VERTU_ONBOARD_RAW
+} else {
+    'https://unpkg.com/vps-work@latest/skills/vps-work-onboard/SKILL.md'
+}
+
+# Critical: use Invoke-WebRequest -OutFile to preserve raw bytes. Invoke-RestMethod +
+# Set-Content -Encoding UTF8 mangles non-ASCII (Chinese) on Windows PowerShell 5.x
+# because IRM decodes the response into a .NET string under the current console codepage,
+# and Set-Content -Encoding UTF8 then writes a BOM. Streaming bytes side-steps both.
+Write-Host "[vps-work-onboard] fetching SKILL.md from $Raw"
+$tmpFile = [System.IO.Path]::GetTempFileName()
+try {
+    try {
+        Invoke-WebRequest -Uri $Raw -OutFile $tmpFile -UseBasicParsing -TimeoutSec 30 | Out-Null
+    } catch {
+        Write-Error "Failed to fetch SKILL.md from $Raw : $($_.Exception.Message)"
+        exit 1
+    }
+
+    # Map: agent id => root dir under $HOME (also the marker that proves the agent is in use)
+    $agents = @(
+        @{ Id = 'cursor';   Root = '.cursor'   },
+        @{ Id = 'claude';   Root = '.claude'   },
+        @{ Id = 'trae';     Root = '.trae'     },
+        @{ Id = 'trae-cn';  Root = '.trae-cn'  },
+        @{ Id = 'openclaw'; Root = '.openclaw' },
+        @{ Id = 'hermes';   Root = '.hermes'   }
+    )
+
+    $homeDir = [Environment]::GetFolderPath('UserProfile')
+    $written = New-Object System.Collections.Generic.List[string]
+
+    foreach ($a in $agents) {
+        $markerPath = Join-Path $homeDir $a.Root
+        if (-not (Test-Path -LiteralPath $markerPath -PathType Container)) { continue }
+        $destDir = Join-Path (Join-Path $markerPath 'skills') 'vps-work-onboard'
+        New-Item -ItemType Directory -Path $destDir -Force | Out-Null
+        $destFile = Join-Path $destDir 'SKILL.md'
+        Copy-Item -LiteralPath $tmpFile -Destination $destFile -Force
+        $written.Add("$($a.Id) -> $destFile")
+    }
+
+    if ($written.Count -eq 0) {
+        Write-Host "[vps-work-onboard] no AI agent root detected under $homeDir ; falling back to Cursor."
+        $destDir = Join-Path $homeDir '.cursor\skills\vps-work-onboard'
+        New-Item -ItemType Directory -Path $destDir -Force | Out-Null
+        $destFile = Join-Path $destDir 'SKILL.md'
+        Copy-Item -LiteralPath $tmpFile -Destination $destFile -Force
+        $written.Add("cursor (fallback) -> $destFile")
+    }
+
+    Write-Host ""
+    Write-Host "[vps-work-onboard] installed to:"
+    foreach ($w in $written) { Write-Host "  $w" }
+    Write-Host ""
+    Write-Host "Next: open your AI agent and say:"
+    Write-Host '  "Use the vps-work-onboard skill to install vps-work on this machine."'
+} finally {
+    Remove-Item -LiteralPath $tmpFile -Force -ErrorAction SilentlyContinue
+}

package/scripts/install-onboard-skill.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# vps-work-onboard skill installer (POSIX bash)
+# Usage:
+#   curl -fsSL https://unpkg.com/vps-work@latest/scripts/install-onboard-skill.sh | bash
+#
+# Behavior:
+#   - Downloads vps-work-onboard/SKILL.md from the npm package on unpkg (override via VERTU_ONBOARD_RAW)
+#   - Detects which AI agent root directories already exist under $HOME and writes
+#     <agent>/skills/vps-work-onboard/SKILL.md into each
+#   - Falls back to ~/.cursor/skills/vps-work-onboard/ when no agent root is detected
+#   - Idempotent: re-running just rewrites the SKILL.md
+#
+# After running, tell your AI agent (Cursor / Claude Code / Trae / ...) something like:
+#   "Use the vps-work-onboard skill to install vps-work on this machine."
+
+set -euo pipefail
+
+RAW="${VERTU_ONBOARD_RAW:-https://unpkg.com/vps-work@latest/skills/vps-work-onboard/SKILL.md}"
+
+echo "[vps-work-onboard] fetching SKILL.md from $RAW"
+TMP="$(mktemp)"
+trap 'rm -f "$TMP"' EXIT
+if ! curl -fsSL --max-time 30 "$RAW" -o "$TMP"; then
+    echo "Failed to fetch SKILL.md from $RAW" >&2
+    exit 1
+fi
+
+# Pairs of "<agent_id>:<root_dir_under_home>" — root_dir is also the marker that
+# proves the user actually uses that agent. We write into <home>/<root>/skills/vps-work-onboard/.
+AGENTS=(
+    "cursor:.cursor"
+    "claude:.claude"
+    "trae:.trae"
+    "trae-cn:.trae-cn"
+    "openclaw:.openclaw"
+    "hermes:.hermes"
+)
+
+HOME_DIR="${HOME:?HOME not set}"
+written=()
+
+for entry in "${AGENTS[@]}"; do
+    id="${entry%%:*}"
+    root="${entry##*:}"
+    marker="$HOME_DIR/$root"
+    [ -d "$marker" ] || continue
+    dest_dir="$marker/skills/vps-work-onboard"
+    mkdir -p "$dest_dir"
+    cp "$TMP" "$dest_dir/SKILL.md"
+    written+=("$id → $dest_dir/SKILL.md")
+done
+
+if [ "${#written[@]}" -eq 0 ]; then
+    echo "[vps-work-onboard] no AI agent root detected under $HOME_DIR ; falling back to Cursor."
+    dest_dir="$HOME_DIR/.cursor/skills/vps-work-onboard"
+    mkdir -p "$dest_dir"
+    cp "$TMP" "$dest_dir/SKILL.md"
+    written+=("cursor (fallback) → $dest_dir/SKILL.md")
+fi
+
+echo
+echo "[vps-work-onboard] installed to:"
+for w in "${written[@]}"; do echo "  $w"; done
+echo
+echo "Next: open your AI agent and say:"
+echo '  "Use the vps-work-onboard skill to install vps-work on this machine."'

package/scripts/test-local-tenant-services.mjs

@@ -0,0 +1,21 @@
+import assert from 'node:assert/strict';
+import {execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+import {fileURLToPath} from 'node:url';
+const base='http://127.0.0.1:3928';
+const tenants=[process.env.VPS_TEST_TENANT_A,process.env.VPS_TEST_TENANT_B];
+if(tenants.some(id=>!id))throw Error('Specify isolated acceptance tenants');
+const bin=process.env.VPS_TEST_CLI_BIN||fileURLToPath(new URL('../dist/vps-work.cjs',import.meta.url));
+async function post(path,body,token){const r=await fetch(base+path,{method:'POST',headers:{'Content-Type':'application/json',...(token?{Authorization:`Bearer ${token}`}:{})},body:JSON.stringify(body)});assert.equal(r.status,200);return r.json();}
+for(const tenant of tenants){
+ const initial=await post('/v1/auth/login',{login:'19900000011',password:'LocalAcceptance-2026!'});
+ const session=await post('/v1/auth/tenant/switch',{tenant_id:tenant},initial.token);
+ assert.equal(session.user.tenantId,tenant);
+ for(const args of [['im','+me'],['im','+users','--limit','100'],['im','+channels'],['task','+tc-tasks']]){
+  const {stdout}=await promisify(execFile)(process.execPath,[bin,...args],{env:{...process.env,VERTU_VPS_SERVICE_URL:base,VERTU_ACCESS_TOKEN:session.token,VERTU_EXPECTED_USER_ID:String(session.user.userId),VERTU_USER_LOGIN:session.user.login},timeout:60000,maxBuffer:4*1024*1024});
+  const result=JSON.parse(stdout);assert.ok(result&&typeof result==='object');
+  if(args[1]==='+me')assert.ok(stdout.includes(tenant),'CLI response must carry the selected tenant');
+  console.log(`PASS ${args.slice(0,2).join(' ')} for isolated tenant ${tenant}`);
+ }
+}
+console.log('Built CLI read-only smoke passed. No global CLI credentials were changed; no SMS or paid model request was sent.');

package/skills/README.md

@@ -0,0 +1,53 @@
+# Agent Skills
+
+布局对齐 [larksuite/cli/skills](https://github.com/larksuite/cli/tree/main/skills)：`skills/<skill_key>/SKILL.md`，域级聚合 skill 提供 `+` 快捷表并指向 `references/` 或子 skill 契约。
+
+## 域聚合（与 `vps-work <域>` 一一对应）
+
+| CLI 域 | 聚合 skill | 说明 |
+|--------|------------|------|
+| （共用） | `vps-shared` | 登录、身份、`+` 约定 |
+| `sales` | `sale-performance-query` | 总销日报、部门 OKR 达成、销售人效 |
+| `store` | `vps-store-management` | 门店接待、进店转化与客户过程数据 |
+| `hr` | `vps-hr` | 薪酬单据、工资条 |
+| `product` | `vps-product` | 库存、商品价格、发货、齐套物料、机头库存 |
+| `task` | `vps-task-management-assistant` | 任务中心项目 / 任务 / 待办 / PDCA 协助人 / OKR |
+| `approval` | `vps-approval` | 审批队列 |
+| `report` | `vps-daily-report-assistant` | 我的日报 / 提交 / 同步 |
+| `okr` | `vps-okr` | OKR |
+| `calendar` | `vps-calendar` | 查询、创建和修改日程，指定日历与多人忙闲 |
+| `docs` | `vps-documents` | 查询、创建、整理、导出、共享企业云文档，并发送文档卡片到 VPS IM |
+| `drive` | `vps-v-drive` | 管理账号级 OSS V盘普通文件、文件夹、传输记录与回收站 |
+| `creative` | `vps-creative` | 内容创作画布：AI 生图、生视频、文字转语音、音乐生成与模型列表 |
+| `tools` | `vps-tools` | 平台公共工具：OSS 上传、公开地址与限时签名地址 |
+| `im` / `mail` / `meeting` | `vps-im` / `vps-mail` / `vps-meeting` | IM 消息与会话附件下载、站内信和会议协作（`vemory` 保留兼容） |
+
+细粒度 `vps-*` skill（如 `vps-daily-sales-report`）承载 script_key 与参数说明；Agent 优先读域聚合 skill，再按需下钻子 skill。
+
+- `vps-device-abnormal-statistics`：按仓位查询在库激活、库存/在途与异常 IMEI，并按 IMEI 下钻未处理异常原因；仅授权中心已分配“VPS 设备异常分析”角色的员工可访问，入口 `vps-work product +abnormal-…`。
+
+## 业务技能（随包静态分发，完全公开）
+
+所有 `vps-*` 业务 skill 都随 npm 包分发于本仓库 `skills/<skill_key>/`，**无需登录、不连服务端**。安装到各 Agent 目录：
+
+```bash
+vps-work skill list                       # 列出全部公开 skill
+vps-work skill install --all --agent all  # 铺到 cursor / claude-code / hermes 等
+vps-work skill update                     # 覆盖式重同步
+```
+
+当前 Agent 使用宿主 app_key 管理用户自己的技能时，使用 `skill +create-personal`、
+`+update-personal`、`+change-category`、`+request-publication`、`+delete-personal`。
+新建和更新命令会自动补齐、校正 `SKILL.md` YAML frontmatter；详见
+[`vps-work/SKILL.md`](./vps-work/SKILL.md#51-agent-管理当前用户自己的技能)。
+
+`.well-known/skills/index.json` 为仓库内发现索引。
+
+**命名**：仓库与文案统一 `vps-*`。
+
+## 仓库内自举 skill
+
+| Skill | 说明 |
+|-------|------|
+| `vps-work-onboard` | 安装 / 登录 / skill 铺设引导 |
+| `vps-work` | CLI 自身说明 |

package/skills/sale-performance-query/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: sale-performance-query
+description: "使用 `vps-work sales +…` 查询 Vertu 销售业绩和订单。用于公司、部门、销售员的销售额、销量、普通销售订单、订单关联的开票申请、正式发票、会计凭证与付款状态、已对账销售收款、JXSD 经销商订单、代理商 Sell-in/Sell-out、代理商五件套来源和 Walk-in、经销商库存与终销、客户画像、新老客占比、环比同比、部门下钻、目标达成、定金退款、人效、个人 OKR、团队 PK，以及按商品系列、款式或 IOT 分析销量销额。除经销商默认仓库库存外，通用商品库存、价格、发货与商品主数据改用 vps-product。"
+---
+
+# 业绩查询
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../vps-shared/SKILL.md`](../vps-shared/SKILL.md)，其中包含认证、当前用户与 `+` 快捷约定**
+
+## 工作原则
+
+- 优先使用 `vps-work sales +…`；不要绕过业务封装查未文档化汇总视图。
+- 查询前确认用户要的时间、部门层级、是否含定金；不明确时采用 Shortcut 默认值，但回答必须说明口径。
+- 如果用户要求本地服务或刚改过 CLI，先 `npm run build`，并显式传 `--base-url http://127.0.0.1:3920` 或确认 `vps-work auth status --json` 指向本地。
+- 引用结果前先看返回的 `filter`：必须核对 `period/start_date/end_date/include_deposit/dept_l1/dept_l2/dept_l3/dept_l4/dept_l5`；商品查询还必须核对 `product_subcategory/product_style/product_style_details/smart_wearable`，趋势查询继续核对 `grain/group_by/breakdown_by`。
+- 返回含 `pagination` 的列表必须检查 `pagination.has_more` / `next_page`，不要把第一页 `rows` 当作全量；需要完整清单时持续翻页直到 `has_more=false`。
+- 空结果先检查权限、过滤条件、姓名/工号拼写、是否默认剔除了定金；不要直接断言全公司为 0。
+
+## Shortcuts（推荐优先使用）
+
+Shortcut 是对常用销售经营查询的高级封装（`vps-work sales +<verb> [flags]`）。有 Shortcut 的操作优先使用，不要绕过业务口径直接查汇总视图。
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+headline-kpi`](references/vps-sales-headline-kpi.md) | 获取公司/部门核心 KPI：销售额、销量、订单 |
+| `+orders` / `+order-list` | 查询订单明细；订单结果已带 `商品码`、分摊比例、客户来源、二级客户来源、最新发货日期和物流单号摘要，支持 `--logistics-no` 反查订单 |
+| [`+order-finance`](references/vps-sales-order-finance.md) / `+finance-detail` | 按销售单号一次查看订单、开票申请、正式发票、过账/付款状态和关联会计凭证摘要 |
+| [`+reconciled-receipts`](references/vps-sales-reconciled-receipts.md) / `+sales-receipts` | 查询最近 30 个自然日内已对账销售单据的收款明细；按单据、收款方式和收款主体聚合 |
+| [`+invoice-status`](references/vps-sales-invoice-status.md) / `+invoice-applications` | 按一个或多个销售单号精确查询开票申请，区分未找到、未申请、草稿、审批中、已完成和已取消 |
+| [`+account-orders`](references/vps-sales-account-orders.md) / `+account-sales-detail` | 按会计科目穿透已过账凭证关联的销售订单行；区分直接关联与同凭证关联 |
+| [`+invoice-attachments`](references/vps-sales-invoice-attachments.md) | 按销售单号查询已过账客户发票/退款单附件；可由本地服务安全下载，不返回存储签名 URL |
+| [`+dealer-orders`](references/vps-sales-dealer-orders.md) / `+dealer-order-list` | 查询独立的 `dealer.sale.order` 经销商订单；仅返回 `JXSD` 前缀，支持经销商、商品和 VSN/IMEI 筛选 |
+| [`+dealer-inventory`](references/vps-sales-dealer-performance.md) | 按经销商默认仓库统计当前正库存数量、标准价金额、SKU 和未定价库存 |
+| [`+dealer-final-sales`](references/vps-sales-dealer-performance.md) | 按经销商和五件套客户类型统计已完成 JXSD 终销数量、含税金额、订单数 |
+| [`+dealer-customer-portrait`](references/vps-sales-dealer-performance.md) / `+dealer-portrait` | 统计终销单客户背景、年龄、购买原因及订单占比 |
+| [`+agent-sell-in-out`](references/vps-sales-agent-five-suite.md) / `+sell-in-out` | 对比国内代理 Sell-in 与经销商销售订单 Sell-out；支持按代理商精确筛选 |
+| [`+agent-sell-in-out-details`](references/vps-sales-agent-five-suite.md) | 返回 Sell-in 销售业绩行与 Sell-out 经销商订单明细 |
+| [`+agent-five-source`](references/vps-sales-agent-five-suite.md) / `+agent-wujiantao` | 返回代理商五件套来源目标、真实 Sell-out、占比与完成率 |
+| [`+agent-five-source-half-year`](references/vps-sales-agent-five-suite.md) | 返回上/下半年五件套 Sell-out 真实业绩 |
+| [`+agent-walkin`](references/vps-sales-agent-five-suite.md) | 查询客户类型为自然进店/Walk-in 的国内经销商销售订单 |
+| [`+agent-list`](references/vps-sales-agent-five-suite.md) | 返回与 `vps-ep` 代理商组织树同期间、同国内代理范围的代理商名单 |
+| [`+agent-top-metrics`](references/vps-sales-agent-five-suite.md) · `+agent-performance` · `+agent-performance-detail` | 查询代理商看板顶部指标、目标业绩及环比同比明细 |
+| [`+agent-delivery`](references/vps-sales-agent-five-suite.md) · `+agent-product-sales` · `+agent-product-ranking` · `+agent-sku-ranking` · `+agent-product-material-ranking` | 查询代理商提货、产品层级及排名 |
+| [`+agent-phone-sales-proportion`](references/vps-sales-agent-five-suite.md) · `+agent-iot-sales-proportion` · `+agent-price-distribution` | 查询代理商手机/IOT 占比和价格区间 |
+| [`+order-logistics`](references/vps-sales-order-logistics.md) | 仅在明确要看某订单/物流单号/出库单号的发货明细时使用 |
+| [`+dept-breakdown`](references/vps-sales-dept-breakdown.md) | 按部门、销售员、产品线等维度拆解销售排名 |
+| [`+customer-region`](references/vps-sales-customer-region.md) / `+customer-region-summary` | 按客户国家/地区查询全公司订单数、营业额及占比 |
+| [`+customer-mix`](references/vps-sales-customer-mix.md) | 按 `customer_source.customer_category` 查询新客、老客及未分类销售额占比 |
+| [`+dept-comparison`](references/vps-sales-dept-comparison.md) | 获取环比、同比对比结果 |
+| [`+target-achievement`](references/vps-sales-target-achievement.md) | 获取部门或公司 OKR / 目标达成率 |
+| `+dept-monthly-okr` | 获取部门月度 OKR 明细，用于核对目标来源；默认与管理端“部门业绩目标”页面一致，需要核对新表时传 `--okr-source postgres` |
+| [`+deposit-breakdown`](references/vps-sales-deposit-breakdown.md) | 获取含定金、不含定金、定金金额三类口径 |
+| [`+refund-summary`](references/vps-sales-refund-summary.md) | 获取退款、退换货汇总与部门 Top |
+| [`+service-sales`](references/vps-sales-service-sales.md) | 获取权益部、服务部销售业绩 |
+| [`+daily-trend`](references/vps-sales-daily-trend.md) / `+trend` | 获取按日/周/月销售趋势、环比、累计、同比及渠道 × 款式明细 |
+| [`+ranking`](references/vps-sales-ranking.md) | 获取销售员 TOP / BOTTOM 红黑榜 |
+| [`+per-person-kpi`](references/vps-sales-per-person-kpi.md) | 获取销售人员个人 KPI（人效） |
+| [`+personal-okr`](references/vps-sales-personal-okr.md) | 获取销售人员个人 OKR 达成 |
+| `+personal-monthly-okr` | 获取个人月度 OKR 明细，用于核对个人目标来源；默认 Postgres，旧 PMS/BI 口径传 `--okr-source legacy` |
+| [`+team-pk`](references/vps-sales-team-pk.md) | 获取团队 PK 排名 |
+
+## 需要读取的参考
+
+- [`销售域业务实体`](references/vps-sales-entities.md) — 三条能力线、商品分类、定金口径。
+- [`共享时间/部门参数`](references/vps-sales-shared-params.md) — 各 Shortcut 共用的 CLI 与 execute 字段。
+- 处理具体 Shortcut 前读取上表对应的参考文档；人员业绩与 PK 的完整参数可继续读取 [`vps-sale-personnel-efficiency/reference.md`](../vps-sale-personnel-efficiency/reference.md)。
+
+## 订单与物流
+
+- 用户提到“经销商订单 / 经销商销售单 / JXSD 单号”时必须用 `+dealer-orders`，不要用普通 `+orders`；两者数据模型和金额口径不同。
+- `+dealer-orders` 默认本月，订单号、经销商、商品或 VSN 筛选后仍需检查 `filter.order_prefix=JXSD`、`filter.access` 和分页状态。
+- 用户问“经销商库存数量/金额”时用 `+dealer-inventory`；这是经销商默认仓库专用口径，不用通用商品库存替代。
+- 用户问“经销商终销/五件套客户类型”时用 `+dealer-final-sales`；用户问终销单内的客户背景、年龄或购买原因时用 `+dealer-customer-portrait`。两个终销入口默认本月，必须说明只含 `JXSD + done + so + 非退货明细`。
+- 用户问“代理商 Sell-in/Sell-out 对比”时用 `+agent-sell-in-out`，追明细用 `+agent-sell-in-out-details`。Sell-in 来自国内代理部门子树销售业绩；Sell-out 来自国内经销商已完成销售单。此处为 `vps-ep` 个性化看板口径，不额外限制 `JXSD` 或 `doc_type=so`。
+- 用户问“代理商五件套/五大来源/来源完成率”时用 `+agent-five-source`；问半年结构时用 `+agent-five-source-half-year`；问自然进店订单时用 `+agent-walkin`。
+- 用户问 `vps-ep` 代理商个性化页面的其他模块时，使用同名 `+agent-*` 看板命令；先用 `+agent-list` 获取完整名称，再向相关命令传 `--agent-name <完整名称>`。
+- 选择单个代理商优先用 `--agent-name <完整名称>` 标准化中英文括号后精确匹配；`--dealer` 是兼容参数，在代理商看板命令中同样按精确名称处理。检查有 `filter` 的返回时同时核对 `filter.agent_name`、`nature=domestic` 和权限范围。
+- 代理商目标来自 `线下代理OKR` 且严格按请求日期范围取数；结果为 `0` 时先区分“当期无目标记录”和“存在目标记录但值为零”，不得自行回退上月目标。
+- 查“订单、订单明细、某商品订单、某客户订单、物流单号对应哪个订单”优先用 `+orders`。订单列表返回 `商品码`、`分摊比例`、`客户来源`、`二级客户来源`、`最新发货日期`、`物流单号`、`物流单号数`，一般不需要再查物流明细。
+- 查“某销售单的开票申请、正式发票、会计凭证、过账和付款状态”优先使用 `+order-finance --order-no ...`，避免拼接多个局部查询。
+- 查“已对账销售收款、某销售单收款方式/主体/金额”使用 `+reconciled-receipts`。其时间范围固定为最近 30 个自然日，即使指定单号也不放宽；结果默认排除“京东自营”和“商场代收”收款方式。
+- 查“某销售单有没有申请开票、申请到哪一步、销售单与开票申请如何关联”使用 `+invoice-status --order-names ...`。禁止用 `+reconciled-receipts` 的“已开票”布尔值代替真实申请状态。
+- 查“某会计科目对应哪些销售单/销售明细”使用 `+account-orders`。必须至少传 `--account-code` 或 `--account-name`，并区分会计行金额、发票行金额与销售订单行金额。
+- 查“某销售单的发票附件”使用 `+invoice-attachments --order-no <销售单号>`；只查询当前用户销售数据范围内的订单。需要文件时加 `--download-dir <目录>`，附件由 Vertu 服务代理下载，不直接展示对象存储 URL。
+- 订单列表客户信息默认按常用规则脱敏：手机号保留前三后四，客户名称保留首字；有 `sales.pii:read` 时才返回明文。
+- 用户明确给出物流单号并要求“物流情况/发货明细/收货信息”时，先运行 `vps-work sales +order-logistics --help`，再传入用户提供的真实物流单号。
+- 不要为了“某部门物流/某销售员物流”优先跑物流明细查询；先运行 `vps-work sales +orders --help`，按帮助中的部门或销售员参数筛选订单，再对具体订单或物流单号精查。
+
+## 新老客销售占比
+
+- 用户问“新老客销售占比 / 新客老客结构”时使用 `+customer-mix`，不要通过客户手机号或首次下单时间自行推断。
+- 分类固定读取销售订单的客户来源关联：`sale_order.customer_source = customer_source.id`，再取 `customer_source.customer_category`。
+- 分类值映射：`new=新客`、`old=老客`、NULL/空值=`未分类`；未知扩展值保留原值，不并入新客或老客。
+- `sales_share` 的分母包含未分类，适合与总销售额对账；`classified_sales_share` 只在新客与老客之间计算；必须同时说明 `classified_coverage_rate`，不能隐藏未分类销售额。
+- 默认不含定金，时间默认本月；部门过滤、商品细类过滤和数据权限与其他销售 KPI 一致。
+
+## 客户地区业绩
+
+- 用户问“客户地区分布 / 某国家来源的业绩 / 马来西亚本月订单数和营业额”时使用 `+customer-region`。
+- 该命令固定为全公司汇总，必须具备 `sales.customer_region.all:read`；缺少权限时不得改用 `+orders`、`+headline-kpi` 或本人范围数据猜测。
+- 地区来自订单国家/国区字段，不是销售部门、门店东西南北区或收货地址文本。
+- 默认本月、不含定金；营业额复用公司 KPI 实际业绩口径，退货/退差价作负数冲减。
+
+## 商品与系列查询口径
+
+- “大折叠”必须先限定 `--product-subcategory "VERTU ALPHAFOLD"`，但这只限定商品细类，不能区分黄金3、黄金4、金钻等款式。
+- “高定销售”使用精确条件 `--product-style 高定`。该口径已与 `vps-ep` 高定销售保持一致，不要改用商品名称模糊搜索。
+- “黄金3 / 黄金4 / 金钻”使用 `--product-style-details "黄金3,黄金4,金钻"`；服务端会把“金钻”“4金3钻”规范化为商品维表的精确值 `4金/3钻`。需要限定大折叠时必须同时传 `--product-subcategory "VERTU ALPHAFOLD"`。
+- “智能穿戴”使用 `--smart-wearable`。它同时限定商品大类为戒指/手链，并使用与 `vps-ep` 一致的系列白名单：智能健康戒指、AI钻戒2代、VERTU AI 水晶智能戒指、VERTU AI 智能戒指、VERTU关心智能手链。
+- “IOT / IOT配件”使用 `--product-category IOT配件`；IOT 分类包含手链。商品趋势同时返回去重销售单数 `orders` 和与 vps-ep 商品页一致的明细行数 `product_order_count`，二者不能混报。含/不含代理折扣、置换排除及库存口径读取 `vps-product`。
+- 聚合查询不要用 `+orders --product <词>` 代替上述精确过滤；`--product` 会在名称、编码和分类上做模糊搜索，只适合找订单明细。
+- 必须检查响应 `filter` 是否原样返回上述商品条件；缺失任一条件时，不得把结果称为该系列或款式的业绩。
+
+### 大折叠高定趋势标准调用
+
+周维度：最新组织渠道 × 款式1，含销量、销额和周环比：
+
+```bash
+vps-work sales +trend --period this_year --grain week \
+  --group-by org_channel --breakdown-by product_style1 \
+  --product-subcategory "VERTU ALPHAFOLD" --product-style 高定 \
+  --product-style-details "黄金3,黄金4,金钻"
+```
+
+月维度：最新组织渠道 × 款式1，含销量、销额和月环比：
+
+```bash
+vps-work sales +trend --period this_year --grain month \
+  --group-by org_channel --breakdown-by product_style1 \
+  --product-subcategory "VERTU ALPHAFOLD" --product-style 高定 \
+  --product-style-details "黄金3,黄金4,金钻"
+```
+
+结果中的 `qty/amount` 是当期销量/销额，`previous_qty/previous_amount` 是上个周/月，`wow_*` 或 `mom_*` 是对应环比。明细必须保留 `bucket_start/bucket_end/group_name/breakdown_name`。
+
+## 部门层级
+
+- 销售查询只接受 `dept_l1` / `dept_l2` / `dept_l3` / `dept_l4` / `dept_l5`。不要传 `dept`、`department`、`dept_name`、`department_name`，也不要把用户说的“部门”静默猜成一级或二级。
+- 用户说“按一级部门”时使用 `+dept-breakdown --group-by dept_l1`。
+- 用户说“继续到二级部门”或“一级部门和二级部门一起”时，不要只查 `dept_l2`。先查 `dept_l1`，再对每个一级部门执行 `+dept-breakdown --group-by dept_l2 --dept-l1 <一级部门>`，最后按“一级部门 / 二级部门 / 小计”展示。
+- 二级部门的订单数子项相加可能大于一级小计，因为同一销售单可能跨二级部门分摊；展示时需要提示这个口径。
+- 当前在线 Odoo 销售脚本没有额外“匹配部门规则”；忽略历史特例后，`匹配部门` 字段等同业绩所属门店（`hdn1.current_name`）。业务业绩、目标达成默认仍可用 `department_mode=matched` 表示按 `匹配部门` 字段汇总；用户明确说“原始组织/组织架构/一级二级三级部门”才用 `department_mode=raw`。
+- 用户说“全公司渠道 / 按最新组织架构渠道”时使用 `group_by=org_channel`，它按当前一级部门归为 `AI渠道 / 国内渠道 / 海外渠道 / 其它部门`。不要使用 `group_by=channel`；后者是销售订单的渠道字段，不是组织架构渠道。
+
+## OKR 合并
+
+- `+target-achievement`、`+dept-monthly-okr` 默认读取管理端“部门业绩目标”相同的 `部门OKR_1` 数据；显式传 `--okr-source postgres` / `okr_source=postgres` 才读取迁移后的部门目标表。`+personal-okr`、`+personal-monthly-okr` 仍默认使用 Postgres 的个人目标表。
+- `+target-achievement` 默认 `group_by=match_dept`，不适合直接合并到一级/二级部门层级表。
+- 要一级部门 OKR，传高级参数：`--params '{"group_by":"dept_l1","limit":500}'`。
+- 要二级部门 OKR，传高级参数：`--params '{"group_by":"dept_l2","limit":500}'`。
+- 用户要“一级 + 二级 + OKR + 达成率”时，先用 `+dept-breakdown` 生成实际业绩层级，再分别拉 `dept_l1/dept_l2` 的目标达成，按部门名合并；展示列至少包含 `实际业绩`、`OKR`、`达成率`。
+- 如果 OKR 明细和销售层级不一致，读取 `+dept-monthly-okr --limit 500` 核对目标来源；回答只合并可匹配到当前展示层级的目标，不把无实绩的门店/小组混进业绩表。
+- 计算“公司整体目标”时必须汇总返回的全部部门目标，包括 `sales_amount=0` 但 `target_amount>0` 的部门；不得把“本期无实绩”当作默认排除条件。如果用户明确要求排除，必须同时披露被排除的部门、数量、目标金额及排除前后的合计。
+- 说明 `target_grain`。本月/月度目标通常是“月度目标整月累加”，不是按当前日期进度折算。
+- OKR 明细与目标达成返回 `pagination`；当 `has_more=true` 时用 `--page <next_page>` 继续查。`total_rows/total_pages` 有值时，回答可说明“共 N 条，仅展示第 X 页”。
+
+## 人员业绩归属
+
+- 查某个人实际业绩优先用 `+headline-kpi --name <姓名>` 或 `+personal-okr --params '{"salesperson_like":"<姓名>"}'`；能确定工号时用 `--work-id` / `work_id` 更稳。
+- 实际业绩归属来自销售行口径：Odoo 在线订单使用 `apportionment_ratio_line.user_id/department_id`，没有分摊时回落 `sale_order.user_id/department_id`；一级/二级部门来自这个“业绩部门”关联后的组织树。
+- `+personal-okr` 展示人员部门时优先取人员视图，再回落销售行部门。若该人在查询窗口没有销售行，显示的部门主要来自人员视图，不代表该窗口有业绩归属。
+- 回答“是否按视图查询”时区分：实际金额按销售视图/代码化销售行口径；人员展示部门可能来自人员视图。
+
+## 回答格式
+
+- 金额用 `¥` 和两位小数；达成率用百分比两位小数。
+- 部门下钻优先用层级表：一级部门小计加粗，下面列二级部门。
+- 汇总时说明：时间窗口、是否含定金、部门层级、商品细类/款式条件、权限范围。
+- **排除项必须披露**：凡结果使用了默认或显式排除（例如不含定金、排除部门/人员、仅统计有实绩行、商品过滤），回答必须逐项说明；分页、Top N、权限范围造成的非全量覆盖也必须说明。禁止把排除后的数字表述为未加限定的“全公司/整体/全部”。
+- 对负数量、退款、订单数分摊导致的合计差异，直接说明口径，不要自行修正数据。
+
+## Skill Resources
+
+```bash
+vps-work sales --help
+vps-work sales +headline-kpi --help
+```
+
+### 业绩汇总脚本
+
+底层 `/v1/execute` 为兼容现有客户端仍使用 `vps-daily-sales-report` 作为 `skill_key`；这只是后端路由键，不是另一个应优先触发的业务 Skill。
+
+- `headline_kpi` · `order_list` · `order_finance` · `sales_invoice_status` · `reconciled_sales_receipts` · `account_sales_detail` · `dealer_order_list` · `dealer_inventory_summary` · `dealer_final_sales_summary` · `dealer_customer_portrait`
+- `agent_list` · `agent_sell_in_out_summary` · `agent_sell_in_out_details` · `agent_walkin_orders` · `agent_five_source_metrics` · `agent_five_source_half_year`
+- `agent_top_metrics` · `agent_performance` · `agent_delivery` · `agent_product_ranking` · `agent_sku_ranking` · `agent_product_material_ranking` · `agent_performance_detail`
+- `agent_product_sales` · `agent_phone_sales_proportion` · `agent_iot_sales_proportion` · `agent_price_distribution`
+- 兼容旧代理商五件套脚本键：`agent_wujiantao_completion_rate` · `agent_wujiantao_five_source_metrics` · `agent_wujiantao_half_year_forecast`
+- `dept_breakdown` · `customer_region_summary` · `customer_sales_mix` · `dept_comparison` · `dept_target_achievement` · `dept_monthly_okr`
+- `with_without_deposit_breakdown` · `refund_summary` · `service_dept_sales_summary`
+- `monthly_daily_trend` · `employee_ranking_top_bottom`
+
+### vps-sale-personnel-efficiency
+
+- `per_person_kpi` · `personal_okr_achievement` · `personal_monthly_okr` · `team_pk_ranking`
+
+## 权限与限制
+
+| 能力 | 说明 |
+|------|------|
+| 登录 | 使用 `vps-work auth status --json` 确认已登录；执行类接口还需要 `execute:read` |
+| 数据范围 | 返回结果会按当前用户数据权限裁剪；用返回 `filter` 检查 `dept_l1/dept_l2/dept_l3/dept_l4/dept_l5/dept_ids/salespersons/barcodes/any_of` |
+| 基础销售 KPI 与订单 | `+headline-kpi`、`+orders`、`+dealer-orders`、`+dealer-inventory`、`+dealer-final-sales`、`+dealer-customer-portrait`、`+agent-sell-in-out`、`+agent-five-source`、`+agent-walkin`、`+dept-breakdown`、`+customer-mix`、`+dept-comparison`、`+deposit-breakdown`、`+refund-summary`、`+service-sales`、`+daily-trend` 需要 `sales.headline_kpi:read` |
+| 全域客户地区业绩 | `+customer-region` 需要独立 `sales.customer_region.all:read`；授权中心角色为 `vps_sales_region_analyst`，只返回地区汇总 |
+| 财务销售查询与发票附件 | `+order-finance`、`+account-orders`、`+invoice-status`、`+reconciled-receipts`、`+invoice-attachments` 需要 `sales.account_orders:read`；开票状态与已对账收款按接口固定 SQL 口径查询，其他能力按各自返回的数据范围说明 |
+| 部门目标达成 | `+target-achievement` 需要 `sales.dept_target:read` |
+| 部门 OKR 明细 | `+dept-monthly-okr` 需要 `sales.dept_monthly_okr:read` |
+| 排名/PK | `+ranking`、`+team-pk` 需要 `sales.team_pk:read` |
+| 人效 | `+per-person-kpi` 需要 `sales.per_person_kpi:read` |
+| 个人 OKR 达成 | `+personal-okr` 需要 `sales.personal_okr_achievement:read` |
+| 个人 OKR 明细 | `+personal-monthly-okr` 需要 `okr.personal_monthly:read` |