@dingxiang-me/openclaw-wechat 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -4,6 +4,78 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-03-15
+
+### Added
+- 文档与发布说明已收口为插件侧接入路径：默认推荐 `installer / quickstart / doctor`，`openclaw channels add --channel wecom --use-env` 仅保留为高级 env-backed 初始化路径
+- 新增官方 / sunnoy 风格配置兼容：支持顶层与账户级 `botId`、`secret`、`network.egressProxyUrl`、`network.apiBaseUrl`
+- `wecom:migrate` 现在会识别 flat `botId/secret` 与 `network.*`，并生成归一化到 `bot.longConnection.*`、`outboundProxy`、`apiBaseUrl` 的 patch
+- `wecom:migrate` / `wecom:doctor` 新增 `migrationSource`，可区分 `official-wecom / sunnoy-wecom / legacy-openclaw-wechat / mixed-source`
+- `wecom:doctor` 新增 `--fix / --confirm-fix`，可先应用本地可落盘的 migration/plugin patch，再用修正后的配置重跑 doctor
+- `openclaw.plugin.json` schema 新增上述兼容字段声明，避免被严格校验误判成 inline 账户
+- `delivery.reasoning.mode/title/maxChars`，可控制 WeCom `<think>` / reasoning 内容分离显示、合并到最终回复或隐藏
+- `delivery.replyFormat`，支持 `auto / text / markdown`，可按链路保留 markdown 或自动回退纯文本
+- 最终回复支持 `MEDIA:` / `FILE:` 指令；Bot / Agent 会自动隐藏指令行并回传对应媒体
+- Pending Reply 新增可选持久化，支持把可靠投递状态落盘并在 gateway 重启后恢复
+- `wecom:selfcheck`、`wecom:agent:selfcheck`、`wecom:bot:selfcheck` 新增 persistence / reasoning 摘要
+- channel metadata 新增结构化 quickstart modes，可直接暴露 `bot_long_connection / agent_callback / hybrid` 三种 starter config
+- 新增 `npm run wecom:quickstart`，可打印或合并写入 starter config，并自动备份原 `openclaw.json`
+- quickstart 新增群策略模板：`inherit / mention_only / open_direct / allowlist_template / deny`，支持用 `--group-profile` 直接生成常见群策略配置
+- 新增显式群聊准入策略：`groupPolicy`、`groupChat.policy`、`groups.<chatId>.policy`，支持 `open / allowlist / deny`
+- `/status` 与 selfcheck 新增群策略诊断摘要，直接显示当前命中的群规则来源、触发模式和白名单是否处于生效状态
+- quickstart 新增 setup plan：可直接产出 `placeholders / setupChecklist / warnings`，并通过 runtime metadata 暴露 `supportsSetupPlan / setupCommand / writeCommand`
+- quickstart 新增 `--wizard` 交互式向导，可逐步选择 mode / dm / group profile，并在最后确认是否写入配置
+- quickstart 新增 `--run-checks / --force-checks`，可直接串起推荐 selfcheck，并在 JSON 输出里返回 `postcheck` 摘要
+- quickstart `postcheck` 新增 remediation 归纳，会把常见失败信号翻译成下一步修复建议
+- quickstart `postcheck` 新增 `repairArtifacts`，可直接产出最小 `configPatch` 与 `.env` 模板，减少手工补配置
+- quickstart 新增 `--repair-dir`，可把 `repairArtifacts` 直接落盘为 `wecom.config-patch.json`、`wecom.account-patch.json`、`wecom.env.template`
+- quickstart 新增 `--apply-repair`，可把生成的 repair patch 直接 merge 到目标 `openclaw.json` 并保留备份
+- quickstart 新增 `--confirm-repair`，可先预览将要变更的字段，再确认是否真正应用 repair patch
+- quickstart setup plan / `--json` 新增 `actions`、`installState`、`migrationState`，便于 CLI / UI 直接消费接入闭环动作
+- quickstart `postcheck` 新增 `repairPlan`，会结构化列出 repair 的配置变更、env 变更和预计文件输出
+- `repairApply` / starter `write` 新增 `changedPaths`，可直接看到真实落盘的字段
+- 新增 `npm run wecom:migrate`，可独立盘点 `legacy_config / mixed_layout / stale_package` 并生成迁移 patch 与 env 模板
+- 新增 `npm run wecom:doctor`，可统一聚合 migration、自检、Agent/Bot E2E、Bot 长连接探针和公网回调矩阵
+- 新增单独安装器包 `@dingxiang-me/openclaw-wecom-cli`，支持 `npx -y @dingxiang-me/openclaw-wecom-cli install`
+- 外部安装器 `install --json` 现在会输出 `migration.guide`、legacy 字段路径和回滚命令，并支持 `--confirm-doctor-fix / --no-doctor-fix / --yes`
+- 外部安装器 `install --json` 新增结构化 `actions`，可直接消费来源审阅、迁移 patch、回滚和重跑 doctor 的动作列表
+- 外部安装器在未显式传 `--mode` 时，会按来源和当前配置能力自动选择 `bot_long_connection / agent_callback / hybrid`，并在 `sourceProfile` 里解释决策
+- 外部安装器 `sourceProfile` 新增来源专属 `checkOrder / repairDefaults`；官方 / legacy 来源默认自动附带 `doctor --fix`，sunnoy / mixed-source 默认先给修复建议
+- quickstart `--json` 新增 `sourcePlaybook`，会按当前来源返回推荐检查顺序、占位项提示和默认 repair 策略
+- quickstart metadata 新增 `supportsActions / supportsMigration / supportsRepairPlan / supportsConfirmRepair / migrationCommand`
+- 新增 `npm run test:e2e:local`，黑盒验证本地 `install -> doctor -> fix -> rerun` 闭环
+- 新增 `npm run test:release`，统一检查 root 包、installer CLI、manifest、运行时版本常量和 `npm pack --dry-run` 产物
+- CI 新增 `Onboarding E2E` 与 `Release Check` 两条门禁；tag 发布新增 release workflow，顺序发布插件包与 installer CLI
+- WeCom 插件新增 `setup.applyAccountConfig / applyAccountName / validateInput`，`openclaw channels add --channel wecom --use-env` 现在可用
+- `channels add` 文档补充为 env-backed WeCom 初始化路径，并明确剩余限制来自 OpenClaw core 当前通用参数集合
+
+### Changed
+- WeCom API token / send / media / doc 链路现在统一支持自定义 `apiBaseUrl`
+- `wecom:selfcheck`、`wecom:agent:selfcheck`、`wecom:bot:selfcheck` 已补齐这些兼容字段的识别，不再把它们误判成 legacy inline 账号
+- Bot fallback、Agent 最终回复和 `/status` 现在都会按 reasoning 策略统一处理可见文本与思考内容
+- 可靠投递状态存储支持导出/恢复，Pending Reply 不再局限于纯内存生命周期
+- package.json / openclaw.plugin.json / runtime channel meta 的接入元数据已同步，便于 installer / quickstart / doctor 和后续集成入口直接消费
+- package.json / openclaw.plugin.json / runtime channel meta 现在会同时暴露 `supportsDoctor / doctorCommand`
+- package metadata / runtime quickstart 现在会同时暴露 `supportsExternalInstaller / installerSpec / installerCommand`
+- 群聊发送者校验不再只依赖 `allowFrom` 是否非空推断；`/status`、manifest、UI schema 与运行时现在统一展示显式 `groupPolicy`
+- selfcheck 的 legacy inline 账号发现保留字同步补齐 `groupPolicy/groupAllowFrom/groups`，避免把群策略字段误判成账号 ID
+- `wecom:selfcheck` 现在会直接显示 install / migration 状态，并在检测到 legacy 布局时指向 `npm run wecom:migrate -- --json`
+- 版本一致性回归不再硬编码具体版本号，改为强校验 root 包、CLI 包、manifest 与运行时常量同步
+
+## [2.2.0] - 2026-03-14
+
+### Added
+- 新增 WeCom 可靠投递状态跟踪，统一记录 `24h` 回复窗口、主动发送额度和当前会话/账户的 Pending Reply 数量
+- 新增 Pending Reply 队列与重试管理器，支持失败最终回复的定时补发和“下次入站优先补发”
+- `/status` 新增可靠投递摘要，直接展示窗口状态、额度状态和最近失败原因
+- `wecom:selfcheck`、`wecom:agent:selfcheck`、`wecom:bot:selfcheck` 新增 `reliable-delivery` 摘要
+
+### Changed
+- WeCom Bot delivery router 现在会输出标准化 `deliveryStatus`，区分 `delivered / rejected_window / rejected_quota / rejected_transport / rejected_target / rejected_unknown`
+- Agent 最终文本回复和超时后的 late reply / timeout fallback 统一接入可靠投递链路
+- 配置 schema 新增 `channels.wecom.delivery.pendingReply.*` 与 `channels.wecom.delivery.quotaTracking.enabled`
+- 仓库、manifest 与运行时版本号统一升级到 `2.2.0`
+
 ## [2.1.0] - 2026-03-14
 
 ### Added

