ai-cli-gateway 1.1.0__py3-none-any.whl

ai_cli_gateway-1.1.0.dist-info/METADATA

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: ai-cli-gateway
+Version: 1.1.0
+Summary: 统一 CLI 进程调用网关：全量日志落盘 + 回放 + 结构化返回——AI 调 CLI 的可观测层
+Author: ningL32
+License: MIT
+Project-URL: Homepage, https://github.com/ningL32/cli-gateway
+Project-URL: Changelog, https://github.com/ningL32/cli-gateway/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/ningL32/cli-gateway/issues
+Keywords: subprocess,cli,gateway,audit,observability,ai-agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# cli-gateway
+
+统一 CLI 进程调用网关：让"AI 调 CLI 是否真跑、输出能否逐字核对"变得可观测、可审计、可回放。
+
+**v1 定位**：本地 subprocess 薄包装。不涉及任何 URL/网络请求。
+
+## 为什么
+
+团队有 9 个 CLI（claude / codex / kilo / mcode / goose / opencode / qoder / crush / hermes）作为 agent 运行时。痛点：
+- 调用了但无法直接观测原始 stdout/stderr，只能靠进程日志+时间戳佐证"跑了"；
+- 无法逐字核对输出、无法回放、无法统一审计。
+
+`cli-gateway` 把任何 CLI 调用包装成"全量日志落盘 + 可回放 + 结构化返回"，让每次调用可观测、可审计、可验证。
+
+## 快速开始
+
+```bash
+pip install ai-cli-gateway   # PyPI 安装（PyPI 上 `cli-gateway` 名字已被占，故用此名）
+pip install -e .             # 或本仓开发安装（或直接 PYTHONPATH=.）
+
+# 作为库
+from cli_gateway import run, replay
+res = run(["claude", "--version"])
+print(res.exit_code, res.duration_ms, res.log_path)
+print(replay(res.log_path))   # 逐字回放
+
+# 作为 CLI
+# 注意：--timeout/--dir 必须写在 -- 之前；-- 之后的参数全部属于被调命令
+cli-gateway run --timeout 10 -- echo hello
+cli-gateway replay ~/.cli-gateway/logs/20261018-190000-echo-abc12345.log
+cli-gateway logs
+cli-gateway doctor
+```
+
+## 返回结构（GatewayResult）
+
+| 字段 | 说明 |
+|---|---|
+| `command` | 原始命令 |
+| `exit_code` | 退出码：命令未找到=**127**，启动失败（不可执行等）=**126**，超时=**124**，其余为命令真实退出码（POSIX 被信号杀死时为负信号值） |
+| `duration_ms` | 耗时毫秒 |
+| `log_path` | 全量日志文件路径 |
+| `stdout_tail` / `stderr_tail` | 输出尾部（默认各 2000 字符，从日志文件取尾，内存有界） |
+| `timestamp` / `pid` / `success` | 时间戳 / 真实进程号 / 是否成功 |
+| `state` | 枚举：`completed` / `timed_out` / `not_found` / `spawn_error` / `killed`（spawn_error 是对 shell 惯例枚举的扩展） |
+| `cwd` | 本次调用的 working directory（未传为 None） |
+| `truncated` | 输出超过 tail 长度被截断时为 True |
+| `timed_out` | 超时标志（等价 `state == "timed_out"`） |
+| `env_overrides` | 显式传入的 env 覆盖项（含 KEY/TOKEN/SECRET/PASSWORD 的值脱敏为 `***`，不记录全量环境） |
+
+## 日志格式
+
+每次调用写一个文件 `<ts>-<cmd>-<id>.log`：元数据头（command/timestamp/pid/cwd/env_overrides/timeout）+ STDOUT 段 + STDERR 段 + END + 结果尾（exit_code/duration_ms/state），可逐字回放、可审计。超时路径保留已产生的部分输出（partial）。
+
+## 注册表（run_cli，白名单路径）
+
+```python
+from cli_gateway import REGISTRY, CliSpec, run_cli
+
+REGISTRY["claude"] = CliSpec(default_timeout=600, tail=2000)  # 零依赖顶层 dict
+res = run_cli("claude", "--version")        # 未注册名字 → KeyError；run() 不查注册表
+```
+
+`CliSpec` 字段：`default_timeout` / `capture` / `tail` / `cwd` / `env` / `retry_on`。重试只在显式传 `retry_count` 时发生，且只重试"启动前失败"（`not_found` / `spawn_error`；超时与非零退出绝不自动重试），每次尝试独立日志文件。`retry_on` 字段当前仅支持 `"spawn"`，其他值保留但不生效。
+
+## Windows 须知：npm shim 与直调
+
+Windows 上 `Popen` 直控走 `CreateProcess`，只解析 `.exe`——npm 全局安装的 CLI（claude / kilo / mcode / opencode 等）目录里只有 `xxx.cmd` shim，直接传名字会得到 `127/not_found`。两种调用方式：
+
+- **原生 exe 直调**：codex / goose / qoderclicn / hermes；crush 的 npm shim 没有 `.exe` 同名文件，`CreateProcess` 会继续搜 PATH 命中 WinGet 的 `crush.exe`，同样直调可用；
+- **npm shim 用 `cmd /c <name> ...` 包装**：gateway 的 `taskkill /T` 树杀仍覆盖 cmd 与其下的整棵进程树。
+
+Git Bash 传参注意：MSYS 会把独立参数 `/c` 转换成 `C:\`，命令行路径须写 `cmd //c` 或设 `MSYS_NO_PATHCONV=1`；走 Python 库传 argv 列表不受影响。
+
+## 真机验证矩阵（2026-10-18，Windows Server 2022）
+
+9 个 CLI 全部经网关真实验证：`--version` 探测 + 真实模型调用（提示词"只回复两个字：收到"）各一次。
+
+| CLI | 版本 | 直调方式 | 非交互用法 | 真实调用 |
+|---|---|---|---|---|
+| claude | 2.1.177 | `cmd /c claude` | `claude -p "<prompt>"` | ✅ |
+| codex | 0.162.1 | 直调 exe | `codex exec "<prompt>"` | ✅ |
+| kilo | 7.7.5 | `cmd /c kilo` | `kilo run "<prompt>"` | ✅ |
+| mcode | 0.4.12 | `cmd /c mcode` | `mcode exec "<prompt>"` | ✅ |
+| goose | 1.51.0 | 直调 exe | `goose run -t "<prompt>"` | ✅ |
+| opencode | 1.18.31 | `cmd /c opencode` | `opencode run "<prompt>"` | ✅ |
+| qoder | 1.1.72 | 直调 exe（命令名 `qoderclicn`） | `qoderclicn -p "<prompt>"` | ✅ |
+| crush | v0.88.0 | 直调 exe（自动命中 WinGet 版） | `crush run "<prompt>"` | ✅ |
+| hermes | v0.21.3 | 直调 exe | `hermes -z "<prompt>"` | ✅ |
+
+矩阵可在你自己的机器上实时复现：
+
+```bash
+cli-gateway doctor                # 体检内置 9 个编码 CLI：形态/版本/日志路径
+cli-gateway doctor --json         # 结构化输出（agent 消费友好）
+cli-gateway doctor --no-probe     # 静态快查：只看安装形态，不实跑版本探测
+cli-gateway doctor --only codex   # 只查指定命令
+```
+
+形态判定以网关真实调用结果为准（先直调，Windows 下 not_found 自动再试 `cmd /c` 包装），不是静态猜测；全部可用退出码 0，否则 1——可直接接进 CI 或 agent 的启动自检。
+
+## 子智能体编队（agents/）
+
+[agents/](agents/) 内置 9 个编码 CLI 的 **ZCode 子代理操作员提示词**——上表 9 个 CLI 各配一个"专属操作员"：主会话（工头）负责拆解派工与验收，子代理通过 Bash 调用对应 CLI 真进程干活。方法论（C4/ADR/TDD/变异测试/八维审查等）全部内置在提示词里，开箱即用。
+
+| 文件 | 角色 | 擅长 |
+|---|---|---|
+| [claude.md](agents/claude.md) | 首席架构 | C4/ADR 架构规格、多维评审、技术决策 |
+| [codex.md](agents/codex.md) | 资深攻坚 | 五 Why 根因、性能剖析、Strangler Fig 重构 |
+| [opencode.md](agents/opencode.md) | 全栈 | React/Next + Node/Python + DB 前后端通吃 |
+| [mcode.md](agents/mcode.md) | 功能实现 | TDD 红绿重构一棒到底 |
+| [kilo.md](agents/kilo.md) | 功能实现 | 补位实现、修测试、环境坑 |
+| [crush.md](agents/crush.md) | 功能实现 | 快速编码、LSP 语义辅助 |
+| [goose.md](agents/goose.md) | QA | 测试金字塔、Playwright 真机验证、变异测试防假绿 |
+| [qoder.md](agents/qoder.md) | 代码评审 | 八维审查、异构模型交叉复核 |
+| [hermes.md](agents/hermes.md) | 研究员 | 技术调研、复盘 postmortem、经验库回写 |
+
+### 安装
+
+```bash
+# 用户级（所有项目生效）
+cp agents/*.md ~/.zcode/agents/
+
+# 或项目级（仅当前项目生效）
+cp agents/*.md .zcode/agents/
+```
+
+重启 ZCode 会话后生效，Agent 工具即可按 `name` 派工（如 `subagent_type: "codex"`）。其他支持自定义子代理的框架同样可用：这些 `.md` 本质是"角色化操作员提示词 + 调用配方"，粘贴为任意 agent 的系统提示词即可复用。
+
+### 使用
+
+主会话按岗位派工，派单三要素（目标/范围/完成标准）写清，例如：
+
+```markdown
+# 任务
+修复 tests/test_api.py 中 3 个失败用例（并发写竞态）
+
+# 完成标准
+pytest 全绿 + 亲自运行过验证命令
+
+# 约束
+只改 src/worker.py，不动接口签名
+```
+
+子代理按固定三段式汇报（修改了什么 / 如何验证 / 哪些仍未验证）；经 cli-gateway 留证调用的，汇报附 `log=` 路径，验收方 `cli-gateway replay <log>` 逐字回放复核——**验收不轻信汇报文字**。
+
+### 提示词结构（自定义时照此改）
+
+每个文件的固定骨架：`frontmatter`（`name` 派工标识 / `description` 主会话路由依据 / `tools` 工具白名单 / `injectAgentsMd`）+ 正文（岗位定位与方法论 / 完成条件 / 预检三问 / 固定汇报格式 / 退化路径 / 调用方式含 cli-gateway 留证配方 / 红线 / 实测档案）。
+
+### 定制指引
+
+- **CLI 名称/版本不同**：改「调用方式」节的命令与核对版本即可，方法论不绑定具体 CLI
+- **后端不是 GLM**：这些操作员原本跑在 GLM 后端，换 provider 只需改 CLI 侧的 provider 配置，提示词无需动
+- **POSIX 环境**：调用配方中 `cmd //c` 包装与 MSYS 注意事项仅适用 Windows + Git Bash，POSIX 直接写命令名
+- **开源版说明**：`agents/` 为脱敏模板（团队名/内网配置/实测记录已替换为占位或通用表述），各文件末尾的「实测档案」留作你的团队自行回写
+
+## 超时与进程组
+
+超时（`timeout` 秒，默认无限等）会按进程组/进程树终止：POSIX 用 `start_new_session` + `os.killpg`（先 SIGTERM，宽限 2s 后 SIGKILL）；Windows 用 `CREATE_NEW_PROCESS_GROUP` + `taskkill /F /T`。这会大幅降低孤儿孙进程残留的概率，但不是绝对保证——极端场景（第三方进程自行脱离进程组/进程树、或孙进程继承管道写句柄导致输出流不关闭）可能有残留或输出不完整，此时结果会置 `truncated=True` 并在日志尾部追加 `# warning:` 行，由调用方按需兜底。
+
+POSIX 下进程被信号杀死时 `state="killed"`、`exit_code` 为负信号值；Windows 正常退出（含非零退出码）均为 `completed`。
+
+输出读取统一按 UTF-8（`errors="replace"`），日志始终是合法 UTF-8。gateway 默认向子进程注入 `PYTHONUTF8=1`（调用方或父环境已显式设置该变量时不覆盖），使 python 类子进程在 Windows 传统代码页（CP936 等）环境下也输出 UTF-8——注意子进程会看到这个变量。
+
+## 设计边界（v1）
+
+- **只做本地 subprocess**，不发起 URL/网络请求——未来 v2 若加远程/HTTP 能力，服务端请求 URL 时仅允许 http/https，且发请求前校验 host、拒绝 localhost/环回/私有/保留地址；
+- 不做沙箱（用 Docker 的 MCP 网关管沙箱，见下）；不做 Web UI；不做多租户。
+
+## 与 docker/mcp-gateway 的关系（不同层）
+
+| | docker/mcp-gateway | cli-gateway |
+|---|---|---|
+| 管 | MCP 服务器（外部工具数据源，Docker 容器） | CLI 进程调用（本地 subprocess） |
+| 解决 | AI 统一访问 MCP 服务器 + 认证/密钥 | CLI 调用日志落盘/回放/结构化返回 |
+| 层 | 协议层（MCP） | 进程层（subprocess） |
+
+两者互补不冲突：MCP 网关管"AI 连外部工具"，cli-gateway 管"AI 调本地 CLI"。
+
+## License
+
+MIT
+
+## 安全约束（Mimosa）
+
+本仓库 v1 不发起任何网络请求。若未来扩展远程调用，必须遵守：仅允许 http/https；发请求前校验 host，拒绝 localhost、环回（127.0.0.0/8, ::1）、私有（RFC1918）与保留地址。

