npm - @coze/cli - Versions diffs - 0.2.0 → 0.3.0 - Mend

@coze/cli 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (42) hide show

package/skills/using-coze-cli/coze-claw/MODULE.md ADDED Viewed

@@ -0,0 +1,189 @@
+---
+name: coze-claw
+version: 0.2.0-alpha.740728
+description: "Coze Claw Session 会话工作流：创建/找回 claw session、发送 session message、监听回复、查询后台 progress、处理文件/PPT/播客产物。当用户需要使用 coze session * 任意命令时触发。"
+metadata:
+  requires:
+    bins: ["coze"]
+  cliHelp: "coze session --help"
+---
+# Coze Claw Session 工作流
+> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解认证、全局参数、输出格式和错误处理。
+> **上下文说明：** `coze session *` 跳过 org/space check，不要求先执行 `coze org use` 或 `coze space use`。只需确保 token 有效，并通过 `coze session status` 解析当前 claw。
+> **执行前必做：** 从下方命令分组定位 reference，并先阅读对应 reference。涉及长任务 follow-up 时，再读 [`coze-claw-async-followup.md`](references/coze-claw-async-followup.md)。
+## 核心概念
+- **claw_id**：当前账号可用的 claw 实例，通常由 `coze session status` 解析并缓存。
+- **session_id**：一条 claw chat 会话，CLI 会把最近一次成功使用的 session 持久化到本地，供后续 message/watch/replies/podcast/ppt edit 默认复用。
+- **message_id**：用户提交的请求消息 ID，用于 `replies` 补偿查询。
+- **answer_message_id**：assistant 回复消息 ID，用于对齐流式回复和最终回复。
+- **progress_id**：claw 后台任务 ID，用于 progress 查询/监听。
+- **file_uri**：平台内部文件引用，不能直接下载。
+- **file_url**：可下载或可直接交付的文件 URL。
+## Agent 快速执行顺序
+1. **检查认证/claw**：`coze session status --format json`。
+2. **优先复用本地默认 session**：除非用户明确要求“新建话题/新增话题/开新会话”，否则先执行 `coze session current --format json` 读取本地默认 `session_id`。
+3. **检查指定 session runtime**：已有 `session_id` 时执行 `coze session status -s <session_id> --format json`。
+4. **找回 / 切换 session，再决定是否创建**：如果本地没有可用的默认 `session_id`，先 `list` 找最近一个可复用 session，并用 `coze session use <session_id> --format json` 切换；只有用户明确要求新开话题，或确实没有可复用 session 时才 `create`。
+5. **发送消息**：短任务用 `message --wait`；长任务用 `message` 无 `--wait` 获取 `message_id`，再 `watch/replies`。
+6. **后台任务**：出现 `progress_id` 后，立即把它视为长任务句柄；如果 CLI 已返回 `task_id`，优先转 `session task show/refresh/watch`，并同时保留 `session_id`、`message_id`、`progress_id`。
+7. **产物处理**：普通文件走 `file`；PPT 走 `ppt`；播客先查 voice，再用 `podcast message`。
+## 用户回传闭环
+- `message_id`、`progress_id`、`task_id`、`status=finished` 都只是恢复和编排主键，不是最终要回给用户的内容。
+- 短任务：读取 `reply_completed.content/files` 后，必须把正文或文件链接回给用户。
+- 长任务前置回复：如果同一轮在转入 `progress/task` 之前，已经通过 `reply_update` 或 `reply_completed` 产出了明确的说明性回复，必须先把这段内容回给用户，再继续后台跟进。
+  - 不要只保留 `progress_id` / `task_id` 而丢掉这段首条回复。
+- 长任务：`task/progress` 进入终态后，必须再取最终 reply。
+  - 推荐：`coze session replies <message_id> -s <session_id> --format json`
+  - 兜底：读取终态 `session task` 快照里的 `reply_content`、`artifacts`
+- 禁止只回复“已发送”“已完成”“耗时 xx s”而不附带实际 reply。
+## Session 复用原则
+- 默认复用最近一次成功使用的 `session_id`。
+- 可用 `coze session current --format json` 查看当前本地默认 session。
+- 可用 `coze session use <session_id> --format json` 显式切换默认 session。
+- 只有用户明确说“新建话题”“新增话题”“开一个新会话”“不要沿用之前上下文”时，才主动创建新 session。
+- 如果最近 `session_id` 不可用，再退回 `coze session list --limit 20 --format json` 找最近一个可复用 session。
+- 只有“用户明确要求新建”或“确实找不到可复用 session”这两种情况，才执行 `coze session create --format json`。
+## 长任务 follow-up 原则
+- 命中 `task_id` / `progress_id` 后，不要把“继续盯结果”绑定在当前 agent 进程上。
+- 如果当前宿主支持 schedule/job/workflow，并且 Agent 能直接调用，必须在同一回合自动创建独立的 follow-up 定时任务去轮询 `coze session task refresh/show`，直到任务进入终态。
+- 如果当前宿主不支持，或 Agent 当前无法真正创建 follow-up 定时任务，必须在同一回合明确告知用户“当前还没有创建后台 follow-up 任务”，并给出下一步选项。
+- follow-up task 至少要保存：
+  - `taskId`
+  - `replyTarget`
+- `sessionId`、`messageId`、`progressId` 这类 Coze task 元数据，优先在 follow-up 执行时通过 `task show/refresh` 现查，不要重复持久化。
+- `dedupeKey`、`notifiedAt`、`notifyStatus` 只在宿主没有现成幂等/状态能力时才额外保存。
+- 终态后必须在原消息上下文回复用户，而不是换一个新地方通知。
+- 禁止在没有真正创建 follow-up task 的情况下，对用户说“我继续盯着”“完成后自动回你”“我会持续跟进到结束”。
+- 如果没有创建 follow-up task，可提供的下一步至少包括：
+  - 当前回合继续前台代查
+  - 提醒用户当前可以创建后台定时轮询任务（如果宿主支持后续补建）
+- 具体数据契约、轮询规则、原地回复策略见 [`coze-claw-async-followup.md`](references/coze-claw-async-followup.md)。
+## 标准工作流
+### 短任务：同步等待当前 turn
+```bash
+coze session create --format json
+coze session message "请分析这份需求" \
+  -s <session_id> \
+  --wait \
+  --timeout 120000 \
+  --format json
+```
+`message --wait --format json` 是事件流，必须按事件/行解析。
+### 长任务：提交与监听分离
+```bash
+coze session message "执行这个长任务" -s <session_id> --format json
+coze session watch -s <session_id> --timeout 120000 --format json
+coze session replies <message_id> -s <session_id> --format json
+```
+优先记录 `session_id` 和 `message_id`，这是恢复流程的主键。
+## 意图 → 命令索引
+| 意图 | 推荐命令 | Reference |
+|------|---------|-----------|
+| 检查 token/claw | `coze session status` | [session](references/coze-claw-session.md) |
+| 查看当前默认 session | `coze session current` | [session](references/coze-claw-session.md) |
+| 切换当前默认 session | `coze session use <session_id>` | [session](references/coze-claw-session.md) |
+| 检查指定 session runtime | `coze session status -s <session_id>` | [session](references/coze-claw-session.md) |
+| 新建 claw session | `coze session create` | [session](references/coze-claw-session.md) |
+| 找回已有 session | `coze session list` | [session](references/coze-claw-session.md) |
+| 发送消息并等待回复 | `coze session message --wait` | [message](references/coze-claw-message.md) |
+| 长任务提交与监听分离 | `coze session message` + `coze session watch` | [message](references/coze-claw-message.md) |
+| 超时/断线后补偿查询 | `coze session replies <message_id>` | [message](references/coze-claw-message.md) |
+| 查询本地可恢复长任务 | `coze session task list/show/refresh/watch` | [progress](references/coze-claw-progress.md) |
+| 查询后台任务 | `coze session progress list/show/poll/watch` | [progress](references/coze-claw-progress.md) |
+| 下载回复文件 | `coze session file download <file_url>` | [artifacts](references/coze-claw-artifacts.md) |
+| 处理 PPT 产物 | `coze session ppt *` | [ppt](references/coze-claw-ppt.md) |
+| 选择播客 voice | `coze session podcast voice list` | [podcast](references/coze-claw-podcast.md) |
+| 发送播客消息 | `coze session podcast message` | [podcast](references/coze-claw-podcast.md) |
+## 命令分组
+| 命令分组 | 说明 | Reference |
+|----------|------|-----------|
+| `session status/create/current/use/list` | claw 状态、本地默认 session 与 session 生命周期 | [coze-claw-session.md](references/coze-claw-session.md) |
+| `message/watch/replies` | 消息发送、流式监听、补偿查询 | [coze-claw-message.md](references/coze-claw-message.md) |
+| `task list/show/refresh/watch/gc` | 本地可恢复长任务查询、刷新与清理 | [coze-claw-progress.md](references/coze-claw-progress.md) |
+| `progress list/show/poll/watch` | claw 后台任务查询和监听 | [coze-claw-progress.md](references/coze-claw-progress.md) |
+| `async follow-up` | 长任务登记、定时轮询、原地回复、幂等与 fallback | [coze-claw-async-followup.md](references/coze-claw-async-followup.md) |
+| `file download` | 普通文件产物下载与交付 | [coze-claw-artifacts.md](references/coze-claw-artifacts.md) |
+| `ppt info/pages/export/edit/share` | PPT 产物处理 | [coze-claw-ppt.md](references/coze-claw-ppt.md) |
+| `podcast voice/message` | 播客 voice 查询与播客消息发送 | [coze-claw-podcast.md](references/coze-claw-podcast.md) |
+| `agent routing` | `/coze-cli`、`/coze` 前缀路由、strip 规则、验收样例 | [coze-claw-agent-routing.md](references/coze-claw-agent-routing.md) |
+## 长耗时任务处理
+| 命令 | 默认行为 | 等待/超时建议 | 恢复命令 |
+|------|----------|---------------|----------|
+| `coze session message` | 提交后返回 `message_id` | 推荐 Agent 默认使用 | `replies <message_id>` / `watch` |
+| `coze session message --wait` | 阻塞并输出事件流 | 必须加 `--timeout` | 有 `message_id` 则 `replies`，否则 `watch/status/list` |
+| `coze session watch` | 持续监听 websocket | 必须加 `--timeout` | 再次 `watch` 或查 `progress list` |
+| `coze session task watch` | 持续观察本地 task 快照 | 必须加 `--timeout` | `task refresh <task_id>` / `replies <message_id>` |
+| `coze session progress watch` | 持续监听 progress | 必须加 `--timeout` | `progress poll <progress_id>` |
+| `coze session progress poll` | 单次查询 | 适合脚本循环 | 查不到按 `finished` 处理 |
+补充规则：
+- `message --wait` 一旦返回 `progress_id`，就不要把它继续当作“同一条同步回复”处理。
+- 对 Agent 而言，`progress_id` 就是当前版本最稳定的长任务句柄。
+- 如果 `message --wait` 同时返回了 `task_id`，优先改走：
+  - `coze session task show <task_id> --format json`
+  - `coze session task refresh <task_id> --format json`
+  - `coze session task watch <task_id> --timeout <ms> --format json`
+- `task_id` 是 CLI 本地恢复点，`progress_id` 仍然是服务端长任务句柄；两者都要保留。
+- `task` 进入终态后，再用 `replies <message_id>` 回查最终回复或产物；至少也要读取 task 快照里的 `reply_content` / `artifacts` 并回给用户。
+## 常见错误速查（Claw 专用）
+| 症状/误用 | 一句话修复 |
+|----------|------------|
+| token 失效或未登录 | 先 `coze auth status`，必要时登录；多步处理见“恢复策略速查”。 |
+| 未记录 `session_id` | 先 `current` 看本地默认；没有再 `list` 找回，必要时 `use` 切换。 |
+| `message --wait` 超时 | 有 `message_id` 走 `replies`；否则看“恢复策略速查”。 |
+| 对事件流整段 `JSON.parse()` | 改为按行/事件处理。 |
+| `progress_id` 查不到 | 用 `progress poll` 缺失即 finished 的语义，再回查结果。 |
+| 把 `file_uri` 当 `file_url` 下载 | 先解析为 `file_url`；PPT 走 `ppt info/export/share`。 |
+| 监听命令没有 `--timeout` | 补 `--timeout`，避免 Agent 挂死。 |
+## 恢复策略速查
+| 场景 | Agent 执行步骤 |
+|------|----------------|
+| token 不可用 | 先 `coze auth status`；未登录或过期时引导 `coze auth login`；成功后重试 session 命令。 |
+| 没有 `session_id` | 先 `coze session current --format json`；无默认时执行 `coze session list --limit 20 --format json` 找回，必要时 `coze session use <session_id>`；只有确实没有可复用 session 时才 `create`。 |
+| 只知道历史上下文但没有 session | 执行 `coze session list --format json`，必要时用 `--offset` 分页找回。 |
+| `message --wait` 超时 | 如果已记录 `message_id`，执行 `coze session replies <message_id> -s <session_id> --format json`；否则执行 `watch -s <session_id>` 或 `status -s <session_id>`。 |
+| `watch` 超时但 session 仍 working | 再次执行 `watch -s <session_id> --timeout <ms>`；或查 `progress list` 判断是否转为后台任务。 |
+| 有 `task_id` | 优先 `task show/refresh/watch`；必要时再退回 `progress poll/watch` 与 `replies`。 |
+| 有 `progress_id` 没有最终产物 | 视为长任务恢复流程：优先 `task refresh/watch` 或 `progress poll/watch` 到 finished，再用 `replies <message_id>` 回查。 |
+| 有 `file_url` | 直接 `coze session file download <file_url>`，或把 `file_url` 作为在线链接交付。 |
+| 只有 `file_uri` | 不能直接下载；用对应能力解析。PPT 使用 `ppt info/export/share`。 |
+| 监听输出解析困难 | 改用非监听命令：`message` 无 `--wait`、`replies`、`progress poll/show`。 |
+## Agent 禁止行为
+- 不要对 `message --wait`、`watch`、`progress watch` 的输出整段 `JSON.parse()`。
+- 不要执行监听命令但不设置 `--timeout`。
+- 不要丢失 `session_id`、`message_id`、`progress_id`。
+- 不要把 `file_uri` 当作 `file_url` 下载。
+- 不要只返回本地下载路径作为最终交付，除非用户明确只要本机路径。

