From 402f7a3446714a5eac4022a4613ca93d08f84a1e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?AI=E4=B8=8D=E6=AD=A2=E8=AF=AD?= <12096460+jnMetaCode@users.noreply.github.com> Date: Fri, 7 Aug 2026 17:25:04 +0800 Subject: [PATCH] =?UTF-8?q?docs(copilot):=20=E8=A1=A5=20Windows=20powershe?= =?UTF-8?q?ll=20=E5=B7=A5=E5=85=B7=E9=9D=A2=EF=BC=8C=E4=BF=AE=E6=AD=A3=20b?= =?UTF-8?q?ash=20=E5=94=AF=E4=B8=80=E5=81=87=E8=AE=BE=20(#93)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit copilot-tools.md 原先只记了 bash + async:true + read_bash/stop_bash/ write_bash/list_bash 一套，并把上游的 Bash 工具名直接映射到 bash。 但 Windows 上实测（Copilot CLI 1.0.69-1 / Node v24.17.0）注册的是 powershell + detach 一套，完全没有 bash/async 家族 —— agent 照着不存在 的工具名调用会找不到工具然后即兴发挥。 - 异步 Shell 会话拆成 Unix/macOS（bash）与 Windows（powershell）两张表， 并明确「两套不会同时出现，动手前先确认本 build 注册的是哪套」 - 标注 powershell 一套没有 write_* 等价物（无法向会话发送输入） - 新增「Windows 上的两个坑」：.sh 需显式走 Git Bash；stop_powershell 停不掉 detach:true 的进程，需按真实 Windows PID（非 MSYS PID）Stop-Process - Bash 映射行补平台提示，指向该节 证据与环境均来自 issue #93 报告人的实测。 --- .../references/copilot-tools.md | 34 +++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-) diff --git a/skills/using-superpowers/references/copilot-tools.md b/skills/using-superpowers/references/copilot-tools.md index 44afc70..66cf61e 100644 --- a/skills/using-superpowers/references/copilot-tools.md +++ b/skills/using-superpowers/references/copilot-tools.md @@ -7,7 +7,7 @@ | `Read`（读取文件） | `view` | | `Write`（创建文件） | `create` | | `Edit`（编辑文件） | `edit` | -| `Bash`（运行命令） | `bash` | +| `Bash`（运行命令） | `bash`（Windows 上常为 `powershell`，见[异步 Shell 会话](#异步-shell-会话)） | | `Grep`（搜索文件内容） | `grep` | | `Glob`（按名称搜索文件） | `glob` | | `Skill` 工具（调用技能） | `skill` | @@ -31,7 +31,11 @@ Copilot CLI 的 `task` 工具接受 `agent_type` 参数： ## 异步 Shell 会话 -Copilot CLI 支持持久化的异步 shell 会话，这在 Claude Code 中没有直接等价物： +Copilot CLI 支持持久化的异步 shell 会话，这在 Claude Code 中没有直接等价物。 + +> ⚠️ **shell 工具面随平台和版本而异，下面两套工具名不会同时出现。** 动手之前先确认你这个 build 实际注册的是哪一套 —— 照着不存在的工具名调用，agent 会找不到工具然后即兴发挥。Windows 上常见的是 powershell 那一套（实测 Copilot CLI 1.0.69-1 / Windows 只有 powershell，没有任何 `bash` / `async` 家族工具）。 + +**Unix / macOS —— bash 一套：** | 工具 | 用途 | |------|---------| @@ -41,6 +45,32 @@ Copilot CLI 支持持久化的异步 shell 会话，这在 Claude Code 中没有 | `stop_bash` | 终止异步会话 | | `list_bash` | 列出所有活跃的 shell 会话 | +**Windows —— powershell 一套：** + +| 工具 | 用途 | +|------|---------| +| `powershell` 配合 `detach: true` | 在后台启动长时间运行的命令（参数名是 `detach`，**不是** `async`） | +| `read_powershell` | 读取会话的输出 | +| `stop_powershell` | 终止会话 | +| `list_powershell` | 列出所有活跃的 shell 会话 | +| （无 `write_powershell`） | 这一套**没有**向运行中会话发送输入的工具 | + +### Windows 上的两个坑 + +**1. `.sh` 脚本不能裸跑。** powershell 下直接执行 `scripts/start-server.sh` 会报 `The term 'scripts/start-server.sh' is not recognized...`，必须显式走 Git Bash： + +```powershell +& "C:\Program Files\Git\bin\bash.exe" scripts/start-server.sh +``` + +**2. `stop_powershell` 停不掉 `detach: true` 启动的进程。** detached 进程要按 PID 停： + +```powershell +Stop-Process -Id +``` + +所以**不要把 `stop_*` 当作 detached 常驻进程的唯一清理路径** —— 必须先拿到真实的 Windows PID（不是 MSYS PID），再 `Stop-Process`。涉及长驻 server 的 skill（如 brainstorming 的视觉伴侣）在 Windows 上尤其要注意这一点。 + ## 额外的 Copilot CLI 工具 | 工具 | 用途 |