@xmanrui/dsh-im 4.19.2 → 4.20.1

package/src/channels/weixin/connection-error.en.mjs

@@ -0,0 +1,116 @@
+// Shared diagnostic copy for the WeChat Host and settings client.
+export default {
+  "插件版本": "Plugin version",
+  "DSH 微信管理接口返回了无法识别的响应，请重新读取状态。": "The DSH WeChat management endpoint returned an invalid response. Refresh the status.",
+  "无法读取现有登录凭据。请检查 DSH 凭据存储。": "Could not read the saved login credential. Check the DSH credential store.",
+  "登录凭据无法写入 DSH 凭据存储。请检查凭据存储是否可写。": "Could not save the login credential to DSH. Check whether the credential store is writable.",
+  "账号配置无法写入本机。请检查 DSH_HOME 目录权限。": "Could not save the account configuration. Check permissions on DSH_HOME.",
+  "无法初始化账号状态或工作区。请检查 DSH_HOME 和工作区目录。": "Could not prepare the account state or workspace. Check DSH_HOME and the workspace directory.",
+  "插件无法连接当前 Harness，请检查宿主是否已就绪。": "The plugin could not connect to this Harness. Check whether the host is ready.",
+  "Harness 健康检查超时。请确认 dsh web 未阻塞。": "The Harness health check timed out. Check whether the host is responsive.",
+  "Harness 健康检查需要身份认证。请检查代理、网关或自定义鉴权配置。": "The Harness health check requires authentication. Check proxy, gateway or custom authentication settings.",
+  "本机 Harness 请求被代理要求认证。请让回环地址绕过代理，并检查 NO_PROXY 配置。": "The proxy requires authentication for the local Harness request. Bypass the proxy for loopback addresses and check NO_PROXY.",
+  "Harness 异常拒绝了回环地址的健康检查。请检查 HTTP 代理、Harness 源码版本和构建产物。": "Harness rejected a loopback health check. Check the HTTP proxy and the running Harness build.",
+  "Harness 的 Host 信任检查拒绝了非回环地址请求。请检查 harnessBaseUrl 与 trustedHosts 配置。": "Harness rejected the non-loopback Host. Check harnessBaseUrl and trustedHosts.",
+  "健康检查收到了非 Harness 标准的 403 拒绝响应。请检查代理或网关配置。": "The health check received a non-standard HTTP 403 response. Check proxy or gateway settings.",
+  "找不到 Harness 健康检查接口。请确认 Harness 与插件版本兼容。": "The Harness health check endpoint was not found. Check Harness and plugin compatibility.",
+  "Harness 健康检查返回服务错误。请查看 DSH 日志。": "The Harness health check returned a service error. Check the DSH logs.",
+  "Harness 返回了无法识别的响应。请确认 Harness 与插件版本兼容。": "Harness returned an unrecognized response. Check Harness and plugin compatibility.",
+  "Harness 拒绝了健康检查请求。请查看 DSH 日志。": "Harness rejected the health check. Check the DSH logs.",
+  "Harness 健康检查发生未知错误。请查看 DSH 日志。": "The Harness health check failed with an unknown error. Check the DSH logs.",
+  "消息连接初始化失败。请查看 DSH 日志后重试。": "The message connection could not start. Check the DSH logs and retry.",
+  "暂时无法访问微信服务。": "The WeChat service is temporarily unreachable.",
+  "微信服务请求超时。": "The WeChat service request timed out.",
+  "微信服务请求失败（HTTP {status}）。": "The WeChat service request failed (HTTP {status}).",
+  "微信服务返回了无法解析的响应。": "The WeChat service returned an unparseable response.",
+  "微信服务没有返回有效二维码。": "The WeChat service did not return a valid QR code.",
+  "微信服务返回了不受信任的扫码地址。": "The WeChat service returned an untrusted QR-code URL.",
+  "微信服务返回了无效的连接地址。": "The WeChat service returned an invalid connection URL.",
+  "微信服务返回了不受信任的连接地址。": "The WeChat service returned an untrusted connection URL.",
+  "拒绝访问不受信任的微信服务地址。": "Refusing to access an untrusted WeChat service URL.",
+  "微信服务返回了无法识别的扫码状态。": "The WeChat service returned an unrecognized QR-code status.",
+  "微信授权成功，但返回的账号凭据不完整。": "WeChat authorized the account but returned incomplete credentials.",
+  "微信服务拒绝了二维码申请。": "The WeChat service rejected the QR-code request.",
+  "已取得扫码地址，但本机二维码图片生成失败。": "The login URL was obtained, but the QR-code image could not be generated locally.",
+  "无法生成微信二维码。": "Could not generate a WeChat QR code.",
+  "这次微信绑定任务已不存在，请重新读取状态或生成二维码。": "This WeChat setup attempt no longer exists. Refresh the status or generate a new QR code.",
+  "这次微信绑定任务当前不能提交配对码，请重新读取状态。": "This setup attempt is not waiting for a pairing code. Refresh the status.",
+  "登录凭据缺失，请移除账号后重新扫码。": "The login credential is missing. Remove the account and scan a new QR code.",
+  "微信登录凭据已失效，请移除账号后重新扫码。": "The WeChat login credential has expired. Remove the account and scan a new QR code.",
+  "无法从 DSH 凭据存储移除微信登录凭据。": "Could not remove the WeChat login credential from the DSH credential store.",
+  "微信账号配置移除失败。": "Could not remove the WeChat account configuration.",
+  "无法读取微信账号状态文件。": "Could not read the WeChat account state file.",
+  "无法保存微信账号状态文件。": "Could not save the WeChat account state file.",
+  "微信账号已移除，但本机状态文件清理失败。": "The WeChat account was removed, but its local state file could not be cleaned up.",
+  "无法保存微信工作区设置。": "Could not save the WeChat workspace settings.",
+  "微信账号已移除，但工作区设置清理失败。": "The WeChat account was removed, but its workspace settings could not be cleaned up.",
+  "微信账号连接启动失败。": "The WeChat account connection could not start.",
+  "微信消息同步请求被拒绝。": "WeChat rejected the message sync request.",
+  "微信服务未确认停止通知。": "WeChat did not confirm the stop notification.",
+  "微信消息连接停止时发生错误。": "An error occurred while stopping the WeChat connection.",
+  "无法读取微信连接状态，请重新读取；之前的操作可能已完成。": "Could not read the WeChat connection status. Refresh it; the previous operation may have completed.",
+  "微信激活过程中发生未知错误。": "An unknown error occurred while activating the WeChat account.",
+  "微信操作发生未知错误。": "The WeChat operation failed with an unknown error.",
+  "微信配置格式错误，请检查 config.json 和 workspaces.json 后重启 DSH。": "The WeChat configuration is invalid. Check config.json and workspaces.json, then restart DSH.",
+  "微信配置访问权限不足，请检查数据目录权限后重启 DSH。": "The WeChat configuration could not be accessed. Check the data directory permissions and restart DSH.",
+  "微信初始化失败，请查看 DSH 启动日志。": "WeChat initialization failed. Check the DSH startup logs.",
+  "微信连接未就绪。": "The WeChat connection is not ready.",
+  "微信操作失败后，原账号状态恢复失败。": "The previous account state could not be restored after the failed WeChat operation.",
+  "原账号状态尚未确认，请重新读取状态，并反馈诊断信息。": "The previous account state has not been confirmed. Refresh the status and share the diagnostic information.",
+  "操作未完成，已恢复之前的本机状态。请处理上述问题后重试。": "The operation did not complete. The previous local state was restored. Resolve the problem above before retrying.",
+  "凭据由只读来源提供，请在启动 DSH 的配置中检查该来源。": "The credential comes from a read-only source. Check that source in the configuration used to launch DSH.",
+  "微信服务域名解析失败，请检查运行 DSH 的机器的网络和 DNS 设置后重试。": "The WeChat service domain could not be resolved. Check the network and DNS settings on the machine running DSH and retry.",
+  "请检查 DSH 数据目录和对应文件的读写权限。": "Check read and write permissions on the DSH data directory and the affected file.",
+  "磁盘空间不足，请释放空间后重试。": "The disk is full. Free up space and retry.",
+  "本机文件格式无效，请检查对应配置或状态文件；不要清空登录凭据。": "The local file format is invalid. Check the affected configuration or state file; do not clear login credentials.",
+  "请检查运行 DSH 的机器的系统时间、证书和网络设置。": "Check the system time, certificates and network settings on the machine running DSH.",
+  "请移除失效接入并重新扫码绑定。": "Remove the invalid connection and scan a new QR code to connect.",
+  "请确认当前 DSH 宿主已就绪，并检查 Harness 与插件实际运行版本及宿主日志。": "Check that this DSH host is ready, and check the running Harness and plugin versions and the host logs.",
+  "微信服务限流，请稍后重试。": "The WeChat service is rate-limiting requests. Try again later.",
+  "访问被拒绝，请检查服务访问限制；HTTP 状态本身不能确认登录凭据已失效。": "Access was denied. Check service access restrictions; the HTTP status alone does not establish that the login credential expired.",
+  "请检查运行 DSH 的机器能否访问微信服务，然后重试。": "Check whether the machine running DSH can access the WeChat service, then retry.",
+  "请按参考号查看 DSH 日志，并复制诊断信息反馈。": "Find this reference in the DSH logs and copy the diagnostic information when reporting the issue.",
+  "无法完成微信管理请求，请检查 DSH 连接后重新读取状态。": "The WeChat management request could not be completed. Check the DSH connection and refresh the status.",
+  "查询微信扫码状态失败": "Could not query WeChat QR-code status",
+  "无法完成微信管理请求": "Could not complete the WeChat management request",
+  "无法生成微信二维码": "Could not generate a WeChat QR code",
+  "状态读取失败，以下是上次读取的状态。": "Status refresh failed. The last known status is shown below.",
+  "诊断详情": "Diagnostic details",
+  "诊断信息": "Diagnostic information",
+  "复制诊断信息": "Copy diagnostic information",
+  "诊断信息已复制": "Diagnostic information copied",
+  "未取得 Host 诊断参考号。": "No diagnostic reference was received from the host.",
+  "无法访问剪贴板，请选择并复制以下诊断信息。": "Clipboard access is unavailable. Select and copy the diagnostic information below.",
+  "错误码": "Error code",
+  "失败阶段": "Failed step",
+  "底层原因": "Underlying cause",
+  "HTTP 状态": "HTTP status",
+  "微信返回码": "WeChat return code",
+  "参考号": "Reference",
+  "发生时间": "Time",
+  "加载微信配置": "Load WeChat configuration",
+  "申请二维码": "Request QR code",
+  "生成二维码图片": "Generate QR-code image",
+  "查询扫码状态": "Query QR-code status",
+  "提交配对码": "Submit pairing code",
+  "取消绑定": "Cancel setup",
+  "读取登录凭据": "Read login credential",
+  "保存登录凭据": "Save login credential",
+  "移除登录凭据": "Remove login credential",
+  "保存账号配置": "Save account configuration",
+  "移除账号配置": "Remove account configuration",
+  "读取账号状态": "Read account state",
+  "保存账号状态": "Save account state",
+  "清理账号状态": "Clean up account state",
+  "保存工作区设置": "Save workspace settings",
+  "清理工作区设置": "Clean up workspace settings",
+  "准备消息连接": "Prepare message connection",
+  "激活微信账号": "Activate WeChat account",
+  "检查 DSH 宿主": "Check DSH host",
+  "启动微信连接": "Start WeChat connection",
+  "同步微信消息": "Sync WeChat messages",
+  "停止微信连接": "Stop WeChat connection",
+  "读取连接状态": "Read connection status",
+  "恢复原账号状态": "Restore previous account state",
+  "访问 DSH 管理接口": "Access DSH management API"
+};

