@jeik/dingtalk-connector 0.8.28 → 0.8.30

package/CHANGELOG.md

@@ -5,53 +5,63 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.8.28] - 2026-07-25
-
-### 主题
+## [0.8.30] - 2026-07-28
 
-基于**官方最新 0.8.24** 继续做社区增强：把连接做稳、消息少丢、错误提示更清楚。少折腾、多好用。
+### Fixes
 
-### 基于官方 0.8.24 吸收的能力
+- **incomplete_turn 误报不定格错误卡** — 上游 `final + isError` 文案为 `Agent couldn't generate a response`，但卡片已有真实答案（`lastAnswerText`/`accumulatedText` ≥20 字）时，忽略该误报，用已有答案 `closeStreaming`，不再覆盖正文/定格错误（避免网关误报后卡片停止流式）。
 
-- 更稳的长连接思路：连接建立后再挂心跳相关监听，减少「看起来连着、其实收不到消息」的假死重连
-- 机器人忙着回上一条时，处理过程中也会保持连接活跃，长回复不容易被中途掐断
-- 上游 SDK 刷屏日志过滤，控制台更干净，少误判成故障
-- 空回复时的友好提示（尤其是群聊配置不当的情况）
+## [0.8.29] - 2026-07-25
 
-> 说明：官方给其他插件用的「卡片创建/更新开放接口」本版**未合入**（对话体验不依赖它）。需要时可后续单独加。
+### 主题
 
-### 本版重点优化（效果向）
+正式版加固：默认日志更轻、排障只靠配置 `debug: true`；继承 0.8.28 连接/消息/错误卡能力。
 
-**1. 长连接更稳**
-- 只有钉钉确认「这条连接可以收机器人消息」之后，才对外显示已连接
-- 连不上会自动多试几轮，而不是假装在线
-- 正常使用时尽量不乱拆连接，减少「连发好几条消息完全没反应」
+### 变更
 
-**2. 消息更少丢、反馈更快**
-- 消息进队成功后再向钉钉确认已收到，失败可让平台重发，避免「确认了却其实没处理」
-- 同一会话排队处理更可靠：任务进行中再发消息，更容易马上出现「已排队 / 处理中」提示和思考中表情
-- 单条任务卡住太久会自动放开队列，避免后面消息永远等不到
+- 🧹 **默认静默诊断刷屏** — 无图文本回复不再输出 LocalImage / MediaIdTrace / CardCache / Quote 成功路径
+- 🔍 **debug 配置统一开关** — 顶层或账号 `"debug": true` 打开连接摘要、图片 mediaId、引用回填、队列计数等详细日志；**不再依赖环境变量**
+- 📚 **文档** — 安装命令精简为三条递进指导；README 中英同步至 0.8.29
 
-**3. 模型出错时体验更好**
-- 上游欠费、无可用线路、503 等失败时，群聊/私聊都更容易定格成清晰中文错误卡片
-- 减少卡在「正在召唤大模型…」或莫名「思考完成」却看不到原因的情况
-- 错误结束后继续发消息，响应能力明显好于旧版
+### 继承（0.8.28）
 
-**4. 社区原有增强（继续保留）**
-- 即时首响卡片、大段答案独立答案卡、图片/本地图修复、中文错误映射、强制群聊正常回复合流等
+- 基于官方 0.8.24 的长连接更稳、消息少丢、模型错误中文定稿、本仓库独有答案卡/图片能力
 
 ### 安装
 
+**npx（一键扫码，按顺序试）：**
+
 ```bash
-npx -y @jeik/dingtalk-connector@0.8.28 install --force
-openclaw gateway restart
+npx @jeik/dingtalk-connector install --force && openclaw gateway restart
+npx @jeik/dingtalk-connector@0.8.29 install --force && openclaw gateway restart
+NPM_CONFIG_REGISTRY=https://registry.npmjs.org npx @jeik/dingtalk-connector@0.8.29 install --force && openclaw gateway restart
 ```
 
