vps-work 1.0.0

package/skills/vps-daily-sales-report/reference.md

@@ -0,0 +1,188 @@
+
+# 编排手册 · 公司总销日报
+
+## 一、脚本一览表
+
+| 脚本 | 何时调用 | 如何调用 | 产物 |
+|------|---------|---------|------|
+| `headline_kpi` | 问"今天/本月/上月/任意时段销售额多少" | `vps-work sales +headline-kpi`（默认今日）或 `vps-work sales +headline-kpi --period last_month --dept-l1 线上事业部` | 周期销量/销额/订单数 + 可选当日单点 |
+| `dept_breakdown` | 问"各部门/销售员/产品线销售额排名" | `vps-work sales +dept-breakdown --period this_month --group-by salesperson --limit 10` | 维度 × 周期销量销额 + 可选当日 |
+| `customer_sales_mix` | 问“本月新老客销售占比 / 新客老客结构” | `vps-work sales +customer-mix --period this_month` | 新客、老客、未分类销售额；总额占比、已分类占比、分类覆盖率 |
+| `dept_comparison` | 问"环比/同比怎么样" | `vps-work sales +dept-comparison --period this_quarter --group-by org_channel` | 部门/组织渠道/商品维度 × 当期/上期/去年同期销量销额 + 环比%/同比% |
+| `dept_target_achievement` | 问"目标完成多少了 / OKR达成率" | `vps-work sales +target-achievement --period last_month --limit 15` | 部门 × 期间目标/实际/达成率；默认与管理端“部门业绩目标”同源、按 `match_dept`，一级/二级合并表需传 `group_by` |
+| `dept_monthly_okr` | 问"部门月度OKR明细 / 目标来源" | `vps-work sales +dept-monthly-okr --period this_month --limit 100` | 默认返回管理端“部门业绩目标”同源的 `部门OKR_1` 月度明细；可显式切换 Postgres 新表 |
+| `with_without_deposit_breakdown` | 问"含/不含定金的销售额" | `vps-work sales +deposit-breakdown --period this_month` | 部门 × 期间定金额/不含定金销额/合计销额；定金口径走销售行 `"定金"='是'` |
+| `refund_summary` | 问"退款/退换货明细"，可自定义订单类型字典 | `vps-work sales +refund-summary --period this_month --dept-l1 海外事业部` | 退款金额/单数 + 退换货金额/单数 + 部门 Top |
+| `service_dept_sales_summary` | 问"权益部/服务部销售业绩" | `vps-work sales +service-sales --period last_n_days --days 30` | 笔数/金额/经办人 Top |
+| `monthly_daily_trend` | 问"按日/周/月的销售走势、环比、渠道×款式明细、IOT 订单或商品折扣" | `vps-work sales +trend --period this_year --grain month --group-by org_channel --breakdown-by product_style1` | 日/周/月 × 主维度 × 明细维度，含销量、销额、去重订单、商品页订单行数、含/不含代理折扣、上期、环比、累计、同期 |
+| `employee_ranking_top_bottom` | 问"销售员 TOP10 / 末位 / 红黑榜" | `vps-work sales +ranking --period this_month --metric amount --top-n 10 --bottom-n 10` | TOP+BOTTOM 销售员双榜 |
+| `order_list` | 问"订单明细/某商品订单/某客户订单/物流单号对应订单" | `vps-work sales +orders --period this_month --logistics-no SF123` | 订单号、商品、`商品码`、客户脱敏信息、金额、分摊比例、客户来源、二级客户来源、最新发货日期、物流单号摘要 |
+| `account_sales_detail` | 问“某会计科目对应哪些销售单明细” | `vps-work sales +account-orders --account-code 6001 --period this_month` | 科目行借贷余额、凭证、关联方式、销售订单行与发票行金额 |
+| `reconciled_sales_receipts` | 问“最近30天已对账销售单收了哪些款” | `vps-work sales +reconciled-receipts --order-types sale,service --invoiced true` | 按销售单、收款方式和收款主体聚合的收款明细；退差价只扣单据金额，真实退货整单排除 |
+| `sales_invoice_status` | 问“某销售单是否申请开票、审批到哪一步” | `vps-work sales +invoice-status --order-names SO001,SO002` | 精确映射销售单与直接/联合开票申请，返回真实申请状态；单号必填，最多100个 |
+| `order_finance` | 问“某销售单的开票申请、发票、会计凭证和付款状态” | `vps-work sales +order-finance --order-no SO001` | 返回订单财务全景；精确单号必填，并按当前用户销售数据范围校验 |
+| `order_logistics` | 明确问"某订单/某物流单号/某出库单号的发货明细" | `vps-work sales +order-logistics --order-no SO123` 或 `vps-work sales +order-logistics --logistics-no SF123` | 订单号、下单时间、销售员、客户掩码信息、出库单、物流单号、发货商品与收货信息 |
+
+## 二、共享时间窗口参数
+
+所有脚本统一支持以下参数。CLI 用 `--period`、`--start-date`、`--end-date`；execute/API 使用 `period`、`start_date`、`end_date`。优先级为日期参数 > `period` > Shortcut 默认值。服务端未收到 `period/start_date/end_date` 时默认 `this_month`；CLI Shortcut 会为不同命令设置更贴近场景的默认值。
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| `period` | string | `today / yesterday / this_month / last_month / this_quarter / last_quarter / this_year / last_year / last_n_days / custom`，也可直接传 `YYYY-MM-DD` 表示单日；默认 `this_month` |
+| `start_date` | string | YYYY-MM-DD；单独给表示单日，和 `end_date` 同时给表示闭区间；CLI flag 为 `--start-date` |
+| `end_date` | string | YYYY-MM-DD；单独给表示单日，和 `start_date` 同时给表示闭区间；CLI flag 为 `--end-date` |
+| `days` | int | 仅当 `period=last_n_days` 时使用，默认 7 |
+
+`period=custom` 必须同时提供 `start_date` 与 `end_date`（CLI: `--start-date` 与 `--end-date`），否则报错。
+
+## 三、共享部门过滤参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| `dept_l1` | string | 一级部门精确匹配 |
+| `dept_l2` | string | 二级部门精确匹配 |
+| `dept_l3` | string | 三级部门精确匹配 |
+| `dept_l4` | string | 四级部门精确匹配 |
+| `dept_l5` | string | 五级部门精确匹配 |
+
+四级互相 AND，缺省=不过滤。
+
+## 四、脚本独有参数
+
+| 参数名 | 类型 | 默认值 | 适用脚本 | 说明 |
+|--------|------|--------|---------|------|
+| `product_subcategory` | string | "" | 销售 KPI / 明细 / 对比 / 趋势 | 单个商品细类精确过滤 |
+| `product_subcategories` | string/list | [] | 销售 KPI / 明细 / 对比 / 趋势 | 多个商品细类精确过滤 |
+| `product_category` | string | "" | 销售 KPI / 明细 / 对比 / 趋势 | 商品分类精确过滤 |
+| `product_major_categories` | string/list | [] | 销售 KPI / 明细 / 对比 / 趋势 | 商品大类精确过滤 |
+| `product_style` | string | "" | 销售 KPI / 明细 / 对比 / 趋势 | `款式` 精确过滤；高定传 `高定` |
+| `product_style_details` | string/list | [] | 销售 KPI / 明细 / 对比 / 趋势 | `款式1` 精确过滤；金钻归一为 `4金/3钻` |
+| `smart_wearable` | bool | false | 销售 KPI / 明细 / 对比 / 趋势 | 戒指/手链 + vps-ep 智能穿戴系列白名单 |
+| `include_today` | bool | true | headline_kpi / dept_breakdown | 是否额外输出当日 KPI |
+| `group_by` | string | "dept_l2" / 自动 | dept_breakdown / dept_comparison / monthly_daily_trend | 聚合维度：dept_l1/l2/l3/l4 / org_channel / salesperson / product_subcategory / product_category / product_style / product_style1 / customer_category；`org_channel` 是最新组织架构渠道 |
+| `auto_next_level` | bool | true | dept_breakdown | 用户没传 group_by 时按已传部门层级 +1 自动选 group_by |
+| `target_proration` | bool | 自动 | dept_target_achievement | OKR 日权重折算：不传时自动判断（月/季/年=不折算，日/周/custom=折算）；显式传则优先 |
+| `match_dept` | string | "" | dept_target_achievement / dept_monthly_okr | 匹配部门模糊过滤 |
+| `okr_source` | string | "legacy" | dept_target_achievement / dept_monthly_okr | 部门目标源；默认 `部门OKR_1`，核对迁移新表时传 `postgres` |
+| `refund_types` | list[string] | ["退货退款","仅退货","退款","退货"] | refund_summary | 退款订单类型清单 |
+| `exchange_types` | list[string] | ["换货"] | refund_summary | 退换货订单类型清单 |
+| `person` | string | "" | service_dept_sales_summary | 经办人 ILIKE 模糊匹配 |
+| `include_cumulative` | bool | true | monthly_daily_trend | 是否输出累计销额销量 |
+| `grain` | string | day | monthly_daily_trend | `day / week / month` |
+| `breakdown_by` | string | "" | monthly_daily_trend | 第二明细维度；高定系列明细用 `product_style1` |
+| `include_comparison` | bool | true | monthly_daily_trend | 是否输出上期销量/销额及日/周/月环比 |
+| `include_yoy` | bool | false | monthly_daily_trend | 是否对齐去年同期 |
+| `metric` | string | "amount" | employee_ranking_top_bottom | amount / qty / orders |
+| `top_n` / `bottom_n` | int | 10 | employee_ranking_top_bottom | TOP / BOTTOM 各取 N |
+| `exclude_zero` | bool | true | employee_ranking_top_bottom | 末位榜是否排除 0 |
+| `order_no` | string | "" | order_list / order_logistics | 订单号；`order_logistics` 中也可匹配出库单号 |
+| `logistics_no` | string | "" | order_list / order_logistics | 物流单号或出库单号；订单查询用它反查订单摘要 |
+| `department` | string | "" | order_logistics | 兼容旧用法；部门/销售员维度一般优先用 `order_list` |
+| `salesperson` | string | "" | order_list / order_logistics | 销售员姓名 / 登录名包含匹配；批量订单优先用 `order_list` |
+| `user_id` | int | "" | order_logistics | 兼容旧用法：销售员 Odoo 用户 ID 精确匹配 |
+| `fuzzy` | bool | false | order_logistics | 订单号相关字段是否包含匹配 |
+| `include_deposit` | bool | false | headline_kpi / dept_breakdown / customer_sales_mix / dept_comparison / dept_target_achievement / monthly_daily_trend / employee_ranking_top_bottom / refund_summary | 业绩口径：false=不含定金（默认，业绩看板口径），true=含定金；`service_dept_sales_summary` 当前固定含定金 |
+| `order_types` | string/list | sale,service,repair,jky | reconciled_sales_receipts | 销售单、销售服务单、销售维修单、吉客云销售订单；固定查询最近30个自然日 |
+| `order_names` | string/list | [] | reconciled_sales_receipts | 销售单号精确匹配；指定单号也不放宽30天范围 |
+| `salesperson` / `department` / `company` | string | "" | reconciled_sales_receipts | 对对应名称做 ILIKE 包含匹配 |
+| `invoiced` | bool | 未限制 | reconciled_sales_receipts | true=已有开票申请，false=无开票申请 |
+| `exclude_payment_methods` | string/list | 京东自营,商场代收 | reconciled_sales_receipts | 收款方式名称关键词排除；显式空数组表示不排除 |
+| `offset` | int | 0 | reconciled_sales_receipts | SQL行偏移，0-4999；下一页使用 `pagination.next_offset` |
+| `limit` | int | 20/30/100/500 | 全部 | 返回行数上限；`dept_target_achievement` 默认 500 |
+| `page` | int | 1 | 返回列表的脚本 | 页码，从 1 开始；配合 `pagination.next_page` 翻页 |
+
+## 五、CLI Shortcut 默认时间
+
+| Shortcut | 默认时间 |
+|----------|----------|
+| `+headline-kpi` | `today` |
+| `+service-sales` | `last_n_days`，未传 `--days` 时为 30 天 |
+| 其他日报/目标类 Shortcut | `this_month` |
+
+## 六、CLI 调用示例
+
+### bash / zsh
+
+```bash
+# 今日公司业绩（快捷命令，推荐）
+vps-work sales +headline-kpi
+
+# 公司本月核心 KPI
+vps-work sales +headline-kpi --period this_month
+
+# 上月线上事业部
+vps-work sales +headline-kpi --period last_month --dept-l1 线上事业部
+
+# 自定义时间段（或用 --params 合并 JSON）
+vps-work sales +headline-kpi --params '{"start_date":"2026-01-01","end_date":"2026-03-31"}'
+
+# 销售员排名 Top10
+vps-work sales +dept-breakdown --period this_month --group-by salesperson --limit 10
+
+# 本季度环比同比
+vps-work sales +dept-comparison --period this_quarter
+
+# 上月线下事业部目标达成
+vps-work sales +target-achievement --period last_month --dept-l1 线下事业部
+
+# 部门 OKR 明细默认与管理端页面同源；返回 pagination，有更多页时继续 --page
+vps-work sales +dept-monthly-okr --period this_month --limit 100 --page 1
+
+# 显式核对迁移后的 Postgres 目标表
+vps-work sales +dept-monthly-okr --period this_month --okr-source postgres --limit 100
+
+# 按物流单号反查订单
+vps-work sales +orders --logistics-no SF123 --period this_month
+
+# 某物流单号发货明细
+vps-work sales +order-logistics --logistics-no SF123
+
+# 最近30天已对账销售收款明细；显式空值表示不排除任何收款方式
+vps-work sales +reconciled-receipts --order-types sale,service --exclude-payment-methods '' --limit 100
+```
+
+### Windows PowerShell
+
+```powershell
+'{"period":"last_month","dept_l1":"线上事业部"}' | Set-Content -Encoding utf8 ./p.json
+vps-work sales +headline-kpi --params '@./p.json'
+```
+
+### 服务接口
+
+```http
+POST /v1/execute
+Content-Type: application/json
+
+{
+  "skill_key": "vps-daily-sales-report",
+  "script_key": "reconciled_sales_receipts",
+  "params": {
+    "order_types": ["sale", "service", "repair", "jky"],
+    "limit": 500,
+    "offset": 0
+  }
+}
+```
+
+成功结果中的 `source` 回显服务 `base_url`、Odoo 数据库 `db` 和执行 `login`；`rows` 为明细，继续翻页使用 `pagination.next_offset`。
+
+## 七、跨 shell 传参约定
+
+| 场景 | bash / zsh | PowerShell 等效 |
+|------|-----------|----------------|
+| 参数含中文 | `--params '{"k":"v"}'`（单引号包） | 写 `.json` 后 `--params '@./p.json'` |
+| 无参数 | 不传，或 `--params '{}'` | `--params '@./empty.json'` |
+| 管道串联 | `echo '{"k":"v"}' \| vps-work … --params '@-'` | `'{"k":"v"}' \| vps-work … --params '@-'` |
+
+## 八、OKR计算规则
+
+- `dept_target_achievement` 默认目标源为管理端“部门业绩目标”同源的 `部门OKR_1`；核对迁移后的新表时传 `okr_source=postgres` / `--okr-source postgres`。
+- `dept_target_achievement` 默认按 `match_dept` 输出多行目标达成，不是单行公司汇总。
+- 汇总公司整体目标时必须包含零销售但有目标的行；任何排除项、分页截断、Top N 或权限范围限制都必须在回答中说明。
+- 一级/二级部门 OKR 需要显式传 `group_by`：`--params '{"group_by":"dept_l1","limit":500}'` 或 `--params '{"group_by":"dept_l2","limit":500}'`。
+- 核对目标来源时用 `+dept-monthly-okr` 查看与管理端页面一致的月度目标明细。
+- 返回 `pagination` 的脚本必须检查 `has_more`；为 true 时继续请求 `page=next_page`。
+- **达成率 = 实际销额 / 期间目标 × 100**
+- 月/季/年 → 整月目标不折算；日/周/custom → 按覆盖天数加权折算