package/src/channels/weixin/connection-error.mjs

@@ -0,0 +1,204 @@
+import { randomUUID } from 'node:crypto';
+import packageInfo from '../../../package.json' with { type: 'json' };
+import { t } from '../shared/i18n.mjs';
+import { normalizeWeixinDiagnosticDetails } from './diagnostic-details.mjs';
+
+const MESSAGES = Object.freeze({
+  'credential-read-failed': '无法读取现有登录凭据。请检查 DSH 凭据存储。',
+  'credential-save-failed': '登录凭据无法写入 DSH 凭据存储。请检查凭据存储是否可写。',
+  'account-config-save-failed': '账号配置无法写入本机。请检查 DSH_HOME 目录权限。',
+  'runtime-prepare-failed': '无法初始化账号状态或工作区。请检查 DSH_HOME 和工作区目录。',
+  'harness-connect-failed': '插件无法连接当前 Harness，请检查宿主是否已就绪。',
+  'harness-timeout': 'Harness 健康检查超时。请确认 dsh web 未阻塞。',
+  'harness-auth-required': 'Harness 健康检查需要身份认证。请检查代理、网关或自定义鉴权配置。',
+  'harness-proxy-auth-required': '本机 Harness 请求被代理要求认证。请让回环地址绕过代理，并检查 NO_PROXY 配置。',
+  'harness-loopback-forbidden': 'Harness 异常拒绝了回环地址的健康检查。请检查 HTTP 代理、Harness 源码版本和构建产物。',
+  'harness-host-untrusted': 'Harness 的 Host 信任检查拒绝了非回环地址请求。请检查 harnessBaseUrl 与 trustedHosts 配置。',
+  'harness-request-forbidden': '健康检查收到了非 Harness 标准的 403 拒绝响应。请检查代理或网关配置。',
+  'harness-api-not-found': '找不到 Harness 健康检查接口。请确认 Harness 与插件版本兼容。',
+  'harness-http-failed': 'Harness 健康检查返回服务错误。请查看 DSH 日志。',
+  'harness-response-invalid': 'Harness 返回了无法识别的响应。请确认 Harness 与插件版本兼容。',
+  'harness-rpc-rejected': 'Harness 拒绝了健康检查请求。请查看 DSH 日志。',
+  'harness-check-unknown-failed': 'Harness 健康检查发生未知错误。请查看 DSH 日志。',
+  'connection-start-failed': '消息连接初始化失败。请查看 DSH 日志后重试。',
+
+  'network-error': '暂时无法访问微信服务。',
+  'timeout': '微信服务请求超时。',
+  'http-error': '微信服务请求失败（HTTP {status}）。',
+  'invalid-response': '微信服务返回了无法解析的响应。',
+  'invalid-qr': '微信服务没有返回有效二维码。',
+  'untrusted-qr': '微信服务返回了不受信任的扫码地址。',
+  'invalid-base-url': '微信服务返回了无效的连接地址。',
+  'untrusted-base-url': '微信服务返回了不受信任的连接地址。',
+  'untrusted-endpoint': '拒绝访问不受信任的微信服务地址。',
+  'invalid-login-status': '微信服务返回了无法识别的扫码状态。',
+  'incomplete-login': '微信授权成功，但返回的账号凭据不完整。',
+  'qr-request-rejected': '微信服务拒绝了二维码申请。',
+  'qr-encode-failed': '已取得扫码地址，但本机二维码图片生成失败。',
+  'qr-start-failed': '无法生成微信二维码。',
+  'provision-attempt-not-found': '这次微信绑定任务已不存在，请重新读取状态或生成二维码。',
+  'provision-state-invalid': '这次微信绑定任务当前不能提交配对码，请重新读取状态。',
+  'missing-token': '登录凭据缺失，请移除账号后重新扫码。',
+  'stale-token': '微信登录凭据已失效，请移除账号后重新扫码。',
+  'credential-remove-failed': '无法从 DSH 凭据存储移除微信登录凭据。',
+  'account-config-remove-failed': '微信账号配置移除失败。',
+  'account-state-read-failed': '无法读取微信账号状态文件。',
+  'account-state-write-failed': '无法保存微信账号状态文件。',
+  'account-state-cleanup-failed': '微信账号已移除，但本机状态文件清理失败。',
+  'workspace-save-failed': '无法保存微信工作区设置。',
+  'workspace-cleanup-failed': '微信账号已移除，但工作区设置清理失败。',
+  'start-rejected': '微信账号连接启动失败。',
+  'updates-rejected': '微信消息同步请求被拒绝。',
+  'stop-rejected': '微信服务未确认停止通知。',
+  'connection-stop-failed': '微信消息连接停止时发生错误。',
+  'status-read-failed': '无法读取微信连接状态，请重新读取；之前的操作可能已完成。',
+  'activation-unknown-failed': '微信激活过程中发生未知错误。',
+  'weixin-operation-failed': '微信操作发生未知错误。',
+  'weixin-startup-config-invalid': '微信配置格式错误，请检查 config.json 和 workspaces.json 后重启 DSH。',
+  'weixin-startup-permission-denied': '微信配置访问权限不足，请检查数据目录权限后重启 DSH。',
+  'weixin-startup-failed': '微信初始化失败，请查看 DSH 启动日志。',
+  'connection-failed': '微信连接未就绪。',
+  'rollback-failed': '微信操作失败后，原账号状态恢复失败。',
+  'workspace-not-absolute': '请输入工作区绝对路径。',
+  'workspace-not-found': '工作区目录不存在。',
+  'workspace-not-directory': '工作区路径不是目录。',
+  'workspace-bot-not-found': '找不到要修改的机器人。',
+  'agent-preset-invalid': 'Agent Preset 无效。',
+  'agent-preset-unavailable': 'Agent Preset 不存在或不可用。',
+  'model-selection-invalid': '模型无效。',
+  'model-selection-unavailable': '模型不存在或不可用。',
+  'model-reasoning-unavailable': '当前模型不支持所选思考强度，请重新选择。',
+  'context-enhancement-invalid': '上下文增强设置无效。',
+});
+
+const ownedStages = new WeakMap();
+const reportedErrors = new WeakMap();
+const CODE_STAGES = {
+  'credential-read-failed': ['credential.read', 'credential-store'],
+  'credential-save-failed': ['credential.save', 'credential-store'],
+  'credential-remove-failed': ['credential.remove', 'credential-store'],
+  'missing-token': ['credential.read', 'credential-store'],
+  'account-config-save-failed': ['account.save', 'account-config'],
+  'account-config-remove-failed': ['account.remove', 'account-config'],
+  'account-state-read-failed': ['state.load', 'account-state'],
+  'account-state-write-failed': ['state.write', 'account-state'],
+  'account-state-cleanup-failed': ['state.cleanup', 'account-state'],
+  'workspace-save-failed': ['workspace.write', 'workspace-config'],
+  'workspace-cleanup-failed': ['workspace.cleanup', 'workspace-config'],
+  'qr-encode-failed': ['qr.encode'], 'qr-request-rejected': ['qr.begin'],
+  'start-rejected': ['connection.start'], 'updates-rejected': ['connection.poll'],
+  'stop-rejected': ['connection.stop'], 'rollback-failed': ['rollback'],
+  'runtime-prepare-failed': ['runtime.prepare'], 'connection-start-failed': ['connection.start'],
+  'status-read-failed': ['status.read'],
+};
+
+export function knownWeixinErrorCode(code) { return Object.hasOwn(MESSAGES, code ?? ''); }
+
+/** Annotate at the operation that knows the failing resource; do not inspect exception prose. */
+export function weixinStageError(code, cause, stage) {
+  if (reportedErrors.has(cause)) return cause;
+  const error = new Error('Weixin operation failed', { cause });
+  error.code = knownWeixinErrorCode(code) ? code : 'weixin-operation-failed';
+  const defaults = CODE_STAGES[error.code] ?? [];
+  ownedStages.set(error, { stage: stage ?? defaults[0], resource: defaults[1] });
+  return error;
+}
+
+function chainOf(error) {
+  const chain = [];
+  const seen = new Set();
+  while (error && typeof error === 'object' && !seen.has(error) && chain.length < 4) {
+    seen.add(error);
+    chain.push(error);
+    error = error.cause;
+  }
+  return chain;
+}
+
+function hintFor(code, details) {
+  if (details.rollback === 'failed' || details.rollback === 'unknown') return t('原账号状态尚未确认，请重新读取状态，并反馈诊断信息。');
+  if (details.rollback === 'succeeded') return t('操作未完成，已恢复之前的本机状态。请处理上述问题后重试。');
+  if (code.startsWith('harness-')) return t('请确认当前 DSH 宿主已就绪，并检查 Harness 与插件实际运行版本及宿主日志。');
+  if (details.reason === 'read-only') return t('凭据由只读来源提供，请在启动 DSH 的配置中检查该来源。');
+  if (details.reason === 'ENOTFOUND' || details.reason === 'EAI_AGAIN') return t('微信服务域名解析失败，请检查运行 DSH 的机器的网络和 DNS 设置后重试。');
+  if (['EACCES', 'EPERM', 'EROFS'].includes(details.reason)) return t('请检查 DSH 数据目录和对应文件的读写权限。');
+  if (details.reason === 'ENOSPC') return t('磁盘空间不足，请释放空间后重试。');
+  if (details.reason === 'invalid-json' && details.resource) return t('本机文件格式无效，请检查对应配置或状态文件；不要清空登录凭据。');
+  if (/CERT|TLS|SSL/.test(details.reason ?? '')) return t('请检查运行 DSH 的机器的系统时间、证书和网络设置。');
+  if (code === 'stale-token' || code === 'missing-token') return t('请移除失效接入并重新扫码绑定。');
+  if (details.httpStatus === 429) return t('微信服务限流，请稍后重试。');
+  if (details.httpStatus === 401 || details.httpStatus === 403) return t('访问被拒绝，请检查服务访问限制；HTTP 状态本身不能确认登录凭据已失效。');
+  if (code === 'network-error' || code === 'timeout') return t('请检查运行 DSH 的机器能否访问微信服务，然后重试。');
+  return t('请按参考号查看 DSH 日志，并复制诊断信息反馈。');
+}
+
+export function createWeixinDiagnostics({ logger = console, now = Date.now } = {}) {
+  const recent = new Map();
+  function write(level, record) {
+    try { logger[level]?.(`[dsh-weixin] ${JSON.stringify(record)}`); } catch { /* Diagnostics must not change the operation outcome. */ }
+  }
+  function report(cause, context = {}) {
+    if (reportedErrors.has(cause)) return cause;
+    const chain = chainOf(cause);
+    const selected = chain.find(error => knownWeixinErrorCode(error.code));
+    const code = selected?.code ?? (knownWeixinErrorCode(context.code) ? context.code : 'weixin-operation-failed');
+    const staged = chain.map(error => ownedStages.get(error)).find(Boolean) ?? {};
+    const defaults = CODE_STAGES[code] ?? [];
+    const reason = chain.map(error => normalizeWeixinDiagnosticDetails({ reason: error.code }).reason).find(Boolean)
+      ?? (chain.some(error => error instanceof SyntaxError) ? 'invalid-json' : undefined);
+    const numeric = field => chain.map(error => normalizeWeixinDiagnosticDetails({ [field]: field === 'httpStatus' ? error.status : error[field] })[field]).find(value => value !== undefined);
+    const details = normalizeWeixinDiagnosticDetails({
+      ...context, stage: staged.stage ?? defaults[0] ?? (code.startsWith('harness-') ? 'harness.check' : context.stage),
+      resource: staged.resource ?? defaults[1] ?? context.resource,
+      reason: reason ?? context.reason, httpStatus: numeric('httpStatus'), providerCode: numeric('providerCode'), pluginVersion: packageInfo.version,
+    });
+    const botId = /^wx_[a-f0-9]{24}$/.test(context.botId ?? '') ? context.botId : undefined;
+    const key = JSON.stringify([botId, details.operation, details.stage, code, details.reason, details.httpStatus, details.providerCode]);
+    const previous = recent.get(key);
+    const time = now();
+    if (context.automatic && previous && time - previous.time < 60_000) {
+      previous.retries += 1;
+      const wrapped = new Error(previous.publicError.message, { cause });
+      wrapped.code = code;
+      wrapped.publicError = structuredClone(previous.publicError);
+      reportedErrors.set(wrapped, true);
+      return wrapped;
+    }
+    if (previous?.retries) write('warn', { event: 'connection-retries', referenceId: previous.publicError.details.referenceId, retries: previous.retries });
+    details.referenceId = `WX-CONN-${randomUUID().replaceAll('-', '').slice(0, 8).toUpperCase()}`;
+    details.occurredAt = new Date(time).toISOString();
+    details.hint = hintFor(code, details);
+    const publicError = { code, message: t(MESSAGES[code], { status: details.httpStatus ?? '?' }), details };
+    const wrapped = new Error(publicError.message, { cause });
+    wrapped.code = code;
+    wrapped.publicError = publicError;
+    reportedErrors.set(wrapped, true);
+    if (context.automatic) {
+      if (recent.size >= 128) recent.delete(recent.keys().next().value);
+      recent.set(key, { time, publicError: structuredClone(publicError), retries: 0, botId });
+    }
+    write(context.warning ? 'warn' : 'error', {
+      event: context.warning ? 'connection-warning' : 'connection-failure', code, ...details,
+      ...(botId ? { botId } : {}), pluginVersion: packageInfo.version, nodeVersion: process.versions.node, platform: process.platform,
+      ...(/^WX-CONN-[A-F0-9]{8}$/.test(context.parentReferenceId ?? '') ? { parentReferenceId: context.parentReferenceId } : {}),
+      ...Object.fromEntries(['durationMs', 'timeoutMs'].filter(field => Number.isFinite(cause?.[field]) && cause[field] >= 0).map(field => [field, cause[field]])),
+    });
+    return wrapped;
+  }
+  function clear(botId) {
+    for (const [key, entry] of recent) {
+      if (botId !== undefined && entry.botId !== botId) continue;
+      if (entry.retries) write('info', { event: 'connection-retries', referenceId: entry.publicError.details.referenceId, retries: entry.retries });
+      recent.delete(key);
+    }
+  }
+  function outcome(error, rollback) {
+    if (!reportedErrors.has(error)) return;
+    const details = normalizeWeixinDiagnosticDetails({ rollback });
+    if (!details.rollback) return;
+    error.publicError.details.rollback = details.rollback;
+    error.publicError.details.hint = hintFor(error.code, error.publicError.details);
+    write('info', { event: 'connection-outcome', referenceId: error.publicError.details.referenceId, ...details });
+  }
+  return { report, clear, outcome };
+}

