weaver-work-cli 0.1.2 → 0.1.5

package/skills/weaver-e10-plan/references/plan-report-query.md

@@ -0,0 +1,154 @@
+# 查询报告详情、报告列表与评论
+
+## 何时使用
+
+- 用户要看某份报告的内容（「看看小A 2026年第33周的报告」「本周我交报告了吗」）；
+- 用户要看共享给自己的报告、下属的报告、团队成员的报告（「共享给我的报告」「下属这周交了吗」）；
+- 用户在查看报告详情后要求查看评论内容。
+
+对应 operation：`plan.report.get`、`plan.report.page`、`plan.comment.list`。
+
+## 输入要点
+
+### plan.report.get
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 报告 id；与周期参数二选一，给了 `id` 就忽略周期参数 |
+| `year` | 报告年份；缺省取本年 |
+| `type` | `week` / `month` / `season` / `halfYear` / `year` |
+| `serialNumber` | 报告周期（正整数） |
+| `creatorUserId` | 报告创建人 id；缺省为当前登录人。**禁止传 userId 之外的 ID 形态，需由 weaver-e10-hrm 解析姓名** |
+| `withComments` | 标准版链路下是否同时查询评论总条数，默认 `true` |
+
+按周期查询时 `type` + `serialNumber` 必填，`year` 缺省取本年；`creatorUserId` 缺省为当前登录人。CLI 内部按周期查询为标准版链路要求，缺省值会自动补齐。
+
+### plan.report.page
+
+| 字段 | 说明 |
+| --- | --- |
+| `scope` | `share`（共享给我的，默认）/ `mine`（我自己及他人共享给我的，eb 链路按创建人筛选） |
+| `unreadOnly` | 仅看未读（标准版专属，eb 链路不支持） |
+| `year` / `type` / `serialNumber` | 报告筛选条件 |
+| `creatorUserId` | 报告创建人 id（eb 链路支持；标准版分页接口不支持按创建人筛选，会返回警告） |
+| `onlyIncludeSubs` | 是否只包含下属（标准版专属） |
+| `pageNo` / `pageSize` | 默认 1 / 10，`pageSize` 最大 100；不自动翻页 |
+
+### plan.comment.list
+
+| 字段 | 说明 |
+| --- | --- |
+| `reportId` | 报告 id（必填） |
+| `pageNo` / `pageSize` | 默认 1 / 10 |
+
+## 命令
+
+查询某份报告（按周期，本周周报）：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json plan run plan.report.get --input-json '{"year":2026,"type":"week","serialNumber":36}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json plan run plan.report.get --input-json '{"year":2026,"type":"week","serialNumber":36}'
+```
+
+按报告 id 查询：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json plan run plan.report.get --input-json '{"id":"PLACEHOLDER_REPORT_ID"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json plan run plan.report.get --input-json '{"id":"PLACEHOLDER_REPORT_ID"}'
+```
+
+分页查询共享给我的报告：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json plan run plan.report.page --input-json '{"pageNo":1,"pageSize":10}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json plan run plan.report.page --input-json '{"pageNo":1,"pageSize":10}'
+```
+
+只查下属、只看未读（标准版链路）：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json plan run plan.report.page --input-json '{"unreadOnly":true,"onlyIncludeSubs":true,"pageNo":1,"pageSize":20}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json plan run plan.report.page --input-json '{"unreadOnly":true,"onlyIncludeSubs":true,"pageNo":1,"pageSize":20}'
+```
+
+查看评论内容（仅标准版链路）：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json plan run plan.comment.list --input-json '{"reportId":"PLACEHOLDER_REPORT_ID","pageNo":1,"pageSize":10}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json plan run plan.comment.list --input-json '{"reportId":"PLACEHOLDER_REPORT_ID","pageNo":1,"pageSize":10}'
+```
+
+## 输出处理
+
+### plan.report.get
+
+- `exists`：报告是否存在。`false` 表示该人员该周期没有报告（用于判断是否提交）。
+- `report`：统一的业务报告结构（`reportId` / `title` / `content` / `summary` / `plans` / `year` / `type` / `typeLabel` / `serialNumber` / `postStatus` / `postStatusLabel` / `postTime` / `postTimeStatus` / `creator`）。
+- `detailUrl`：可直接跳转的报告详情页链接，必须呈现给用户。
+- `commentCount` / `commentHint`：仅在**标准版链路且评论总条数大于 0** 时出现。
+
+### 评论处理规则（查询单份报告详情时生效）
+
+1. 评论总条数 = 0：只返回报告详情，**完全忽略评论模块**，不输出任何评论相关文字。
+2. 评论总条数 > 0：返回报告详情，并附加提示「该报告下共有 {N} 条评论，是否需要查看评论内容？」，**禁止直接输出评论内容**。
+3. 只有收到用户明确的查看评论类指令后，才调用 `plan.comment.list` 展示全部评论详情。
+
+### plan.report.page
+
+`rows` 中每行都是统一业务报告结构，并带 `detailUrl`。必须用表格呈现，固定列：
+
+| 报告名称 | 报告创建人名称 | 发布时间 |
+| --- | --- | --- |
+
+- 报告名称渲染为指向 `detailUrl` 的可点击链接。
+- `count` 为本页返回行数；`pageSize` 最大 100，不做自动翻页。
+- `warnings` 非空时要向用户简要说明（例如标准版链路忽略 `creatorUserId`）。
+
+## 注意
+
+- 「某某某的报告」需要先由 weaver-e10-hrm skill 把姓名解析为人员 ID，再作为 `creatorUserId` 传入；禁止把姓名直接当 ID 传。
+- 标准版链路的报告列表接口语义是「共享给我的报告」，它不能按创建人过滤；需要按人筛选时改用 eb 链路或按 `plan.report.get` 精确查询。
+- eb 链路未提供报告评论接口，`plan.comment.list` 会返回 `policy/link_unsupported`；此时如实告知用户该链路无法查询评论。
+- 不要在只读查询场景调用业务模块采集数据。
+
+## 失败处理
+
+- `not_found`：目标报告不存在。按周期查询时 `exists:false` 是正常结果，不是错误。
+- `validation/type_invalid` / `validation/serial_number_invalid` / `validation/year_invalid`：入参不合法，按提示修正后重试一次。
+- `policy/link_unsupported`：该能力在当前链路不可用，按 `message` 说明告知用户。
+- `authentication` / `session_expired`：先确认 E10 登录域名再执行 `weaver-work-cli auth login`。

package/skills/weaver-e10-plan/references/plan-report-remind.md

@@ -0,0 +1,104 @@
+# 发送报告提交提醒
+
+## 何时使用
+
+- 查询发现部分人员在指定周期没有报告，用户确认需要提醒时；
+- 用户直接要求「提醒某某交报告」「催一下团队交周报」。
+
+对应 operation：`plan.report.remind.prepare` → `plan.report.remind.apply`（**仅标准版链路**）。
+
+## 触发前提
+
+1. 先用 `plan.report.get` 按周期确认目标人员在该周期确实没有报告（逐人确认，缺省创建人参数需替换为目标人员 ID）。
+2. 把「哪些人缺少该周期报告」摘要给用户，并询问 **是否需要向提交人发送提交提醒**。
+3. 用户明确确认后，才进入 `prepare → apply`。
+
+不要未经确认就批量发送提醒。
+
+## 输入要点
+
+| 字段 | 说明 |
+| --- | --- |
+| `personIds` | 需要提醒的人员 ID（`["1001","1002"]` 数组或 `"1001,1002"` 英文逗号拼接字符串）。**必须由 weaver-e10-hrm 解析姓名得到真实人员 ID，禁止传姓名** |
+| `year` | 报告年份；缺省取本年 |
+| `type` | `week` / `month` / `season` / `halfYear` / `year`（必填） |
+| `serialNumber` | 报告周期（必填） |
+| `content` | 提醒文案；缺省按周期生成默认文案 |
+
+## 默认提醒文案
+
+用户未指定文案时使用动态默认文案，年份与周期随实际条件替换：
+
+| 报告类型 | 默认文案 |
+| --- | --- |
+| 周报 | 请提交{年份}年第{N}周的报告 |
+| 月报 | 请提交{年份}年{N}月的报告 |
+| 季报 | 请提交{年份}年第{N}季度的报告 |
+| 年中报告 | 请提交{年份}年年中报告 |
+| 年报 | 请提交{年份}年年度报告 |
+
+## 命令
+
+准备发送（含默认文案）：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json plan run plan.report.remind.prepare --input-json '{"personIds":["PLACEHOLDER_PERSON_ID"],"year":2026,"type":"week","serialNumber":36}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json plan run plan.report.remind.prepare --input-json '{"personIds":["PLACEHOLDER_PERSON_ID"],"year":2026,"type":"week","serialNumber":36}'
+```
+
+指定文案：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json plan run plan.report.remind.prepare --input-json '{"personIds":"PLACEHOLDER_PERSON_ID,PLACEHOLDER_PERSON_ID_2","type":"month","serialNumber":9,"content":"请在今天 18:00 前提交9月月报"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json plan run plan.report.remind.prepare --input-json '{"personIds":"PLACEHOLDER_PERSON_ID,PLACEHOLDER_PERSON_ID_2","type":"month","serialNumber":9,"content":"请在今天 18:00 前提交9月月报"}'
+```
+
+用户确认后发送：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json plan run plan.report.remind.apply --input-json '{"confirm":true,"continuation":"PLACEHOLDER_CONTINUATION"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json plan run plan.report.remind.apply --input-json '{"confirm":true,"continuation":"PLACEHOLDER_CONTINUATION"}'
+```
+
+## 输出处理
+
+`prepare` 返回 `preview`：`personIds`（人员 ID 列表）、`targets`（年份/类型/周期）、`content`（实际文案）、`messageEventCode`（固定 14）以及 `continuation`。
+
+必须把「提醒对象 + 周期 + 实际文案」摘要给用户后再执行 `apply`。
+
+`apply` 返回 `status: COMPLETE` 与 `personIds`、`content`。
+
+## 注意
+
+- 人员 ID 必须来自 weaver-e10-hrm 的 `id` / `employeeId`，**禁止使用 `userId`，禁止直接传姓名**。
+- 提醒接口为标准版链路专属；eb 链路返回 `policy/link_unsupported`，如实告知用户当前链路无法发送提交提醒。
+- 提醒属于对外发送动作，必须在用户明确确认后才 `apply`。
+
+## 失败处理
+
+- `policy/link_unsupported`：当前租户走 eb 链路，无提交提醒接口。
+- `validation/ids_invalid` / `ids_required`：人员 ID 不合法或为空。
+- `confirmation/required`：未取得用户确认。
+- `partial` / `write_uncertain`：提醒是否已发送不确定，**禁止自动重试**，先向用户说明并询问是否重发。
+- `api/business_error`：接口返回业务失败，按 `error.message` 说明。