package/skills/vps-device-abnormal-statistics/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: vps-device-abnormal-statistics
+description: "查询 Vertu 设备在库激活与异常统计：按仓位查看总库存、实物库存、在途、门店库存和异常 IMEI，查询仓位选项，以及按 IMEI 下钻未处理异常原因、销售、激活、出库和维修信息。用户提到在库激活、仓位异常、异常设备、异常 IMEI、激活异常或设备异常明细时使用 `vps-work product +abnormal-…`。"
+---
+
+# 设备异常统计
+
+**CRITICAL — 开始前 MUST 先读取 [`../vps-shared/SKILL.md`](../vps-shared/SKILL.md)。**
+
+## 命令
+
+| 用户意图 | 命令 |
+| --- | --- |
+| 查看仓位异常库存汇总 | `vps-work product +abnormal-location` |
+| 搜索仓位、获取仓位 ID 或默认仓位 | `vps-work product +abnormal-location-list` |
+| 按异常 IMEI 下钻未处理原因 | `vps-work product +abnormal-details` |
+
+接口字段、异常标识和响应口径见 [`references/api.md`](references/api.md)。只有需要解释字段或异常原因时再读取该文件。
+
+## 推荐流程
+
+1. 用户明确给出仓位 ID 时，直接传 `--location-ids`。
+2. 用户只给仓位名称时，先用 `+abnormal-location-list --location-name` 确认仓位及 ID；名称足够明确时也可直接用 `+abnormal-location --location-name` 模糊查询。
+3. 用户说“和 vps-ep 在库激活页面一样”或“默认门店”时，使用 `+abnormal-location --default-selected`。页面默认范围不是“不传筛选查全部”，而是仓位列表中 `is_selected=true` 的仓位。
+4. 下钻明细时，从仓位结果的 `abnormal_imeis` 去重后传给 `+abnormal-details`。返回只包含仍有未处理异常原因的 IMEI，条数可以少于请求数量。
+
+```bash
+vps-work product +abnormal-location-list --location-name 上海
+vps-work product +abnormal-location --location-ids 27081,11169
+vps-work product +abnormal-location --default-selected
+vps-work product +abnormal-details --imeis 860000000000001,860000000000002 \
+  --stat-date 2025-09-01 --end-date 2026-07-02
+vps-work product +abnormal-details --imeis @./imeis.json --exception-type address_exception
+```
+
+## 结果解释
+
+- 仓位查询返回 `summary` 和 `rows`。`summary.abnormal_imei_count` 是所有行去重后的异常 IMEI 数；库存字段是行级数值求和。
+- `reported_total` 保留源接口的 `data.total`。源接口当前可能返回 `0`，实际行数以 `summary.row_count` 为准。
+- 明细查询返回 `rows` 裸数组的 CLI 规范化结果；`total` 是实际异常明细条数。
+- 在途设备优先归为“已激活在途”，不要再同时报告为“在库无销售”或“无库存无销售”。
+- `stat_date` / `end_date` 影响销售、OTA、VPUSH 等时间过滤；地址异常需要 `--exception-type address_exception`，此时 OTA 数据有特殊保留口径。
+
+## 安全与边界
+
+- 三个命令必须经 vps-service 登录鉴权代理访问，不得绕过代理直连上游。`--base-url` 仅用于指定 vps-service 地址。
+- 当前身份必须是在职内部员工，并在授权中心明确分配角色 `vps_device_abnormal_analyst`（VPS 设备异常分析），同时取得显式 scope `product.device_abnormal:read`。外部/经销商账号、普通员工、数据分析员和仅有 `admin:*` 的管理员都不会自动获得该能力；管理员员工也必须显式分配专属角色。
+- 遇到 403 时停止查询，并请授权中心管理员给对应员工分配上述角色；不得改成直连 `temporary-tool.vertu.cn` 规避权限。
+- CLI 只向官方或已明确配置的 HTTPS/loopback vps-service origin 发送 VPS Session、服务 API Key 或 Agent Key；临时传入的未知 `--base-url` 不会收到凭证。
+- vps-service 代理只向上游发送白名单查询字段以及 `Accept`、`Content-Type`、`User-Agent`，不会转发 VPS Session、服务 API Key 或 Agent Key。
+- 这是只读诊断数据。回答时只展示用户要求的字段；IMEI、收货地址和销售人员等明细不要无关扩散。
+- 用 `--validate-only` 或 `--dry-run` 预览请求，不访问远端。