package/src/channels/weixin/diagnostic-details.mjs

@@ -0,0 +1,40 @@
+// Shared by Host and Client: only explicitly admitted diagnostic facts cross the UI boundary.
+const OPERATIONS = new Set([
+  'startup', 'connection.restore', 'connection.monitor', 'connection.close', 'connection.status',
+  'provision.begin', 'provision.poll', 'provision.verify', 'provision.cancel', 'bot.reconnect', 'bot.delete',
+  'bot.workspace.set', 'bot.model.set', 'bot.agent-preset.set', 'bot.context-enhancement.set', 'bot.access-policy.set', 'bot.alias.set',
+]);
+const STAGES = new Set([
+  'startup.load', 'qr.begin', 'qr.encode', 'qr.poll', 'qr.verify', 'qr.cancel', 'credential.read', 'credential.save', 'credential.remove',
+  'account.save', 'account.remove', 'state.load', 'state.write', 'state.cleanup', 'workspace.write', 'workspace.cleanup',
+  'runtime.prepare', 'activation', 'harness.check', 'connection.start', 'connection.poll', 'connection.stop', 'status.read', 'rollback', 'management.request',
+]);
+const REASONS = new Set([
+  'ENOTFOUND', 'EAI_AGAIN', 'ECONNREFUSED', 'ECONNRESET', 'EHOSTUNREACH', 'ENETUNREACH', 'ETIMEDOUT', 'EPIPE',
+  'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT', 'UND_ERR_SOCKET',
+  'CERT_HAS_EXPIRED', 'CERT_NOT_YET_VALID', 'DEPTH_ZERO_SELF_SIGNED_CERT', 'SELF_SIGNED_CERT_IN_CHAIN',
+  'UNABLE_TO_VERIFY_LEAF_SIGNATURE', 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY', 'ERR_TLS_CERT_ALTNAME_INVALID', 'ERR_SSL_WRONG_VERSION_NUMBER',
+  'ENOENT', 'EACCES', 'EPERM', 'ENOSPC', 'EROFS', 'ENOTDIR', 'EISDIR', 'EBUSY', 'EIO', 'EXDEV', 'EMFILE', 'ENFILE', 'EEXIST',
+  'invalid-json', 'read-only',
+]);
+const RESOURCES = new Set(['credential-store', 'account-config', 'account-state', 'workspace-config', 'workspace-directory']);
+
+export function normalizeWeixinDiagnosticDetails(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  const result = {};
+  for (const [field, allowed] of [['operation', OPERATIONS], ['stage', STAGES], ['reason', REASONS], ['resource', RESOURCES]]) {
+    if (allowed.has(value[field])) result[field] = value[field];
+  }
+  if (/^WX-CONN-[A-F0-9]{8}$/.test(value.referenceId ?? '')) result.referenceId = value.referenceId;
+  if (typeof value.occurredAt === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(value.occurredAt)
+    && Number.isFinite(Date.parse(value.occurredAt))) result.occurredAt = value.occurredAt;
+  if (Number.isInteger(value.httpStatus) && value.httpStatus >= 100 && value.httpStatus <= 599) result.httpStatus = value.httpStatus;
+  const provider = typeof value.providerCode === 'number' && Number.isSafeInteger(value.providerCode)
+    ? String(value.providerCode) : value.providerCode;
+  if (typeof provider === 'string' && /^-?\d{1,12}$/.test(provider)) result.providerCode = provider;
+  if (typeof value.pluginVersion === 'string' && /^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(value.pluginVersion)
+    && value.pluginVersion.length <= 64) result.pluginVersion = value.pluginVersion;
+  if (['succeeded', 'failed', 'not-attempted', 'unknown'].includes(value.rollback)) result.rollback = value.rollback;
+  if (typeof value.hint === 'string' && value.hint.trim()) result.hint = value.hint.trim().slice(0, 500);
+  return result;
+}

