larkcc 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -7,23 +7,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-03-27
+
+### Added
+
+- CardKit SDK migration: all API calls now use `client.cardkit.v1.*` instead of raw fetch with manual token management
+- Streaming preview (summary) with correct object format `{ content, i18n_content }` for card list display
+- Two-step streaming close: `card.settings({ streaming_mode: false })` then `card.update()`, aligned with openclaw-lark best practice
+- `wide_screen_mode` and `update_multi` card config for all modes (CardKit, Update, non-streaming)
+- Structured error handling: `CardKitApiError` class with `isRateLimit` and `isTableLimit` detection
+- Shared `prepareOverflowContext()` helper extracted from `replyWithDocument()` for reuse in CardKit overflow
+- Tool status display in CardKit mode: status text prepended to streaming content during tool calls
+
+### Fixed
+
+- Thinking block not captured (SDK sends `type: "thinking"` blocks, code only handled text/tool_use)
+- Abort not updating card (abort handler inside event loop, never reached when SDK exits)
+- Tool status not displaying when no text content yet (`updateStatus` didn't trigger card creation or flush)
+- Bottom model name not showing in card footer (extracted from `modelUsage` keys instead of non-existent `result.model`)
+- CardKit status bar visibility (empty initial content prevented element rendering)
+- Sequence number conflicts between concurrent `updateStatus` and `performFlush` calls
+- `updateStatus` not awaited in agent.ts causing potential state race conditions
+- Unnecessary token cache invalidation on every overflow (now only refreshes when <10min remaining)
+
+### Changed
+
+- FlushController deduplication: CardKit mode now imports from `streaming.ts` instead of inline copy
+- CardKit constructor no longer accepts `appId`/`appSecret` params (SDK handles token management)
+- `@larksuiteoapi/node-sdk` upgraded from `^1` to `^1.60`
+- Default `flush_interval_ms` changed from 300 to 200
+- `/stop` now provides full abort feedback: signal received notification + success/failure message + distinct reaction
+
+### Refactored
+
+- Removed separate `status_bar` element, merged tool status into `streaming_content` as in-memory prefix to eliminate timing issues
+
+## [0.5.0] - 2026-03-27
+
 ### Added
 
-- Card table limit handling for Feishu messages (max 5 tables per card)
-  - `countTables()` function to accurately count tables in markdown (excludes code blocks)
-  - `splitMarkdownByTables()` to split markdown by table boundaries
-  - `CardTableConfig` for configurable thresholds (`max_tables_per_card`, `max_tables_split`)
-  - Tables >10 auto-write to document, 6-10 split into multiple cards
+- Streaming output support with two modes: CardKit (default) and Update
+  - **CardKit mode**: single-card architecture with state machine (idle → creating → streaming → completed), aligned with official openclaw-lark approach
+  - **Update mode**: message patch API with auto-fallback chain (cardkit → update → none)
+- Image resolver for external images (download and re-upload to Feishu CDN)
+  - Internal CDN domain skip list (feishucdn.com, larksuitecdn.com, etc.)
+- Configurable `card_title` for all streaming modes (default: "Claude")
+- Collapsible thinking section in CardKit complete output
+- Per-tool status words for tool cards (replaces random thinking words)
+- `prepublishOnly` script to package.json for safe npm publishing
+- Card footer metadata (model, tokens, duration) in streaming cards
+
+### Changed
+
+- Default streaming mode changed from `update` to `cardkit`
+- CardKit mode no longer sends separate tool call cards (single-card design)
+
+### Removed
+
+- `thinking_words` config option (replaced by per-tool status words)
 
 ### Fixed
 
-- Correct BlockType enum values to match official Feishu API docs
-  - TABLE: 24 → 31
-  - TABLE_CELL: 25 → 32
-  - IFRAME: 27 → 26
-  - IMAGE: 28 → 27
-  - VIEW: 29 → 33
-  - Add GRID (24) and GRID_COLUMN (25)
+- Correct CardKit API format (card_json type, IM message reply, sequence counter)
+- CardKit lazy card creation on first `append()` call
+- Image resolver CDN download failures with internal domain blacklist
+- ESM-compatible `__dirname` polyfill in guide.ts
+- Align all docx block structures with Feishu SDK types to resolve 1770024 error
 
 ## [0.3.0] - 2026-03-26
 

package/README.md

@@ -219,10 +219,13 @@ Bot: ✅ 已执行
 
 ```
 你：帮我重构整个项目...
-你：/stop  → ⏹ 已发送中断信号
+你：/stop  → ⏹ 已发送中断信号，等待当前步骤完成...
+         → ✅ 已中断
 ```
 
-任务超过 10 分钟无响应自动释放锁，无需重启。
+- `/stop` 发送后先提示"已发送中断信号"，中断完成后通知"已中断"
+- 中断后卡片保留已生成的内容和思考过程，不会丢失
+- 任务超过 10 分钟无响应自动释放锁，无需重启
 
 ## 图片支持
 
@@ -312,12 +315,18 @@ setup 不需要填 open_id，发第一条消息自动保存。
 - ✅ 启动/断开通知
 - 👌 处理中打 reaction，完成换 DONE
 - 💬 回复引用原消息
-- ⚡ 工具调用实时展示
-- 📋 Markdown 卡片渲染
+- ⚡ 工具调用实时展示（首个工具调用即创建卡片，无需等待正文）
+- 🌊 流式输出（互斥守卫 + 自适应节流 + 长间隔批处理）
+- 📋 Markdown 卡片渲染（自动标题降级适配）
 - 📄 超长消息支持分段发送或写入云文档
+- 🛡️ 文档写入容错（单表/批次失败不影响整篇文档）
+- 🎯 格式指导注入（从源头优化输出质量）
 - 🖼 图片理解（支持富文本多图）
+- 🧠 思考过程折叠面板（collapsible_panel，显示推理耗时）
+- ⏱ 响应元数据（耗时、模型、token 数实时显示）
+- 🖼 外部图片自动上传（下载 → 飞书 → 渲染，支持卡片和文档）
 - ⌨️ Slash 命令
-- ⏹ `/stop` 中断任务
+- ⏹ `/stop` 中断任务（保留已有内容）
 - 👥 群聊 @ 触发
 
 ## Markdown 扩展语法
@@ -368,6 +377,97 @@ setup 不需要填 open_id，发第一条消息自动保存。
 \<u\> 显示为 <u>
 ```
 
+## 流式输出
+
+回复内容会以打字机效果逐字显示，无需等待完整输出。
+
+内部使用 FlushController：
+- **互斥守卫** — 防止并发刷新冲突
+- **自适应节流** — 根据上次刷新时间动态调整间隔
+- **长间隔批处理** — 2 秒无新内容自动 flush 剩余缓冲
+
+### 配置
+
+```yaml
+streaming:
+  enabled: true                # 是否启用流式（默认 true）
+  mode: cardkit                # update（message.patch）| cardkit | none
+  flush_interval_ms: 200       # 最小刷新间隔（毫秒）
+  thinking_enabled: false      # 是否显示 Claude 思考过程
+  fallback_on_error: true      # 失败时降级为一次性发送
+
+# 卡片标题（所有模式生效）
+card_title: Claude              # 留空则不显示 header
+
+# 图片自动解析（下载外部图片上传到飞书）
+image_resolver:
+  enabled: true                # 是否启用（默认 true）
+```
+
+### 模式说明
+
+| 模式 | 说明 | 额外权限 |
+|------|------|---------|
+| `update` | 使用消息 patch API 模拟流式 | 无（默认即可用） |
+| `cardkit` | 使用飞书 CardKit API（真正打字机效果） | `cardkit:card:write` |
+| `none` | 禁用流式，等待完整输出后一次性发送 | 无 |
+
+- `cardkit` 模式为默认模式，采用单卡片架构（对齐飞书官方 OpenClaw 方案），全程只有一个消息
+- `cardkit` 模式使用飞书 SDK CardKit 客户端（自动 token 管理、结构化错误处理）
+- `cardkit` 模式支持流式预览（summary）、工具状态栏实时展示（无需等待正文到来）、思考过程折叠面板、长内容自动溢出到云文档
+- `cardkit` 模式关闭流式采用两步操作（settings + update），对齐官方最佳实践
+- 中断时保留已有内容（正文 + 思考过程），不丢失已生成的回复
+- `update` 模式使用消息 patch API 模拟流式，会发送独立的工具调用卡片
+- 流式过程中如果内容超长，最终会自动写入云文档并回复链接
+
+### 中断
+
+流式输出过程中可以使用 `/stop` 中断，卡片会保留已生成的内容和思考过程。
+
+### 思考过程
+
+开启 `streaming.thinking_enabled: true` 后，Claude 的扩展思考过程会以折叠面板显示在回复上方：
+
+- 流式期间显示 "⏳ 思考中..." 提示
+- 完成后思考内容收起在折叠面板中，标题显示思考耗时（如 `💭 思考 3.2s`），点击可展开查看
+- 超过 3000 字的思考内容自动截断
+- 关闭时完全过滤思考内容，用户无感
+
+### 响应元数据
+
+每条回复底部自动显示耗时、模型和 token 用量：
+
+```
+⏱ 8.2s · claude-sonnet-4-6 · 1,234 tokens
+```
+
+仅显示在卡片消息中，云文档不追加。
+
+## 格式优化
+
+### 卡片自动优化
+
+发送到飞书卡片的 Markdown 会自动经过优化管线处理：
+
+1. **标题降级** — H1→H4, H2-H6→H5（飞书卡片只支持 H4/H5）
+2. **代码块保护** — 代码块内容不会被其他处理逻辑误解析
+3. **外部图片上传** — 自动下载外部图片并上传到飞书，替换为 `img_xxx` 格式（卡片和文档均支持）
+
+### 格式指导（System Prompt）
+
+默认启用，通过 Claude Code SDK 的 system prompt 注入飞书格式规范，从源头提升输出质量。整个会话只需注入一次，不重复消耗 token。
+
+```yaml
+format_guide:
+  enabled: true    # 是否启用（默认 true）
+```
+
+**自定义格式指导：**
+
+编辑 `~/.larkcc/format-guide.md` 即可覆盖默认内容。格式指导内容是纯 Markdown，你可以根据实际需求增减规则。
+
+查看默认格式指导：`resources/format-guide.md`（随项目发布）。
+
 ## 消息类型支持
 
 | 类型 | 单聊 | 群聊 |
@@ -408,6 +508,25 @@ overflow:
     threshold: 2800           # 写文档阈值
     title_template: "{cwd} - {session_id} - {datetime}"
 
+# 格式指导（从源头优化 Claude 输出质量）
+format_guide:
+  enabled: true               # 是否注入飞书格式要求到 prompt
+
+# 卡片标题
+card_title: Claude              # 留空则不显示 header
+
+# 流式输出配置
+streaming:
+  enabled: true               # 是否启用流式（默认 true）
+  mode: cardkit                # update | cardkit | none
+  flush_interval_ms: 300      # 最小刷新间隔（毫秒）
+  thinking_enabled: false     # 是否显示思考过程
+  fallback_on_error: true     # 失败时降级
+
+# 图片自动解析（下载外部图片上传到飞书）
+image_resolver:
+  enabled: true               # 是否启用（默认 true）
+
 commands:
   deploy: "部署到测试环境"
 
@@ -429,12 +548,8 @@ reaction:
   done: DONE            # 完成
   error: OnIt           # 出错
 
-# 思考状态词（随机显示）
-thinking_words:
-  - "💭 思考中..."
-  - "🔍 分析中..."
-  - "💻 编码中..."
-  # ... 更多状态词
+# 卡片标题
+card_title: Claude
 
 profiles:
   mybot:
@@ -489,9 +604,13 @@ profiles:
 
 - 支持 Markdown 格式（标题、代码块、列表等）
 
-**无效图片过滤：**
+**图片处理：**
 
-当内容包含 `blob:` 格式的无效图片 URL（如 websearch 返回的临时图片）时，系统会自动过滤并在消息末尾提示。
+- `blob:` 格式的无效图片 URL 自动过滤
+- 外部图片（`https://`）自动下载并上传到飞书，替换为内部 `img_xxx` 格式
+- 上传失败的图片降级为链接，不影响整体流程
+- 图片大小限制 10MB，下载超时 10 秒
+- 卡片和云文档均支持图片渲染
 
 **自动清理：**
 
@@ -536,19 +655,45 @@ overflow:
 
 ### 权限
 
+权限按功能分组，建议全部开通：
+
+#### 基础消息（必开）
+
 | 权限 | 用途 |
 |------|------|
-| `im:message` | 基础消息（含下载消息中的文件） |
-| `im:message:send_as_bot` | 发送消息 |
-| `im:message.p2p_msg:readonly` | 接收私聊 |
+| `im:message` | 基础消息（含下载消息中的图片、文件） |
+| `im:message:send_as_bot` | 以机器人身份发送消息、回复消息、更新消息（**流式输出也依赖此权限**） |
+| `im:message.p2p_msg:readonly` | 接收私聊消息 |
 | `im:message.group_at_msg:readonly` | 接收群 @ 消息 |
-| `im:message.reactions:write_only` | 打 reaction |
-| `cardkit:card:write` | 发送卡片 |
-| `docx:document` | 创建/编辑云文档（超长消息写入） |
-| `drive:file` | 删除云空间文件（清理旧文档） |
+| `im:message.reactions:write_only` | 打 reaction 表情（处理中/完成/出错状态） |
+
+#### 卡片与富文本
+
+| 权限 | 用途 |
+|------|------|
+| `cardkit:card:write` | 发送交互式卡片、CardKit 流式输出 |
 
 > 💡 `im:message` 权限已包含下载消息中资源文件（图片、文件）的能力
 
+#### 云文档（超长消息写入）
+
+| 权限 | 用途 |
+|------|------|
+| `docx:document` | 创建/编辑云文档（`overflow.mode: document` 时需要） |
+| `drive:file` | 删除云空间文件（自动清理旧文档时需要） |
+
+> 💡 不使用文档模式时，这两个权限可以不开
+
+#### 开通步骤
+
+1. 进入 [飞书开发者后台](https://open.feishu.cn/) → 选择你的应用
+2. 左侧菜单 **权限管理** → 搜索并开通上述权限
+3. 点击 **权限管理** 页面上方的 **权限配置** → 批量开通
+4. 创建新版本 → 申请发布（企业自建应用管理员审批即可）
+5. 发布成功后权限生效
+
+> ⚠️ 权限变更后需要重新发布应用版本，已运行的 larkcc 需要重启
+
 ### 事件订阅
 
 使用**长连接** → 订阅 `im.message.receive_v1`
@@ -748,7 +893,7 @@ You: [Error screenshot] How to fix this
 You: [Rich text with multiple images] Analyze these images
 ```
 
-> **Note:** Invalid image URLs (like `blob:` URLs from websearch) are automatically filtered.
+> **Note:** Invalid image URLs (like `blob:` URLs from websearch) are automatically filtered. External images are automatically downloaded and uploaded to Feishu for proper rendering.
 
 ## File Support
 
@@ -821,21 +966,37 @@ larkcc -p mybot             # Use specified bot
 
 ### Permissions
 
+#### Basic Messaging (Required)
+
 | Permission | Purpose |
 |------------|---------|
-| `im:message` | Basic message (including file download) |
-| `im:message:send_as_bot` | Send messages |
+| `im:message` | Basic message (including image/file download) |
+| `im:message:send_as_bot` | Send/reply/update messages (**streaming also depends on this**) |
 | `im:message.p2p_msg:readonly` | Receive direct messages |
 | `im:message.group_at_msg:readonly` | Receive group @ messages |
-| `im:message.reactions:write_only` | Add reactions |
-| `cardkit:card:write` | Send cards |
-| `docx:document` | Create/edit cloud documents |
-| `drive:file` | Delete cloud files |
+| `im:message.reactions:write_only` | Add reactions (processing/done/error status) |
+
+#### Cards
+
+| Permission | Purpose |
+|------------|---------|
+| `cardkit:card:write` | Send interactive cards, CardKit streaming |
+
+#### Cloud Documents (for overflow mode)
+
+| Permission | Purpose |
+|------------|---------|
+| `docx:document` | Create/edit cloud documents (when `overflow.mode: document`) |
+| `drive:file` | Delete cloud files (auto-cleanup of old documents) |
 
 ### Event Subscription
 
 Use **Long Connection** → Subscribe to `im.message.receive_v1`
 
+## 致谢
+
+CardKit 流式卡片实现参考了飞书官方 [openclaw-lark](https://github.com/larksuite/openclaw-lark) 项目的 API 用法与架构设计。
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md)

package/dist/agent.d.ts

@@ -4,6 +4,7 @@ export interface ImageInput {
     base64: string;
     mediaType: string;
 }
+export type RunAgentResult = "completed" | "aborted";
 export declare function runAgent(prompt: string, cwd: string, config: LarkccConfig, client: lark.Client, chatId: string, rootMsgId: string, images?: ImageInput[], abortSignal?: AbortSignal, // 可选中断信号
-profile?: string): Promise<void>;
+profile?: string): Promise<RunAgentResult>;
 export declare function ensureEnv(): void;