vps-work 1.0.0

package/skills/vps-sale-personnel-efficiency/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: vps-sale-personnel-efficiency
+description: |
+  面向销售人效（人产、人均产出）、开单率、个人销售业绩查询、个人月度/季度/年度 OKR 达成、团队/个人 PK 排名等场景。查某人销售额/业绩/卖了多少钱直接用 personal_okr_achievement 脚本 + salesperson_like 参数。支持任意时间窗口（CLI: period 枚举或 YYYY-MM-DD、--start-date/--end-date；execute/API: start_date/end_date）。数据基于销售行口径 + Postgres/PMS 个人目标 + 人员信息，通过 `vps-work sales +per-person-kpi` 等命令取数。部门汇总走 vps-daily-sales-report。触发词：人效、人产、人均产出、开单率、开单人数、个人业绩、销售员业绩、个人 OKR、销售员目标、PK、销售榜单、销售员排名、谁卖最多、谁卖了、卖了多少、个人达成率、上月人效、季度达成。
+---
+
+# 销售人效与个人 OKR
+
+## 何时使用
+
+用户要查"销售人效 / 个人业绩 / 某人卖了多少钱 / 个人 OKR 达成 / 团队或个人 PK 排名"等以**人**为维度的销售指标。数据来自销售行 + Postgres `vps_okr_*` 个人目标 + 人员信息，统一通过 `vps-work sales +per-person-kpi` / `+personal-okr` / `+team-pk` 取数。**点名查某人业绩**（如"杨晶晶今天卖了多少钱"）直接用 `personal_okr_achievement` + `salesperson_like` 参数。部门汇总走 **vps-daily-sales-report**。
+
+## 业绩口径
+
+三个脚本（per_person_kpi / personal_okr_achievement / team_pk_ranking）**默认不含定金**：`LEFT JOIN mv_product` 过滤 `"定金"='是'`。需含定金时显式传 `include_deposit=true`。OKR 目标按月一行不受影响。
+
+个人 OKR 目标默认来自 Postgres `vps_okr_personal_performance_targets`；只有排查旧 PMS/BI 口径时才传 `--okr-source legacy` / `okr_source=legacy`。
+
+## 开单率口径
+
+- 公式：`开单率 = 查询期存在销售单的去重人员数 ÷ 查询期存在个人业绩目标的去重人员数`。
+- 人员键统一使用工号：销售榜 `barcode` ↔ 个人目标 `工号`；分别去重，不要求分子必须属于分母集合。
+- 分子使用 `+ranking --metric orders --top-n 500`，仅保留 `order_count > 0` 的工号。
+- 分母使用 `+personal-monthly-okr --okr-source legacy --limit 500`，与管理端个人业绩目标页面同源，仅保留目标大于 0 的工号。
+- 固定排除：`国内渠道 / 国内代理`、`AI渠道 / AI电商`。分子按销售榜 `dept_name` 排除对应二级部门；分母按目标明细的 `一级部门 + 二级部门` 排除。
+- 每次回答必须说明：`已排除国内渠道-国内代理、AI渠道-AI电商`，并展示 `开单人数 / 有目标人数 = 开单率`。
+- 同时给一级部门结果时，对国内渠道、AI渠道应用相同排除；海外渠道无固定排除项。
+- 若任一返回的 `pagination.has_more=true`，继续取全量后再去重计算；不得只用第一页。
+
+## 人产口径
+
+- 公式：`人产 = 查询期业绩 ÷ 查询期存在个人业绩目标的去重人员数`，金额单位为元/人。
+- 业绩使用 `+ranking --metric orders --top-n 500` 返回行的 `sales_amount` 合计，默认不含定金。
+- 分母与开单率完全一致：使用 `+personal-monthly-okr --okr-source legacy --limit 500` 的目标工号去重数。
+- 固定排除与开单率完全一致：排除 `国内渠道 / 国内代理`、`AI渠道 / AI电商`；业绩按销售榜 `dept_name` 排除，分母按目标明细的 `一级部门 + 二级部门` 排除。
+- 每次回答必须说明排除项，并展示 `业绩 ÷ 有目标人数 = 人产`；需要同时回答开单率时复用同一批销售榜和目标明细，不得使用在职人数作为分母。
+
+## 时间窗口（统一约定）
+
+所有脚本统一接受下列时间参数（优先级由高到低）：
+
+1. CLI `--start-date` + `--end-date`（YYYY-MM-DD，闭区间；单独传任意一个也表示单日；execute/API 为 `start_date` + `end_date`）
+2. CLI `--period` 枚举或单日日期 — `today / yesterday / this_month / last_month / this_quarter / last_quarter / this_year / last_year / last_n_days / custom / YYYY-MM-DD`
+3. `days`（仅 `period=last_n_days` 时使用）
+4. 默认 `this_month`
+
+`period=custom` 必须同时提供 CLI `--start-date` 与 `--end-date`（execute/API 为 `start_date` 与 `end_date`），否则报错。Postgres 个人 OKR 目标按月一行，跨多月窗口时会按窗口涉及的月份聚合 SUM(目标)。
+
+## 部门过滤
+
+人效脚本只接受 `dept_l1 / dept_l2 / dept_l3 / dept_l4 / dept_l5`。不要使用 `dept`、`department`、`dept_name`、`department_name` 表示销售部门；用户只说“部门”时，先确认层级或用组织结构查询定位。
+
+## 工作流
+
+1. **快速路径** — 用户已指明人名 + 时间（如"杨晶晶今天卖了多少"）→ 直接跳到步骤 3，用 `personal_okr_achievement` + `salesperson_like`
+2. **澄清** — 否则：维度（部门/团队/个人）、时间（默认本月）、是否需要 OKR 对比
+3. **选择脚本** — `per_person_kpi`（通用人效）/ `personal_okr_achievement`（个人达成）/ `team_pk_ranking`（PK 排名）；开单率和本口径人产组合使用 `employee_ranking_top_bottom` + `personal_monthly_okr`
+4. **执行** — `vps-work sales +per-person-kpi` / `+personal-okr` / `+team-pk`（见 `reference.md`）；复杂参数用 `--params`。
+5. **解读** — 先给整体（部门人均、整体达成率、第一名），再列 Top N
+6. **翻页** — 返回 `pagination.has_more=true` 时，用 `--page <next_page>` 继续查询；不要把第一页 `rows` 当全量。
+
+## 硬约束
+
+- **工号字段统一**：销售行 `工号` ↔ Postgres OKR `user_id` ↔ 人员信息 `barcode/user_id`
+- **OKR 跨多月窗口**：累加 SUM(目标)，与销售实际同窗口对比；非整月（如 `last_n_days=10`）按涉及月份目标全额累计，对应注释会标注"目标按月粒度累加"
+- **OKR 目标源默认 Postgres**：不传 `--okr-source` 等同于 `postgres`；旧 PMS/BI 口径才传 `legacy`
+- **开单率目标源例外**：分母必须显式传 `okr_source=legacy`，与管理端个人业绩目标页面一致
+- **开单率固定排除**：国内渠道排除二级部门国内代理；AI渠道排除二级部门AI电商；输出必须披露
+- **人产共用口径**：分母和固定排除与开单率一致，禁止改用在职人数或开单人数
+- **取数走 CLI 封装**：脚本通过 `vps-work sales +…` 直连规范视图执行，无需手写连接
+
+## 常见坑点
+
+| 现象 | 根因 | 正确做法 |
+|------|------|---------|
+| 在职人数=0 | 部门一级名 odoo_sale.一级部门 与 人员信息.one_name 命名不一致 | 显示给用户作为"无对应在职人员"，不要静默隐藏 |
+| 个人销额 vs OKR 数字差距大 | 销售员只挂工号但本月无 OKR 登记 | 月度目标显示 0，达成率 NULL |
+| 同一人多部门串扰 | 销售员临时调岗 | 以 odoo_sale 当行的部门为准展示 |
+
+## 关联技能
+
+- **vps-daily-sales-report** — 部门汇总日报
+- **vps-okr-management-assistant** — OKR 树与组织 OKR 详情
+
+---
+
+## Extension fallback path (when current shortcuts don't cover the question)
+
+If none of this skill's `vps-work sales +…` shortcuts answers the user's question,
+**do not fabricate a query path**:
+
+1. 取数只走 CLI 封装：用本 skill `reference.md` 已列的 `vps-work sales +per-person-kpi` /
+   `+personal-okr` / `+team-pk` 快捷命令；高级参数走 `--params` 或 `/v1/execute` 的 `script_key`。
+
+2. 嵌在本 skill 脚本里的销售行、商品定金与 Postgres OKR 目标源承载了规范业务口径；
+   不要绕过封装自行拼接原始字段，以免丢失校准。
+
+3. 字段 / 模型 / 业务实体语义只取自本 skill 的 `reference.md`、`skills/` 下兄弟 skill，或
+   `vps-work sales +…` 快捷命令。缺口 → `POST /ai/skills/v1/feedback`。
+
+
+---
+
+## 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-sale-personnel-efficiency/reference.md

