test-mirror-qqbot 1.5.5

package/CHANGELOG.md

@@ -0,0 +1,165 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [1.6.4] - 2026-03-20
+
+### Added
+
+- **One-click hot upgrade `/bot-upgrade`**: Upgrade the plugin directly from private chat — no server login needed. Supports `--latest` (upgrade to latest), `--version X` (specific version), and `--force` (force reinstall). Version existence is verified against npm before proceeding.
+- **Channel API proxy tool `qqbot_channel_api`**: AI can call QQ Open Platform channel HTTP APIs directly with automatic Token authentication and SSRF protection. Supports guild/channel management, member queries, forum threads, announcements, schedules, and more.
+- **Credential backup protection**: New `credential-backup.ts` module auto-saves `appId`/`clientSecret` to a standalone file before hot upgrade. `isConfigured` now falls back to backup check — if config is lost but backup exists, the account still starts and credentials are auto-restored.
+- **Command usage help**: All slash commands support `?` suffix to show detailed usage (e.g. `/bot-upgrade ?`).
+
+### Changed
+
+- **Real-time version check**: `getUpdateInfo()` changed from synchronous cache to `async` live npm registry query — every `/bot-version` or `/bot-upgrade` call fetches the latest data.
+- **`/bot-logs` multi-source aggregation**: Long logs are auto-truncated with explanation.
+
+### Improved
+
+- **`switchPluginSourceToNpm` post-write validation**: Verifies `channels.qqbot` data integrity before writing back to `openclaw.json`, preventing race-condition credential loss.
+- **Upgrade scripts with credential backup**: `upgrade-via-npm.sh` and `upgrade-via-source.sh` now save credential snapshots before upgrading.
+
+## [1.6.3] - 2026-03-18
+
+### Changed
+
+- **Update checker: HTTPS-native with multi-registry fallback**: Replaced `npm view` CLI call with direct HTTPS requests to npm registry API; supports automatic fallback from npmjs.org to npmmirror.com, solving network issues in mainland China.
+- **Upgrade script multi-registry fallback**: `upgrade-via-npm.sh` now tries npmjs.org → npmmirror.com → default registry in sequence, improving upgrade reliability in restricted networks.
+
+## [1.6.2] - 2026-03-18
+
+### Changed
+
+- **Markdown-aware text chunking**: Replaced custom `chunkText` with SDK built-in `chunkMarkdownText`, supporting auto code-fence close/reopen, bracket awareness, etc.
+- **Enable block streaming**: Set `blockStreaming: true` — the framework now collects streamed responses and delivers via the `deliver` callback.
+- **Reduce text chunk limit**: `textChunkLimit` lowered from 20000 to 5000 for better message readability.
+- **Silent media errors**: Media send failures (image/voice/video/file) are now logged only; error messages are no longer surfaced to the user.
+
+### Improved
+
+- **Ref-index content untruncated**: Removed `MAX_CONTENT_LENGTH` cap when storing quoted-message content, preserving full message body in ref-index store.
+
+### Removed
+
+- `MSG` constants and `formatMediaErrorMessage` from `user-messages.ts` — plugin layer no longer generates user-facing error text.
+
+## [1.6.1] - 2026-03-18
+
+### Improved
+
+- **Upgrade script auto-restart**: `upgrade-via-npm.sh` now automatically restarts the gateway after upgrade to apply the new version immediately.
+- **Increase text chunk limit**: Raised `textChunkLimit` from 2000 to 20000, allowing longer messages to be sent without splitting.
+- **Remove proactive update push**: Removed the auto-push notification to admin when a new version is detected; version info is now only available passively via `/bot-version` and `/bot-upgrade` commands, reducing noise.
+
+### Removed
+
+- `onUpdateFound` callback and `formatUpdateNotice` helper from `update-checker.ts` — no longer needed after removing proactive push.
+
+## [1.6.0] - 2026-03-16
+
+### Added
+
+- **Slash command system**: `/bot-ping`, `/bot-version`, `/bot-help`, `/bot-upgrade`, `/bot-logs` — five plugin-level slash commands.
+- **Update checker**: Background npm version check with update status in `/bot-version` and upgrade guide in `/bot-upgrade`.
+- **Startup greeting**: Distinguish first install vs. restart with different greeting messages.
+- **Log download**: `/bot-logs` packages the last 2000 lines of logs and sends as a file.
+
+### Changed
+
+- **Unified rich media tag**: Replaced `<qqimg>`, `<qqvoice>`, `<qqfile>`, `<qqvideo>` with a single `<qqmedia>` tag — the system auto-detects media type by file extension.
+
+### Improved
+
+- **Greeting debounce**: Suppress duplicate greetings within 60s during rapid restarts (e.g. upgrades).
+- **Proactive message 48h filter**: Skip users inactive for 48h+ when sending startup greetings, reducing 500 errors.
+- **Token cache refresh threshold**: Changed from hardcoded 5-minute early refresh to `min(5min, remaining/3)`, fixing repeated token requests when API returns short-lived tokens.
+- **Streamlined context injection**: Reduced redundant context injected into OpenClaw, lowering token consumption.
+
+## [1.5.7] - 2026-03-12
+
+### Added
+
+- Add quoted-message context pipeline for QQ `REFIDX_*`: parse quote indices from inbound events, cache inbound/outbound message summaries, and inject quote body into agent context.
+- Add persistent quote index store (`~/.openclaw/qqbot/data/ref-index.jsonl`) with in-memory cache + JSONL append, restart recovery, 7-day TTL eviction, and compact.
+- Add structured quote attachment summaries (image/voice/video/file, local path/url, voice transcript source) for better reply grounding.
+
+### Improved
+
+- Bot replies now attach quote reference to the user's current message when available, improving threaded conversation readability in QQ.
+
+## [1.5.6] - 2026-03-10
+
+### Added
+
+- Add voice input summary log with STT/ASR/fallback source counters and ASR text preview for debugging voice pipeline.
+- Add `asr_refer_text` fallback support — when STT is not configured or fails, use QQ platform's built-in ASR text as low-confidence fallback.
+- Pass voice-related metadata (`QQVoiceAsrReferTexts`, `QQVoiceTranscriptSources`, `QQVoiceInputStrategy`, etc.) to agent context.
+- Add scheduled reminder (proactive message) section to README with demo screenshot.
+- Normalize `appId` parsing to support both numeric and string values across runtime and proactive scripts.
+
+### Fixed
+
+- Fix voice prompt hints to distinguish STT-configured vs. unconfigured states and add ASR fallback / voice forward guidance.
+
+## [1.5.5] - 2026-03-09
+
+### Added
+
+- Add `npm-upgrade.sh` script for npm-based plugin installation and upgrade.
+  - Supports `--tag` and `--version` options, defaults to `@alpha`.
+  - Handles channel config backup/restore, old plugin cleanup (including legacy variants like `qqbot`, `@sliverp/qqbot`), and gateway restart.
+  - Temporarily removes `channels.qqbot` before install to avoid `unknown channel id` validation error.
+
+### Fixed
+
+- Fix plugin id not matching package name, causing plugin load failure.
+- Fix `normalizeTarget` return type — now returns structured `{ok, to, error}` object.
+- Fix outdated repo URL references in `pull-latest.sh` and `upgrade.sh`.
+- Fix `proactive-api-server.ts` / `send-proactive.ts` hardcoded config file paths.
+- Fix `set-markdown.sh` `read` missing timeout causing hang in non-interactive environments.
+
+### Improved
+
+- Scripts now fully compatible with multiple CLIs (openclaw / clawdbot / moltbot) with auto-detection of config file paths.
+- `upgrade-and-run.sh` now shows clear prompt when AppID/Secret is missing on first run.
+- `upgrade-and-run.sh` now displays qqbot plugin version before and after upgrade.
+
+## [1.5.4] - 2026-03-08
+
+### Fixed
+
+- Fix Token collision in multi-account concurrent mode — refactored global Token cache from a single variable to a per-`appId` `Map`, resolving `11255 invalid request` errors when multiple bots run simultaneously.
+- Per-instance background Token refresh — `clearTokenCache()` and `stopBackgroundTokenRefresh()` now accept an `appId` parameter for independent per-account management.
+- Fix `openclaw message send` failing for non-default accounts — without `--account`, `accountId` always fell back to `"default"`, causing a 500 error when sending to an OpenID belonging to a different bot.
+
+### Added
+
+- Multi-account documentation — added "Multi-Account Setup" section to README.
+- Enhanced debug logging — `[qqbot:channel]` prefixed logs in `channel.ts`, covering account resolution, message sending, and gateway startup.
+- API log prefix — all API request logs now include `[qqbot-api:${appId}]` prefix for easier multi-instance debugging.
+
+## [1.5.3] - 2026-03-06
+
+### Fixed
+
+- Improved rich media tag parsing logic for higher recognition success rate.
+- Fixed file encoding issues and special path handling that prevented file sending.
+- Fixed intermittent message loss caused by duplicate message seq numbers.
+
+### Improved
+
+- Upgrade script now auto-backs up and restores qqbot channel config during upgrades.
+- Updated README with rich media usage instructions and plugin config/upgrade tutorial.
+
+## [1.5.2] - 2026-03-05
+
+### Added
+
+- Voice/file sending capability with TTS text-to-speech support.
+- Rich media enhancements: upload caching, video support, automatic retry on failure.
+- Markdown messages enabled by default.
+- Standalone upgrade script with user choice of foreground/background startup.

