@colinlu50/openclaw-lark-stream 2026.3.17

package/skills/feishu-update-doc/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: feishu-update-doc
+description: |
+  更新飞书云文档。支持 7 种更新模式：追加、覆盖、定位替换、全文替换、前/后插入、删除。
+---
+
+# feishu__update_doc
+
+更新飞书云文档内容，支持 7 种更新模式。优先使用局部更新（replace_range/append/insert_before/insert_after），慎用 overwrite（会清空文档重写，可能丢失图片、评论等）。
+
+# 定位方式
+
+定位模式（replace_range/replace_all/insert_before/insert_after/delete_range）支持两种定位方式，二选一：
+
+## selection_with_ellipsis - 内容定位
+
+支持两种格式：
+
+1. **范围匹配**：`开头内容...结尾内容`
+   - 匹配从开头到结尾的所有内容（包含中间内容）
+   - 建议 10-20 字符确保唯一性
+
+2. **精确匹配**：`完整内容`（不含 `...`）
+   - 匹配完整的文本内容
+   - 适合替换短文本、关键词等
+
+**转义说明**：如果要匹配的内容本身包含 `...`，使用 `\.\.\.` 表示字面量的三个点。
+
+示例：
+- `你好...世界` → 匹配从"你好"到"世界"之间的任意内容
+- `你好\.\.\.世界` → 匹配字面量 "你好...世界"
+
+**建议**：如果文档中有多个 `...`，建议使用更长的上下文来精确定位，避免歧义。
+
+## selection_by_title - 标题定位
+
+格式：`## 章节标题`（可带或不带 # 前缀）
+
+自动定位整个章节（从该标题到下一个同级或更高级标题之前）。
+
+**示例**：
+- `## 功能说明` → 定位二级标题"功能说明"及其下所有内容
+- `功能说明` → 定位任意级别的"功能说明"标题及其内容
+
+# 可选参数
+
+## new_title
+
+更新文档标题。如果提供此参数，将在更新文档内容后同步更新文档标题。
+
+**特性**：
+- 仅支持纯文本，不支持富文本格式
+- 长度限制：1-800 字符
+- 可以与任何 mode 配合使用
+- 标题更新在内容更新之后执行
+
+
+# 返回值
+
+## 成功
+
+```json
+{
+  "success": true,
+  "doc_id": "文档ID",
+  "mode": "使用的模式",
+  "message": "文档更新成功（xxx模式）",
+  "warnings": ["可选警告列表"],
+  "log_id": "请求日志ID"
+}
+```
+
+## 异步模式（大文档超时）
+
+```json
+{
+  "task_id": "async_task_xxxx",
+  "message": "文档更新已提交异步处理，请使用 task_id 查询状态",
+  "log_id": "请求日志ID"
+}
+```
+
+使用返回的 `task_id` 再次调用 update-doc（仅传 task_id 参数）查询状态。
+
+## 错误
+
+```json
+{
+  "error": "[错误码] 错误消息\n💡 Suggestion: 修复建议\n📍 Context: 上下文信息",
+  "log_id": "请求日志ID"
+}
+```
+
+---
+
+# 使用示例
+
+## append - 追加到末尾
+
+```json
+{
+  "doc_id": "文档ID或URL",
+  "mode": "append",
+  "markdown": "## 新章节\n\n追加的内容..."
+}
+```
+
+## replace_range - 定位替换
+
+使用 `selection_with_ellipsis`：
+```json
+{
+  "doc_id": "文档ID或URL",
+  "mode": "replace_range",
+  "selection_with_ellipsis": "## 旧章节标题...旧章节结尾。",
+  "markdown": "## 新章节标题\n\n新的内容..."
+}
+```
+
+使用 `selection_by_title`（替换整个章节）：
+```json
+{
+  "doc_id": "文档ID或URL",
+  "mode": "replace_range",
+  "selection_by_title": "## 功能说明",
+  "markdown": "## 功能说明\n\n更新后的功能说明内容..."
+}
+```
+
+## replace_all - 全文替换
+
+与 replace_range 类似，但支持多处同时替换（replace_range 要求匹配唯一）：
+```json
+{
+  "doc_id": "文档ID或URL",
+  "mode": "replace_all",
+  "selection_with_ellipsis": "张三",
+  "markdown": "李四"
+}
+```
+
+**返回值**包含 `replace_count` 字段，表示替换的次数：
+```json
+{
+  "success": true,
+  "replace_count": 4,
+  "message": "文档更新成功（replace_all模式，替换4处）"
+}
+```
+
+**注意**：
+- 与 `replace_range` 不同，`replace_all` 允许多个匹配
+- 如果没有找到匹配内容，会返回错误
+- `markdown` 可以为空字符串，表示删除所有匹配内容
+
+## insert_before - 前插入
+
+```json
+{
+  "doc_id": "文档ID或URL",
+  "mode": "insert_before",
+  "selection_with_ellipsis": "## 危险操作...数据丢失风险。",
+  "markdown": "> **警告**：以下操作需谨慎！"
+}
+```
+
+## insert_after - 后插入
+
+```json
+{
+  "doc_id": "文档ID或URL",
+  "mode": "insert_after",
+  "selection_with_ellipsis": "```python...```",
+  "markdown": "**输出示例**：\n```\nresult = 42\n```"
+}
+```
+
+## delete_range - 删除内容
+
+使用 `selection_with_ellipsis`：
+```json
+{
+  "doc_id": "文档ID或URL",
+  "mode": "delete_range",
+  "selection_with_ellipsis": "## 废弃章节...不再需要的内容。"
+}
+```
+
+使用 `selection_by_title`（删除整个章节）：
+```json
+{
+  "doc_id": "文档ID或URL",
+  "mode": "delete_range",
+  "selection_by_title": "## 废弃章节"
+}
+```
+
+注意：delete_range 模式不需要 markdown 参数。
+
+## 同时更新标题和内容
+
+可以在任何更新模式中添加 `new_title` 参数来同时更新文档标题：
+
+```json
+{
+  "doc_id": "文档ID或URL",
+  "mode": "overwrite",
+  "markdown": "# 项目文档 v2.0\n\n全新的内容...",
+  "new_title": "项目文档 v2.0"
+}
+```
+
+```json
+{
+  "doc_id": "文档ID或URL",
+  "mode": "append",
+  "markdown": "## 更新日志\n\n2025-12-18: 新增功能...",
+  "new_title": "项目文档（已更新）"
+}
+```
+
+## overwrite - 完全覆盖
+
+⚠️ 会清空文档后重写，可能丢失图片、评论等，仅在需要完全重建文档时使用。
+
+```json
+{
+  "doc_id": "文档ID或URL",
+  "mode": "overwrite",
+  "markdown": "# 新文档\n\n全新的内容..."
+}
+```
+
+---
+
+# 最佳实践
+
+## 小粒度精确替换
+
+修改文档内容时，**定位范围越小越安全**。尤其是表格、分栏等嵌套块，应精确定位到需要修改的文本，避免影响其他内容。
+
+**示例**：表格单元格中有图片和文字，只需修改文字
+- ❌ 替换整个表格或整行 → 可能破坏图片引用
+- ✅ 只定位需要修改的文本 → 图片等其他内容不受影响
+
+
+## 保护不可重建的内容
+
+图片、画板、电子表格、多维表格、任务等内容以 token 形式存储，**无法读出后原样写入**。
+
+**保护策略**：
+- 替换时避开包含这些内容的区域
+- 精确定位到纯文本部分进行修改
+
+## 分步更新优于整体覆盖
+
+修改多处内容时：
+- ✅ 多次小范围替换，逐步修改
+- ⚠️ 谨慎使用 `overwrite` 重写整个文档, 除非你认为风险完全可控
+
+**原因**：局部更新保留原有媒体、评论、协作历史，更安全可靠。
+
+## insert 模式扩大定位范围时注意插入位置
+
+使用 `insert_before` 或 `insert_after` 时，如果目标内容重复出现，需要扩大 `selection_with_ellipsis` 范围来唯一定位。
+
+**关键**：插入位置基于匹配范围的**边界**：
+- `insert_after` → 插入在匹配范围的**结尾**之后
+- `insert_before` → 插入在匹配范围的**开头**之前
+
+扩大范围时，确保边界仍然是期望的插入点。
+
+## 修复画板语法错误
+
+当 create-doc 或 update-doc 返回画板写入失败的 warning 时：
+1. warning 中包含 whiteboard 标签（如 `<whiteboard token="xxx"/>`）
+2. 分析错误信息，修正 Mermaid/PlantUML 语法
+3. 用 `replace_range` 替换：`selection_with_ellipsis` 使用 warning 中的 whiteboard 标签，`markdown` 提供修正后的代码块
+4. 重新提交验证
+
+---
+
+# 注意事项
+
+- **Markdown 语法**：支持飞书扩展语法，详见 create-doc 工具文档

