vps-work 1.0.0

package/skills/vps-meeting/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: vps-meeting
+version: 1.0.0
+description: 查询会议录音、逐字稿、纪要、总结、章节、问答、待办和部门/模版统计。按本人、递归下属、全域或已授权的指定部门/人员控制访问。入口 `vps-work meeting +…`。触发词：会议、录音、逐字稿、会议纪要、会议总结、会议待办、会议统计、会议模版、谁说了什么。
+metadata:
+  requires:
+    bins: ['vps-work']
+  cliHelp: 'vps-work meeting --help'
+---
+
+# meeting
+
+**MUST Read [`../vps-shared/SKILL.md`](../vps-shared/SKILL.md)**
+
+首选标准命令是 `meeting`；`vemory +meetings` 仅用于兼容旧调用。
+
+| 意图 | 命令 |
+|------|------|
+| 我的会议 | `vps-work meeting +list --scope mine` |
+| 所有递归下属的会议 | `vps-work meeting +list --scope subordinates` |
+| 全域会议（需全域权限） | `vps-work meeting +list --scope all` |
+| 指定人员/部门 | `vps-work meeting +list --scope selection --user-ids 12,13 --department-ids 7` |
+| 按姓名精确查询 | `vps-work meeting +list --employee-name "员工姓名"` |
+| 按纪要模版类型筛选 | `vps-work meeting +list --template-type "团队内部会议"` |
+| 指定部门会议统计 | `vps-work meeting +statistics --department-ids 7 --group-by department` |
+| 全部门分部门统计 | `vps-work meeting +statistics --all-departments --group-by department` |
+| 按会议模版统计 | `vps-work meeting +statistics --department-ids 7 --group-by template` |
+| 按部门和模版交叉统计 | `vps-work meeting +statistics --all-departments --group-by department_template` |
+| 会议详情与手写笔记 | `vps-work meeting +detail --meeting-id <id_or_minutes_id>` |
+| 将会议行动项创建为关联待办 | `vps-work task +tc-todo-create --title "<行动项>" --meeting-id <id_or_minutes_id> --meeting-todo-index <1-based>` |
+
+- `subordinates` 按 `manager_user_id` 递归查下属，不包含同级员工，也不等同于“本部门”。
+- `selection` 只能查询本人、下属及管理员明确授权的人员/部门；越权目标会整体返回 403，不会静默漏数。
+- `all` 仅用于已授予 `meeting.center.all:read` 的用户或管理员。
+- `+statistics --department-ids` 需 `meeting.statistics.selected:read`；`--all-departments` 需 `meeting.statistics.all:read`，且后者结果始终保留部门维度。
+- 统计合并 VPS 会议纪要与旧 Vemory 会议，返回会议场次、生成待办、有效待办、强闭环、待办已完成场次和日程来源场次；响应中的 `metric_definitions` 是字段口径。
+- 部门选择默认包含其子部门。`+list` 只返回轻量列表字段；录音地址、章节、待办、逐字稿和手写笔记仅由 `+detail` 返回。
+- 管理员授权只能在管理后台“授权中心 → 人员 → 会议录音与纪要数据范围”中维护，不得通过 `vps-work` 修改。
+- 使用 `--page` 和 `--page-size` 分页；命令直接返回结构化 JSON，不要追加 `jq` 或 `grep`。
+- VPS 会议列表项通过 `template_type` 返回纪要模版类型；它与原有 `analysis_scene` 值一致。Vemory 支持按模版名称或 `template_code` 精确筛选。
+- `+detail` 同时支持 `+list` 返回的 Vemory `id` 和 VPS `minutes_id`。本地会议的 `meeting.notes` 返回录音过程中手写的笔记；每条包含 `time_ms`、原文 `content`、AI 润色后的 `polished_content` 和 `attachments`。
+- 如需把 `+detail` 的 `todos` 行动项写入任务中心，使用 `task +tc-todo-create`；`--meeting-id` 与 `--meeting-todo-index` 必须同时传入，序号按 `todos` 数组从 1 开始，以便待办详情可回到原会议/录音。