package/src/channels/weixin/state-store.mjs

@@ -1,3 +1,4 @@
+import { weixinStageError } from './connection-error.mjs';
 import { deferredStateAccess, normalizeDeferredState } from '../shared/deferred-state.mjs';
 import { createHash } from 'node:crypto';
 import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
@@ -123,7 +124,7 @@ export class WeixinStateStore {
     try {
       this.#state = normalizeState(JSON.parse(await readFile(this.#path, 'utf8')));
     } catch (error) {
-      if (error?.code !== 'ENOENT') throw error;
+      if (error?.code !== 'ENOENT') throw weixinStageError('account-state-read-failed', error);
       this.#state = structuredClone(EMPTY_STATE);
       await this.#persist();
     }
@@ -271,7 +272,7 @@ export class WeixinStateStore {
     try {
       await unlink(this.#path);
     } catch (error) {
-      if (error?.code !== 'ENOENT') throw error;
+      if (error?.code !== 'ENOENT') throw weixinStageError('account-state-cleanup-failed', error);
     }
     this.#state = structuredClone(EMPTY_STATE);
   }
@@ -285,6 +286,6 @@ export class WeixinStateStore {
       await rename(temporary, this.#path);
     });
     this.#writeQueue = operation.then(() => undefined, () => undefined);
-    await operation;
+    await operation.catch(error => { throw weixinStageError('account-state-write-failed', error); });
   }
 }

