weaver-work-cli 0.1.5 → 0.1.7

package/skills/weaver-e10-okr/references/okr-query.md

@@ -0,0 +1,105 @@
+# 目标查询与详情（okr-query）
+
+只读 operation 清单：`okr.list`、`okr.get`、`okr.kr.list`、`okr.comment.list`、`okr.viewlink`、`okr.detail.link`。全部不需要确认，也不会写入数据。
+
+## `okr.list` — 分页查询目标
+
+标准版与 ebuilder 链路共用同一个 operation，入参一致，请求体按链路自动转换。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `query_scope` | `self` / `all` | `self`=本人对应周期（默认），`all`=按条件跨人检索 |
+| `period_type` | `"1"`/`"2"`/`"3"`/`"4"` | 1-年度 2-季度 3-月度 4-自定义；`query_scope=self` 时必填 |
+| `period_range` | string | 年度/季度为 `yyyy`，月度为 `yyyy-MM`，自定义为 `开始日期,结束日期` |
+| `period_quarter` | `"1"`..`"4"` | `period_type=2` 时必填 |
+| `name` | string | 目标名称关键字（**仅标准版链路**，模糊匹配） |
+| `principalid` | 人员 ID | 责任人筛选（人员 ID 由 weaver-e10-hrm 解析） |
+| `status` | string | 状态码，英文逗号拼接（**仅标准版链路**） |
+| `match` | `and` / `or` | 多条件关系，默认 `and`（仅标准版链路） |
+| `page_no` / `page_size` | integer | 默认 1 / 10；`page_size` 最大 100 |
+
+返回：
+
+- `link`、`queryScope`、`period`、`page`（含 `total`/`hasNext`）、`count`。
+- `goals[]`：统一结构的目标数组（`goalId`、`name`、`principalid`、`principalName`、`periodType`、`periodTypeLabel`、`periodRange`、`periodStart`、`periodEnd`、`status`、`statusLabel`、`progress`、`detailUrl` 等）。
+- `table`：**固定四列**表格（目标名称、目标责任人名称、目标周期类型、目标周期范围），`table.markdown` 中的目标名称是可点击的**绝对地址**链接。
+
+链路差异：
+
+- **标准版**：`query_scope=self` 固定传 `condtype=1`/`subcondtype=1`/`status=1`；`query_scope=all` 传 `condtype=4`/`subcondtype=6`，支持 `name`/`principalid`/`status`。
+- **ebuilder**：只传 `creator`（self 时）/`principalid` + 周期筛选字段；**不支持按名称或状态筛选**，传入 `name` 或 `status` 会返回 `validation/link_filter_unsupported`。
+
+便捷入口：`weaver-work-cli okr list --period-type 3 --period-range 2026-09 --page-size 10`。
+
+## `okr.get` — 目标详情
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `id` | 目标 ID | 必填 |
+| `include_comment_count` | boolean | 默认 `true`，仅标准版链路生效 |
+
+返回 `link`、`goalId`、`goal`（统一结构）、`raw`（原始响应），以及标准版链路下的评论提示。
+
+**评论规则**：标准版链路会额外查询评论总条数，但**详情绝不直接输出评论正文**：
+
+- 总数 > 0 → 只返回 `commentSummary.totalCount` 与提示「该目标下共有 N 条评论，是否需要查看评论内容？」，正文必须由用户确认后再调 `okr.comment.list`。
+- 总数 = 0 → 完全忽略评论模块，不输出任何评论相关文字。
+- 评论接口不可用 → 记入 `meta.notes`（`comment_count_unavailable`）。
+- ebuilder 链路 → 不查询评论接口，`meta.notes` 说明 `comment_api_unsupported_on_eb_link`。
+
+## `okr.kr.list` — 关键成果列表（仅 ebuilder）
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `object_id` | 目标 ID | 必填 |
+| `page_no` / `page_size` | integer | 默认 1 / 10 |
+
+标准版链路没有独立的关键成果分页接口，调用会返回 `policy/link_unsupported`；标准版请改用 `okr.get` 的 `goal.keyresultList` 或 `okr.list` 的 `goals[].keyresultList`。
+
+## `okr.comment.list` — 目标评论（仅标准版）
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `target_id` | 目标 ID | 必填 |
+| `page_no` / `page_size` | integer | 默认 1 / 10 |
+
+**只有在用户明确要求查看评论内容后才可调用**（`okr.get` 只给提示不给正文）。ebuilder 链路没有评论接口，调用会返回 `policy/link_unsupported`。
+
+## `okr.viewlink` / `okr.detail.link` — 详情页链接
+
+- `okr.viewlink`：`ids`（目标 ID 数组或英文逗号拼接字符串）必填，`anchor` 可选（链接展示文案）。逐条返回 `goalId`、`path`（站内相对路径）、`url`（绝对地址）、`anchor`。任一 id 链接不可用时整体返回 `status=VIEWLINK_UNAVAILABLE`、`available=false` 并给出 `warnings`。
+- `okr.detail.link`：返回当前链路的地址模板（`pathTemplate` / `urlTemplate`）与 eb 表单 id 解析来源。
+
+## 调用示例
+
+标准版本人月度目标：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json okr run okr.list --input-json '{"query_scope":"self","period_type":"3","period_range":"2026-09","page_size":10}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+printf '%s\n' '{"query_scope":"self","period_type":"3","period_range":"2026-09","page_size":10}' | weaver-work-cli --json okr run okr.list --input -
+```
+
+跨人检索（标准版）：
+
+```text
+weaver-work-cli --json okr run okr.list --input-json '{"query_scope":"all","name":"10月份","principalid":"<人员ID>"}'
+```
+
+查询详情：
+
+```text
+weaver-work-cli --json okr get --id <目标ID>
+```
+
+## 注意
+
+- 返回的 `table.markdown` 可能较长，给用户只渲染表格与数量摘要，不要整段回贴 `raw`。
+- `principalid`/`status` 等筛选字段传错类型会被 schema 直接拒绝，错误形状见 stderr JSON。
+- 列表默认只查一页，需要更多数据时按 `page.hasNext` 递增 `page_no`，不要一次性把 `page_size` 调到 100 以上。

package/skills/weaver-e10-okr/references/okr-write.md

@@ -0,0 +1,94 @@
+# 新建与编辑目标（okr-write）
+
+新建目标与编辑目标都拆成 `prepare -> apply` 两个 operation，四个 operation 都属于高风险写入，必须经用户明确确认。
+
+| operation | 风险 | 作用 |
+| --- | --- | --- |
+| `okr.create.prepare` | read-before-write | 归一化输入、补默认值、生成预览与 continuation，**不写入** |
+| `okr.create.apply` | high-risk-write | 提交新建目标 |
+| `okr.update.prepare` | read-before-write | 先查询当前目标详情并合并修改，生成预览与 continuation，**不写入** |
+| `okr.update.apply` | high-risk-write | 提交编辑目标 |
+
+## 入参字段
+
+`prepare` 与对应 `apply` 使用同一组业务字段；`apply` 额外要求 `confirm=true` 与 `continuation`，编辑类 `apply` 还要求显式传 `id`。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `name` | string | 目标名称（新建必填） |
+| `period_type` | `"1"`..`"4"` | 周期类型（新建必填） |
+| `period_range` | string | 周期范围（新建必填，格式随类型变化） |
+| `period_quarter` | `"1"`..`"4"` | `period_type=2` 必填 |
+| `principalid` | 人员 ID | 责任人，默认当前登录用户 |
+| `partners` | 人员 ID 或数组 | 参与人，英文逗号拼接或数组 |
+| `scope_id` | `"1"` / `"2"` | 1-个人目标（默认） 2-部门目标 |
+| `scope_data_id` | 部门 ID | 标准版链路 `scope_id=2` 必填 |
+| `principal_dept` | 部门 ID | ebuilder 链路 `scope_id=2` 必填 |
+| `parent_id` | 目标 ID | 上级目标 |
+| `category_id` | string | 目标分类 id |
+| `remark` | string | 目标描述 |
+| `progress` | number | 进度 0-100（ebuilder 新建默认 0） |
+| `status` | `"0"` / `"1"` | **标准版**：0-保存草稿（新建默认） 1-正式提交 |
+| `m_status` | `"1"`..`"5"` | **ebuilder**：1-进行中（新建默认） 2-已完成 3-已撤销 4-审批中 5-未开始 |
+| `wb_state` | `"1"`..`"3"` | **ebuilder** 紧急状态：1-正常 2-紧急 3-非常紧急 |
+| `keyresult_list` | array | 随目标一起创建的关键成果（**仅标准版**），元素 `{name, principalid?, weight?, target_value?}` |
+| `confirm` | `true` | 仅 `apply`，必须为 `true` |
+| `continuation` | string | 仅 `apply`，取自 `prepare` 返回 |
+
+非本链路的字段会被忽略并记入 `meta.notes`（如标准版链路的 `m_status`/`wb_state`/`principal_dept`，ebuilder 链路的 `keyresult_list`）。
+
+## 关键业务规则
+
+- **标准版新建默认草稿**：未传 `status` 时新建默认 `status=0`，不会直接提交为正式目标。
+- **标准版编辑必须显式传 `status`**：`update.prepare` 不传 `status` 会返回 `validation/status_required`，避免把正式目标静默回退为草稿。
+- **编辑为全量合并**：`update.prepare` 先通过详情接口取回当前目标，再合并用户修改；只读字段（如 `creator`、`img_url`）不回写。
+- **ebuilder 新建默认值**：`m_status=1`、`progress=0`。
+- **部门目标**：标准版要 `scope_data_id`，ebuilder 要 `principal_dept`，缺失时 prepare 阶段直接阻断。
+- **人员 ID**：必须传人员 ID，传姓名会返回 `validation/person_id_invalid` 并指向 weaver-e10-hrm。
+
+## 确认链
+
+1. 调 `okr.create.prepare` / `okr.update.prepare`，向用户展示 `preview`（含目标名称、级别、周期、责任人、参与人、状态等）与 `expiresInSeconds`。
+2. 用户明确同意后调 `okr.create.apply` / `okr.update.apply`，传 `confirm=true` 与 prepare 返回的 `continuation`。
+3. continuation 绑定 `baseUrl`/`profile`/`userId`，10 分钟有效；登录上下文变化会返回 `validation/context_mismatch`，写入内容指纹变化会返回 `validation/target_changed`，两种情况都必须重新 prepare。
+
+`apply` 成功后返回 `status=COMPLETE`、`goalId`、`path` 与 `detailUrl`（可点击的绝对地址）。
+
+## 失败处理
+
+- 写入请求发出后连接中断 → `partial/write_uncertain`，**禁止自动重试**，先调 `okr.get` 复核目标是否已落库。
+- `validation/context_mismatch`、`validation/target_changed` → 重新执行 prepare，不要复用旧 continuation。
+- `validation/scope_data_id_required`、`validation/principal_dept_required`、`validation/period_quarter_invalid` → 补齐参数后重新 prepare。
+
+## 调用示例
+
+新建个人月度目标：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json okr run okr.create.prepare --input-json '{"name":"2026年9月目标","period_type":"3","period_range":"2026-09"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+printf '%s\n' '{"name":"2026年9月目标","period_type":"3","period_range":"2026-09"}' | weaver-work-cli --json okr run okr.create.prepare --input -
+```
+
+用户在对话中确认后提交：
+
+```text
+weaver-work-cli --json okr run okr.create.apply --input-json '{"confirm":true,"continuation":"<prepare 返回的 continuation>"}'
+```
+
+编辑已有目标（标准版必须带 `status`）：
+
+```text
+weaver-work-cli --json okr run okr.update.prepare --input-json '{"id":"<目标ID>","name":"2026年9月目标（修订）","status":"0"}'
+```
+
+## 注意
+
+- 禁止手工构造或跨任务复用 continuation；`confirm=true` 只在用户明确确认后传入。
+- `preview` 是给用户看的确认摘要，不是真实请求体；不要用 `preview` 去推测接口字段名。