package/skills/vps-okr/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: vps-okr
+version: 1.0.0
+description: 部门与员工 OKR。`vps-work okr +…`。
+metadata:
+  requires:
+    bins: ['vps-work']
+  cliHelp: 'vps-work okr --help'
+---
+
+# okr
+
+**MUST Read [`../vps-shared/SKILL.md`](../vps-shared/SKILL.md)**
+
+| Shortcut | 说明 |
+|----------|------|
+| `+dept-okr` | 部门 OKR 结构化（`department_okr_structured`，含组织树） |
+| `+employee-okr` | 员工 OKR 结构化（`personal_okr_structured`，含组织树） |
+| `+department-structured` | 同 `+dept-okr` |
+| `+personal-structured` | 同 `+employee-okr` |
+
+Agent / Bot 必须使用宿主注入的 app_key，禁止执行账号密码登录。仅人工用户可在交互终端执行 `vps-work auth login`。

package/skills/vps-okr-management-assistant/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: vps-okr-management-assistant
+description: "面向 Vertu 部门和员工 OKR 的结构化取数与分析。用户询问某月部门 OKR、员工个人 OKR、绩效与管理目标、低分目标、目标金额和实际金额时使用。真实入口只有 `vps-work okr +dept-okr`、`+employee-okr` 及其两个别名；周期必须为 YYYY-MM，可按部门或员工名称、ID 过滤。"
+---
+
+# OKR 管理助理
+
+开始前读取 [`../vps-shared/SKILL.md`](../vps-shared/SKILL.md)。
+
+## 命令选择
+
+| 场景 | 命令 |
+|------|------|
+| 部门 OKR | `vps-work okr +dept-okr --okr-period <YYYY-MM>` |
+| 员工 OKR | `vps-work okr +employee-okr --okr-period <YYYY-MM>` |
+| 部门别名 | `vps-work okr +department-structured --okr-period <YYYY-MM>` |
+| 员工别名 | `vps-work okr +personal-structured --okr-period <YYYY-MM>` |
+
+当前 `vps-work okr` 不提供 `+org-tree`、`+dept-objectives`、`--include-sub-departments`、批量 `--department-ids` 或批量 `--employee-ids`。不要生成这些命令。
+
+## 工作流
+
+1. 确认周期，格式必须为 `YYYY-MM`。
+2. 部门可直接传 `--department-name`、`--department-id` 或 `--match-dept`；员工可直接传 `--employee-name`、`--employee-id` 或 `--department-name`。名称由服务端模糊过滤，不要为了查询先猜 ID。
+3. 需要限制返回目标数量时传 `--row-limit <n>`；省略表示不主动限制。
+4. 执行前如需校验参数，追加 `--validate-only`；它只输出请求，不访问服务。
+5. 从响应的 `objectives`、`department_tree` 和 `counts` 解读结果。不要读取旧文档中的 `.data`、`.results` 或分页字段。
+
+## 响应口径
+
+- `scope` 为 `department` 或 `personal`。
+- `okr_period` 是请求周期；`management_latest_period` 是管理类 OKR 的最新可用周期，二者可能不同。
+- `objectives` 是目标平铺数组；每个目标包含 `key_results`。
+- `department_tree` 是按组织结构重组后的同一批目标。
+- `counts.performance`、`counts.management`、`counts.total` 是本次过滤后的数量。
+- `data_source` 在 2026-07 及以后为 `formal-okr-relational`；2026-01 至 2026-06 历史查询为 `pms-postgresql-new-okr-tables`。
+
+详细参数和示例见 [`reference.md`](reference.md)。
+
+## 限制
+
+- “部门及所有下级部门”当前没有单一 OKR CLI 参数。可以先用 `vps-work hr +org-tree` 理解组织结构，再对明确部门逐个查询；不得声称 `+dept-okr` 已自动穿透下级。
+- `employee_id` 是 `res.users.id`，`department_id` 是 `hr.department.id`。
+- 查询结果受当前用户权限和服务端数据范围限制。
+- 2026-07 及以后不回退 PMS；正式表不可用时服务端会明确报错。

package/skills/vps-okr-management-assistant/reference.md