package/skills/using-coze-cli/coze-claw/references/coze-claw-agent-routing.md ADDED Viewed

@@ -0,0 +1,45 @@
+# Agent routing contract
+## 路由目标
+- `/coze-cli`：显式命中 Coze CLI skill
+- `/coze`：`/coze-cli` 的短别名，行为完全一致
+## 适用范围
+- 此规则适用于所有 Claw 子模块，不只限于 `session message`
+- 只要最终会把用户正文转发到 Claw，会消费同一份规范化结果的链路都应遵守
+- 当前至少覆盖：
+  - 普通消息链路：[`coze-claw-message.md`](coze-claw-message.md)
+  - PPT 场景：[`coze-claw-ppt.md`](coze-claw-ppt.md)
+  - 播客场景：[`coze-claw-podcast.md`](coze-claw-podcast.md)
+## 规范化规则
+1. 只移除首个路由 token
+2. 保留剩余正文中的所有业务 token
+3. 不改写正文中的中间 `/coze-cli`
+4. 不吞掉 `@PPT`、`@播客`、文件引用、引号和换行
+## 正例
+- 输入：`/coze-cli 制作一个介绍潮汕美食的 PPT`
+  输出正文：`制作一个介绍潮汕美食的 PPT`
+- 输入：`/coze-cli @PPT 制作介绍海南美食的 PPT`
+  输出正文：`@PPT 制作介绍海南美食的 PPT`
+- 输入：`/coze 制作一个冒泡排序 markdown`
+  输出正文：`制作一个冒泡排序 markdown`
+## 反例
+- 错误：把 `/coze-cli` 原样发给 `coze session message`
+- 错误：移除 `@PPT`
+- 错误：移除 `@播客`
+- 错误：把正文里的 `/coze-cli` 全局替换掉
+## 最小验收样例
+1. 不带前缀的自然语言，允许模型自行命中 skill，但不保证确定性
+2. 带 `/coze-cli` 的请求，必须命中 skill
+3. 命中后真正发给 Claw 的 message 不包含 `/coze-cli`
+4. 同一规则适用于 `@PPT`、`@播客` 等子模块入口

