vps-work 1.0.0

package/skills/vps-current-user-identity/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: vps-current-user-identity
+description: |
+  适用场景：用户提到「我」「我的」「本人」「我自己」「我们部门」「本部门」「我的上级」「我的领导」「汇报对象」「我的销售订单 / 采购 / 审批 / 任务」「我创建的」「我负责的」「以我的名义」等任何一人称指代时使用。提供 3 条等价路径取当前身份：(1) CLI vps-work hr +me 一次性返回 user_id / employee_id / department_id / department_chain / manager_user_id；(2) Domain DSL 宏 @me / @my_partner / @my_employee / @my_department / @company / @companies 可在各域命令的 domain 参数中直接用，无需先取身份；(3) vps-work auth status --json 极简身份（uid / login）。常见误区：禁止把 partner_id 当 user_id、禁止扫 res.users 找自己、禁止重复取身份。触发词：我、我的、本人、我自己、我们部门、本部门、我上级、我领导、汇报对象、当前用户、current user、@me、auth status、self identity、me。
+---
+
+# 当前用户身份与组织信息
+
+# 当前用户身份与组织信息
+
+> **本技能是"参数型"skill，不是查询终点。**
+> 它只负责回答"我=哪个 user / partner / employee / 部门 / 公司"，**不负责"查我的转正日期 / 我的销售单 / 我的待办"这类业务取数**。
+> **取完身份/宏后，把 `@me` 等宏配合对应域命令（`vps-work <域> +…`）继续取数。**
+
+## 何时使用
+
+凡用户表达涉及**第一人称**就走这份技能，**不要再去猜或试**：
+
+- 「**我的**销售订单 / 采购单 / 待办 / 审批 / 任务 / 日报 / OKR」
+- 「**我创建的** / **我负责的** / **我审批过的** / **我跟进的**」
+- 「**我们部门** / **本部门** / **我下属** / **我管的人**」
+- 「**我的上级** / **我的领导** / **汇报对象**」
+- 「**以我的名义**发消息 / 代我转告」
+- 任何 `user_id == ?` / `partner_id == ?` / `employee_id == ?` 需要填「自己」的位置
+
+> 90% 的场景下，你**根本不需要**先 `vps-work hr +me`——只要把 `@me` / `@my_partner` / `@my_employee` / `@my_department` 写进 domain 即可（详见下方场景 A）。把身份当"业务模型上的一个参数"理解，不要把它当成独立任务。
+
+## Golden path（按场景选最短路径）
+
+### 场景 A：写 domain / 过滤条件 — 直接用宏，**不要**先取身份
+
+| 业务表达 | DSL 宏 | 等价 JSON |
+|---|---|---|
+| 我创建/我负责/我登录 | `@me` | `env.uid` |
+| 我作为联系人 | `@my_partner` | `env.user.partner_id.id` |
+| 我作为员工 | `@my_employee` | `hr.employee.user_id == env.uid` |
+| 我所在部门 | `@my_department` | 当前员工的 `department_id.id` |
+| 当前公司 | `@company` | `env.company.id` |
+| 我可访问的所有公司 | `@companies` | `env.companies.ids`（list） |
+
+把宏直接写进对应域命令的 domain 参数（PowerShell 外双内单是硬规矩）：
+
+```text
+--domain "user_id = @me AND state = 'sale'"
+```
+
+### 场景 B：需要把身份字段**回传给 UI / 摘要** — 一次性取全
+
+```bash
+vps-work hr +me
+```
+
+返回（节选）：
+
+```json
+{
+  "user_id": 12, "login": "lihua", "name": "李华",
+  "employee_id": 305, "job_title": "销售经理",
+  "department_id": 17, "department_name": "海外销售部",
+  "department_chain": ["销售中心", "海外销售部"],
+  "manager_id": 220, "manager_name": "张总", "manager_user_id": 9,
+  "source": "vertu"
+}
+```
+
+> 一次任务**只调一次**，把结果缓存起来后续复用。
+
+### 场景 C：只要一个 uid（极简）
+
+```bash
+vps-work auth status --json
+→ {"auth_mode": "user|agent", "uid": 12, "login": "lihua", ...}
+```
+
+仅当不需要 partner / employee / 部门时才用。
+
+---
+
+## 下一步：身份取到之后（**强制**）
+
+身份/宏拿到后，**把控制权交给对应业务域 skill**：
+
+1. **匹配** — 扫一遍可用 skill，看是否有专项技能对应用户的业务意图（如 `sale-performance-query` / `vps-product` / `vps-okr-management-assistant` / `vps-pending-approval-assistant` / `vps-daily-report-assistant`）
+2. **用对应域命令取数** — 把 `@me` / `@my_employee` / `@my_department` 等宏写进对应 `vps-work <域> +…` 的 domain 参数；字段/模型/业务实体未知时只读 `skills/` 文档，不要凭直觉拼未文档化的字段。员工姓名 → ID 的解析能力已不再提供，需由调用方给定 `employee_id` 或用 `vps-work hr +me` 取本人。
+
+| 反面例子 | 应改为 |
+|---|---|
+| 取到 `department_id=2124` → 在 domain 里硬编码 `department_id=2124` | 直接用宏：`--domain "department_id = @my_department"`（可移植、显式、无需先 me） |
+
+## 硬约束
+
+- **不是查询终点**：本 skill 只产出"身份/宏"，取到后交给对应业务域 skill（`vps-work <域> +…`）继续取数，字段只来自 `skills/` 文档。
+- **禁止**把 `partner_id` 当 `user_id` 用：sale.order / purchase.order / project.task 上的 `user_id` 是 `res.users.id`，**不是** `res.partner.id`。
+- **禁止**用 `search res.users` + `[('login', '=', ...)]` 「找我自己」：当前请求已是登录用户上下文，直接用 `env.uid` / `vps-work hr +me` 即可。
+- **禁止**在同一任务里**反复**调 `vps-work hr +me`：第一次调用后缓存复用；身份在一次任务期间不会变。
+- **禁止**在能用宏的场景下绕路先取身份。例如「列我本月的订单」直接 `user_id = @me AND date_order >= @month_start`，不要先 `vps-work hr +me`、再用 `user_id = 12`。
+- **禁止**虚构 `manager_user_id` / `department_chain`：模型上没有就是没有，必要时重跑 `vps-work hr +me` 看真实输出。
+- **禁止**凭直觉拼业务字段名（`date_of_joining` / `hire_date` 等）：字段只取自对应域 skill 的 `reference.md` / `references`，禁止凭空猜测或 schema 嗅探。
+
+## 常见坑点
+
+| 现象 | 根因 | 正确做法 |
+|---|---|---|
+| 身份取到就直接对业务模型拼字段，结果 `Invalid field` 反复报错 | 把本 skill 当查询终点，跳过专项文档 | 交给对应域 skill（`vps-work <域> +…`）；字段只来自 `skills/` 文档 |
+| 拿到 `employee_id` 后写 `domain "id = 6941"` | 把宏当成"取完就丢"，反而硬编码了 ID | 用 `domain "id = @my_employee"`（更可移植，宏会在 DSL 编译期校验） |
+| `user_id` 过滤不出结果但本人确实有数据 | 业务模型上 `user_id` 是 `res.users`，被填成了 `partner_id` | 用 `@me`（=`env.uid`）；如必须用 ID，从 `vps-work hr +me` 取 `user_id` |
+| 「我们部门」过滤少人 | 直接用了员工自己的 `department_id`，未递归子部门 | domain 里改用 `department_id child_of @my_department` |
+| 多公司环境少数据 | 默认上下文只看了 `@company` 一个 | 用 `company_id IN @companies` |
+| `vps-work hr +me` 没返回 `employee_id` | 当前用户在 HR 库里没有员工档案（外协 / 系统账号） | 退化路径：仅用 `user_id` / `partner_id` 维度过滤；不要假设 `employee_id` 一定存在 |
+
+## 关联技能
+
+- 未知字段先读对应专项 skill 文档，不做运行时字段嗅探。
+- **vps-pending-approval-assistant** / **vps-okr-management-assistant** — 都默认「我=登录用户」，遇到下属/转告/部门过滤时先回到本技能确认 ID。
+
+---
+
+## 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>"
+}
+```
+
+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-current-user-identity/reference.md

@@ -0,0 +1,79 @@
+
+# reference.md — 当前用户身份与组织信息
+
+## 1. 3 条路径技术细节
+
+| 路径 | 实现位置 | 鉴权要求 | 返回粒度 |
+|---|---|---|---|
+| **`vps-work hr +me`** / `vps-work hr +me` | Vertu 服务 `/v1/auth/me` + `hr-personnel-directory` | 已登录（user 或 bot） | 全字段（user / employee / department_chain / manager） |
+| Domain DSL 宏 `@me` 系列 | `vertu_addons/vt_ai_domain_dsl/services/macros.py` `expand_macro_token` | 已登录 + 装了 `vt_ai_domain_dsl` | 直接展开为 ID / list |
+| `vps-work auth status --json` | 当前会话状态 | 已登录 | 仅 uid / login / auth_mode |
+
+## 2. `vps-work hr +me` 字段表（来自 Vertu 服务身份与 HR 人员目录）
+
+| 字段 | 类型 | 说明 | 可能为空的情形 |
+|---|---|---|---|
+| `user_id` | int | `res.users.id` | 不会 |
+| `login` | str | 登录名 | 不会 |
+| `name` | str | 用户显示名 | 不会 |
+| `email` | str | 邮箱（无邮箱时回落到 `login`） | 不会 |
+| `lang` | str | 用户语言代码 | 未设语言 |
+| `tz` | str | 用户时区 | 未设时区 |
+| `employee_id` | int | `hr.employee.id` | 没有员工档案 / 未装 HR 模块 |
+| `employee_name` | str | 员工姓名 | 同上 |
+| `job_title` | str | 自由文本职位 | 字段为空 |
+| `job_id` / `job_name` | int / str | 职位档案 | 字段为空 |
+| `mobile_phone` / `work_email` | str | 工作联系方式 | 字段为空 |
+| `department_id` | int | 当前部门 ID | 员工无部门 |
+| `department_name` | str | 当前部门名 | 同上 |
+| `department_chain` | string[] | 从一级部门到当前部门的名称链路 | 同上 |
+| `manager_id` | int | 从员工所在部门向上解析到的最近有效部门负责人员工 ID（排除本人） | 没有可用部门负责人 |
+| `manager_name` | str | 上级姓名 | 同上 |
+| `manager_user_id` | int | 上级关联的 `res.users.id`（**用它做"我上级"过滤**） | 上级是无系统账号的纯员工 |
+| `employment_started_at` | str | Odoo 入职日期换算的上海时区起始边界（ISO 8601） | 员工档案未维护入职日期 |
+| `employment_ended_at` | str | Odoo 离职日期换算的就业有效期结束边界（ISO 8601） | 仍在职或员工档案未维护离职日期 |
+| `profile_unavailable` | str | 仅当 HR 人员目录（VPS 原生 HR 档案视图）在当前环境返回 503 不可用时出现，值为服务端原因 | 正常环境不出现 |
+
+> 当出现 `profile_unavailable` 时，`user_id` / `employee_id` / `department_id` / `department_path` / `department_chain`（按 `department_path` 拆分）仍来自平台会话且可用；`manager_*`、`job_*`、入离职日期等档案补充字段为空，不要因此重试。
+
+## 3. Domain DSL 宏对照表
+
+| 宏 | 展开为 | 适用模型 / 字段类型 |
+|---|---|---|
+| `@me` | `env.uid`（int） | 任何 `Many2one('res.users')` 字段，例如 `sale.order.user_id` / `crm.lead.user_id` / `project.task.user_ids` |
+| `@my_partner` / `@user_partner` | `env.user.partner_id.id`（int） | 任何 `Many2one('res.partner')` 字段，例如 `mail.message.author_id`、`sale.order.partner_id`（语义上"我作为联系人"） |
+| `@my_employee` / `@employee` | 当前 `hr.employee.id` | `hr.attendance.employee_id` / `hr.leave.employee_id` 等 |
+| `@my_department` | 当前员工的 `department_id.id` | `hr.employee.department_id` / `account.analytic.account.department_id` 等；可配 `child_of` 递归 |
+| `@company` | `env.company.id` | `Many2one('res.company')` |
+| `@companies` | `env.companies.ids`（list） | `Many2many('res.company')` 或 `IN` 操作 |
+
+> **缺失对应数据**时（如未配 HR 员工），DSL 编译期会抛 `DSLParseError(phase='macro')`，提示 hint：把过滤改成 `user_id = @me` 等不依赖 HR 的写法。
+
+## 4. PowerShell 引号规则速查
+
+```powershell
+# 正确：外双内单（宏写进对应域命令的 domain 参数）
+--domain "user_id = @me AND date_order >= @month_start"
+
+# 错误：外单内双（CJK / 引号会被吞）
+--domain '"user_id = @me"'
+```
+
+## 5. 反面教材回放（实际碰到过的试错链）
+
+| LLM 错误做法 | 错误原因 | 正确做法 |
+|---|---|---|
+| 拿到 `employee_id` 后**直接**对 `hr.employee` 拼猜测的字段（如 `date_of_joining`）→ `Invalid field` | 把本 skill 当查询终点，字段名是猜的 | 字段只取自对应域 skill 的 `reference.md` / `references`；员工字段未知时由调用方给定或交给 HR 域 skill，不要猜字段名 |
+| 凭直觉猜业务字段名而非查文档 | 字段口径未知 | 字段只取自 `skills/` 文档；缺口 `POST /ai/skills/v1/feedback` |
+| `search res.users [('login','=','...')]` 找自己 | 拿不到 `login`、即便拿到也是多此一举 | 直接用 `@me` 宏或 `vps-work hr +me` |
+| `domain=[('partner_id','=', uid)]` 过滤"我的订单" | 模型上 `user_id` 才是 `res.users`，`partner_id` 是客户 | `domain="user_id = @me"` |
+| 先 `vps-work hr +me` 取 `department_id=17`，再 domain 写 `department_id = 17` | 失去递归子部门能力，下属团队数据漏掉 | `domain="department_id child_of @my_department"` |
+| 用 `manager_id` 当过滤，期望"我上级审过的单子" | `manager_id` 是 `hr.employee.id`，不是 `res.users.id` | 用 `manager_user_id`（res.users.id）；或显式 `domain="user_id = <manager_user_id>"` |
+| 多公司环境只看到一个公司的数据 | 当前请求只激活了 `env.company` | `domain="company_id IN @companies"` |
+
+## 6. 关联
+
+- 顶层 CLI 命令注册：`src/commands/hr/shortcuts.ts` 的 `+me`。
+- 宏定义源码：`vertu_addons/vt_ai_domain_dsl/services/macros.py`。
+- 极简身份：`vps-work auth status --json` 的 `uid` / `login` 字段。
+- 反向查询「下属/上级链」：见 `vps-okr-management-assistant` 中的 `child_of` 递归用法。

package/skills/vps-daily-report-assistant/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: vps-daily-report-assistant
+description: |
+  面向 Vertu 日报系统的查询与提交。用户要查每日应填未交或打卡未交日报名单、本部门日报、员工日报、自己的日报、可汇报任务、提交今日日报、管理员删除当日日报测试数据、同步日报助手卡片时使用。入口 CLI 为 `vps-work report +…`，当前提供 `+missing-daily-reports`、`+checkin-missing`、`+mine`、`+department`、`+tasks`、`+submit`、`+delete-today`、`+sync`。触发词：日报、部门日报、应填未交、未交日报、打卡未交、员工日报、我的日报、日报任务、提交日报、删除今日日报、同步日报助手、daily report。
+metadata:
+  requires:
+    bins: ['vps-work']
+  cliHelp: 'vps-work report --help'
+---
+
+# 日报助理（未交比对 / 员工日报 / 自助提交）
+
+**开始前 Read [`../vps-shared/SKILL.md`](../vps-shared/SKILL.md)。**
+
+统一入口是 `vps-work report +…`。自助查询与提交走本项目 Vertu 服务的 `/v1/daily-report/*` REST；打卡未交比对与员工日报汇总走本项目 Vertu 服务的日报查询脚本。`+submit` 默认把日报消息写入本系统 IM 的当前用户部门组织群；只有显式传 `--legacy-push` 时才走旧 PMS/小小V IM 推送接口。
+
+## 何时使用
+
+- 查每日应填但没有提交日报的名单：`+missing-daily-reports`。
+- 查打卡了但没提交日报的名单：`+checkin-missing`。
+- 查某员工或自己的日报记录：`+mine`。
+- 查当前登录用户所在部门及子部门成员日报：`+department`。
+- 查我可以填写日报的未完成研发任务：`+tasks`。
+- 提交今日日报并推送当前用户部门群：`+submit`。
+- 管理员删除今天的日报测试数据：`+delete-today`。
+- 同步日报助手会话与今日日报卡片：`+sync`。
+
+用户明确说“每日应填但未提交”时使用 `+missing-daily-reports`。用户说“打卡但未交”时使用 `+checkin-missing`；后者不会把请假、出差未打卡、离职等本来不应提交的人混入。
+
+## 命令清单
+
+| 命令 | 服务接口 | 说明 |
+|------|----------|------|
+| `+missing-daily-reports --date YYYY-MM-DD` | `GET /api/v1/tasks/tasks/export-missing-daily-reports` | 每日应填但未提交日报名单 |
+| `+checkin-missing --date YYYY-MM-DD` | 日报查询脚本 `checkin_missing` | 打卡但未提交日报名单；可选 `--department-id` `--limit` |
+| `+mine --user-id N --start-time YYYY-MM-DD --end-time YYYY-MM-DD` | `GET /v1/daily-report/mine` | 统一日报列表；省略 `--user-id` 时查当前登录用户，日期省略默认今天 |
+| `+department --date YYYY-MM-DD --limit 500` | `GET /v1/daily-report/department` | 默认查当前用户部门树；`--department-path` 需要指定部门权限，`--all-departments` 需要全公司权限 |
+| `+tasks --limit 50` | `GET /v1/daily-report/tasks` | 我的可汇报研发任务 |
+| `+submit` | `POST /v1/daily-report/submit` | 提交今日日报，更新任务进度并推送本系统 IM 当前用户部门群 |
+| `+delete-today --confirm` | `POST /v1/daily-report/admin/delete-today` | 管理员删除今天的日报提交记录；默认撤回本系统 IM 日报消息 |
+| `+sync` | `POST /v1/daily-report/sync` | 同步日报助手会话与今日日报卡片 |
+
+## 提交日报
+
+单任务提交：
+
+```bash
+vps-work report +submit \
+  --task-id 2454 \
+  --progress 80 \
+  --spent-hours 6 \
+  --content "今日进展" \
+  --tomorrow "明日计划"
+```
+
+多任务提交可用 `--items-json` 或 `--params` 传 `items`：
+
+```bash
+vps-work report +submit \
+  --items-json '[{"task_id":2454,"progress":80,"spent_hours":3,"content":"接口联调"},{"task_id":2455,"progress":60,"spent_hours":3,"content":"问题修复"}]' \
+  --tomorrow "继续联调并补充测试"
+```
+
+`items[]` 元素字段：
+
+| 字段 | 说明 |
+|------|------|
+| `task_id` | PMS 任务数字 ID |
+| `progress` | 目标进度，0-100，必须高于当前进度 |
+| `spent_hours` | 今日投入小时数，(0, 24] |
+| `content` | 今日工作内容；多行会拆成多条进度 |
+
+可选字段：
+
+| 字段 | 说明 |
+|------|------|
+| `im_channel_id` | 本系统 IM 会话 id；省略时优先推送当前用户所在的日报群，没有日报群时按当前用户部门路径复用或创建组织群 |
+| `legacy_push` | 设为 `true` 时改走旧 PMS/小小V IM 推送接口；默认 `false` |
+| `channel_id` | 旧 IM channel_id；仅 `legacy_push=true` 时有效 |
+| `chat_group_name` | 旧 IM 群名称；仅 `legacy_push=true` 时有效 |
+
+## 管理员删除今日日报
+
+用于测试当日日报提交。只允许管理员执行，且必须显式传 `--confirm`：
+
+```bash
+vps-work report +delete-today --confirm
+```
+
+默认行为：
+
+| 项 | 说明 |
+|----|------|
+| 删除对象 | 当前登录用户今天的 `daily_report_push_records` |
+| 本系统 IM | 撤回当前用户今天由 `+submit` 发出的本系统 IM 日报消息 |
+| 任务进度 | 默认不删除任务进度记录，不回滚任务当前 progress |
+
+可选项：
+
+| 参数 | 说明 |
+|------|------|
+| `--user-id N` | 管理员指定要删除日报的用户；省略为当前登录用户 |
+| `--with-progress` | 同时删除日报 payload 中引用的今日任务进度，并按剩余进度记录回算任务 progress；测试重放时才使用 |
+| `--keep-im-message` | 不撤回本系统 IM 日报消息 |
+
+## 工作流
+
+1. 用户问“每日应填但谁没交日报”时，用 `vps-work report +missing-daily-reports --date YYYY-MM-DD`；用户明确说“打卡没写日报”时用 `+checkin-missing`。日期缺失先确认或按自然语言解析。
+2. 用户查询自己的日报时用 `vps-work report +mine`；查询本部门成员日报时用 `vps-work report +department --date YYYY-MM-DD`；管理员点名查某员工时传 `--user-id`。
+3. 用户要填日报但没给任务 ID 时，先用 `vps-work report +tasks --limit 50` 列出可汇报任务。
+4. 提交日报前检查 `task_id`、`progress`、`spent_hours`、`content`、`tomorrow` 是否齐全；信息不全先追问。
+5. 用户要“删除今天的日报/重测提交”时，仅管理员可用 `vps-work report +delete-today --confirm`；除非明确要求重放进度，否则不要加 `--with-progress`。
+6. 提交后如需要刷新卡片，调用 `vps-work report +sync`。
+7. 输出时先说明结论，再列日期、人员、部门、任务 ID、项目、进度等关键字段。
+
+## 硬约束
+
+- 以 `vps-work report --help` 列出的命令为准。
+- `+missing-daily-reports` 是“每日应填但未交”口径；`+checkin-missing` 是“打卡但未交”口径，二者不可混用。
+- `+mine` 的 `--user-id` 是 `res.users.id`，仅管理员可查询其他用户；姓名解析不在本命令内完成。
+- `+department` 默认范围由当前登录用户决定；`--department-path` 需要 `daily_report.departments.selected:read`，`--all-departments` 需要 `daily_report.departments.all:read`，两者不能同时使用。
+- `task_id` 是 PMS 任务数字 ID，不是 task-center UUID。
+- `+delete-today` 是管理员测试命令，必须带 `--confirm`；默认不删除任务进度，`--with-progress` 只在明确需要重放提交进度时使用。
+- 写操作前若用户意图不明确或字段缺失，先确认再提交。
+- 日期参数使用 `YYYY-MM-DD`。
+
+## 常见场景
+
+```bash
+# 查某天每日应填但未提交日报名单
+vps-work report +missing-daily-reports --date 2026-07-13
+
+# 查某天打卡但未提交日报名单
+vps-work report +checkin-missing --date 2026-06-19
+
+# 查某员工本月日报（管理员）
+vps-work report +mine --user-id 12837 --start-time 2026-06-01 --end-time 2026-06-19
+
+# 查我本月日报
+vps-work report +mine --start-time 2026-06-01 --end-time 2026-06-19
+
+# 查本部门及子部门成员某天日报
+vps-work report +department --date 2026-06-19
+
+# 查指定其他部门（需要指定部门权限）
+vps-work report +department --date 2026-06-19 --department-path "销售中心 / 华东区"
+
+# 查所有部门（需要全公司权限）
+vps-work report +department --date 2026-06-19 --all-departments
+
+# 查可汇报任务
+vps-work report +tasks --limit 50
+
+# 同步日报助手卡片
+vps-work report +sync
+```
+
+---
+
+## 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-daily-sales-report/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: vps-daily-sales-report
+description: |
+  公司级全部门销售总览，含销售额/销量、新老客销售占比、环比/同比、商品系列周月趋势、IOT 商品页订单数、已对账销售收款明细、销售单开票申请状态、正式发票、会计凭证与付款状态、含/不含代理折扣、最新组织渠道、高定销售、智能穿戴、大折叠黄金3/黄金4/金钻、部门目标达成率。支持任意时间窗口（CLI: period 枚举或 YYYY-MM-DD、--start-date/--end-date；execute/API: start_date/end_date），数据基于代码化销售行口径 + 管理端同源的部门目标，通过 `vps-work sales +…` 取数。本技能面向公司全部门汇总，并有新客/老客结构、环比/同比/目标达成。触发词：总销日报、公司日销、日报、今日销售、本月销售、已对账收款、销售收款明细、申请开票、开票状态、开票审批、正式发票、会计凭证、付款状态、商品趋势、IOT、商品订单数、商品折扣、含代理、不含代理、高定、智能穿戴、大折叠、黄金3、黄金4、金钻、新客销售、上月、上周、环比、同比、部门达成率、全部门销售。
+---
+
+# 公司总销日报
+
+# 公司总销日报
+
+## 何时使用
+
+用户要查公司级全部门销售总览：今日/本月/上月/任意时间段销售额/量、部门排名、环比同比、目标达成。销售实际走代码化销售行口径，部门目标默认来自管理端“部门业绩目标”同源的 `部门OKR_1`，统一通过 `vps-work sales +…` 取数。
+
+## 业绩口径
+
+下列脚本**默认不含定金**：`LEFT JOIN mv_product` 过滤 `"定金"='是'` 的 SKU：
+
+- `headline_kpi` / `dept_breakdown` / `customer_sales_mix` / `dept_comparison` / `dept_target_achievement` / `monthly_daily_trend` / `employee_ranking_top_bottom`
+- `refund_summary`（业绩侧退款，剔除定金退款）
+
+需含定金口径时显式传 `include_deposit=true`。`with_without_deposit_breakdown` 本身双口径展示。
+
+## 公司OKR计算规则
+
+- **公司OKR = 所有部门OKR之和**：默认汇总 `部门OKR_1`，与管理端“部门业绩目标”页面一致；不传 dept_l1 时默认涵盖所有公司
+- **零销售部门仍计入公司OKR**：`sales_amount=0` 且 `target_amount>0` 的部门不能被静默排除；公司整体目标必须对全部目标行求和
+- **Postgres 新表用于核对**：需要检查迁移后的部门目标数据时显式传 `--okr-source postgres` / `okr_source=postgres`
+- **达成率** = 实际销额 / 期间目标 × 100
+
+## 工作流
+
+1. **澄清** — 时间窗口（CLI 用 `--period` 枚举/日期或 `--start-date`/`--end-date`）、部门层级（一级/二级/三级/四级）、聚合维度
+2. **选择脚本** — 对照 reference.md 脚本一览表选择：headline_kpi / dept_breakdown / customer_sales_mix / dept_comparison / dept_target_achievement / order_finance / sales_invoice_status / reconciled_sales_receipts / with_without_deposit_breakdown / refund_summary / service_dept_sales_summary
+3. **执行** — 使用 `vps-work sales +headline-kpi` / `+dept-breakdown` / …（见 `reference.md`）；复杂参数用各快捷上的 `--params` 或 `--params-file` 合并 JSON。
+4. **解读** — 先给核心数字（窗口总额 + 环比/同比），再列部门 Top N
+
+商品销售必须使用精确维度：大折叠=`product_subcategory=VERTU ALPHAFOLD`，高定=`product_style=高定`，黄金3/黄金4/金钻=`product_style_details`；智能穿戴使用 `smart_wearable=true`。不得用商品名模糊搜索代替聚合口径。
+
+用户说“全公司渠道/最新架构”时使用 `group_by=org_channel`；周/月趋势使用 `monthly_daily_trend` 的 `grain=week/month`，款式明细加 `breakdown_by=product_style1`。
+
+IOT 用 `product_category=IOT配件`，分类包含手链。`monthly_daily_trend` 的 `orders` 是去重销售单数，`product_order_count` 才是与 vps-ep 商品页一致的销售/分摊明细行数；折扣同时返回 `incl_agent` / `excl_agent`，均排除置换。完整字段公式读取 `vps-product`。
+
+## 时间窗口（统一约定）
+
+所有脚本统一接受下列时间参数（优先级由高到低）：
+
+1. `--start-date` + `--end-date`（YYYY-MM-DD，闭区间；execute/API 为 `start_date` + `end_date`）— 完全自定义
+2. `--period YYYY-MM-DD` 或单独 `--start-date YYYY-MM-DD` — 单日查询
+2. `period` 枚举 — `today / yesterday / this_week / last_week / this_month / last_month / this_quarter / last_quarter / this_year / last_year / last_n_days / custom`
+3. `days`（仅当 `period=last_n_days` 时使用）
+4. 默认 `this_month`
+
+`period=custom` 必须同时提供 CLI `--start-date` 与 `--end-date`（execute/API 为 `start_date` 与 `end_date`），否则报错。
+
+## 部门过滤（统一约定）
+
+所有脚本统一接受 `dept_l1 / dept_l2 / dept_l3 / dept_l4 / dept_l5`，全部可选，按 AND 拼接。空串等同于不过滤。
+
+不要使用 `dept`、`department`、`dept_name`、`department_name` 表示销售部门；这些字段无法区分一级/二级/三级/四级部门，服务端会拒绝。用户只说“部门”时，先确认层级或用组织结构查询定位。
+
+## 硬约束
+
+- **中文标识符双引号**：销售结果中的 `"销售日期"`、`"一级部门"` 等中文字段按 PostgreSQL 规则处理
+- **取数走 CLI 封装**：脚本通过 `vps-work sales +…` 直连规范视图执行，无需手写连接
+- **行数控制**：可在 SQL 内自由使用 `LIMIT n`、`LIMIT n OFFSET m`、`OFFSET m LIMIT n`、`LIMIT %s`、`FETCH FIRST n ROWS ONLY` 等任一标准写法；若末尾未写，服务端按 `default_sql_limit`（500）追加默认上限，并以 `max_sql_rows`（2000）做硬截断兜底
+- **OKR JOIN 必须先缩销售**：禁止目标明细直连未聚合销售行；必须先按 部门 × 月份 聚合销售，再与目标合并
+- **列表必须翻页**：返回 `pagination.has_more=true` 时，用 `page=next_page` 继续查询，不能把第一页 `rows` 当全量
+- **排除项必须披露**：凡使用默认或显式排除（包括不含定金、部门/人员/商品过滤、仅保留有实绩行），回答必须逐项说明；分页、Top N、权限范围造成的非全量覆盖也必须说明。若计算排除后指标，必须同时给出排除项及排除前后的口径，不能把它称为未加限定的“公司整体”。
+
+## 常见坑点
+
+| 现象 | 根因 | 正确做法 |
+|------|------|---------|
+| 环比/同比为空 | 上期/去年同期数据不存在（新部门） | 脚本用 COALESCE 处理 NULL，展示时标注"无同期数据" |
+| 目标达成率异常高/低 | `部门OKR_1` 目标部门名与销售匹配部门不一致 | 先查 `+dept-monthly-okr` 核对管理端同源目标；必要时用 `--okr-source postgres` 对比迁移后的新表 |
+| 部门销售为空 | 使用了 `匹配部门` 而非 `一级部门` | odoo_sale 视图直接用 `一级部门`~`四级部门` |
+| `period=custom` 报错 | 必填 `--start-date/--end-date`（execute/API: `start_date/end_date`） | 同时提供两个日期，或者改用枚举 period / `--period YYYY-MM-DD` |
+
+## 关联技能
+
+- **vps-sale-personnel-efficiency** — 人效 / 个人业绩 / 个人 OKR / PK 榜
+- **sale-performance-query** — 销售业绩聚合入口
+
+---
+
+## 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` / `references/*.md` 已列的 `vps-work sales +…`
+   快捷命令；高级参数走 `--params` 或 `/v1/execute` 的 `script_key`。
+
+2. 嵌在本 skill 脚本里的销售行、商品定金与 Postgres OKR 目标源承载了规范业务口径；
+   不要绕过封装自行拼接原始字段，以免丢失校准。
+
+3. 字段 / 模型 / 业务实体语义只取自本 skill 的 `reference.md` / `references/*.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 文档。