@@ -0,0 +1,84 @@
+# OKR CLI 真实契约
+
+本页与 `vps-work okr --help`、`vps-work okr +dept-okr --help`、`vps-work okr +employee-okr --help` 对齐。
+
+## 部门 OKR
+
+```bash
+vps-work okr +dept-okr \
+  --okr-period 2026-07 \
+  --department-name "国内渠道" \
+  --row-limit 100
+```
+
+| CLI 参数 | execute 参数 | 说明 |
+|----------|--------------|------|
+| `--okr-period <ym>` | `okr_period` | 必填，`YYYY-MM` |
+| `--department-name <text>` | `department_name` | 部门名称模糊过滤 |
+| `--department-id <id>` | `department_id` | 单个 `hr.department.id` |
+| `--match-dept <text>` | `match_dept` | 部门名或管辖部门模糊过滤 |
+| `--row-limit <n>` | `limit` | 目标条数上限；省略表示不限 |
+
+脚本键为 `department_okr_structured`。
+
+## 员工 OKR
+
+```bash
+vps-work okr +employee-okr \
+  --okr-period 2026-07 \
+  --employee-name "张三" \
+  --row-limit 100
+```
+
+| CLI 参数 | execute 参数 | 说明 |
+|----------|--------------|------|
+| `--okr-period <ym>` | `okr_period` | 必填，`YYYY-MM` |
+| `--employee-name <text>` | `employee_name` | 员工姓名模糊过滤 |
+| `--employee-id <id>` | `employee_id` | 单个 `res.users.id` |
+| `--department-name <text>` | `department_name` | 员工所在部门模糊过滤 |
+| `--row-limit <n>` | `limit` | 目标条数上限；省略表示不限 |
+
+脚本键为 `personal_okr_structured`。
+
+## 共同调试参数
+
+两类命令都支持：
+
+- `--params <json>` / `--params-file <path>`：合并高级参数。
+- `--validate-only` / `--dry-run`：只输出将要发送到 `/v1/execute` 的请求。
+- `--base-url <url>`：覆盖 Vertu 服务地址。
+- `--no-json`：输出紧凑文本。
+
+`--params` 不能替代必填的 `--okr-period`。
+
+## 返回结构
+
+```json
+{
+  "okr_period": "2026-07",
+  "scope": "department",
+  "data_source": "formal-okr-relational",
+  "management_latest_period": "2026-07",
+  "department_tree": [],
+  "objectives": [],
+  "counts": {
+    "performance": 0,
+    "management": 0,
+    "total": 0
+  }
+}
+```
+
+当前响应不分页，也不返回旧契约中的 `query_mode`、`results`、`data`、`rejected_department_ids` 或 `rejected_employee_ids`。
+
+数据源按周期固定分流：2026-07 及以后只读正式 OKR 关系表，2026-01 至 2026-06 只读 PMS 历史表。
+
+## 不存在的旧入口
+
+以下入口不在当前 CLI 中，禁止调用：
+
+- `vps-work okr +org-tree`
+- `vps-work okr +dept-objectives`
+- `--include-sub-departments`
+- `--department-ids`
+- `--employee-ids`