ai_cli_gateway-1.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+ai_cli_gateway-1.1.0.dist-info/licenses/LICENSE,sha256=K4nY9OJKVuqm1Wl9T5GEtOchVpyl3n6DItyudCvN-pI,1065
+cli_gateway/__init__.py,sha256=tCyc2ua56RF6Jvx87R7QwuAiokeuASFMb7osjYTBJ4M,23224
+cli_gateway/__main__.py,sha256=ugddHNYTOwC1xlh-aZaVZ0nuuz3aponst2ZRthvr0Lo,4284
+cli_gateway/doctor.py,sha256=VeRvXV58p_RK-ywMdA-U3z2fNbTKp8HL252ug2nHBtQ,5146
+ai_cli_gateway-1.1.0.dist-info/METADATA,sha256=Jdts14wR5srjIl147L6WsfeFFQmbwoFndF5WGlzWUsM,12324
+ai_cli_gateway-1.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ai_cli_gateway-1.1.0.dist-info/entry_points.txt,sha256=OpxFUToKh0H-JJMjZIP-hOCbr_9do6jG0u7hJtiye9U,58
+ai_cli_gateway-1.1.0.dist-info/top_level.txt,sha256=qTtaSg4B6UnLy5SbZo9uy7tdtOXHVwAKosJomH9JAqI,12
+ai_cli_gateway-1.1.0.dist-info/RECORD,,