package/skills/vps-device-abnormal-statistics/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Vertu 设备异常统计"
+  short_description: "按仓位查询异常库存并下钻 IMEI 未处理原因"
+  default_prompt: "使用 $vps-device-abnormal-statistics 查询指定仓位的异常设备，并汇总库存与异常 IMEI。"

package/skills/vps-device-abnormal-statistics/references/api.md

@@ -0,0 +1,134 @@
+# 异常统计 API 契约
+
+上游根地址：`https://temporary-tool.vertu.cn`
+
+CLI 不直连上游，而是携带当前 VPS 身份访问 vps-service 权限代理。三个代理接口都要求调用者是在职内部员工、明确拥有角色 `vps_device_abnormal_analyst`（VPS 设备异常分析），并具备显式 scope `product.device_abnormal:read`；外部/经销商账号和仅有 `admin:*` 的管理员不能访问。
+
+| CLI / vps-service 代理 | 上游接口 |
+| --- | --- |
+| `GET /v1/product/abnormal/location` | `GET https://temporary-tool.vertu.cn/abnormal/location` |
+| `GET /v1/product/abnormal/location-list` | `GET https://temporary-tool.vertu.cn/abnormal/location/list` |
+| `POST /v1/product/abnormal/details` | `POST https://temporary-tool.vertu.cn/api/stats/device/detail1` |
+
+代理验证并白名单化参数，只向上游发送 `Accept`、`Content-Type` 和 `User-Agent`，不转发 VPS Session、服务 API Key、Agent Key 或来路 `Authorization`。403 表示当前员工未分配专属角色，不能通过直连上游规避。
+
+## 1. 仓位异常统计
+
+- vps-service：`GET /v1/product/abnormal/location`
+- 上游：`GET /abnormal/location`
+- CLI：`vps-work product +abnormal-location`
+- 参数：
+  - `location_name`：仓位名称模糊搜索。
+  - `location_ids`：仓位 ID 多选；CLI 使用英文逗号拼接。
+
+源响应是 `{code,message,data:{data,total},other,statusText}`。CLI 输出：
+
+- `rows`：源 `data.data`。
+- `reported_total`：源 `data.total`，当前可能固定为 `0`。
+- `summary.row_count`：实际行数。
+- `summary.location_count`：去重仓位名称数。
+- `summary.total_stock` / `physical_stock` / `in_transit_stock` / `store_stock`：逐行求和。
+- `summary.abnormal_imei_count`：全部行的 `abnormal_imeis` 去重计数。
+
+行字段：
+
+| 字段 | 含义 |
+| --- | --- |
+| `location_name` | 仓位展示名；按对应 location ID 分组 |
+| `phone_model` / `phone_name` | 手机型号、商品名称 |
+| `total_stock` | `physical_stock + in_transit_stock + store_stock` |
+| `physical_stock` | 实物库存；同分组会扣减在途数量 |
+| `in_transit_stock` | `transit_logistics_report` 中 `is_in_transit=true` 的数量 |
+| `store_stock` | 门店库存 |
+| `active_time` | 优先 VPUSH，缺失时取 OTA |
+| `vpush_active_time` / `ota_active_time` | 两类激活时间 |
+| `abnormal_imeis` | 存在 VPUSH 或 OTA 激活记录的库存设备 IMEI |
+
+在途记录中的 `vsn`、`imei1`、`imei2` 可能是逗号拼接多值；服务端会拆分匹配，但在途 `quantity` 每行只统计一次。
+
+## 2. 仓位列表
+
+- vps-service：`GET /v1/product/abnormal/location-list`
+- 上游：`GET /abnormal/location/list`
+- CLI：`vps-work product +abnormal-location-list`
+- 参数：`location_name`，可选模糊搜索。
+- 行字段：`location_id`、`location_name`、`is_selected`。
+
+`+abnormal-location --default-selected` 会先调用此接口，提取 `is_selected=true` 的 ID，再请求仓位异常统计，以复现 vps-ep 页面默认范围。默认选中的 ID 是：
+
+`27568,11241,11451,11483,27081,11169,10944,11201,11185,11177,11443,11233,11217,11743,11313,11507,11531`
+
+不要把“未传筛选时查全部仓位”误称为 vps-ep 默认范围。
+
+## 3. 异常设备明细
+
+- vps-service：`POST /v1/product/abnormal/details`
+- 上游：`POST /api/stats/device/detail1`
+- CLI：`vps-work product +abnormal-details`
+- JSON 请求：
+
+```json
+{
+  "imeis": ["860000000000001"],
+  "stat_date": "2025-09-01",
+  "end_date": "2026-07-02",
+  "exception_type": ""
+}
+```
+
+- `imeis` 必填；CLI 支持逗号、空白、JSON 数组或 `@file`。
+- `stat_date` 默认 `2000-01-01`，`end_date` 默认 `2035-01-01`。
+- `exception_type=address_exception` 时，OTA 数据即使不在时间范围内也会保留用于地址异常判断。
+
+源接口成功时直接返回数组。只有计算出至少一个未处理异常原因的 IMEI 才会返回；无异常、异常已处理或数据不足时不会返回该 IMEI。
+
+重要明细字段：
+
+- 身份与库存：`model`、`phone_name`、`IMEI`、`VSN`、`production_date`、`inventory_status`、`depository_company`、`place_for_storage`。
+- 销售与出库：`sale_order_name`、`sale_date`、`sale_department`、`sales_personnel`、`sale_country_name`、`is_agent_sale`、`delivery_date`、`delivery_address`、`factory_dispatch_date`、`last_delivery_time`、`delivery_type`、`factory_dispatch_version`。
+- 激活与维修：`ota_activation_*`、`register_version`、`current_version`、`vpush_activation_date`、`has_repair`、`repair_count`、`first_repair_date`。
+- 异常：`abnormal_cause`、`abnormal_cause_list`、`abnormal_cause_list1`。
+
+`inventory_status` 可能为 `库存中`、`在途`、`已售`、`不存在`；`is_agent_sale` 可能为 `代理`、`零售` 或空值。
+
+## 异常标识
+
+已存在于 `device_anomaly_processings.anomaly_signs` 的标识会被排除。当前可能返回：
+
+| sign | 说明 |
+| --- | --- |
+| `VPUSH_SOLD_NOT_DISPATCHED` | 已售且 VPUSH 激活但仍在库存 |
+| `VPUSH_ACTIVATION_BEFORE_SALE` | VPUSH 激活早于销售 |
+| `VPUSH_ACTIVATED_NO_SALES_IN_STOCK` | 未售、在库且 VPUSH 激活 |
+| `VPUSH_ACTIVATED_IN_TRANSIT` | 在途且 VPUSH 激活 |
+| `VPUSH_ACTIVATED_NO_SALES_NO_STOCK` | 未售、无库存且 VPUSH 激活 |
+| `VPUSH_ACTIVATED_WITH_REPAIR_NO_SALE` | 未售、VPUSH 激活且有维修 |
+| `OTA_ACTIVATION_BEFORE_SALE` | OTA 激活早于销售 |
+| `OTA_SOLD_NOT_DISPATCHED` | 已售且 OTA 激活但仍在库存 |
+| `OTA_ACTIVATED_NO_SALES_IN_STOCK` | 未售、在库且 OTA 激活 |
+| `OTA_ACTIVATED_IN_TRANSIT` | 在途且 OTA 激活 |
+| `OTA_ACTIVATED_NO_SALES_NO_STOCK` | 未售、无库存且 OTA 激活 |
+| `OTA_ACTIVATED_WITH_REPAIR_NO_SALE` | 未售、OTA 激活且有维修 |
+| `OTA_SOLD_OUT_STOCK_VERSION_NOT_MATCH` | OTA 注册版本与出库版本不一致 |
+| `OTA_SOLD_LOCATION_NOT_MATCH` | OTA 激活国家与销售国家不匹配 |
+| `OTA_ACTIVATION_AFTER_REPAIR` | OTA 激活晚于首次维修 |
+| `VPUSH_ACTIVATION_AFTER_REPAIR` | VPUSH 激活晚于首次维修 |
+| `VPUSH_ACTIVATION_BEFORE_PRODUCTION` | VPUSH 激活早于生产或生产日期为空 |
+| `OTA_ACTIVATION_BEFORE_PRODUCTION` | OTA 激活早于生产或生产日期为空 |
+| `VPUSH_REPAIR_BEFORE_OUT_STOCK` | VPUSH 设备维修早于最新出库或无出库时间 |
+| `OTA_REPAIR_BEFORE_OUT_STOCK` | OTA 设备维修早于最新出库或无出库时间 |
+| `VPUSH_SOLD_WITH_REPAIR_REPAIR_TIME_NOT_MATCH` | 已售、VPUSH 未激活且维修/出库时间异常 |
+| `OTA_SOLD_WITH_REPAIR_REPAIR_TIME_NOT_MATCH` | 已售、OTA 未激活且维修/出库时间异常 |
+
+在途设备优先归类为 `*_ACTIVATED_IN_TRANSIT`，不会同时归为在库无销售或无库存无销售。
+
+## 数据来源
+
+- 销售：Odoo `sale_order_line_report_small`。
+- 库存：缓存 `device_stats_odoo_inventory_all`，缺失时查 `stock_quant_report`。
+- 在途：Odoo `transit_logistics_report`，要求 `is_in_transit=true`。
+- OTA：缓存 `device_stats_ota_all1`，缺失时查 `ota_设备日志`。
+- VPUSH：缓存 `device_stats_vpush_all1`，缺失时查 `v_push.device`。
+- 出库/生产：Odoo `vsn_product_manufacture_info`。
+- 售后维修：Odoo `after_sale_maintenance` 与 `vsn_index`。
+- 异常配置与处理记录：`device_anomaly`、`device_anomaly_processings`。