package/CHANGELOG.zh.md

@@ -0,0 +1,165 @@
+# 更新日志
+
+本文件记录项目的所有重要变更。
+
+格式参考 [Keep a Changelog](https://keepachangelog.com/)。
+
+## [1.6.4] - 2026-03-20
+
+### 新增
+
+- **一键热更新指令 `/bot-upgrade`**：在私聊中直接完成版本升级，无需登录服务器。支持 `--latest`（升级到最新）、`--version X`（指定版本）、`--force`（强制重装）参数。升级前自动校验版本是否存在于 npm。
+- **频道 API 代理工具 `qqbot_channel_api`**：AI 可直接调用 QQ 开放平台频道 HTTP 接口，自动 Token 鉴权，内置 SSRF 防护。支持频道/子频道管理、成员查询、论坛发帖、公告发布、日程管理等操作。
+- **凭证备份保护**：新增 `credential-backup.ts` 模块，热更新前自动备份 `appId`/`clientSecret` 到独立文件。`isConfigured` 增加备份兜底检查——配置丢失但备份存在时仍可启动并自动恢复凭证。
+- **指令用法查询**：所有斜杠指令支持 `?` 后缀查看详细用法（如 `/bot-upgrade ?`）。
+
+### 变更
+
+- **版本检查改为实时查询**：`getUpdateInfo()` 从同步缓存改为 `async` 实时请求 npm registry，每次调用 `/bot-version` 或 `/bot-upgrade` 都拿最新数据。
+- **`/bot-logs` 支持多日志源聚合**：超长日志自动截断并附带说明。
+
+### 改进
+
+- **`switchPluginSourceToNpm` 写后校验**：写回 `openclaw.json` 前验证 `channels.qqbot` 数据未被破坏，防止竞态写入导致凭证丢失。
+- **升级脚本增加凭证备份逻辑**：`upgrade-via-npm.sh` 和 `upgrade-via-source.sh` 升级前自动保存凭证快照。
+
+## [1.6.3] - 2026-03-18
+
+### 变更
+
+- **版本检查改用 HTTPS 原生请求 + 多 registry 兜底**：使用 HTTPS 直接请求 npm registry API 替代 `npm view` CLI 调用；支持 npmjs.org → npmmirror.com 自动降级，解决国内网络环境下版本检查失败的问题。
+- **升级脚本多 registry 兜底**：`upgrade-via-npm.sh` 现在依次尝试 npmjs.org → npmmirror.com → 默认 registry，提升受限网络下的升级可靠性。
+
+## [1.6.2] - 2026-03-18
+
+### 变更
+
+- **Markdown 感知文本分块**：使用 SDK 内置 `chunkMarkdownText` 替代自定义分块函数，支持代码块自动关闭/重开、括号感知等。
+- **启用块流式（blockStreaming）**：设置 `blockStreaming: true`，框架收集流式响应后通过 `deliver` 回调统一发送。
+- **降低文本分块上限**：`textChunkLimit` 从 20000 调整为 5000，提升消息可读性。
+- **静默媒体发送错误**：图片/语音/视频/文件发送失败时仅写日志，不再向用户展示错误提示。
+
+### 改进
+
+- **引用内容不再截断**：移除存储引用消息时的 `MAX_CONTENT_LENGTH` 截断，保留完整消息原文。
+
+### 移除
+
+- 移除 `user-messages.ts` 中的 `MSG` 常量和 `formatMediaErrorMessage` 函数——插件层不再生成面向用户的错误提示。
+
+## [1.6.1] - 2026-03-18
+
+### 改进
+
+- **升级脚本自动重启**：`upgrade-via-npm.sh` 升级完成后自动重启网关，使新版本立即生效。
+- **提高文本分块上限**：`textChunkLimit` 从 2000 提升至 20000，允许更长的消息不被拆分发送。
+- **移除主动推送更新通知**：不再在检测到新版本时主动推送通知给管理员，版本信息仅通过 `/bot-version` 和 `/bot-upgrade` 指令被动查询，减少消息打扰。
+
+### 移除
+
+- 移除 `update-checker.ts` 中的 `onUpdateFound` 回调和 `formatUpdateNotice` 辅助函数（主动推送移除后不再需要）。
+
+## [1.6.0] - 2026-03-16
+
+### 新增
+
+- **斜杠指令体系**：新增 `/bot-ping`、`/bot-version`、`/bot-help`、`/bot-upgrade`、`/bot-logs` 五个插件级指令。
+- **版本检查**：后台定时检查 npm 最新版本，`/bot-version` 展示更新状态，`/bot-upgrade` 提供升级指引。
+- **启动问候语**：区分首次安装与普通重启，发送不同问候语。
+- **日志下载**：`/bot-logs` 打包最近 2000 行日志发送文件给用户。
+
+### 变更
+
+- **统一富媒体标签**：将 `<qqimg>`、`<qqvoice>`、`<qqfile>`、`<qqvideo>` 统一为 `<qqmedia>` 标签，系统根据文件扩展名自动识别媒体类型。
+
+### 改进
+
+- **问候语防抖**：60s 内重复重启不再重复发送问候语（解决升级过程中刷屏问题）。
+- **主动消息 48h 过滤**：发送启动问候前过滤超过 48h 未交互的用户，减少无效 500 错误。
+- **Token 缓存刷新阈值**：从硬编码 5 分钟改为 `min(5min, remaining/3)`，修复短有效期 token 缓存失效导致每分钟重复请求的问题。
+- **精简上下文注入**：优化注入给 OpenClaw 的上下文信息，减少冗余内容，降低 token 消耗。
+
+## [1.5.7] - 2026-03-12
+
+### 新增
+
+- 新增 QQ `REFIDX_*` 引用消息上下文链路：从入站事件解析引用索引，缓存入站/出站消息摘要，并将引用内容注入 agent 上下文。
+- 新增引用索引持久化存储（`~/.openclaw/qqbot/data/ref-index.jsonl`）：采用内存缓存 + JSONL 追加写，支持重启恢复、7 天 TTL 淘汰与 compact 压缩。
+- 新增结构化引用附件摘要（图片/语音/视频/文件、local path/url、语音转录来源），提升引用回复语义完整性。
+
+### 改进
+
+- 机器人回复在可用时自动挂载对当前用户消息的引用，提升 QQ 会话串联可读性。
+
+## [1.5.6] - 2026-03-10
+
+### 新增
+
+- 新增语音输入汇总日志，包含 STT/ASR/fallback 来源计数和 ASR 文本预览，便于调试语音处理链路。
+- 新增 `asr_refer_text` 兜底支持——当 STT 未配置或转写失败时，使用 QQ 平台内置 ASR 文本作为低置信度兜底。
+- 向 agent 上下文传递语音相关元数据（`QQVoiceAsrReferTexts`、`QQVoiceTranscriptSources`、`QQVoiceInputStrategy` 等）。
+- README 新增定时提醒（主动消息）功能说明及演示截图。
+- 统一 `appId` 解析逻辑，同时支持数值和字符串类型（涵盖运行时和主动消息脚本）。
+
+### 修复
+
+- 修复语音 prompt 提示，区分 STT 已配置/未配置状态，并增加 ASR 兜底和语音转发引导说明。
+
+## [1.5.5] - 2026-03-09
+
+### 新增
+
+- 新增 `npm-upgrade.sh` 脚本，支持通过 npm 包安装和升级插件。
+  - 支持 `--tag` 和 `--version` 选项，默认安装 `@alpha`。
+  - 自动处理通道配置备份/恢复、旧插件清理（包括 `qqbot`、`@sliverp/qqbot`、`openclaw-qqbot`、"@tencent-connect/openclaw-qqbot" 等历史版本）、网关重启。
+  - 安装前临时移除 `channels.qqbot` 配置，避免 `unknown channel id` 校验错误。
+
+### 修复
+
+- 修复插件 ID 与包名不一致导致插件加载失败的问题。
+- 修复 `normalizeTarget` 返回类型——现在返回结构化的 `{ok, to, error}` 对象。
+- 修复 `pull-latest.sh` 和 `upgrade.sh` 中过时的仓库 URL 引用。
+- 修复 `proactive-api-server.ts` / `send-proactive.ts` 中硬编码的配置文件路径。
+- 修复 `set-markdown.sh` 的 `read` 命令缺少超时参数，在非交互式环境下导致挂起的问题。
+
+### 改进
+
+- 脚本现已完全兼容多种 CLI（openclaw / clawdbot / moltbot），支持自动检测配置文件路径。
+- `upgrade-and-run.sh` 首次运行时若缺少 AppID/Secret，现在会显示清晰的提示。
+- `upgrade-and-run.sh` 升级前后现在会显示 qqbot 插件版本号。
+
+## [1.5.4] - 2026-03-08
+
+### 修复
+
+- 修复多账户并发模式下的 Token 冲突——将全局 Token 缓存从单一变量重构为按 `appId` 隔离的 `Map`，解决多机器人同时运行时的 `11255 invalid request` 错误。
+- 按实例独立刷新后台 Token——`clearTokenCache()` 和 `stopBackgroundTokenRefresh()` 现在接受 `appId` 参数，实现各账户独立管理。
+- 修复非默认账户使用 `openclaw message send` 发送失败的问题——不指定 `--account` 时 `accountId` 始终回退到 `"default"`，导致向其他机器人的 OpenID 发消息时返回 500 错误。
+
+### 新增
+
+- 多账户配置文档——在 README 中新增"多账户配置"章节。
+- 增强调试日志——`channel.ts` 中的日志添加 `[qqbot:channel]` 前缀，覆盖账户解析、消息发送和网关启动流程。
+- API 日志前缀——所有 API 请求日志现在包含 `[qqbot-api:${appId}]` 前缀，方便多实例调试。
+
+## [1.5.3] - 2026-03-06
+
+### 修复
+
+- 优化富媒体标签解析逻辑，提高识别成功率。
+- 修复文件编码和特殊路径处理问题导致无法发送文件的问题。
+- 修复消息 seq 号重复导致的间歇性消息丢失问题。
+
+### 改进
+
+- 升级脚本现在会在升级过程中自动备份和恢复 qqbot 通道配置。
+- 更新 README，添加富媒体使用说明和插件配置/升级教程。
+
+## [1.5.2] - 2026-03-05
+
+### 新增
+
+- 语音/文件发送能力，支持 TTS 文字转语音。
+- 富媒体增强：上传缓存、视频支持、失败自动重试。
+- 默认启用 Markdown 消息格式。
+- 独立升级脚本，支持用户选择前台/后台启动。

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 sliverp
+Copyright (c) 2026 Tencent Connect
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.