@dingxiang-me/openclaw-wechat 2.0.1 → 2.3.0

package/CHANGELOG.md

@@ -4,6 +4,91 @@ 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
+- 新增 `dm.mode=pairing`，首次私聊可接入 OpenClaw 原生配对审批流，不再只能依赖静态 `allowFrom`
+- 新增 WeCom 渠道 pairing metadata，支持 `quickstartAllowFrom`、`wecomUserId` 归一化以及审批通过后的默认通知回执
+- `wecom:selfcheck`、`wecom:agent:selfcheck`、`wecom:bot:selfcheck` 新增接入摘要，直接输出 `readiness` 与 `routing`
+
+### Changed
+- WeCom 渠道 metadata 补齐 `detailLabel`、`systemImage` 与 quickstart 提示，接入路径更贴近 OpenClaw 原生渠道
+- `/status` 输出优先展示“收消息 / 回消息 / 主动发送 / 媒体 / 语音 / 文档”准备情况，并显式展示 `bindings` / `dynamicAgent` 路由来源
+- WeCom Bot 长连接正常连接日志默认降到 `debug`，减少 `connect/opened/subscribed` 噪音
+- README（中英文）改成 `2.1.0` 接入口径，补充 `pairing`、selfcheck 摘要和推荐接入顺序
+
 ## [2.0.1] - 2026-03-14
 
 ### Fixed

package/README.en.md

@@ -10,7 +10,7 @@ OpenClaw-Wechat is an OpenClaw channel plugin for Enterprise WeChat (WeCom), wit
 
 ## Table of Contents
 
-- [Major Update (v2.0.0)](#major-update-v200)
+- [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,41 +28,29 @@ OpenClaw-Wechat is an OpenClaw channel plugin for Enterprise WeChat (WeCom), wit
 - [Development](#development)
 - [FAQ](#faq)
 
-## Major Update (v2.0.0)
+## Reliable Delivery Update (v2.2.0)
 
-This is a real capability update, not a minor patch.  
-`OpenClaw-Wechat` now has **working WeCom Bot long-connection support** in real gateway runtime.
+This release focuses on reply reliability rather than new surface area. The goal is to make WeCom delivery visible, retryable, and diagnosable.
 
-### WeCom Bot long connection
+### What changed
 
 | Item | Result |
 |---|---|
-| Official endpoint | `wss://openws.work.weixin.qq.com` |
-| Inbound commands | `aibot_msg_callback` / `aibot_event_callback` |
-| Outbound command | `aibot_respond_msg` |
-| Runtime | switched to `ws`, no longer blocked by built-in Node WebSocket `1006` failures |
-| Public Bot callback required | no, not in long-connection mode |
-| Verification command | `npm run wecom:bot:longconn:probe -- --json` |
-
-### Control UI and operations
-
-This release also keeps the earlier operations improvements: **WeCom supports visual configuration in Control UI**, so you no longer need to rely on manual JSON edits only.
-
-### Visual config in Control UI
-
-| Item | Status | Notes |
-|---|---|---|
-| WeCom config form | ✅ | `channels.wecom` can be edited/saved directly from UI |
-| Localized labels | ✅ | Common fields are now clearly labeled in Chinese for ops teams |
-| Sensitive-field hints | ✅ | secret/token/aesKey fields are marked as sensitive |
-| Runtime status clarity | ✅ | `Connected` is no longer stuck at `n/a`; default account display name is localized |
-| Inbound activity tracking | ✅ | `Last inbound` is updated after webhook callbacks (`n/a` before first inbound after restart is expected) |
+| 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
 
-- Configure WeCom directly in `Channels -> WeCom` without hand-editing large config files.
-- Better readability for day-to-day ops and handover.
-- More accurate runtime status display reduces false alarm on “plugin not working”.
+- 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
 
@@ -75,7 +63,7 @@ This release also keeps the earlier operations improvements: **WeCom supports vi
 | Bot card replies | ✅ | `markdown/template_card` with automatic text fallback |
 | Multi-account support | ✅ | `channels.wecom.accounts.<id>` |
 | Sender allowlist and admin bypass | ✅ | `allowFrom` + `adminUsers` |
-| Direct-message policy | ✅ | `dm.mode=open/allowlist/deny` + account overrides |
+| Direct-message policy | ✅ | `dm.mode=open/allowlist/pairing/deny` + account overrides |
 | Event welcome reply (`enter_agent`) | ✅ | configurable via `events.enterAgentWelcome*` |
 | Command allowlist | ✅ | `/help`, `/status`, `/clear`, `/new`, etc. |
 | Group trigger policy | ✅ | mention-required or direct-trigger |
@@ -99,11 +87,39 @@ This release also keeps the earlier operations improvements: **WeCom supports vi
 
 ### 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.0.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:
 
@@ -159,6 +175,20 @@ If you are loading from source path instead, use the version below with `load.pa
 
 > Agent-mode note (important): configure **Trusted IP** in the WeCom self-built app settings and include the real egress IP of your OpenClaw gateway. Otherwise you may see "messages received but no reply".
 
+If you want first-contact DM approval, add:
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "dm": {
+        "mode": "pairing"
+      }
+    }
+  }
+}
+```
+
 ### 4) Restart and verify
 
 ```bash
@@ -169,6 +199,11 @@ npm run wecom:agent:selfcheck -- --all-accounts
 npm run wecom:bot:selfcheck -- --all-accounts
 ```
 
+Selfcheck now starts with two summary lines:
+
+- `readiness`: whether receive / reply / send are currently usable
+- `routing`: whether `bindings` and `dynamicAgent` are active
+
 ## Requirements
 
 | Item | Description |
@@ -310,16 +345,135 @@ When multi-account is enabled, each account can override Bot callback credential
 | Sender ACL | `allowFrom`, `allowFromRejectMessage` |
 | Command ACL | `commands.enabled`, `commands.allowlist`, `commands.rejectMessage` |
 | Admin bypass | `adminUsers` |
-| Direct-message policy | `dm.mode`, `dm.allowFrom`, `dm.rejectMessage` |
+| 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
@@ -433,7 +587,7 @@ Outbound target formats:
 |---|---|
 | `WECOM_ALLOW_FROM*` | sender authorization |
 | `WECOM_COMMANDS_*` | command ACL |
-| `WECOM_DM_*`, `WECOM_<ACCOUNT>_DM_*` | DM policy + allowlist |
+| `WECOM_DM_*`, `WECOM_<ACCOUNT>_DM_*` | DM policy + allowlist / pairing controls |
 | `WECOM_EVENTS_*`, `WECOM_<ACCOUNT>_EVENTS_*` | event handling + enter_agent welcome text |
 | `WECOM_GROUP_CHAT_*` | group trigger policy |
 | `WECOM_DEBOUNCE_*` | text debounce |
@@ -794,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.