-或：
+**openclaw plugins install（只装插件，按顺序试）：**
 
 ```bash
-openclaw plugins install @jeik/dingtalk-connector@0.8.28 --force
-openclaw gateway restart
+openclaw plugins install @jeik/dingtalk-connector --force && openclaw gateway restart
+openclaw plugins install @jeik/dingtalk-connector@0.8.29 --force && openclaw gateway restart
+NPM_CONFIG_REGISTRY=https://registry.npmjs.org openclaw plugins install @jeik/dingtalk-connector@0.8.29 --force && openclaw gateway restart
+```
+
+## [0.8.28] - 2026-07-25
+
+### 主题
+
+基于**官方最新 0.8.24**，并保留**本仓库独有**优化：连接更稳、消息少丢、错误提示更清楚。
+
+### 本版重点
+
+- 长连接：能收消息才显示已连接；少假死误重连
+- 消息：进队后再 ACK；排队反馈更及时
+- 错误：503 / 欠费 / 无通道等中文定稿，少卡「正在召唤大模型」
+- 本仓库独有：答案卡、图片全路径、首响等
+
+### 安装
+
+```bash
+openclaw plugins install @jeik/dingtalk-connector@0.8.28 --force && openclaw gateway restart
 ```
 
 ## [0.8.26] - 2026-07-25

package/README.en.md

@@ -2,9 +2,9 @@
   <img alt="DingTalk" src="https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-openclaw-connector/main/docs/images/dingtalk.svg" width="72" height="72" />
   <h1>dingtalk-openclaw-connector（Community Maintained Fork）</h1>
   <p>Community-enhanced fork based on official <strong>v0.8.24</strong>: adopts official long-connection improvements, plus stronger message delivery, queue feedback, and error-card UX.<br/>
-  Keeps community extras (images, answer cards, first-response UX) and continues to fix issues not yet covered upstream.</p>
+  Keeps <strong>this repo’s unique</strong> extras (images, answer cards, first-response UX) and continues to fix issues not yet covered upstream.</p>
 
-  <p><strong>Current release: <a href="https://www.npmjs.com/package/@jeik/dingtalk-connector">@jeik/dingtalk-connector</a> v0.8.28</strong> (recommended for production; install: <code>npx -y @jeik/dingtalk-connector@0.8.28 install --force</code>).</p>
+  <p><strong>Current release: <a href="https://www.npmjs.com/package/@jeik/dingtalk-connector">@jeik/dingtalk-connector</a> v0.8.30</strong></p>
 
   <p>
     <a href="https://www.npmjs.com/package/@jeik/dingtalk-connector"><img src="https://img.shields.io/npm/v/@jeik/dingtalk-connector.svg?style=flat&colorA=18181B&colorB=28CF8D" alt="npm version" /></a>
@@ -23,87 +23,89 @@
 
 ## 🔧 Recent Updates
 
-### 🚀 v0.8.28 · 2026-07-25 (current)
+### 🚀 v0.8.30 · 2026-07-29 (current)
 
-**Theme: based on official 0.8.24 · steadier connection · fewer lost messages · clearer errors**
+**Theme: production hardening · quieter logs · debug config only**
 
-Built on community enhancements, aligned with official **0.8.24** connection work, and focused on real UX: “sent but no reply”, stuck error cards, and missing “queued” feedback.
+Built on **0.8.28** (steadier connection / fewer lost messages / clearer error cards):
 
-#### From official 0.8.24
+| Experience | Effect |
+|------------|--------|
+| 🧹 **Quieter by default** | No LocalImage / MediaIdTrace / CardCache spam on normal text replies |
+| 🔍 **Simple debug** | Set `"debug": true` for connection, image, quote, and queue diagnostics (no env vars) |
+| 🔗 **Connection / queue** | Connected only when messages can be received; better multi-send and post-error recovery |
+| ⚠️ **Model failures** | 503 / billing / no-channel settle to clear Chinese cards instead of spinning forever |
+| 🃏 **This repo’s unique extras** | Answer cards, full image paths, first-response UX remain |
 
-- More reliable long-connection setup and keepalive (fewer “connected but silent” cases)
-- Long AI runs less likely to get cut mid-task by connection flapping
-- Cleaner console logs for easier ops
+### 📦 v0.8.28 · 2026-07-25
 
-#### Extra community improvements (what you’ll notice)
+Official 0.8.24-aligned connection & delivery hardening (included in 0.8.30).
 
