weaver-work-cli 0.1.4 → 0.1.5

package/skills/weaver-e10-yimiaoban/references/msg-write.md

@@ -0,0 +1,64 @@
+# 发送消息 / 撤回 / 群消息置顶（写）
+
+## 何时使用
+
+给某人/某群发文本、图片或文件消息；撤回自己 2 分钟内的消息；群消息置顶/取消置顶。全部是两段式写操作：
+
+| operation 对 | 动作 |
+| --- | --- |
+| `yimiaoban.msg.send.single.prepare` / `.apply` | 发送单聊消息 |
+| `yimiaoban.msg.send.group.prepare` / `.apply` | 发送群聊消息 |
+| `yimiaoban.msg.withdraw.prepare` / `.apply` | 撤回消息（`type`=single/group） |
+| `yimiaoban.msg.top.set.prepare` / `.apply` | 群消息置顶/取消（`type`:1 置顶 2 取消，或 `cancel:true`） |
+
+## 输入要点（prepare 阶段）
+
+- 发送单聊：`toUid`+`toCid`（接收人，先用 `person.resolve` 解析）；群聊：`groupId`。文本用 `txt`；图片用本地路径 `img`；文件用本地路径 `file`（CLI 会先上传到 E10 文件服务再发送，`img`/`file` 与 `txt` 可组合）。
+- **全空白文本（空格/换行）不算内容，会被拒绝（`content_required`）**；`img` 与 `file` 一次只能传一种（`content_conflict`）。
+- 撤回：`type`（single/group）+ `msgid`（消息 `ser_msgid`）；单聊还需 `toUid`/`toCid`，群聊还需 `groupId`。**只能撤回本人 2 分钟内发出的消息**；回包带 `time_out` 时会返回 `withdrawInterval`（如"2 分钟"），超时（1505）错误里也会带上该时限。
+- 置顶：`groupId` + `msgid` + `type`（1 置顶 / 2 取消）。
+- 本地文件路径：绝对路径或相对 CLI 运行目录的路径均可；上传前必须先与用户确认该文件内容可能进入大模型上下文并被发送到 E10 文件服务。
+
+## 命令
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json yimiaoban run yimiaoban.msg.send.group.prepare --input-json '{"groupId":"1788334281700000004","txt":"下午 3 点评审，请准时参加"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json yimiaoban run yimiaoban.msg.send.group.prepare --input-json '{"groupId":"1788334281700000004","txt":"下午 3 点评审，请准时参加"}'
+```
+
+prepare 返回 `data.summary`（动作/目标/内容预览）与 `data.continuation`。向用户确认后执行 apply：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json yimiaoban run yimiaoban.msg.send.group.apply --input-json '{"confirm":true,"continuation":"<prepare 返回的 continuation>"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json yimiaoban run yimiaoban.msg.send.group.apply --input-json '{"confirm":true,"continuation":"<prepare 返回的 continuation>"}'
+```
+
+## 注意
+
+- apply 只接受 prepare 签发的 continuation；**不得手工拼 token**，不得复用/跨操作使用。超过 10 分钟或切换账号/租户后 continuation 失效，需重新 prepare。
+- `apply` 里不要重复传业务参数（发送目标/内容以 prepare 快照为准）；重复调用 prepare 后必须用**最新** continuation。
+- 图片/文件发送成功与否以 apply 响应为准；若响应为 `partial`/`write_uncertain`，停止并做只读回查（如拉群最新消息确认是否已发出），**不要自动重发**——否则可能重复发送。
+- 撤回超时或非本人消息会业务失败（1505/1506/1507），按错误信息告知用户，不重试。
+- 普通请求 15 秒超时即失败，不重试；上传按 15 秒（预检）/60 秒（实传）执行。
+- CLI 固定使用各 operation 的接口路径，**不提供自定义接口路径参数**（避免绕过 operation 契约）；遇到异常路径需求请改用 `schema` 中登记的对应能力。
+
+## 失败处理
+
+- `confirmation required`：说明没有带 `confirm:true`，重新按协议走 prepare→apply。
+- `continuation_expired`/`context_mismatch`：重新 prepare。
+- `target_changed`：prepare 之后目标/内容被改动过（指纹不一致），重新 prepare。
+- 消息发出但不确定结果：只读回查群/单聊最新消息确认，不盲目重试。

