weaver-work-cli 0.1.1 → 0.1.4

package/skills/weaver-e10-plan/references/plan-overview-and-routing.md

@@ -0,0 +1,138 @@
+# 意图判定、版本路由与通用规则
+
+## 何时使用
+
+任何与「报告 / 周报 / 月报 / 季报 / 年报 / 年中报告」相关的请求，先读本 reference 完成意图判定和链路判定，再按需读取其它 reference。
+
+## 一、意图判定（最高优先级）
+
+自上而下命中即止，命中后不再二次询问。
+
+### 1. B 链路（查询与管理已有报告）——禁止采集业务数据
+
+消息中出现以下任一信号即走 B：
+
+`查看` / `查询` / `列表` / `共享给我的` / `团队` / `下属` / `成员` / `某某某的报告` / `已提交` / `发布` / `撤回` / `修改` / `提醒他们交报告`。
+
+B 链路只调用报告侧 operation，**禁止**因为「报告」二字去调用 IM消息、日报、日程、会议、项目任务、客户营销、流程等业务模块采集数据。
+
+### 2. A 链路（生成与汇总报告）——必须采集业务数据
+
+未命中 B 链路任何信号，且同时满足以下两个要素时走 A：
+
+- 动词要素：汇总 / 生成 / 写 / 整理 / 总结 / 帮我出一份；
+- 对象要素：周期词（周报 / 月报 / 季报 / 年报 / 周 / 月 / 季度 / 本周 / 上周 / 本月 / 上月 / 本季度 / 上季度）+ 内容词（报告 / 周报 / 内容 / 工作 / 总结）。
+
+### 3. 默认值规则
+
+动词为「汇总 / 生成 / 写 / 整理」，对象含周期与报告类名词，且未命中 B 链路信号时，一律按 A 处理，默认采集**当前登录人自己**的业务数据。以下说法直接归入 A：
+
+- 汇总上周报告、汇总本周报告、汇总上月报告、汇总上季度报告；
+- 生成上周报告、生成本周报告、帮我写周报 / 写月报 / 写季报 / 写年报；
+- 帮我整理上周工作写报告、把上周的工作总结成周报。
+
+A 链路的完整作业步骤见 [`plan-collect-and-compose.md`](plan-collect-and-compose.md)。
+
+## 二、版本路由与租户缓存
+
+报告侧接口分标准版与 e10-ebuilder 版两套链路，由 CLI 统一判定，Agent **不要手工选择链路**。
+
+| 步骤 | 行为 |
+| --- | --- |
+| 1 | 优先读租户隔离、有效期 1 天的版本判定缓存；命中且未过期直接复用，跳过版本接口 |
+| 2 | 缓存缺失或过期时调用 `plan_searchAppver`，读取返回字段 `ver_name` |
+| 3 | `ver_name = V2` → 全部报告侧接口走 **e10-ebuilder 链路**；其它情况 → **标准版链路** |
+| 4 | 把判定结果写入租户缓存，有效期 1 天 |
+
+禁止行为：不读缓存直接调版本接口；缓存过期不重新拉取；跳过版本判定硬编码链路；eb 链路命中后混用标准版接口。
+
+- 查看当前判定结果：`plan.version.check`（或 `plan route`），返回 `link`（`standard` / `eb`）、`verName`、`cached`、`degraded`。
+- `degraded: true` 表示版本接口暂不可用、已降级为标准版链路，此时不写缓存，下次会重试。
+- **采集业务数据阶段禁止调用版本接口和任何报告侧接口**，只在判定为 B 链路、或 A 链路走到「用户确认后做重复性检查」时才允许触发版本路由。
+
+### eb 报告详情页表单 id
+
+eb 链路详情页地址为 `/sp/ebdfpage/card/0/{报告详情 eb 表单 id}/{报告 id}`，其中表单 id 指 **idobjId**（不是 formId）。`plan.eb.form.resolve` 负责解析：
+
+- 应用 appTag：`weaver-wrplan-eb`；报告详情表单 tag：`uf_plan_work_report`。
+- 租户 key 为 `tt1pa2w2i3` 时无需动态获取，固定为 `1029659181695361024`；其它租户按 appTag、表单 tag 动态获取。
+- 取到后按租户**长期缓存**，后续直接使用，不再动态获取。
+
+`plan.report.get` 与 `plan.report.page` 已在 `detailUrl` 中返回拼好的详情页地址，Agent 直接用即可。
+
+## 三、operation 总表
+
+| operation | 风险 | 说明 |
+| --- | --- | --- |
+| `plan.version.check` | read | 判定租户报告链路，命中缓存则跳过接口调用 |
+| `plan.eb.form.resolve` | read | 解析 eb 报告详情表单 id（idobjId） |
+| `plan.report.get` | read | 按 id 或按周期查询单份报告详情，附带评论总条数 |
+| `plan.report.page` | read | 分页查询报告列表 |
+| `plan.comment.list` | read | 查询报告评论内容（标准版链路） |
+| `plan.report.create.prepare` / `.apply` | read-before-write / high-risk-write | 新建报告 |
+| `plan.report.update.prepare` / `.apply` | read-before-write / high-risk-write | 修改报告 |
+| `plan.report.publish.prepare` / `.apply` | read-before-write / high-risk-write | 发布报告 |
+| `plan.report.withdraw.prepare` / `.apply` | read-before-write / high-risk-write | 撤回报告（标准版链路） |
+| `plan.report.remind.prepare` / `.apply` | read-before-write / high-risk-write | 发送提交提醒（标准版链路） |
+
+字段细节以 `weaver-work-cli plan schema` 为准。
+
+## 四、通用基础规则（两条链路均生效）
+
+1. **周期计算**：周报年份、周数严格遵循 ISO8601，1 月 4 日所在周为当年第 1 周。未明确周期类型时先向用户确认周/月/季/年，确认前不得臆造区间。
+2. **跳转能力**：报告新建、查询、修改、发布、撤回成功后，必须把 `detailUrl` 呈现为可点击链接。
+3. **分页表格输出**：分页接口返回的列表必须用表格展示，固定列为 **报告名称 / 报告创建人名称 / 发布时间**；报告名称可点击，直接跳转 `detailUrl`。
+4. **人员 ID 规则**：所有传递和获取人员 id 的地方，都取 `id` 或 `employeeId` 字段，**禁止取 `userId`**。人员信息通过 weaver-e10-hrm skill 获取。
+5. **雪花 ID 传参**：请求体中的雪花 ID（人员 ID、报告 ID 等）必须加引号包裹为字符串，避免数字精度丢失。CLI 已完成归一化，业务输入按字符串传更安全。
+6. **重复性判断**：判断当前人员是否提交某个周期的报告，**只能**通过 `plan.report.get` 按周期查询（必须传报告年份、报告类型、报告周期，创建人缺省为当前登录人）。
+7. **不得重复创建**：当且仅当用户确认需要创建某个周期的报告时才判断是否已创建；若已创建，不得重复创建，需明确告知用户并征询是否改为编辑。
+8. **字段名禁止项**：任何执行阶段和最终创建的报告内容中，决不允许出现报告相关的数据库英文字段名。CLI 已把 eb 链路返回值归一化为业务字段（`reportId` / `title` / `content` / `summary` / `plans` / `year` / `type` / `serialNumber` / `postStatus` / `postTime` / `creator` / `detailUrl`），Agent 只使用这些业务键，不要向用户复述原始接口结构。
+9. **认证三件套**：所有请求必须携带完整登录态（Cookie 完整原始串、eteamsid、User-Agent）。由 CLI 托管，禁止输出、索取或写入任何凭证；未登录时先按共享规则读取 `../weaver-e10-shared/references/e10-auth-and-session.md` 并通过 `weaver-work-cli auth ...` 确认会话。
+
+## 命令
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json plan run plan.version.check --input-json '{"refresh":false}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json plan run plan.version.check --input-json '{"refresh":false}'
+```
+
+强制重新判定链路：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json plan run plan.version.check --input-json '{"refresh":true}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json plan run plan.version.check --input-json '{"refresh":true}'
+```
+
+## 输出处理
+
+`plan.version.check` 返回示例（字段说明）：
+
+- `link`：`standard` 或 `eb`，本次生效的链路。
+- `verName`：版本接口返回的 `ver_name` 原始值。
+- `cached`：本次结果是否来自缓存。
+- `degraded`：是否因版本接口不可用而降级为标准版。
+
+## 注意
+
+- 报告侧接口链路由 CLI 判定并缓存；Agent 不要缓存或自行推断链路。
+- 采集阶段（A 链路第 1~7 步）不得触发版本接口或报告侧接口。
+
+## 失败处理
+
+- `authentication` / `session_expired`：先向用户确认 E10 登录域名，再执行 `weaver-work-cli auth login`。
+- `policy` / `link_unsupported`：该能力在当前链路不可用，按 `message` 给出的替代路径处理。
+- `endpoint_not_found`（HTTP 404）：当前环境可能未部署「计划报告」相关应用或接口，先向用户说明再决定是否停止。

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` 做一次只读回查，再向用户说明并让用户决定。