package/src/card/builder.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Interactive card building for Lark/Feishu.
+ *
+ * Provides utilities to construct Feishu Interactive Message Cards for
+ * different agent response states (thinking, streaming, complete, confirm).
+ */
+/**
+ * Element ID used for the streaming text area in cards. The CardKit
+ * `cardElement.content()` API targets this element for typewriter-effect
+ * streaming updates.
+ */
+export declare const STREAMING_ELEMENT_ID = "streaming_content";
+export declare const REASONING_ELEMENT_ID = "reasoning_content";
+export interface ToolCallInfo {
+    name: string;
+    status: 'running' | 'complete' | 'error';
+    args?: Record<string, unknown>;
+    result?: string;
+    durationMs?: number;
+    startTime?: number;
+}
+export interface CardElement {
+    tag: string;
+    [key: string]: unknown;
+}
+export interface FeishuCard {
+    config: {
+        wide_screen_mode: boolean;
+        update_multi?: boolean;
+        locales?: string[];
+        summary?: {
+            content: string;
+        };
+    };
+    header?: {
+        title: {
+            tag: 'plain_text';
+            content: string;
+            i18n_content?: Record<string, string>;
+        };
+        template: string;
+    };
+    elements: CardElement[];
+}
+export type CardState = 'thinking' | 'streaming' | 'complete' | 'confirm';
+export interface ConfirmData {
+    operationDescription: string;
+    pendingOperationId: string;
+    preview?: string;
+}
+/**
+ * Split a payload text into optional `reasoningText` and `answerText`.
+ *
+ * Handles two formats produced by the framework:
+ * 1. "Reasoning:\n_italic line_\n…" prefix (from `formatReasoningMessage`)
+ * 2. `<think>…</think>` / `<thinking>…</thinking>` XML tags
+ *
+ * Equivalent to the framework's `splitTelegramReasoningText()`.
+ */
+export declare function splitReasoningText(text?: string): {
+    reasoningText?: string;
+    answerText?: string;
+};
+/**
+ * Strip reasoning blocks — both XML tags with their content and any
+ * "Reasoning:\n" prefixed content.
+ */
+export declare function stripReasoningTags(text: string): string;
+/**
+ * Format reasoning duration into a human-readable i18n pair.
+ * e.g. { zh: "思考了 3.2s", en: "Thought for 3.2s" }
+ */
+export declare function formatReasoningDuration(ms: number): {
+    zh: string;
+    en: string;
+};
+/**
+ * Format milliseconds into a human-readable duration string.
+ */
+export declare function formatElapsed(ms: number): string;
+/**
+ * Build a full Feishu Interactive Message Card JSON object for the
+ * given state.
+ */
+export declare function buildCardContent(state: CardState, data?: {
+    text?: string;
+    reasoningText?: string;
+    reasoningElapsedMs?: number;
+    toolCalls?: ToolCallInfo[];
+    confirmData?: ConfirmData;
+    elapsedMs?: number;
+    isError?: boolean;
+    isAborted?: boolean;
+    footer?: {
+        status?: boolean;
+        elapsed?: boolean;
+    };
+}): FeishuCard;
+/**
+ * Convert an old-format FeishuCard to CardKit JSON 2.0 format.
+ * JSON 2.0 uses `body.elements` instead of top-level `elements`.
+ */
+export declare function toCardKit2(card: FeishuCard): Record<string, unknown>;