diff --git a/skills/mono/SKILL.md b/skills/mono/SKILL.md index 192ec8fe..fee8b882 100644 --- a/skills/mono/SKILL.md +++ b/skills/mono/SKILL.md @@ -44,10 +44,10 @@ cli_version: ">=1.0.15" |-------------------|------------------------------------------------------|----------------------------------------------------------------| | `aisearch` | AI搜问（搜人首选）：按姓名/部门/职位/职责/上级/下级/手机号/工号维度找人，"谁负责 XX/XX 的负责人/某事项/某项目的人"统一走本产品 | [aisearch.md](./references/products/aisearch.md) | | `aitable` | AI表格：Base/数据表/字段/记录/视图/附件/图表/仪表盘/导入导出/模板搜索 | [aitable.md](./references/products/aitable.md) | -| `attendance` | 考勤：打卡结果/打卡流水/考勤组查询/考勤规则/汇总统计/假期类型/假期余额（P0 已落地，部分管理类命令仍属 P1） | [attendance.md](./references/products/attendance.md) | +| `attendance` | 考勤：考勤组与规则查询(rules)/个人打卡详情(record get)/批量班次查询(shift list)/考勤统计摘要(summary)，仅此 4 个命令组 | [attendance.md](./references/products/attendance.md) | | `calendar` | 日历：日历列表/日程/参与者/附件/响应/会议室/闲忙查询/时间建议 | [calendar.md](./references/products/calendar.md) | | `chat` | 群聊与机器人：搜索群/建群/群成员管理/改群名/消息发送(文本/Markdown/图片/文件)/拉取消息/@我/特别关注/机器人群发/单聊/撤回/转发/引用回复/Webhook/**查询**已有机器人 | [chat.md](./references/products/chat.md) | -| `contact` | 通讯录：用户查询(当前用户/搜索/详情/手机号)/花名册档案(学历/家庭/银行卡/合同)/离职员工查询(姓名/时间范围/部门)/部门查询(搜索/详情/子部门/成员)/角色查询(主管/管理员/财务/HR 等 label)/特别关注列表 | [contact.md](./references/products/contact.md) | +| `contact` | 通讯录：用户查询(当前用户/搜索/详情/手机号)/花名册档案(学历/家庭/银行卡/合同)/离职员工查询(姓名/时间范围/部门)/部门查询(搜索/详情/子部门/成员)/特别关注列表（按角色/职责找人请走 `aisearch`） | [contact.md](./references/products/contact.md) | | `dev` | 开放平台开发者：**新建/配置机器人（建号）**、建联调试（把机器人接到本地 agent 的 Stream）、应用生命周期（创建/更新/删除/凭证/权限/成员/事件订阅）、开放平台文档搜索 | [dev.md](./references/products/dev.md) | | `devdoc` | 开放平台文档：搜索开发文档 | [devdoc.md](./references/products/devdoc.md) | | `ding` | DING消息：发送/撤回（应用内/短信/电话） | [ding.md](./references/products/ding.md) | @@ -94,13 +94,13 @@ cli_version: ">=1.0.15" ## 意图判断决策树 -用户提到"找人/搜人/谁负责 XX/某事项的负责人/某项目的人/团队成员/上级/下级/按工号找人/按手机号找人" → `aisearch` +用户提到"找人/搜人/谁负责 XX/某事项的负责人/某项目的人/某职责/某角色（主管/管理员/财务/HR 等）由谁担任/团队成员/上级/下级/按工号找人/按手机号找人" → `aisearch`（按角色或职责找人用 `aisearch person --dimension duty`） 用户提到"表格/多维表/AI表格/记录/数据/视图/图表/仪表盘" → `aitable` 用户提到"考勤/打卡/排班" → `attendance` 用户提到"日程/日历/会议室/约会/时间建议" → `calendar` 用户提到"群聊/建群/群成员/群管理/发消息/发图片消息/发文件消息/发 Markdown 消息/截图发钉钉/转发消息/引用回复/@我/特别关注消息/机器人发消息/Webhook/机器人群发/机器人单聊/通知" → `chat`（仅 IM 操作；创建/配置/建联机器人走 `dev`，见下） 用户提到"创建机器人/新建机器人/建机器人/配置机器人/机器人建号/建联/把机器人连到/接入 agent/opencode/claude/qoder/连接 agent/开放平台应用/开发者应用/app 创建/应用凭证/事件订阅/dws dev" → `dev` -用户提到"通讯录/同事/部门/组织架构/子部门/部门多少人/离职员工/离职名单/离职花名册/花名册/员工档案/学历/家庭/银行卡/紧急联系人/合同/角色/主管角色/管理员角色/财务/HR/特别关注/星标联系人" → `contact` +用户提到"通讯录/同事/部门/组织架构/子部门/部门多少人/离职员工/离职名单/离职花名册/花名册/员工档案/学历/家庭/银行卡/紧急联系人/合同/特别关注/星标联系人" → `contact`（按角色/职责找人不在此，走 `aisearch`） 用户提到"开发/API/调用错误 文档" → `devdoc` 用户提到"DING/紧急消息/电话提醒" → `ding` 用户提到"钉钉文档/云文档/读写文档/知识库里的文档/浏览知识库内容/知识库内搜索文档/块级编辑/文档评论/文档复制移动" → `doc` diff --git a/skills/mono/references/best_practices/08-directory.md b/skills/mono/references/best_practices/08-directory.md index 95bfc5d9..16ab9fc0 100644 --- a/skills/mono/references/best_practices/08-directory.md +++ b/skills/mono/references/best_practices/08-directory.md @@ -5,7 +5,7 @@ ## 专用规则（#8 非 lite 步骤必守） -- **角色类查人优先 label**：用户说"角色为XX的员工/XX角色的员工/XX角色的人员""所有主管/主管理员/财务/HR/总经理"等角色类型人员时，**优先** `contact label list` 获取全部角色 → 匹配目标角色 → `contact label list-members --id `；若用户明确指定了角色名称（如"角色为总经理"），则先用 `contact label get --names ` 精确匹配，**若精确匹配无结果，降级 `label list` 模糊匹配**（如用户说"管理员"可匹配到"主管理员"和"子管理员"）。 +- **角色/职责类查人优先 aisearch**：用户说"角色为XX的员工/XX角色的人员""所有主管/财务/HR/总经理""谁负责 XX"等角色/职责类查询时，**优先** `aisearch person --keyword "<角色或职责>" --dimension duty`（`contact label` 角色查询命令已下线，不再可用）。 - **脚本优先**：按部门拉成员**优先** `python scripts/contact_dept_members.py --query "<部门名>"`（`--dry-run` / `--format json`）；失败再 `dept search` → `dept list-members --depts`。 - **详情链路**：用户要子部门、职位、联系方式、汇报关系等，在 `user search` 之后**必须**再 `contact user get --ids `；禁止仅用 search 的浅表字段交差。 - **`user get` 后部门仍空**：不得过早结束或只建议用户去 App；须在 CLI 能力内尝试 **用户点名的部门** `dept search` + `dept list-members` 等与 `userId` 交叉核对，再结构化汇总「返回中有哪些字段 / 哪些为空及可能原因」。 @@ -20,7 +20,7 @@ ## 与其他场景消歧 -- **按角色/职位类型查人（主管/管理员/财务等）** → 优先 `contact label list` + `label list-members`；label 精确命中角色维度，返回完整名单；aisearch 是语义模糊搜索不保证完整性。 +- **按角色/职位类型查人（主管/管理员/财务等）** → 优先 `aisearch person --dimension duty`（按职责维度找人）；`contact label` 角色查询命令已下线。 - **搜人/找人/找同事/查工号/查手机号** → 首选 **`aisearch person`**（AI 语义搜索，支持姓名/部门/职责/上下级/手机号/工号维度），见 `aisearch`（开源版未引入，悟空内部产品）。 - **需要 userId 做后续操作 / 按手机号查 / 按 userId 查详情** → `contact`（精确查询）。 - **纯查部门与子部门成员 / 验证归属 / 组织关系** → `contact`。 @@ -31,7 +31,7 @@ | Recipe | 步骤 | |--------|------| -| `lookup-label-members` | 1. `contact label list` → 浏览全部角色，匹配目标角色的 labelId
2. `contact label list-members --id ` → 该角色下的成员列表 | +| `lookup-role-members` | 1. `aisearch person --keyword "<角色或职责>" --dimension duty` → 按职责维度找人（`contact label` 已下线） | | `search-user-by-mobile` | 1. `contact user search-mobile --mobile "<手机号>"` → 按需 `contact user get --ids ` | | `lookup-dept-id` | 1. `contact dept search --query "<部门关键词>"` → 回显 `deptId`（多命中须消歧） | | `list-subdepts` | 1. 已有父 `deptId` → `contact dept list-children --dept <父deptId>` 直接取直属子部门列表
2. 只有部门名 → 先 `lookup-dept-id` 取 `deptId`，再 `list-children` | diff --git a/skills/mono/references/intent-guide.md b/skills/mono/references/intent-guide.md index 27e3e631..a572736b 100644 --- a/skills/mono/references/intent-guide.md +++ b/skills/mono/references/intent-guide.md @@ -82,10 +82,10 @@ **用 `report` 的场景**： - "帮我看看收到的日报" — 日志收件箱 -- "帮我写/提交今天的日报（钉钉日志模版）" — 先 `report template list` / `template detail`，再 `report create` +- "帮我写/提交今天的日报（钉钉日志模版）" — 先 `report template list` / `template get`，再 `report entry submit --contents-file .json` - "有什么日志模版" — 查看模版 - "看看这个日志的已读统计" — 阅读状态 -- "我发过的日志有哪些" — 已发送列表 (`report sent`) +- "我发过的日志有哪些" — 已发送列表 (`report outbox list`) - 用户提到"日报"、"周报"、"日志" **用 `todo` 的场景**： diff --git a/skills/mono/references/products/attendance.md b/skills/mono/references/products/attendance.md index 8c46578a..c4098d41 100644 --- a/skills/mono/references/products/attendance.md +++ b/skills/mono/references/products/attendance.md @@ -1,545 +1,28 @@ # 考勤 (attendance) 命令参考 -> **【开源版命令可用性提示】** 当前开源 dws 已落地 P0 5 条命令：`attendance check result`、`attendance check record`、`attendance group search`、`attendance vacation balance`、`attendance vacation types`。文档中其余 P1 阶段命令（`class` / `overtime` / `adjustment` / `group settings` / `report` / `schedule` / `boss-check` 等共 28 条）暂未通过服务发现推全，调用会返回 `unknown command`，将在后续批次落地。 +> **【命令合法性 — 必读】** 当前 dws 只提供以下 4 个考勤命令组，其余命令（check / checkin / class / group settings / adjustment / overtime / schedule / approve / selfsetting / globalsetting / report / vacation / boss-check 等）均**不存在**，调用会返回 `unknown command`： +> +> | 命令 | 用途 | +> |------|------| +> | `attendance rules` | 查询考勤组与考勤规则（我属于哪个考勤组、打卡范围、弹性工时） | +> | `attendance record get` | 查询某个人某天的考勤打卡详情 | +> | `attendance shift list` | 批量查询多名员工在某日期范围内的班次 | +> | `attendance summary` | 查询某个人的考勤统计摘要（周/月） | -> **【必读】日期范围严格计算规则 — 所有含 --start/--end 或 --from/--to 的命令均适用** +> **【日期计算规则】** 所有含日期参数的命令均适用，禁止随意猜测日期范围，必须按下表精确计算： > -> **禁止随意猜测日期范围，必须按以下规则精确计算后再组装命令参数：** -> -> | 用户表达 | --start（含）| --end（含）| 说明 | +> | 用户表达 | 起始（含）| 结束（含）| 说明 | > |---------|------------|------------|------| -> | 本周 / 这周 / 当周 | 本周**周一** | 本周**周日** | 周一为一周的第一天，周日为最后一天 | -> | 上周 / 上一周 | 上周**周一** | 上周**周日** | 同上，往前推一周 | -> | 本月 / 这个月 / 当月 | 本月 **1 日** | 本月**最后一天**（28/29/30/31）| 必须计算当月实际天数 | -> | 上月 / 上个月 | 上月 **1 日** | 上月**最后一天** | 同上，往前推一个月 | -> | 今天 / 今日 | **今天** | **今天** | start == end | -> | 昨天 | **昨天** | **昨天** | start == end | +> | 本周 / 这周 | 本周**周一** | 本周**周日** | 周一为一周第一天 | +> | 上周 | 上周**周一** | 上周**周日** | 往前推一周 | +> | 本月 / 这个月 | 本月 **1 日** | 本月**最后一天** | 必须计算当月实际天数 | +> | 上月 | 上月 **1 日** | 上月**最后一天** | 往前推一个月 | +> | 今天 / 昨天 | 当天 | 当天 | start == end | > -> **必须遵守：** -> 1. **本周一定是周一到周日**，严禁将"本周"解释为周一到周五或其他任意范围。 -> 2. **本月一定是 1 日到该月实际最后一天**，严禁将"本月"截断为 1 日到 28 日或其他固定天数。 -> 3. 计算日期时必须参考当前系统时间，不得使用硬编码或模糊估算。 -> 4. 如果用户指定了具体日期范围（如"4月1日到4月15日"），直接使用用户给定的范围，不套用上述规则。 -> 5. 日期格式统一按各命令要求：`shift list` / `check result` 等使用 `YYYY-MM-DD`；`report query-data` / `report query-leave` 等使用 `yyyy-MM-dd HH:mm:ss`（start 取当天 `00:00:00`，end 取当天 `23:59:59`）。 +> 计算日期必须参考当前系统时间，不得硬编码或模糊估算；用户给定具体日期范围时直接采用。 ## 命令总览 - -### 查询打卡结果 -``` -Usage: - dws attendance check result [flags] -Example: - dws attendance check result --users userId1,userId2 --start 2026-04-01 --end 2026-04-30 --limit 50 -Flags: - --start string 起始日期, 格式 YYYY-MM-DD (必填) - --end string 结束日期, 格式 YYYY-MM-DD, 不超过 1 个月 (必填) - --limit int 分页大小, 默认 100, 范围 1-1000 (可选) - --offset int 分页偏移量, 默认 0 (可选) - --users string 用户 ID 列表, 逗号分隔, 最多 100 个 (必填) -``` - -返回每条记录含：用户 ID、工作日期、时间结果（Normal/Late/Early/Absenteeism/NotSigned）、位置结果、计划打卡时间、实际打卡时间、打卡流水 ID。时间跨度不超过 1 个月，最多 100 人。 - -### 查询打卡流水 -``` -Usage: - dws attendance check record [flags] -Example: - dws attendance check record --users userId1 --start 2026-04-01 --end 2026-04-30 -Flags: - --start string 起始日期, 格式 YYYY-MM-DD (必填) - --end string 结束日期, 格式 YYYY-MM-DD, 不超过 1 个月 (必填) - --users string 用户 ID 列表, 逗号分隔 (必填) -``` - -返回每条记录含：用户 ID、实际打卡时间、打卡地址、打卡经纬度、打卡类型（OnDuty/OffDuty）、定位方式（Map/Wifi/etc）。时间跨度不超过 1 个月。 - -### 查询审批单 -``` -Usage: - dws attendance approve list [flags] -Example: - dws attendance approve list --users userId1 --types overtime,leave --start 2026-04-01 --end 2026-04-30 -Flags: - --start string 起始日期, 格式 YYYY-MM-DD (必填) - --end string 结束日期, 格式 YYYY-MM-DD (必填) - --types string 审批类型, 逗号分隔: overtime/trip/leave/patch (必填) - --users string 用户 ID 列表, 逗号分隔 (必填) -``` - -审批类型映射：overtime=加班, trip=出差, leave=请假, patch=补卡。返回每条记录含：用户 ID、审批标签、审批子类型、审批类型、生效时间、时长、时长单位、流程实例 ID。 - -### 查询补卡/请假/加班审批提交链接 (必须走引导流程) -``` -Usage: - dws attendance approve templates [flags] -Example: - dws attendance approve templates --type leave - dws attendance approve templates --type REPAIR_CHECK - dws attendance approve templates --type 加班 -Flags: - --type string 审批类型：repair-check/patch/补卡、leave/请假、overtime/加班，或 REPAIR_CHECK/LEAVE/OVERTIME（必填） -``` - -当用户提到需要提交补卡、请假或加班时，优先使用该命令查询考勤审批表单模板提交链接，并引导用户点击返回的 `submitUrl` 提交。 -`corpId` 和 `opUserId` 由系统参数自动注入，无需通过命令参数传入。 -审批类型映射：补卡=`REPAIR_CHECK`，请假=`LEAVE`，加班=`OVERTIME`。返回结果为列表，每条记录包含 `approveType`、`formName`、`processCode`、`submitUrl`。 -#### 引导用户自主选择合适的表单模板流程 -如果返回多个表单模板，必须将多个可用模板都返回给用户，并引导用户根据实际场景自主选择合适的模板提交： -- 请假场景：可根据 `formName` 将与用户请假类型更匹配的模板放在前面展示。例如用户明确说年假、事假、病假、调休时，将名称中包含对应假期类型的模板靠前；如果用户只泛化表达“请假”，将名称最通用的请假模板靠前，例如“请假”“员工请假”“通用请假”等，避免把专项或特殊场景模板放在最前。 -- 补卡/加班场景：可将名称与“补卡”或“加班”最直接匹配的模板放在前面展示。 -- 回复用户时不要直接裸露任何 `submitUrl`，所有返回的表单模板都必须使用 Markdown 可点击链接格式展示：`[formName](submitUrl)`，例如 `[员工请假](https://...)`。如存在更匹配的模板，可以放在列表前面，但不要只返回推荐模板，必须同时返回其它可用模板供用户选择，且每个模板都应是用户可直接点击的 Markdown 链接。 - -### 导入排班记录（排班 = 为员工安排工作日期和班次, 写场景接口，必须走二次确认流程） -``` -Usage: - dws attendance schedule import [flags] -Example: - dws attendance schedule import --group-id 123456 \ - --schedules '[{"userId":"user001","classId":123,"workDate":"2026-04-22","checkBeginTime":"09:00","checkEndTime":"18:00"}]' \ - --yes -Flags: - --group-id string 考勤组（必填，传入考勤组ID） - --schedules string 排班记录 JSON 数组（必填） - --yes 跳过确认提示 -``` - -为排班制考勤组导入排班记录。`--schedules` 为 JSON 数组，每条记录包含： -- `userId`: 员工ID -- `classId`: 班次ID -- `workDate`: 工作日期（YYYY-MM-DD），如 2026-04-22 -- `checkBeginTime`: 开始打卡时间 -- `checkEndTime`: 结束打卡时间 -- `isRest`: 是否休息日 Y/N（可选） - -#### AI 调用 `schedule import` 的二次确认流程 - -`schedule import` 是写操作，会为考勤组导入或变更员工排班。AI 调用时必须按以下流程执行，不得在未确认的情况下直接导入： - -1. **识别写操作**：用户表达“导入排班 / 设置排班 / 安排排班 / 给员工排班 / 批量排班”等意图时，命中 `schedule import`。 -2. **收集必要参数**：必须明确 `--group-id` 和 `--schedules`，并确认排班记录中的 `userId`、`classId`、`workDate`、`checkBeginTime`、`checkEndTime`、`isRest` 等字段。 -3. **展示导入摘要并反问确认**：向用户展示考勤组 ID、导入员工数量、涉及日期范围、班次 ID 列表，以及排班记录明细摘要，并询问是否确认执行导入。 -4. **用户确认后再执行导入**：只有用户明确确认后，才可以执行 `dws attendance schedule import ... --format json`。 - -确认话术示例： - -```text -即将导入排班记录，请确认： -- 考勤组 ID： -- 员工数量： -- 日期范围： ~ -- 班次 ID： -- 排班明细： - - ： -，班次 - -是否确认执行导入？ -``` - -如用户明确要求跳过确认，或命令中明确包含全局 `--yes`，可跳过二次确认。 - -### 获取排班记录 - -**禁止直接调用 `dws attendance schedule get`。必须先 `read_file` 读取 [attendance-schedule.md](./attendance-schedule.md) 后按其中的「排班查询导出工作流」执行。** - -- 任何"查询排班"、"查看排班"、"XX考勤组的排班"、"X月份的排班"场景，**一律走 attendance-schedule.md 工作流**，由脚本 `attendance_schedule_export.py` 统一处理 -- 脚本自动处理：分批查询（超 20 人自动分批）、userId→姓名转换、classId→班次名称转换、排班表格式 Excel 输出 -- 违反后果：人数多时接口超时/报错、输出裸 userId 和 classId 用户看不懂、无排班表格式 -- **此处不提供 `schedule get` 的 Usage/Flags，防止绕过工作流直接拼命令。完整参数由 attendance-schedule.md 工作流中的脚本内部使用。** - -### 查询当前用户可管理的所有班次详情 -``` -Usage: - dws attendance class search [flags] -Example: - dws attendance class search - dws attendance class search --query "早班" --filter-type MINE_OWN - dws attendance class search --page 1 --limit 50 -Flags: - --filter-type string 班次类型: ALL 全部班次 / MINE_OWN 我负责的 (可选) - --query string 班次名称关键字, 模糊搜索 (可选) - --page int 页码, 从 1 开始 (可选, 默认 1) - --limit int 每页条数, 最大 200 (可选, 默认 20) -``` - -### 查询班次详情 -``` -Usage: - dws attendance class get [flags] -Example: - dws attendance class get --class-id 1170996821 -Flags: - --class-id int 班次 ID (必填) -``` - -根据班次 ID 查询该班次的完整详细信息。班次 ID 可从 `class search` 返回结果中提取，也有可能来源于用户手动输入。 - -### 创建班次 (写场景接口，必须走二次确认流程) -**强制执行流程**：此命令为写操作，Agent 调用时必须遵守以下流程： -1. 先向用户展示待执行操作的完整参数摘要，包括班次名称、上下班时间、休息时段等 -2. 使用 `ask_human` 或返回待确认状态，等待用户明确确认 -3. 用户确认后，再传全局 `--yes` 执行命令 - -**禁止未经用户确认直接执行或自动添加 `--yes`。** -``` -Usage: - dws attendance class create [flags] -Example: - dws attendance class create --name "早班" --class-vo '{"sections":[{"times":[{"checkType":"OnDuty","checkTime":"08:00","across":0},{"checkType":"OffDuty","checkTime":"17:00","across":0}]}]}' --timeout 10 - # 带休息时段（12:00-13:00 午休） - dws attendance class create --name "测试CLI" --class-vo '{"sections":[{"times":[{"checkType":"OnDuty","checkTime":"09:00","across":0},{"checkType":"OffDuty","checkTime":"18:00","across":0}]}],"setting":{"topRestTimeList":[{"checkType":"OnDuty","checkTime":"12:00","across":0},{"checkType":"OffDuty","checkTime":"13:00","across":0}]}}' --timeout 10 -Flags: - --name string 班次名称 (必填) - --owner string 班次负责人 userId (可选) - --class-vo string 完整 TopAtClassVO JSON 字符串, 包含 sections 等复杂子对象 (必填) -``` - -创建一个新班次。`--name` 和 `--class-vo`（包含 `sections`）必填。`sections` 定义班次的上下班时间段，支持多段上下班，每段包含 `times` 数组（有且只能有两个对象：上班+下班）。由于保存班次耗时较久，建议加 `--timeout 10`。 - -`checkTime` 字段统一使用 "HH:mm" 格式（如 "09:00"、"17:30"），CLI 自动转换为服务端所需格式。 - -`--class-vo` 支持字段： -- `name`(string, 必填) `owner`(string, 可选) -- `sections`([]object, 必填): 每个对象含 `times`([]object)，每个 time 含 `checkType`(OnDuty/OffDuty, 必填) `checkTime`("HH:mm", 必填) `across`(0/1, 必填) `freeCheck`(bool) `beginMin`(number, -1不限制) `endMin`(number, -1不限制) -- `setting`(object, 可选): `seriousLateMinutes`(严重迟到分钟) `absenteeismLateMinutes`(旷工迟到分钟) `attendDays`(出勤天数) `topRestTimeList`([]object, 仅单段上下班时可用，最多3段: checkType/checkTime("HH:mm")/across) - -### 更新班次 (写场景接口，必须走二次确认流程) -**强制执行流程**：此命令为写操作，Agent 调用时必须遵守以下流程： -1. 先向用户展示待执行操作的完整参数摘要，包括班次 ID、要修改的字段含义及新值 -2. 使用 `ask_human` 或返回待确认状态，等待用户明确确认 -3. 用户确认后，再传全局 `--yes` 执行命令 - -**禁止未经用户确认直接执行或自动添加 `--yes`。** -``` -Usage: - dws attendance class update [flags] -Example: - dws attendance class update --class-id 1170996821 --name "新早班" --timeout 10 - dws attendance class update --class-id 1170996821 --class-vo '{"sections":[{"times":[{"checkType":"OnDuty","checkTime":"08:30","across":0},{"checkType":"OffDuty","checkTime":"17:30","across":0}]}]}' --timeout 10 - # 带休息时段（12:00-13:00 午休） - dws attendance class update --class-id 1170996821 --class-vo '{"sections":[{"times":[{"checkType":"OnDuty","checkTime":"09:00","across":0},{"checkType":"OffDuty","checkTime":"18:00","across":0}]}],"setting":{"topRestTimeList":[{"checkType":"OnDuty","checkTime":"12:00","across":0},{"checkType":"OffDuty","checkTime":"13:00","across":0}]}}' --timeout 10 -Flags: - --class-id int 班次 ID (必填) - --name string 班次名称 (可选，不传则保持原值) - --owner string 班次负责人 userId (可选，不传则保持原值) - --class-vo string 完整 TopAtClassVO JSON 字符串，用于修改复杂子对象 (可选) -``` - -更新班次配置。`--class-id` 必填，其余均可选，仅需对要修改的字段进行赋值，未传字段会自动从已有配置补充。小改用单字段 flag（如 `--name`）；修改上下班时间、休息时段等复杂子对象时用 `--class-vo` 传入完整 JSON。`--class-vo` 与单字段 flag 同时传入时，单字段 flag 优先级更高。 - -`checkTime` 字段统一使用 "HH:mm" 格式（如 "09:00"、"17:30"），CLI 自动转换为服务端所需格式。 - -`--class-vo` 支持字段（均可选，只需包含要修改的字段）： -- `name`(string) `owner`(string) -- `sections`([]object): 每个对象含 `times`([]object)，每个 time 含 `checkType`(OnDuty/OffDuty) `checkTime`("HH:mm") `across`(0/1) `freeCheck`(bool) `beginMin`(number, -1不限制) `endMin`(number, -1不限制) -- `setting`(object): `seriousLateMinutes` `absenteeismLateMinutes` `attendDays` `topRestTimeList`([]object: checkType/checkTime("HH:mm")/across) - -由于保存班次耗时较久，建议加 `--timeout 10`。 - -### 分页查询补卡规则，支持按名称搜素 -``` -Usage: - dws attendance adjustment search [flags] -Example: - dws attendance adjustment search --page 1 --limit 20 - dws attendance adjustment search --query "标准" --page 1 --limit 50 -Flags: - --page int 页码, 从 1 开始 (必填, 默认 1) - --query string 补卡规则名称关键字, 模糊搜索 (可选) - --limit int 每页条数, 200 以内 (必填, 默认 20) -``` - -### 查询补卡规则详情 -``` -Usage: - dws attendance adjustment get [flags] -Example: - dws attendance adjustment get --adjustment-id 12345 -Flags: - --adjustment-id int 补卡规则主键 ID (必填) -``` - -根据补卡规则主键 ID 查询对应的补卡规则详情。主键 ID 可从 `adjustment search` 返回结果中提取，也有可能来源于用户手动输入。**注意：已被删除或被更新覆盖的补卡规则无法查询到。** - -### 分页查询加班规则，支持按名称搜素 -``` -Usage: - dws attendance overtime search [flags] -Example: - dws attendance overtime search --page 1 --limit 20 - dws attendance overtime search --query "节假日" --page 1 --limit 50 -Flags: - --page int 页码, 从 1 开始 (必填, 默认 1) - --query string 加班规则名称关键字, 模糊搜索 (可选) - --limit int 每页条数, 200 以内 (必填, 默认 20) -``` - -### 查询加班规则详情 -``` -Usage: - dws attendance overtime get [flags] -Example: - dws attendance overtime get --overtime-id 12345 -Flags: - --overtime-id int 加班规则主键 ID (必填) -``` - -根据加班规则主键 ID 查询对应的加班规则详情。主键 ID 可从 `overtime search` 返回结果中提取，也有可能来源于用户手动输入。**已被删除或更新覆盖的加班规则也可以查到。** - -### 查询考勤组列表 -``` -Usage: - dws attendance group search [flags] -Example: - dws attendance group search --query "研发" - dws attendance group search --type FIXED --limit 50 - dws attendance group search --page 1 --limit 20 -Flags: - --query string 考勤组名称关键字, 模糊搜索 (可选) - --page int 页码, 从 1 开始 (必填, 默认 1) - --limit int 每页条数, 200 以内 (必填, 默认 20) - --query-ble 是否查询蓝牙设备列表 (可选, 默认 false) - --query-position 是否查询地理定位和 Wifi 名称 (可选, 默认 false) - --type string 考勤组类型: FIXED 固定班制 / TURN 排班制 / NONE 自由工时 (可选) -``` - -### 查询考勤组全量信息 -``` -Usage: - dws attendance group get [flags] -Example: - dws attendance group get --group-id 123456 -Flags: - --group-id int 考勤组 ID (必填) -``` - -根据考勤组 ID 查询该考勤组的全量信息。考勤组 ID 可从 `group search` 返回结果中提取，也有可能来源于用户手动输入。如果只需查询成员、打卡地址、蓝牙、Wifi 子集，请使用 `group filtered-get` 以节省查询成本。 -返回结果中如含成员 userId 列表，必须调用 `dws contact user get --ids ,,...`（支持逗号分隔传多个 ID），将 userId 转换为员工姓名后再输出；不得直接输出裸 userId - -### 按需查询考勤组部分信息 -``` -Usage: - dws attendance group filtered-get [flags] -Example: - dws attendance group filtered-get --group-id 123456 --member - dws attendance group filtered-get --group-id 123456 --position --wifi -Flags: - --group-id int 考勤组 ID (必填) - --member 是否查询考勤组成员信息 (可选, 默认 false) - --position 是否查询打卡地址 (可选, 默认 false) - --wifi 是否查询打卡 Wifi (可选, 默认 false) - --bles 是否查询打卡蓝牙 (可选, 默认 false) -``` - -强烈建议在仅需查询成员、打卡地址、蓝牙、Wifi 时调用该命令，避免全量查询带来的性能开销。考勤组 ID 可从 `group search` 返回结果中提取，也有可能来源于用户手动输入。 -返回结果中如含成员 userId 列表，必须调用 `dws contact user get --ids ,,...`（支持逗号分隔传多个 ID），将 userId 转换为员工姓名后再输出；不得直接输出裸 userId - -### 更新考勤组成员 (写场景接口，必须走二次确认流程) -**强制执行流程**：此命令为写操作，Agent 调用时必须遵守以下流程： -1. 先向用户展示待执行操作的完整参数摘要，包括考勤组 ID、要添加/移除的成员列表 -2. 使用 `ask_human` 或返回待确认状态，等待用户明确确认 -3. 用户确认后，再传全局 `--yes` 执行命令 - -**禁止未经用户确认直接执行或自动添加 `--yes`。** - -``` -Usage: - dws attendance group update-members [flags] -Example: - dws attendance group update-members --group-id 123456 --add-users userId1,userId2 - dws attendance group update-members --group-id 123456 --remove-users userId1 - dws attendance group update-members --group-id 123456 --add-depts deptId1 --remove-users userId2 -Flags: - --group-id int 考勤组 ID (必填) - --add-users string 添加考勤人员 userId 列表, 逗号分隔, 最多 20 个 (可选) - --remove-users string 删除考勤人员 userId 列表, 逗号分隔, 最多 20 个 (可选) - --add-extra-users string 添加无需考勤的人员 userId 列表, 逗号分隔, 最多 20 个 (可选) - --remove-extra-users string 删除无需考勤的成员 userId 列表, 逗号分隔, 最多 20 个 (可选) - --add-depts string 添加考勤部门 ID 列表, 逗号分隔, 最多 20 个 (可选) - --remove-depts string 删除考勤部门 ID 列表, 逗号分隔, 最多 20 个 (可选) -``` - -对指定考勤组的成员进行增删操作。--group-id 必填，其余参数均为可选，但至少需要传入一个变更项，否则命令拒绝执行。每次调用各参数最多传 20 个 ID。"无需考勤"人员指考勤组内豁免打卡的成员（如高管）。 - -### 更新考勤组配置 (写场景接口，必须走二次确认流程) -**强制执行流程**：此命令为写操作，Agent 调用时必须遵守以下流程： -1. 先向用户展示待执行操作的完整参数摘要，包括考勤组 ID、要修改的字段含义及新值 -2. 使用 `ask_human` 或返回待确认状态，等待用户明确确认 -3. 用户确认后，再传全局 `--yes` 执行命令 - -**禁止未经用户确认直接执行或自动添加 `--yes`。** -``` -Usage: - dws attendance group update [flags] -Example: - dws attendance group update --group-id 123456 --name "研发考勤组" --timeout 10 - dws attendance group update --group-id 123456 --owner userId1 --timeout 10 - dws attendance group update --group-id 123456 --classIds '[1374234767]' --timeout 10 - dws attendance group update --group-id 123456 --group-vo '{"positions":[{"title":"总部","address":"北京市...","latitude":39.9,"longitude":116.4,"offset":200}]}' --timeout 10 -Flags: - --group-id int 考勤组 ID (必填) - --name string 考勤组名称 (可选) - --type string 考勤组类型：FIXED 固定班制 / TURN 排班制 / NONE 自由工时 (可选) - --owner string 考勤组主负责人 userId (可选) - --enable-outside-check 是否允许外勤打卡 true/false (可选) - --classIds string 所选班次 id 列表, JSON 数组格式, 如 '[123,456]' (可选) - --group-vo string 完整 groupVO JSON 字符串, 用于修改复杂子对象 (可选) -``` - -更新考勤组配置。--group-id 必填，其余均可选，但至少需指定一个修改项。仅需对要修改的字段进行赋値，其余字段会自动从已有配置补充。小改用单字段 flag；修改打卡地址、wifi、蓝牙设备、循环排班等复杂子对象时用 `--group-vo` 传入完整 JSON。`--group-vo` 与单字段 flag 同时传入时，单字段 flag 优先级更高。 - -`--group-vo` 支持字段（均可选，只需包含要修改的字段）： -- 基础：`name`(名称) `type`(FIXED/TURN/NONE) `owner`(主负责人 userId) `managerList`([]string 子负责人) `skipHolidays`(bool，只在固定班制和自由工时生效) `defaultGroup`(bool) `classIds`([]number，所选班次 id，只有固定班制和排班制才有班次，自由工时没有) -- 打卡范围：`trimDistance`(微调距离) `enablePositionOfGps/Wifi/Ble`(bool) -- 打卡地址：`positions`([]对象: title/address/latitude/longitude/offset，其中 offset 为该地址允许的打卡范围米) -- Wifi：`wifis`([]对象: ssid/macAddr/groupId) -- 蓝牙：`bleDeviceVOList`([]对象: name/deviceUid/sn/productType/devServId) -- 外勤：`enableOutsideCheck`(bool) `enableOutsideCameraCheck/Remark/Apply`(bool) `outsideCheckApproveMode`(NO_NEED_APPROVE/APPROVE_FIRST/CHECK_FIRST/APPROVE_EVERYTIME) `outSideCheckApplyType`(1全天/2上班/3下班) `forbidHideOutSideAddress`(bool) `enableOutSideUpdateNormalCheck`(下班时允许外勤卡更新内勤卡) `enableOnDutyNormalUpdateOutsideCheck`(上班时允许内勤卡更新外勤卡) -- 打卡方式：`enableCameraCheck/openCameraCheck` `openFaceCheck` `enableFaceStrictMode` `enableFaceBeauty`(bool) `onlyMachineCheck`(bool) `permitMaxBeaconCount`(number) `disableCheckWhenRest`(bool，休息日打卡需审批，只在固定班制和排班制生效) -- 固定班制设置（FIXED）：`defaultClassId`(number) `workDayClassList`([]number，共7个值代表周日到周六每天的班次id，为0表示当天休息，如[0,1279240003,0,0,0,0,0]表示只有周一上班) -- 排班制设置（TURN）：`disableCheckWithoutSchedule`(bool，true=未排班时禁止打卡) `enableEmpSelectClass`(未排班时员工可选班次) `enableScheduleAutoMatch`(未排班时系统自动匹配) - - 循环排班（非必填，不设置则由管理员手动排班）：`cycleDays`(number) `startCycleDate`(时间戳，毫秒) `cycleScheduleList`([]对象: cycleName/groupId/isValid(Y/N)/itemList[{classId/className/isValid}]) -- 自由工时设置（NONE）：`workDays`([1-7]，1=周一7=周日) `freeCheckDayStartMinOffset`(number，距0点分钟数) `freeCheckCoreTime`(最短工作时长，分钟) `freeCheckDemandWorkMinutes`(要求打卡时长，分钟) `freeCheckSettingVO`(对象: freeCheckType(CYCLE上下班交替/MAX_TIME_UPDATE最大时间打卡)/freeWorkDayLackSwitch/freeOnDutyLackMinOffset/freeOffDutyLackMinOffset/delimitOffsetMinutesBetweenDays/freeCheckGapVO{onOffCheckGapMinutes/offOnCheckGapMinutes}) `freeGroupSpecialDayVO`(对象: specialOnDutyDays[]/specialOffDutyDays[]) - -### 创建考勤组 (写场景接口，必须走二次确认流程) -**强制执行流程**：此命令为写操作，Agent 调用时必须遵守以下流程： -1. 先向用户展示待执行操作的完整参数摘要，包括考勤组名称、类型、班次列表等 -2. 使用 `ask_human` 或返回待确认状态，等待用户明确确认 -3. 用户确认后，再传全局 `--yes` 执行命令 - -**禁止未经用户确认直接执行或自动添加 `--yes`。** -``` -Usage: - dws attendance group create [flags] -Example: - dws attendance group create --name "研发考勤组" --type FIXED --group-vo '{"defaultClassId":1170996821,"workDayClassList":[0,1170996821,0,0,0,0,0]}' --timeout 10 - dws attendance group create --name "自由工时分组" --type NONE --timeout 10 -Flags: - --name string 考勤组名称 (必填) - --type string 考勤组类型：FIXED 固定班制 / TURN 排班制 / NONE 自由工时 (必填) - --owner string 考勤组主负责人 userId (可选) - --group-vo string 完整 groupVO JSON 字符串，用于传入复杂子对象 (可选) -``` - -创建一个新的考勤组。`--name` 和 `--type` 必填，`--type` 必须为 FIXED/TURN/NONE 之一。 - -**条件必填（type=FIXED 固定班制时）**：`--group-vo` 必须包含 `workDayClassList`（工作日班次列表，不能为空，共 7 个值，代表周日到周六每天的班次 ID，为 0 表示当天休息）和 `defaultClassId`（默认班次 ID，不能为 null）。 - -`--group-vo` 可用字段说明（与 `group update` 的 `--group-vo` 一致，均可选，只需包含要设置的字段）： - -【基础信息】 - id number 考勤组 id（创建时无需传入，由服务端分配） - name string 考勤组名称（必填） - type string 考勤组类型：FIXED（固定班制）/ TURN（排班制）/ NONE（自由工时）（必填） - owner string 考勤组主负责人 userId - managerList []string 考勤组子负责人 userId 列表 - skipHolidays bool 节假日自动排休（只有固定班制和自由工时考勤组生效） - defaultGroup bool 是否默认考勤组 - classIds []number 所选班次 id 列表(只有固定班制和排班制才有班次，自由工时没有) - -【打卡范围与定位】 - trimDistance number 定位允许微调距离（米） - enablePositionOfGps bool 打卡是否允许开启 GPS 定位 - enablePositionOfWifi bool 打卡是否允许开启 Wifi 定位 - enablePositionOfBle bool 打卡是否允许开启蓝牙定位 - enableMacCheck bool 开启 MAC 地址校验 - checkDistanceType string 打卡距离类型：NORMAL(正常) / OUTER_ADDRESS(仅允许在外勤地址打卡) - wifiCompanyId number 允许打卡的 Wifi 公司 ID - -【打卡地址】 - positions []object 打卡地址列表，每个对象字段： - title string 地址名称 - address string 详细地址 - latitude number 纬度 - longitude number 经度 - offset number 该地址允许的打卡范围（米） - -【打卡 Wifi】 - wifis []object 打卡 Wifi 列表，每个对象字段： - ssid string Wifi 名称 - macAddr string MAC 地址 - groupId number 所属考勤组 ID - -【蓝牙设备】 - bleDeviceVOList []object 蓝牙设备列表，每个对象字段： - name string 设备名称 - deviceUid string 设备 ID - sn string 序列号 - productType string 产品类型 - devServId number 设备服务 ID - -【外勤打卡设置】 - enableOutsideCheck bool 是否允许外勤打卡 - openOutsideCameraCheck bool 外勤打卡是否开启拍照 - enableOutsideRemark bool 是否允许外勤备注 - enableOutsideApply bool 外勤打卡是否需审批 - forbidHideOutSideAddress bool 禁止隐藏外勤打卡地址 - enableOutSideUpdateNormalCheck bool 下班时允许外勤卡更新内勤卡 - enableOnDutyNormalUpdateOutsideCheck bool 上班时允许内勤卡更新外勤卡 - outsideCheckApproveMode string 外勤审批模式：NO_NEED_APPROVE / APPROVE_FIRST / CHECK_FIRST / APPROVE_EVERYTIME - outSideCheckApplyType number 外勤打卡申请类型：1 全天 / 2 上班 / 3 下班 - -【打卡方式】 - openCameraCheck bool 是否开启拍照打卡 - enableFaceStrictMode bool 是否开启人脸严格模式 - enableFaceBeauty bool 是否开启人脸美颜 - onlyMachineCheck bool 是否仅允许考勤机打卡 - permitMaxBeaconCount number 允许最大蓝牙信标数量 - disableCheckWhenRest bool 休息日打卡需审批（只在固定班制和排班制生效） - -【固定班制设置（FIXED）】 - defaultClassId number 默认班次 ID - workDayClassList []number 工作日班次列表，共 7 个值代表周日到周六每天的班次 id，为 0 表示当天休息。 - 例如 [0,1279240003,0,0,0,0,0] 表示只有周一上班 - -【排班制设置（TURN）】 - disableCheckWithoutSchedule bool 未排班时禁止打卡 - enableEmpSelectClass bool 未排班时员工可选班次 - enableScheduleAutoMatch bool 未排班时系统自动匹配 - cycleDays number 循环排班周期天数 - startCycleDate number 循环排班开始日期（时间戳，毫秒） - cycleScheduleList []object 循环排班列表： - cycleName string 循环排班名称 - groupId number 考勤组 ID - isValid string 是否生效：Y/N - itemList []object 循环排班明细： - classId number 班次 ID - className string 班次名称 - isValid string 是否生效：Y/N - -【自由工时设置（NONE）】 - workDays []number 工作日，[1-7]，1=周一，7=周日 - freeCheckDayStartMinOffset number 距 0 点分钟数 - freeCheckCoreTime number 最短工作时长（分钟） - freeCheckDemandWorkMinutes number 要求打卡时长（分钟） - freeCheckSettingVO object 自由打卡设置： - freeCheckType string 打卡类型：CYCLE（上下班交替）/ MAX_TIME_UPDATE（最大时间打卡） - freeWorkDayLackSwitch bool 工作日缺卡开关 - freeOnDutyLackMinOffset number 上班缺卡分钟数偏移 - freeOffDutyLackMinOffset number 下班缺卡分钟数偏移 - delimitOffsetMinutesBetweenDays number 跨天切割分钟数偏移 - freeCheckGapVO object 打卡间隔： - onOffCheckGapMinutes number 上班到下班最小间隔（分钟） - offOnCheckGapMinutes number 下班到上班最小间隔（分钟） - freeGroupSpecialDayVO object 特殊日期设置： - specialOnDutyDays []number 特殊上班日期 - specialOffDutyDays []number 特殊休息日期 - -当使用 `--group-vo` 传入完整 JSON 时，`--name`、`--type`、`--owner` 仍可覆写 JSON 中的同名字段。由于保存考勤组耗时较久，建议加 `--timeout 10`。 - -> **新建考勤组并同时添加成员的工作流**：`group create` 不支持在创建时直接传入成员列表。若用户需要在新建考勤组后立即添加成员，必须先执行 `group create` 创建考勤组，从返回结果中提取 `groupId`，再执行 `group update-members --group-id --add-users ...` 完成成员添加。 - -### 查询某个人的考勤统计摘要 -``` -Usage: - dws attendance summary [flags] -Example: - dws attendance summary --user USER_ID --date "2026-03-12 15:00:00" -Flags: - --date string 工作日期, 格式 yyyy-MM-dd HH:mm:ss (必填) - --user string 钉钉用户 ID (必填) -``` - ### 查询考勤组与考勤规则 ``` Usage: @@ -548,754 +31,91 @@ Example: dws attendance rules --date 2026-03-14 dws attendance rules --date "2026-03-14 09:00:00" Flags: - --date string 考勤日期, 格式 YYYY-MM-DD 或 yyyy-MM-dd HH:mm:ss (必填) + --date string 考勤日期，格式 YYYY-MM-DD 或 yyyy-MM-dd HH:mm:ss (必填) +Notes: + - 用于回答：我属于哪个考勤组、打卡范围是什么、弹性工时怎么算 + - 认证信息（corpId、optUserId）由系统自动注入，无需手动传入 ``` -查询考勤组/考勤规则。例如：我属于哪个考勤组、打卡范围是什么、弹性工时怎么算。 - -### 查询个人规则设置 +### 查询个人考勤详情 ``` Usage: - dws attendance selfsetting get [flags] + dws attendance record get [flags] Example: - dws attendance selfsetting get --setting-scene checkRemind --user --format json - dws attendance selfsetting get --setting-scene fastCheck --user --format json + dws attendance record get --user USER_ID --date 2026-03-08 Flags: - --setting-scene string 查询设置项: checkRemind/fastCheck/checkResultNotify/lackRemind/personalAttendStatNotify/bossAttendStatNotify (必填) - --user string 查询用户 ID (必填) + --date string 查询日期，格式 YYYY-MM-DD (必填) + --user string 钉钉用户 ID (必填) ``` -调用 MCP 工具 query_self_setting 查询个人规则设置，包括打卡提醒、极速打卡、打卡结果通知、缺卡提醒、个人考勤统计通知、团队考勤统计通知等设置项。MCP 入参 `userId` 必填；CLI 的 `--user` 也必填，必须显式传入目标用户 ID。认证信息 `corpId` 和 `opUserId` 由当前登录上下文自动注入，无需手动传入。 - -`--setting-scene` 枚举值： -- `checkRemind`: 打卡提醒 -- `fastCheck`: 极速打卡 -- `checkResultNotify`: 打卡结果通知 -- `lackRemind`: 缺卡提醒 -- `personalAttendStatNotify`: 个人考勤统计通知 -- `bossAttendStatNotify`: 团队考勤统计通知 - -返回 `ServiceResult`，包含 `success`、`code`、`message`、`result`。`result` 可能根据 `--setting-scene` 仅返回对应设置项相关字段。常见字段包括： -- `checkRemind`: `checkRemindSetting`、`checkRemindUserOnDuty`、`checkRemindUserOffDuty`、`enableOndutyCheckRemindOfPc`、`enableOffdutyCheckRemindOfPc` -- `fastCheck`: `ondutyCheckType`、`offdutyCheckType`、`ondutyRemindStartMin`、`ondutyRemindEndMin`、`offdutyRemindStartMin`、`offdutyRemindEndMin`、`fastCheckLateNeedConfirm`、`canUpdateOffDuty`、`voiceRemindSwitch`、`vibrationRemindSwitch` -- `checkResultNotify`: `checkResultMsg`, 取值 0 表示关闭, 1 表示开启 -- `lackRemind`: `lackSendTodoMsg`、`lackRemindUser`, 取值 0 表示关闭, `null` 或 1 表示开启 -- `personalAttendStatNotify`: `personDailyReportSwitch`、`personWeekReportType`、`personMonthReportType` -- `bossAttendStatNotify`: `bossPushStartMin`、`bossWeekReportType`、`bossMonthReportType` - -其中周报/月报通知渠道枚举值：0 表示全关闭，1 表示工作通知，2 表示钉邮，3 表示工作通知和钉邮。 - -### 更新保存个人规则设置 (写场景接口，必须走二次确认流程) -**强制执行流程**：此命令为写操作，Agent 调用时必须遵守以下流程： -1. 先向用户展示待执行操作的完整参数摘要，包括目标用户、设置场景、当前值、新值和最终命令参数 -2. 使用 `ask_human` 或返回待确认状态，等待用户明确确认 -3. 用户确认后，再传全局 `--yes` 执行命令 - -**禁止未经用户确认直接执行或自动添加 `--yes`。** - +### 批量查询员工班次信息 ``` Usage: - dws attendance selfsetting save [flags] + dws attendance shift list [flags] Example: - # 开启打卡结果通知（Agent 调用时，必须先完成 ask_human 二次确认，确认后再追加 --yes 执行） - dws attendance selfsetting save --setting-scene checkResultNotify --user --check-result-msg 1 --yes --format json - # 更新极速打卡设置（Agent 调用时，必须先完成 ask_human 二次确认，确认后再追加 --yes 执行） - dws attendance selfsetting save --setting-scene fastCheck --user --onduty-check-type 3 --voice-remind-switch=true --yes --format json - # 更新打卡提醒设置（Agent 调用时，必须先完成 ask_human 二次确认，确认后再追加 --yes 执行） - dws attendance selfsetting save --setting-scene checkRemind --user --check-remind-user-on-duty=false \ - --check-remind-setting '{"onDutyRemind":{"openRemind":true,"remindMinutes":10}}' --yes --format json + dws attendance shift list --users userId1,userId2 --start 2026-03-03 --end 2026-03-07 Flags: - --setting-scene string 更新设置项: checkRemind/fastCheck/checkResultNotify/lackRemind/personalAttendStatNotify/bossAttendStatNotify (必填) - --user string 更新用户 ID (必填) - --check-remind-setting string 打卡提醒 DING 渠道设置 JSON - --check-remind-user-on-duty 打卡提醒工作通知渠道：用户个人上班打卡提醒开关 - --check-remind-user-off-duty 打卡提醒工作通知渠道：用户个人下班打卡提醒开关 - --enable-onduty-check-remind-of-pc PC 端弹窗渠道：上班打卡提醒开关 - --enable-offduty-check-remind-of-pc PC 端弹窗渠道：下班打卡提醒开关 - --onduty-check-type int 上班极速打卡方式：1 提醒打卡，2 不提醒且不自动打卡，3 自动打卡 - --offduty-check-type int 下班极速打卡方式：1 提醒打卡，2 不提醒且不自动打卡，3 自动打卡 - --onduty-remind-start-min int 上班打卡提醒开始时间，单位：分钟 - --onduty-remind-end-min int 上班打卡提醒结束时间，单位：分钟 - --offduty-remind-start-min int 下班打卡提醒开始时间，单位：分钟 - --offduty-remind-end-min int 下班打卡提醒结束时间，单位：分钟 - --fast-check-late-need-confirm 迟到时是否需要二次确认 - --can-update-off-duty 是否允许用户更新下班打卡设置 - --voice-remind-switch 极速打卡提示音开关 - --vibration-remind-switch 极速打卡震动提醒开关 - --check-result-msg int 打卡结果通知开关：0 关闭，1 开启 - --lack-send-todo-msg int 缺卡提醒待办渠道：0 关闭，null 或 1 开启 - --lack-remind-user int 缺卡提醒工作通知渠道：0 关闭，null 或 1 开启 - --person-daily-report-switch int 个人考勤统计日报推送开关：0 关闭，1 开启 - --person-week-report-type int 个人考勤统计周报通知渠道：0 全关闭，1 工作通知，2 钉邮，3 工作通知和钉邮 - --person-month-report-type int 个人考勤统计月报通知渠道：0 全关闭，1 工作通知，2 钉邮，3 工作通知和钉邮 - --boss-push-start-min int 团队考勤统计日报推送开始时间，单位：分钟；-1 表示关闭日报推送 - --boss-week-report-type int 团队考勤统计周报通知渠道：0 全关闭，1 工作通知，2 钉邮，3 工作通知和钉邮 - --boss-month-report-type int 团队考勤统计月报通知渠道：0 全关闭，1 工作通知，2 钉邮，3 工作通知和钉邮 - --yes 用户已确认，跳过交互式确认提示 - Agent 调用时传入前必须已完成 ask_human 二次确认 + --users string 员工 ID 列表，逗号分隔，最多 50 人 (必填) + --start string 起始日期，格式 YYYY-MM-DD (必填) + --end string 结束日期，格式 YYYY-MM-DD (必填) +Notes: + - 单次查询最多 7 天、最多 50 人 ``` -调用 MCP 工具 save_self_setting 更新保存个人规则设置，请求体封装在 `RuleMcpSaveSelfSettingRequest` 中。`settingScene` 必填；MCP 入参 `userId` 必填，CLI 的 `--user` 也必填，必须显式传入目标用户 ID。认证信息 `corpId` 和 `opUserId` 由当前登录上下文自动注入，无需手动传入。 - -`selfsetting save` 必须按 `--setting-scene` 传入对应场景的字段，且至少一个字段有值： -- `checkRemind`: `checkRemindSetting`、`checkRemindUserOnDuty`、`checkRemindUserOffDuty`、`enableOndutyCheckRemindOfPc`、`enableOffdutyCheckRemindOfPc` -- `fastCheck`: `ondutyCheckType`、`offdutyCheckType`、`ondutyRemindStartMin`、`ondutyRemindEndMin`、`offdutyRemindStartMin`、`offdutyRemindEndMin`、`fastCheckLateNeedConfirm`、`canUpdateOffDuty`、`voiceRemindSwitch`、`vibrationRemindSwitch` -- `checkResultNotify`: `checkResultMsg` -- `lackRemind`: `lackSendTodoMsg`、`lackRemindUser` -- `personalAttendStatNotify`: `personDailyReportSwitch`、`personWeekReportType`、`personMonthReportType` -- `bossAttendStatNotify`: `bossPushStartMin`、`bossWeekReportType`、`bossMonthReportType` - -返回 `ServiceResult`，包含 `success`、`code`、`message`、`result`。其中 `result` 为 boolean，表示保存是否成功。 - -#### 强制执行流程：Agent 调用 `selfsetting save` - -`selfsetting save` 是写操作，会修改用户个人规则设置。Agent 调用时 **必须按以下流程执行**，**禁止**在未确认的情况下直接提交： - -1. **识别写操作**：用户表达“更新个人规则设置 / 保存打卡提醒 / 修改极速打卡 / 关闭缺卡提醒 / 开启打卡结果通知 / 设置个人考勤统计通知 / 设置团队考勤统计通知”等意图时，命中 `selfsetting save`。 -2. **收集必要参数**：必须明确 `--user`、`--setting-scene`，以及对应场景下将要修改的字段和值。 -3. **前置查询当前设置**：执行 `dws attendance selfsetting get --setting-scene --user --format json`，获取当前配置，用于确认目标用户和当前值。 -4. **展示待写入数据并等待确认**：向用户展示目标用户、设置场景、要更新的字段、当前值、新值和最终命令参数摘要。必须调用 `ask_human` 或返回待确认状态，并等待用户明确确认。 -5. **用户确认后再执行保存**：**只有用户明确确认后**，才可以追加全局 `--yes` 执行 `dws attendance selfsetting save ... --yes --format json`。 - -确认话术示例： - -```text -即将更新个人考勤规则设置，请确认： -- 用户 ID： -- 设置场景：checkResultNotify -- 修改内容： - - 打卡结果通知(checkResultMsg)：关闭 → 开启 - -是否确认执行更新？ -``` - -禁止在未获得用户明确确认前执行保存；禁止为了推进流程自动添加全局 `--yes`。即使用户在最初需求中表达“直接改/不用问”，Agent 也必须先通过 `ask_human` 或待确认状态展示完整参数摘要并获得明确确认后，才允许追加 `--yes` 执行。 - -### 查询全局规则设置（仅管理员） +### 查询某个人的考勤统计摘要 ``` Usage: - dws attendance globalsetting get [flags] + dws attendance summary [flags] Example: - dws attendance globalsetting get --scope 企业 --setting-scene checkRemind --format json - dws attendance globalsetting get --scope 全公司 --setting-scene bossAttendStatNotify --format json + dws attendance summary --user USER_ID --date "2026-03-12 15:00:00" --stats-type month + dws attendance summary --user USER_ID --date "2026-03-12 15:00:00" --stats-type week Flags: - --setting-scene string 查询设置项: checkRemind/fastCheck/checkResultNotify/lackRemind/personalAttendStatNotify/bossAttendStatNotify (必填) - --scope string 全局范围确认，必须明确输入：企业/全公司/所有人（必填） + --user string 钉钉用户 ID (必填) + --date string 工作日期，格式 yyyy-MM-dd HH:mm:ss (必填) + --stats-type string 统计类型：week（周统计）或 month（月统计）(必填) +Notes: + - --stats-type 必填，不填会返回 C0002 统计类型错误（钉钉服务端业务层强制要求） ``` -调用 MCP 工具 `query_global_setting` 查询全局规则设置，请求体封装在 `RuleMcpQueryGlobalSettingRequest` 中。`settingScene` 必填；CLI 必须通过 `--scope` 明确输入 `企业`、`全公司` 或 `所有人`，用于确认查询的是全局范围。认证信息 `corpId` 和 `opUserId` 由当前登录上下文自动注入，无需手动传入。该接口仅管理员可以调用。 - -返回 `ServiceResult`，包含 `success`、`code`、`message`、`result`。`result` 常见字段包括： -- `checkRemindCorp`: 打卡提醒企业总开关 -- `checkRemindPcCorp`: 打卡提醒 PC 端企业总开关 -- `fastCheckCorp`: 极速打卡企业总开关 -- `enableCheckCertPush`: 打卡结果通知企业总开关 -- `lackRemindCorp`: 缺卡提醒企业总开关 -- `enablePersonalDailyReport`: 个人考勤统计通知日报企业总开关 -- `enablePersonalWeeklyReport`: 个人考勤统计通知周报企业开关，钉邮渠道 -- `enablePersonalWeeklyReportCard`: 个人考勤统计通知周报企业开关，工作通知渠道 -- `enablePersonalMonthlyReport`: 个人考勤统计通知月报企业总开关 -- `bossDailyReportType`: 团队考勤统计通知日报发送渠道类型，0 全关闭，1 开启 -- `bossWeeklyReportType`: 团队考勤统计通知周报发送渠道类型，0 全关闭，1 工作通知，2 钉邮，3 工作通知和钉邮 -- `bossMonthlyReportType`: 团队考勤统计通知月报发送渠道类型，0 全关闭，1 工作通知，2 钉邮，3 工作通知和钉邮 - -### 更新保存全局规则设置（写场景接口，仅管理员，必须走二次确认流程） -**强制执行流程**：此命令为写操作，Agent 调用时必须先向用户展示待执行操作的完整参数摘要，等待用户明确确认后，才能追加 `--yes` 执行。 - -``` -Usage: - dws attendance globalsetting save [flags] -Example: - dws attendance globalsetting save --scope 企业 --setting-scene checkRemind --check-remind-corp=true --yes --format json - dws attendance globalsetting save --scope 全公司 --setting-scene fastCheck --fast-check-corp=false --yes --format json - dws attendance globalsetting save --scope 所有人 --setting-scene bossAttendStatNotify --boss-daily-report-type 1 --boss-weekly-report-type 3 --yes --format json -Flags: - --setting-scene string 更新设置项: checkRemind/fastCheck/checkResultNotify/lackRemind/personalAttendStatNotify/bossAttendStatNotify (必填) - --scope string 全局范围确认，必须明确输入：企业/全公司/所有人（必填） - --check-remind-corp 打卡提醒企业总开关 - --check-remind-pc-corp 打卡提醒 PC 端弹窗企业总开关 - --fast-check-corp 极速打卡企业总开关 - --enable-check-cert-push 打卡结果通知企业总开关 - --lack-remind-corp 缺卡提醒企业总开关 - --enable-personal-daily-report 个人考勤统计通知日报企业总开关 - --enable-personal-weekly-report 个人考勤统计通知周报企业开关，钉邮渠道 - --enable-personal-weekly-report-card 个人考勤统计通知周报企业开关，工作通知渠道 - --enable-personal-monthly-report 个人考勤统计通知月报企业总开关 - --boss-daily-report-type int 团队考勤统计通知日报发送渠道类型：0 全关闭，1 开启 - --boss-weekly-report-type int 团队考勤统计通知周报发送渠道类型：0 全关闭，1 工作通知，2 钉邮，3 工作通知和钉邮 - --boss-monthly-report-type int 团队考勤统计通知月报发送渠道类型：0 全关闭，1 工作通知，2 钉邮，3 工作通知和钉邮 - --yes 用户已确认，跳过交互式确认提示 -``` - -调用 MCP 工具 `save_global_setting` 更新保存全局规则设置，请求体封装在 `RuleMcpSaveGlobalSettingRequest` 中。`settingScene` 必填；CLI 必须通过 `--scope` 明确输入 `企业`、`全公司` 或 `所有人`，用于确认更新的是全局范围。认证信息 `corpId` 和 `opUserId` 由当前登录上下文自动注入，无需手动传入。该接口仅管理员可以调用。 - -`globalsetting save` 必须按 `--setting-scene` 传入对应场景的字段，且至少一个字段有值： -- `checkRemind`: `checkRemindCorp`、`checkRemindPcCorp` -- `fastCheck`: `fastCheckCorp` -- `checkResultNotify`: `enableCheckCertPush` -- `lackRemind`: `lackRemindCorp` -- `personalAttendStatNotify`: `enablePersonalDailyReport`、`enablePersonalWeeklyReport`、`enablePersonalWeeklyReportCard`、`enablePersonalMonthlyReport` -- `bossAttendStatNotify`: `bossDailyReportType`、`bossWeeklyReportType`、`bossMonthlyReportType` - -返回 `ServiceResult`，其中 `result` 为 boolean，表示保存是否成功。 - -### 获取企业考勤字段列表（仅管理员） -``` -Usage: - dws attendance report columns -Example: - dws attendance report columns -``` - -根据操作者的列权限，过滤并返回其有权查看的考勤字段列表。操作者必须是管理员，否则返回权限错误。 - -### 根据字段查询考勤数据（仅管理员） -``` -Usage: - dws attendance report query-data [flags] -Example: - dws attendance report query-data \ - --users userId1,userId2 --columns 1001,1002 --start "2026-03-01 00:00:00" --end "2026-03-31 23:59:59" -Flags: - --columns string 字段 ID 列表, 逗号分隔, 可通过 report columns 获取（必填） - --end string 结束日期, 格式 yyyy-MM-dd HH:mm:ss（必填） - --start string 开始日期, 格式 yyyy-MM-dd HH:mm:ss（必填） - --users string 目标用户 ID 列表, 逗号分隔, 最多 20 人（必填） -``` - -根据字段查询考勤数据，含列权限过滤和用户查看权限校验。--users 最多 20 人，--start 到 --end 不超过 32 天。 - -### 查询用户假期数据（仅管理员） -``` -Usage: - dws attendance report query-leave [flags] -Example: - dws attendance report query-leave \ - --users userId1,userId2 --leave-names 年假,病假 --start "2026-03-01 00:00:00" --end "2026-03-31 23:59:59" -Flags: - --end string 结束日期, 格式 yyyy-MM-dd HH:mm:ss（必填） - --leave-names string 假期类型名称列表, 逗号分隔, 不填则查询所有假期类型（选填） - --start string 开始日期, 格式 yyyy-MM-dd HH:mm:ss（必填） - --users string 目标用户 ID 列表, 逗号分隔, 最多 20 人（必填） -``` - -查询用户假期数据，含用户查看权限校验。--users 最多 20 人，--start 到 --end 不超过 32 天。 - -### 查询当前用户假期规则列表 -``` -Usage: - dws attendance vacation types -Example: - dws attendance vacation types -Flags: - 无 -``` - -调用 MCP 工具 get_leave_types 查询当前用户可用的假期规则列表。例如：年假、事假、病假等假期类型及对应规则。请求体封装在 McpLeaveTypeRequest 中，认证信息（corpId、opUserId）由系统自动注入，无需手动传入。 - -### 查询指定员工假期余额 -``` -Usage: - dws attendance vacation balance [flags] -Example: - dws attendance vacation balance --users userId1,userId2 --leave-code a1b2c3d4-e5f6-7890-abcd-ef1234567890 -Flags: - --users string 目标员工 ID 列表, 逗号分隔 (必填) - --leave-code string 假期规则 code (选填，不传则查询所有假期规则余额) -``` - -调用 MCP 工具 get_leave_balance_quota 查询指定员工的假期余额。例如：查询某员工年假还剩多少、病假额度等。`--leave-code` 可通过 `vacation types` 获取；不传 `--leave-code` 时查询所有假期规则余额。认证信息（corpId、opUserId）由系统自动注入。 - -如用户需要“所有假期规则余额 / 导出假期余额列表 / 所有假期规则余额 Excel / 按截图样式导出假期余额”，必须先读取 [attendance-vacation.md](./attendance-vacation.md)，再按其中工作流调用脚本生成 Excel。 - -### 查询指定员工假期余额变更记录 -``` -Usage: - dws attendance vacation records [flags] -Example: - dws attendance vacation records --user USER_ID --leave-code a1b2c3d4-e5f6-7890-abcd-ef1234567890 --start 2026-04-01 --end 2026-04-22 -Flags: - --user string 指定查询员工 ID (必填) - --leave-code string 假期规则 code (必填, 不传则无法查询) - --start string 查询开始日期, 格式 YYYY-MM-DD (必填) - --end string 查询结束日期, 格式 YYYY-MM-DD (必填) -``` - -调用 MCP 工具 get_leave_balance_records 查询指定员工的假期余额变更记录。例如：查询某员工年假变更历史、请假扣减记录等。`--leave-code` 可通过 `vacation types` 获取。认证信息（corpId、opUserId）由系统自动注入。 - -### 更新假期规则（写场景接口，必须走二次确认流程） - -**强制执行流程**：此命令为写操作，Agent 调用时必须遵守以下流程： -1. 先向用户展示待执行操作的完整参数摘要 -2. 使用 `ask_human` 或返回待确认状态，等待用户明确确认 -3. 用户确认后，再传 `--user-say-yes=true` 执行命令 - -**禁止未经用户确认直接执行或自动添加 `--user-say-yes=true`。** - -``` -Usage: - dws attendance vacation update-type [flags] -Example: - # 更新假期规则名称 - dws attendance vacation update-type --leave-code a1b2c3d4-e5f6-7890-abcd-ef1234567890 --name "事假（修改版）" - - # 更新假期单位 - dws attendance vacation update-type --leave-code a1b2c3d4-e5f6-7890-abcd-ef1234567890 --unit hour --per-hours 8 - - # 更新适用范围 - dws attendance vacation update-type --leave-code a1b2c3d4-e5f6-7890-abcd-ef1234567890 --visibility-rules '[{"type":"dept","visible":["1","2","3"]}]' -Flags: - --leave-code string 假期编码（必填） - --name string 假期名称（可选） - --unit string 假期单位：day/halfDay/hour（可选） - --paid bool 是否带薪假期（可选，默认 false） - --per-hours int 一天折算小时数（可选） - --when-can-leave string 新员工请假规则：entry/formal（可选） - --visibility-rules string 适用范围规则 JSON 数组（可选） - --user-say-yes 用户已确认，跳过交互式确认提示 - Agent 调用时传 true 前必须完成用户二次确认 -``` - -调用 MCP 工具 save_leave_type 更新已有假期规则。`--leave-code` 必填，指定要更新的假期规则编码。其他字段均为可选，仅需传入要修改的字段。除 `--leave-code` 外，必须至少传入一个更新字段。 - -#### 强制执行流程：Agent 调用 `vacation update-type` - -`vacation update-type` 是写操作，会修改假期规则配置。Agent 调用时 **必须按以下流程执行**，**禁止**在未确认的情况下直接提交： - -1. **识别写操作**：用户表达"更新假期规则 / 修改假期类型 / 编辑假期规则"等意图时，命中 `vacation update-type`。 -2. **收集必要参数**：必须明确 `--leave-code`，以及至少一个更新字段（`--name`、`--unit`、`--paid`、`--per-hours`、`--when-can-leave`、`--visibility-rules`）。 -3. **前置查询当前规则**：需先调用 `vacation types` 确认该规则是否存在及当前配置。 -4. **展示待写入数据并等待确认**：向用户展示假期编码、要更新的字段及新值，并询问是否确认执行。**必须等待用户明确确认**。 -5. **用户确认后再执行保存**：**只有用户明确确认后**，才可以传 `--user-say-yes=true` 执行 `dws attendance vacation update-type ... --format json`。 - -确认话术示例： - -```text -即将更新假期规则，请确认： -- 假期编码：a1b2c3d4-e5f6-7890-abcd-ef1234567890 -- 更新内容： - - 名称：事假 → 事假（修改版） - -是否确认执行更新？ -``` - -如用户明确要求跳过确认，可传 `--user-say-yes=true`；否则默认必须等待确认。 - -#### 强制执行流程：Agent 调用 `vacation save-balance` - -`vacation save-balance` 是写操作，会直接替换员工的假期余额（SET 接口，而非 ADD）。Agent 调用时 **必须按以下流程执行**，**禁止**在未确认的情况下直接提交： - -1. **识别写操作**：用户表达"设置假期余额 / 调整假期额度 / 更新假期余额 / 增加假期余额 / 发放年假 / 给员工加年假"等意图时，命中 `vacation save-balance`。 -2. **前置查询当前余额**：必须先调用 `vacation balance --users --leave-code ` 获取当前余额，因为这是 SET 接口，传入值会直接替换而非累加。 -3. **收集必要参数**：必须明确 `--target`（目标员工）、`--leave-code`（假期编码）、`--num`（新余额数量）、`--reason`（变更原因），以及可选参数 `--start/--end`（有效期）。 -4. **计算变更并展示确认**：向用户展示目标员工、假期类型、当前余额、新余额、差额（增加或减少）、变更原因、有效期等，并询问是否确认执行。**必须等待用户明确确认**。 -5. **用户确认后再执行保存**：**只有用户明确确认后**，才可以传 `--user-say-yes=true` 执行 `dws attendance vacation save-balance ... --format json`。 - -确认话术示例： - -**设置余额场景**： -```text -即将设置员工假期余额，请确认： -- 目标员工：张三（user001） -- 假期类型：年假（leaveCode: a1b2c3d4-e5f6-7890-abcd-ef1234567890） -- 当前余额：5 天 -- 新余额：8 天 -- 变更差额：+3 天（增加） -- 变更原因：年度发放 -- 有效期：2024-01-01 至 2024-12-31 - -是否确认执行设置？ -``` - -**减少余额场景**： -```text -即将设置员工假期余额，请确认： -- 目标员工：李四（user002） -- 假期类型：年假（leaveCode: a1b2c3d4-e5f6-7890-abcd-ef1234567890） -- 当前余额：10 天 -- 新余额：2 天 -- 变更差额：-8 天（减少） -- 变更原因：请假扣减 - -注意：此操作将大幅减少余额，请确认是否继续？ - -是否确认执行设置？ -``` - -如用户明确要求跳过确认，可传 `--user-say-yes=true`；否则默认必须等待确认。 - -### 设置员工假期余额 -``` -Usage: - dws attendance vacation save-balance [flags] -Example: - # 设置员工年假余额为8天 - dws attendance vacation save-balance --target user001 \ - --leave-code a1b2c3d4-e5f6-7890-abcd-ef1234567890 --num 8 --reason "年度发放" - - # 设置带有效期的假期余额 - dws attendance vacation save-balance --target user001 \ - --leave-code a1b2c3d4-e5f6-7890-abcd-ef1234567890 --num 8 --reason "年度发放" \ - --start 2024-01-01 --end 2024-12-31 -Flags: - --target string 目标员工工号（必填） - --leave-code string 假期编码（必填） - --num string 余额数量，如8天传8，7.5天传7.5（必填） - --reason string 变更原因，最长100字符（必填） - --start string 有效期开始日期 YYYY-MM-DD（可选） - --end string 有效期结束日期 YYYY-MM-DD（可选） - --user-say-yes 用户已确认，跳过交互式确认提示 - Agent 调用时传 true 前必须完成用户二次确认 -``` - -**重要：这是设置（SET）接口，传入的值会替换当前余额，而非增加（ADD）。**余额数量在传递给 MCP 时会自动乘以 100（如 8 天传 800）。执行前会展示待写入数据，需用户确认后提交。 - -### 查询指定员工的签到记录 -``` -Usage: - dws attendance checkin records [flags] -Example: - dws attendance checkin records \ - --operator-staff-id op001 --staff-ids user001,user002 --start "2026-04-01 00:00:00" --end "2026-04-07 00:00:00" -Flags: - --end string 结束时间, 格式 yyyy-MM-dd HH:mm:ss（必填） - --operator-corp-id string 操作者企业 ID（必填） - --operator-staff-id string 操作者员userID（必填） - --staff-ids string 目标员工userID 列表, 逗号分隔（必填），员工数最多100个人 - --start string 开始时间, 格式 yyyy-MM-dd HH:mm:ss（必填），开始到结束时间限制在7天 -``` - -调用 MCP 工具 get_checkin_record 查询指定员工在一段时间内的签到记录。权限说明：Boss/超级管理员可查看全公司员工，子管理员可查看管理范围内员工，部门主管可查看所管理部门员工，普通员工只能查询自己。接口单次最多返回100条签到记录。 - ## 意图判断 -用户说"打卡记录/出勤/考勤" → `check record` -用户说"指定用户打卡结果/考勤结果/迟到早退/缺卡异常" → `check result` -用户说"指定用户打卡流水/打卡详情/打卡时间地点/打卡记录详情" → `check record` -用户说"审批单/请假记录/加班记录/出差记录/补卡记录" → `approve list` -用户说"查询排班记录/获取排班详情/查看排班/排班表/导出排班/导出排班表/排班导出/XX考勤组的排班" → **必须先 `read_file` 读取 [attendance-schedule.md](./attendance-schedule.md) 后按其中的「排班查询导出工作流」执行**。 - - **优先级**：只要用户句中含"排班"二字且意图是查看/导出，就走本条，不要走 `attendance-report.md`。"导出排班表" ≠ "导出考勤报表" - - **严禁**绕过 `attendance-schedule.md` 直接调用 `dws attendance schedule get` 命令 - - 脚本自动处理：分批查询（超 20 人自动分批）、userId→姓名转换、classId→班次名称转换、排班表格式 Excel 输出 -用户说"排班/导入排班/安排排班/设置排班/安排班次/调班/换班/排休" → **必须先 `read_file` 读取 [attendance-schedule.md](./attendance-schedule.md) 后按其中的「排班导入工作流」执行**。 - - **严禁**绕过 `attendance-schedule.md` 直接调用 `dws attendance schedule import` 命令 - - **严禁**仅凭命令 `--help` 或本文件中的命令参考自行组装排班命令 - - 该文档定义了：考勤组类型校验（必须为 TURN）、班次校验（必须属于该考勤组）、排班回显确认、错误处理等约束，缺一不可 - - 违反约束的后果：排错班次、排错人员、排班数据覆盖无法回退 -用户说"班次定义/班次列表/有哪些班次/我负责的班次" → `class search`（返回结果已包含全量属性，无需再调 get） -用户说"班次详情/某个班次的具体信息" → `class search --name "..."`（search 直出，直接返回详情）。`class get` 仅在需要按已知 classId 精确查询时使用 -用户说"更新班次/修改班次/班次改名/修改上下班时间" → `class update` -用户说"补卡规则/补卡设置" → `adjustment search`（返回结果已包含全量属性，无需再调 get） -用户说"补卡规则详情/某条补卡规则的具体信息" → `adjustment search --name "..."`（search 直出）。`adjustment get` 仅在需要按已知 adjustmentId 精确查询时使用 -用户说"加班规则/加班设置/加班计算" → `overtime search`（返回结果已包含全量属性，无需再调 get） -用户说"加班规则详情/某条加班规则的具体信息" → `overtime search --name "..."`（search 直出）。如需查已删除/被覆盖的历史记录 → `overtime get` -用户说"考勤组列表/有哪些考勤组" → `group search` -用户说"考勤组详情/全量考勤组信息" → `group get`,若返回结果中含成员 userId 列表，则对每个 userId 调用 `dws contact user get --user-ids `（或等价通讯录查询），在最终输出中展示员工姓名而非裸 userId -用户说"考勤组成员/打卡地址/打卡wifi/打卡蓝牙" → `group filtered-get`（按需查询，节省成本）,若返回结果中含成员 userId 列表，则对每个 userId 调用 `dws contact user get --user-ids `（或等价通讯录查询），在最终输出中展示员工姓名而非裸 userId -用户说"更新考勤组成员/添加考勤人员/删除考勤人员/添加考勤部门/删除考勤部门/加入考勤组/移出考勤组/设置无需考勤/取消无需考勤" → `group update-members` -用户说"修改考勤组/更新考勤组配置/考勤组改名/改变考勤组绑定的班次/修改打卡范围/设置考勤组负责人" → `group update` -用户说"创建考勤组/新建考勤组/添加考勤组" → `group create` -用户说"考勤汇总/统计" → `summary` -用户说"考勤组/考勤规则/打卡规则" → `rules` -用户说"查询个人规则设置/查看打卡提醒/查看极速打卡/查看缺卡提醒/查看打卡结果通知/查看个人考勤统计通知/查看团队考勤统计通知" → `selfsetting get` -用户说"更新个人规则设置/保存打卡提醒/修改极速打卡/关闭缺卡提醒/开启打卡结果通知/设置个人考勤统计通知/设置团队考勤统计通知" → `selfsetting save` -用户说"考勤字段/考勤列" → `report columns` -用户说"考勤数据/查询考勤报表数据" → `report query-data`（单次查询场景，非导出） - **导出考勤/导出报表/生成考勤报表/出勤汇总导出/考勤明细导出/迟到早退统计导出/全员考勤数据导出/月度考勤报表/考勤表格/考勤 Excel** → **必须先 `read_file` 读取 [attendance-report.md](./attendance-report.md) 后按其中的工作流执行**。 - - **排除**：如果用户说的是"导出**排班**表"/"导出**排班**"/"**排班**导出"，这属于**排班查询导出**，应路由到 [attendance-schedule.md](./attendance-schedule.md)，而非本条。判断标准：句中含"排班"二字 → 走排班；不含"排班"或明确说"考勤报表/考勤数据/出勤统计" → 走报表。 - - **严禁**绕过 `attendance-report.md` 直接调用 `python scripts/attendance_report_*.py` 任何脚本 - - **严禁**仅凭脚本 `--help` 或本文件"自动化脚本"表格里的脚本路径就推断参数自行组装命令 - - 该文档定义了：报表类型默认值、列选择策略（`--column-keywords`）、阶段 1 人员获取流程、错误处理、输出摘要规范，缺一不可 - - 违反约束的后果：报表数据不全、列错位、人员遗漏、用户得到错误结果 -用户说"假期数据/年假/病假/请假记录" → `report query-leave` -用户说"假期/我的假期/假期规则" → `vacation types` -用户说"病假余额/年假余额/事假剩余假期"等查询指定假期规则的余额 → `vacation balance` -用户说"导出假期余额/假期余额列表/所有假期规则余额/假期余额 Excel/年假病假调休余额导出"等全部假期规则余额的查询 → **必须先 `read_file` 读取 [attendance-vacation.md](./attendance-vacation.md) 后按其中工作流执行** -用户说"假期变更/假期记录/请假扣减" → `vacation records` -用户说"更新假期规则/修改假期类型/编辑假期规则" → `vacation update-type --leave-code ` -用户说"设置假期余额/调整假期额度/更新假期余额" → 先调用 `vacation balance` 获取当前余额，计算修改后的值，再调用 `vacation save-balance` -用户说"增加假期余额/发放年假/给员工加年假" → 先调用 `vacation balance` 获取当前余额，加上要增加的天数，再调用 `vacation save-balance` 设置新总额度 -用户说"签到/签到记录" → `checkin records` +用户说"我属于哪个考勤组/打卡范围/弹性工时/考勤规则" → `attendance rules --date <日期>` +用户说"某人某天的打卡记录/打卡详情/几点上下班" → `attendance record get --user --date <日期>` +用户说"某些人的班次/排了什么班/某段时间的班次" → `attendance shift list --users --start <开始> --end <结束>` +用户说"某人的考勤统计/本周/本月出勤/迟到早退汇总" → `attendance summary --user --date <日期> --stats-type week|month` + +关键区分： +- `record get` = 某天的逐次打卡明细（单人单日） +- `summary` = 一段时间的统计汇总（单人，周/月） +- `shift list` = 排班（谁哪天上什么班，可批量多人） +- `rules` = 考勤组与规则配置（不查打卡数据） ## 核心工作流 ```bash -# 导入排班记录 -dws attendance schedule import --group-id 123456 \ - --schedules '[{"userId":"user001","classId":123,"workDate":"2026-04-22","checkBeginTime":"09:00","checkEndTime":"18:00"}]' \ - --yes --format json - -# 获取排班记录 — 禁止直接调用，必须走 attendance-schedule.md 排班查询导出工作流 -# python scripts/attendance_schedule_export.py --users user001,user002 --start 2026-04-01 --end 2026-04-30 - -# 查询可管理的班次列表 -dws attendance class search --format json -dws attendance class search --query "早班" --filter-type MINE_OWN --format json - -# 查询班次详情 -dws attendance class get --class-id 1170996821 --format json - -# 更新班次 -dws attendance class update --class-id 1170996821 --name "新早班" --timeout 10 --format json -dws attendance class update --class-id 1170996821 --class-vo '{"sections":[{"times":[{"checkType":"OnDuty","checkTime":"08:30","across":0},{"checkType":"OffDuty","checkTime":"17:30","across":0}]}]}' --timeout 10 --format json - -# 查询补卡规则 -dws attendance adjustment search --page 1 --limit 20 --format json -dws attendance adjustment search --query "标准" --page 1 --limit 20 --format json - -# 查询补卡规则详情 -dws attendance adjustment get --adjustment-id 12345 --format json - -# 查询加班规则 -dws attendance overtime search --page 1 --limit 20 --format json - -# 查询加班规则详情 -dws attendance overtime get --overtime-id 12345 --format json - -# 查询考勤组列表 -dws attendance group search --query "研发" --page 1 --limit 20 --format json -dws attendance group search --type FIXED --page 1 --limit 20 --format json - -# 查询考勤组全量信息 -dws attendance group get --group-id 123456 --format json - -# 按需查询考勤组成员/地址/蓝牙/Wifi -dws attendance group filtered-get --group-id 123456 --member --format json -dws attendance group filtered-get --group-id 123456 --position --wifi --format json - -# 更新考勤组成员 -dws attendance group update-members --group-id 123456 --add-users userId1,userId2 --timeout 10 --format json -dws attendance group update-members --group-id 123456 --remove-users userId1 --timeout 10 --format json -dws attendance group update-members --group-id 123456 --add-depts deptId1 --remove-users userId2 --timeout 10 --format json - -# 更新考勤组配置 -dws attendance group update --group-id 123456 --name "研发考勤组" --timeout 10 --format json -dws attendance group update --group-id 123456 --classIds '[1374234767]' --timeout 10 --format json -dws attendance group update --group-id 123456 --group-vo '{"positions":[{"title":"总部","address":"北京市","latitude":39.9,"longitude":116.4,"offset":200}]}' --timeout 10 --format json - -# 创建考勤组 -dws attendance group create --name "研发考勤组" --type FIXED --group-vo '{"defaultClassId":1170996821,"workDayClassList":[0,1170996821,0,0,0,0,0]}' --timeout 10 --format json -dws attendance group create --name "自由工时分组" --type NONE --timeout 10 --format json - -# 查看考勤统计摘要 -dws attendance summary --user --date "2026-03-12 15:00:00" --format json - # 查看考勤组和规则 dws attendance rules --date 2026-03-14 --format json -# 查看指定用户的打卡提醒设置 -dws attendance selfsetting get --setting-scene checkRemind --user --format json +# 查询某人某天的打卡详情（先用 contact 拿 userId） +dws contact user search --query "张三" --format json +dws attendance record get --user --date 2026-03-08 --format json -# 查看指定用户的极速打卡设置 -dws attendance selfsetting get --setting-scene fastCheck --user --format json +# 批量查询多人班次（最多 7 天、50 人） +dws attendance shift list --users userId1,userId2 --start 2026-03-03 --end 2026-03-07 --format json -# 开启指定用户的打卡结果通知 -dws attendance selfsetting save --setting-scene checkResultNotify --user --check-result-msg 1 --format json - -# 更新指定用户的极速打卡设置 -dws attendance selfsetting save --setting-scene fastCheck --user \ - --onduty-check-type 3 --voice-remind-switch=true --format json - -# 获取考勤字段列表（管理员） -dws attendance report columns --format json - -# 根据字段查询考勤数据（管理员） -dws attendance report query-data --users userId1,userId2 \ - --columns 1001,1002 --start "2026-03-01 00:00:00" --end "2026-03-31 23:59:59" --format json - -# 查询用户假期数据（管理员） -dws attendance report query-leave --users userId1,userId2 \ - --leave-names 年假,病假 --start "2026-03-01 00:00:00" --end "2026-03-31 23:59:59" --format json - -# 查看假期规则列表 -dws attendance vacation types --format json - -# 查看指定员工假期余额 -dws attendance vacation balance --users userId1,userId2 --format json - -# 查看指定员工某类假期余额 -dws attendance vacation balance --users userId1 --leave-code a1b2c3d4-e5f6-7890-abcd-ef1234567890 --format json - -# 查看指定员工假期余额变更记录 -dws attendance vacation records --user USER_ID --start 2026-04-01 --end 2026-04-22 --format json - -# 更新假期规则名称 -dws attendance vacation update-type --leave-code a1b2c3d4-e5f6-7890-abcd-ef1234567890 \ - --name "事假（修改版）" --format json - -# 更新假期单位 -dws attendance vacation update-type --leave-code a1b2c3d4-e5f6-7890-abcd-ef1234567890 \ - --unit hour --per-hours 8 --format json - -# 更新适用范围 -dws attendance vacation update-type --leave-code a1b2c3d4-e5f6-7890-abcd-ef1234567890 \ - --visibility-rules '[{"type":"dept","visible":["1","2","3"]}]' --format json - -# 设置员工假期余额完整流程 -# 1. 查询当前余额 -dws attendance vacation balance --users user001 \ - --leave-code a1b2c3d4-e5f6-7890-abcd-ef1234567890 --format json - -# 2. 根据查询结果计算新值（如当前5天，要设置为8天） - -# 3. 执行设置（SET操作，会替换当前余额） -dws attendance vacation save-balance --target user001 \ - --leave-code a1b2c3d4-e5f6-7890-abcd-ef1234567890 \ - --num 8 --reason "年度发放" --start 2024-01-01 --end 2024-12-31 --format json - -# 增加员工假期余额完整流程（ADD场景） -# 1. 查询当前余额（假设返回5天） -dws attendance vacation balance --users user001 \ - --leave-code a1b2c3d4-e5f6-7890-abcd-ef1234567890 --format json - -# 2. 计算增加后的新值（5 + 3 = 8天） - -# 3. 设置新总额度 -dws attendance vacation save-balance --target user001 \ - --leave-code a1b2c3d4-e5f6-7890-abcd-ef1234567890 \ - --num 8 --reason "绩效奖励发放3天" --format json - -# 查询签到记录 -dws attendance checkin records --operator-staff-id op001 --staff-ids user001,user002 \ - --start "2026-04-01 00:00:00" --end "2026-04-07 00:00:00" --format json +# 查看某人本月考勤统计摘要 +dws attendance summary --user --date "2026-03-12 15:00:00" --stats-type month --format json ``` ## 上下文传递表 + | 操作 | 提取 | 用于 | |------|------|------| -| `contact user get-self` | `userId` | summary 的 --user | -| `rules` | `groupId` | schedule import 的 --group-id | -| `schedule import` | `classId` | schedule import 的 schedules 中的 classId | -| `contact user search` | `userId` | schedule import/get 的 userId | +| `contact user search/get-self` | `userId` | record get / summary 的 --user、shift list 的 --users | -| `contact user get-self` / `contact user search` | `userId` | summary 的 --user, vacation records 的 --user；selfsetting get/save 的 --user（必填） | -| 当前登录上下文 | `corpId`, `opUserId` | selfsetting get/save 自动补齐 MCP 入参, CLI 不需要传 `--corp-id` / `--op-user` | -| `vacation types` | `leaveCode` | vacation balance 的 --leave-code, vacation records 的 --leave-code | ## 注意事项 -**Agent 使用引导**： -- 执行 vacation 子命令前，**必须先调用** `dws attendance vacation --help` 查看完整子命令列表和参数说明 -- 新增命令可能不在 Agent 缓存中，直接猜测命令会失败 -- 正确流程：查看帮助 → 选择命令 → 查看命令详细参数（如 `dws attendance vacation update-type --help`）→ 执行 -- `record get` 的 `--date` 格式: YYYY-MM-DD（如 `2026-03-08`），CLI 自动转换为毫秒时间戳 -- `shift list` 查询班次信息，`--start/--end` 使用 YYYY-MM-DD 格式，间隔不超过 7 天 -- `schedule import` 导入排班记录 — 必须通过 [attendance-schedule.md](./attendance-schedule.md) 排班导入工作流执行 -- `schedule get` 查询排班记录 — 必须通过 [attendance-schedule.md](./attendance-schedule.md) 排班查询导出工作流执行（脚本自动分批、姓名转换、排班表格式导出） -- `schedule import` 是写操作，AI 调用时必须先展示导入摘要并引导用户二次确认；用户明确确认后才允许执行。用户明确要求跳过确认或命令包含全局 `--yes` 时，可跳过二次确认 -- `class search` 所有参数均为可选，不填时返回全部可管理班次（默认第 1 页，每页 20 条） -- **概念区分**：班次是员工当天打卡安排；排班是为排班制考勤组导入的排班记录；班次定义是考勤管理员创建的工作时间规则 -- `class get` 的 `--class-id` 必填，班次 ID 可从 `class search` 结果中提取 -- `class search` 返回结果已包含全量属性，无需再调用 `class get`；`class get` 仅在需要按已知 classId 精确查询时使用 -- `class update` 的 `--class-id` 必填，其余均可选，仅需对要修改的字段赋值，未传字段会自动从已有配置补充；由于保存班次耗时较久，建议加 `--timeout 10` -- `adjustment search` 返回结果已包含全量属性，无需再调用 `adjustment get`；`adjustment get` 仅在需要按已知 adjustmentId 精确查询时使用 -- `overtime search` 返回结果已包含全量属性，无需再调用 `overtime get`；`overtime get` 仅在需要按已知 overtimeId 查询时使用（包括已删除/被覆盖的历史记录） -- `adjustment search` / `overtime search` 分页字段为 `--page` 和 `--limit`，不传时自动使用默认值 1 / 20 -- `group search` 的分页字段为 `--page` 和 `--limit`，不传时自动使用默认值 1 / 20 -- `group get` 的 `--group-id` 必填，返回考勤组全量字段；如仅需成员/地址/蓝牙/Wifi，优先使用 `group filtered-get` 节省成本。**返回结果中如含成员 userId 列表，必须调用 `dws contact user get --ids ,,...`（支持逗号分隔传多个 ID），将 userId 转换为员工姓名后再输出；不得直接输出裸 userId。** -- `group update-members` 的 --group-id 必填，其余参数均可选，但至少需传一个变更项；各参数每次最多 20 个 ID；`--add-extra-users` 和 `--remove-extra-users` 操作的是"无需考勤"豁免名单，不影响考勤组主成员列表 -- `group update` 的 --group-id 必填，其余均可选，至少需指定一个修改项；仅需对要修改的字段赋値，未传字段会从已有配置自动补充；修改打卡地址/wifi/蓝牙等复杂子对象时用 `--group-vo` 传入完整 JSON；`--group-vo` 与单字段 flag 同时传入时单字段 flag 优先级更高 -- `group create` 的 `--name` 和 `--type` 必填，`--type` 必须为 FIXED/TURN/NONE 之一；type=FIXED 时 `--group-vo` 必须包含 `workDayClassList`（非空）和 `defaultClassId`（非 null）；由于保存考勤组耗时较久，建议加 `--timeout 10` -- `group filtered-get` 的 `--group-id` 必填，`--member/--position/--wifi/--bles` 均可选，默认 false。**返回结果中如含成员 userId 列表，必须调用 `dws contact user get --ids ,,...`（支持逗号分隔传多个 ID），将 userId 转换为员工姓名后再输出；不得直接输出裸 userId。** -- `summary` 的 `--date` 格式: yyyy-MM-dd HH:mm:ss（如 `2026-03-12 15:00:00`） -- `rules` 的 `--date` 支持 YYYY-MM-DD 或 yyyy-MM-dd HH:mm:ss 两种格式 -- `selfsetting get/save` 的 `--setting-scene` 必须是 `checkRemind`、`fastCheck`、`checkResultNotify`、`lackRemind`、`personalAttendStatNotify`、`bossAttendStatNotify` 之一 -- `selfsetting get/save` 的 MCP 入参 `userId` 为必填；CLI 的 `--user` 也必填，必须显式传入目标用户 ID -- `selfsetting save` 必须传入与 `--setting-scene` 对应的至少一个设置字段；不同场景的字段不能混用 -- `selfsetting save` 是敏感写操作，AI 调用时必须先执行 `selfsetting get` 查询当前值，并向用户展示目标用户、设置场景、修改字段、“当前值 → 新值”和最终命令参数摘要；必须调用 `ask_human` 或返回待确认状态等待用户明确确认；用户确认后才允许追加全局 `--yes` 执行保存。禁止未经确认直接执行或自动添加 `--yes` -- `selfsetting get/save` 不需要传 `--corp-id` / `--op-user`，`corpId` 和 `opUserId` 由当前登录上下文自动补齐 -- `report columns` 无需额外参数，corpId 和 operatorId 由系统自动传入 -- `report query-data` 和 `report query-leave` 的 `--start/--end` 格式: yyyy-MM-dd HH:mm:ss，间隔不超过 32 天，最多 20 人 -- report 系列接口仅对管理员开放 -- 用户 ID 需从 `contact user get-self` 或 `aisearch person` 获取 -- 考勤组 ID 需从 `rules` 命令返回结果中获取 -- `vacation types` 无需任何参数，认证信息自动注入 -- `vacation balance` 的 `--users` 为目标员工 ID 列表，逗号分隔；`--leave-code` 选填，可通过 `vacation types` 获取 -- `vacation records` 的 `--start/--end` 使用 YYYY-MM-DD 格式，CLI 自动转换为毫秒时间戳；`--leave-code` 选填 -- `vacation balance` 和 `vacation records` 的认证参数（corpId、opUserId）由系统自动注入，无需手动传入 -- `vacation update-type` 的 `--leave-code` 必填；其他字段均为可选，但至少需传一个更新字段 -- `vacation update-type` 的 `--visibility-rules` 为 JSON 数组字符串，格式：`[{"type":"dept","visible":["1","2","3"]}]`，type 可取值 staff/label/dept -- `vacation save-balance` 是 **SET 接口**而非 ADD 接口：传入值会直接替换当前余额，而非累加 -- `vacation save-balance` 的 `--num` 输入为实际天数（如 8 或 7.5），内部会乘以 100 传给 MCP（如 800 或 750） -- `vacation save-balance` 执行前需先调用 `vacation balance` 查询当前余额，再计算新值，避免误操作 -- `vacation save-balance` 的 `--start/--end` 使用 YYYY-MM-DD 格式，CLI 自动转换为毫秒时间戳 -- `vacation update-type` 和 `vacation save-balance` 执行前会展示待写入数据，需用户输入 yes/y 确认后提交 -- 假期编码为 UUID 格式字符串，可通过 `vacation types` 命令查询获取 - -### 改签打卡记录 - -**命令**: `dws attendance boss-check` - -**功能**: 改签打卡记录，管理员可修改员工的打卡时间、打卡结果等信息。 - -**强制执行流程**: 此命令为写操作，Agent 调用时必须遵守以下流程： -1. 先向用户展示待执行操作的完整参数摘要 -2. 使用 `ask_human` 或返回待确认状态，等待用户明确确认 -3. 用户确认后，再传 `--user-say-yes=true` 执行命令 -4. **禁止**未经用户确认直接执行或自动添加 `--user-say-yes=true` - -**参数**: -| 参数 | 必填 | 说明 | 来源 | -|------|------|------|------| -| --plan-id | y* | 排班ID（与 --result-id 二选一） | `dws attendance schedule get` 返回的 `id` 字段 | -| --result-id | y* | 打卡结果ID（与 --plan-id 二选一，优先使用） | **暂不支持**（record get 未返回此字段） | -| --time | n | 新打卡时间，格式 yyyy-MM-dd HH:mm | - | -| --result | n | 打卡结果枚举值 | - | -| --absent-min | n | 缺勤时长（分钟） | - | -| --remark | n | 备注，最长500字符 | - | -| --user-say-yes | n | 用户已确认，跳过交互式确认提示 | - | - -**获取 planId 步骤**: -1. 查询排班记录：`dws attendance schedule get --userIdList USER_ID --workDateBegin DATE --workDateEnd DATE` -2. 从返回结果中找到对应打卡类型（OnDuty=上班，OffDuty=下班）的记录 -3. 使用该记录的 `id` 字段作为 `--plan-id` 参数 -4. 示例返回：`{"id": 948964045503, "checkType": "OffDuty", ...}` → `--plan-id 948964045503` - -**打卡结果枚举值**: -- Normal: 正常 -- TimesResultA: 迟到 -- TimesResultB: 早退 -- TimesResultC: 缺卡 -- TimesResultD: 迟到+早退 -- TimesResultE: 缺卡+早退 -- TimesResultF: 迟到+缺卡 - -**示例**: -```bash -# 步骤1：获取排班记录的 planId -dws attendance schedule get --userIdList 03642229451220076 --workDateBegin 2026-05-13 --workDateEnd 2026-05-13 -f json - -# 步骤2：使用返回的 id 作为 --plan-id 改签 -# 假设返回 id: 948964045503 (OffDuty 下班打卡) -dws attendance boss-check --plan-id 948964045503 --result Normal --user-say-yes - -# 同时修改打卡时间 -dws attendance boss-check --plan-id 948964045503 --time "2026-05-13 18:00" --result Normal --yes -``` - -## 自动化脚本 - -| 脚本 | 场景 | 用法 | -|------|------|------| -| [attendance_my_record.py](../../scripts/attendance_my_record.py) | 查看我今天/指定日期的考勤记录 | `python attendance_my_record.py today` | -| [attendance_team_shift.py](../../scripts/attendance_team_shift.py) | 查询团队成员本周排班 | `python attendance_team_shift.py --users userId1,userId2` | -| [attendance_report_common.py](../../scripts/attendance_report_common.py) | 考勤报表导出公共模块（不可单独执行） | — | -| [attendance_vacation_balance.py](../../scripts/attendance_vacation_balance.py) | 假期余额列表 Excel 导出 | **禁止直接调用**，必须先读 [attendance-vacation.md](./attendance-vacation.md) 按工作流执行 | -| attendance_report_detail.py | 考勤报表 — **明细粒度** | **禁止直接调用**，必须先读 [attendance-report.md](./attendance-report.md) 按工作流执行 | -| attendance_report_monthly.py | 考勤报表 — **月度汇总** | **禁止直接调用**，必须先读 [attendance-report.md](./attendance-report.md) 按工作流执行 | -| attendance_report_daily.py | 考勤报表 — **每日统计** | **禁止直接调用**，必须先读 [attendance-report.md](./attendance-report.md) 按工作流执行 | -| attendance_schedule_import.py | 排班导入（含校验、回显、执行） | **禁止直接调用**，必须先读 [attendance-schedule.md](./attendance-schedule.md) 按工作流执行 | -| attendance_schedule_export.py | 排班查询导出（分批查询、排班表 Excel） | **禁止直接调用**，必须先读 [attendance-schedule.md](./attendance-schedule.md) 按工作流执行 | - -> 说明： -> - `attendance_report_*.py` 三个脚本由 [attendance-report.md](./attendance-report.md) 工作流编排使用，自动处理 `--users` 超过 20 人分批、`--start/--end` 超过 32 天按月切片，输出 `attendance_report___<粒度>.xlsx` -> - `attendance_schedule_import.py` 由 [attendance-schedule.md](./attendance-schedule.md) 排班导入工作流编排使用，自动处理考勤组校验、班次校验、排班回显确认 -> - `attendance_schedule_export.py` 由 [attendance-schedule.md](./attendance-schedule.md) 排班查询导出工作流编排使用，自动处理分批查询（超 20 人自动分批）、userId→姓名转换、classId→班次名称转换、输出排班表格式 Excel - -## 严格约束 -- 不要凭历史记忆复用 userId / classId / leaveCode / groupId / instanceId 等任何 ID，每次必须从当次命令返回值中提取 -- 不要猜测命令，先查询明确命令，不要使用记忆中未经证实（即不存在于本.md文件中的指令）或执行失败（指令传参有误或flag不正确）的的命令 -- 制定 plan 并自我审查，严格按 plan 执行 -- 涉及超过 3 条记录的聚合（求和、分组、计数、排序、跨字段计算）时必须落 Python 脚本处理，禁止用大模型口算或目测。脚本里如果用到 mcp，先提前看下 mcp 返回的结构，避免执行异常 -- 遇到时长字段时，注意区分单位是秒、分钟还是小时 -- 遇到意图不清晰的场景不要猜测，主动询问用户明确意图 -- 如果查询结果很多时，不要自作主张省略，必须明确告知用户或者用表格或展示所有。 \ No newline at end of file +- `--user` / `--users` 需要 userId，可先用 `contact user search`、`contact user get-self` 或 `aisearch person` 获取 +- `shift list` 单次最多 7 天、50 人，跨度更大需分批 +- `summary` 的 `--stats-type` 必填（week / month），缺省会被钉钉服务端拒绝 +- 认证信息（corpId、optUserId）由系统自动注入，无需手动传入 diff --git a/skills/mono/references/products/calendar.md b/skills/mono/references/products/calendar.md index 241868b5..3e0f6950 100644 --- a/skills/mono/references/products/calendar.md +++ b/skills/mono/references/products/calendar.md @@ -101,8 +101,6 @@ Flags: **默认行为**：不传 `--start` / `--end` 时，默认返回今天的日程（00:00:00 ~ 23:59:59）。 **权限**：查询共享日历下的日程时，至少要有reader权限。 -补充：当前用户的个人日程也可用 `dws calendar event list-mine` 查询，参数与 `event list` 一致。 - ### 获取日程详情 ``` Usage: @@ -219,12 +217,13 @@ Flags: Usage: dws calendar attendee add [flags] Example: - dws calendar attendee add --event --attendees , - dws calendar attendee add --event --attendees --optional + dws calendar attendee add --event --users , + dws calendar attendee add --event --users --optional true Flags: - --event string 日程 ID (必填) - --attendees string 参会人 userId 列表，逗号分隔 (必填，最多500人) - --optional 参会人可选 (默认必选参会人) + --event string 日程 eventId (必填) + --users string 参会人 userId 列表，逗号分隔 (必填) + --optional string 是否可选参会人 (可选) + --calendar-id string 日历 ID (可选) ``` ### 移除参会人 @@ -235,10 +234,11 @@ Flags: Usage: dws calendar attendee delete [flags] Example: - dws calendar attendee delete --event --attendees --yes + dws calendar attendee delete --event --users --yes Flags: - --event string 日程 ID (必填) - --attendees string 参会人 userId 列表，逗号分隔 (必填) + --event string 日程 eventId (必填) + --users string 参会人 userId 列表，逗号分隔 (必填) + --calendar-id string 日历 ID (可选) ``` ### 搜索会议室 @@ -317,10 +317,10 @@ Usage: dws calendar room list-groups [flags] Example: dws calendar room list-groups - dws calendar room list-groups --limit 20 --page 0 + dws calendar room list-groups --page-size 20 --page-index 0 Flags: - --limit string 页大小 (可选，不填默认 100，超过 100 按 100 处理) - --page string 分页起始位置 (可选，不填默认 0) + --page-size string 页大小 (可选，默认 100，上限 100) + --page-index string 分页起始位置 (可选，默认 0) ``` ### 添加日程附件 @@ -419,8 +419,8 @@ Flags: 用户说"参会人/与会者": - 查看 → `attendee list` -- 邀请/添加 → `attendee add --attendees `（可选参会人加 `--optional`） -- 移除 → `attendee delete --attendees ` +- 邀请/添加 → `attendee add --users `（可选参会人加 `--optional true`） +- 移除 → `attendee delete --users ` 用户说"会议室/订会议室": - 哪个空闲 → `room search` @@ -479,7 +479,7 @@ dws calendar event create --title "Q1 复盘会" \ --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15:00:00+08:00" --format json # Step 2: 添加参会人（必须用 Step 1 返回的 eventId） -dws calendar attendee add --event --attendees userId1,userId2 --format json +dws calendar attendee add --event --users userId1,userId2 --format json # Step 3: 搜索空闲会议室 dws calendar room search --start ... --end ... --format json @@ -519,19 +519,19 @@ dws calendar event list --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15 - 时间格式: `event create/update`、`event list`、`busy search` 和 `event suggest` 用 ISO-8601 - 时区: `event create/update` 和 `event suggest` 支持 `--timezone` 指定 IANA 时区（如 `Asia/Shanghai`、`America/New_York`），不传默认 `Asia/Shanghai` -- 创建日程时可通过 `--attendees` 直接指定参会人（最多500人），也可创建后用 `attendee add --attendees ...` 单独添加 -- `--attendees` 和 `--open-dingtalk-ids` 至少传一个（如果需要指定参会人） -- 添加参会人时可通过 `--optional` 设为可选参会人（默认必选） +- 创建日程时可通过 `--attendees` 直接指定参会人（最多500人），也可创建后用 `attendee add --users ...` 单独添加 +- `event create` 的 `--attendees` 和 `--open-dingtalk-ids` 至少传一个（如果需要指定参会人） +- `attendee add` 可通过 `--optional true` 设为可选参会人（默认必选） - `event suggest` 根据参会人闲忙自动推荐合适时间，适合会议时间未确定时使用 - 创建日程**支持**通过 `--rooms` 一步预定会议室（`event create --rooms roomId1,roomId2`）；若创建后再加，仍可用 `room add` - `room search` 不带 `--group-id` 时查根目录；企业会议室超过 100 条会报错，此时需先 `room list-groups` 获取分组，再按分组逐一查询 -- `room list-groups` 支持 `--limit` / `--page` 分页（schema 类型为字符串） +- `room list-groups` 支持 `--page-size` / `--page-index` 分页（schema 类型为字符串） - **`event create --rooms` / `room add --rooms` 的唯一合法来源**：最近一次（同一会话、同一时段窗口）`room search` 返回体中的 `roomId`；禁止把用户自然语言会议室名当 `roomId` 传入（否则会 `roomId invalid` 等错误） - **搜房无结果**：在符合早停/用户限定范围内，`room search`（含按分组逐组查）全部返回空或无空闲 → 应**直接向用户报错/说明失败**并结束订房；**禁止**假设 roomId、禁止无合法 `roomId` 时调用 `room add` / `event create --rooms` 试探、禁止用 `event get` 等绕路推断 roomId - **评测 / 自动化断言**：凡涉及 `room add` / `event create --rooms` 的流程，`--rooms` 只能填上游 `room search`（或等价接口）返回 JSON 中的 **`rooms[].roomId`**；不得以会议室展示名、楼层文案或用户口语当作 `roomId` - **附件**：`attachment add` 仅负责挂载，**不上传**文件；fileId 必须先通过钉盘流程取得；`--files` 多附件用 `:` 元素逗号分隔 - **日历本**：`book list` 返回的 `id` 才是合法 `calendarId`；如无明确说明，`event list` / `event get` 都不要带 `--calendar-id`，让接口默认走 primary 主日历 -- **已弃用入参**：`--max-results`（event list / list-mine）在新 MCP schema 中被移除；CLI 仍接受但**不会**透传到 MCP；模型生成命令时**禁止**继续使用 +- **已弃用入参**：`--max-results`（event list）在新 MCP schema 中被移除；CLI 仍接受但**不会**透传到 MCP；模型生成命令时**禁止**继续使用 ## 自动化脚本 @@ -544,4 +544,4 @@ dws calendar event list --start "2026-03-10T14:00:00+08:00" --end "2026-03-10T15 ## 相关产品 - [conference](./simple.md) — 仅视频会议预约（返回入会链接），不含参会人/会议室管理 -- [contact](./contact.md) — 搜索同事 userId，用于 attendee add --attendees +- [contact](./contact.md) — 搜索同事 userId，用于 attendee add --users diff --git a/skills/mono/references/products/chat.md b/skills/mono/references/products/chat.md index b52ed1d5..e3c491d7 100644 --- a/skills/mono/references/products/chat.md +++ b/skills/mono/references/products/chat.md @@ -18,9 +18,9 @@ Flags: #### 查看群成员列表 — 分页查询指定群聊的成员 ``` Usage: - dws chat group members [flags] + dws chat group members list [flags] Example: - dws chat group members --id + dws chat group members list --id Flags: --cursor string 分页游标，首次从 0 开始 --id string 群 ID / openconversation_id (必填) @@ -100,13 +100,11 @@ Usage: dws chat group transfer-owner [flags] Example: dws chat group transfer-owner --group --new-owner - dws chat group transfer-owner --group --user # 查询群 ID: dws chat search --query "群名" # 查询人员: dws aisearch person --keyword "姓名" --dimension name Flags: --group string 群聊 openConversationId (必填) - --new-owner string 新群主 openDingTalkId - --user string 新群主 userId + --new-owner string 新群主 openDingTalkId (必填) ``` #### 获取群邀请链接 — 获取指定群聊的邀请加入链接 @@ -511,28 +509,17 @@ Usage: Example: dws chat message send-by-bot --robot-code --group --title "日报" --text "## 今日完成..." dws chat message send-by-bot --robot-code --users userId1,userId2 --title "提醒" --text "请提交周报" - dws chat message send-by-bot --robot-code --open-dingtalk-ids openDingtalkId1,openDingtalkId2 --title "提醒" --text "请提交周报" - dws chat message send-by-bot --robot-code --group --at-user-ids userId1,userId2 --title "提醒" --text "@userId1 @userId2 请查收本周报告" - dws chat message send-by-bot --robot-code --group --at-open-dingtalk-ids openDingtalkId1,openDingtalkId2 --title "提醒" --text "@openDingtalkId1 @openDingtalkId2 请查收本周报告" - dws chat message send-by-bot --robot-code --group --at-all --title "通知" --text "请所有人注意" Flags: --group string 群聊 openConversationId（群聊时必填） --robot-code string 机器人 Code (必填) --text string 消息内容 Markdown (必填) --title string 消息标题 (必填) - --users string 用户 userId 列表，逗号分隔，最多20个（单聊时必填） - --open-dingtalk-ids string 用户 openDingtalkId 列表，逗号分隔（单聊时可替代 --users，可选） - --at-user-ids string @指定成员的 userId 列表，逗号分隔（仅群聊时生效，可选） - --at-open-dingtalk-ids string @指定成员的 openDingtalkId 列表，逗号分隔（仅群聊时生效，可选） - --at-all @所有人（可选），服务端接收字符串 true/false + --users string 接收者 userId 列表，逗号分隔，最多20个（单聊时必填） 注意: - 用户明确要求机器人发送时，必须使用 `chat message send-by-bot`；严禁使用 `chat message send` 以用户身份代发 - - --group 与 --users/--open-dingtalk-ids 互斥，必须且只能指定其一 - - --group 的别名: --id, --chat, --conversation-id (均可替代 --group) - - --at-user-ids 仅在 --group 群聊时生效，单聊时无效；设置时 --text 中需包含 @userId 对应文本 - - --at-open-dingtalk-ids 仅在 --group 群聊时生效，单聊时无效；设置时 --text 中需包含 @openDingtalkId 对应文本 - - --at-all @所有人，仅群聊时生效；只需带上 --at-all flag 即可，服务端会自动处理 + - --group（群聊）与 --users（单聊）互斥，必须且只能指定其一 + - send-by-bot 不支持 @成员/@所有人 参数（无 --at-user-ids/--at-open-dingtalk-ids/--at-all）；如需在群里 @人，用 `chat message send --group` 走用户身份发送 - userId 获取方式：`dws contact user search --query "姓名"` 搜人获取 userId - **换行符**：--text 按 Markdown 渲染，换行规则同 `chat message send`： 1. 必须使用**真实换行符**（`U+000A`），而非字面量 `\n`，否则全部内容会渲染在同一行 @@ -1179,7 +1166,7 @@ Flags: 用户说"建群/创建群聊" → `chat group create` 用户说"搜索群/找群" → `chat search` 用户说"我创建的群/我管理的群/我是群主的群/我当管理员的群" → `chat group list-my-groups` -用户说"群成员/看群里有谁" → `chat group members` +用户说"群成员/看群里有谁" → `chat group members list` 用户说"拉人进群/加群成员" → `chat group members add` 用户说"踢人/移除群成员" → `chat group members remove` 用户说"加机器人到群" → `chat group members add-bot` @@ -1351,7 +1338,7 @@ dws chat message send-by-bot --robot-code --group --robot-code +dws chat group members add-bot --id --robot-code # Step 4: 重新发送 dws chat message send-by-bot --robot-code --group \ @@ -1370,27 +1357,22 @@ dws chat bot find --query "玉澜" --format json dws chat message send --open-dingtalk-id --text "你好" --format json ``` -### 机器人 @指定人发群消息 +### @指定人发群消息（用户身份） -通过 `--at-user-ids` 传入 userId 列表或 `--at-open-dingtalk-ids` 传入 openDingtalkId 列表来 @指定成员，多个用逗号分隔。`--text` 中需包含 `@userId` 或 `@openDingtalkId` 文本（不要用尖括号，不要用姓名）。通过 `--at-all` @所有人。 +`send-by-bot` 不支持 @ 参数。群里 @人/@所有人请用 `chat message send --group`（当前用户身份）：通过 `--at-open-dingtalk-ids` 传入 openDingTalkId 列表 @指定成员（多个逗号分隔），`--text` 中需包含对应 `@openDingTalkId` 文本；`--at-all` @所有人。 ```bash -# Step 1: 搜人获取 userId +# Step 1: 搜人获取 openDingTalkId dws contact user search --query "张三" --format json -# Step 2: 用 userId 发送并 @（注意 text 中 @userId） -dws chat message send-by-bot --robot-code --group \ - --at-user-ids userId1,userId2 \ - --title "提醒" --text "@userId1 @userId2 请查收本周报告" --format json - -# 或者用 openDingtalkId 发送并 @ -dws chat message send-by-bot --robot-code --group \ +# Step 2: @指定成员发群消息（注意 text 中带 @openDingTalkId） +dws chat message send --group \ --at-open-dingtalk-ids openDingtalkId1,openDingtalkId2 \ - --title "提醒" --text "@openDingtalkId1 @openDingtalkId2 请查收本周报告" --format json + --text "@openDingtalkId1 @openDingtalkId2 请查收本周报告" --format json # @所有人 -dws chat message send-by-bot --robot-code --group \ - --at-all --title "通知" --text "请所有人注意" --format json +dws chat message send --group \ + --at-all --text "请所有人注意" --format json ``` @@ -1467,8 +1449,8 @@ Flags: | `chat search` | `openConversationId` | message send/list、group members 等的 --group | | `chat group create` | `openConversationId` | 同上 | | `chat message list-all` | `nextCursor` | 下次 list-all 的 --cursor | -| `aisearch person` | `userId` | message send 的 --user、list-direct 的 --user、send-by-bot 的 --users、send-by-bot 的 --at-user-ids、list-by-sender 的 --sender-user-id | -| `aisearch person` → `contact user get` | `openDingTalkId` | message send 的 --at-open-dingtalk-ids、--open-dingtalk-id、list-direct 的 --open-dingtalk-id、send-by-bot 的 --open-dingtalk-ids、send-by-bot 的 --at-open-dingtalk-ids、list-by-sender 的 --sender-open-dingtalk-id | +| `aisearch person` | `userId` | message send 的 --user、list-direct 的 --user、send-by-bot 的 --users、list-by-sender 的 --sender-user-id | +| `aisearch person` → `contact user get` | `openDingTalkId` | message send 的 --at-open-dingtalk-ids、--open-dingtalk-id、list-direct 的 --open-dingtalk-id、list-by-sender 的 --sender-open-dingtalk-id | | `chat bot search` | `robotCode` | send-by-bot / recall-by-bot 的 --robot-code（仅我创建的机器人，无 openDingTalkId） | | `chat bot find` | `openDingTalkId` | 给机器人发单聊消息（全部可用机器人，额外返回 openDingTalkId） | | `chat message send-by-bot` | `processQueryKey` | recall-by-bot 的 --keys | @@ -1514,12 +1496,12 @@ Flags: - `--user` 和 `--open-dingtalk-id` 本质上都是发起单聊操作，只是用户标识格式不同：userId 为企业内部应用常用标识，openDingTalkId 为三方应用或跨组织场景下的用户标识，服务端对两种 ID 的解析逻辑不同 - `--time` 格式: `yyyy-MM-dd HH:mm:ss`，为拉取消息的起始时间点；`--forward` 控制方向（默认 true，拉给定时间之后的消息），`--limit` 控制数量 - `chat search` 挂在 `chat` 下（非 `chat group` 下），路径为 `dws chat search` -- `send-by-bot` 群聊传 `--group`，单聊传 `--users` 或 `--open-dingtalk-ids`，与 `--group` 互斥且必选其一；群聊时可选 `--at-user-ids` @指定成员（传 userId 列表）或 `--at-open-dingtalk-ids` @指定成员（传 openDingtalkId 列表），content 中需包含对应 @标识；`--at-all` @所有人；群聊场景如果返回"机器人不存在"错误，需先通过 `chat group members add-bot --group --robot-code ` 将机器人邀请进群后再发送 +- `send-by-bot` 群聊传 `--group`，单聊传 `--users`，二者互斥且必选其一；**不支持 @成员/@所有人**（无 `--at-user-ids`/`--at-open-dingtalk-ids`/`--at-all`），群里 @人请用 `chat message send --group` 走用户身份；群聊场景如果返回"机器人不存在"错误，需先通过 `chat group members add-bot --id --robot-code ` 将机器人邀请进群后再发送 - `recall-by-bot` 群聊传 `--group` + `--keys`，单聊仅传 `--keys`（不传 `--group` 即为单聊撤回） - `send-by-webhook` 支持 `--at-all`、`--at-mobiles`、`--at-users` 进行 @ 操作，但需在 `--text` 中包含 `@userId` 或 `@手机号` 才能生效；`--at-all` @所有人时需在 `--text` 中包含 `@10` - `chat group-role` 系列命令用于管理群的自定义身份标签：`list` 查列表，`add` 创建，`update` 改名，`remove` 删除；`set-user` 覆盖某人全部身份（传空 --role-ids 则清除），`remove-user` 仅移除指定身份，`query-user` 查询某人当前身份；用户用 `--user ` - 消息**换行符**（`send` / `send-by-bot` / `send-by-webhook` 的 `--text`）有两层要求：(1) 必须是**真实换行符** `U+000A`，不是字面量 `\n`；(2) Markdown 规范下单换行不生效，需用空行 `\n\n`（段落分隔）或行尾两空格 + 换行 / `
`（硬换行） -- `chat group transfer-owner` 转让群主，需传 --group（openConversationId）；新群主 userId 用 `--user`，openDingTalkId 用 `--new-owner` +- `chat group transfer-owner` 转让群主，需传 --group（openConversationId）；新群主用 `--new-owner`（传 openDingTalkId） - `chat group invite-url` 获取群邀请链接，需传 --group（openConversationId），可选 --expires-seconds 指定有效期（秒，0=永久） - `chat group quit` 退出群聊，需传 --group（openConversationId） - `chat group update-icon` 更新群头像，需传 --group（openConversationId）和 --icon-media-id（mediaId） @@ -1553,5 +1535,5 @@ Flags: ## 相关产品 -- [contact](./contact.md) — 搜索同事/好友，获取 userId 用于 --user、send-by-bot --users、send-by-bot --at-user-ids、list-by-sender --sender-user-id；获取 openDingTalkId 用于 message send 的 --at-open-dingtalk-ids、--open-dingtalk-id、send-by-bot --open-dingtalk-ids、send-by-bot --at-open-dingtalk-ids、list-by-sender 的 --sender-open-dingtalk-id +- [contact](./contact.md) — 搜索同事/好友，获取 userId 用于 --user、send-by-bot --users、list-by-sender --sender-user-id；获取 openDingTalkId 用于 message send 的 --at-open-dingtalk-ids、--open-dingtalk-id、list-by-sender 的 --sender-open-dingtalk-id - [drive](./drive.md) — 上传文件获取下载链接，用于 Markdown 图片/文件消息 diff --git a/skills/mono/references/products/contact.md b/skills/mono/references/products/contact.md index dbc7846e..aca24680 100644 --- a/skills/mono/references/products/contact.md +++ b/skills/mono/references/products/contact.md @@ -1,7 +1,8 @@ # 通讯录 (contact) 命令参考 -> **CRITICAL — 命令合法性**：contact 只有 `user` / `dept` / `label` / `relation` 四个二级子命令。 +> **CRITICAL — 命令合法性**：contact 只有 `user` / `dept` / `relation` 三个可操作的二级子命令。 > 不存在 `contact search`、`contact find`、`contact list`、`contact get`、`contact user find/list`。 +> 角色/标签（label）查询命令已下线，不再提供 `contact label list/get/list-members`。 > 构造命令前必须确认路径在下方「命令总览」中存在；不确定时，**根据意图对照下方「意图判断」选择正确命令**。 > > **CRITICAL — 根部门**：钉钉根部门 `deptId=1`。`dept` 系列命令查根部门统一传 `--dept 1` 或 `--depts 1`，不要传 `self / me / root / 0`。 @@ -187,52 +188,6 @@ Notes: - 跨层级成员展开见 [08-directory.md](../best_practices/08-directory.md) 的 `cross-level-dept-members` recipe ``` -### label (角色查询) - -> **角色ID = labelId**：用户提到"角色ID"时，均指通讯录 label 系统中的角色ID，**不是部门ID也不是userId**。查角色成员用 `label list-members --id <角色ID>`，不要传给 `dept get-info` 或 `user get`。 - -#### 获取企业所有角色列表 -``` -Usage: - dws contact label list -Example: - dws contact label list -Flags: - 无 -Notes: - - 无需参数，返回当前企业全部角色列表（labelId、labelName等） - - 用于不知道准确角色名称时先浏览全部角色 - - 典型场景：用户说“企业所有主管/查所有管理员/财务人员有哪些”→ 先 label list 浏览全部角色，匹配目标角色后 label list-members 获取成员 -``` - -#### 根据角色名称查询角色 -``` -Usage: - dws contact label get [flags] -Example: - dws contact label get --names "管理员" - dws contact label get --names "管理员,财务" -Flags: - --names string 角色名称，逗号分隔 (必填) -Notes: - - 精确匹配角色名称，不支持模糊搜索 - - 支持同时查询多个角色名称，逗号分隔 - - 无需分页 -``` - -#### 查询角色下的成员 -``` -Usage: - dws contact label list-members [flags] -Example: - dws contact label list-members --id 12345 -Flags: - --id string 角色 ID (必填) -Notes: - - 根据角色ID直接查询成员列表；已有角色ID时直接用 `--id ` - - 不知道角色ID时：先 `dws contact label get --names "角色名"` 或 `dws contact label list` 获取 labelId -``` - ## 意图判断 > **搜人首选 `aisearch person`**：凡是“找人/搜人/找同事/谁负责/上级/下级”均优先用 [aisearch person](./aisearch.md)，以下场景才用 contact。 @@ -247,32 +202,19 @@ Notes: 用户说"部门详情/部门信息/部门多少人" → `dept get-info`（返回部门ID、部门名称、部门人数；需 deptId，若只有部门名称需先 `dept search`） 用户说"子部门/下设部门/部门有哪些下级部门/枚举二级部门" → `dept list-children`（需父 deptId；只有部门名先 `dept search`） 用户说"部门有谁/部门成员/人员名单" → `dept list-members`（需 deptId；**仅本部门不含下级**，含下级先 `dept list-children` 再合并查） -用户查询涵盖"角色"（主管/管理员/财务/HR/总经理等任意角色名）→ 统一走 `contact label` 链路，按下方决策树选命令： -- 不知道角色名 / 枚举所有角色 → `label list` -- 已知角色名，查ID或成员 → 先 `label get --names <名>` 拿ID，查成员再调 `label list-members --id `；**精确匹配无结果时降级 `label list` 模糊匹配** -- 已知角色ID 查成员 → `label list-members --id ` +用户查询涵盖"角色/职责"（主管/管理员/财务/HR/总经理/谁负责 XX 等）→ 优先用 [`aisearch person`](./aisearch.md) 按职责维度找人（`dws aisearch person --keyword "<角色或职责>" --dimension duty`）。 > [!IMPORTANT] -> **角色查询 3 步决策树**（不依赖字串匹配，按语义判定）： -> 1. 不知道角色名 / 要枚举所有角色（列出企业有哪些角色、每个角色的名称和ID、不确定叫什么角色、负责XX的人有哪些等） → `label list` -> 2. 已知角色名 要查角色ID → `label get --names` -> 3. 已知角色ID 要查成员 → `label list-members --id` -> -> 任何含"角色"一词的查询默认走 `contact label` 链路。**唯一例外**：终点是"某个人是否具备某权限"（如"张三是不是管理员"）→ `user get`。禁止路由到 `user profile fields`（那是花名册字段）、`dept list-members` 筛选、或 OA/chat 模块。 - -> [!IMPORTANT] -> **角色查人 vs 查某人的角色信息 — 判断口径**：先判断用户的终点是"人"还是"属性"： -> - 终点是**人**（"管理员角色有哪些人""管理员下都有谁""查XX角色的成员"）→ 角色维度查人，**必须**走 `contact label` 链路（`label get`/`label list` → `label list-members`），**禁止**通过 `dept list-members` 筛选 `isAdmin` 等字段替代 +> **角色查人 vs 查某人的属性 — 判断口径**：先判断用户的终点是"人"还是"属性"： +> - 终点是**人**（"管理员有哪些人""谁负责财务""找 XX 角色的成员"）→ 走 [`aisearch person`](./aisearch.md)（职责维度找人） > - 终点是**属性**（"张三是不是管理员""查某人的主管/管理员权限"）→ 已知 userId 查个人详情，走 `user get`（返回 isAdmin/leader 等字段） > > 反例对照： -> - "管理员角色下都有哪些人" → `label get --names 管理员` → `label list-members`（终点=角色下的**人员列表**） -> - "我想知道管理员这个角色下都有谁" → `label get --names 管理员` → `label list-members`（终点=角色下的**人员列表**） +> - "管理员都有哪些人" → `aisearch person --keyword 管理员 --dimension duty`（终点=人员列表） > - "张三是不是管理员" → `user get --ids `（终点=某个人的**属性**） > - "查一下张三的管理员权限" → `user get --ids `（终点=某个人的**属性**） -> - "角色ID为55808858的角色下有哪些成员" → `label list-members --id 55808858`（已有角色ID直接查成员） > -> **角色 = 通讯录 label**：用户提到"角色"（角色ID/角色成员/角色名称/企业角色/查角色下的人）时，均指通讯录组织角色，应走 `contact label` 链路。OA 审批只管审批流程（待审批/同意/拒绝），**不支持**查询角色成员；群角色(chat group-role)只管群内身份，不涉及企业组织角色。 +> 注意：`contact label` 角色查询命令已下线，不要再构造 `contact label list/get/list-members`。OA 审批只管审批流程（待审批/同意/拒绝），**不支持**查询角色成员；群角色(chat group-role)只管群内身份，不涉及企业组织角色。 用户说"我关注了谁/我的特别关注列表/我的星标联系人/特别关注的人有哪些" → `relation list-my-followings` > [!IMPORTANT] @@ -312,28 +254,19 @@ dws contact dept list-children --dept <父deptId> --format json # 6. 查看部门成员 dws contact dept list-members --depts --format json -# 7. 获取企业所有角色列表 — 不知道角色名时先浏览 -dws contact label list --format json - -# 8. 根据角色名称查询角色 -dws contact label get --names "管理员" --format json - -# 9. 查询角色下的成员 -dws contact label list-members --id --format json - -# 10. 查询花名册有权限的字段列表 +# 7. 查询花名册有权限的字段列表 dws contact user profile fields --format json -# 11. 根据字段 code 查询指定员工的花名册信息 +# 8. 根据字段 code 查询指定员工的花名册信息 dws contact user profile get --staff-id --fields fieldCode1,fieldCode2 --format json -# 12. 查询所有可见字段的花名册信息 +# 9. 查询所有可见字段的花名册信息 dws contact user profile get --staff-id --format json -# 13. 查询全部离职员工 +# 10. 查询全部离职员工 dws contact user dismission search --format json -# 14. 按姓名/时间范围/部门筛选离职员工 +# 11. 按姓名/时间范围/部门筛选离职员工 dws contact user dismission search --name "张三" --format json dws contact user dismission search --start 2026-01-01 --end 2026-03-31 --format json dws contact user dismission search --depts 123456,789012 --hide-retirement=false --format json @@ -347,8 +280,6 @@ dws contact user dismission search --depts 123456,789012 --hide-retirement=false | `user get-self/search` | `orgAuthEmail` | mail message send 的 --to/--cc (跨产品) | | `user get-self/search` | `userId` | profile get 的 --staff-id | | `user profile fields` | `fieldCode` | profile get 的 --fields | -| `label list` | `labelId` / `labelName` | `label get --names` 或 `label list-members --id` | -| `label get` | `labelId` | `label list-members` 的 --id | | `dept search/list-children` | `deptId` | dept get-info/list-children/list-members 的 --dept/--depts | | `dept search/list-children` | `deptId` | dismission search 的 --depts | @@ -362,11 +293,7 @@ dws contact user dismission search --depts 123456,789012 --hide-retirement=false - 建议先执行 `user profile fields` 获取可用字段列表，再根据需要的字段 code 执行 `user profile get` - `user dismission search` 的 `--start`/`--end` 必须同时设置或同时不设置，不允许只传其中一个 - `user dismission search` 默认隐藏退休人员（`--hide-retirement` 默认 true），默认展示合作伙伴（`--hide-partner` 默认 false） -- `label list` 无需参数，适用于不知道准确角色名称的场景；当用户说“查所有主管/主管理员/财务”等角色类型人员时，优先 `label list` 列出企业全部角色，LLM 灵活匹配目标角色后调用 `label list-members` -- 角色类查询（主管、管理员、财务、HR 等任意角色）优先走 label 链路，而非 dept list-members 或 aisearch person；label 精确命中角色维度，返回完整名单 -- `label get` 是精确匹配角色名称，不支持模糊搜索；支持逗号分隔同时查询多个角色名称 -- **`label get` 精确匹配无结果时的降级策略**：若 `label get --names "XX"` 返回空结果，必须降级调用 `label list` 获取全部角色列表，从中模糊匹配包含XX关键词的角色（如用户说"管理员"可匹配到"主管理员"和"子管理员"），再对匹配到的角色调用 `label list-members` -- `label list-members` 需要先通过 `label list` 或 `label get` 获取 labelId，再用 --id 查询角色下的成员 +- 角色/职责类查询（主管、管理员、财务、HR 等任意角色，或"谁负责 XX"）优先走 [`aisearch person`](./aisearch.md) 的职责维度（`--dimension duty`）；`contact label` 角色查询命令已下线，不要再构造 ## 自动化脚本 diff --git a/skills/mono/references/products/ding.md b/skills/mono/references/products/ding.md index 28cc5beb..f9849bbb 100644 --- a/skills/mono/references/products/ding.md +++ b/skills/mono/references/products/ding.md @@ -26,36 +26,10 @@ Flags: --robot-code string 机器人 ID (必填, 或设 DINGTALK_DING_ROBOT_CODE) ``` -### 查询 DING 消息历史 -``` -Usage: - dws ding message list [flags] -Example: - dws ding message list - dws ding message list --type UNREAD - dws ding message list --type SEND --cursor 10 -Flags: - --cursor int 分页游标 (首次传 0, 翻页传返回的 nextCursor) - --type string 消息类型: ALL / UNREAD / SEND / NEW_COMMENT / DELETED (可选, 不传返回全部) -``` - -### 查看 DING 接收状态 -``` -Usage: - dws ding message receiver-status [flags] -Example: - dws ding message receiver-status --ding-id - # 查询 dingId: dws ding message list -Flags: - --ding-id string DING 消息 openDingId (必填) -``` - ## 意图判断 用户说"DING 一下/紧急通知/电话提醒" → `message send` 用户说"撤回 DING" → `message recall` -用户说"DING 消息/查 DING/DING 历史/我的 DING" → `message list` -用户说"DING 接收状态/谁收到了 DING/DING 已读" → `message receiver-status` 关键区分: - ding(紧急提醒, 支持电话/短信) vs bot(常规群/单聊消息) @@ -77,7 +51,6 @@ dws ding message recall --robot-code --id --format j | 操作 | 提取 | 用于 | |------|------|------| | `message send` | `openDingId` | message recall 的 --id | -| `message list` | `openDingId` | message receiver-status 的 --ding-id | ## 注意事项 - `--robot-code` 从钉钉开放平台 **应用管理 → 机器人** 中获取，也可设环境变量 `DINGTALK_DING_ROBOT_CODE` - sms/call 类型有通信费用，使用前需和用户确认 diff --git a/skills/mono/references/products/doc.md b/skills/mono/references/products/doc.md index 218915d8..63f87305 100644 --- a/skills/mono/references/products/doc.md +++ b/skills/mono/references/products/doc.md @@ -77,19 +77,19 @@ dws doc media --help | `doc comment list/create/reply/create-inline` | 文档评论与划词评论 | `--node` (+ ...) | [`doc/doc-comment.md`](./doc/doc-comment.md) | | `doc export` / `doc export get` | 在线文档导出 docx | `--node` `--output` | [`doc/doc-export.md`](./doc/doc-export.md) | -### 文件操作（已迁移，以下命令 deprecated） +### 文件操作（doc 与 drive 均提供，按场景选用） -> **迁移提示**：文件管理命令已按产品领域架构重新归属，旧命令在过渡期内仍可使用，运行时会输出 deprecated 警告。 +> **说明**：以下命令在 `doc` 下均为可用命令；`drive` 下也有等价命令（聚合钉盘 + 文档空间）。需要纯文件/钉盘语义时用 `drive`，需要在文档空间内操作时用 `doc`，两者都不会报 deprecated。 -| 旧命令 | 推荐命令 | 详见 | -|--------|----------|------| +| doc 命令 | drive 等价命令 | 详见 | +|----------|----------------|------| | `doc upload` | `dws drive upload` | [`drive.md`](./drive.md) | | `doc download` | `dws drive download` | [`drive.md`](./drive.md) | | `doc copy` | `dws drive copy` | [`drive.md`](./drive.md) | | `doc move` | `dws drive move` | [`drive.md`](./drive.md) | | `doc rename` | `dws drive rename` | [`drive.md`](./drive.md) | | `doc delete` | `dws drive delete` | [`drive.md`](./drive.md) | -| `doc folder create` | `dws drive folder create` | [`drive.md`](./drive.md) | +| `doc folder create` | `dws drive mkdir` | [`drive.md`](./drive.md) | | `doc file create` | `dws wiki node create --type ` | [`wiki.md`](./wiki.md) | | `doc permission *` | `dws drive permission *` | [`drive.md`](./drive.md) | | `doc list` | `dws drive list --workspace` / `dws wiki node list` | [`drive.md`](./drive.md) / [`wiki.md`](./wiki.md) | @@ -120,9 +120,9 @@ dws doc media --help | 插入富 block（callout / 分栏 / 表格） | [`doc-block.md`](./doc/doc-block.md) + [`format/doc-jsonml-cookbook.md`](./doc/format/doc-jsonml-cookbook.md) + [`style/doc-style-guideline.md`](./doc/style/doc-style-guideline.md) | block insert | | 上传图片 / 附件 | [`doc-media.md`](./doc/doc-media.md) | media insert | | 评论 / 划词评论（含 @人） | [`doc-comment.md`](./doc/doc-comment.md)（+ `dws contact user search` 取 mention 用 userId） | comment create | -| 文档分享 / 节点级权限 | [`drive.md`](./drive.md)（已迁移：`dws drive permission add/update/list/remove`） | `drive permission` | +| 文档分享 / 节点级权限 | [`drive.md`](./drive.md)（推荐 `dws drive permission add/update/list/remove`；`doc permission *` 亦可用） | `drive permission` | | 导出 PDF / DOCX | [`doc-info.md`](./doc/doc-info.md) + [`doc-export.md`](./doc/doc-export.md) | export | -| 文件下载 / 上传 / 移动 / 重命名 / 复制 | [`drive.md`](./drive.md)（已迁移：`dws drive upload/download/copy/move/rename/delete`） | `drive *` | +| 文件下载 / 上传 / 移动 / 重命名 / 复制 | [`drive.md`](./drive.md)（推荐 `dws drive upload/download/copy/move/rename/delete`；同名 `doc` 命令亦可用） | `drive *` | ## 意图判断 @@ -284,12 +284,12 @@ dws doc block list --node --format json # 划词需先 dws doc comment create-inline --node --block-id \ --start 0 --end 10 --content "建议调整" --selected-text "原文" --format json -# ── 工作流 8: 权限授予（节点级，已迁移到 drive）── +# ── 工作流 8: 权限授予（节点级，推荐用 drive，doc permission 亦可用）── dws contact user search --query "张三" --format json # 取 userId dws drive permission add --node --user , --role EDITOR --format json dws drive permission list --node --format json # 校验 -# ── 工作流 9: 文件操作（已迁移到 drive）── +# ── 工作流 9: 文件操作（推荐用 drive，同名 doc 命令亦可用）── # 第一步：获取 nodeId # 方式 A（优先）：用户直接提供 URL / nodeId → 直接传 --node # 方式 B：按关键字找：dws drive search --query "项目周报" --format json diff --git a/skills/mono/references/products/doc/doc-comment.md b/skills/mono/references/products/doc/doc-comment.md index 0d2f3a3f..50cc9dda 100644 --- a/skills/mono/references/products/doc/doc-comment.md +++ b/skills/mono/references/products/doc/doc-comment.md @@ -15,11 +15,11 @@ Usage: Example: dws doc comment list --node dws doc comment list --node --type inline --resolve-status unresolved - dws doc comment list --node --limit 20 --cursor + dws doc comment list --node --page-size 20 --next-token Flags: --node string 目标文档的标识，支持传入 URL 或 ID (必填) - --limit int 每页返回的评论数量，默认 50，最大 50 - --cursor string 分页游标，从上一次请求的返回结果中获取 (首次请求不传) + --page-size int 每页返回的评论数量 + --next-token string 下一页 token，从上一次请求的返回结果中获取 (首次请求不传) --type string 按评论类型过滤: global (全文评论) / inline (划词评论) --resolve-status string 按解决状态过滤: resolved (已解决) / unresolved (未解决) ``` diff --git a/skills/mono/references/products/doc/doc-list.md b/skills/mono/references/products/doc/doc-list.md index a05a6293..0be541fe 100644 --- a/skills/mono/references/products/doc/doc-list.md +++ b/skills/mono/references/products/doc/doc-list.md @@ -13,19 +13,19 @@ Usage: Example: dws doc list dws doc list --folder - dws doc list --workspace --limit 20 + dws doc list --workspace --page-size 20 Flags: --folder string 文档文件夹 nodeId 或 alidocs 文件夹 URL；不要传 drive dentryId/parent-id 这类纯数字 ID --workspace string 知识库 ID - --limit int 每页数量 (默认 50，最大 50) - --cursor string 分页游标 (从上次结果的 nextPageToken 获取) + --page-size int 每页数量 + --page-token string 分页 token (从上次结果的 nextPageToken 获取) ``` ## 关键说明 - 不传任何 flag 时遍历"我的文档"根目录。 - `--folder` 仅接受文档文件夹 `nodeId` / `dentryUuid` / alidocs 文件夹 URL；**禁止**传入 drive `dentryId`、`parentId`、`spaceId` 这类纯数字 ID。 -- 单页最多 50 条，需翻页时使用 `nextPageToken` → `--cursor`。 +- 需翻页时使用 `nextPageToken` → `--page-token`。 ## 上下文传递 @@ -45,10 +45,10 @@ dws doc list --folder --format json dws doc list --folder "https://alidocs.dingtalk.com/i/nodes/" --format json # 浏览指定知识库根目录（取出 workspaceId 后） -dws doc list --workspace --limit 20 --format json +dws doc list --workspace --page-size 20 --format json # 翻页 -dws doc list --folder --cursor --format json +dws doc list --folder --page-token --format json ``` ## 参考 diff --git a/skills/mono/references/products/doc/doc-search.md b/skills/mono/references/products/doc/doc-search.md index ea6aa4ca..845b9b22 100644 --- a/skills/mono/references/products/doc/doc-search.md +++ b/skills/mono/references/products/doc/doc-search.md @@ -31,8 +31,8 @@ Flags: --editor-uids strings 按编辑者用户 ID 过滤，逗号分隔 --mentioned-uids strings 按 @提及的用户 ID 过滤，逗号分隔 --workspace-ids strings 按知识库 ID 过滤，支持知识库 URL，逗号分隔 - --limit int 每页数量 (默认 10，最大 30) - --cursor string 分页游标 (从上次结果的 nextPageToken 获取) + --page-size int 每页数量 + --page-token string 分页 token (从上次结果的 nextPageToken 获取) ``` ## 关键说明 @@ -70,7 +70,7 @@ dws doc search --creator-uids uid1,uid2 dws doc search --workspace-ids wsId1,wsId2 # 翻页 -dws doc search --query "周报" --limit 30 --cursor +dws doc search --query "周报" --page-size 30 --page-token ``` ## 参考 diff --git a/skills/mono/references/products/mail.md b/skills/mono/references/products/mail.md index ca3ad80b..4abb021e 100644 --- a/skills/mono/references/products/mail.md +++ b/skills/mono/references/products/mail.md @@ -96,13 +96,13 @@ dws contact user search --keyword "姓名" --format json Usage: dws mail message search [flags] Example: - dws mail message search --email user@company.com --query "subject:\"周报\"" --size 20 - dws mail message search --email user@company.com --query "from:alice AND date>2025-06-01T00:00:00Z" --size 10 + dws mail message search --email user@company.com --query "subject:\"周报\"" --limit 20 + dws mail message search --email user@company.com --query "from:alice AND date>2025-06-01T00:00:00Z" --limit 10 Flags: --cursor string 邮件的起始偏移标识, 其值取自响应中的nextCursor字段。""表示从头开始 --email string 搜索目标邮箱地址 (必填) --query string KQL 查询表达式 (必填), 其中 date 格式需遵循 ISO8601 规范 - --size string 每页返回数量(最大限制 100, 默认 20)，别名: --limit, --page-size + --limit string 每页返回数量(最大限制 100, 默认 20) ``` KQL 查询字段: date, size, tag, folderId, isRead, hasAttachments, subject, attachname, body, from, to @@ -140,9 +140,9 @@ KQL 查询字段: date, size, tag, folderId, isRead, hasAttachments, subject, at **翻页示例：** ```bash # 第一页 -dws mail message search --email user@company.com --query "folderId:2" --size 20 --format json +dws mail message search --email user@company.com --query "folderId:2" --limit 20 --format json # 取返回中的 nextCursor，传入下一次请求（nextCursor="$" 时停止） -dws mail message search --email user@company.com --query "folderId:2" --size 20 --cursor --format json +dws mail message search --email user@company.com --query "folderId:2" --limit 20 --cursor --format json ``` ### 查看邮件完整内容 @@ -168,17 +168,17 @@ Usage: dws mail message send [flags] Example: dws mail message send --from user@company.com --to colleague@company.com \ - --subject "周报" --body "本周完成任务A和任务B" + --subject "周报" --content "本周完成任务A和任务B" dws mail message send --from user@company.com --to colleague@company.com \ - --subject "周报" --body "见附件" --attachment ./report.pdf + --subject "周报" --content "见附件" --attachment ./report.pdf dws mail message send --from user@company.com --to colleague@company.com \ - --subject "周报" --body "见附件" --attachment ./a.pdf --attachment ./b.xlsx + --subject "周报" --content "见附件" --attachment ./a.pdf --attachment ./b.xlsx dws mail message send --from user@company.com --to colleague@company.com \ - --subject "图表周报" --body "图表如下：[inline:chart.png]" --inline-attachment ./chart.png + --subject "图表周报" --content "图表如下：[inline:chart.png]" --inline-attachment ./chart.png dws mail message send --from user@company.com --to colleague@company.com \ - --subject "带图文档" --body "见附件，图表：[inline:img.png]" --attachment ./doc.pdf --inline-attachment ./img.png + --subject "带图文档" --content "见附件，图表：[inline:img.png]" --attachment ./doc.pdf --inline-attachment ./img.png Flags: - --body string 邮件正文 (必填) + --content string 邮件正文 (必填) --cc string 抄送人列表 --from string 发件人邮箱 (必填)，别名: --sender --subject string 邮件标题 (必填) @@ -202,7 +202,7 @@ Flags: - 仅支持图片类型：`jpg` / `jpeg` / `png` / `gif` / `webp` / `bmp` / `svg` - CLI 自动生成 contentId，格式：`inline-{文件名(不含扩展名)}-{序号}@alimail.com`，例：`inline-chart-1@alimail.com` -- 在 `--body` 中使用占位符 `[inline:文件名]` 引用图片，CLI 自动替换为 `` 标签 +- 在 `--content` 中使用占位符 `[inline:文件名]` 引用图片，CLI 自动替换为 `` 标签 - 若 body 中没有对应占位符，内联图片会自动追加到正文末尾 - 非图片类型（PDF、视频、音频等）请改用 `--attachment` @@ -339,13 +339,13 @@ Usage: dws mail message reply [flags] Example: dws mail message reply --from user@company.com --id - dws mail message reply --from user@company.com --id --subject "Re: 周报" --body "已收到，谢谢！" + dws mail message reply --from user@company.com --id --subject "Re: 周报" --content "已收到，谢谢！" Flags: --from string 发件人邮箱 (必填)，别名: --sender --to string 收件人列表（可选） --id string 要回复的邮件 ID (必填) --subject string 回复邮件标题（可选） - --body string 回复正文（可选） + --content string 回复正文（可选） --attachment stringArray 附件文件路径，可多次指定 (可选) --inline-attachment stringArray 内联图片路径，可多次指定，cid 自动生成 (可选) ``` @@ -371,13 +371,13 @@ Usage: dws mail message reply-all [flags] Example: dws mail message reply-all --from user@company.com --id - dws mail message reply-all --from user@company.com --id --subject "Re: 周报" --body "感谢大家的参与！" + dws mail message reply-all --from user@company.com --id --subject "Re: 周报" --content "感谢大家的参与！" Flags: --from string 发件人邮箱 (必填)，别名: --sender --to string 收件人列表（可选，包含发件人及所有原始收件人） --id string 要回复的邮件 ID (必填) --subject string 回复邮件标题（可选） - --body string 回复正文（可选） + --content string 回复正文（可选） --attachment stringArray 附件文件路径，可多次指定 (可选) --inline-attachment stringArray 内联图片路径，可多次指定，cid 自动生成 (可选) ``` @@ -409,7 +409,7 @@ Flags: --to string 转发收件人列表（可选） --id string 要转发的邮件 ID (必填) --subject string 转发邮件标题（可选） - --body string 转发附言（可选） + --content string 转发附言（可选） --attachment stringArray 附件文件路径，可多次指定 (可选) --inline-attachment stringArray 内联图片路径，可多次指定，cid 自动生成 (可选) ``` @@ -461,27 +461,27 @@ Usage: dws mail draft create [flags] Example: dws mail draft create --from user@company.com --to colleague@company.com \ - --subject "草稿标题" --body "草稿正文" + --subject "草稿标题" --content "草稿正文" dws mail draft create --from user@company.com --subject "草稿标题" dws mail draft create --from user@company.com --subject "带附件草稿" \ - --body "见附件" --attachment ./report.pdf + --content "见附件" --attachment ./report.pdf dws mail draft create --from user@company.com --subject "带图片草稿" \ - --body "图表：[inline:chart.png]" --inline-attachment ./chart.png + --content "图表：[inline:chart.png]" --inline-attachment ./chart.png Flags: --from string 发件人邮箱 (必填)，别名: --sender --subject string 邮件标题 (必填) --to string 收件人列表（可选，有确定收件人时才传） --cc string 抄送人列表（可选，有确定抄送人时才传） - --body string 邮件正文（可选，有正文内容时才传） + --content string 邮件正文（可选，有正文内容时才传） --attachment stringArray 附件文件路径，可多次指定 (可选) --inline-attachment stringArray 内联图片路径，可多次指定，cid 自动生成 (可选) ``` -> **注意：** `--to`、`--cc`、`--body` 均为可选参数，**仅在用户明确提供对应信息时才传入**。若用户未指定收件人，不要传 `--to ""`（空字符串）。 +> **注意：** `--to`、`--cc`、`--content` 均为可选参数，**仅在用户明确提供对应信息时才传入**。若用户未指定收件人，不要传 `--to ""`（空字符串）。 **附件说明：** -指定 `--attachment` 或 `--inline-attachment` 时，CLI 自动完成草稿创建和附件上传，**草稿保留在草稿箱，不会发送**。内联图片用法同 `message send`（`--body` 中使用 `[inline:文件名]` 占位符）。 +指定 `--attachment` 或 `--inline-attachment` 时，CLI 自动完成草稿创建和附件上传，**草稿保留在草稿箱，不会发送**。内联图片用法同 `message send`（`--content` 中使用 `[inline:文件名]` 占位符）。 **返回字段：** @@ -494,24 +494,24 @@ Flags: Usage: dws mail draft update [flags] Example: - dws mail draft update --from user@company.com --id --subject "新标题" --body "新正文" - dws mail draft update --from user@company.com --id --body "见附件" --attachment ./report.pdf + dws mail draft update --from user@company.com --id --subject "新标题" --content "新正文" + dws mail draft update --from user@company.com --id --content "见附件" --attachment ./report.pdf dws mail draft update --from user@company.com --id \ - --body "图表：[inline:chart.png]" --inline-attachment ./chart.png + --content "图表：[inline:chart.png]" --inline-attachment ./chart.png Flags: --from string 发件人邮箱 (必填)，别名: --sender --id string 草稿邮件 ID (必填) --to string 收件人列表（可选） --cc string 抄送人列表（可选） --subject string 邮件标题（可选） - --body string 邮件正文（可选） + --content string 邮件正文（可选） --attachment stringArray 附件文件路径，可多次指定 (可选) --inline-attachment stringArray 内联图片路径，可多次指定，cid 自动生成 (可选) ``` **附件说明：** -指定 `--attachment` 或 `--inline-attachment` 时，CLI 自动完成草稿更新和附件上传，**草稿保留在草稿箱，不会发送**。内联图片用法同 `message send`（`--body` 中使用 `[inline:文件名]` 占位符）。 +指定 `--attachment` 或 `--inline-attachment` 时，CLI 自动完成草稿更新和附件上传，**草稿保留在草稿箱，不会发送**。内联图片用法同 `message send`（`--content` 中使用 `[inline:文件名]` 占位符）。 ### 发送草稿 ``` @@ -533,13 +533,13 @@ Usage: Example: dws mail user search --keyword "张三" dws mail user search --email user@company.com --keyword "张三" - dws mail user search --email user@company.com --keyword "alice" --size 10 + dws mail user search --email user@company.com --keyword "alice" --limit 10 dws mail user search --email user@company.com --keyword "alice" --cursor Flags: --email string 搜索目标邮箱地址 (可选) --keyword string 搜索关键词 (必填) --cursor string 分页游标，取自响应中的 nextCursor 字段（可选） - --size string 每页返回数量（可选） + --limit string 每页返回数量（可选） ``` > **重要区别：** @@ -621,29 +621,29 @@ dws mail mailbox list --format json # 2. 搜索邮件 — 提取 messageId dws mail message search --email user@company.com \ - --query "subject:\"周报\" AND date>2025-06-01T00:00:00Z" --size 10 --format json + --query "subject:\"周报\" AND date>2025-06-01T00:00:00Z" --limit 10 --format json # 3. 查看邮件详情 dws mail message get --email user@company.com --id --format json # 4. 发送邮件（纯文本） dws mail message send --from user@company.com --to colleague@company.com \ - --subject "周报" --body "本周完成…" --format json + --subject "周报" --content "本周完成…" --format json # 4b. 发送带附件的邮件（自动编排：创建草稿→上传附件→发送草稿） dws mail message send --from user@company.com --to colleague@company.com \ - --subject "周报" --body "见附件" --attachment ./report.pdf --format json + --subject "周报" --content "见附件" --attachment ./report.pdf --format json # 4c. 发送带内联图片的邮件（正文自动转 HTML， 标签自动注入） dws mail message send --from user@company.com --to colleague@company.com \ - --subject "图表周报" --body "本周图表如下：[inline:chart.png]" \ + --subject "图表周报" --content "本周图表如下：[inline:chart.png]" \ --inline-attachment ./chart.png --format json # 5. 下载邮件附件到本地（每次只能下载一个附件，不支持批量下载） # 步骤 5.1：搜索匹配的邮件，获取 messageId 列表 # 示例：下载4月所有发票邮件的附件 dws mail message search --email user@company.com \ - --query "subject:发票 AND date>2025-04-01T00:00:00Z AND date<2025-05-01T00:00:00Z AND hasAttachments:true" --size 50 --format json + --query "subject:发票 AND date>2025-04-01T00:00:00Z AND date<2025-05-01T00:00:00Z AND hasAttachments:true" --limit 50 --format json # 步骤 5.2：对每封邮件，列出附件获取 attachmentId 和 name # （对搜索结果中的每封邮件都要执行一次） @@ -656,7 +656,7 @@ dws mail attachment download --email user@company.com \ # 5. 获取邮件所属会话详情（thread） # 步骤 5.1：先通过 message search 或 message get 获取邮件中的 conversationId dws mail message search --email user@company.com \ - --query "subject:\"周报\"" --size 5 --format json + --query "subject:\"周报\"" --limit 5 --format json # 从返回的邮件列表中提取 conversationId 字段 # 步骤 5.2：用 conversationId 获取会话详情 diff --git a/skills/mono/references/products/minutes.md b/skills/mono/references/products/minutes.md index 438e07ad..8ba2acd6 100644 --- a/skills/mono/references/products/minutes.md +++ b/skills/mono/references/products/minutes.md @@ -22,9 +22,9 @@ minutes 模块的命令是**两级或三级结构**，不同层级之间不能 ``` dws minutes ├── list # 查询听记列表（list 后必须跟 mine / shared / all） -│ ├── mine [--query] [--start] [--end] [--max] [--next-token] # 仅查询我自己创建/发起的听记（不含他人共享给我的） -│ ├── shared [--query] [--start] [--end] [--max] [--next-token] # 仅查询他人共享给我的听记（不含我自己创建的） -│ └── all [--query] [--start] [--end] [--max] [--next-token] # 查询我可访问的所有听记（= mine ∪ shared，覆盖面最广，默认 scope） +│ ├── mine [--query] [--start] [--end] [--max] [--cursor] # 仅查询我自己创建/发起的听记（不含他人共享给我的） +│ ├── shared [--query] [--start] [--end] [--max] [--cursor] # 仅查询他人共享给我的听记（不含我自己创建的） +│ └── all [--query] [--start] [--end] [--max] [--cursor] # 查询我可访问的所有听记（= mine ∪ shared，覆盖面最广，默认 scope） ├── get # 获取听记详情（get 后必须跟子命令名） │ ├── info --id # 获取听记基础信息（标题、时长、参与人、状态等） │ ├── summary --id # 获取听记 AI 摘要（结构化纪要） @@ -102,15 +102,15 @@ dws minutes > > | 语义 | 规约 Primary | minutes 当前 CLI 实际参数 | alias 注册状态 | 说明 | > |------|-------------|------------------------|--------------|------| -> | 单页大小 (Group 13) | `--limit` | `--max` | `--limit` 未注册 | minutes 用 `--max`，其他模块用 `--limit`。**跨模块切换时注意差异** | -> | 续页标识 (Group 14) | `--cursor` | `--next-token` | `--next-token` 在 alias 池中 | minutes 用 `--next-token`，合法 alias | +> | 单页大小 (Group 13) | `--limit` | `--limit`（别名 `--max`） | 已对齐 | `list mine/shared/all` 用 `--limit`，`--max` 为别名 | +> | 续页标识 (Group 14) | `--cursor` | `list`: `--cursor`；`get transcription`: `--next-token` | 部分对齐 | **list 系列用 `--cursor`，get transcription 用 `--next-token`，不要混用** | > | 搜索关键词 (Group 11) | `--query` | `--query` | 已对齐 | 无差异 | > | 起始时间 (Group 15) | `--start` | `--start` | 已对齐 | 无差异 | > | 结束时间 (Group 16) | `--end` | `--end` | 已对齐 | 无差异 | > > **跨模块参数名差异速查（防止混用）：** -> - 分页大小：minutes 用 `--max`，aitable/calendar/chat/drive 用 `--limit` -> - 续页标识：minutes 用 `--next-token`，aitable/drive/doc 用 `--cursor` +> - 分页大小：minutes `list` 用 `--limit`（别名 `--max`），与其他模块一致 +> - 续页标识：minutes `list mine/shared/all` 用 `--cursor`；minutes `get transcription` 用 `--next-token`；aitable/drive/doc 用 `--cursor` > - 起止时间：minutes/report 用 `--start`/`--end`，calendar 用 `--start-time`/`--end-time`（跨模块最高频错误） **铁律：禁止编造 taskUuid（0512 P0 Golden Case 提炼）** @@ -271,9 +271,9 @@ dws minutes ``` dws minutes ├── list # 二级：list 后必须跟 mine / shared / all -│ ├── mine [--query] [--start] [--end] [--max] [--next-token] -│ ├── shared [--query] [--start] [--end] [--max] [--next-token] -│ └── all [--query] [--start] [--end] [--max] [--next-token] +│ ├── mine [--query] [--start] [--end] [--max] [--cursor] +│ ├── shared [--query] [--start] [--end] [--max] [--cursor] +│ └── all [--query] [--start] [--end] [--max] [--cursor] ├── get # 二级：get 后必须跟子命令名 │ ├── info --id │ ├── summary --id @@ -320,17 +320,17 @@ Usage: Example: dws minutes list mine dws minutes list mine --max 10 - dws minutes list mine --max 10 --next-token + dws minutes list mine --max 10 --cursor dws minutes list mine --query "周会" Flags: - --max float 查询的听记篇数 (默认 10) - --next-token string 分页 token (首页留空，后续填写前次返回的 nextToken) + --max float 查询的听记篇数 (默认 10，--limit 的别名) + --cursor string 分页游标 (首页留空，后续填写前次返回的 nextCursor) --query string 关键字筛选 (可选) --start string 开始时间 ISO-8601 (可选) --end string 结束时间 ISO-8601 (可选) ``` -查询我创建的听记列表，支持 `--max` 和 `--next-token` 分页，支持按关键字和时间范围筛选。 +查询我创建的听记列表，支持 `--max` 和 `--cursor` 分页，支持按关键字和时间范围筛选。 ### 查询他人共享给我的听记列表 ``` @@ -339,16 +339,16 @@ Usage: Example: dws minutes list shared dws minutes list shared --max 20 - dws minutes list shared --max 5 --next-token + dws minutes list shared --max 5 --cursor Flags: - --max float 查询的听记篇数 (默认 10) - --next-token string 分页 token (首页留空，后续填写前次返回的 nextToken) + --max float 查询的听记篇数 (默认 10，--limit 的别名) + --cursor string 分页游标 (首页留空，后续填写前次返回的 nextCursor) --query string 关键字筛选 (可选) --start string 开始时间 ISO-8601 (可选) --end string 结束时间 ISO-8601 (可选) ``` -查询他人共享给我的听记列表，支持 `--max` 和 `--next-token` 分页，支持按关键字和时间范围筛选。 +查询他人共享给我的听记列表，支持 `--max` 和 `--cursor` 分页，支持按关键字和时间范围筛选。 ### 查询我有权限访问的所有听记列表 ``` @@ -359,16 +359,16 @@ Example: dws minutes list all --max 20 dws minutes list all --query "周会" --max 20 dws minutes list all --start "2026-03-01T00:00:00+08:00" --end "2026-03-20T23:59:59+08:00" - dws minutes list all --max 10 --next-token + dws minutes list all --max 10 --cursor Flags: --end string 结束时间 ISO-8601 (可选) --query string 关键字筛选 (可选) - --max float 查询的听记篇数 (默认 10) - --next-token string 分页 token (首页留空，后续填写前次返回的 nextToken) + --max float 查询的听记篇数 (默认 10，--limit 的别名) + --cursor string 分页游标 (首页留空，后续填写前次返回的 nextCursor) --start string 开始时间 ISO-8601 (可选) ``` -查询我有权限访问的所有听记列表（包括我创建的、他人共享给我的等所有有权限的听记）。支持按关键字和时间范围筛选。时间范围和关键字为可选参数，不传则返回所有有权限的听记。支持使用 `--max` 和 `--next-token` 进行分页查询。 +查询我有权限访问的所有听记列表（包括我创建的、他人共享给我的等所有有权限的听记）。支持按关键字和时间范围筛选。时间范围和关键字为可选参数，不传则返回所有有权限的听记。支持使用 `--max` 和 `--cursor` 进行分页查询。 ### 获取听记基础信息 ``` @@ -1607,7 +1607,7 @@ dws minutes record start --format json # 1. 查看我的听记列表 — 提取 taskUuid dws minutes list mine --format json -dws minutes list mine --max 10 --next-token --format json +dws minutes list mine --max 10 --cursor --format json dws minutes list mine --query "周会" --format json # 1b. 查看共享给我的听记 @@ -1678,9 +1678,9 @@ dws minutes upload cancel --session-id --format json | 操作 | 从返回中提取 | 用于 | |------|-------------|------| -| `list mine` | `taskUuid`、`nextToken` | get/update 的 --id；翻页时 --next-token | -| `list shared` | `taskUuid`、`nextToken` | get/update 的 --id；翻页时 --next-token | -| `list all` | `taskUuid`、`nextToken` | get/update 的 --id；翻页时 --next-token | +| `list mine` | `taskUuid`、`nextCursor` | get/update 的 --id；翻页时 --cursor | +| `list shared` | `taskUuid`、`nextCursor` | get/update 的 --id；翻页时 --cursor | +| `list all` | `taskUuid`、`nextCursor` | get/update 的 --id；翻页时 --cursor | | `get batch` | 各听记 `taskUuid` | 进一步查询详情 | | `get audio` | 音频/视频 OSS 地址 | 用 HTTP GET 下载录音文件 / 在浏览器播放 | | `record start` | `taskUuid`/`uuid` | record pause/resume/stop 的 --id | @@ -1841,7 +1841,7 @@ loop: - `record pause` / `record resume` / `record stop` 对应 `cmd=pause/resume/end`，需要传入 `--id`（映射 MCP 入参 `uuid`） - 如果用户传入听记 URL（格式: `https://shanji.dingtalk.com/app/transcribes/`），直接从路径末段提取 taskUuid 作为 `--id` 参数，无需再调用 list 查询 - `list mine`、`list shared`、`list all` 统一走 `list_by_keyword_and_time_range` 链路，通过 `belongingConditionId` 区分（`created` / `shared` / `noLimit`） -- 三个 list 命令均支持 `--max`、`--next-token` 分页及 `--query`、`--start`、`--end` 筛选 +- 三个 list 命令均支持 `--max`（=--limit）、`--cursor` 分页及 `--query`、`--start`、`--end` 筛选 - `list mine`、`list shared` 默认每页 20 条，`list all` 默认每页 10 条 - `get summary` 返回 AI 生成的结构化 Markdown 摘要 - `get transcription` 的 `--direction` 控制时间排序: 0=正序(默认), 1=倒序；当用户明确要求查看/分析转写原文时，默认自动翻页拉取全部原文（不需要用户手动说"拉第一页"），如果用户意图不是专门看原文（如查列表、看摘要），则不应主动调用此命令 @@ -1860,7 +1860,7 @@ loop: - 当用户提供关键词或时间范围时，必须使用 --query / --start / --end 在服务端筛选，严禁全量拉取后本地过滤。**严禁在 dws 命令后拼接 shell 管道做本地过滤**（如 `| grep "关键词"` / `| head -50` / `python -c "import json;..."` / `> /tmp/xxx.txt && grep ...`），这些写法在 Windows 沙箱里 100% 失败（`head`/`grep`/`wait` 不是 Windows 内置命令），即使在 macOS 上也会因 list 本身失败导致整个管道链路断掉。正确做法是始终使用 `--query` / `--start` / `--end` / `--max` 等 cli 内置参数在服务端完成筛选 - `dws minutes list` 后面**必须跟 `mine` / `shared` / `all` 子命令**，不能直接 `dws minutes list --start ... --end ...`（会报 `unknown flag: --start`）。正确写法：`dws minutes list mine --start ... --end ...` 或 `dws minutes list all --query "关键词" --start ... --end ...` - get transcription 翻页时，同一个 next-token 连续返回空 2 次即终止翻页，不再重试 -- **跨平台兼容性**：悟空运行环境可能是 Windows cmd / PowerShell / macOS bash，**严禁在 dws 命令中使用任何依赖特定 shell 的工具或管道**，包括但不限于：`| head`、`| grep`、`| tail`、`| wc`、`& wait`、`> %TEMP%\xxx`、`timeout /t 5`、`Start-Sleep`、`python -c "..."` 等。所有数据筛选、截断、过滤都必须通过 dws cli 自身的参数完成（`--query`/`--start`/`--end`/`--max`/`--next-token`） +- **跨平台兼容性**：悟空运行环境可能是 Windows cmd / PowerShell / macOS bash，**严禁在 dws 命令中使用任何依赖特定 shell 的工具或管道**，包括但不限于：`| head`、`| grep`、`| tail`、`| wc`、`& wait`、`> %TEMP%\xxx`、`timeout /t 5`、`Start-Sleep`、`python -c "..."` 等。所有数据筛选、截断、过滤都必须通过 dws cli 自身的参数完成（`--query`/`--start`/`--end`/`--max`/`--cursor`，get transcription 翻页用 `--next-token`） ### 错误恢复策略（AI 遇到以下错误时必须自动执行对应恢复动作） diff --git a/skills/mono/references/products/wiki.md b/skills/mono/references/products/wiki.md index 7c61c7b0..c990492d 100644 --- a/skills/mono/references/products/wiki.md +++ b/skills/mono/references/products/wiki.md @@ -302,7 +302,7 @@ Flags: - 用户说"复制知识库里的文档" → `node copy`（需 `--workspace` + `--node`） - 用户说"移动知识库里的文档" → `node move`（需 `--workspace` + `--node`） - 用户说"删除知识库里的文档/节点" → `node delete`（需 `--workspace` + `--node`） -- 用户说"把知识库分享给某人/给某人加入知识库/邀请进知识库" → `member add`（需 `--workspace` + `--user` + `--role`） +- 用户说"把知识库分享给某人/给某人加入知识库/邀请进知识库" → `member add`（需 `--workspace` + `--users` + `--role`） - 用户说"修改某人在知识库的权限/调整成员角色" → `member update` - 用户说"移除知识库成员/把某人从知识库移除/删除知识库成员" → `member remove`（需 `--workspace` + `--users`） - 用户说"知识库有哪些成员/查看知识库成员" → `member list` diff --git a/skills/multi/dingtalk-report/SKILL.md b/skills/multi/dingtalk-report/SKILL.md index 9458da6c..e5ab1707 100644 --- a/skills/multi/dingtalk-report/SKILL.md +++ b/skills/multi/dingtalk-report/SKILL.md @@ -35,17 +35,17 @@ metadata: | 用户说 | 命令 | |--------|------| | "今天收到的日志" | `python scripts/report_received_today.py` | -| "看日志模版" | `dws report template list` → `dws report template detail --name "<模版名>"` | -| "提交日报 / 周报（按模版）" | `dws report create --template-id --contents '[...]' | -| "我已发送的日志" | `dws report sent --start --end ` | -| "日志已读统计" | `dws report stats --report-id ` | +| "看日志模版" | `dws report template list` → `dws report template get --name "<模版名>"` | +| "提交日报 / 周报（按模版）" | `dws report entry submit --template-id --contents-file .json` | +| "我已发送的日志" | `dws report outbox list --start --end ` | +| "日志已读统计" | `dws report entry stats --report-id ` | | "生成日报 / 周报 / 月报 / 主题报告" | 见 [05-reporting.md](references/05-reporting.md) recipe | ## 日志查询硬约束 -- 查“收到的日志”必须用 `dws report list --start "" --end "" --cursor 0 --size 20 --format json`，并把“今天 / 最近 30 天”等时间词先展开成完整 ISO 起止时间。 -- 列表返回后，后续 `detail` / `stats` 必须复用同一个 `reportId`；不要重新挑选、猜测或改用标题。 -- 用户要正文时用 `dws report detail --report-id `；用户要已读/统计时用 `dws report stats --report-id `。 +- 查“收到的日志”必须用 `dws report inbox list --start "" --end "" --cursor 0 --size 20 --format json`，并把“今天 / 最近 30 天”等时间词先展开成完整 ISO 起止时间。 +- 列表返回后，后续 `entry get` / `entry stats` 必须复用同一个 `reportId`；不要重新挑选、猜测或改用标题。 +- 用户要正文时用 `dws report entry get --report-id `；用户要已读/统计时用 `dws report entry stats --report-id `。 ## 跨产品协作 diff --git a/skills/multi/dingtalk-report/references/05-reporting.md b/skills/multi/dingtalk-report/references/05-reporting.md index 4f8c3e96..08db7f1d 100644 --- a/skills/multi/dingtalk-report/references/05-reporting.md +++ b/skills/multi/dingtalk-report/references/05-reporting.md @@ -8,7 +8,7 @@ | query 中是否含强信号 | 选哪个 recipe | 默认值 | |---------------------|---------------|--------| -| 含「钉钉日志 / OA 周报 / 我的钉钉日志 / 日报模板 / 周报模板 / 提交日志 / 填模版」 | `submit-report`（走 dws report create） | — | +| 含「钉钉日志 / OA 周报 / 我的钉钉日志 / 日报模板 / 周报模板 / 提交日志 / 填模版」 | `submit-report`（走 dws report entry submit） | — | | 含「在线文档 / 写一篇文档 / 整理成文档 / 文档保存」 | `generate-*-report`（走 dws doc create） | — | | **无强信号**（如"写日报"、"写周报"、"整理本周工作"）| `generate-*-report`（走 dws doc create） | 默认 | @@ -21,9 +21,9 @@ | Recipe | 行动指南（固定路线） | |--------|-------------------| -| query-report | **0. 前置判定**：query 含「查日志 / 看日志 / 我发过的日志 / 收到的日志 / 日志详情」且语义指向钉钉日志 OA 应用？是 → 直接走 `dws report`；否 → 先按 doc/report 分歧澄清
1. 用户说「我发过 / 我创建」→ `report sent --cursor 0 --size 20 --format json`；用户说「收到 / 别人发给我」→ `report list --start "" --end "" --cursor 0 --size 20 --format json`（注意：`dws report inbox` 当前 CLI 未实现，禁止编造）
2. 时间 flag 只允许 `--start` / `--end`，禁止 `--start-date` / `--end-date` / `--date`；不要只传裸日期，必须展开完整 ISO；不要先查 `help`，不要预先登录；只有命令返回认证错误时才处理认证
3. 从列表返回中取 `reportId` 留给内部后续调用；如果用户已直接提供 `reportId`，跳过列表
4. 面向用户展示列表时必须基于 `result[]` 拼 Markdown 表：`日期 | 标题 | 发送人 | 状态 | 钉钉链接`；每条 `result[]` 都带这五个中文字段；不要把日志 ID 作为主列；已读状态字段缺失则不展示，不要编造
5. 用户要看正文时再执行 `report detail --report-id --format json`；用户要统计 / 已读情况时执行 `report stats --report-id --format json`
**不要把 list/sent 当正文接口**；查询正文必须补 `detail` | +| query-report | **0. 前置判定**：query 含「查日志 / 看日志 / 我发过的日志 / 收到的日志 / 日志详情」且语义指向钉钉日志 OA 应用？是 → 直接走 `dws report`；否 → 先按 doc/report 分歧澄清
1. 用户说「我发过 / 我创建」→ `report outbox list --cursor 0 --size 20 --format json`；用户说「收到 / 别人发给我」→ `report inbox list --start "" --end "" --cursor 0 --size 20 --format json`
2. 时间 flag 只允许 `--start` / `--end`，禁止 `--start-date` / `--end-date` / `--date`；不要只传裸日期，必须展开完整 ISO；不要先查 `help`，不要预先登录；只有命令返回认证错误时才处理认证
3. 从列表返回中取 `reportId` 留给内部后续调用；如果用户已直接提供 `reportId`，跳过列表
4. 面向用户展示列表时必须基于 `result[]` 拼 Markdown 表：`日期 | 标题 | 发送人 | 状态 | 钉钉链接`；每条 `result[]` 都带这五个中文字段；不要把日志 ID 作为主列；已读状态字段缺失则不展示，不要编造
5. 用户要看正文时再执行 `report entry get --report-id --format json`；用户要统计 / 已读情况时执行 `report entry stats --report-id --format json`
**不要把 inbox list/outbox list 当正文接口**；查询正文必须补 `entry get`
**不要再生成** `report list` / `report sent` / `report detail` / `report stats`（deprecated alias，仍能跑但会打 stderr 警告） | | generate-daily-report | 1. 按「多源并行采集」（见 `dws-shared/references/best_practices/_common/conventions.md`）执行（时间=今日）
2. 交叉汇总并把日报内容写入临时文件 `.md`（UTF-8，真实换行）
3. **创建文档**：`doc create --name "<日报名>" --content-file .md`（> 200KB 按 `dingtalk-doc/references/04-document.md` 的 write-doc 兜底走 create 空 → 循环 update） | | generate-weekly-report | 1. 按「多源并行采集」（见 `dws-shared/references/best_practices/_common/conventions.md`）执行（时间=本周）
2. 交叉对比并把周报内容写入临时文件 `.md`
3. **创建文档**：`doc create --name "<周报名>" --content-file .md`（兜底同上） | -| submit-report | **0. 前置判定**：query 含「钉钉日志 / OA 周报模板 / 我的钉钉日志」等强信号？是 → 继续；否 → 切换到 `generate-weekly-report` 或 `generate-daily-report`（走 dws doc）
1. 按「多源并行采集」（见 `dws-shared/references/best_practices/_common/conventions.md`）执行（时间=当日）
2. `report template list --format json` → 取 `report_template_id`
3. `report template detail --name "<模版名>" --format json` → 取 `result.report_template_fields[]`，每项含 `field_name`/`field_sort`/`field_type`
4. **把 contents 写入临时文件**（避免 shell 引号问题）：每项含 `key`/`sort`/`content`/`contentType`/`type` 五个字段，**严格映射** `field_name → key`、`field_sort → sort`、`field_type → type`，再填 `content` 与 `contentType`
5. `report create --template-id --contents '[...]' (或 echo "$json" | ... --contents -) --format json` → CLI 会在创建成功后自动反查详情并追加 `dingtalkOpenMarkdownLink` / `dingtalkOpenUrl` / `dingtalkOpenLink` 字段；取返回的 `reportId` 与钉钉打开链接
6. final reply 优先直接使用 `dingtalkOpenMarkdownLink`，让用户点击跳转钉钉客户端查看 / 修改；仅当 create 返回中缺少 `dingtalkOpenUrl` 时，才手动执行 `report detail --report-id --format json` 补取 `result.url`，再包装成 `[在钉钉中查看日志](result.url)`
**不要走 doc 写文档**；**禁止跳过 2/3 步**直接 create；**禁止把 raw `dingtalk://...` URL 直接粘到回复**，必须包成 markdown link | -| generate-monthly-report | 1. 按「多源并行采集」（见 `dws-shared/references/best_practices/_common/conventions.md`）执行（时间=当月）
2. `report sent --start "<月初ISO>" --end "<月末ISO>"` → 取当月已提交日志
3. 按周分段归纳并把月报内容写入临时文件 `.md`
4. **创建文档**：`doc create --name "<月报名>" --content-file .md`（兜底同上） | +| submit-report | **0. 前置判定**：query 含「钉钉日志 / OA 周报模板 / 我的钉钉日志」等强信号？是 → 继续；否 → 切换到 `generate-weekly-report` 或 `generate-daily-report`（走 dws doc）
1. 按「多源并行采集」（见 `dws-shared/references/best_practices/_common/conventions.md`）执行（时间=当日）
2. `report template list --format json` → 取 `report_template_id`
3. `report template get --name "<模版名>" --format json` → 取 `result.report_template_fields[]`，每项含 `field_name`/`field_sort`/`field_type`
4. **把 contents 写入临时文件**（避免 shell 引号问题）：每项含 `key`/`sort`/`content`/`contentType`/`type` 五个字段，**严格映射** `field_name → key`、`field_sort → sort`、`field_type → type`，再填 `content` 与 `contentType`
5. `report entry submit --template-id --contents-file .json --format json` → CLI 会在提交成功后自动反查详情并追加 `dingtalkOpenMarkdownLink` / `dingtalkOpenUrl` / `dingtalkOpenLink` 字段；取返回的 `reportId` 与钉钉打开链接
6. final reply 优先直接使用 `dingtalkOpenMarkdownLink`，让用户点击跳转钉钉客户端查看 / 修改；仅当 submit 返回中缺少 `dingtalkOpenUrl` 时，才手动执行 `report entry get --report-id --format json` 补取 `result.url`，再包装成 `[在钉钉中查看日志](result.url)`
**不要走 doc 写文档**；**禁止跳过 2/3 步**直接 submit；**禁止把 raw `dingtalk://...` URL 直接粘到回复**，必须包成 markdown link
**不要再生成** `report template detail` / `report create`（deprecated alias，仍能跑但会打 stderr 警告） | +| generate-monthly-report | 1. 按「多源并行采集」（见 `dws-shared/references/best_practices/_common/conventions.md`）执行（时间=当月）
2. `report outbox list --start "<月初ISO>" --end "<月末ISO>"` → 取当月已提交日志
3. 按周分段归纳并把月报内容写入临时文件 `.md`
4. **创建文档**：`doc create --name "<月报名>" --content-file .md`（兜底同上） | | generate-topic-report | 1. 提取主题关键词；推断时间范围（"最近"默认近 30 天）
2. 按「多源并行采集」（见 `dws-shared/references/best_practices/_common/conventions.md`）执行
3. 按时间线排列，交叉归纳核心结论/决策/行动项/未解决问题/演进脉络，并把内容写入临时文件 `.md`
4. **创建文档**：`doc create --name "<报告名>" --content-file .md`（兜底同上） |