ai_cli_gateway-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ai_cli_gateway-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cli-gateway = cli_gateway.__main__:main

ai_cli_gateway-1.1.0.dist-info/licenses/LICENSE

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

ai_cli_gateway-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cli_gateway

cli_gateway/__init__.py

@@ -0,0 +1,649 @@
+"""cli-gateway — 统一 CLI 进程调用网关：全量日志落盘 + 回放 + 结构化返回。
+
+v1.1 范围：本地 subprocess 包装（Popen 直控 + 进程组终止 + 流式 tee），不涉及任何 URL/网络请求。
+设计目标：让"AI 调 CLI 是否真跑、输出能否逐字核对"变得可观测、可审计、可回放。
+
+GatewayResult.state ∈ {completed, timed_out, not_found, spawn_error, killed}
+（spawn_error 是对 shell 惯例枚举的扩展：找到但无法启动，见下方退出码）。
+退出码语义：命令未找到=127，启动失败=126，超时=124，
+其余为命令真实退出码（POSIX 被信号杀死时为负信号值）。
+子进程 env 默认注入 PYTHONUTF8=1（调用方或父环境已显式设置时不覆盖），
+使 python 类子进程在 Windows 传统代码页（CP936 等）环境下仍输出 UTF-8。
+"""
+
+from __future__ import annotations
+
+import codecs
+import os
+import shlex
+import signal
+import subprocess
+import sys
+import threading
+import time
+import uuid
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Mapping, Sequence
+
+__version__ = "1.1.0"
+
+DEFAULT_LOG_DIR = Path(os.environ.get("CLI_GATEWAY_LOG_DIR", "~/.cli-gateway/logs")).expanduser()
+
+_PUMP_CHUNK = 65536       # 流式泵每次从管道读取的字节数（内存有界）
+_READER_JOIN_S = 10.0     # 等待 reader 线程正常 EOF 的宽限；打满视为异常出口
+_KILL_GRACE_S = 2.0       # SIGTERM 后等待进程组自行退出的宽限期（POSIX）
+_EXIT_NOT_FOUND = 127     # shell 惯例：命令未找到
+_EXIT_SPAWN_ERROR = 126   # shell 惯例：找到但无法启动/不可执行
+_EXIT_TIMEOUT = 124       # shell 惯例：超时
+_SPAWN_FAILURE_STATES = ("not_found", "spawn_error")  # 允许重试的"启动前失败"
+_SENSITIVE_MARKS = ("KEY", "TOKEN", "SECRET", "PASS", "CREDENTIAL")
+
+
+@dataclass
+class GatewayResult:
+    """一次 CLI 调用的结构化返回。
+
+    旧字段（v0.1 契约，名字与含义不变）：command/exit_code/duration_ms/log_path/
+    stdout_tail/stderr_tail/timestamp/pid/success。
+    v1.1 新增（带默认值、追加在尾部，旧调用方按位置构造不受影响）：
+    state/cwd/truncated/timed_out/env_overrides。
+    """
+
+    command: str
+    exit_code: int
+    duration_ms: int
+    log_path: str
+    stdout_tail: str
+    stderr_tail: str
+    timestamp: str
+    pid: int
+    success: bool
+    state: str = "completed"
+    cwd: str | None = None
+    truncated: bool = False
+    timed_out: bool = False
+    env_overrides: dict[str, str] = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class CliSpec:
+    """一个 CLI 在注册表中的配置（白名单语义只在 run_cli 路径成立）。
+
+    retry_on 当前仅支持 "spawn"（只重试启动前失败）；其他值保留字段但不生效。
+    """
+
+    default_timeout: float | None = None
+    capture: bool = True
+    tail: int = 2000
+    cwd: str | os.PathLike | None = None
+    env: dict[str, str] | None = None
+    retry_on: str = "spawn"
+
+
+REGISTRY: dict[str, CliSpec] = {}
+
+
+def _safe_component(cmd: Sequence[str]) -> str:
+    """取命令首段用于文件名（防路径穿越）。"""
+    head = cmd[0] if cmd else "unknown"
+    return Path(head).name.replace("/", "_").replace("\\", "_")[:40]
+
+
+def _norm_log_path(p: Path) -> str:
+    """规范化库内构造的日志路径再落盘（resolve 消除 .. 等相对成分）。
+
+    所有日志/part 路径均由本库从 log_root + _safe_component 文件名拼出，
+    此处 resolve 是纵深防御：即使上游成分异常，落盘目标也退化为规范绝对路径。
+    """
+    return str(Path(p).resolve())
+
+
+def _mask_env(env: Mapping[str, str] | None) -> dict[str, str]:
+    """只记显式传入的覆盖项；疑似敏感（KEY/TOKEN/SECRET/PASSWORD/PASS/CREDENTIAL）的值脱敏。"""
+    if not env:
+        return {}
+    out: dict[str, str] = {}
+    for k, v in env.items():
+        ku = k.upper()
+        out[k] = "***" if any(m in ku for m in _SENSITIVE_MARKS) else str(v)
+    return out
+
+
+def _copy_part(src: Path, f) -> None:
+    """把 part 文件按块搬进主日志（内存 O(块)，不整读）。
+
+    用增量解码器：多字节 UTF-8 字符跨块时由解码器内部缓冲衔接，不会产生 U+FFFD 残留。
+    """
+    if not src.is_file():
+        return
+    decoder = codecs.getincrementaldecoder("utf-8")("replace")
+    with open(src, "rb") as s:
+        while True:
+            chunk = s.read(_PUMP_CHUNK)
+            if not chunk:
+                break
+            f.write(decoder.decode(chunk))
+        f.write(decoder.decode(b"", True))  # EOF 冲刷：尾部半字符按 replace 收尾
+
+
+def _tail_from_file(path: Path, max_chars: int) -> tuple[str, bool]:
+    """从文件尾部取最多 max_chars 字符，返回 (tail, truncated)。
+
+    字节窗口 = max_chars*4（utf-8 每字符上界）+ 16 字节余量：seek 劈开多字节字符时
+    产生的替位符（至多 3 个，且必在窗口开头）保证被 [-max_chars:] 切片裁掉——
+    tail 永不残留 U+FFFD。内存 O(max_chars)，10MB 输出也不会整读进内存。
+    文件缺失/不可读按空尾部处理（pump 写盘失败时的兜底，不让 run() 崩溃）。
+    """
+    try:
+        size = path.stat().st_size
+    except OSError:
+        return ("", False)
+    if max_chars <= 0:
+        return ("", size > 0)
+    want = max_chars * 4 + 16
+    try:
+        with open(path, "rb") as f:
+            if size > want:
+                f.seek(size - want)
+            data = f.read()
+    except OSError:
+        return ("", size > 0)
+    text = data.decode("utf-8", errors="replace")
+    truncated = size > want or len(text) > max_chars
+    if len(text) > max_chars:
+        text = text[-max_chars:]
+    return text, truncated
+
+
+def _close_quietly(pipe) -> None:
+    try:
+        pipe.close()
+    except (OSError, ValueError):
+        pass
+
+
+def _close_in_background(pipe) -> None:
+    """在守护线程里关管道：Windows 上 close 可能与阻塞中的 ReadFile 互锁，
+    放到后台执行，防止 close 本身挂死主线程。"""
+    threading.Thread(target=_close_quietly, args=(pipe,), daemon=True).start()
+
+
+def _pump(pipe, out) -> None:
+    """reader 线程体：边读管道边写盘（流式 tee）。
+
+    buffering=0：每块立即落盘，主线程稍后取 tail / 组装日志时不依赖 reader 的
+    Python 层缓冲被刷出（reader 卡死场景下 partial 依然可读）。
+    out 为 None（part 打开失败，如磁盘满）时纯排水：仍消费管道，防止子进程
+    因管道满而阻塞——排水是 reader 的硬职责，落盘是尽力而为。
+    """
+    try:
+        if out is not None:
+            while True:
+                chunk = pipe.read1(_PUMP_CHUNK)  # read1：有数据即返回，不等满块
+                if not chunk:
+                    break
+                out.write(chunk)
+        else:
+            while pipe.read1(_PUMP_CHUNK):
+                pass
+    except (OSError, ValueError):
+        pass  # 管道被并发关闭等场景，尽力而为
+    finally:
+        if out is not None:
+            _close_quietly(out)
+        _close_quietly(pipe)
+
+
+def _terminate_process_group(proc: subprocess.Popen) -> None:
+    """超时终止：杀整个进程组/进程树，防孤儿孙进程。
+
+    POSIX：start_new_session 使子进程自成进程组 → killpg(SIGTERM) → 宽限后 SIGKILL。
+    Windows：CREATE_NEW_PROCESS_GROUP + taskkill /F /T（按 PID 杀整棵树）。
+    """
+    if sys.platform == "win32":
+        try:
+            subprocess.run(
+                ["taskkill", "/F", "/T", "/PID", str(proc.pid)],
+                capture_output=True,
+                check=False,  # 进程可能刚好自行退出，容忍 taskkill 失败
+            )
+        except OSError:
+            pass  # taskkill 本身缺失/不可启动：交由 finally 的 proc.wait 兜底
+        try:
+            proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            try:
+                proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                pass
+        return
+
+    try:
+        pgid = os.getpgid(proc.pid)
+    except ProcessLookupError:
+        pgid = None
+    if pgid is not None:
+        try:
+            os.killpg(pgid, signal.SIGTERM)
+        except ProcessLookupError:
+            pass
+    try:
+        proc.wait(timeout=_KILL_GRACE_S)
+        return
+    except subprocess.TimeoutExpired:
+        pass
+    if pgid is not None:
+        try:
+            os.killpg(pgid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+    try:
+        proc.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        pass
+
+
+def _guard_inputs(cmd: Sequence[str], cwd: str | os.PathLike | None) -> list[str]:
+    """入参守卫：str 拒收（防拆字符）、空列表拒收、cwd 前置校验（防误报 not found）。"""
+    if isinstance(cmd, str):
+        raise TypeError("cmd 必须是参数序列（如 ['echo', 'hi']），不要传字符串")
+    argv = list(cmd)
+    if not argv:
+        raise ValueError("cmd 不能为空列表")
+    if cwd is not None and not Path(cwd).is_dir():
+        raise FileNotFoundError(f"cwd does not exist: {cwd}")
+    return argv
+
+
+def _header_lines(
+    argv: list[str],
+    started_at: str,
+    pid: int,
+    cwd: str | os.PathLike | None,
+    env: Mapping[str, str] | None,
+    timeout: float | None,
+    capture: bool,
+) -> list[str]:
+    """日志元数据头（capture=False 时"没输出"与"没采集"可区分）。"""
+    return [
+        f"# command: {shlex.join(argv)}",
+        f"# timestamp: {started_at}",
+        f"# pid: {pid}",
+        f"# capture: {capture}",
+        f"# cwd: {Path(cwd) if cwd else ''}",
+        f"# env_overrides: {_mask_env(env)}",
+        f"# timeout: {timeout if timeout is not None else 'none'}",
+    ]
+
+
+def _write_spawn_failure_log(
+    log_path: Path,
+    header: list[str],
+    state: str,
+    exit_code: int,
+    message: str,
+    duration_ms: int,
+) -> None:
+    """启动前失败也落盘留痕（失败场景恰恰最需要审计）。newline="" 保字节保真。"""
+    try:
+        with open(_norm_log_path(log_path), "w", encoding="utf-8", errors="replace", newline="") as f:
+            for line in header:
+                f.write(line + "\n")
+            f.write("--- STDOUT ---\n--- STDERR ---\n--- END ---\n")
+            f.write(f"# exit_code: {exit_code}\n")
+            f.write(f"# duration_ms: {duration_ms}\n")
+            f.write(f"# state: {state}\n")
+            f.write(f"# error: {message}\n")
+    except OSError:
+        pass  # 日志都写不进时不再叠加异常，结果对象里仍有 log_path/信息
+
+
+def _spawn_failed_result(
+    log_path: Path,
+    argv: list[str],
+    started_at: str,
+    start: float,
+    cwd: str | os.PathLike | None,
+    env: Mapping[str, str] | None,
+    timeout: float | None,
+    capture: bool,
+    state: str,
+    exit_code: int,
+    message: str,
+) -> GatewayResult:
+    duration_ms = int((time.monotonic() - start) * 1000)
+    _write_spawn_failure_log(
+        log_path,
+        _header_lines(argv, started_at, 0, cwd, env, timeout, capture),
+        state,
+        exit_code,
+        message,
+        duration_ms,
+    )
+    return GatewayResult(
+        command=shlex.join(argv),
+        exit_code=exit_code,
+        duration_ms=duration_ms,
+        log_path=str(log_path),
+        stdout_tail=message,
+        stderr_tail="",
+        timestamp=started_at,
+        pid=0,
+        success=False,
+        state=state,
+        cwd=str(cwd) if cwd else None,
+        timed_out=False,
+        env_overrides=_mask_env(env),
+    )
+
+
+def _assemble_log(
+    log_path: Path,
+    header: list[str],
+    stdout_part: Path | None,
+    stderr_part: Path | None,
+    trailer: list[str],
+) -> None:
+    """组装最终日志：头（元数据）+ STDOUT 段 + STDERR 段 + END + 尾（结果元数据）。
+
+    newline=""：禁用 Windows 文本模式换行翻译，part 里的 CRLF 原样落盘（不膨胀成 CRCRLF）。
+    """
+    with open(log_path, "w", encoding="utf-8", errors="replace", newline="") as f:
+        for line in header:
+            f.write(line + "\n")
+        f.write("--- STDOUT ---\n")
+        if stdout_part is not None:
+            _copy_part(stdout_part, f)
+        f.write("--- STDERR ---\n")
+        if stderr_part is not None:
+            _copy_part(stderr_part, f)
+        f.write("--- END ---\n")
+        for line in trailer:
+            f.write(line + "\n")
+
+
+def _write_minimal_log(log_path: Path, header: list[str], trailer: list[str]) -> None:
+    """组装失败时的兜底最小日志：保证"有调用必有审计条目"。"""
+    try:
+        with open(_norm_log_path(log_path), "w", encoding="utf-8", errors="replace", newline="") as f:
+            for line in header:
+                f.write(line + "\n")
+            f.write("--- STDOUT ---\n--- STDERR ---\n--- END ---\n")
+            for line in trailer:
+                f.write(line + "\n")
+    except OSError:
+        pass
+
+
+def _run_once(
+    argv: list[str],
+    *,
+    cwd: str | os.PathLike | None,
+    timeout: float | None,
+    log_root: Path,
+    capture: bool,
+    tail: int,
+    env: Mapping[str, str] | None,
+) -> GatewayResult:
+    """单次尝试：spawn → 流式 tee → 终止/收尾 → 组装日志 → 结构化返回。"""
+    ts = datetime.now().strftime("%Y%m%d-%H%M%S")
+    run_id = uuid.uuid4().hex[:8]
+    log_path = log_root / f"{ts}-{_safe_component(argv)}-{run_id}.log"
+    stdout_part = log_path.with_suffix(".stdout.part")
+    stderr_part = log_path.with_suffix(".stderr.part")
+    start = time.monotonic()
+    started_at = datetime.now().isoformat(timespec="seconds")
+
+    # env：显式覆盖合并进当前环境；注入 PYTHONUTF8=1（已显式设置时不覆盖）
+    merged_env = dict(os.environ)
+    if env:
+        merged_env.update(env)
+    merged_env.setdefault("PYTHONUTF8", "1")
+
+    popen_kwargs: dict = {}
+    if sys.platform == "win32":
+        popen_kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+    else:
+        popen_kwargs["start_new_session"] = True  # 子进程自成进程组，killpg 才有靶子
+
+    try:
+        proc = subprocess.Popen(
+            argv,
+            cwd=str(cwd) if cwd else None,
+            env=merged_env,
+            stdout=subprocess.PIPE if capture else None,
+            stderr=subprocess.PIPE if capture else None,
+            **popen_kwargs,
+        )
+    except FileNotFoundError as exc:
+        # 启动前失败①：命令未找到（cwd 不存在已在守卫分流，不会到这里）
+        return _spawn_failed_result(
+            log_path, argv, started_at, start, cwd, env, timeout, capture,
+            "not_found", _EXIT_NOT_FOUND, f"command not found: {exc}",
+        )
+    except OSError as exc:
+        # 启动前失败②：找到但不可执行等（PermissionError / WinError 193 ...）
+        return _spawn_failed_result(
+            log_path, argv, started_at, start, cwd, env, timeout, capture,
+            "spawn_error", _EXIT_SPAWN_ERROR, f"spawn failed: {exc}",
+        )
+
+    # 流式 tee：两个 reader 线程边读边写盘（part 在主线程打开后移交，失败则纯排水）
+    pipes = [p for p in (proc.stdout, proc.stderr) if p is not None]
+    readers: list[threading.Thread] = []
+    if capture:
+        for pipe, part in ((proc.stdout, stdout_part), (proc.stderr, stderr_part)):
+            try:
+                out = open(_norm_log_path(part), "wb", buffering=0)
+            except OSError:
+                out = None  # 磁盘满/杀软拦截等：放弃落盘，但排水不停（防管道满死锁）
+            t = threading.Thread(target=_pump, args=(pipe, out), daemon=True)
+            t.start()
+            readers.append(t)
+
+    result: GatewayResult
+    try:
+        # 等进程结束或超时（reader 持续排水，wait 不会因管道满而死锁）
+        timed_out = False
+        try:
+            returncode = proc.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            timed_out = True
+            _terminate_process_group(proc)
+            returncode = proc.returncode
+
+        # duration 在 wait 返回即定格——reader join（孙进程继承写句柄时可能打满超时）不得计入
+        duration_ms = int((time.monotonic() - start) * 1000)
+
+        # 收 reader：正常 EOF 立即返回；打满宽限即异常出口
+        for t in readers:
+            t.join(timeout=_READER_JOIN_S)
+        readers_hung = any(t.is_alive() for t in readers)
+        if readers_hung:
+            # 孙进程继承管道写端 → 管道不 EOF。后台关管道解堵（防 close 挂死主线程）。
+            for p in pipes:
+                _close_in_background(p)
+            for t in readers:
+                t.join(timeout=5)
+
+        if timed_out:
+            state, exit_code = "timed_out", _EXIT_TIMEOUT
+        elif returncode is not None and returncode < 0:
+            state, exit_code = "killed", returncode  # POSIX：被信号杀死，exit_code 为负信号值
+        else:
+            state, exit_code = "completed", returncode if returncode is not None else -1
+
+        trailer = [
+            f"# exit_code: {exit_code}",
+            f"# duration_ms: {duration_ms}",
+            f"# state: {state}",
+        ]
+        if timed_out:
+            trailer.append(f"# error: TIMEOUT after {timeout}s")
+        if readers_hung:
+            trailer.append(
+                "# warning: reader did not finish (descendant may hold the pipe); output may be incomplete"
+            )
+
+        header = _header_lines(argv, started_at, proc.pid, cwd, env, timeout, capture)
+
+        # 组装日志：失败兜底最小日志，保证"有调用必有审计条目"
+        assembly_error: OSError | None = None
+        try:
+            _assemble_log(
+                log_path,
+                header,
+                stdout_part if capture else None,
+                stderr_part if capture else None,
+                trailer,
+            )
+        except OSError as exc:
+            assembly_error = exc
+            trailer.append(f"# warning: log assembly failed: {exc}")
+            _write_minimal_log(log_path, header, trailer)
+
+        # tail 从 part 文件取尾部（内存有界），不保留整份输出在内存
+        if capture and assembly_error is None:
+            stdout_tail, out_trunc = _tail_from_file(stdout_part, tail)
+            stderr_tail, err_trunc = _tail_from_file(stderr_part, tail)
+            truncated = out_trunc or err_trunc
+        else:
+            stdout_tail = stderr_tail = ""
+            truncated = assembly_error is not None  # 组装失败=输出不完整
+        if readers_hung:
+            truncated = True  # reader 未正常收尾，输出可能撕裂，显式告警
+
+        result = GatewayResult(
+            command=shlex.join(argv),
+            exit_code=exit_code,
+            duration_ms=duration_ms,
+            log_path=str(log_path),
+            stdout_tail=stdout_tail,
+            stderr_tail=stderr_tail,
+            timestamp=started_at,
+            pid=proc.pid,
+            success=(not timed_out) and exit_code == 0,
+            state=state,
+            cwd=str(cwd) if cwd else None,
+            truncated=truncated,
+            timed_out=timed_out,
+            env_overrides=_mask_env(env),
+        )
+    finally:
+        # 兜底：杀活进程、关管道、清 part——异常/半途退出也不泄漏资源
+        try:
+            if proc.poll() is None:
+                _terminate_process_group(proc)
+        except Exception:
+            pass
+        for p in pipes:
+            _close_quietly(p)
+        for part in (stdout_part, stderr_part):
+            try:
+                part.unlink(missing_ok=True)
+            except OSError:
+                pass  # reader 仍持句柄时 unlink 失败（WinError 32），尽力清理即可
+
+    return result
+
+
+def run(
+    cmd: Sequence[str],
+    *,
+    cwd: str | os.PathLike | None = None,
+    timeout: float | None = None,
+    log_dir: str | os.PathLike | None = None,
+    capture: bool = True,
+    tail: int = 2000,
+    env: Mapping[str, str] | None = None,
+    retry_count: int = 0,
+) -> GatewayResult:
+    """执行一条 CLI 命令，全量落盘并返回结构化结果。
+
+    - stdout/stderr 全量流式写入 log 文件（可回放、可审计，内存有界）
+    - 退出码语义：未找到=127、启动失败=126、超时=124
+      state ∈ {completed, timed_out, not_found, spawn_error, killed}
+    - env 只作覆盖合并进当前环境（另注入 PYTHONUTF8=1，已显式设置时不覆盖），
+      审计仅记录显式传入项（敏感值脱敏）
+    - retry_count 只对"启动前失败"（not_found / spawn_error）重试；
+      超时/非零退出绝不自动重试；每次尝试独立日志
+    - 纯本地 subprocess，不发起任何网络请求
+    """
+    argv = _guard_inputs(cmd, cwd)
+
+    log_root = Path(log_dir) if log_dir else DEFAULT_LOG_DIR
+    log_root.mkdir(parents=True, exist_ok=True)  # 目录不可写 → fail-fast 抛 OSError
+
+    attempts = max(0, int(retry_count)) + 1
+    result: GatewayResult | None = None
+    for attempt in range(attempts):
+        result = _run_once(
+            argv,
+            cwd=cwd,
+            timeout=timeout,
+            log_root=log_root,
+            capture=capture,
+            tail=tail,
+            env=env,
+        )
+        if result.state not in _SPAWN_FAILURE_STATES or attempt == attempts - 1:
+            break  # 只有启动前失败才重试
+    assert result is not None
+    return result
+
+
+def run_cli(
+    name: str,
+    *args: str,
+    timeout: float | None = None,
+    log_dir: str | os.PathLike | None = None,
+    retry_count: int = 0,
+) -> GatewayResult:
+    """按注册表白名单调用 CLI：name 必须已注册，配置取自 CliSpec（显式参数优先）。"""
+    spec = REGISTRY.get(name)
+    if spec is None:
+        raise KeyError(f"CLI not registered: {name!r} (known: {sorted(REGISTRY)})")
+    return run(
+        [name, *args],
+        cwd=spec.cwd,
+        timeout=spec.default_timeout if timeout is None else timeout,
+        log_dir=log_dir,
+        capture=spec.capture,
+        tail=spec.tail,
+        env=spec.env,
+        retry_count=retry_count,
+    )
+
+
+def replay(log_path: str | os.PathLike) -> str:
+    """回放一次已记录的 CLI 调用（打印完整日志）。"""
+    p = Path(log_path)
+    if not p.is_file():
+        raise FileNotFoundError(f"log not found: {p}")
+    return p.read_text(encoding="utf-8", errors="replace")
+
+
+def list_logs(log_dir: str | os.PathLike | None = None) -> list[Path]:
+    """列出全部调用日志（按时间倒序）。"""
+    root = Path(log_dir) if log_dir else DEFAULT_LOG_DIR
+    if not root.is_dir():
+        return []
+    return sorted(root.glob("*.log"), key=lambda p: p.stat().st_mtime, reverse=True)
+
+
+__all__ = [
+    "GatewayResult",
+    "CliSpec",
+    "REGISTRY",
+    "run",
+    "run_cli",
+    "replay",
+    "list_logs",
+    "DEFAULT_LOG_DIR",
+]

cli_gateway/__main__.py

@@ -0,0 +1,97 @@
+"""cli-gateway 命令行入口：replay / logs / run。
+
+用法：
+  cli-gateway run -- <command...>      执行并落盘
+  cli-gateway replay <log-path>        回放一次调用
+  cli-gateway logs [--dir DIR]         列出日志
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import platform
+import sys
+
+from . import DEFAULT_LOG_DIR, list_logs, replay, run
+from .doctor import doctor
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="cli-gateway", description="统一 CLI 进程调用网关")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_run = sub.add_parser("run", help="执行一条命令并全量落盘")
+    # 注意：不能叫 "cmd"——会与 subparsers 的 dest 同名冲突，覆盖子命令名导致 run 分支永不执行
+    p_run.add_argument("payload", nargs=argparse.REMAINDER, help="要执行的命令（-- 后的全部参数）")
+    p_run.add_argument("--timeout", type=float, default=None, help="超时秒数")
+    p_run.add_argument("--dir", default=None, help="日志目录")
+
+    p_replay = sub.add_parser("replay", help="回放一次已记录的调用")
+    p_replay.add_argument("log_path", help="日志文件路径")
+
+    p_logs = sub.add_parser("logs", help="列出全部调用日志")
+    p_logs.add_argument("--dir", default=None, help="日志目录")
+
+    p_doctor = sub.add_parser("doctor", help="体检本机编码 CLI：安装形态/版本/调用配方")
+    p_doctor.add_argument("--only", nargs="+", metavar="CMD", help="只查指定命令（默认内置 9 个编码 CLI）")
+    p_doctor.add_argument("--json", action="store_true", help="结构化 JSON 输出")
+    p_doctor.add_argument("--no-probe", action="store_true", help="静态快查：只看 PATH 形态，不实跑版本探测")
+    p_doctor.add_argument("--timeout", type=float, default=20.0, help="单命令探测超时秒数")
+
+    args = parser.parse_args(argv)
+
+    # 打印子进程 tail 前兜底：裸 CP936 控制台编不出 UTF-8 字符时 replace，
+    # 防 UnicodeEncodeError 直接崩掉 CLI（不改变 stdout 的编码，只放宽错误策略）
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            try:
+                reconfigure(errors="replace")
+            except (OSError, ValueError):
+                pass
+
+    if args.cmd == "run":
+        # 切片写法：payload 为空列表时 args.payload[0] 会 IndexError，parser.error 永不可达
+        cmd = args.payload[1:] if args.payload[:1] == ["--"] else args.payload
+        if not cmd:
+            parser.error("run 需要一个命令")
+        res = run(cmd, timeout=args.timeout, log_dir=args.dir)
+        print(f"exit={res.exit_code} duration={res.duration_ms}ms log={res.log_path}")
+        if res.stdout_tail:
+            print(res.stdout_tail, end="")
+        if res.stderr_tail:
+            print(res.stderr_tail, end="", file=sys.stderr)
+        return 0 if res.success else 1
+
+    if args.cmd == "replay":
+        print(replay(args.log_path))
+        return 0
+
+    if args.cmd == "logs":
+        for p in list_logs(args.dir):
+            print(p)
+        return 0
+
+    if args.cmd == "doctor":
+        rows = doctor(commands=args.only, probe=not args.no_probe, timeout=args.timeout)
+        if args.json:
+            print(json.dumps(rows, ensure_ascii=False, indent=2))
+        else:
+            print(f"cli-gateway doctor  {platform.platform()}  python {sys.version.split()[0]}")
+            for r in rows:
+                mark = "✅" if r["ok"] else "❌"
+                ver = r["version"] or "-"
+                dur = f"  {r['duration_ms']}ms" if r["duration_ms"] is not None else ""
+                print(f"  {mark} {r['name']:<10} {r['form']}  |  {ver}{dur}")
+                if r["form"] == "npm shim（需 cmd /c 包装）":
+                    print(f"      └─ 网关调用配方：cmd /c {r['cmd']} ...（Git Bash 写 //c）")
+            ok_n = sum(1 for r in rows if r["ok"])
+            print(f"\n{ok_n}/{len(rows)} 可用；探测日志已落盘 {DEFAULT_LOG_DIR}")
+        return 0 if all(r["ok"] for r in rows) else 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cli_gateway/doctor.py

@@ -0,0 +1,133 @@
+"""cli-gateway doctor：本机编码 CLI 环境体检。
+
+对已知 CLI 清单逐个探测：能否找到、以什么形态被网关调用（原生 exe 直调 /
+npm shim 需 cmd /c 包装 / 未找到）、版本是什么——真机验证矩阵的产品化复现。
+
+形态判定以网关真实调用结果为准（先直调，Windows 下 not_found 再试 cmd /c 包装），
+不做静态猜测；`--no-probe` 才退化为按 CreateProcess 语义的 PATH 静态快查。
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from typing import Any
+
+from . import run
+
+# 内置体检清单：name 是展示名，cmd 是实际命令，probe 是版本探测参数
+DOCTOR_SPECS: list[dict[str, Any]] = [
+    {"name": "claude", "cmd": "claude", "probe": ["--version"]},
+    {"name": "codex", "cmd": "codex", "probe": ["--version"]},
+    {"name": "kilo", "cmd": "kilo", "probe": ["--version"]},
+    {"name": "mcode", "cmd": "mcode", "probe": ["--version"]},
+    {"name": "goose", "cmd": "goose", "probe": ["--version"]},
+    {"name": "opencode", "cmd": "opencode", "probe": ["--version"]},
+    {"name": "qoder", "cmd": "qoderclicn", "probe": ["--version"]},
+    {"name": "crush", "cmd": "crush", "probe": ["--version"]},
+    {"name": "hermes", "cmd": "hermes", "probe": ["--version"]},
+]
+
+FORM_MISSING = "未找到"
+FORM_NATIVE = "原生 exe（直调）"
+FORM_DIRECT_OK = "直调可用（自动命中同名 exe）"
+FORM_SHIM = "npm shim（需 cmd /c 包装）"
+FORM_INSTALLED = "已安装（直调）"
+
+
+def _find_exe(cmd: str) -> str | None:
+    """按 CreateProcess 语义搜 PATH：Windows 找 <cmd>.exe（shim 不算数）；含路径分隔符按原样判定。"""
+    if os.sep in cmd or (os.altsep and os.altsep in cmd):
+        return cmd if os.path.isfile(cmd) else None
+    if os.name != "nt":
+        return shutil.which(cmd)
+    for d in os.environ.get("PATH", "").split(os.pathsep):
+        if not d:
+            continue
+        candidate = os.path.join(d, cmd + ".exe")
+        if os.path.isfile(candidate):
+            return candidate
+    return None
+
+
+def _first_line(res: Any) -> str:
+    """版本行：stdout 首行优先，stderr 兜底（部分 CLI 把版本打到 stderr）。"""
+    src = (res.stdout_tail or "").strip().splitlines() or (res.stderr_tail or "").strip().splitlines()
+    return src[0].strip()[:80] if src else ""
+
+
+def _probe_one(cmd: str, probe: list[str], timeout: float) -> dict[str, Any]:
+    """实跑探测：网关直调；Windows 下确认 shim 文件存在才用 cmd /c 复核（cmd 自身对
+    不存在命令也能启动且退出非零，不能拿它判定形态）。"""
+    res = run([cmd] + probe, timeout=timeout)
+    if res.state == "not_found" and os.name == "nt":
+        shim = shutil.which(cmd)
+        if shim and shim.lower().endswith((".cmd", ".bat")):
+            res = run(["cmd", "/c", cmd] + probe, timeout=timeout)
+            return {
+                "cmd": cmd,
+                "form": FORM_SHIM,
+                "ok": res.exit_code == 0 and res.state == "completed",
+                "exit_code": res.exit_code,
+                "state": res.state,
+                "version": _first_line(res),
+                "duration_ms": res.duration_ms,
+                "log_path": res.log_path,
+                "path": shim,
+            }
+    if res.state in ("not_found", "spawn_error"):
+        form = FORM_MISSING
+    else:
+        form = FORM_NATIVE if _find_exe(cmd) else FORM_DIRECT_OK
+    return {
+        "cmd": cmd,
+        "form": form,
+        "ok": res.exit_code == 0 and res.state == "completed",
+        "exit_code": res.exit_code,
+        "state": res.state,
+        "version": _first_line(res),
+        "duration_ms": res.duration_ms,
+        "log_path": res.log_path,
+        "path": shutil.which(cmd) or "",
+    }
+
+
+def _static_one(cmd: str) -> dict[str, Any]:
+    """静态快查：只按 PATH 判形态，不实跑（--no-probe；shim 判定对同名 exe 共存场景可能不准）。"""
+    exe_hit = _find_exe(cmd)
+    which_hit = shutil.which(cmd)
+    if exe_hit:
+        form, ok = FORM_NATIVE, True
+    elif os.name == "nt" and which_hit:
+        form, ok = FORM_SHIM, True
+    elif which_hit:
+        form, ok = FORM_INSTALLED, True
+    else:
+        form, ok = FORM_MISSING, False
+    return {
+        "cmd": cmd,
+        "form": form,
+        "ok": ok,
+        "exit_code": None,
+        "state": "static",
+        "version": "",
+        "duration_ms": None,
+        "log_path": "",
+        "path": which_hit or "",
+    }
+
+
+def doctor(commands: list[str] | None = None, probe: bool = True, timeout: float = 20.0) -> list[dict[str, Any]]:
+    """体检本机 CLI，返回结构化行。commands 为空则用内置 9 个编码 CLI 清单。"""
+    if commands:
+        specs: list[dict[str, Any]] = [{"name": c, "cmd": c, "probe": ["--version"]} for c in commands]
+    else:
+        specs = DOCTOR_SPECS
+    rows = []
+    for spec in specs:
+        if probe:
+            row = _probe_one(spec["cmd"], list(spec["probe"]), timeout)
+        else:
+            row = _static_one(spec["cmd"])
+        rows.append({"name": spec["name"], **row})
+    return rows