package/skills/weaver-e10-plan/references/plan-report-write.md

@@ -0,0 +1,162 @@
+# 新建 / 修改 / 发布 / 撤回报告
+
+## 何时使用
+
+- 用户明确要求新建、修改、发布、撤回某个周期的报告；
+- A 链路汇总完成、用户确认「生成对应周期的报告」后，创建报告；
+- 用户已确认要报告但还没创建草稿，又要直接发布（先创建，再发布）。
+
+这些 operation 全部是 `prepare → apply` 写入链，必须先取得用户明确确认。
+
+## 输入要点
+
+### 新建 `plan.report.create.prepare` / `.apply`
+
+| 字段 | 说明 |
+| --- | --- |
+| `content` | 工作成效（支持 HTML 片段） |
+| `summary` | 总结心得 |
+| `plans` | 计划内容 |
+| `year` | 报告年份；缺省取本年 |
+| `type` | `week` / `month` / `season` / `halfYear` / `year`（必填） |
+| `serialNumber` | 报告周期（必填，正整数） |
+| `userName` | 当前登录人姓名，eb 链路自动生成报告名称时必填（由 weaver-e10-hrm 解析） |
+| `title` | 报告名称，直接指定时优先于自动生成 |
+
+- `content` / `summary` / `plans` 至少提供一个。
+- eb 链路创建时发布状态固定为草稿（`0`），不允许为空或其它状态；报告名称按「{姓名}{年份}年第{N}周的报告」（周报）等规则动态生成。
+- 标准版链路的报告名称由服务端生成并返回，无需传 `title` / `userName`。
+
+### 修改 `plan.report.update.prepare` / `.apply`
+
+用 `id` 或 `year` + `type` + `serialNumber`（+ `creatorUserId`）定位报告，再传要更新的 `content` / `summary` / `plans`（至少一个）。`prepare` 会先查当前内容并给出 before/after 差异；未传的字段保持原值。
+
+### 发布 `plan.report.publish.prepare` / `.apply`
+
+用 `id` 或周期参数定位报告。`prepare` 会校验报告存在且当前不是「已发布」；若还没创建草稿，先走新建流程。
+
+### 撤回 `plan.report.withdraw.prepare` / `.apply`
+
+用 `id` 或周期参数定位报告，`prepare` 会校验当前状态为「已发布（1）」。**仅标准版链路支持**：eb 链路的撤回是 ESB 动作流「eb撤回报告」，源资料未提供动作流唯一标识，CLI 返回 `policy/link_unsupported`，需要改用 weaver-e10-customesb-execute skill 执行同名动作流。
+
+## 命令
+
+### 新建（先 prepare）
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json plan run plan.report.create.prepare --input-json '{"type":"week","serialNumber":36,"content":"<p>完成A模块联调</p>","summary":"<p>节奏可控</p>","plans":"<p>推进B模块</p>"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json plan run plan.report.create.prepare --input-json '{"type":"week","serialNumber":36,"content":"<p>完成A模块联调</p>","summary":"<p>节奏可控</p>","plans":"<p>推进B模块</p>"}'
+```
+
+用户确认后 apply（`continuation` 用原样回传）：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json plan run plan.report.create.apply --input-json '{"confirm":true,"continuation":"PLACEHOLDER_CONTINUATION"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json plan run plan.report.create.apply --input-json '{"confirm":true,"continuation":"PLACEHOLDER_CONTINUATION"}'
+```
+
+### 修改
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json plan run plan.report.update.prepare --input-json '{"type":"week","serialNumber":36,"plans":"<p>下周三完成B模块验收</p>"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json plan run plan.report.update.prepare --input-json '{"type":"week","serialNumber":36,"plans":"<p>下周三完成B模块验收</p>"}'
+```
+
+### 发布
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json plan run plan.report.publish.prepare --input-json '{"year":2026,"type":"week","serialNumber":36}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json plan run plan.report.publish.prepare --input-json '{"year":2026,"type":"week","serialNumber":36}'
+```
+
+### 撤回
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json plan run plan.report.withdraw.prepare --input-json '{"year":2026,"type":"week","serialNumber":36}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json plan run plan.report.withdraw.prepare --input-json '{"year":2026,"type":"week","serialNumber":36}'
+```
+
+复杂或多行内容（例如大段 HTML 报告正文）建议写入 UTF-8 JSON 文件后用 `--input <path>`：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json plan run plan.report.create.prepare --input "C:\path\to\plan-create.json"
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json plan run plan.report.create.prepare --input "/path/to/plan-create.json"
+```
+
+## 输出处理
+
+`*.prepare` 返回：
+
+- `status`：`AWAITING_CONFIRMATION`（可继续确认执行）或 `ALREADY_EXISTS`（该周期报告已存在，不签发 continuation）。
+- `preview`：将要写入的业务内容（新建为完整内容，修改为 `before` / `after` / `changedFields`）。
+- `continuation` + `expiresInSeconds`：确认凭据，默认 10 分钟有效。
+- `link`：本次生效的链路（`standard` / `eb`）。
+
+`*.apply` 返回：
+
+- `status: COMPLETE`；
+- `reportId`（新建时返回新建报告 id）、`detailUrl`（必须呈现为可点击链接）。
+
+## 注意
+
+- **重复创建防护**：`plan.report.create.prepare` 会按周期（年份 + 类型 + 周期 + 当前登录人）先查重。返回 `status: ALREADY_EXISTS` 时**禁止**直接创建，必须先询问用户是否改为编辑已有报告。
+- **先草稿后发布**：用户要求直接发布但还没有草稿时，先走新建（prepare→apply），再走发布（prepare→apply）。
+- **判断是否已提交**只能通过 `plan.report.get` 按周期查询，不要用列表接口猜。
+- **禁止出现数据库英文字段名**：创建出的报告内容与给用户的回复中，不要出现 `content` / `f_content` / `summary` / `f_summary` / `plans` / `f_plans` / `year` / `f_year` / `type` / `f_type` / `serial_number` / `f_serial_number` 等字段名。CLI 输入输出均为业务字段，直接使用即可。
+- 涉及「让谁看/共享范围」「按上级或部门层级」等报告名称前缀信息，标准版由服务端处理；不要手工拼报告名称。
+- 报告正文可能包含大段 HTML，属于业务数据处理，写入前必须在 `prepare` 预览里让用户确认内容。
+
+## 失败处理
+
+- `confirmation/required`：没有传 `confirm=true`。必须取得用户明确确认后再调用。
+- `validation/continuation_invalid` / `continuation_mismatch` / `continuation_expired`：continuation 不合法、串用或过期，重新执行 `prepare`。
+- `validation/context_mismatch` / `link_changed`：租户或登录账号变化、链路变化，重新执行 `prepare`。
+- `validation/report_exists`：并发或状态变化导致重复。停止创建，改为询问用户是否编辑。
+- `validation/not_found`：目标报告不存在；发布/撤回/修改前先创建。
+- `validation/already_published`：已发布，无需重复发布。
+- `validation/not_published`：不是已发布状态，无法撤回。
+- `validation/userName_required`：eb 链路上未提供报告名称与姓名，先由 weaver-e10-hrm 解析当前登录人姓名后重试。
+- `policy/link_unsupported`：该能力在当前链路不可用（eb 撤回），按 `message` 给出的替代路径处理。
+- `partial` / `write_uncertain`：写请求已发出但结果不确定。**立即停止，禁止自动重试**；先用 `plan.report.get` 做一次只读回查，再向用户说明并让用户决定。