@unlinearity/cli-wechat-bridge 1.1.0 → 1.1.1

package/README.md

@@ -26,6 +26,7 @@
 - [运行配置](docs/configuration.md)：数据目录、上传大小限制、调试开关等环境变量。
 - [开发说明](docs/development.md)：源码运行、测试、构建、打包和全局 smoke 验证。
 - [发布说明](docs/releases/README.md)：各版本变更与升级说明。
+- [通信架构](docs/architecture.md)：三种 CLI 适配器的通信机制、PTY 依赖分析和技术决策。
 
 ## 这个项目解决什么问题？
 
@@ -63,6 +64,35 @@ npm install -g cli-wechat-bridge@latest
 
 兼容性说明：旧包名 `@unlinearity/cli-wechat-bridge` 会继续同步发布，已经安装旧包名的用户可以正常升级；新用户优先使用更短的 `cli-wechat-bridge`。
 
+<details>
+<summary><b>安装遇到问题？（node-pty 原生模块）</b></summary>
+
+本项目使用 `node-pty` 为 CLI 适配器提供完整终端模拟。**Claude Code 适配器当前通过 PTY 交互模式工作**，node-pty 不可用时会回退到兼容模式，但 Claude Code 在此模式下可能无法正常桥接；Codex 适配器主要通过 WebSocket RPC 通信，通常不受影响；OpenCode 适配器完全不依赖 node-pty。
+
+**Linux 用户**（最常见）：需要原生模块编译工具：
+
+```bash
+# Debian / Ubuntu
+sudo apt install build-essential python3
+# RHEL / Fedora
+sudo dnf groupinstall "Development Tools" && sudo dnf install python3
+# Alpine
+apk add build-base python3
+```
+
+安装编译工具后重新安装：`npm install -g cli-wechat-bridge@latest`
+
+**macOS 用户**：如遇编译问题，安装 Xcode 命令行工具：`xcode-select --install`
+
+**Windows 用户**：
+- 需要 Windows 10 1809（build 18309）或更高版本
+- 如果 node-pty 加载失败，运行 `npm rebuild node-pty` 或重新安装
+- 确保已安装 [Visual C++ Redistributable](https://aka.ms/vs/17/release/vc_redist.x64.exe)
+
+运行 `wechat-daemon --doctor` 可快速检查环境状态。详见 [问题排查](docs/troubleshooting.md#pty-不可用--回退模式)。
+
+</details>
+
 ### 3. 完成微信登录
 
 全局安装后运行：

package/dist/bridge/bridge-adapters.shared.js

@@ -1301,6 +1301,9 @@ export function buildSpawnDiagnostic(error, spawnTarget, platform = process.plat
         if (platform === "darwin") {
             lines.push(t("spawn.diagnostic.xcode"));
         }
+        if (platform === "linux") {
+            lines.push(t("spawn.diagnostic.linuxBuildTools"));
+        }
     }
     else if (errorMessage.includes("ENOENT") || errorMessage.includes("spawn")) {
         lines.push(t("spawn.diagnostic.notFound", { target }));
@@ -1310,7 +1313,7 @@ export function buildSpawnDiagnostic(error, spawnTarget, platform = process.plat
     }
     lines.push(t("spawn.diagnostic.nodeVersion"));
     if (platform === "win32") {
-        lines.push(t("spawn.diagnostic.winAdmin"));
+        lines.push(t("spawn.diagnostic.winFull"));
     }
     return lines.join("\n");
 }

package/dist/bridge/wechat-bridge.js

@@ -242,6 +242,11 @@ function printUsageAndExit() {
     process.exit(0);
 }
 async function main() {
+    if (process.argv.includes("--doctor")) {
+        const { runDoctorCheck } = await import("../utils/doctor.js");
+        await runDoctorCheck(process.argv.slice(2), { mode: "bridge" });
+        process.exit(0);
+    }
     const options = parseCliArgs(process.argv.slice(2));
     const daemonEndpoint = readDaemonEndpoint();
     if (daemonEndpoint && await isDaemonEndpointAlive(daemonEndpoint, { timeoutMs: 500 })) {

package/dist/daemon/wechat-daemon.js

@@ -1580,6 +1580,11 @@ export async function runDaemon(options) {
     await daemon.runPollLoop();
 }
 export async function main(argv = process.argv.slice(2)) {
+    if (argv.includes("--doctor")) {
+        const { runDoctorCheck } = await import("../utils/doctor.js");
+        await runDoctorCheck(argv, { mode: "daemon" });
+        process.exit(0);
+    }
     try {
         await runDaemon(parseDaemonCliArgs(argv));
     }

package/dist/i18n/messages-en.js

@@ -26,16 +26,17 @@ export const messages = {
     "hook.healthCheck.logHint": "\nCheck: {logPath}",
     "hook.healthCheck.fixes": "\nCommon fixes:\n- Ensure Node.js >= 22.6.0: node --version\n- Reinstall: npm install -g cli-wechat-bridge@latest\n- Check firewall: allow localhost TCP connections",
     // === PTY fallback ===
-    "pty.fallback.warning": "[Warning] PTY unavailable, using fallback mode. Terminal rendering may be degraded.\n",
+    "pty.fallback.warning": "[Warning] PTY unavailable — using fallback mode (TERM=dumb).\nCore features (messaging, approvals, session management) work normally; terminal rendering (colors, progress bars) may be degraded.\nFix: Linux install build-essential python3 | Windows run npm rebuild node-pty | macOS run xcode-select --install\nRun --doctor for detailed environment info.\n",
     // === Spawn diagnostic ===
     "spawn.diagnostic.title": "Failed to start CLI process: {target}\nError: {error}",
     "spawn.diagnostic.fixesHeader": "\nPossible fixes:",
     "spawn.diagnostic.nodePty": "- The node-pty native module is incompatible with your Node.js version.\n- Run: npm rebuild node-pty\n- Or reinstall: npm install -g cli-wechat-bridge@latest",
     "spawn.diagnostic.xcode": "- Ensure Xcode CLI tools are installed: xcode-select --install",
+    "spawn.diagnostic.linuxBuildTools": "- Linux requires build tools for node-pty: sudo apt install build-essential python3\n- Then reinstall: npm install -g cli-wechat-bridge@latest",
     "spawn.diagnostic.notFound": "- The command \"{target}\" was not found on PATH.\n- Verify it is installed and accessible from your terminal.",
     "spawn.diagnostic.generic": "- Reinstall: npm install -g cli-wechat-bridge@latest",
     "spawn.diagnostic.nodeVersion": "- Ensure Node.js >= 22.6.0: node --version",
-    "spawn.diagnostic.winAdmin": "- If using ConPTY, try running as Administrator.",
+    "spawn.diagnostic.winFull": "- Ensure Windows 10 build 18309+ (run 'winver' to check)\n- Install Visual C++ Redistributable: https://aka.ms/vs/17/release/vc_redist.x64.exe\n- Run: npm rebuild node-pty\n- Try running as Administrator",
     // === Emoji bindings ===
     "binding.usage": "Invalid format.\nUsage: /bind [emoji] command\nExample: /bind 🚀 deploy --prod",
     "binding.bound": "Bound {emoji} → {command}",
@@ -45,4 +46,80 @@ export const messages = {
     "binding.listHeader": "Emoji bindings:",
     // === Version checker ===
     "update.available": "[Update Available] Version {latest} is available (current: {current}).\nRun: npm install -g cli-wechat-bridge@latest",
+    // === Doctor ===
+    "doctor.title": "CLI WeChat Bridge Doctor",
+    "doctor.section.environment": "Environment",
+    "doctor.section.adapterCli": "Adapter commands",
+    "doctor.section.data": "Data",
+    "doctor.section.runtime": "Runtime",
+    "doctor.label.node": "Node.js",
+    "doctor.label.platform": "Platform",
+    "doctor.label.winBuild": "Windows build",
+    "doctor.label.nodePty": "node-pty",
+    "doctor.label.shell": "shell",
+    "doctor.label.dataDir": "Data dir",
+    "doctor.label.credentials": "Credentials",
+    "doctor.label.mode": "Mode",
+    "doctor.label.cwd": "Cwd",
+    "doctor.label.adapter": "Adapter",
+    "doctor.label.daemon": "Daemon",
+    "doctor.label.bridgeLock": "Bridge lock",
+    "doctor.label.workspaceEndpoint": "Workspace endpoint ({adapter})",
+    "doctor.label.legacyEndpoint": "Legacy endpoint",
+    "doctor.winBuildConpty": "(ConPTY requires build 18309+)",
+    "doctor.nodePty.loaded": "loaded",
+    "doctor.nodePty.fix": "Fix: {fix}",
+    "doctor.adapterCli.shellNative": "uses the local shell; no other adapter CLI is checked.",
+    "doctor.adapterCli.notFound": "not found{optional}",
+    "doctor.dataDirMissing": "(will be created on first run)",
+    "doctor.credentialsFound": "found",
+    "doctor.credentialsMissing": "not found (run wechat-setup first)",
+    "doctor.mode.bridge": "standalone bridge",
+    "doctor.mode.generic": "generic",
+    "doctor.notSpecified": "(not specified)",
+    "doctor.none": "none",
+    "doctor.unknown": "unknown",
+    "doctor.yes": "yes",
+    "doctor.no": "no",
+    "doctor.optional": "(optional)",
+    "doctor.invalidShape": "unexpected file shape",
+    "doctor.file": "File: {file}",
+    "doctor.issue": "Issue: {issue}.",
+    "doctor.daemon.invalid": "invalid endpoint file ({error})",
+    "doctor.daemon.stale": "stale endpoint pid={pid} cwd={cwd} port={port}",
+    "doctor.daemon.staleStartup": "Startup: bridge and daemon startup paths will clear stale daemon endpoint state before continuing.",
+    "doctor.daemon.live": "live pid={pid} cwd={cwd} port={port}",
+    "doctor.daemon.liveBridgeStartup": "Startup: standalone bridge will refuse to start while this daemon is live.",
+    "doctor.daemon.liveDaemonStartup": "Startup: daemon startup will request shutdown of this daemon before binding.",
+    "doctor.lock.invalid": "invalid lock file ({error})",
+    "doctor.lock.stale": "stale",
+    "doctor.lock.staleDaemonStartup": "daemon startup will clear this stale single-bridge lock.",
+    "doctor.lock.staleBridgeStartup": "the next standalone bridge start will replace this stale lock.",
+    "doctor.lock.reclaimable": "reclaimable",
+    "doctor.lock.parent": "pid={pid} alive={alive}",
+    "doctor.lock.detail.pid": "pid",
+    "doctor.lock.detail.adapter": "adapter",
+    "doctor.lock.detail.cwd": "cwd",
+    "doctor.lock.detail.lifecycle": "lifecycle",
+    "doctor.lock.detail.startedAt": "started at",
+    "doctor.lock.detail.parent": "parent",
+    "doctor.lock.detail.startup": "startup",
+    "doctor.lock.detail.note": "note",
+    "doctor.lock.reclaimableDaemonStartup": "daemon startup will stop or clear this orphaned single bridge before continuing.",
+    "doctor.lock.reclaimableBridgeStartup": "standalone bridge startup can reclaim this companion-bound or legacy lock because its parent is gone.",
+    "doctor.lock.live": "live",
+    "doctor.lock.liveDaemonStartup": "daemon startup will stop this single bridge before continuing.",
+    "doctor.lock.liveBridgeStartup": "standalone bridge will fail with a lock conflict until this process exits.",
+    "doctor.lock.cwdDifferent": "lock cwd differs from requested cwd ({cwd}); single-bridge lock is global.",
+    "doctor.lock.adapterDifferent": "lock adapter={lockAdapter} differs from requested adapter={requestedAdapter}.",
+    "doctor.endpoint.legacySame": "same as adapter endpoint",
+    "doctor.endpoint.summary": "instance={instanceId} kind={kind} port={port} reachable={reachable}",
+    "doctor.endpoint.owner": "ownerPid={ownerPid} ownerAlive={ownerAlive} companionPid={companionPid} companionAlive={companionAlive} status={status}",
+    "doctor.endpoint.issue.kind": "endpoint kind={kind} differs from requested adapter={adapter}",
+    "doctor.endpoint.issue.cwd": "endpoint cwd differs from requested cwd ({cwd})",
+    "doctor.endpoint.issue.port": "endpoint port {port} is not reachable",
+    "doctor.endpoint.issue.ownerDead": "bridge owner pid={pid} is dead",
+    "doctor.endpoint.issue.companionDead": "companion pid={pid} is dead",
+    "doctor.endpoint.issue.workerStatus": "visible worker status={status}",
+    "doctor.endpoint.issue.instanceMismatch": "endpoint instanceId does not match bridge lock instanceId",
 };

package/dist/i18n/messages-zh.js

@@ -26,16 +26,17 @@ export const messages = {
     "hook.healthCheck.logHint": "\n查看日志: {logPath}",
     "hook.healthCheck.fixes": "\n常见修复方法:\n- 确保 Node.js >= 22.6.0: node --version\n- 重新安装: npm install -g cli-wechat-bridge@latest\n- 检查防火墙: 允许 localhost TCP 连接",
     // === PTY 回退 ===
-    "pty.fallback.warning": "[警告] PTY 不可用，已切换到回退模式。终端渲染可能受限。\n",
+    "pty.fallback.warning": "[警告] PTY 不可用 — 已切换到回退模式（TERM=dumb）。\n核心功能（消息收发、审批、会话管理）正常工作；终端渲染（颜色、进度条）可能受限。\n修复方法: Linux 安装 build-essential python3 | Windows 运行 npm rebuild node-pty | macOS 运行 xcode-select --install\n运行 --doctor 查看详细环境信息。\n",
     // === 启动诊断 ===
     "spawn.diagnostic.title": "无法启动 CLI 进程: {target}\n错误: {error}",
     "spawn.diagnostic.fixesHeader": "\n可能的修复方法:",
     "spawn.diagnostic.nodePty": "- node-pty 原生模块与当前 Node.js 版本不兼容。\n- 运行: npm rebuild node-pty\n- 或重新安装: npm install -g cli-wechat-bridge@latest",
     "spawn.diagnostic.xcode": "- 确保已安装 Xcode 命令行工具: xcode-select --install",
+    "spawn.diagnostic.linuxBuildTools": "- Linux 需要编译工具来构建 node-pty: sudo apt install build-essential python3\n- 然后重新安装: npm install -g cli-wechat-bridge@latest",
     "spawn.diagnostic.notFound": "- 命令 \"{target}\" 未在 PATH 中找到。\n- 请确认已安装并可从终端访问。",
     "spawn.diagnostic.generic": "- 重新安装: npm install -g cli-wechat-bridge@latest",
     "spawn.diagnostic.nodeVersion": "- 确保 Node.js >= 22.6.0: node --version",
-    "spawn.diagnostic.winAdmin": "- 如使用 ConPTY，请尝试以管理员身份运行。",
+    "spawn.diagnostic.winFull": "- 确保 Windows 10 build 18309+（运行 winver 查看）\n- 安装 Visual C++ Redistributable: https://aka.ms/vs/17/release/vc_redist.x64.exe\n- 运行: npm rebuild node-pty\n- 尝试以管理员身份运行",
     // === Emoji 绑定 ===
     "binding.usage": "格式错误。\n用法: /bind [表情] 命令\n示例: /bind 🚀 deploy --prod",
     "binding.bound": "已绑定 {emoji} → {command}",
@@ -45,4 +46,80 @@ export const messages = {
     "binding.listHeader": "Emoji 绑定列表:",
     // === 版本检查 ===
     "update.available": "[有新版本] 版本 {latest} 可用（当前: {current}）。\n运行: npm install -g cli-wechat-bridge@latest",
+    // === Doctor ===
+    "doctor.title": "CLI WeChat Bridge 诊断",
+    "doctor.section.environment": "环境",
+    "doctor.section.adapterCli": "适配器命令",
+    "doctor.section.data": "数据",
+    "doctor.section.runtime": "运行时",
+    "doctor.label.node": "Node.js",
+    "doctor.label.platform": "平台",
+    "doctor.label.winBuild": "Windows build",
+    "doctor.label.nodePty": "node-pty",
+    "doctor.label.shell": "shell",
+    "doctor.label.dataDir": "数据目录",
+    "doctor.label.credentials": "凭据",
+    "doctor.label.mode": "模式",
+    "doctor.label.cwd": "目录",
+    "doctor.label.adapter": "适配器",
+    "doctor.label.daemon": "守护进程",
+    "doctor.label.bridgeLock": "桥接锁",
+    "doctor.label.workspaceEndpoint": "工作区端点 ({adapter})",
+    "doctor.label.legacyEndpoint": "旧端点",
+    "doctor.winBuildConpty": "(ConPTY 需要 build 18309+)",
+    "doctor.nodePty.loaded": "已加载",
+    "doctor.nodePty.fix": "修复: {fix}",
+    "doctor.adapterCli.shellNative": "使用本机 shell，无需检查其它适配器 CLI。",
+    "doctor.adapterCli.notFound": "未找到{optional}",
+    "doctor.dataDirMissing": "(首次运行会创建)",
+    "doctor.credentialsFound": "已找到",
+    "doctor.credentialsMissing": "未找到 (先运行 wechat-setup)",
+    "doctor.mode.bridge": "独立桥接",
+    "doctor.mode.generic": "通用",
+    "doctor.notSpecified": "(未指定)",
+    "doctor.none": "无",
+    "doctor.unknown": "未知",
+    "doctor.yes": "是",
+    "doctor.no": "否",
+    "doctor.optional": "（可选）",
+    "doctor.invalidShape": "文件结构不符合预期",
+    "doctor.file": "文件: {file}",
+    "doctor.issue": "问题: {issue}。",
+    "doctor.daemon.invalid": "端点文件无效 ({error})",
+    "doctor.daemon.stale": "过期端点 pid={pid} cwd={cwd} port={port}",
+    "doctor.daemon.staleStartup": "启动行为: 桥接和守护进程启动路径会先清理过期守护进程端点。",
+    "doctor.daemon.live": "运行中 pid={pid} cwd={cwd} port={port}",
+    "doctor.daemon.liveBridgeStartup": "启动行为: 守护进程运行中时，独立桥接会拒绝启动。",
+    "doctor.daemon.liveDaemonStartup": "启动行为: 守护进程启动会先请求关闭这个旧守护进程再绑定。",
+    "doctor.lock.invalid": "锁文件无效 ({error})",
+    "doctor.lock.stale": "过期",
+    "doctor.lock.staleDaemonStartup": "守护进程启动会清理这个过期的单桥接锁。",
+    "doctor.lock.staleBridgeStartup": "下次独立桥接启动会替换这个过期锁。",
+    "doctor.lock.reclaimable": "可回收",
+    "doctor.lock.parent": "pid={pid} alive={alive}",
+    "doctor.lock.detail.pid": "pid",
+    "doctor.lock.detail.adapter": "适配器",
+    "doctor.lock.detail.cwd": "目录",
+    "doctor.lock.detail.lifecycle": "生命周期",
+    "doctor.lock.detail.startedAt": "启动时间",
+    "doctor.lock.detail.parent": "父进程",
+    "doctor.lock.detail.startup": "启动行为",
+    "doctor.lock.detail.note": "注意",
+    "doctor.lock.reclaimableDaemonStartup": "守护进程启动会先停止或清理这个孤儿单桥接。",
+    "doctor.lock.reclaimableBridgeStartup": "独立桥接可回收这个父进程已退出的锁。",
+    "doctor.lock.live": "运行中",
+    "doctor.lock.liveDaemonStartup": "守护进程启动会先停止这个单桥接。",
+    "doctor.lock.liveBridgeStartup": "该进程退出前，独立桥接会因锁冲突启动失败。",
+    "doctor.lock.cwdDifferent": "锁 cwd 与请求 cwd 不同 ({cwd})；单桥接锁是全局的。",
+    "doctor.lock.adapterDifferent": "锁 adapter={lockAdapter} 与请求 adapter={requestedAdapter} 不同。",
+    "doctor.endpoint.legacySame": "与适配器端点相同",
+    "doctor.endpoint.summary": "实例={instanceId} 类型={kind} 端口={port} 可达={reachable}",
+    "doctor.endpoint.owner": "ownerPid={ownerPid} ownerAlive={ownerAlive} companionPid={companionPid} companionAlive={companionAlive} 状态={status}",
+    "doctor.endpoint.issue.kind": "端点类型 {kind} 与请求适配器 {adapter} 不同",
+    "doctor.endpoint.issue.cwd": "端点 cwd 与请求 cwd 不同 ({cwd})",
+    "doctor.endpoint.issue.port": "端点端口 {port} 不可达",
+    "doctor.endpoint.issue.ownerDead": "桥接 owner pid={pid} 已退出",
+    "doctor.endpoint.issue.companionDead": "companion pid={pid} 已退出",
+    "doctor.endpoint.issue.workerStatus": "可见端 worker 状态={status}",
+    "doctor.endpoint.issue.instanceMismatch": "端点 instanceId 与桥接锁 instanceId 不一致",
 };

package/dist/utils/doctor.js

@@ -0,0 +1,540 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { normalizeBridgeLockPayload, shouldAutoReclaimBridgeLock, } from "../bridge/bridge-state.js";
+import { readLocalCompanionEndpoint as readWorkspaceEndpoint, } from "../companion/local-companion-link.js";
+import { isDaemonEndpointAlive, } from "../daemon/daemon-link.js";
+import { t } from "../i18n/index.js";
+import { resolveChannelDataDir } from "../wechat/channel-config.js";
+const STATE_OK = "[ok]";
+const STATE_WARN = "[warn]";
+const STATE_FAIL = "[fail]";
+const RUNTIME_ENDPOINT_TIMEOUT_MS = 500;
+const DAEMON_ENDPOINT_TIMEOUT_MS = 500;
+function msg(key, params) {
+    return t(`doctor.${key}`, params);
+}
+function section(lines, title) {
+    if (lines.length > 0 && lines.at(-1) !== "") {
+        lines.push("");
+    }
+    lines.push(title);
+}
+function row(status, label, value) {
+    return `  ${status} ${label} ${value}`;
+}
+function fieldRow(label, value) {
+    return `  ${label} ${value}`;
+}
+function detail(value) {
+    return `    ${value}`;
+}
+function detailField(label, value) {
+    return detail(`${label} ${value}`);
+}
+function findExecutable(name) {
+    const cmd = process.platform === "win32" ? "where" : "which";
+    try {
+        return execFileSync(cmd, [name], {
+            stdio: ["ignore", "pipe", "ignore"],
+            encoding: "utf8",
+        }).trim().split(/\r?\n/)[0] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function getPlatformPtyFix(platform) {
+    switch (platform) {
+        case "linux":
+            return "sudo apt install build-essential python3 && npm install -g cli-wechat-bridge@latest";
+        case "darwin":
+            return "xcode-select --install && npm rebuild node-pty";
+        case "win32":
+            return "npm rebuild node-pty (also ensure Visual C++ Redistributable is installed)";
+        default:
+            return "npm rebuild node-pty";
+    }
+}
+function defaultIsProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function defaultIsTcpPortReachable(port, timeoutMs) {
+    if (!Number.isInteger(port) || port <= 0) {
+        return false;
+    }
+    return await new Promise((resolve) => {
+        const socket = net.connect({
+            host: "127.0.0.1",
+            port,
+        });
+        let done = false;
+        const finish = (result) => {
+            if (done) {
+                return;
+            }
+            done = true;
+            socket.destroy();
+            resolve(result);
+        };
+        socket.setTimeout(timeoutMs);
+        socket.once("connect", () => finish(true));
+        socket.once("timeout", () => finish(false));
+        socket.once("error", () => finish(false));
+    });
+}
+function resolveDeps(deps = {}) {
+    return {
+        platform: deps.platform ?? process.platform,
+        arch: deps.arch ?? process.arch,
+        nodeVersion: deps.nodeVersion ?? process.version,
+        osRelease: deps.osRelease ?? os.release,
+        findExecutable: deps.findExecutable ?? findExecutable,
+        loadNodePty: deps.loadNodePty ??
+            (async () => {
+                await import("node-pty");
+            }),
+        resolveDataDir: deps.resolveDataDir ?? resolveChannelDataDir,
+        exists: deps.exists ?? fs.existsSync,
+        readTextFile: deps.readTextFile ??
+            ((filePath) => fs.readFileSync(filePath, "utf8")),
+        isProcessAlive: deps.isProcessAlive ?? defaultIsProcessAlive,
+        isTcpPortReachable: deps.isTcpPortReachable ?? defaultIsTcpPortReachable,
+        isDaemonAlive: deps.isDaemonAlive ??
+            ((endpoint) => isDaemonEndpointAlive(endpoint, { timeoutMs: DAEMON_ENDPOINT_TIMEOUT_MS })),
+        readLocalCompanionEndpoint: deps.readLocalCompanionEndpoint ??
+            ((cwd, adapter) => readWorkspaceEndpoint(cwd, adapter ? { adapter } : {})),
+    };
+}
+function isBridgeAdapterKind(value) {
+    return (value === "codex" ||
+        value === "claude" ||
+        value === "opencode" ||
+        value === "shell");
+}
+export function parseDoctorCliArgs(argv, mode = "generic", fallbackCwd = process.cwd()) {
+    let cwd = fallbackCwd;
+    let adapter;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        const next = argv[i + 1];
+        if (!arg) {
+            continue;
+        }
+        if (arg === "--cwd" && next) {
+            cwd = path.resolve(next);
+            i += 1;
+            continue;
+        }
+        if (arg === "--adapter" && isBridgeAdapterKind(next)) {
+            adapter = next;
+            i += 1;
+            continue;
+        }
+    }
+    return {
+        mode,
+        cwd: path.resolve(cwd),
+        adapter,
+    };
+}
+function statusTag(status) {
+    if (status === "ok") {
+        return STATE_OK;
+    }
+    if (status === "warn") {
+        return STATE_WARN;
+    }
+    return STATE_FAIL;
+}
+function shortError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.length > 100 ? `${message.slice(0, 100)}...` : message;
+}
+function sameWorkspacePath(left, right) {
+    const normalizedLeft = path.resolve(left);
+    const normalizedRight = path.resolve(right);
+    return process.platform === "win32"
+        ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
+        : normalizedLeft === normalizedRight;
+}
+function normalizeDaemonEndpoint(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    const record = value;
+    if (typeof record.protocolVersion !== "number" ||
+        typeof record.pid !== "number" ||
+        typeof record.port !== "number" ||
+        typeof record.token !== "string" ||
+        typeof record.cwd !== "string" ||
+        typeof record.startedAt !== "string") {
+        return null;
+    }
+    return {
+        protocolVersion: record.protocolVersion,
+        pid: record.pid,
+        port: record.port,
+        token: record.token,
+        cwd: record.cwd,
+        startedAt: record.startedAt,
+    };
+}
+function readNormalizedJsonFile(filePath, deps, normalize) {
+    if (!deps.exists(filePath)) {
+        return { kind: "missing", filePath };
+    }
+    try {
+        const parsed = JSON.parse(deps.readTextFile(filePath));
+        const normalized = normalize(parsed);
+        if (!normalized) {
+            return {
+                kind: "invalid",
+                filePath,
+                error: msg("invalidShape"),
+            };
+        }
+        return {
+            kind: "ok",
+            filePath,
+            value: normalized,
+        };
+    }
+    catch (error) {
+        return {
+            kind: "invalid",
+            filePath,
+            error: shortError(error),
+        };
+    }
+}
+function formatMode(mode) {
+    if (mode === "bridge") {
+        return msg("mode.bridge");
+    }
+    if (mode === "daemon") {
+        return "wechat-daemon";
+    }
+    return msg("mode.generic");
+}
+function formatAlive(value) {
+    if (value === undefined) {
+        return msg("unknown");
+    }
+    return value ? msg("yes") : msg("no");
+}
+function appendLockDetailLines(lines, lock) {
+    lines.push(detailField(msg("lock.detail.pid"), String(lock.pid)));
+    lines.push(detailField(msg("lock.detail.adapter"), lock.adapter));
+    lines.push(detailField(msg("lock.detail.cwd"), lock.cwd));
+    lines.push(detailField(msg("lock.detail.lifecycle"), lock.lifecycle));
+    lines.push(detailField(msg("lock.detail.startedAt"), lock.startedAt));
+}
+async function appendDaemonLines(lines, options, dataDir, deps) {
+    const endpointFile = path.join(dataDir, "daemon-endpoint.json");
+    const endpointResult = readNormalizedJsonFile(endpointFile, deps, normalizeDaemonEndpoint);
+    const label = msg("label.daemon");
+    if (endpointResult.kind === "missing") {
+        lines.push(row(STATE_OK, label, msg("none")));
+        return;
+    }
+    if (endpointResult.kind === "invalid") {
+        lines.push(row(STATE_WARN, label, msg("daemon.invalid", {
+            error: endpointResult.error,
+        })));
+        lines.push(detail(msg("file", { file: endpointResult.filePath })));
+        return;
+    }
+    const endpoint = endpointResult.value;
+    const pidAlive = deps.isProcessAlive(endpoint.pid);
+    const daemonAlive = pidAlive ? await deps.isDaemonAlive(endpoint) : false;
+    if (!daemonAlive) {
+        lines.push(row(STATE_WARN, label, msg("daemon.stale", {
+            pid: endpoint.pid,
+            cwd: endpoint.cwd,
+            port: endpoint.port,
+        })));
+        lines.push(detail(msg("daemon.staleStartup")));
+        return;
+    }
+    const status = options.mode === "bridge" ? "fail" : "warn";
+    lines.push(row(statusTag(status), label, msg("daemon.live", {
+        pid: endpoint.pid,
+        cwd: endpoint.cwd,
+        port: endpoint.port,
+    })));
+    if (options.mode === "bridge") {
+        lines.push(detail(msg("daemon.liveBridgeStartup")));
+    }
+    else if (options.mode === "daemon") {
+        lines.push(detail(msg("daemon.liveDaemonStartup")));
+    }
+}
+function appendBridgeLockLines(lines, options, dataDir, deps) {
+    const lockFile = path.join(dataDir, "bridge.lock.json");
+    const lockResult = readNormalizedJsonFile(lockFile, deps, normalizeBridgeLockPayload);
+    const label = msg("label.bridgeLock");
+    if (lockResult.kind === "missing") {
+        lines.push(row(STATE_OK, label, msg("none")));
+        return null;
+    }
+    if (lockResult.kind === "invalid") {
+        lines.push(row(STATE_WARN, label, msg("lock.invalid", {
+            error: lockResult.error,
+        })));
+        lines.push(detail(msg("file", { file: lockResult.filePath })));
+        return null;
+    }
+    const lock = lockResult.value;
+    const lockAlive = deps.isProcessAlive(lock.pid);
+    const parentAlive = lock.parentPid > 1 ? deps.isProcessAlive(lock.parentPid) : undefined;
+    const reclaimable = lockAlive
+        ? shouldAutoReclaimBridgeLock(lock, deps.isProcessAlive)
+        : false;
+    if (!lockAlive) {
+        lines.push(row(STATE_WARN, label, msg("lock.stale")));
+        appendLockDetailLines(lines, lock);
+        lines.push(detailField(msg("lock.detail.startup"), options.mode === "daemon"
+            ? msg("lock.staleDaemonStartup")
+            : msg("lock.staleBridgeStartup")));
+    }
+    else if (reclaimable) {
+        lines.push(row(STATE_WARN, label, msg("lock.reclaimable")));
+        appendLockDetailLines(lines, lock);
+        lines.push(detailField(msg("lock.detail.parent"), msg("lock.parent", {
+            pid: lock.parentPid,
+            alive: formatAlive(parentAlive),
+        })));
+        lines.push(detailField(msg("lock.detail.startup"), options.mode === "daemon"
+            ? msg("lock.reclaimableDaemonStartup")
+            : msg("lock.reclaimableBridgeStartup")));
+    }
+    else if (options.mode === "daemon") {
+        lines.push(row(STATE_WARN, label, msg("lock.live")));
+        appendLockDetailLines(lines, lock);
+        lines.push(detailField(msg("lock.detail.startup"), msg("lock.liveDaemonStartup")));
+    }
+    else {
+        lines.push(row(STATE_FAIL, label, msg("lock.live")));
+        appendLockDetailLines(lines, lock);
+        lines.push(detailField(msg("lock.detail.startup"), msg("lock.liveBridgeStartup")));
+    }
+    if (!sameWorkspacePath(lock.cwd, options.cwd)) {
+        lines.push(detailField(msg("lock.detail.note"), msg("lock.cwdDifferent", { cwd: options.cwd })));
+    }
+    if (options.adapter && lock.adapter !== options.adapter) {
+        lines.push(detailField(msg("lock.detail.note"), msg("lock.adapterDifferent", {
+            lockAdapter: lock.adapter,
+            requestedAdapter: options.adapter,
+        })));
+    }
+    return lock;
+}
+function chooseEndpointAdapters(options, lock) {
+    if (options.adapter) {
+        return [options.adapter];
+    }
+    if (lock) {
+        return [lock.adapter];
+    }
+    return options.mode === "daemon"
+        ? ["codex", "claude", "opencode"]
+        : ["codex"];
+}
+function chooseCliChecks(options) {
+    if (options.mode === "bridge") {
+        switch (options.adapter) {
+            case "codex":
+                return [{ name: "codex", label: "Codex CLI", optional: false }];
+            case "claude":
+                return [{ name: "claude", label: "Claude CLI", optional: false }];
+            case "opencode":
+                return [{ name: "opencode", label: "OpenCode", optional: false }];
+            case "shell":
+                return [];
+            default:
+                return [];
+        }
+    }
+    return [
+        { name: "codex", label: "Codex CLI", optional: true },
+        { name: "claude", label: "Claude CLI", optional: true },
+        { name: "opencode", label: "OpenCode", optional: true },
+    ];
+}
+function appendCliLines(lines, options, deps) {
+    const clis = chooseCliChecks(options);
+    if (options.mode === "bridge" && options.adapter === "shell") {
+        section(lines, msg("section.adapterCli"));
+        lines.push(row(STATE_OK, msg("label.shell"), msg("adapterCli.shellNative")));
+        return;
+    }
+    if (clis.length === 0) {
+        return;
+    }
+    section(lines, msg("section.adapterCli"));
+    for (const cli of clis) {
+        const loc = deps.findExecutable(cli.name);
+        if (loc) {
+            lines.push(row(STATE_OK, cli.label, loc));
+        }
+        else {
+            lines.push(row(STATE_FAIL, cli.label, msg("adapterCli.notFound", {
+                optional: cli.optional ? ` ${msg("optional")}` : "",
+            })));
+        }
+    }
+}
+async function appendEndpointSummary(lines, label, endpoint, options, lock, deps) {
+    if (!endpoint) {
+        lines.push(row(STATE_OK, label, msg("none")));
+        return;
+    }
+    const port = endpoint.serverPort ?? endpoint.port;
+    const reachable = await deps.isTcpPortReachable(port, RUNTIME_ENDPOINT_TIMEOUT_MS);
+    const bridgeOwnerAlive = endpoint.bridgeOwnerPid
+        ? deps.isProcessAlive(endpoint.bridgeOwnerPid)
+        : undefined;
+    const companionAlive = endpoint.companionPid
+        ? deps.isProcessAlive(endpoint.companionPid)
+        : undefined;
+    const issues = [];
+    if (options.adapter && endpoint.kind !== options.adapter) {
+        issues.push(msg("endpoint.issue.kind", {
+            kind: endpoint.kind,
+            adapter: options.adapter,
+        }));
+    }
+    if (!sameWorkspacePath(endpoint.cwd, options.cwd)) {
+        issues.push(msg("endpoint.issue.cwd", { cwd: options.cwd }));
+    }
+    if (!reachable) {
+        issues.push(msg("endpoint.issue.port", { port }));
+    }
+    if (bridgeOwnerAlive === false) {
+        issues.push(msg("endpoint.issue.ownerDead", {
+            pid: endpoint.bridgeOwnerPid ?? msg("none"),
+        }));
+    }
+    if (companionAlive === false) {
+        issues.push(msg("endpoint.issue.companionDead", {
+            pid: endpoint.companionPid ?? msg("none"),
+        }));
+    }
+    if (endpoint.companionStatus === "stopped" ||
+        endpoint.companionStatus === "error") {
+        issues.push(msg("endpoint.issue.workerStatus", {
+            status: endpoint.companionStatus,
+        }));
+    }
+    if (lock &&
+        endpoint.kind === lock.adapter &&
+        sameWorkspacePath(endpoint.cwd, lock.cwd) &&
+        endpoint.instanceId !== lock.instanceId) {
+        issues.push(msg("endpoint.issue.instanceMismatch"));
+    }
+    const status = issues.length > 0 ? "warn" : "ok";
+    lines.push(row(statusTag(status), label, msg("endpoint.summary", {
+        instanceId: endpoint.instanceId,
+        kind: endpoint.kind,
+        port,
+        reachable: reachable ? msg("yes") : msg("no"),
+    })));
+    lines.push(detail(msg("endpoint.owner", {
+        ownerPid: endpoint.bridgeOwnerPid ?? msg("none"),
+        ownerAlive: formatAlive(bridgeOwnerAlive),
+        companionPid: endpoint.companionPid ?? msg("none"),
+        companionAlive: formatAlive(companionAlive),
+        status: endpoint.companionStatus ?? msg("unknown"),
+    })));
+    for (const issue of issues) {
+        lines.push(detail(msg("issue", { issue })));
+    }
+}
+async function appendWorkspaceEndpointLines(lines, options, lock, deps) {
+    const adapters = chooseEndpointAdapters(options, lock);
+    const seenEndpoints = new Set();
+    for (const adapter of adapters) {
+        const endpoint = deps.readLocalCompanionEndpoint(options.cwd, adapter);
+        if (endpoint) {
+            seenEndpoints.add(`${endpoint.kind}:${endpoint.instanceId}:${endpoint.port}`);
+        }
+        await appendEndpointSummary(lines, msg("label.workspaceEndpoint", { adapter }), endpoint, { ...options, adapter }, lock, deps);
+    }
+    const legacyEndpoint = deps.readLocalCompanionEndpoint(options.cwd);
+    const legacyLabel = msg("label.legacyEndpoint");
+    if (!legacyEndpoint) {
+        lines.push(row(STATE_OK, legacyLabel, msg("none")));
+        return;
+    }
+    const legacyKey = `${legacyEndpoint.kind}:${legacyEndpoint.instanceId}:${legacyEndpoint.port}`;
+    if (seenEndpoints.has(legacyKey)) {
+        lines.push(row(STATE_OK, legacyLabel, msg("endpoint.legacySame")));
+        return;
+    }
+    await appendEndpointSummary(lines, legacyLabel, legacyEndpoint, options, lock, deps);
+}
+export async function buildDoctorReport(options = {}, rawDeps = {}) {
+    const deps = resolveDeps(rawDeps);
+    const parsed = parseDoctorCliArgs(options.argv ?? process.argv.slice(2), options.mode ?? "generic", options.cwd ?? process.cwd());
+    const doctorOptions = {
+        ...parsed,
+        cwd: path.resolve(options.cwd ?? parsed.cwd),
+        adapter: options.adapter ?? parsed.adapter,
+    };
+    const lines = [];
+    lines.push(msg("title"));
+    section(lines, msg("section.environment"));
+    lines.push(row(STATE_OK, msg("label.node"), deps.nodeVersion));
+    lines.push(row(STATE_OK, msg("label.platform"), `${deps.platform}-${deps.arch}`));
+    if (deps.platform === "win32") {
+        const release = deps.osRelease();
+        const build = parseInt(release.split(".").pop() ?? "0", 10);
+        const ok = build >= 18309;
+        lines.push(row(ok ? STATE_OK : STATE_FAIL, msg("label.winBuild"), ok ? String(build) : `${build} ${msg("winBuildConpty")}`));
+    }
+    try {
+        await deps.loadNodePty();
+        lines.push(row(STATE_OK, msg("label.nodePty"), msg("nodePty.loaded")));
+    }
+    catch (error) {
+        lines.push(row(STATE_FAIL, msg("label.nodePty"), shortError(error)));
+        lines.push(detail(msg("nodePty.fix", { fix: getPlatformPtyFix(deps.platform) })));
+    }
+    appendCliLines(lines, doctorOptions, deps);
+    section(lines, msg("section.data"));
+    const dataDir = deps.resolveDataDir();
+    const dataDirExists = deps.exists(dataDir);
+    lines.push(row(dataDirExists ? STATE_OK : STATE_FAIL, msg("label.dataDir"), dataDirExists ? dataDir : `${dataDir} ${msg("dataDirMissing")}`));
+    const credFile = path.join(dataDir, "account.json");
+    const credExists = deps.exists(credFile);
+    lines.push(row(credExists ? STATE_OK : STATE_FAIL, msg("label.credentials"), credExists ? msg("credentialsFound") : msg("credentialsMissing")));
+    section(lines, msg("section.runtime"));
+    lines.push(fieldRow(msg("label.mode"), formatMode(doctorOptions.mode)));
+    lines.push(fieldRow(msg("label.cwd"), doctorOptions.cwd));
+    lines.push(fieldRow(msg("label.adapter"), doctorOptions.adapter ?? msg("notSpecified")));
+    lines.push("");
+    await appendDaemonLines(lines, doctorOptions, dataDir, deps);
+    const lock = appendBridgeLockLines(lines, doctorOptions, dataDir, deps);
+    await appendWorkspaceEndpointLines(lines, doctorOptions, lock, deps);
+    lines.push("");
+    return lines;
+}
+export async function runDoctorCheck(argv = process.argv.slice(2), options = {}) {
+    const lines = await buildDoctorReport({
+        argv,
+        mode: options.mode ?? "generic",
+    });
+    process.stdout.write(lines.join("\n") + "\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unlinearity/cli-wechat-bridge",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "CLI WeChat Bridge for Codex, Claude Code, OpenCode, and PowerShell over WeChat",
   "type": "module",
   "files": [