package/skills/using-coze-cli/coze-claw/references/coze-claw-artifacts.md ADDED Viewed

@@ -0,0 +1,52 @@
+# claw artifact commands
+> **前置条件：** 先阅读 [`../../SKILL.md`](../../SKILL.md) 和 [`coze-claw-message.md`](coze-claw-message.md)。
+本文档覆盖普通 session 产物处理。PPT 产物见 [`coze-claw-ppt.md`](coze-claw-ppt.md)。
+## 核心区别
+| 字段 | 含义 | 处理方式 |
+|------|------|----------|
+| `file_url` | 可下载或可直接交付的 URL | 可传给 `file download` |
+| `file_uri` | 平台内部文件引用 | 不能直接下载，需要先解析 |
+Agent 不要猜测 `file_uri` 的公网 URL。
+## file download
+```bash
+coze session file download "<file_url>" --format json
+coze session file download "<file_url>" --output-path ./downloads/result.md --format json
+```
+关键输出：
+| 字段 | 含义 |
+|------|------|
+| `status` | `saved` |
+| `path` | 本地保存路径 |
+| `filename` | 文件名 |
+| `size` | 文件大小 |
+| `url` | 原始下载 URL |
+如果用户需要在线链接，已有 `file_url` 时可直接返回它。不要只返回本地路径，除非用户明确只需要本机文件。
+## 普通文件链路
+```text
+reply_completed.files[].file_url
+  -> coze session file download <file_url>
+```
+如果回复中只有 `file_uri`：
+- 普通回复产物需要先通过 session 文件 URL 解析逻辑或后续命令拿到 `file_url`。
+- PPT 类 `file_uri` 交给 [`coze-claw-ppt.md`](coze-claw-ppt.md)。
+- 不要直接把 `file_uri` 拼成 URL。
+## 上传和下载边界
+- 上传本地输入文件给 session message：使用 `coze session message --file` 或正文 `@<path>`。
+- 下载 session 回复产物：使用 `coze session file download <file_url>`。
+- 对用户交付产物：优先返回在线 `file_url`；如果需要本地落盘，再给出下载后的 `path`。

