让 LLM Agent 像调函数一样驱动一台 Windows 主机：跑
cmd.exe/ PowerShell、 推拉文件、调用厂商专用的 Windows 工具，统一返回{ok, data, error, artifacts}。
English · 中文
windows-llm-bridge（简称 wlb）是 android-llm-bridge 的姊妹项目。
alb 把"在一台真实安卓设备上调试"这件事变成 LLM Agent 能直接调用的工具集。 wlb 把"在一台 Windows 主机上跑命令 / 推拉文件 / 驱动厂商工具"这件事变成同样的工具集。
典型工作流：
- 在 Linux 上交叉编译固件，输出到 Samba/SMB 共享目录
- LLM Agent 通过 wlb 调用 Windows 端的厂商烧录工具
- Agent 读回结构化进度 + 最终状态，自己决定下一步重试 / 改参数 / 报错给人
这个工作流以前是：人来回切窗口；现在是：Agent 一气呵成。
很多嵌入式 / 驱动 / 固件场景下：
- 重活在 Linux：编译、CI、测试农场，LLM Agent 用着很顺手
- 关键工具在 Windows：厂商烧录器、JTAG GUI、产测夹具、签名打包器，只有 Windows 二进制
夹在中间最难受的不是切窗口，而是 Agent 看不到 Windows 那边的状态——一旦工具跑在另一台机器上， Agent 的反馈闭环就断了。wlb 用结构化的工具桥把 Windows 接回 Agent 的视野。
直接对比：
| 维度 | 裸 SSH / RDP | wlb |
|---|---|---|
| 输出格式 | 自由文本 | {ok, data, error, artifacts, timing_ms} 结构化 |
| 错误信号 | 看 exit code 自己猜 | error.code + error.suggestion 可直接喂回 Agent |
| 危险动作 | 谁跑谁负责（format c: 一路畅通） |
默认黑名单拒绝（format / Format-Volume / bcdedit / Remove-Item -Recurse -Force C:\） |
| MCP 集成 | 写胶水脚本 | 一行 JSON 注册到 Claude Code / Cursor / Codex |
| 工具调用 | 拼字符串 | 声明式 TOML 配置 + 进度正则 + 成功/失败正则（M2） |
| 文件传输 | scp / 网盘 |
SFTP 或 SMB 路径自动翻译（M2） |
本仓库现在处于 M1：SSH 主通路真实现已完成（asyncssh，cmd + powershell 都能跑，PowerShell 走
-EncodedCommand避免引号噩梦），M2 是 filesync / tool runner / HTTP 备用通路。详见PLAN.md。
| 名称 | 实现位置 | 状态 | 用途 |
|---|---|---|---|
| ssh | wlb.transport.ssh |
beta | 主通路：Windows OpenSSH Server，asyncssh，key-auth |
| local | wlb.transport.local |
beta | 本地测试用 loopback，单元测试基础 |
| http | wlb.transport.http |
beta | 备用通路：Windows 端跑 wlb-agent 微服务（FastAPI），控制端 httpx + Bearer token（save-to-file）+ 可选 TLS |
| hybrid | wlb.transport.hybrid |
planned | M2 智能路由：file → SFTP，cmd → SSH，离线 → HTTP |
| 名称 | CLI | MCP tool | 状态 | 说明 |
|---|---|---|---|---|
| status | wlb status / describe |
wlb_status / wlb_describe |
beta | 主机自检、环境信息、传输健康检查 |
| cmd | wlb cmd <args> |
wlb_cmd |
beta | cmd.exe /c 执行 |
| powershell | wlb powershell <args> |
wlb_powershell |
beta | PowerShell 5 / 7+ 自动探测，结构化返回 |
| filesync | `wlb fs push | pull/maps` |
wlb_push / wlb_pull |
beta |
| tool | wlb tool list / show / run [--stream] |
wlb_tool_list / wlb_tool_show / wlb_tool_run |
beta | 用户 TOML 声明工具（command_template + 进度/成功/失败 regex + workdir）；--stream 实时输出 + 进度匹配（M3.1）；arg 值禁 shell meta；全输出落到 workspace/hosts/.../tools/.../.log |
| web | wlb web / wlb-api |
— | beta | 本地仪表板（FastAPI + WebSocket），dashboard + 实时工具运行；默认 127.0.0.1，M3.3 无 auth（要外网暴露请加反代+auth） |
| pty | (browser) /pty.html | — | beta | 交互式 PTY 终端（xterm.js + WebSocket）；ssh = asyncssh PTY channel；local = Unix pty.openpty 或 Windows ConPTY (pywinpty, uv sync --extra windows-local-pty)；http = wlb-agent WS /v1/pty（M3.6）；可选 asciinema .cast 录制：WLB_PTY_RECORD=1 或 [pty] record=true（M3.7）；/casts.html 浏览/回放（M3.8） |
| skill | wlb skill list / show |
wlb_skill_list / wlb_skill_get + Resource wlb-skill://<name> |
beta | 每个声明 tool 自动生成 Markdown skill pack 给 LLM client preload；可选 workspace/wlb-skills/<name>.md 作者扩展；HTTP /api/skills + /api/skills/<name>（M3.11） |
# 1. 安装（用户态，零 root，零系统 Python 污染）
git clone https://github.com/TbusOS/windows-llm-bridge.git
cd windows-llm-bridge
./scripts/install.sh
# 2. 在 Windows 端启用 OpenSSH Server（详见 docs/windows-side-setup.md）
# 把 scripts/windows-setup/enable-openssh.ps1 拷过去，以管理员跑一次
# 3. 配置 SSH 目标（交互式，写到 workspace/profiles/default.toml）
uv run wlb setup ssh
# 多主机：uv run wlb setup ssh --profile homelab
# 脚本化：uv run wlb setup ssh --non-interactive --host ... --user ... --yes
# 4. 自检
uv run wlb describe
uv run wlb status
uv run wlb setup show # 看合并后的 env > profile > default
# 5. 跑命令
uv run wlb cmd "ver"
uv run wlb powershell "Get-ComputerInfo | Select-Object OsName, OsVersion"
# 切 profile: uv run wlb --profile homelab cmd "ver"把 wlb 接到 Claude Code（或 Cursor / Codex）作为 MCP server：
{
"mcpServers": {
"wlb": {
"command": "uv",
"args": ["run", "--project", "/abs/path/to/windows-llm-bridge", "wlb-mcp"]
}
}
}完整步骤见 docs/quickstart.md 和
docs/mcp-integration.md。
windows-llm-bridge/
├── CLAUDE.md # AI agent 规则（敏感词、风格、流程）
├── REQUIREMENTS.md # 需求文档：做什么、为谁、反目标
├── PLAN.md # 计划文档：M0/M1/M2/M3 拆到文件级
├── README.md / README.en.md # 介绍
├── pyproject.toml # PEP 621 manifest（hatchling + uv）
├── src/wlb/
│ ├── infra/ # Result/Errors/Permissions/Registry/Workspace
│ ├── transport/ # base ABC + ssh / local / http / hybrid
│ ├── capabilities/ # cmd / powershell / status / filesync / tool
│ ├── mcp/ # FastMCP server + per-capability tool 注册
│ └── cli/ # typer 入口 + 5 个子命令
├── scripts/
│ ├── install.sh / uninstall.sh
│ ├── check_sensitive_words.sh
│ └── windows-setup/enable-openssh.ps1
├── tests/ # pytest，asyncio_mode=auto
├── docs/ # architecture / quickstart / setup / mcp
└── workspace/ # 运行时产物（不入仓）
- 结构化优先：所有返回
{ok, data, error, artifacts, timing_ms}， 错误必有code+suggestion - 权限默认拒：危险命令模式黑名单（
format/Format-Volume/bcdedit /delete/Remove-Item -Recurse -Force C:\）默认拒绝， 必须显式--allow-dangerous - 零系统污染：
install.sh不走 sudo、不动系统 Python、不写/etc - MCP 一等公民：每个能力同时有 CLI 子命令和 MCP tool，行为一致
- 品牌中立：仓库内不出现任何具体厂商工具名 / SoC 型号 / 内部主机名
| 文件 | 内容 |
|---|---|
| REQUIREMENTS.md | 需求 / 反目标 / 成功标准 |
| PLAN.md | 里程碑拆分（M0/M1/M2/M3） |
| docs/architecture.md | 分层架构 + Result 流转 + 权限模型 |
| docs/quickstart.md | 8 步入门 |
| docs/windows-side-setup.md | Windows 端配 OpenSSH Server |
| docs/mcp-integration.md | MCP 注册到 Claude Code / Cursor |
| docs/walkthrough.md | 真 Windows 端到端 walkthrough（脚本 + checklist 在 walkthrough/） |
| docs/skills.md | Skill packs — 每 tool LLM 可 preload 的 Markdown 引导（M3.11） |
| CLAUDE.md | AI agent 工作规则 |
PR 之前请通读 CLAUDE.md 和 PLAN.md。
特别注意：
- commit 之前
./scripts/check_sensitive_words.sh必须 0 命中 - 新能力同时要补：capability module + MCP tool + CLI 子命令 + tests + 注册表条目 + README 矩阵
- 不接受
Co-Authored-By: Claude ...之类的 AI 共作署名
MIT — 见 LICENSE。