package/skills/weaver-e10-yimiaoban/references/person.md

@@ -0,0 +1,44 @@
+# 人员解析
+
+## 何时使用
+
+发消息前确定接收人 uid/cid、把消息/群成员里的 uid 翻译成姓名、查某人的 uid 和部门。覆盖：
+
+| operation | 用途 |
+| --- | --- |
+| `yimiaoban.person.resolve` | 按姓名/工号/手机/邮箱**模糊**查询在职员工 → uid/cid/部门 |
+| `yimiaoban.person.resolveByIds` | 按 uid 批量解析 → 姓名/部门/岗位/cid（一次最多 100，超出自动分批） |
+
+## 输入要点
+
+- `person.resolve` 的 `name` 是模糊关键字，**多人命中必须列出候选让用户选**，不得自动取第一条。
+- `person.resolveByIds` 入参字段是 **`ids`**（uid 列表，不要写成 `uids`）；uid 是 uint64，必须按字符串传；一次最多 100，超出自会分批（CLI 保证）。
+- 消歧展示、未匹配处理、上下文传递契约见 [`field-resolution.md`](field-resolution.md)。
+
+## 命令
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json yimiaoban run yimiaoban.person.resolve --input-json '{"name":"初四十九"}'
+weaver-work-cli --json yimiaoban run yimiaoban.person.resolveByIds --input-json '{"ids":["100234","100235"]}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json yimiaoban run yimiaoban.person.resolve --input-json '{"name":"初四十九"}'
+weaver-work-cli --json yimiaoban run yimiaoban.person.resolveByIds --input-json '{"ids":["100234","100235"]}'
+```
+
+## 注意
+
+- **人名解析一律走 hrm**（`/api/hrm/common/getEmployeeByIds`），禁止使用 IM 群成员接口返回的 `name` 字段展示姓名，也不得本地拼表。
+- 返回的 uid/cid 直接用于发消息/拉单聊（作为 `fromUid`/`toUid` 等）。
+- 模糊命中多人时按 `person.resolve` 返回列表向用户确认；重名场景以用户指定的工号/部门为准确认。
+- **未匹配（`total=0`）直接告知用户姓名可能有误并停止**，禁止翻历史会话/相似名模糊搜索去猜人。
+
+## 失败处理
+
+- 无命中：`data.employees` 为空，告知用户换关键字（可尝试工号/手机号）。
+- 只读操作，安全；认证失败参照共享规则。

package/skills/weaver-e10-yimiaoban/references/safety-boundaries.md

@@ -0,0 +1,61 @@
+# 易秒办红线与边界
+
+本文件汇总易秒办业务域**不可违反**的红线，供写操作/消息展示前自查。写协议（prepare→apply、continuation、停止条件）见 [`msg-write.md`](msg-write.md)、[`ding-write.md`](ding-write.md)、[`group-write.md`](group-write.md)；共享层通用规则见 `weaver-work-cli-shared`。
+
+## 红线（违规 = 必须停下说明，不绕过）
+
+1. **请求体禁止操作人字段**：任何 operation 的输入都不接受 `user`/`sender`/`creator`/`operator` 等操作人字段；操作者由会话 `eteamsid` 识别。不要在入参里补这些字段，CLI 会直接拒绝（`forbidden_keys`）。
+2. **人名一律走 hrm**：姓名解析（消息发送者、群成员、阅读人、@提及）只认 `yimiaoban.person.resolve`/`resolveByIds`（底层 `/api/hrm/common/getEmployeeByIds`）或消息行里的 hrm 姓名；**禁止用 IM 群成员接口返回的 `name` 字段**展示姓名，禁止本地猜测/拼表。
+3. **uid/cid/群 id 非 0、按字符串传输**：uint64 必须字符串化；`0`、空串直接拒绝。
+4. **不本地过滤、不隐式全量**：搜索/筛选一律服务端完成（`mask`/`cond`/`type` 等）；拉历史/会话/系统消息默认单页，需要更多用返回锚点显式请求，**未经用户确认不得自动循环翻页拉全部**。
+5. **时间范围查询转 id 区间**：单聊/群聊历史不支持服务端时间过滤，CLI 把 `from/to` 换算为消息 id 区间分页；跨天/全量拉取必须先与用户确认范围。
+6. **消息展示完整不截断**：拉到的 `content` 完整展示，无论多长；不得自行截断/省略/改写正文。渲染表格时转义 `|`、保留换行提示（⏎）、媒体显示为 `[图片]/[视频]/[文件]名称` 且预览/下载链接保持可点击，必达消息保留 `[必达]` 前缀。
+7. **写操作只认 CLI 签发的 continuation**：不手工拼、不复用、不跨操作；prepare 后 10 分钟有效；`apply` 不自动重试。
+8. **禁止发送空白消息**：`txt` 为空或全空白（空格/换行）不算内容，CLI 直接返回 `content_required`，需提示用户提供非空内容。
+9. **超时即失败**：普通请求超过 15 秒即视为失败（上传 15/60 秒），不再重试，向用户说明失败原因；禁止无限重试或静默换接口。
+10. **未匹配不猜测**：人员/群未匹配（`total=0`/空）时直接告知「未找到『XX』，请确认名称是否正确」并停止。🔴 禁止翻历史会话、拉会话列表、按相似名/部分名模糊搜索去猜人，也不要推荐"可能的人"。
+11. **禁止拉全量获取数量**：不允许通过逐页拉全量统计消息总数/会话总数等；触发此类需求（如"一共有多少条消息"）直接回复「无法统计总数，功能暂时不支持」，不提供逐页全量变通。数量只基于当页返回（如当页 `total=N`）。
+12. **数据对不上不得自行猜测**：接口返回与预期不符（返回 0 条/条数不符/字段缺失）时，按下面模板先给证据再让用户选方向；禁止自作主张换参数反复探测、换同类型接口或编造数据。
+
+## 写链停止条件
+
+遇到以下任一情况立即停止写流程，先向用户说明再做只读回查，不静默重试：
+
+- 返回 `partial` / `write_uncertain`（结果未知）。
+- 网络中断 / 超时（可安全重试的只有 prepare 这类纯只读准备）。
+- `apply` 已发出但响应丢失。
+- 回查手段：单聊/群聊用 `msg.sync.single`/`msg.sync.group`（`latest:true`）看是否已发出；群状态用 `group.info`/`group.users`；必达可用系统消息或群置顶辅助确认。
+
+## 已知禁用边界
+
+- 不实现"已读回执的主动标记/已处理系统消息"这类状态回写（CLI 未暴露，避免伪装处理）。
+- 不支持删除/清空消息、编辑已发消息：只能撤回**本人**消息（`msg.withdraw`，有时限）。
+- 不支持建非普通群（部门群/全员群/事项群等）：`group.create` 只建普通群（type=0）。
+- 不支持统计消息总数/会话总数（见红线 11），也不做消息统计分析/报表。
+- 不支持定时推送、机器人托管、自动回复；跨平台 IM（企业微信/钉钉/邮件）请改用对应技能，不代为调用。
+- 不支持"按接口未支持的字段做本地过滤"（免打扰/未读/发送人等）：接口不支持就如实告知，引导改用原生参数（`flag`/`deal`/`type` 等）。
+- 移动端打卡、定位、设备凭证等与本域无关，不在此列。
+- `schema` 之外的接口路径一律不可直接调用；禁止 Agent 绕过 CLI 拼 `/api/em/msg/executeIm/...` 等原始请求。
+
+## 数据对不上提问模板（配合红线 12）
+
+```
+已确认事实：<接口返回码、条数、关键字段>（如「querySysMsgInfo group=110 返回 code=0，0 条」）
+差异：接口返回 <X>，会话/预期显示 <Y>（如「会话列表显示未读 58 条」）
+可能方向（需你选择，我不替你决定）：A <方向1> B <方向2> C <方向3>
+```
+
+## 常见错误码速查
+
+| 码/type | 含义 | 处理 |
+| --- | --- | --- |
+| `1303` | 无聊天记录 | 按成功空列表（看 `emptyReason`），不报错 |
+| `1209` / 群不存在 | 群不可读/已解散 | 告知用户 |
+| `forbidden_keys` | 传了操作人字段 | 去掉后重试（说明红线） |
+| `context_mismatch` / `continuation_expired` | 会话/租户或超时变化 | 重新 prepare |
+| `target_changed` | prepare 后目标/内容指纹变化 | 重新 prepare |
+| `members_resolve_failed` | 成员 hrm 解析失败 | 列失败项，问是否 `removeFailed:true` |
+| `source_not_found` / `source_invalid` / `unread_empty` | 转必达源消息缺失/无未读人员 | 说明后由用户决定是否改发全员 |
+| `content_required` / `content_conflict` | 内容为空或同时传了 img+file | 补非空内容/一次只发一种媒体 |
+| `output_exists` / `output_parent_missing` | `file.download` 目标已存在/父目录不存在 | 换路径或先建目录，不覆盖既有文件 |
+| 其他码（群 12xx / 消息 15xx / 数据 13xx） | — | 对照 [`error-codes.md`](error-codes.md) 解释并告知用户 |

package/skills/weaver-e10-yimiaoban/references/session-sysmsg.md

@@ -0,0 +1,47 @@
+# 会话列表与系统消息
+
+## 何时使用
+
+用户要"看我的会话/最近聊天"（单聊、群聊、系统消息入口）；查"系统消息/流程待办通知/审批提醒"等 IM 系统消息。
+
+| operation | 用途 |
+| --- | --- |
+| `yimiaoban.session.list` | 拉当前用户会话列表（单聊/群聊/系统消息，名称与副标题已解析） |
+| `yimiaoban.sysmsg.groupSearch` | 按名称搜系统消息分组/类型配置（供 query 使用） |
+| `yimiaoban.sysmsg.typeSync` | 按 gids/tids 拉系统消息分组/类型配置 |
+| `yimiaoban.sysmsg.query` | 拉系统消息（流程/任务/公文等），支持阅读维度/处理状态/时间范围/单页倒序 |
+
+## 输入要点
+
+- `session.list`：`num` 默认 20 上限 50；`flag` 0 up+down / 1 up / 2 down（默认 2，从最新拉）；`msgid` 锚点实现翻页（取上页边界消息 id）；`type` 只过滤该 session_type；`around` 表示锚点附近上下各半。
+- 会话返回带 `sessionTypeName`（单聊/群聊/系统消息）、`name`（单聊=对方姓名、群聊=群名、系统=分组名）、`unread`（来自 `unread_count`）、`unreadLabel`（免打扰会话显示 `N（免打扰）`）、`time`（会话更新时间）、`subtitle`（发送者：最近消息内容）、`lastMsgid`（下一页锚点 `nextMsgid`）。
+- `sysmsg.groupSearch` 用名称找分组/类型（流程/待办/公告等），返回 gid/tid 供 `typeSync` 与 `query`。
+- `sysmsg.query`：**必填 `group`（系统分组 id，来自 `groupSearch`/会话列表）**，可选 `type`（消息类型 id）、`flag`（0 不分已读未读/1 已读/2 未读）、`deal`（0 全部/1 未处理/2 已处理）、`num`（默认 20、上限 50）、时间范围 `from`/`to`/`latest`、显式 `start`/`end`。系统消息"已读/处理"类状态更新在需要时由 Agent 引导用户到易秒办处理，CLI 不伪装处理。
+
+## 命令
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json yimiaoban run yimiaoban.session.list --input-json '{"num":20}'
+weaver-work-cli --json yimiaoban run yimiaoban.sysmsg.query --input-json '{"group":110,"num":20,"flag":2}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json yimiaoban run yimiaoban.session.list --input-json '{"num":20}'
+weaver-work-cli --json yimiaoban run yimiaoban.sysmsg.query --input-json '{"group":110,"num":20,"flag":2}'
+```
+
+## 输出处理
+
+- 会话列表渲染：单聊/群聊显示名称（走 hrm/群信息），系统消息显示分组名；副标题按类型给最近消息预览，媒体会话显示 `[图片]xxx.png`/`[文件]xxx.pdf` 形式，必达消息保留 `[必达]` 前缀。
+- 列表结果大时按共享规则汇总（只给关键列 + 总数），不要整表倾倒；按需翻页。
+- `sysmsg.query` 返回 `dealMode`：`true` 表示该分组以**处理状态**为准（`statusLabel` = 已处理/未处理），`false` 表示以**阅读状态**为准（已读/未读）；`title` 为系统消息标题（如流程标题），展示时标题一行、内容一行。
+
+## 失败处理
+
+- `sysmsg.*` 的分组/类型 id 必须来自 `groupSearch`/`typeSync` 返回，禁止编造 gid/tid。
+- 会话/系统消息为空：返回空列表，正常。
+- 认证/上下文错误参照共享规则。