-| Experience | Effect |
-|------------|--------|
-| 🔗 **Connection** | Marks “connected” only when the bot can actually receive messages; auto-retries instead of faking online |
-| 📩 **Fewer lost messages** | Much better after errors, after a reply finishes, or when sending several messages quickly |
-| ⏳ **Queue feedback** | While the previous message is still running, new messages more reliably show “queued / processing” + thinking reaction |
-| ⚠️ **Model failures** | Billing / no channel / 503-style failures settle into clear Chinese error cards instead of spinning forever |
-| 🃏 **Answer cards & images** | Existing community answer-card and full image-path fixes remain |
+### 📦 v0.8.26 / 0.8.25 and earlier
 
-```bash
-npx -y @jeik/dingtalk-connector@0.8.28 install --force && openclaw gateway restart
-```
+Target ID rules, sender identity, answer cards, image fixes — see [CHANGELOG.md](CHANGELOG.md).
 
-### 📦 v0.8.26 · 2026-07-25
+---
 
-Stricter outbound target ID rules (keep `==` suffixes and case).
+## 🚀 Quick Start
 
-### 📦 v0.8.25 · 2026-07-24
+### Requirements
 
-Sender role/title identity; bare DingTalk IDs as direct chat.
+- **OpenClaw** installed and running ([website](https://openclaw.ai/))
+- **Version**: OpenClaw ≥ **2026.4.9** (`openclaw -v`)
+- Same channel id as official (`dingtalk-connector`); `--force` overwrites — **no uninstall** needed
+- Always `openclaw gateway restart` after install/upgrade
 
-### 📦 v0.8.21-fix49 and earlier
+Package: [`@jeik/dingtalk-connector`](https://www.npmjs.com/package/@jeik/dingtalk-connector)
 
-Answer cards, image path fixes, streaming finalize, Chinese error mapping — see [CHANGELOG.md](CHANGELOG.md).
+### A) npx one-command QR install (try in order)
 
-Full log: [CHANGELOG.md](CHANGELOG.md) · [FIXES.md](FIXES.md)
+```bash
+# 1) Install latest
+npx @jeik/dingtalk-connector install --force && openclaw gateway restart
 
----
+# 2) If you did not get the latest, pin the version
+npx @jeik/dingtalk-connector@0.8.30 install --force && openclaw gateway restart
 
-## ✨ Enhanced Features
+# 3) If it still fails, force the official npm registry
+NPM_CONFIG_REGISTRY=https://registry.npmjs.org npx @jeik/dingtalk-connector@0.8.30 install --force && openclaw gateway restart
+```
 
-### 🖼️ Image sending: full fix & upgrade
+### B) Plugin only (credentials already set; try in order)
 
-> 🔥 **No dead corners** · mixed send paths · far beyond the official’s weak image pipeline  
-> ✅ Chat · ✅ message direct · ✅ markdown embed · ✅ split or merge layout
+```bash
+# 1) Install latest
+openclaw plugins install @jeik/dingtalk-connector --force && openclaw gateway restart
 
-Full-path image fixes — every channel below renders correctly:
+# 2) If you did not get the latest, pin the version
+openclaw plugins install @jeik/dingtalk-connector@0.8.30 --force && openclaw gateway restart
 
-| | Path | Capability |
-|--|------|------------|
-| 💬 | **Normal chat reply** | Agent embeds `![alt](…)`; upload to mediaId before finalize |
-| 📤 | **message · mediaUrl** | Proactive direct send (local / LAN / public) |
-| 📝 | **message · markdown body** | Nested `![](…)` (local / `file://` / URL) with text |
-| ⚙️ | **Configurable layout** | Default 📎 **separate**; `messageImageMd: true` → 🧩 **merge** one markdown |
+# 3) If it still fails, force the official npm registry
+NPM_CONFIG_REGISTRY=https://registry.npmjs.org openclaw plugins install @jeik/dingtalk-connector@0.8.30 --force && openclaw gateway restart
+```
 
-#### 🌐 Source types covered
+### Local tgz / from source (dev / offline)
 
-| | Type | Examples |
-|--|------|----------|
-| 🌍 | Public URL | `https://…` |
-| 🏠 | Private / LAN URL | `http://intranet/…` |
-| 📁 | Local absolute path | `/tmp/…` · `/root/…` |
-| 💾 | **`/mnt` mounts** | Chinese paths · SMB shares |
-| 🔗 | `file://` URI | `file:///mnt/…` · `file:///tmp/…` |
-| 🆔 | Existing mediaId | `@lADP…` |
+```bash
+git clone https://github.com/jeikl/dingtalk-openclaw-connector-fix-Community.git
+cd dingtalk-openclaw-connector-fix-Community
+npm install && npm run build && npm pack
+openclaw plugins install ./jeik-dingtalk-connector-0.8.30.tgz --force && openclaw gateway restart
+```
 
-#### 🛡️ Extra safeguards
+### Smoke check
 
-- 📦 Code-block / inline-code paths are **not** uploaded
-- ⬇️ Remote: **download then upload**; local: **`/tmp` retry** on failure
-- 🫧 Image + download link in **one bubble**: `![]` → mediaId, URL kept as-is
+```bash
+openclaw -v
+openclaw plugins list
+# Send a DingTalk message — first “summoning model…”, then streaming / answer card
+```
 
-### 🎨 AI Card template
+---
 
-- ✨ Custom stream cards; **if `cardTemplateId` is omitted**, defaults to  
-  `0d2c84b3-12c1-473b-b14a-f329a7a102cd.schema` (📋 copy button, etc.)
+## ⚙️ Configuration
 
-### ⚙️ Minimal config
+### Minimal config
 
 ```json
 "channels": {
@@ -121,8 +123,6 @@ Defaults apply: stream card `0d2c84b3-…schema`, session answer card on, messag
 
 ### Maximal config (for illustration; defaults written out)
 
-**Single Agent** and **multi Agent** (all values are defaults — **not extra features**).
-
 **Single Agent (top-level credentials):**
 
 ```json
@@ -197,12 +197,64 @@ Defaults apply: stream card `0d2c84b3-…schema`, session answer card on, messag
 | `answerCardTemplateId` | string | `d246b7f5-1783-4e9b-bb46-bef52d63050e.schema` | Static answer card template |
 | `messageAnswerCard` | boolean | **true** | message-tool body via answer card; `false` = plain message |
 | `messageImageMd` | boolean | **false** | message images: separate vs merge markdown |
+| `debug` | boolean | **false** | Verbose diagnostics (connection / image mediaId / quote / queue). **Off in production**; set `true` then restart gateway |
 
 > `answerCard` = conversation finalize; `messageAnswerCard` = message-tool outbound.
 
+**Temporary debug example:**
+
+```json
+"channels": {
+  "dingtalk-connector": {
+    "enabled": true,
+    "clientId": "…",
+    "clientSecret": "…",
+    "debug": true
+  }
+}
+```
+
 ---
 
-## 🎯 Reply markers + Answer card + Tool progress (core enhancements)
+## ✨ Enhanced Features
+
+### 🖼️ Image sending: full fix & upgrade
+
+> 🔥 **No dead corners** · mixed send paths · far beyond the official’s weak image pipeline  
+> ✅ Chat · ✅ message direct · ✅ markdown embed · ✅ split or merge layout
+
+Full-path image fixes — every channel below renders correctly:
+
+| | Path | Capability |
+|--|------|------------|
+| 💬 | **Normal chat reply** | Agent embeds `![alt](…)`; upload to mediaId before finalize |
+| 📤 | **message · mediaUrl** | Proactive direct send (local / LAN / public) |
+| 📝 | **message · markdown body** | Nested `![](…)` (local / `file://` / URL) with text |
+| ⚙️ | **Configurable layout** | Default 📎 **separate**; `messageImageMd: true` → 🧩 **merge** one markdown |
+
+#### 🌐 Source types covered
+
+| | Type | Examples |
+|--|------|----------|
+| 🌍 | Public URL | `https://…` |
+| 🏠 | Private / LAN URL | `http://intranet/…` |
+| 📁 | Local absolute path | `/tmp/…` · `/root/…` |
+| 💾 | **`/mnt` mounts** | Chinese paths · SMB shares |
+| 🔗 | `file://` URI | `file:///mnt/…` · `file:///tmp/…` |
+| 🆔 | Existing mediaId | `@lADP…` |
+
+#### 🛡️ Extra safeguards
+
+- 📦 Code-block / inline-code paths are **not** uploaded
+- ⬇️ Remote: **download then upload**; local: **`/tmp` retry** on failure
+- 🫧 Image + download link in **one bubble**: `![]` → mediaId, URL kept as-is
+
+### 🎨 AI Card template
+
+- ✨ Custom stream cards; **if `cardTemplateId` is omitted**, defaults to  
+  `0d2c84b3-12c1-473b-b14a-f329a7a102cd.schema` (📋 copy button, etc.)
+
+### 🎯 Reply markers + Answer card + Tool progress
 
 These make the "process → final answer" rendering on DingTalk cleaner and more stable, working around DingTalk's official streaming AI Card bug:
 
@@ -232,80 +284,12 @@ Community contributions (features & bug fixes) are always welcome — submit a P
 
 | Item | Description |
 |------|-------------|
-| Base | Official v0.8.20, fully identical features |
-| Fixes | Bugs the official team hasn't addressed (see recent fixes above) |
+| Base | Aligned with official **v0.8.24** long-connection work + this repo’s unique extras |
+| Fixes | Silent connection, lost messages, stuck error cards, grey images, etc. |
 | Maintenance | Community maintained, continuously tracking official updates |
 
 ---
 
-## Requirements & Installation
-
-Before you start, make sure you have:
-
-- **OpenClaw**: Installed and running properly. Visit the [OpenClaw website](https://openclaw.ai/) for details.
-- **Version**: OpenClaw ≥ **2026.4.9**. Check with `openclaw -v`.
-
-> If below this version, upgrade with: `npm install -g openclaw`
-
----
-
-## Installation
-
-> Same channel id as the official plugin (`dingtalk-connector`); `--force` overwrites in place — **no uninstall** needed.  
-> **Current stable: `0.8.21-fix31`** (npm `latest`). Always run `openclaw gateway restart` after install/upgrade.
-
-### Option 1: npm (recommended)
-
-Package: [`@jeik/dingtalk-connector`](https://www.npmjs.com/package/@jeik/dingtalk-connector)
-
-**1) One-command QR install** (bot → credentials → plugin → config):
-
-```bash
-npx -y @jeik/dingtalk-connector install
-
-# force overwrite when a local dingtalk-connector already exists
-npx -y @jeik/dingtalk-connector install --force
-```
-
-**2) Plugin only** (credentials already set / manual setup):
-
-```bash
-openclaw plugins install @jeik/dingtalk-connector --force
-openclaw gateway restart
-```
-
-**3) Upgrade to latest:**
-
-```bash
-openclaw plugins install @jeik/dingtalk-connector --force
-openclaw gateway restart
-```
-
-### Option 2: Local tgz / from source (dev / offline)
-
-```bash
-git clone https://github.com/jeikl/dingtalk-openclaw-connector-fix-Community.git
-cd dingtalk-openclaw-connector-fix-Community
-# optional: pin a release (this is a git tag, not a branch)
-# git fetch --tags && git checkout v0.8.21-fix31
-
-npm install && npm run build && npm pack
-# → jeik-dingtalk-connector-0.8.21-fix31.tgz
-
-openclaw plugins install ./jeik-dingtalk-connector-0.8.21-fix31.tgz --force
-openclaw gateway restart
-```
-
-### Smoke check
-
-```bash
-openclaw -v
-openclaw plugins list
-# Send a DingTalk message — you should first see "🦸 正在召唤大模型…" then streaming reply
-```
-
----
-
 ## Usage Guide
 
 [OpenClaw DingTalk Plugin User Guide](https://alidocs.dingtalk.com/i/nodes/2Amq4vjg89GEno0zfPqoPGqdV3kdP0wQ?utm_scene=team_space)
@@ -338,4 +322,4 @@ This project is licensed under the [MIT](LICENSE) License.
 ## Support
 
 - **Issues**: [GitHub Issues](https://github.com/jeikl/dingtalk-openclaw-connector-fix-Community/issues)
-- **Changelog**: [CHANGELOG.md](CHANGELOG.md)
+- **Changelog**: [CHANGELOG.md](CHANGELOG.md)