package/skills/vps-documents/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: vps-documents
+description: 查询、读取、新建、重命名、复制、导出和共享 Vertu 企业云文档、智能表格与文件夹，读取智能表格工作簿并批量更新单元格，以及将文档卡片发送到当前 VPS IM 会话。用户提到云文档、V盘文档、企业文档、智能表格、创建文档、读取或更新表格单元格、修改标题、复制文档、导出 Markdown、设置文档权限或把文档发到当前会话时使用。入口为 `vps-work docs +…`。
+---
+
+# Vertu 企业云文档
+
+开始前先读取 `../vps-shared/SKILL.md`，遵循其中的认证、当前用户与 `+` 快捷约定。Hermes 使用宿主注入的 Agent Key 和当前用户身份，禁止索取账号密码或云文档内部密钥。
+
+## 命令选择
+
+| 用户意图 | 命令 |
+|---|---|
+| 查询我的文档 | `vps-work docs +list` |
+| 按标题搜索 | `vps-work docs +list --query <关键词>` |
+| 查询团队或回收站 | `vps-work docs +list --scope team\|trash` |
+| 读取详情与正文 | `vps-work docs +get --doc-id <uuid>` |
+| 查询块格式能力 | `vps-work docs +block-schema` |
+| 读取协作文档块 | `vps-work docs +get-blocks --doc-id <uuid>` |
+| 精确修改段落格式 | `vps-work docs +update-block --doc-id <uuid> --block-id <id> --patch <json>` |
+| 新建文档 | `vps-work docs +create --title <标题> [--content-file <md>]` |
+| 新建智能表格 | `vps-work docs +create --title <标题> --type sheet` |
+| 读取智能表格 | `vps-work docs +sheet-get --doc-id <uuid>` |
+| 更新智能表格单元格 | `vps-work docs +sheet-set-cells --doc-id <uuid> --updates-file <json>` |
+| 新建文件夹 | `vps-work docs +create --title <标题> --type folder` |
+| 重命名 | `vps-work docs +rename --doc-id <uuid> --title <新标题>` |
+| 复制 | `vps-work docs +duplicate --doc-id <uuid>` |
+| 导出 Markdown | `vps-work docs +export-markdown --doc-id <uuid>` |
+| 设置共享权限 | `vps-work docs +share --doc-id <uuid> --mode <权限>` |
+| 分享到当前 VPS IM 会话 | `vps-work docs +send --doc-id <uuid> [--permission request\|view\|edit]` |
+
+完整参数和接口映射见 [`references/api.md`](references/api.md)。执行前可用 `vps-work docs <命令> --help` 核对参数。
+
+## 正文写入规则
+
+- 新建块文档时，优先通过 `+create --content-file <path>` 一次写入 Markdown 初始正文。
+- `+set-content` 只适用于尚未进入实时协作的块文档。若服务返回“协作文档正文必须通过实时协作通道更新”，立即停止，不得通过数据库、内部接口或纯文本覆盖绕过保护。
+- 用 `+sheet-get` 读取当前工作簿；用 `+sheet-set-cells` 更新已有智能表格。更新数组使用 A1 地址，`value` 支持字符串、数字、布尔值与 `null`（清空），也可用 `formula` 写公式。
+- 单次最多更新 10000 个单元格。默认更新第一张工作表；多工作表必须用 `--sheet <ID或名称>` 明确目标。
+- 表格更新通过实时协作通道写入同一 Yjs 工作簿。不要先导出再整体覆盖工作簿，也不要构造 Yjs 状态。
+- CLI 仍不覆盖已有协作块文档正文；需要进入桌面端/移动端实时编辑器完成。
+- 读取到的 `doc.content` 是便于 Agent 理解的提取文本，不等同于可直接回写的协作状态。
+- 精确修改段落格式时，先用 `+get-blocks` 获取稳定 `blockId` 和 `version`，再将该版本传给 `+update-block --expected-version`；版本冲突时必须重新读取，不得盲目重试。
+- `+update-block` 仅开放正文、H1-H5、列表、任务列表、代码块和引用类型，以及左/中/右对齐、默认/黄色背景。它只修改目标块，不接受文本模糊匹配或任意 Yjs 属性。
+- Agent 不得凭记忆猜测 patch：能力不确定时先执行 `+block-schema`。常规修改优先使用 `--type`、`--level`、`--align`、`--background`，由 CLI 构造 patch；只有结构化参数无法表达时才使用 `--patch-file`。
+
+## 权限与安全
+
+- 所有查询按当前 Hermes 用户身份过滤；不要尝试读取用户无权访问的文档。
+- 用户要求“发给我、分享到当前会话”时使用 `+send`，不要手工拼 `interactive_card` metadata。Hermes 会自动使用当前 `channel_id`；只有明确指定其他会话时才传 `--channel-id`。
+- `+send` 默认 `--permission request`，只发送卡片且不改变现有权限；`view` 会设置 `login-view`，`edit` 会设置 `login-edit`。不得在用户未明确要求时扩大为编辑权限。
+- `+share` 属于权限变更，只在用户明确要求时执行。常用模式：`private`（仅已授权成员）、`login-view`（企业成员登录后浏览）、`login-edit`（企业成员登录后编辑）、`public-view`（持链接浏览）。
+- `public-edit` 会允许持链接编辑，风险较高；用户没有明确要求时不得启用。
+- 复制、创建、重命名和共享是写操作；根据用户意图执行。删除能力目前不向 Agent CLI 开放。
+- 命令默认输出 JSON，优先读取 `id`、`title`、`type`、`role`、`shareMode`、`content`。
+
+## 示例
+
+```bash
+vps-work docs +list --query "项目方案"
+vps-work docs +get --doc-id <uuid>
+vps-work docs +block-schema
+vps-work docs +get-blocks --doc-id <uuid>
+vps-work docs +update-block --doc-id <uuid> --block-id <block-id> --expected-version <version> --type heading --level 2 --align center --background yellow
+vps-work docs +update-block --doc-id <uuid> --block-id <block-id> --expected-version <version> --patch-file ./patch.json
+vps-work docs +create --title "项目方案" --content-file ./方案.md
+printf '# 周报\n\n本周进展' | vps-work docs +create --title "周报" --content-file -
+vps-work docs +create --title "销售台账" --type sheet
+vps-work docs +sheet-get --doc-id <uuid>
+vps-work docs +sheet-set-cells --doc-id <uuid> --sheet "明细" --updates '[{"cell":"A1","value":"姓名"},{"cell":"B2","value":100},{"cell":"C2","formula":"SUM(B2:B10)"}]'
+printf '[{"cell":"A1","value":null}]' | vps-work docs +sheet-set-cells --doc-id <uuid> --updates-file -
+vps-work docs +rename --doc-id <uuid> --title "项目方案 V2"
+vps-work docs +share --doc-id <uuid> --mode login-view
+vps-work docs +send --doc-id <uuid>
+vps-work docs +send --doc-id <uuid> --permission view
+vps-work docs +export-markdown --doc-id <uuid>
+```