package/skills/vps-pending-approval-assistant/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: vps-pending-approval-assistant
+description: |
+  提供 VPS 审批相关能力：`vps-work approval +wait` / `+pending` / `+my-submitted` / `+my-approved` 拉取本人、部门或全员待办与历史视图，`+logs` 看单证轨迹，`+pass` / `+refuse` 在明确意图下操作当前步骤。在用户查看待我审批、审批流、签核历史、我提交的审批、我已批过的单子、同意或驳回、统计待办类型或整理审批队列时使用。业务单据金额/明细等结构化取数由对应业务域 skill 负责，本技能不下钻业务表。
+---
+
+# 审批助手
+
+## 何时使用
+
+用户需要审批相关能力：查看待我审批、我提交的审批、我已批过的单子、某单的审批轨迹，或在明确意图下通过/拒绝当前步骤。业务单据的金额/明细等结构化取数由对应业务域 skill 负责，本技能不下钻业务表。
+
+## 工作流
+
+1. **待办总览** — **`vps-work approval +wait`**，返回 model_name/res_model/count/res_ids/form_view_id/tree_view_id
+   - 部门负责人：`vps-work approval +pending --scope department --all`
+   - 全员审计：`vps-work approval +pending --scope all --all`（需要 `approvals.pending.all:read`）
+2. **历史审批** — **`vps-work approval +my-submitted`** / **`+my-approved`**。用户未区分时两条都跑
+3. **审批轨迹** — `vps-work approval +logs --res-model <m> --res-id <id>`
+4. **通过/拒绝** — 仅在用户明确表态后调用 `vps-work approval +pass` / `refuse`，带 res_model + res_id
+5. **下钻业务正文** — 用户要看"具体是哪些单子 / 单据金额 / 申请人 / 明细"等：交给对应 `res_model` 的业务域 skill；本技能不在内部对业务模型拼 `--fields` / `--domain` 绕路。若无对应专项 skill，则说明该明细暂不提供。
+
+## 硬约束
+
+- **下钻明细必须切技能**：用户追问业务字段（金额/伙伴/状态/申请人/明细行 等）时，交给对应业务域 skill，不在本技能里查 res_model 业务表
+- **禁止盲构查询**：字段名/关系/枚举必须出现在 **skills/** 文档中；禁止 `vps-work odoo knowledge`；禁止 `_fields` 嗅探；缺口 `POST /ai/skills/v1/feedback`
+- 只向用户展示 model_name 与数量，禁止展示 res_model/res_ids/原始 id 列表
+- web.approval.commit/approvaled 与 wait 同形，fields 完全相同
+- 所有 CLI 以当前用户 ACL 执行，不提供法律/强制性建议
+
+## 常见坑点
+
+| 现象 | 根因 | 正确做法 |
+|------|------|---------|
+| 用户追问"具体是哪些单子 / 金额 / 申请人" | 只看了 model_name 和 count，想在本技能里直接查业务表 | **停下，交给对应 res_model 的业务域 skill**；无对应专项 skill 则说明该明细暂不提供 |
+| 业务字段报错 / 返回空 | 在本技能内对业务模型自行猜字段 | 禁止盲构；交给对应域 skill 后只使用文档已列字段，无文档则 feedback |
+| 审批后状态未变 | 没确认审批轨迹 | 通过/拒绝后查 approval logs 验证 |
+
+## 关联技能
+
+- 未知字段先读对应专项 skill 文档，禁止运行时字段嗅探；下钻前读专项文档
+- **vps-current-user-identity** — 第一人称身份解析，审批视图已自动限定当前用户，无需额外取身份
+
+---
+
+## Feedback protocol (mandatory before answering)
+
+After you finish the user's task with this skill (success or partial failure),
+**write exactly one feedback row** so we can improve docs and parameter schemas:
+
+```
+POST /ai/skills/v1/feedback
+{
+  "skill_key": "<this skill's slug>",
+  "severity": 'warn',
+  "tag": 'detour',
+  "summary": '<≤200-char one-liner in business language>',
+  "proposed_fix": '<optional: where to fix in SKILL.md / reference.md / schema>'
+}
+```
+
+Severity: `info` / `warn` / `blocker`. Tag: `detour` / `missing_doc` /
+`wrong_schema` / `runtime_error` / `unfit_skill` / `slow` / `other`.
+
+Skip the call only when the task ran perfectly and matched docs exactly.
+发现口径或参数问题时，直接更新对应 skill/reference 文档。

package/skills/vps-pending-approval-assistant/reference.md

@@ -0,0 +1,55 @@
+
+# vps-work（本技能）
+
+| 步骤 | CLI（Agent 只用左列） | 实现 |
+|------|----------------------|------|
+| 待办列表 | `vps-work approval +wait` | `odoo_search` · `web.approval.wait` |
+| 部门/全员待办 | `vps-work approval +pending --scope department\|all` | VPS 审批镜像 + 显式数据权限 |
+| 我提交的 | `vps-work approval +my-submitted` | `odoo_search` · `web.approval.commit` |
+| 我已审批的 | `vps-work approval +my-approved` | `odoo_search` · `web.approval.approvaled` |
+| 通过 | `vps-work approval +pass --res-model … --res-id …` | `odoo_approval_pass` |
+| 拒绝 | `vps-work approval +refuse …` | `odoo_approval_refuse` |
+| 轨迹 | `vps-work approval +logs …` | `odoo_approval_logs` |
+
+## 三种视图的通用查询
+
+| 视图 | 用途 | 说明 |
+|------|------|------|
+| `web.approval.wait` | 待我审批 | 当前活跃步骤中我是审批人且未操作 |
+| `web.approval.commit` | 我提交的审批 | 我提交的所有审批（基于 `web.approval.log` action=commit） |
+| `web.approval.approvaled` | 我已审批的 | 我审批通过的所有单据（基于 `web.approval.log` action=accept） |
+
+- 三个视图共享相同结构：`model_name`、`res_model`、`count`、`res_ids`、`form_view_id`、`tree_view_id`。
+- `vps-work approval +wait` / `+my-submitted` / `+my-approved` 已自动限定当前用户并返回上述字段，无需手写 domain。
+
+## 历史查询载荷示例
+
+- `model_name`: `web.approval.commit` 或 `web.approval.approvaled`
+- `domain`: `[]`
+- `fields`: `["model_name","res_model","count","res_ids","form_view_id","tree_view_id"]`
+
+## 日志与通过/拒绝
+
+- **`vps-work approval +logs`**：`res_model`、`res_id`。
+- **`vps-work approval +pass` / `+refuse`**：`res_model`、`res_id`；`+pass` 可选 `proposal`。
+
+## 下钻明细必须切技能
+
+用户从"审批待办/历史"进入"具体是哪些单子 / 金额多少 / 谁提交的 / 明细行" 这一步时，**本技能就到此为止**：
+
+1. **交给对应 `res_model` 的业务域 skill** —— 由它负责业务模型取数；若无对应专项 skill，则说明该明细暂不提供。
+2. 匹配 **Features** 中与 `res_model` 对应的专项 skill，读其 `reference.md` / `references/*.md` 中的字段与 domain 示例。
+3. 仅使用文档已列字段，通过对应域命令（`vps-work <域> +…`）取数。
+
+**禁止行为**：
+
+- 在本技能里直接对业务 `res_model` 自行拼字段绕路。
+- 使用未在 `skills/` 文档出现的字段名（典型反例：未核对就写 `amount_total`、`partner_id`、`state`）。
+- `vps-work odoo knowledge`、sandbox `_fields` 嗅探。
+
+## 输出结构（对用户）
+
+1. 待办/历史：仅文档类型标签 + 数量。
+2. 轨迹：时间顺序叙述，无内部 id。
+3. 其他业务信息：经数据技能路径取数后，用业务语言转述。
+4. 可给简短核对建议，不编造数据。

package/skills/vps-product/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: vps-product
+description: "VPS 商品与供应链：商品销量、销额、订单数、IOT、商品折扣、日/周/月趋势、款式环比，以及库存、价格、发货、齐套物料、机头库存、在库激活和异常 IMEI。用户问某商品/系列/款式卖了多少时使用 `vps-work sales +trend` 等销售聚合；用户问普通库存、价格、发货或设备异常时使用 `vps-work product +…`。触发词：商品销量、商品销额、IOT、折扣、款式、库存、价格、发货、齐套、BOM、机头、在库激活、仓位异常、异常设备、异常 IMEI。"
+---
+
+# product（产品与供应链）
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../vps-shared/SKILL.md`](../vps-shared/SKILL.md)，其中包含认证、当前用户与 `+` 快捷约定。**
+
+## Shortcuts（推荐优先使用）
+
+Shortcut 封装产品与供应链常用查询（`vps-work product +<verb> [flags]`），统一经 Vertu 数据视图取数，返回 `{view, columns, rows, pagination}`；库存和机头库存还会返回 `summary.total_quantity`。返回 `pagination.has_more=true` 时必须用 `--page <next_page>` 继续查询，不要把第一页当全量。
+
+返回结构中 `columns` 是字段元数据和推荐展示顺序，不是业务数据；即使 `rows=[]`，也用它理解该查询会返回哪些字段。回答用户时引用 `rows` 里的值，价格查询重点看 `产品编码`、`商品名称`、`销售标准价_CNY`、`销售标准价_USD`、`销售标准价_HKD`。
+
+| Shortcut | 说明 | data-view |
+|----------|------|-----------|
+| `+inventory` | 库存数据：分仓/门店库存、门店明细 | `inventory-data` |
+| `+inventory-by-vsn` / `+vsn-inventory` | 按 VSN 精确查询商品、内部/在途库存、仓库和完整库位 | `/v1/product/inventory-by-vsn` |
+| `+price` | 商品价格：标准价/海外价/国内价，不依赖库存 | `product-price` |
+| `+delivery` | 发货数据：出库单、发货数量、收货部门 | `delivery-data` |
+| `+kit-materials` | 齐套物料：BOM 可用库存与商品分类 | `kit-materials` |
+| `+phone-head-inventory` | 机头库存：机头良品、内存、颜色与库存部门 | `phone-head-inventory` |
+| `+abnormal-location` | 仓位异常库存：实物、在途、门店库存和异常 IMEI | `/v1/product/abnormal/location` |
+| `+abnormal-location-list` | 异常统计仓位与 vps-ep 默认选择 | `/v1/product/abnormal/location-list` |
+| `+abnormal-details` | 按 IMEI 下钻未处理异常原因 | `/v1/product/abnormal/details` |
+| `sales +trend` | 跨域查询商品/系列/款式销量、销额、订单、折扣、日周月趋势与环比 | `/v1/execute: monthly_daily_trend` |
+
+设备异常三个快捷命令的完整流程和口径见 [`../vps-device-abnormal-statistics/SKILL.md`](../vps-device-abnormal-statistics/SKILL.md)。普通库存仍使用 `+inventory`，不要用异常仓位接口代替全量库存视图。
+
+## 参数（filter）
+
+filter 为模糊包含（ILIKE），留空则不过滤。分页参数适用于所有 shortcut：`--page` 默认 1，`--limit` 默认 100，`--page-size` 或 `--limit` 上限 1000。通用调试参数：`--base-url`、`--endpoint`、`--params`、`--params-file`、`--validate-only`、`--dry-run`、`--no-json`。
+
+| Shortcut | flags |
+|----------|-------|
+| `+inventory` | `--product-code` `--product-name` `--product-family`（产品） `--product-category`（商品大类） `--product-class`（商品分类） `--product-subcategory`（商品细类） `--product-color`（颜色） `--product-material`（材质） `--product-color-material`（颜色材质） `--product-phone-version`（手机版本） `--store-detail` |
+| `+inventory-by-vsn` | `--vsn` 必填；精确匹配，多个 VSN 用逗号或空白分隔，最多 100 个 |
+| `+inventory --group-by` | 仅库存支持聚合：`product` `product_category` `product_class` `product_subcategory` `product_color` `product_material` `store_detail` `department` |
+| `+price` | `--product-code` `--product-name` `--product-family` `--product-category` `--product-class` `--product-subcategory` `--product-color` `--product-material` `--product-color-material` `--product-phone-version` `--price-region`（`standard`/`domestic`/`overseas`） |
+| `+delivery` | `--product-code` `--product-name` `--product-family` `--product-category` `--product-class` `--product-subcategory` `--product-color` `--product-material` `--product-color-material` `--product-phone-version` `--warehouse` `--department` `--start-date` `--end-date` `--launch-start-date` `--launch-end-date` |
+| `+kit-materials` | `--product-name` `--product-code` |
+| `+phone-head-inventory` | `--product-name` `--department` |
+
+所有产品 shortcut 都支持 `--filters-json '<json>'` 或 `--filters-json @./filters.json` 合并高级过滤条件；显式 flag 与 `--filters-json` 可混用。不要给 `+delivery`、`+kit-materials`、`+phone-head-inventory` 加 `--group-by`；服务端只支持库存聚合。
+
+## 口径
+
+| Shortcut | 口径 |
+|----------|------|
+| `+inventory` | 与 vps-ep 商品看板统一使用 Odoo `mv_inventory` 可用库存，只计 `产成品`、`半成品`且`库存数量 > 0`；商品分类、大类、细类和门店归属以该库存视图为准，销售标准价及颜色/材质/版本由商品维表补充。 |
+| `+inventory-by-vsn` | 直接查询 Odoo `stock_lot → stock_quant → stock_location → stock_warehouse`；仅返回数量大于零的内部/在途库位，状态区分 VSN 不存在、不在内部/在途库存、库存中和在途；可用数量=库存数量-预留数量；库位品质区分良品库、非良品库、待检库和在途库。 |
+| `+price` | 基于商品价格维表，直接返回 `销售标准价_CNY/USD/HKD`；不依赖是否有库存。`--price-region overseas` 表示海外版价格，`domestic` 表示国内版价格，`standard` 表示标准区域。 |
+| `+delivery` | 基于 `report_sale_shipment`，关联发货仓、收货部门和完整商品维表；排除不良品库和 `%-YP` 样品编码。可按商品大类/细类/材质/手机版本/上市时间/发货仓/发货日期过滤。 |
+| `+kit-materials` | 基于指定 BOM/物料仓的 `stock_quant` 汇总，输出 BOM 可用库存和商品层级。 |
+| `+phone-head-inventory` | 只查商品大类为手机辅料且名称含机头的库存，排除库存/JD/维修等库位，派生良品判断、内存和机头颜色。 |
+
+## 自然语言映射
+
+商品自然语言要拆成稳定 filter，不要把多个词硬塞进 `--product-name`。但如果用户给的是完整商品名称，尤其是带系列、套装、材质、颜色、内存、版本的全称，查价格优先用 `+price --product-name "<完整商品名>"` 精确包含匹配。常见映射：
+
+| 用户说法 | 推荐 filter |
+|----------|-------------|
+| 大折叠 | `--product-subcategory "VERTU ALPHAFOLD"`，通常再加 `--product-family 产成品 --product-category 手机` |
+| 手机 / 手机明细 | `--product-category 手机` |
+| IOT / IOT配件 | 销售用 `sales +trend --product-category IOT配件`；库存用 `product +inventory --product-class IOT配件` |
+| 小牛皮 | `--product-material 小牛皮` |
+| 鳄鱼皮 | `--product-material 鳄鱼皮` |
+| 黑色 | `--product-color 黑色` |
+| 颜色材质 / 颜色材质原值 | `--product-color-material <颜色材质>` |
+| 海外版 / 国内版 | `--product-phone-version 海外` / `--product-phone-version 国内` |
+| 从仓库发出 / 发货仓 | `--warehouse 发货仓`；如果用户指定仓名，用 `--warehouse <仓名>` |
+| 发货日期范围 | `--start-date YYYY-MM-DD --end-date YYYY-MM-DD` |
+| 上市时间范围 | `--launch-start-date YYYY-MM-DD --launch-end-date YYYY-MM-DD` |
+| 海外版价格 | `+price --price-region overseas` |
+| 国内版价格 | `+price --price-region domestic` |
+| 某门店库存 | `--store-detail <门店名>` |
+
+这些别名是业务规则，不是实时从数据库推断。如果用户的俗称不确定，先用聚合查询确认候选商品细类，例如 `vps-work product +inventory --product-category 手机 --group-by product_subcategory --limit 100`。
+
+用户给出 VSN/IMEI 并询问“在哪里、是否在库、可用库存”时，使用 `+inventory-by-vsn`，不要使用普通 `+inventory` 的空 `vsn` 展示列，也不要用仅返回未处理异常设备的 `+abnormal-details` 代替。
+
+## 商品销量、销额与趋势
+
+商品“卖了多少”属于销售事实，不要用库存变化或发货数量反推。使用 `vps-work sales +headline-kpi` 查询汇总，使用 `vps-work sales +trend` 查询日/周/月趋势和环比；更完整的业绩口径读取 `sale-performance-query`。
+
+月维度“最新组织渠道 × 款式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`：当月销量、销额。
+- `orders`：去重后的销售单数；同一销售单有多条商品或分摊记录时只计 1。
+- `product_order_count`：与 vps-ep 商品月报 `total_orders` 对齐的销售/分摊明细行数，即 SQL `COUNT(*)`；它不是去重订单数。用户明确问“商品页订单数”或要求与 vps-ep 对数时使用本字段。
+- `previous_qty/previous_amount`：上月销量、销额。
+- `previous_product_order_count`：上一比较周期的商品页口径订单行数。
+- `mom_qty_rate/mom_amount_rate`：月环比。
+- `group_name`：最新组织渠道；`breakdown_name`：款式1。
+- 必须核对响应 `filter.grain/group_by/breakdown_by` 和全部商品过滤条件，再把结果表述为指定商品或款式的业绩。
+
+### IOT 订单、库存与折扣
+
+IOT 商品分类以商品维表为准，包含耳机、戒指、腕表、**手链**、钢笔、录音笔，以及配置中的打火机、眼镜等 IOT 细类。不要仅按商品名包含 `IOT`，也不要漏掉手链。
+
+查询指定期间 IOT 销售、两种订单数和折扣：
+
+```bash
+vps-work sales +trend \
+  --start-date 2026-07-01 --end-date 2026-07-29 \
+  --grain month --group-by product_category \
+  --product-category IOT配件
+```
+
+折扣计算只统计非置换行。置换包括 Odoo `is_barter_line=true`，历史数据还按出货性质 `置换` / `以旧换新` 识别。
+
+- `discount_standard_amount_* = Σ(标准单价 × COALESCE(分摊比例数量, 数量))`
+- `discount_actual_amount_* = Σ(实际业绩)`
+- vps-ep 折扣口径：`discount_rate_* = 实际业绩 / 标准价金额`；`discount_rate_*_pct` 是百分数，例如 `73.9` 表示 73.9%。
+- 用户原式“标准价金额 / 实际业绩”对应 `standard_to_actual_ratio_*`；不要把这个倒数误报成 vps-ep 折扣率。
+- 后缀 `incl_agent`：含代理；后缀 `excl_agent`：排除一级部门 `海外渠道`、二级部门 `国内代理`及销售行 `渠道=代理`。
+
+查询 IOT 可用库存：
+
+```bash
+vps-work product +inventory \
+  --product-class IOT配件 \
+  --group-by product_category
+```
+
+若用户要求与 vps-ep 商品页核对，必须同时说明：销售 `product_order_count` 是明细行数，`orders` 才是去重订单数；库存只统计 `mv_inventory` 中正数的产成品/半成品。不要把两种订单口径或旧的原始 `stock_quant` 库存混在一起。
+
+## 价格查询
+
+查商品价格优先用 `+price`，不要用库存或发货接口反推价格。`+price` 不依赖是否有库存，结果的 `价格区域` 可能是 `standard`、`domestic` 或 `overseas`。
+
+完整商品名查价：
+
+```bash
+vps-work product +price \
+  --product-name "VERTU ALPHAFOLD-黑品质套装款-鳄鱼皮-樱花粉-1TB-国内" \
+  --limit 20 \
+  --page 1
+```
+
+结构化条件查价：
+
+```bash
+vps-work product +price \
+  --product-category 手机 \
+  --product-subcategory "VERTU ALPHAFOLD" \
+  --product-material 鳄鱼皮 \
+  --product-color 樱花粉 \
+  --product-phone-version 国内 \
+  --limit 20 \
+  --page 1
+```
+
+若用户明确问“国内版/海外版价格口径”，追加 `--price-region domestic` 或 `--price-region overseas`。如果结构化条件返回多条，按 `商品名称`、`颜色材质`、`产品编码` 再确认，不要自行合并价格。
+
+例如“黑色小牛皮的大折叠库存情况”：
+
+```bash
+vps-work product +inventory \
+  --product-family 产成品 \
+  --product-category 手机 \
+  --product-subcategory "VERTU ALPHAFOLD" \
+  --product-material 小牛皮 \
+  --product-color 黑色 \
+  --group-by store_detail
+```
+
+## 示例
+
+```bash
+vps-work product +inventory --product-name "AGENT Q" --limit 50
+vps-work product +inventory --product-name "AGENT Q" --group-by product_subcategory
+vps-work product +inventory --product-category 手机 --product-subcategory "VERTU AGENT Q" --page-size 20
+vps-work product +inventory --product-subcategory "VERTU ALPHAFOLD" --product-material 小牛皮 --product-color 黑色 --group-by store_detail
+vps-work product +inventory --product-name "ALPHAFOLD" --product-color-material 玄铁黑 --product-phone-version 国内
+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 +inventory --store-detail 三亚太古
+vps-work product +inventory-by-vsn --vsn VSN001
+vps-work product +inventory-by-vsn --vsn VSN001,VSN002
+vps-work sales +trend --period this_month --grain month --group-by product_category --product-category IOT配件
+vps-work product +inventory --product-class IOT配件 --group-by product_category
+vps-work product +delivery --product-category 手机 --warehouse 发货仓 --limit 20
+vps-work product +delivery --filters-json '{"product_category":"手机","warehouse":"发货仓","product_phone_version":"国内"}' --limit 20
+vps-work product +kit-materials --product-name IRONFLIP
+vps-work product +phone-head-inventory --product-name QUANTUM --department 工厂
+```
+
+## 验证命令
+
+```bash
+vps-work product --help
+vps-work product +inventory --help
+vps-work product +inventory --product-name "AGENT Q" --validate-only
+```
+
+> **重要**：库存、价格、发货和供应链查询使用 `vps-work product +…`；销量、销额和销售趋势使用 `vps-work sales +…`，完整业绩口径读取 `sale-performance-query`；OKR 走 `vps-okr`。
+
+## 权限与限制
+
+| 能力 | 说明 |
+|------|------|
+| 认证 | Agent 使用宿主 app_key，禁止账号密码登录；人工会话须具备数据查询权限 |
+| `vps-work product +…` | 产品与供应链数据唯一推荐入口 |
+| `product.all_categories:read` | 用户会话只有具备该 scope 才能查看全部产品大类；否则商品类 data-view 强制限制为 `产成品`、`半成品`。 |
+| VSN 库存与设备异常统计 | `+inventory-by-vsn` 和三个 `+abnormal-…` 命令只允许在职内部员工访问，且必须明确分配角色 `vps_device_abnormal_analyst` 并具备显式 scope `product.device_abnormal:read`；外部/经销商账号和仅有 `admin:*` 的管理员不放行。 |
+| 服务 API Key | 无会话用户的系统调用按受信调用处理，可查看全部产品大类。 |
+
+`--params` 可以合并高级参数，但服务端只会使用当前 data-view 已启用的 filter key；未知 key 会被忽略，不能据此判断过滤已经生效。
+
+## 性能提示
+
+库存视图读取 `mv_inventory` 并关联商品价格、币种、颜色、材质、手机版本等派生字段。因此按维度聚合的库存查询可能比价格查询慢。查价格用 `vps-work product +price --help`，查“有没有货/在哪里有货”用 `vps-work product +inventory --help`。库存查询应按帮助中列出的商品编码、商品名或分类参数缩小范围，并检查 `pagination.has_more` 后继续翻页。