@@ -0,0 +1,139 @@
+
+# 编排手册 · 销售人效与个人 OKR
+
+## 一、脚本一览表
+
+| 脚本 | 何时调用 | 如何调用 | 产物 |
+|------|---------|---------|------|
+| `per_person_kpi` | 问"销售人效 / 人均产出（任意时段）" | **`vps-work sales +per-person-kpi`** | 部门 × 期间销额/活跃销售人数/在职人数/活跃人均/在职人均 |
+| `personal_okr_achievement` | 问"哪个销售员达成不了目标 / 个人 OKR 完成率" | **`vps-work sales +personal-okr`** | 销售员 × 期间目标/实际/达成率；默认 Postgres 目标源 |
+| `personal_monthly_okr` | 问"个人月度 OKR 明细 / 个人目标来源" | **`vps-work sales +personal-monthly-okr`** | Postgres `vps_okr_personal_performance_targets` 明细 |
+| `team_pk_ranking` | 问"团队/个人 PK 榜 / 谁卖最多" | **`vps-work sales +team-pk`** | 排名 × 销额/销量/订单数 |
+| 开单率组合口径 | 问"本月/某期间开单率" | `+ranking --metric orders` + `+personal-monthly-okr --okr-source legacy` | 去重开单人数 ÷ 去重目标人数；固定排除国内代理、AI电商 |
+| 人产组合口径 | 问"本月/某期间人产" | `+ranking --metric orders` + `+personal-monthly-okr --okr-source legacy` | 排除后业绩 ÷ 去重目标人数；分母和排除项与开单率一致 |
+
+## 二、共享时间窗口参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| `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` / `end_date` | string | YYYY-MM-DD；单独给任意一个表示单日，同时给表示闭区间；CLI flags 为 `--start-date` / `--end-date` |
+| `days` | int | 仅 `period=last_n_days` 时使用 |
+| `period_month` | string | 老参数兼容（personal_okr_achievement 专用，YYYY-MM-01）；建议改用 `period` |
+
+## 三、CLI Shortcut 默认时间
+
+| Shortcut | 默认时间 |
+|----------|----------|
+| `+per-person-kpi` | `last_month` |
+| `+personal-okr` | `this_quarter` |
+| `+personal-monthly-okr` | `this_month` |
+| `+team-pk` | `this_month` |
+
+## 四、共享部门参数
+
+`dept_l1 / dept_l2 / dept_l3 / dept_l4 / dept_l5` 全部可选，AND 拼接。
+
+## 五、脚本独有参数
+
+| 参数名 | 类型 | 默认值 | 适用脚本 | 说明 |
+|--------|------|--------|---------|------|
+| `dept_level` | int | 2 | per_person_kpi | 输出聚合层级 1/2/3 |
+| `on_duty_status` | string | "在职" | per_person_kpi | 在职状态过滤；可设 "全部" |
+| `salesperson_like` | string | "" | personal_okr_achievement | 销售员姓名 ILIKE 模糊匹配 |
+| `work_id` | string | "" | personal_okr_achievement | 工号精确匹配 |
+| `name` | string | "" | personal_monthly_okr | 姓名 ILIKE 模糊匹配 |
+| `barcode` | string | "" | personal_monthly_okr | 工号精确匹配 |
+| `only_below_target` | bool | false | personal_okr_achievement | 仅看未达标 |
+| `order_by` | string | "rate_asc" | personal_okr_achievement | rate_asc/rate_desc/amount_desc/name |
+| `mode` | string | "person" | team_pk_ranking | team / person |
+| `okr_source` | string | "postgres" | personal_okr_achievement / personal_monthly_okr | 目标源；旧 PMS/BI 口径才传 `legacy` |
+| `page` | int | 1 | 全部列表型脚本 | 页码，从 1 开始；配合返回 `pagination.next_page` 翻页 |
+| `include_deposit` | bool | false | per_person_kpi / personal_okr_achievement / team_pk_ranking | 业绩口径：false=不含定金（默认），true=含定金 |
+| `limit` | int | 20/30 | 全部 | 返回行数上限 |
+
+返回含 `pagination` 时必须检查 `has_more`；为 true 时继续请求 `page=next_page`。不要把当前页 `rows` 当作全量。
+
+## 六、CLI 调用示例
+
+### bash / zsh
+
+```bash
+# 上月全部门人效
+vps-work sales +per-person-kpi --period last_month
+
+# 本季度线下事业部 — 未达标销售员清单（按达成率升序）
+vps-work sales +personal-okr --period this_quarter --dept-l1 线下事业部 \
+  --params '{"only_below_target":true,"limit":50}'
+
+# 本月个人销售 PK 榜 Top20
+vps-work sales +team-pk --period this_month --params '{"mode":"person","limit":20}'
+
+# 何龙承本月个人 OKR 达成
+vps-work sales +personal-okr --period this_month --salesperson-like 何龙承
+
+# 何龙承本月个人 OKR 明细
+vps-work sales +personal-monthly-okr --period this_month --name 何龙承
+
+# 翻到第 2 页
+vps-work sales +personal-okr --period this_month --limit 20 --page 2
+
+# 仅排查旧 PMS/BI 目标口径
+vps-work sales +personal-okr --period this_month --okr-source legacy --limit 50
+```
+
+### Windows PowerShell
+
+```powershell
+'{"period":"last_month","dept_l1":"线下事业部","only_below_target":true}' | Set-Content -Encoding utf8 ./p.json
+vps-work sales +personal-okr --params '@./p.json'
+```
+
+### Windows PowerShell：本月开单率与人产
+
+```powershell
+$base = 'http://127.0.0.1:3920'
+
+$sales = (vps-work sales +ranking --base-url $base --period this_month `
+  --metric orders --top-n 500 --bottom-n 1 | Out-String | ConvertFrom-Json).top
+
+$targets = (vps-work sales +personal-monthly-okr --base-url $base --period this_month `
+  --okr-source legacy --limit 500 | Out-String | ConvertFrom-Json).rows
+
+$eligibleSales = @($sales |
+  Where-Object { $_.dept_name -notin @('国内代理', 'AI电商') })
+
+$opened = @($eligibleSales |
+  Where-Object { [double]$_.order_count -gt 0 } |
+  ForEach-Object { [string]$_.barcode } |
+  Where-Object { $_ } |
+  Sort-Object -Unique)
+
+$targeted = @($targets |
+  Where-Object {
+    -not (($_.'一级部门' -eq '国内渠道' -and $_.'二级部门' -eq '国内代理') -or
+          ($_.'一级部门' -eq 'AI渠道' -and $_.'二级部门' -eq 'AI电商'))
+  } |
+  ForEach-Object { [string]$_.'工号' } |
+  Where-Object { $_ } |
+  Sort-Object -Unique)
+
+$performance = [double](($eligibleSales | Measure-Object sales_amount -Sum).Sum)
+
+[pscustomobject]@{
+  period = '本月'
+  performance_amount = [math]::Round($performance, 2)
+  opened_people = $opened.Count
+  targeted_people = $targeted.Count
+  opening_rate_pct = [math]::Round(100 * $opened.Count / $targeted.Count, 2)
+  human_output = [math]::Round($performance / $targeted.Count, 2)
+  exclusions = '国内渠道-国内代理；AI渠道-AI电商'
+}
+```
+
+该组合命令依赖当前数据量不超过 500 人；若目标明细返回 `pagination.has_more=true`，必须逐页取全后再计算。
+
+## 七、人员归属口径
+
+- `personal_okr_achievement` 的实际业绩来自销售行；销售行部门按业绩分摊部门归属。
+- 返回行中的 `dept_l1/dept_l2` 优先取人员视图，再回落销售行部门。若某人在查询窗口没有销售行，展示部门主要来自人员视图。

package/skills/vps-shared/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: vps-shared
+description: |
+  vps-work 共用约定：登录、当前用户身份、活目录 catalog / exec、数据查询与反馈。业务域技能开始前应先读本文件。
+metadata:
+  requires:
+    bins: ['vps-work']
+---
+
+# vps-work 共用（认证与约定）
+
+**业务域 skill（`sale-performance-query`、`vps-hr`、`vps-task-management-assistant` 等）执行前 MUST 先 Read 本文件。**
+
+## 认证
+
+Agent / Bot / Hermes **MUST NOT** 执行账号密码登录、不得索取或在 Prompt/命令中传递用户密码。宿主必须预先注入 Agent 凭证；Hermes 固定使用 `app_id=vertu-hermes-agent`。Agent 只执行状态检查：
+
+```bash
+vps-work auth status
+```
+
+若状态无效，Agent 必须停止并提示管理员刷新宿主凭证。仅人工用户可在交互终端执行 `vps-work auth login`。
+
+V盘与企业云文档是 Vertu 服务能力，不依赖 Odoo Session。`drive +…` 返回 401 或 `auth status` 无效时，只能判断为宿主 Agent Key / Profile HOME 注入异常；不得执行 `reauth`、legacy Odoo 登录或调用 Odoo Session 接口。
+
+Agent 不得读取、输出、复制或修改 `~/.vps-work/vps-service.json` 及其权限，也不得把其中的 Key 拼进 `curl`。排障只运行 `vps-work auth status --json` 并将状态反馈给管理员；业务请求必须继续使用公开的 `vps-work <域> +…` 命令，不得猜测 `/v1/...` 内部路由。
+
+## 命令与 skill 清单
+
+- 执行前先看当前企业身份：`vps-work auth status --json`，必要时由人工/宿主执行 `vps-work auth tenants` / `vps-work auth use --tenant <id>`。Agent 不得自行切换企业。
+- **活目录优先**：`vps-work catalog --json`（可加 `--domain sales`）列出当前身份能用的命令。本地 Skill 表不是全集。
+- `transport=execute` 的条目用 `vps-work exec --skill <skill_key> --script <script_key> --param k=v`；不要编造 catalog 里没有的 script_key。
+- 已有的 `vps-work <域> +…` 仍可用；`--help` 只反映本机命令糖衣，不以它判断服务端是否新增了脚本。
+- **数据归属**：catalog 条目带 `provider=odoo` 的（sales / store / product 域）数据来自第三方应用 **Odoo ERP**（客户、订单、商品、库存、合同、经营数据、产销、审批）；HR 档案、工资条、IM、云文档、V盘、日程等是 VPS 原生能力。企业管理员在「企业应用 → 第三方 → Odoo ERP」停用该应用后，catalog 会隐藏这些条目、`exec` 返回 403，Agent 应如实告知“本企业未启用 Odoo ERP”，不得绕行。
+- 公开 skill 随 npm 包分发：`vps-work skill list` / `vps-work skill install`（详见 `skills/vps-work/SKILL.md`）。
+
+## 当前用户（「我 / 本部门」）
+
+一人称场景优先：
+
+1. `vps-work hr +me` — 返回 user / employee / department 等 ID；
+2. Domain DSL 宏 `@me`、`@my_department` 等（见 `skills/vps-current-user-identity/SKILL.md`）；
+3. `vps-work auth status`。
+
+需要查看组织层级关系时用 `vps-work hr +org-tree`（默认一级/二级部门；全量加 `--max-depth 0`）。
+
+细则见 `skills/vps-current-user-identity/SKILL.md`。
+
+### 协助人身份
+
+PDCA 协助关系由 Vertu 服务端根据当前登录用户实时校验。CLI/Skill 必须保留当前登录用户作为真实操作人；Agent Key 必须签发并绑定给协助人本人，修改登录请求头不能切换身份。被协助人的 `user_id` 只能用于列表过滤或业务负责人字段，禁止替换登录身份、伪造 `user_id`，也禁止改用服务 API Key 绕过用户鉴权。协助人操作产生的审计记录必须归属于协助人本人。
+
+## 快捷方式 `+` 约定
+
+- 形态：`vps-work <域> +<shortcut>`，例如 `vps-work sales +headline-kpi`。
+- 参数与 `--help` 以 CLI 为准；编排与 script_key 见各域 `references/` 或子 skill 的 `reference.md`。
+- 取数统一以 `+` 快捷命令为入口，参数以 `--help` 为准。
+- `--validate-only` / `--dry-run` 仅预览请求载荷，不执行查询；execute 类 shortcut 会打印 `skill_key`、`script_key`、`params`。
+
+## 数据查询
+
+- 取数统一通过 `vps-work <域> +…`（如 `vps-work sales +headline-kpi`、`vps-work hr +payslip`）。
+- 各域取数参数与 script_key 见对应域 `references/` 或子 skill 的 `reference.md`。
+
+## 技能发现
+
+- 仓库索引：`skills/README.md`、`.well-known/skills/index.json`
+- 按意图选域：销售业绩 `sale-performance-query`、商品与供应链 `vps-product`、人力 `vps-hr`、审批 `vps-approval`、OKR `vps-okr`、日报 `vps-daily-report-assistant`、任务 `vps-task-management-assistant`、日程 `vps-calendar`、云文档 `vps-documents`、V盘普通文件 `vps-v-drive`、平台公共工具 `vps-tools`、IM `vps-im`、邮件 `vps-mail`、会议 `vps-meeting` 等（与 `vps-work <域> --help` 一一对应）。
+
+## 任务结束反馈（可选）
+
+完成复杂取数或发现文档/参数问题时，直接修正对应业务 skill/reference 文档。

package/skills/vps-store-management/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: vps-store-management
+description: "门店管理：查询国内渠道门店接待、进店客流、客户画像、意向商品、加微信、有效客户、产品触摸/试用和现场成交过程数据。用户问门店接待情况、进店组数、进店人数、客户画像、意向商品、加微率、有效客户、触摸率、使用率、现场成交率、门店客流排行时使用 `vps-work store +reception`。"
+---
+
+# 门店管理
+
+**CRITICAL — 开始前 MUST 先读取 [`../vps-shared/SKILL.md`](../vps-shared/SKILL.md)。**
+
+## 门店接待情况
+
+使用 `vps-work store +reception`，详细参数和口径见
+[`references/store-reception.md`](references/store-reception.md)。
+
+```bash
+vps-work store +reception --period this_month
+vps-work store +reception --start-date 2026-08-01 --end-date 2026-08-18 --region 东区
+vps-work store +reception --period today --store "北京国贸"
+vps-work store +reception --period this_month --employee "张三"
+vps-work store +reception --period this_month --source dealer
+```
+
+## 路由规则
+
+- “门店接待、进店组数/人数、加微、有效客户、触摸、试用、现场成交”使用本 Skill。
+- “自然进店来源的经销商销售订单”仍使用 `vps-work sales +agent-walkin`。
+- 两者都叫 Walk-in，但前者来自接待过程表，后者来自成交订单，禁止混算。
+
+## Script
+
+- `skill_key`: `vps-store-management`
+- `script_key`: `store_reception_summary`
+- 权限：`sales.headline_kpi:read`
+
+返回除汇总和门店行外，还包含 `breakdowns`：接待类型、到店时段、单据状态、性别、年龄段、购买目的、手机品牌、客户来源、微信状态和意向商品。

package/skills/vps-store-management/references/store-reception.md

@@ -0,0 +1,40 @@
+# 门店接待情况
+
+## 命令
+
+```bash
+vps-work store +reception [options]
+```
+
+| 参数 | 说明 |
+|---|---|
+| `--period` | 默认 `this_month`；支持 today/this_week/last_week/this_month/last_month/last_n_days/单日 |
+| `--start-date` / `--end-date` | 自定义日期范围 |
+| `--region` | 东区/西区/北区/南区 |
+| `--store` | 门店名称精确匹配 |
+| `--department-id` | 真实接待部门 ID |
+| `--employee` | 接待员工姓名模糊匹配 |
+| `--source` | `store`（默认，排除代理商填报）、`dealer`（仅代理商）或 `all` |
+
+## 指标口径
+
+- 进店组数：`crm_walk_in` 记录数。
+- 进店人数：`SUM(customer_count)`。
+- 添加组数：每个接待组至少一位画像客户已加微信。
+- 微信添加数、有效客户数、有效客户添加数、触摸人数、试用人数：累计 `crm_walk_in_portrait` 客户画像行。
+- 成交组数/成交金额：仅 `is_transaction='yes'`。
+- 成交金额按接待类型拆分：自然流、售后、邀约、下线转介绍、其他。
+- 日期按 `reception_date + 8 hours` 后的北京时间自然日归属。
+- 组织范围固定为国内渠道东/西/北/南四区，并兼容“区域直属门店”和“国内直营门店/区域/门店”两种组织层级后按区域、门店汇总。
+- 门店名称优先使用表单的 `walk_in_store`，未填写时回退组织门店；北京 SKP 旧值归入“北京SKP 老店”。
+- 代理商入口与门店共用主表，默认排除 `is_dealer_submission=true`；需要时使用 `--source dealer/all`。
+
+## 返回结果
+
+- `filter`：实际日期和筛选条件，回答前必须核对。
+- `summary`：当前过滤范围总计及各项转化率。
+- `rows`：区域/门店明细。
+- `breakdowns`：接待类型、时段、状态、客户画像、微信状态和意向商品（含意向金额）。
+- `notes`：口径说明。
+
+门店接待过程数据不能与 `sales +agent-walkin` 的经销商订单金额直接相加。

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

@@ -0,0 +1,140 @@
+---
+name: vps-task-management-assistant
+metadata:
+  requires:
+    bins: ['vps-work']
+  cliHelp: 'vps-work task --help'
+description: |
+  面向 Vertu 当前任务中心的项目、任务、待办、PDCA 协助人与个人/团队 OKR 查询和写操作。当用户提到项目进度、任务列表、未完成待办、给某人/自己创建待办或任务、完成待办、待办转任务、协助人代办、我的 OKR 时使用。入口 CLI 为 `vps-work task +…`，当前提供任务中心 `+tc-*` REST 命令与 `+my-okr`。触发词：任务管理、研发管理、项目、任务、待办、todo、创建待办、完成待办、待办转任务、任务中心、项目进度、未完成事项、负责人、协助人、代操作、我的 OKR、团队 OKR。
+---
+
+# 研发任务助理（任务中心 / OKR）
+
+**开始前 Read [`../vps-shared/SKILL.md`](../vps-shared/SKILL.md)。**
+
+统一入口是 `vps-work task +…`。本域只暴露本项目 Vertu 服务的任务中心 REST 能力和任务助手 OKR。
+
+## 何时使用
+
+- 项目、任务、待办的查询、创建、更新、完成、待办转任务：使用任务中心 `+tc-*`。
+- 个人或团队 OKR：使用 `+my-okr`。
+
+如果用户要求任务中心以外的历史任务脚本查询，不要编造命令；当前 `vps-work task` 不提供这些入口。
+
+## 命令清单
+
+### 任务中心（`+tc-*`，UUID 主键）
+
+| 命令 | 说明 |
+|------|------|
+| `+tc-assisted-users` | 当前登录用户可协助的 PDCA 用户；返回 `principal_users`，只读 |
+| `+tc-tasks` | 我的任务列表（`--relation all|created|assisting`、协助对象用 `--principal-user-id`、负责人用 `--owner-user-id`） |
+| `+tc-todos` | 我的待办列表（`--relation all|owned|created|following|assisting|completed`、协助对象用 `--principal-user-id`、负责人用 `--owner-user-id`） |
+| `+tc-projects` | 我参与的项目列表 |
+| `+tc-task-create` | 创建任务（必填 `--title`；可选 `--status` `--priority` `--progress` `--owner-user-id` `--project-id` `--start-date` `--deadline`） |
+| `+tc-task-update` | 更新任务（必填 `--task-id`） |
+| `+tc-todo-create` | 创建待办（必填 `--title`；可选 `--remark` `--priority` `--owner-user-id` `--project-id` `--deadline`；关联会议用 `--meeting-id` + `--meeting-todo-index`） |
+| `+tc-todo-update` | 更新待办/进度（`--progress 0-100`）；完成待办用 `--status done`（必填 `--todo-id`） |
+| `+tc-todo-convert` | 待办转任务（必填 `--todo-id`） |
+| `+tc-project-create` | 创建项目（必填 `--name`；创建人自动成为管理员） |
+
+状态与字段：
+
+| 类型 | 取值 |
+|------|------|
+| 任务状态 | `not_started` / `in_progress` / `paused` / `done` / `cancelled` |
+| 待办状态 | `pending` / `in_progress` / `done` / `cancelled` |
+| 优先级 | `0-3` |
+| 进度 | `0-100` |
+| 日期 | `YYYY-MM-DD` |
+
+### OKR
+
+| 命令 | 说明 |
+|------|------|
+| `+my-okr` | 个人或团队 OKR（`--type mine|team`，默认 mine；`--period YYYY-MM` 省略=当前周期） |
+
+## 工作流
+
+1. 判断用户是查询还是写操作；任务/待办/项目都走 `+tc-*`。
+2. 第一人称（我 / 我的）默认使用当前登录用户；指定他人时 `--owner-user-id` 必须是 `res.users.id`。
+3. 用户要求代协助对象操作时，先执行 `+tc-assisted-users` 验证关系，再用 `--relation assisting --principal-user-id <principal_user_id>` 获取服务端授权返回的真实 UUID。该过滤覆盖被协助人作为负责人、创建人或督办人的事项及继承的子任务。
+4. 更新协助事项时只传列表返回的任务/待办 UUID；不要在 PATCH 请求或 `--params` 中传被协助人的 `user_id` 冒充操作人。
+5. 创建或更新前检查必填字段；涉及多条候选或影响他人时先确认。
+6. 从会议详情中创建待办时，`--meeting-id` 传 `meeting +detail` 使用的 `id` 或 `minutes_id`，`--meeting-todo-index` 传该行动项在 `todos` 数组中从 1 开始的序号；两者必须同时传入。
+7. 输出结果先给结论，再列关键字段：UUID、标题、项目、负责人、状态、进度、截止时间；协助场景注明实际操作人和被协助人。
+
+## 硬约束
+
+- 以 `vps-work task --help` 列出的命令为准。
+- 任务中心主键是 UUID；不要把 PMS 数字 ID 当作 task-center UUID。
+- `--owner-user-id` 是 `res.users.id`，不是 `res.partner.id` 或 `hr.employee.id`。
+- `--principal-user-id` 仅与 `--relation assisting` 一起使用，值必须来自 `+tc-assisted-users`；它是授权关系过滤，不是身份切换。
+- 协助权限只覆盖与被协助人相关的任务、待办和 PDCA 状态；不能添加/移除协助人，不能扩展到 OKR 评分、组织权限或无关业务数据。
+- 协助授权必须来自当前用户会话/Agent 凭证。禁止把被协助人的 ID 填入 `user_id`、禁止伪造身份、禁止使用服务 API Key 绕过用户鉴权；服务端审计人始终应为当前协助人。
+- Agent Key 必须签发并绑定给实际协助人；`VERTU_USER_LOGIN` 或请求头只携带上下文，不能把已绑定给他人的 Key 切换成协助人身份。
+- `viewer_is_assistant: true` 表示该行通过协助关系可操作；没有该标记且不是本人正常角色的行，不要尝试写入。
+- 员工、用户、项目名称不要猜 ID；用户给 ID 除外，否则先用现有身份/组织/列表命令确认。
+- 完成待办前先运行 `vps-work task +tc-todos` 获取真实待办 ID，再按 `vps-work task +tc-todo-update --help` 的参数说明执行。
+- `--meeting-id` 与 `--meeting-todo-index` 只能成对使用；会议待办序号从 1 开始，不要直接填内部的零基索引。
+
+## 常见场景
+
+```bash
+# 我的未完成任务
+vps-work task +tc-tasks
+
+# 我的未完成待办
+vps-work task +tc-todos
+
+# 查看我能协助谁，再只查看其中一人的协助任务
+vps-work task +tc-assisted-users
+vps-work task +tc-tasks --relation assisting --principal-user-id 14110
+
+# 更新协助待办的进度；UUID 必须来自 assisting 列表
+vps-work task +tc-todo-update --todo-id <uuid> --progress 60
+
+# 创建待办并指定负责人
+vps-work task +tc-todo-create --title "整理项目周报" --owner-user-id 14110
+
+# 从会议详情的第 2 条行动项创建待办，并保留会议/录音关联
+vps-work task +tc-todo-create --title "整理交付清单" --meeting-id <id_or_minutes_id> --meeting-todo-index 2
+
+# 查看「完成待办」的精确参数；--todo-id 使用 +tc-todos 返回的 id
+vps-work task +tc-todo-update --help
+
+# 查看「待办转任务」的精确参数；ID 使用列表命令返回的真实值
+vps-work task +tc-todo-convert --help
+
+# 我的本期个人 OKR
+vps-work task +my-okr --type mine
+```
+
+## 关联技能
+
+- **vps-current-user-identity**：处理「我 / 我的 / 我们部门 / 我的上级」。
+- **vps-okr-management-assistant**：部门级 OKR 取数与分析。
+
+---
+
+## 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-tools/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: vps-tools
+description: "VPS 平台公共工具：按需解析用户附件，以及把本地文件上传到统一 OSS。附件默认读取原文件；只有复杂 PDF、Office、扫描件等确有需要时才调用 `vps-work tools +attachment-parse` 启动 MinerU。"
+---
+
+# tools（平台公共工具）
+
+开始前先读取 [`../vps-shared/SKILL.md`](../vps-shared/SKILL.md)，复用宿主注入的登录或 Agent Key，禁止输出凭据。
+
+## OSS 上传
+
+默认上传为私有对象，并返回限时签名地址：
+
+```bash
+vps-work tools +oss-upload --file ./report.pdf
+```
+
+用户明确要求永久公开访问时才使用 `public`：
+
+```bash
+vps-work tools +oss-upload --file ./logo.png --visibility public
+```
+
+指定身份隔离目录内的相对对象名：
+
+```bash
+vps-work tools +oss-upload \
+  --file ./report.pdf \
+  --object-name reports/2026/report.pdf \
+  --signed-url-expires 86400
+```
+
+## 参数
+
+| 参数 | 说明 |
+|---|---|
+| `--file <path>` | 必填，本地普通文件，最大 50 MiB |
+| `--visibility private\|public` | 默认 `private`；公开对象使用 `public` |
+| `--object-name <path>` | 可选的安全相对路径，服务端仍会自动增加身份、日期和 UUID 前缀 |
+| `--signed-url-expires <seconds>` | 60～604800，默认 3600 |
+| `--content-type <mime>` | 可选；默认按扩展名推断 |
+| `--dry-run` | 只验证文件和参数，不上传 |
+
+返回 JSON 包含 `object_name`、`url`、`public_url`、`signed_url`、`signed_url_expires_in`、`visibility`、MIME 和文件大小。私有上传的 `public_url` 为 `null`，使用 `url` 或 `signed_url`；公开上传的 `url` 等于 `public_url`。
+
+## 附件读取与按需解析
+
+用户附件已经以原文件保存到当前 Profile 工作区。先按类型处理：
+
+- 图片：优先使用多模态视觉，不先做 OCR/MinerU。
+- 视频：读取原文件，按需抽帧；音轨需要时再转写。
+- 音频：使用转写工具，再结合原文件分析。
+- TXT/Markdown/JSON/CSV/HTML：直接读取。
+- XLSX：优先使用电子表格工具，保留 sheet、公式与单元格结构。
+- DOCX：优先使用 Word 结构化读取。
+- PDF：先尝试直接文本/页面读取；扫描版、复杂版面或表格再使用 MinerU。
+
+只有附件清单提供了 `文档 ID` 时才能调用 MinerU：
+
+```bash
+vps-work tools +attachment-parse --document-id <uuid>
+```
+
+命令默认等待解析完成并返回缓存的 Markdown。只触发一次可加 `--no-wait`。同一文档 ID 重复调用会复用服务端缓存，不重复创建解析记录。
+
+## 约束
+
+- 没有明确公开需求时保持 `private`，不要为了方便擅自公开企业文件。
+- 不要自行拼 OSS 地址或签名参数，始终使用命令返回值。
+- 不要把凭据、令牌或配置文件上传到公共对象。
+- 大于 50 MiB 的文件改用 V Drive 或业务专用分片上传流程。
+- 不要为了“先看看”就调用 MinerU；能用原文件或专项工具读取时优先直接读取。
+- 后续公共工具继续在 `vps-work tools +…` 下发现：先运行 `vps-work tools --help`。

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "VPS 公共工具"
+  short_description: "上传文件到统一 OSS 并返回公开或限时签名访问地址"
+  default_prompt: "Use $vps-tools to upload this file to OSS and return the appropriate access URL."