package/skills/vps-documents/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Vertu 云文档"
+  short_description: "查询、更新、导出和共享企业云文档与智能表格"
+  default_prompt: "Use $vps-documents to help me manage Vertu cloud documents safely."

package/skills/vps-documents/references/api.md

@@ -0,0 +1,106 @@
+# 云文档 CLI 与接口映射
+
+CLI 统一请求 `vps-service`，由服务端校验 Hermes Agent Key、解析当前用户，再代理到云文档服务。Agent 不直接持有 `VPS_CLOUD_DOCS_INTERNAL_KEY`。
+
+| CLI | 方法与接口 | 说明 |
+|---|---|---|
+| `docs +list` | `GET /v1/documents` | `q`、`scope`、`teamId` 查询参数 |
+| `docs +get` | `GET /v1/documents/:id` | 返回详情、权限、提取正文及实时协作入口 |
+| `docs +create` | `POST /v1/documents` | `title`、`type`、`parentId`、`initialPayload` |
+| `docs +rename` | `POST /v1/documents/:id/rename` | 修改标题 |
+| `docs +set-content` | `PUT /v1/documents/:id/content` | 仅未进入实时协作的块文档 |
+| `docs +block-schema` | `GET /v1/documents/capabilities/blocks` | 返回机器可读的块类型、属性值和并发规则 |
+| `docs +get-blocks` | `GET /v1/documents/:id/blocks` | 返回稳定块 ID、格式属性和 Yjs 状态版本 |
+| `docs +update-block` | `PATCH /v1/documents/:id/blocks/:blockId` | 在协作事务内精确修改一个块的白名单格式 |
+| `docs +sheet-get` | `GET /v1/documents/:id/sheet` | 返回智能表格当前工作簿 JSON |
+| `docs +sheet-set-cells` | `PUT /v1/documents/:id/sheet` | 通过实时协作工作簿批量更新 A1 单元格 |
+| `docs +share` | `POST /v1/documents/:id/share` | 修改共享模式 |
+| `docs +send` | `GET /v1/documents/:id` + 可选 `POST /share` + IM 消息接口 | 生成 `document_share` 卡片并发送到当前 Hermes/VPS IM 会话 |
+| `docs +duplicate` | `POST /v1/documents/:id/duplicate` | 复制文档 |
+| `docs +export` | `POST /v1/documents/:id/export` | 导出原始文档信息和 Yjs 状态 |
+| `docs +export-markdown` | `POST /v1/documents/:id/export-markdown` | 导出 Markdown 文本 |
+
+## 认证链路
+
+1. Hermes 宿主注入 `VERTU_APP_ID`、`VERTU_APP_KEY`、`VERTU_USER_LOGIN`。
+2. CLI 将凭证发送给 `vps-service`。
+3. `vps-service` 完成 Agent 鉴权并确定当前企业用户。
+4. `vps-service` 通过内部鉴权头代理到云文档服务。
+5. 云文档服务按用户 ACL 返回或修改数据。
+
+`docs +send` 在 Hermes 中读取宿主注入的 `VERTU_AGENT_CHANNEL_ID`、Agent 与用户上下文，通过 `/v1/im/agents/hermes/notify` 保留智能体身份；普通 CLI 显式传入 `--channel-id` 时通过会话消息接口发送。`request` 不修改权限，`view/edit` 分别映射为 `login-view/login-edit`。
+
+API 调用方若不是 `vps-work`，也应调用公开的 `/v1/documents` 接口并使用 Vertu Bearer/Agent Key 鉴权，不要直连 `/api/docs`。
+
+## 文档类型
+
+- `block`：块文档，创建时支持 Markdown 初始正文。
+- `sheet`：智能表格，支持创建、查询、读取工作簿、批量更新单元格、重命名、复制、共享和导出。
+- `folder`：文件夹，用 `parentId` 组织层级。
+
+## 共享模式
+
+| 模式 | 含义 |
+|---|---|
+| `private` | 仅已授权成员 |
+| `login-view` | 企业成员登录后可查看 |
+| `login-edit` | 企业成员登录后可编辑 |
+| `team-view` | 所属团队可查看 |
+| `team-edit` | 所属团队可编辑 |
+| `public-view` | 持链接可查看 |
+| `public-edit` | 持链接可编辑，高风险 |
+
+服务端始终是最终权限裁决者。CLI 收到 401/403、文档不存在或协作保护错误时，应原样反馈并停止，不得换用内部密钥重试。
+
+## 智能表格单元格更新
+
+请求体：
+
+```json
+{
+  "sheet": "明细",
+  "cells": [
+    { "cell": "A1", "value": "姓名" },
+    { "cell": "B2", "value": 100 },
+    { "cell": "C2", "formula": "SUM(B2:B10)" },
+    { "cell": "D2", "value": null }
+  ]
+}
+```
+
+- `sheet` 可为工作表 ID 或名称；省略时使用第一张工作表。
+- `cell` 使用 A1 地址，范围限制与 Excel 一致（A1–XFD1048576）。
+- `value` 支持字符串、有限数字、布尔值或 `null`；`null` 表示清空。
+- `formula` 与 `value` 互斥，省略开头 `=` 时服务端自动补齐。
+
+## 协作文档块格式更新
+
+先执行 `+block-schema` 获取当前服务端能力，再读取块列表，并将返回的 `version` 作为并发保护。常规操作使用结构化参数：
+
+```bash
+vps-work docs +update-block \
+  --doc-id <uuid> --block-id <id> --expected-version <version> \
+  --type heading --level 2 --align center --background yellow
+```
+
+高级 `--patch-file` 请求体为：
+
+```json
+{
+  "expectedVersion": "Yjs-state-vector",
+  "patch": {
+    "type": "heading",
+    "props": {
+      "level": 2,
+      "textAlignment": "center",
+      "backgroundColor": "yellow"
+    }
+  }
+}
+```
+
+- 类型：`paragraph`、`heading`、`numberedListItem`、`bulletListItem`、`checkListItem`、`codeBlock`、`quote`。
+- `level` 仅适用于 `heading`，范围为 1-5。
+- `textAlignment` 为 `left`、`center` 或 `right`；引用和代码块不支持对齐。
+- `backgroundColor` 为 `default` 或 `yellow`；代码块不支持背景设置。
+- 版本不匹配时重新执行 `+get-blocks`，确认目标块后再提交。