package/README.en.md

@@ -10,7 +10,7 @@ OpenClaw-Wechat is an OpenClaw channel plugin for Enterprise WeChat (WeCom), wit
 
 ## Table of Contents
 
-- [Onboarding Update (v2.1.0)](#onboarding-update-v210)
+- [Reliable Delivery Update (v2.2.0)](#reliable-delivery-update-v220)
 - [Highlights](#highlights)
 - [Mode Comparison](#mode-comparison)
 - [5-Minute Quick Start](#5-minute-quick-start)
@@ -28,27 +28,29 @@ OpenClaw-Wechat is an OpenClaw channel plugin for Enterprise WeChat (WeCom), wit
 - [Development](#development)
 - [FAQ](#faq)
 
-## Onboarding Update (v2.1.0)
+## Reliable Delivery Update (v2.2.0)
 
-This release focuses on setup quality, not feature sprawl. The goal is to make `OpenClaw-Wechat` behave more like a native OpenClaw channel during install and first-run.
+This release focuses on reply reliability rather than new surface area. The goal is to make WeCom delivery visible, retryable, and diagnosable.
 
 ### What changed
 
 | Item | Result |
 |---|---|
-| DM pairing approval | Added `dm.mode=pairing`, backed by OpenClaw native pairing flow |
-| Quickstart metadata | Added `detailLabel`, `systemImage`, and `quickstartAllowFrom` |
-| `/status` readability | Status now leads with `receive / reply / send / media / voice / doc` readiness |
-| Selfcheck summaries | `wecom:selfcheck`, `wecom:agent:selfcheck`, and `wecom:bot:selfcheck` now print `readiness` and `routing` summaries |
-| Route visibility | Status and selfcheck now show whether routing comes from `bindings` or `dynamicAgent` |
-| Long-connection log noise | Normal connect / opened / subscribed logs moved to `debug` |
+| Reliable-delivery status | `/status` now shows `24h window / proactive quota / Pending Reply` summary |
+| Pending Reply | final replies that fail to deliver are queued for retry and next-inbound replay |
+| Failure classification | delivery now distinguishes `window expired / quota exhausted / transport failure / invalid target` |
+| Selfcheck summaries | `wecom:selfcheck`, `wecom:agent:selfcheck`, and `wecom:bot:selfcheck` now print `reliable-delivery` summaries |
+| Group-policy diagnostics | `/status` and selfcheck now show group rule source, access mode, and whether allowlists are actually active |
+| Bot/Agent convergence | bot fallback and agent final reply now share the same reliable-delivery tracking |
+| Long-connection log noise | normal connect / opened / subscribed logs stay at `debug` |
 
 ### Practical impact
 
-- New users can start from the smallest working config, then add multi-account or dynamic routing later.
-- Teams that want controlled DM access can now use `pairing` instead of maintaining `allowFrom` only.
-- `/status` and selfcheck answer “can it receive, reply, and send?” before lower-level transport details.
-- Bot long-connection is quieter by default while still keeping useful warnings and errors.
+- You can now see whether the current session is still inside the 24-hour reply window.
+- Group-chat policy no longer requires log forensics: `/status` and selfcheck explain which group rule is active and whether an allowlist is currently enforced.
+- Failed final replies no longer disappear into timeout-only fallbacks; they move into Pending Reply retry flow.
+- Selfcheck now tells you whether reliable-delivery tracking is enabled, not just whether tokens and webhook paths exist.
+- Bot long-connection stays quiet by default while keeping warnings and errors visible.
 
 ## Highlights
 
@@ -85,11 +87,39 @@ This release focuses on setup quality, not feature sprawl. The goal is to make `
 
 ### 1) Install plugin
 
+Fastest path:
+
+```bash
+npx -y @dingxiang-me/openclaw-wecom-cli install
+```
+
+This wraps the same quickstart / migrate / doctor flow and turns plugin install + starter config write into one command.
+
+If you want to stay inside this repo, run the same flow with:
+
+```bash
+npm run wecom:quickstart -- --mode bot_long_connection
+npm run wecom:doctor -- --json
+```
+
+If you already have `WECOM_*` / `WECOM_BOT_*` env vars prepared, WeCom also supports an env-backed `channels add` flow:
+
+```bash
+export WECOM_BOT_LONG_CONNECTION_BOT_ID=your-bot-id
+export WECOM_BOT_LONG_CONNECTION_SECRET=your-bot-secret
+openclaw channels add --channel wecom --use-env
+```
+
+This works without any OpenClaw core patch because the plugin exposes `setup.applyAccountConfig` for WeCom. It can persist Agent/Bot settings discovered from env vars into `openclaw.json`.  
+Treat it as an advanced env-backed compatibility path, not the primary onboarding flow. For full setup, migration, and repair, the external installer remains the recommended path.
+
+If you only want the plugin package itself:
+
 ```bash
 openclaw plugins install @dingxiang-me/openclaw-wechat
 ```
 
-Recommended minimum package version: `2.1.0`. If `plugins.installs.openclaw-wechat` in `openclaw.json` still reports `1.7.x`, upgrade or reinstall first; those older npm packages do not expose the current WeCom channel metadata.
+Recommended minimum package version: `2.3.0`. If `plugins.installs.openclaw-wechat` in `openclaw.json` still reports `1.7.x`, upgrade or reinstall first; those older npm packages do not expose the current WeCom onboarding, migration, or reliable-delivery capabilities.
 
 For local development or direct source-path loading, use:
 
@@ -318,13 +348,132 @@ When multi-account is enabled, each account can override Bot callback credential
 | Direct-message policy | `dm.mode`, `dm.allowFrom`, `dm.rejectMessage` (`open / allowlist / pairing / deny`) |
 | Event policy | `events.enabled`, `events.enterAgentWelcomeEnabled`, `events.enterAgentWelcomeText` |
 | Group trigger | `groupChat.enabled`, `groupChat.triggerMode`, `groupChat.mentionPatterns`, `groupChat.triggerKeywords` |
+| Group policy | `groupPolicy`, `groupChat.policy`, `groups.<chatId>.policy` (`open / allowlist / deny`) |
+| Group member ACL | `groupAllowFrom`, `groups.<chatId>.allowFrom` (used with `allowlist`) |
 | Dynamic route | `dynamicAgent.*` (compatible with `dynamicAgents.*`, `dm.createAgentOnFirstMessage`) |
 | Debounce | `debounce.enabled`, `debounce.windowMs`, `debounce.maxBatch` |
 | Agent streaming | `streaming.enabled`, `streaming.minChars`, `streaming.minIntervalMs` |
+| Pending Reply persistence | `delivery.pendingReply.persist`, `delivery.pendingReply.storeFile` |
+| Reasoning visibility | `delivery.reasoning.mode`, `delivery.reasoning.title`, `delivery.reasoning.maxChars` |
+| Final reply format | `delivery.replyFormat` (`auto / text / markdown`) |
 | Observability | `observability.enabled`, `observability.logPayloadMeta` |
 
 ### OpenClaw bindings for account-level routing
 
+Package metadata, plugin manifest, and runtime channel meta now expose the same quickstart modes so the installer, quickstart, doctor, and future integrations can consume the same starter config and setup checklist.
+
+Fastest entry:
+
+```bash
+npx -y @dingxiang-me/openclaw-wecom-cli install
+```
+
+If you prefer the repo-local scripts, you can still generate a starter config immediately:
+
+```bash
+npm run wecom:quickstart -- --mode bot_long_connection
+```
+
+If you prefer an interactive wizard:
+
+```bash
+npm run wecom:quickstart -- --wizard
+```
+
+Common examples:
+
+```bash
+# Recommended default mode
+npm run wecom:quickstart -- --json
+
+# Walk through mode / dm / group-policy choices interactively
+npm run wecom:quickstart -- --wizard
+
+# Run the recommended selfchecks for the selected mode
+npm run wecom:quickstart -- --run-checks
+
+# Force those checks even if starter placeholders are still present
+npm run wecom:quickstart -- --run-checks --force-checks
+
+# Write a ready-to-apply config patch and .env template to disk
+npm run wecom:quickstart -- --run-checks --repair-dir ./.wecom-repair
+
+# Merge the generated repair configPatch directly into the target openclaw.json
+npm run wecom:quickstart -- --run-checks --apply-repair
+
+# Preview the fields that would change, then confirm before applying the repair patch
+npm run wecom:quickstart -- --run-checks --confirm-repair
+
+# Inspect legacy / mixed-layout config and generate a migration patch
+npm run wecom:migrate -- --json
+
+# Aggregate migration, selfchecks, E2E checks, long-connection probe, and callback matrix
+npm run wecom:doctor -- --json
+
+# Run the local black-box onboarding flow: install -> doctor -> fix -> rerun
+npm run test:e2e:local
+
+# Verify version sync and npm pack outputs for both packages
+npm run test:release
+
+# Scaffold an account-scoped Agent callback setup
+npm run wecom:quickstart -- --mode agent_callback --account sales --dm-mode allowlist
+
+# Add a ready-to-edit group allowlist template
+npm run wecom:quickstart -- --mode hybrid --group-profile allowlist_template --group-chat-id wr-ops-room --group-allow ops_lead,oncall_user
+
+# Merge into openclaw.json and create a backup first
+npm run wecom:quickstart -- --mode hybrid --write
+```
+
+Supported `--group-profile` values: `inherit`, `mention_only`, `open_direct`, `allowlist_template`, `deny`.
+`--wizard` treats any CLI flags you already passed as defaults, then walks through the remaining choices and write confirmation.
+`--run-checks` executes the recommended post-setup selfchecks for the selected mode; if placeholders are still present, execution is blocked unless you explicitly pass `--force-checks`.
+`--apply-repair` merges `postcheck.repairArtifacts.configPatch` directly into the `--config` file and creates a backup first.
+`--confirm-repair` prints the exact fields that would change, then asks before performing `--apply-repair`; the prompt stays on `stderr` so `--json` output remains machine-readable.
+`npm run wecom:migrate -- --json` skips starter generation and audits only the current install / migration state, which is useful for `legacy_config / mixed_layout / stale_package`.
+`npm run wecom:migrate -- --json` and `npm run wecom:doctor -- --json` now also report `migrationSource`, so you can tell whether the current layout looks closer to `official-wecom`, `sunnoy-wecom`, `legacy-openclaw-wechat`, or `mixed-source`.
+`npm run wecom:doctor -- --json` aggregates `migration + selfcheck + agent/bot e2e + longconn probe + callback matrix` into one report; add `--skip-network` if you want to inspect local install / migration issues first.
+`npm run wecom:doctor -- --fix --skip-network --json` applies the current local fix patch first, then reruns doctor on the merged config.
+`npm run wecom:doctor -- --confirm-fix --skip-network --json` previews the exact fields first, then asks before writing the patch.
+`npm run wecom:quickstart -- --json` now also returns `sourcePlaybook`, so the quickstart report itself can expose source-specific check order, placeholder guidance, and default repair behavior.
+`npx -y @dingxiang-me/openclaw-wecom-cli install` first tries `openclaw plugins install @dingxiang-me/openclaw-wechat`, then writes starter config and can continue with a local doctor pass.
+`npm run test:e2e:local` black-boxes the local `install -> doctor -> fix -> rerun` flow without relying on a live WeCom network.
+`npm run test:release` verifies root package, installer CLI, manifest, runtime version constants, and `npm pack --dry-run` outputs before a release.
+If the current layout looks closer to the official plugin, sunnoy, or legacy OpenClaw-Wechat, the `--json` report now includes `migration.guide`, source-specific notes, legacy field paths, and a rollback command.
+Use `--confirm-doctor-fix` if you want the installer to ask before appending `doctor --fix`; use `--no-doctor-fix` to suppress it entirely, or `--yes` to auto-confirm prompts.
+The installer `--json` report now also includes structured `actions`, so a CLI/UI layer can consume source review, migration, rollback, and rerun-doctor steps directly.
+If you do not pass `--mode`, the installer can now auto-pick `bot_long_connection / agent_callback / hybrid` from the detected source plus current capabilities, and explains that decision in `sourceProfile`.
+The repo now also ships two CI gates: `Onboarding E2E` for the local install loop, and `Release Check` for version/pack consistency; tag releases run a dedicated workflow that publishes both the plugin package and installer CLI in sequence.
+`sourceProfile` now also exposes source-specific `checkOrder` and `repairDefaults`. Official / legacy sources still default to auto-appending `doctor --fix`, while sunnoy / mixed-source defaults stay advisory until you confirm repair explicitly.
+
+The `--json` report now also includes:
+
+- `placeholders`: starter-template values you still need to replace
+- `setupChecklist`: the next admin/selfcheck steps to run
+- `actions`: structured setup actions that CLI / UI can consume directly
+- `installState / migrationState`: whether the current layout is fresh, legacy_config, stale_package, mixed_layout, or ready
+- `migrationSource / migrationSourceSummary`: whether the current layout looks closer to the official plugin, sunnoy compatibility layout, legacy-openclaw-wechat, or a mixed-source config
+- `fix`: whether doctor `--fix` prompted, confirmed, and wrote a local patch, plus the real `changedPaths`
+- `sourcePlaybook`: the quickstart-side source-specific check order, placeholder guidance, and repair defaults
+- `sourceProfile.checkOrder / sourceProfile.repairDefaults`: the source-specific validation order plus the installer's default repair strategy
+- `warnings`: mode/profile-specific caveats that still need confirmation
+- `postcheck`: recommended selfcheck execution status, blockage reason, or summary
+- `postcheck.remediation`: actionable fix hints derived from failed checks
+- `postcheck.repairArtifacts`: a minimal `configPatch` plus `.env` template you can apply directly to fix the detected setup gaps
+- `postcheck.repairPlan`: itemized repair changes, env updates, and file writes
+- `migration.configPatch / migration.envTemplate`: suggested normalized layout for the current legacy config
+
+If you also pass `--repair-dir <path>`, quickstart will materialize those artifacts as:
+
+- `wecom.config-patch.json`
+- `wecom.account-patch.json`
+- `wecom.env.template`
+- `README.txt`
+
+If you pass `--apply-repair`, the report will also include `repairApply` so you can see whether the repair patch was actually merged into the target config.
+If you pass `--confirm-repair`, `repairApply` also includes `prompted/confirmed` so you can tell whether the patch was declined or auto-applied; actual writes are listed in `repairApply.changedPaths`.
+
 Use OpenClaw core `bindings` for stable account-to-agent routing. The plugin exposes `channel=wecom` and `accountId=<id>` to the core router.
 
 ```json
@@ -799,6 +948,24 @@ Set:
 }
 ```
 
+If you also need to limit which members can trigger the bot in a group, add a group member ACL:
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "groupAllowFrom": ["alice", "bob"],
+      "groups": {
+        "wr9N1x...": {
+          "allowFrom": ["ops_lead"],
+          "rejectMessage": "Only the on-duty team can trigger this bot in the group."
+        }
+      }
+    }
+  }
+}
+```
+
 And verify WeCom-side prerequisites:
 1. App callback is enabled and URL verification succeeded.
 2. App visibility includes group members.

package/README.md

@@ -12,7 +12,7 @@ OpenClaw-Wechat 是一个面向 OpenClaw 的企业微信渠道插件，支持两
 
 ## 目录
 
-- [接入更新（v2.1.0）](#接入更新v210)
+- [可靠投递更新（v2.2.0）](#可靠投递更新v220)
 - [功能概览](#功能概览)
 - [模式对比](#模式对比)
 - [5 分钟极速上手](#5-分钟极速上手)
@@ -33,30 +33,38 @@ OpenClaw-Wechat 是一个面向 OpenClaw 的企业微信渠道插件，支持两
 - [FAQ](#faq)
 - [版本与贡献](#版本与贡献)
 
-## 接入更新（v2.1.0）
+## 可靠投递更新（v2.2.0）
 
-这版不是继续堆新平台能力，而是把接入体验收口到“更像 OpenClaw 原生渠道”的状态。
+这版重点不在接入元信息，而是把 WeCom 回复链路补成“可感知、可补发、可诊断”的可靠投递。
 
 ### 这版新增了什么
 
 | 项目 | 结果 |
 |---|---|
-| 私聊配对审批 | 新增 `dm.mode=pairing`，首次私聊会生成 OpenClaw 原生配对审批 |
-| Quickstart 元信息 | 渠道 metadata 补齐 `detailLabel`、`systemImage`、`quickstartAllowFrom` |
-| `/status` 可读性 | 优先展示 `收消息 / 回消息 / 主动发送 / 媒体 / 语音 / 文档` 准备情况 |
-| Selfcheck 摘要 | `wecom:selfcheck` / `wecom:agent:selfcheck` / `wecom:bot:selfcheck` 新增 `readiness` 与 `routing` 摘要 |
-| 路由可见性 | 明确显示当前是否命中 `bindings` 或 `dynamicAgent` |
-| 长连接日志降噪 | 正常的 connect / opened / subscribed 改为 `debug`，减少默认噪音 |
+| 可靠投递状态 | `/status` 新增 `24h 窗口 / 主动发送额度 / Pending Reply` 摘要 |
+| Pending Reply | 最终回复投递失败后自动入队，支持定时重试和下次入站补发 |
+| Pending Reply 持久化 | 可选落盘，gateway 重启后继续补发未送达的最终回复 |
+| 配额感知 | 统一区分 `窗口过期 / 额度不足 / 传输失败 / 目标无效` |
+| 推理展示策略 | `delivery.reasoning` 可控制 `<think>` 内容分离显示、合并到最终回复或隐藏 |
+| Selfcheck 摘要 | `wecom:selfcheck` / `wecom:agent:selfcheck` / `wecom:bot:selfcheck` 增加 `reliable-delivery` 摘要 |
+| 群策略诊断 | `/status` 与 selfcheck 会显示当前群规则来源、准入模式以及白名单是否生效 |
+| 最终回复格式 | `delivery.replyFormat` 支持 `auto / text / markdown`，会按链路选择纯文本或 markdown 能力 |
+| 媒体指令 | 模型最终回复支持 `MEDIA:` / `FILE:` 指令，自动回传图片/文件并隐藏指令行 |
+| Bot/Agent 收口 | Bot fallback 与 Agent 最终回复统一纳入可靠投递跟踪 |
+| 长连接日志降噪 | 正常的 connect / opened / subscribed 继续保持 `debug`，默认日志更安静 |
 
 ### 这版对接入有什么实际影响
 
-- 新用户现在可以按最小配置先跑通，再决定是否启用多账号、动态路由和文档工具。
-- 需要私聊审批时，不再只能靠手写 `allowFrom`，可以直接用 `pairing` 模式接到 OpenClaw 审批流。
-- `/status` 和 selfcheck 先回答“能不能收、能不能回、能不能发”，再展开工程细节。
-- Bot 长连接默认日志更安静，排障时再开 `debug` 看正常心跳和订阅细节。
+- 现在能直接看出当前会话是否仍在 `24h` 回复窗口内，以及是否存在待补发的最终回复。
+- Bot / Agent 不再只是超时兜底，而是会把失败结果分类并进入 Pending Reply 重试。
+- selfcheck 会明确告诉你可靠投递追踪是否打开、是否持久化，以及当前推理展示模式。
+- 群聊策略不再只能靠日志反推，`/status` 和 selfcheck 会直接说明当前命中的群规则来源与白名单是否真的在限制触发。
+- Bot 长连接默认日志仍然更安静，排障时再开 `debug` 看正常心跳和订阅细节。
 
 ### 当前推荐的接入顺序
 
+现在 package / manifest / runtime channel meta 都会暴露同一套 quickstart metadata，便于 installer、quickstart、doctor 和后续集成入口读取同一份推荐模式、starter config 和 setup checklist。
+
 1. 先选一个主入口：
    - Bot 长连接：适合最快跑通对话
    - Agent：适合需要主动发送、菜单、自建应用能力
@@ -68,7 +76,133 @@ OpenClaw-Wechat 是一个面向 OpenClaw 的企业微信渠道插件，支持两
    - `bindings`
    - `dynamicAgent`
    - `wecom_doc`
-   - 本地语音转写
+
+### Quickstart 命令
+
+推荐入口：
+
+```bash
+npx -y @dingxiang-me/openclaw-wecom-cli install
+```
+
+如果你更想留在仓库内执行同一套流程：
+
+```bash
+npm run wecom:quickstart -- --mode bot_long_connection
+npm run wecom:doctor -- --json
+```
+
+如果你想走交互式向导：
+
+```bash
+npm run wecom:quickstart -- --wizard
+```
+
+如果你已经准备好了 `WECOM_*` / `WECOM_BOT_*` 环境变量，也可以使用兼容性的 env-backed 初始化路径：
+
+```bash
+export WECOM_BOT_LONG_CONNECTION_BOT_ID=your-bot-id
+export WECOM_BOT_LONG_CONNECTION_SECRET=your-bot-secret
+openclaw channels add --channel wecom --use-env
+```
+
+这条 `channels add --use-env` 路径不需要任何 OpenClaw core 补丁，但它只适合 env-backed 初始化。  
+日常文档、排障和安装说明都默认以 `installer / quickstart / doctor` 为主路径；如果你需要完整接入和迁移闭环，仍然优先用 `npx -y @dingxiang-me/openclaw-wecom-cli install`。
+
+常见用法：
+
+```bash
+# 默认推荐模式：Bot 长连接
+npm run wecom:quickstart -- --json
+
+# 交互式选择 mode / dm / 群策略，并决定是否直接写入配置
+npm run wecom:quickstart -- --wizard
+
+# 把推荐 selfcheck 也串起来跑；如仍有占位项，默认会先阻止执行
+npm run wecom:quickstart -- --run-checks
+
+# 即使还没填完占位项，也强制执行推荐检查
+npm run wecom:quickstart -- --run-checks --force-checks
+
+# 把修复用的 configPatch 和 .env 模板直接写到目录里
+npm run wecom:quickstart -- --run-checks --repair-dir ./.wecom-repair
+
+# 直接把生成的 repair configPatch 合并进目标 openclaw.json
+npm run wecom:quickstart -- --run-checks --apply-repair
+
+# 先预览将要修改的字段，再确认是否真的应用 repair patch
+npm run wecom:quickstart -- --run-checks --confirm-repair
+
+# 单独盘点当前配置里的 legacy / mixed-layout 问题，并生成迁移 patch
+npm run wecom:migrate -- --json
+
+# 一次性聚合安装状态、迁移状态、自检、长连接探针和回调矩阵
+npm run wecom:doctor -- --json
+
+# 跑本地黑盒 onboarding E2E：install -> doctor -> fix -> rerun
+npm run test:e2e:local
+
+# 检查 root 包、installer CLI、manifest 和 npm pack 产物是否一致
+npm run test:release
+
+# 生成 sales 账号的 Agent 回调模板
+npm run wecom:quickstart -- --mode agent_callback --account sales --dm-mode allowlist
+
+# 直接带一份群白名单模板（值班群/运营群）
+npm run wecom:quickstart -- --mode hybrid --group-profile allowlist_template --group-chat-id wr-ops-room --group-allow ops_lead,oncall_user
+
+# 直接合并写入 openclaw.json，并自动备份原文件
+npm run wecom:quickstart -- --mode hybrid --write
+```
+
+`--group-profile` 可选值有：`inherit`、`mention_only`、`open_direct`、`allowlist_template`、`deny`。  
+默认行为只打印 starter config 和检查清单；只有显式传 `--write` 才会写文件。
+`--wizard` 会把当前 CLI 参数当作默认值，然后逐步提问，最后再确认是否写入 `openclaw.json`。
+`--run-checks` 会按当前 mode 的推荐命令执行自检；若 starter config 里还有占位项，默认会阻止执行，除非显式传 `--force-checks`。
+`--apply-repair` 会把 `postcheck.repairArtifacts.configPatch` 直接 merge 到 `--config` 指向的配置文件，并自动备份原文件。
+`--confirm-repair` 会先打印将要修改的字段，再询问是否真正执行 `--apply-repair`；交互提示走 `stderr`，不会污染 `--json` 的机器输出。
+`npm run wecom:migrate -- --json` 不再生成 starter config，只做当前安装 / 迁移状态盘点，适合排查 `legacy_config / mixed_layout / stale_package`。
+`npm run wecom:migrate -- --json` 和 `npm run wecom:doctor -- --json` 现在还会给出 `migrationSource`，直接区分 `official-wecom / sunnoy-wecom / legacy-openclaw-wechat / mixed-source`。
+`npm run wecom:doctor -- --json` 会把 `migration + selfcheck + agent/bot e2e + longconn probe + callback matrix` 聚合成一份报告；可以加 `--skip-network` 先只看本地安装 / 迁移问题。
+`npm run wecom:doctor -- --fix --skip-network --json` 会先应用当前可落盘的本地 fix patch（例如 migration patch、`plugins.allow/entries`），再用修正后的配置重跑 doctor。
+`npm run wecom:doctor -- --confirm-fix --skip-network --json` 会先预览将要修改的字段，再确认是否真正写回。
+`npm run wecom:quickstart -- --json` 现在也会带 `sourcePlaybook`，把当前来源推荐的检查顺序、占位项提示和默认 repair 策略一起返回。
+`npx -y @dingxiang-me/openclaw-wecom-cli install` 会先尝试执行 `openclaw plugins install @dingxiang-me/openclaw-wechat`，再写入 starter config，并可选继续跑本地 doctor。
+`npm run test:e2e:local` 会黑盒验证 `install -> doctor -> fix -> rerun` 这条本地闭环，不依赖真实企微网络。
+`npm run test:release` 会校验 root 包、installer CLI、manifest、运行时版本常量和 `npm pack --dry-run` 产物，适合作为发版前门禁。
+如果当前配置更像官方插件 / sunnoy / 旧版 OpenClaw-Wechat，安装器会在 `--json` 输出里直接给出 `migration.guide`、来源说明、legacy 字段路径和回滚命令。
+如果你想人工确认是否附带执行 `doctor --fix`，可以加 `--confirm-doctor-fix`；要强制不附带 `--fix`，可加 `--no-doctor-fix`，自动确认则用 `--yes`。
+安装器的 `--json` 现在还会直接输出 `actions`，把来源审阅、迁移 patch、回滚和重跑 doctor 这些步骤结构化暴露出来。
+如果你没有显式传 `--mode`，安装器还会按来源和现有能力自动选择 `bot_long_connection / agent_callback / hybrid`，并在 `sourceProfile` 里说明为什么这么选。
+`sourceProfile` 现在还会给出来源专属 `checkOrder` 和 `repairDefaults`。例如官方 / legacy 来源默认允许自动附带 `doctor --fix`，而 sunnoy / mixed-source 来源默认只给修复建议，不会直接附带 `--fix`。
+仓库现在也自带两条 GitHub Actions 门禁：`Onboarding E2E` 跑本地安装闭环，`Release Check` 跑版本/打包一致性；tag 发布会走独立 release workflow，顺序发布插件包和 installer CLI。
+
+`--json` 输出会额外给出：
+
+- `placeholders`：还有哪些模板占位项没替换
+- `setupChecklist`：下一步应该执行的管理台配置和自检命令
+- `actions`：可被 CLI / UI 直接消费的结构化 setup flow
+- `installState / migrationState`：当前是 fresh、legacy_config、stale_package、mixed_layout 还是 ready
+- `migrationSource / migrationSourceSummary`：当前更接近官方插件、sunnoy 配置、legacy-openclaw-wechat，还是 mixed-source
+- `fix`：doctor `--fix` 是否已提示、确认、落盘，以及真实 `changedPaths`
+- `sourcePlaybook`：quickstart 基于当前来源生成的推荐检查顺序、占位提示和 repair 默认值
+- `sourceProfile.checkOrder / sourceProfile.repairDefaults`：当前来源推荐的检查顺序，以及 installer 默认采用的修复策略
+- `warnings`：当前 mode / group profile 下仍需确认的风险点
+- `postcheck`：推荐 selfcheck 的执行结果、阻塞原因或汇总状态
+- `postcheck.remediation`：把失败检查翻译成可执行的修复建议
+- `postcheck.repairArtifacts`：自动生成最小 `configPatch` 和 `.env` 模板，便于直接修复当前检查暴露的问题
+- `postcheck.repairPlan`：按项列出 repair patch 的配置变更、env 变更和会写出的文件
+- `migration.configPatch / migration.envTemplate`：当前 legacy 配置可直接迁移到的新布局建议
+
+如果再加 `--repair-dir <path>`，quickstart 还会把这些修复产物直接落盘成：
+
+- `wecom.config-patch.json`
+- `wecom.account-patch.json`
+- `wecom.env.template`
+- `README.txt`
+
+如果加的是 `--apply-repair`，则会在输出中额外看到 `repairApply`，说明 repair patch 是否已实际写入目标配置。
+如果加的是 `--confirm-repair`，`repairApply` 里还会带 `prompted/confirmed`，方便区分“用户拒绝”与“自动执行”；真正写入的字段会出现在 `repairApply.changedPaths`。
 
 ## 5 分钟极速上手
 
@@ -76,11 +210,21 @@ OpenClaw-Wechat 是一个面向 OpenClaw 的企业微信渠道插件，支持两
 
 ### Step 1. 安装插件
 
+最快入口：
+
+```bash
+npx -y @dingxiang-me/openclaw-wecom-cli install
+```
+
+它会复用仓库内的 quickstart / migrate / doctor 能力，把“安装插件 + 写 starter config + 跑本地体检”串成一次执行。
+
+如果你只想单独安装插件包：
+
 ```bash
 openclaw plugins install @dingxiang-me/openclaw-wechat
 ```
 
-> 最低建议版本：`2.1.0`。如果 `openclaw.json` 里的 `plugins.installs.openclaw-wechat` 仍显示 `1.7.x`，请先升级或重装；旧包不会正确注册 `wecom` channel 元数据。
+> 最低建议版本：`2.3.0`。如果 `openclaw.json` 里的 `plugins.installs.openclaw-wechat` 仍显示 `1.7.x`，请先升级或重装；旧包不会正确注册 `wecom` channel 元数据，也不包含当前这套接入、迁移与可靠投递能力。
 
 如果你是在本地开发或要直接跑仓库源码，再用下面这套：
 
@@ -554,12 +698,13 @@ node ./scripts/wecom-bot-selfcheck.mjs --help
 | `webhookPath` | string | `/wecom/callback` | Agent 回调路径（非 default 账户未配置时自动生成 `/wecom/<accountId>/callback`） |
 | `agent` | object | - | 兼容旧配置：`agent.corpId/corpSecret/agentId`（与顶层 Agent 字段等价） |
 | `outboundProxy` | string | - | WeCom 出站代理 |
+| `apiBaseUrl` | string | `https://qyapi.weixin.qq.com` | 可选：覆盖默认 WeCom API Base URL |
 | `defaultAccount` | string | - | 多账号下的默认账号 ID（文档工具等优先使用） |
 | `tools.doc` | boolean | `true` | 是否启用 `wecom_doc` 文档工具 |
 | `webhooks` | object | - | 命名 Webhook 目标映射（如 `{ "ops": "https://...key=xxx" }`） |
 | `accounts` | object | - | 多账户配置（支持 `accounts.<id>.bot` 独立 Bot 配置） |
 
-兼容说明：支持旧字段与旧结构迁移：`name`、`token` / `encodingAesKey`、`agent.*`、`dynamicAgents.*`、`dm.createAgentOnFirstMessage`、`dm.allowFrom`、`workspaceTemplate`、`commandAllowlist/commandBlockMessage`、`commands.blockMessage`、以及 inline 账户写法 `channels.wecom.<accountId>`。新配置建议优先使用 `accounts.<id>`、`callbackToken/callbackAesKey`、`commands.*` 与 `dynamicAgent.*`。
+兼容说明：支持旧字段与旧结构迁移：`name`、`token` / `encodingAesKey`、`agent.*`、`dynamicAgents.*`、`dm.createAgentOnFirstMessage`、`dm.allowFrom`、`workspaceTemplate`、`commandAllowlist/commandBlockMessage`、`commands.blockMessage`、inline 账户写法 `channels.wecom.<accountId>`，以及官方 / sunnoy 风格的 `botId`、`secret`、`network.egressProxyUrl`、`network.apiBaseUrl`。新配置建议优先使用 `accounts.<id>`、`callbackToken/callbackAesKey`、`bot.longConnection.*`、`outboundProxy/apiBaseUrl`、`commands.*` 与 `dynamicAgent.*`。
 
 提示：`accounts.<id>` 现在支持 Bot-only 账号（仅配置 `bot.*`），不再强制要求 `corpId/corpSecret/agentId`。
 兼容提示：当使用默认新路径时会自动附加 legacy alias，便于旧回调地址平滑迁移：Agent 默认路径会附加 `/webhooks/app`（多账号为 `/webhooks/app/<id>`），Bot 默认路径会附加 `/webhooks/wecom`（多账号为 `/webhooks/wecom/<id>`）。若 alias 与另一类路由冲突会自动跳过并告警。
@@ -633,6 +778,8 @@ node ./scripts/wecom-bot-selfcheck.mjs --help
 | `longConnection` | object | - | 该账户专用长连接配置（覆盖全局 `bot.longConnection`） |
 | `card` | object | - | 该账户专用卡片回包配置（覆盖全局 `bot.card`） |
 
+兼容提示：如果你是从官方插件或 sunnoy 配置直接迁移，也可以先保留 `channels.wecom.botId/secret` 或 `accounts.<id>.botId/secret`，以及 `network.egressProxyUrl/apiBaseUrl`；插件会在运行时兼容读取，`npm run wecom:migrate -- --json` 会给出归一化 patch。
+
 ### 多账户文档工具覆盖（`channels.wecom.accounts.<id>.tools`）
 
 | 键 | 类型 | 默认 | 说明 |
@@ -651,6 +798,8 @@ node ./scripts/wecom-bot-selfcheck.mjs --help
 | 私聊策略 | `dm.mode` + `dm.allowFrom` + `dm.rejectMessage` | 控制私聊开放/白名单/配对审批/拒绝 |
 | 事件策略 | `events.enabled` + `events.enterAgentWelcomeEnabled` + `events.enterAgentWelcomeText` | 控制事件处理与 enter_agent 欢迎语 |
 | 群聊触发 | `groupChat.enabled` + `triggerMode` + `mentionPatterns` + `triggerKeywords` | 控制群消息触发条件（自建应用支持 `direct/mention/keyword`；Bot 模式按平台限制固定 `mention`） |
+| 群聊准入策略 | `groupPolicy` + `groupChat.policy` + `groups.<chatId>.policy` | 显式控制 `open / allowlist / deny`；支持账户级覆盖与按群覆盖 |
+| 群聊成员授权 | `groupAllowFrom` + `groups.<chatId>.allowFrom` | 与 `allowlist` 搭配使用，控制哪些群成员可以触发机器人；支持账户级覆盖与按群覆盖 |
 | 动态路由 | `dynamicAgent.*`（兼容 `dynamicAgents.*`、`dm.createAgentOnFirstMessage`） | 动态 Agent + workspace bootstrap 播种 |
 
 ### 吞吐与稳定性
@@ -660,6 +809,9 @@ node ./scripts/wecom-bot-selfcheck.mjs --help
 | 文本防抖 | `debounce.enabled/windowMs/maxBatch` | 合并短时间多条文本 |
 | Agent 增量回包 | `streaming.enabled/minChars/minIntervalMs` | 多消息模拟流式 |
 | 异步补发 | `WECOM_LATE_REPLY_WATCH_MS/POLL_MS` | dispatch 超时后补发最终回复 |
+| Pending Reply 持久化 | `delivery.pendingReply.persist/storeFile` | 重启后恢复未送达最终回复；未指定 `storeFile` 时自动写入 OpenClaw state 目录 |
+| 推理展示 | `delivery.reasoning.mode/title/maxChars` | 控制 `<think>` / reasoning 分离显示、附加到最终回复，或完全隐藏 |
+| 最终回复格式 | `delivery.replyFormat` | `auto / text / markdown`；优先在支持的 WeCom 链路上保留 markdown，其余链路自动回退纯文本 |
 | 观测统计 | `observability.enabled/logPayloadMeta` | 记录入站/回包/错误并在 `/status` 展示 |
 
 ### 语音转写（本地）
@@ -1223,6 +1375,7 @@ npm run wecom:bot:selfcheck -- --all-accounts
 {
   "channels": {
     "wecom": {
+      "groupPolicy": "open",
       "groupChat": {
         "enabled": true,
         "triggerMode": "direct"
@@ -1232,6 +1385,38 @@ npm run wecom:bot:selfcheck -- --all-accounts
 }
 ```
 
+如果还要限制“只有指定群成员能触发”，可以再加一层群聊成员授权：
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "groupPolicy": "allowlist",
+      "groupAllowFrom": ["alice", "bob"],
+      "groups": {
+        "wr9N1x...": {
+          "policy": "allowlist",
+          "allowFrom": ["ops_lead"],
+          "rejectMessage": "当前群仅限值班同学触发。"
+        }
+      }
+    }
+  }
+}
+```
+
+如果你要“一刀切关闭群聊处理”，直接用：
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "groupPolicy": "deny"
+    }
+  }
+}
+```
+
 同时确认企业微信侧前提：
 1. 自建应用已开启“接收消息”并完成 URL 验证
 2. 应用可见范围包含该群成员