package/src/channels/weixin/weixin-api.mjs

@@ -93,9 +93,9 @@ function uncertainWeixinDelivery(cause) {
   return preserveArtifactMetadata(error, cause);
 }
 
-function rejectedProviderResponse(value) {
+export function rejectedProviderResponse(value, fields = ['ret', 'errcode']) {
   if (!value || typeof value !== 'object') return null;
-  for (const field of ['ret', 'errcode']) {
+  for (const field of fields) {
     if (value[field] !== undefined && value[field] !== 0 && value[field] !== '0') {
       return safeProviderCode(value[field]) ?? 'rejected';
     }
@@ -411,6 +411,7 @@ async function requestJson(fetchImpl, {
   }
 
   const controller = new AbortController();
+  const startedAt = Date.now();
   let timedOut = false;
   const onAbort = () => controller.abort(signal?.reason);
   if (signal?.aborted) throw abortError(signal);
@@ -441,11 +442,16 @@ async function requestJson(fetchImpl, {
     }
   } catch (error) {
     if (signal?.aborted) throw abortError(signal);
+    let failure;
     if (timedOut) {
-      throw new WeixinApiError('timeout', '微信服务请求超时。', { cause: error });
+      failure = new WeixinApiError('timeout', '微信服务请求超时。', { cause: error });
+    } else {
+      failure = error instanceof WeixinApiError ? error
+        : new WeixinApiError('network-error', '暂时无法访问微信服务。', { cause: error });
     }
-    if (error instanceof WeixinApiError) throw error;
-    throw new WeixinApiError('network-error', '暂时无法访问微信服务。', { cause: error });
+    failure.durationMs = Date.now() - startedAt;
+    failure.timeoutMs = timeoutMs;
+    throw failure;
   } finally {
     if (timer) clearTimeout(timer);
     signal?.removeEventListener('abort', onAbort);
@@ -599,6 +605,8 @@ export function createWeixinApi({ fetchImpl = fetch } = {}) {
         signal,
       });
       const qrcode = nonEmptyString(response?.qrcode);
+      const providerCode = rejectedProviderResponse(response, ['errcode', 'ret']);
+      if (providerCode) throw new WeixinApiError('qr-request-rejected', '微信服务拒绝了二维码申请。', { providerCode });
       if (!qrcode) throw new WeixinApiError('invalid-qr', '微信服务没有返回二维码令牌。');
       return {
         qrcode,
@@ -764,14 +772,15 @@ export function createWeixinApi({ fetchImpl = fetch } = {}) {
         timeoutMs: 10_000,
         body: { base_info: baseInfo() },
       });
-      if (response?.ret !== undefined && response.ret !== 0) {
-        throw new WeixinApiError('start-rejected', '微信账号连接启动失败。');
+      const providerCode = rejectedProviderResponse(response, ['errcode', 'ret']);
+      if (providerCode) {
+        throw new WeixinApiError(providerCode === '-14' ? 'stale-token' : 'start-rejected', '微信账号连接启动失败。', { providerCode });
       }
       return response;
     },
 
     async notifyStop({ baseUrl, token, signal }) {
-      return requestJson(fetchImpl, {
+      const response = await requestJson(fetchImpl, {
         method: 'POST',
         baseUrl,
         endpoint: 'ilink/bot/msg/notifystop',
@@ -780,6 +789,9 @@ export function createWeixinApi({ fetchImpl = fetch } = {}) {
         timeoutMs: 10_000,
         body: { base_info: baseInfo() },
       });
+      const providerCode = rejectedProviderResponse(response, ['errcode', 'ret']);
+      if (providerCode) throw new WeixinApiError('stop-rejected', '微信服务未确认停止通知。', { providerCode });
+      return response;
     },
   });
 }

package/src/channels/weixin/weixin-bridge.mjs

@@ -567,9 +567,10 @@ export class WeixinHarnessBridge {
     ].find(Number.isSafeInteger);
     if (quotedAt === undefined) return { unavailableReason: 'not-delivered' };
     const sender = nonEmptyString(reference?.toUserId);
-    const sessionId = sender ? this.#state.sessionFor(conversationKey(sender)) : null;
+    const key = sender ? conversationKey(sender) : null;
+    const sessionId = key ? this.#state.sessionFor(key) : null;
     const session = typeof sessionId === 'string' && sessionId
-      ? this.#harness.workspaceSession?.(sessionId)
+      ? this.#harness.workspaceSession?.(sessionId, key)
       : null;
     if (typeof session?.readHistory !== 'function') {
       return { unavailableReason: 'not-delivered' };