package/skills/vps-hr/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: vps-hr
+description: |
+  人力资源：当前用户身份、组织架构、内部在职员工、人员档案、上下级、岗位、工龄、合同、薪酬单据。用户询问公司在职员工、内部员工名单、在职人数或要求排除外部人员时使用。入口 `vps-work hr +…`。
+---
+
+# hr（人力资源）
+
+**CRITICAL — MUST Read [`../vps-shared/SKILL.md`](../vps-shared/SKILL.md)**
+
+| Shortcut | 说明 | 契约 |
+|----------|------|------|
+| [`+me`](../vps-current-user-identity/SKILL.md) | 当前用户身份 | 内建 `vps-work hr +me` |
+| `+org-tree` | 组织部门树；默认一级/二级，`--max-depth 0` 查看全量，`--flat` 输出扁平列表 | Vertu 通讯录 |
+| `+headcount` | 授权范围内的通讯录口径人数统计；返回人数与在职拆分 | 普通员工为本人，部门负责人为负责部门；全公司需要 `hr.profile.all:read` |
+| `+profile` | 本人人事档案；含部门、岗位、上级、入职/转正/离职、工龄、最新合同 | `hr-personnel-directory` data-view |
+| `+tenure` | 本人工龄与入职/转正/离职信息 | `hr-personnel-directory` data-view |
+| `+manager` | 本人的直属上司档案 | `hr +me` 的 `manager_id` + `hr-personnel-directory` |
+| `+subordinates` | 本人的全层级下属；默认递归到最深层、默认 `--status 在职`，`--direct` 仅直属 | 从 `hr +me` 的 `employee_id` 开始逐层过滤 `manager_employee_id` |
+| `+job-details` | 岗位明细；支持 `--department-l1` / `--department-l2` / `--department` / `--job` / `--manager-name` 等过滤 | `hr-personnel-directory` data-view |
+| `+contracts` | 合同信息；本人可查，查询他人需要 `hr.profile.contract:read` | `--all` 只取消 CLI 本人过滤，不能扩大服务端人员范围 |
+| [`+payslip`](../vps-hr-compensation-documents/references/+payslip.md) | 工资条 | `vps-hr-compensation-documents` |
+| `+personnel-info` | 授权范围内的 HR 人员信息；部门负责人默认仅有基本字段 | 任职、合同、历史档案分别需要独立 scope |
+
+## 常用自然语言映射
+
+| 用户问法 | 命令 |
+|----------|------|
+| 查组织架构 | `vps-work hr +org-tree` |
+| 查授权范围人数 / 在职多少人 | `vps-work hr +headcount` |
+| 查内部在职员工名单 | `vps-work hr +personnel-info --status "在职" --limit 1000` |
+| 查岗位明细 | `vps-work hr +job-details --job "<岗位关键词>"` |
+| 查我的下属 | `vps-work hr +subordinates` |
+| 查我的上司 / 汇报对象 | `vps-work hr +manager` |
+| 查我的人事档案 / 工龄 / 合同 | `vps-work hr +profile`；只看合同可用 `vps-work hr +contracts` |
+| 按一级/二级部门查人员 | `vps-work hr +personnel-info --department-l1 "<一级部门>" --department-l2 "<二级部门>"` |
+
+## 字段与口径
+
+- `+org-tree` 走 Vertu 通讯录部门树，默认显示一级/二级；需要全量时用 `--max-depth 0`。
+- HR 人员范围由服务端计算：普通员工只能查本人；部门负责人默认查直接负责部门；显式部门管理员映射可通过 `include_children` 纳入下级部门；`hr.profile.all:read` 才能查看全公司。
+- 部门负责人默认字段包为 `basic`（姓名、工号、部门、岗位、上级、在职状态）。任职详情、合同和历史人员分别需要 `hr.profile.employment:read`、`hr.profile.contract:read`、`hr.profile.history:read`；`admin:*` 不自动获得这些人事敏感权限。
+- `+headcount` 是授权范围人数统计入口；不要用 `+personnel-info` 拉明细后本地统计人数。
+- 查询“在职员工 / 内部员工”明细时固定使用 `+personnel-info --status "在职"`，并保留默认通讯录口径；不要添加 `--include-non-directory`。`status` 是包含匹配，会覆盖正式、试用、兼职和实习等内部在职分类。
+- 外部人员的人事状态为“外部人员-不计入人数”，不含“在职”；默认 `directory_visible=true` 还会将结果与在职通讯录员工取交集。因此该查询排除外部人员、离职人员、无有效部门及未同步到通讯录的档案。
+- 回答在职名单或人数时必须主动说明：`口径：仅统计通讯录可见的内部在职员工，已排除外部人员和离职人员。` 若返回 `pagination.has_more=true`，还要说明当前只展示首批结果，不能把 `rows.length` 当作总人数；总人数读取 `pagination.total_rows` 或改用 `+headcount`。
+- `+profile` / `+manager` / `+subordinates` / `+job-details` / `+contracts` / `+personnel-info` 默认只返回授权范围内的通讯录可见人员；历史档案必须同时显式加 `--include-non-directory` 并具备 `hr.profile.history:read`。
+- `+profile` / `+manager` / `+subordinates` 会先取一次 `hr +me`，再用 `employee_id` / `manager_id` 精确过滤。
+- HR 人员视图（`hr-personnel-directory`）读取 VPS 原生 HR 档案（企业成员 + `vps_hr_profiles` + 组织单元），不再依赖 Odoo `hr.employee`；部门层级来自组织单元路径，合同取档案中最新一条。`employee_id` / `user_id` 对内部企业仍为 Odoo 兼容号，可与销售等第三方应用数据对齐。
+- `+subordinates` 默认递归查询下级团队直到最深层，返回 `level` 与 `manager_chain_text` 辅助识别层级；如只要直属下属，使用 `--direct`。