package/skills/using-coze-cli/coze-claw/references/coze-claw-async-followup.md ADDED Viewed

@@ -0,0 +1,266 @@
+# claw async follow-up
+> **前置条件：** 先阅读 [`coze-claw-message.md`](coze-claw-message.md) 和 [`coze-claw-progress.md`](coze-claw-progress.md)。
+当 `coze session message --wait` 或 `coze session message` 命中长任务后，Agent 不应依赖“当前这次对话进程还在”去等待终态。优先做法是登记一个独立的 follow-up 定时任务，周期刷新 `session task` 状态，任务完成后再在原消息上下文回复用户。
+## 适用场景
+- OpenClaw + 飞书：用户在飞书里发消息，长任务完成后仍然回飞书原位置
+- 宿主支持 cron / delayed job / background workflow / schedule
+- 当前回合只适合先 ACK，再后台继续跟进
+## 核心原则
+1. **ACK 和 follow-up 分离**
+   - 当前回合负责快速确认“已接单/已转后台处理”
+   - 后续通知由独立 follow-up task 负责
+2. **回复位置必须持久化**
+   - `session_id` 只能恢复 Coze 任务
+   - `reply_target` 才决定最后把结果回到哪里
+3. **在哪里收到，就在哪里回复**
+   - 飞书 DM 回 DM
+   - 飞书群消息回原群
+   - 飞书 topic/thread 回原 thread
+   - 飞书消息卡片优先更新原卡片
+   - 飞书 Drive 评论必须 reply comment
+4. **必须防重**
+   - follow-up task 重试时不能重复通知用户
+   - 如果宿主已有任务幂等、去重或回执能力，优先复用，不要重复维护一套平行状态
+5. **创建结果必须说实话**
+   - 真正创建了 follow-up task，才可以对用户说“已转后台持续跟进/完成后自动回你”
+   - 如果当前没有创建成功，必须在同一回合明确告知“当前还没有创建后台 follow-up 任务”
+   - 禁止把“我准备创建”“理论上可以创建”表述成“我已经在后台盯着”
+## 执行分支
+命中长任务后，Agent 必须先判断当前宿主是否真的支持并允许创建 follow-up 定时任务：
+### 分支 A：当前就能创建
+- 直接创建，不要把“要不要创建定时任务”再抛回给用户做默认选择题
+- 当前回合应明确告诉用户：
+  - 已创建后台 follow-up 定时任务
+  - 结果会回到原消息上下文
+  - 当前这条回复只是 ACK，不是最终结果
+### 分支 B：当前不能创建
+- 必须在同一回合明确告诉用户：
+  - 当前还没有创建后台 follow-up 定时任务
+  - 原因是当前宿主不支持、权限不允许，或本轮无法实际调用该能力
+- 必须立即给出下一步，而不是停在“我继续盯着”
+- 可给出的下一步至少包括：
+  - 当前回合继续前台代查，查到终态再回复
+  - 如果宿主支持后续补建，提醒用户当前可以创建一个后台定时轮询任务
+- 没有真正创建 follow-up task 时，禁止说“完成后自动回你”“我会持续盯到结束”
+## 最小数据契约
+建议在宿主侧登记一条尽量轻量的 follow-up 记录。`coze session task show/refresh --format json` 已经能按 `task_id` 反查 `session_id`、`message_id`、`progress_id`、`status`、`reply_content`、`artifacts`，所以不要把这些 Coze task 元数据再重复存一份。
+```ts
+type FollowUpJob = {
+  taskId: string;
+  replyTarget: ReplyTarget;
+};
+type FollowUpJobWithHostState = FollowUpJob & {
+  notifyPolicy?: NotifyPolicy;
+  dedupeKey?: string;
+  notifiedAt?: number;
+  notifyStatus?: "pending" | "sent" | "failed";
+};
+type ReplyTarget = {
+  source:
+    | "feishu_dm"
+    | "feishu_group"
+    | "feishu_thread"
+    | "feishu_card"
+    | "feishu_drive_comment";
+  accountId?: string;
+  chatId?: string;
+  threadId?: string;
+  topicId?: string;
+  messageId?: string;
+  commentId?: string;
+  replyMode:
+    | "reply"
+    | "thread_reply"
+    | "update_card"
+    | "reply_comment";
+};
+type NotifyPolicy = {
+  pollIntervalSec: number;
+  maxWaitSec: number;
+  maxAttempts: number;
+  backoff: "fixed" | "linear" | "exponential";
+};
+```
+必填约束：
+- `taskId` 必须保留
+- `replyTarget` 必须在当前回合就确定
+可选宿主字段：
+- 如果宿主没有内建幂等或任务状态，可使用 `FollowUpJobWithHostState` 额外保存 `dedupeKey`、`notifiedAt`、`notifyStatus`
+- 如果宿主调度器需要显式参数，也可在 `FollowUpJobWithHostState` 中补 `notifyPolicy`
+- 如果宿主本身已经有 cron/workflow 元数据、重试策略、任务状态机，就不要在 follow-up 记录里再镜像保存一套
+恢复说明：
+- `taskId` 足够恢复 Coze 长任务
+- follow-up 执行时，如需 `session_id`、`message_id`、`progress_id`，先执行：
+```bash
+coze session task refresh <task_id> --format json
+coze session task show <task_id> --format json
+```
+- 只有 `replyTarget` 这类“Coze CLI 无法帮你恢复的宿主上下文”才值得持久化
+## 标准流程
+### 1. 当前回合 ACK
+当前回合只做三件事：
+1. 把前置回复回给用户
+2. 说明 follow-up 是否已经创建成功
+3. 创建成功则登记 follow-up task；未创建成功则明确给出下一步选项
+只有真正创建成功，才可以明确说“已登记后台跟进任务”。
+### 2. 创建 follow-up task
+follow-up task 至少要能执行：
+```bash
+coze session task refresh <task_id> --format json
+coze session task show <task_id> --format json
+# message_id 和 session_id 从上一步 task refresh/show 输出中获取
+coze session replies <message_id> -s <session_id> --format json
+```
+推荐顺序：
+1. 先 `task refresh`
+2. 从输出里读取 `status`，并按需取 `session_id`、`message_id`
+3. 如果仍是 `running`，按宿主自己的 schedule/workflow 策略继续下一次调度
+4. 如果是 `finished/failed/cancelled`，进入终态回复流程
+### 3. 终态回复流程
+优先级：
+1. 如果 `task show/refresh` 已带 `reply_content` 或 `artifacts`，直接用它
+2. 否则调用 `replies <message_id>`
+3. 整理为最终用户可见结果
+4. 通过 `replyTarget` 回复到原上下文
+### 4. 回复成功后收口
+- 如果宿主使用 `FollowUpJobWithHostState`，写入 `notifiedAt`
+- 如果宿主使用 `FollowUpJobWithHostState`，写入 `notifyStatus=sent`
+- 后续轮询不再重复发送
+如果宿主已有任务完成回执或幂等键，也可以不额外维护这两个字段，只要能保证“同一终态结果只通知一次”即可。
+## 飞书优先级规则
+OpenClaw + 飞书场景，建议按这个顺序回复：
+1. `feishu_drive_comment`
+   - 必须 `reply_comment`
+2. `feishu_card`
+   - 优先 `update_card`
+   - 更新失败时退回 `thread_reply` 或普通 `reply`
+3. `feishu_thread`
+   - 优先回原 thread/topic
+4. `feishu_group`
+   - 回原群消息上下文
+5. `feishu_dm`
+   - 回原 DM
+禁止：
+- 在飞书收到，最后却发到另一个渠道
+- 原线程还能回复，却新开一条无关联消息
+- 当前回合和 follow-up task 各发一次终态结果
+## 轮询与重试建议
+默认轮询建议：
+- `pollIntervalSec`: 30
+- `maxWaitSec`: 1800
+- `maxAttempts`: 60
+- `backoff`: `fixed`
+这是一组调度建议，不要求一定落成 `FollowUpJob` 字段。能复用宿主自己的 cron / delayed job / workflow 配置时，优先复用。
+更长任务可用：
+- 前 600 秒（10 分钟）每 30 秒
+- 之后每 120 秒（2 分钟）
+如果宿主调度成本高，可改成：
+- 前 3 次 15 秒
+- 之后 60 秒固定间隔
+## 幂等与 fallback
+### 幂等
+- 每次发送前先检查 `notifiedAt`
+- 如果宿主已有幂等键，优先用宿主能力；否则可用 `dedupeKey=<source>:<taskId>:terminal`
+- 如果发送 API 超时但结果未知，也不要立即重发全文；应先查发送结果或写入待人工确认状态
+### fallback
+如果原上下文失效，按这个顺序退化：
+1. 原 thread/topic 不可用，退回同一 chat 的普通 reply
+2. 原 card 无法更新，退回同一 thread reply
+3. 原 comment 无法 reply，退回同一文档或同一会话中的普通通知
+4. 仍失败时，记录 `notifyStatus=failed` 并保留人工补发所需上下文
+禁止直接静默丢失通知。
+## 推荐示例
+### 示例 1：普通长任务
+1. 当前回合收到 `task_id`
+2. 先回复“任务已转后台处理，完成后我会在这里回复你”
+3. 保存 `replyTarget=feishu_dm`
+4. 创建 follow-up task
+5. follow-up `task refresh`
+6. 终态后读取 `reply_content`
+7. 回原 DM
+### 示例 2：PPT 长任务
+1. 当前回合先回前置回复
+2. 命中 `task_id`
+3. 保存 `replyTarget=feishu_group` 或 `feishu_thread`
+4. follow-up 定时轮询
+5. 终态后读取 `artifacts`
+6. 把 PPT 链接或导出产物回原消息位置
+### 示例 3：飞书评论触发
+1. 用户在文档评论区触发任务
+2. 保存 `replyTarget=feishu_drive_comment`
+3. follow-up 轮询 `task`
+4. 终态后用评论回复接口回结果
+5. 不再额外发一条普通 IM 消息