windows-shell

Windows Shell 技能

此技能提供处理 Windows 文件系统路径和命令的指南，帮助避免在 Windows 上使用 Claude Code 时遇到常见问题。

核心原则

路径格式

在技能和配置中：

• 始终使用正斜杠（Unix 风格）：scripts/helper.py
• 技能中切勿使用反斜杠：scripts\helper.py
• 这样可以确保跨平台兼容性

在 Bash 命令中：

• 路径包含空格或反斜杠时，始终加引号：cd "C:\KolyaRepositories\project"
• 不加引号时，反斜杠会丢失：cd C:\KolyaRepositories\project
• 结果：/usr/bin/bash: line 1: cd: C:KolyaRepositoriesproject: No such file or directory

Shell 命令模式

推荐模式：

# Quoted paths work reliably
cd "C:\KolyaRepositories\repo" && git status

# Multiple commands in sequence
cd "C:\KolyaRepositories\repo" && git rev-parse --abbrev-ref HEAD && git status --short

# Direct git commands without piping
git status --short

不推荐模式：

# Unquoted paths fail
cd C:\KolyaRepositories\repo && git status

# Piping to findstr after cd fails
cd "C:\KolyaRepositories\repo" && git status --short | findstr /R "."
# Error: FINDSTR: Cannot open repo

# PowerShell via -Command loses cd context
cd "C:\KolyaRepositories\repo" && powershell -Command "git status --short | Where-Object { $_ }"
# Error: The term 'C:\KolyaRepositories\repo' is not recognized

常见问题

1. 更改目录后使用 Findstr

问题： 在 cd 后通过管道调用 findstr 时，findstr 会将目录名识别为文件参数。

# Fails
cd "C:\KolyaRepositories\calc" && git status --short | findstr /R "."
# Error: FINDSTR: Cannot open calc

解决方案： 直接使用命令，避免不必要的管道。

# Works
cd "C:\KolyaRepositories\calc" && git status --short

2. PowerShell 上下文丢失

问题： 在 cd 后使用 powershell -Command 会导致 Shell 上下文被错误解析。

# Fails
cd "C:\KolyaRepositories\calc" && powershell -Command "git status --short | Where-Object { $_ }"
# Error: The term 'C:\KolyaRepositories\calc' is not recognized

解决方案： 从一开始就直接使用 PowerShell，或者避免在 Bash cd 后通过管道调用 PowerShell。

# Works - all in PowerShell
powershell -Command "cd 'C:\KolyaRepositories\calc'; git status --short"

# Works - no PowerShell piping
cd "C:\KolyaRepositories\calc" && git status --short

3. Bash 中未加引号的路径

问题： Bash 会从未加引号的 Windows 路径中移除反斜杠。

# Fails
cd C:\KolyaRepositories\calc
# Error: cd: C:KolyaRepositoriescalc: No such file or directory

解决方案： 包含反斜杠的路径始终要加引号。

# Works
cd "C:\KolyaRepositories\calc"

4. 将输出重定向到空设备

背景： Claude Code 在 Windows 上使用 Git Bash，后者提供类 Unix 路径。

在 Git Bash（Claude Code 默认使用）中：

# CORRECT - Git Bash provides /dev/null
command > /dev/null 2>&1

# WRONG - creates a literal file named "nul" in working directory!
command >nul 2>&1

警告： 在 Git Bash 中使用 >nul 会创建一个文件，污染 git status 的结果。在 Git Bash 中始终使用 /dev/null。

在 PowerShell 中：

command 2>$null
command | Out-Null

5. PowerShell 特殊字符转义

问题 A——取反运算符： 通过 Bash 传递 PowerShell 命令时，感叹号会被转义为反斜杠加感叹号。

# Fails - ! becomes \!
powershell -Command "if (!(Test-Path 'file.txt')) { Write-Output 'missing' }"
# Error: \! is not recognized

解决方案： 使用 -not 代替感叹号表示取反。

# Works
powershell -Command "if (-not (Test-Path 'file.txt')) { Write-Output 'missing' }"

问题 B——变量插值： 通过 Bash 传递 PowerShell 命令时，$variable 语法会被移除。

# Fails - $pdf and $sizeKB are empty
powershell -Command "$pdf = Get-Item 'file.pdf'; $sizeKB = [math]::Round($pdf.Length / 1KB, 1); Write-Output $sizeKB"
# Output: (empty or partial)

解决方案： 对于复杂操作，使用 .ps1 脚本文件；或者在简单命令之间通过管道传递输出。

# Works - use script file
powershell -ExecutionPolicy Bypass -File "script.ps1" -Path "file.pdf"

# Works - simple piped commands
powershell -Command "Get-Item 'file.pdf' | Select-Object Length"

内联 PowerShell 总结：

• 使用 -not 代替感叹号
• 对于包含变量的复杂逻辑，使用脚本文件
• 保持内联命令简单（单个操作、通过管道传递输出）

多仓库操作的最佳实践

遍历多个仓库时（例如，检查状态）：

模式 1——使用 && 执行顺序命令：

cd "C:\KolyaRepositories\repo1" && git status --short
cd "C:\KolyaRepositories\repo2" && git status --short

模式 2——使用自包含命令：

git -C "C:\KolyaRepositories\repo1" status --short
git -C "C:\KolyaRepositories\repo2" status --short

模式 3——并行调用工具： 对于彼此独立的操作，在同一条消息中多次调用 Bash 工具：

• Bash 工具 1：cd "C:\repo1" && git status
• Bash 工具 2：cd "C:\repo2" && git status
• Bash 工具 3：cd "C:\repo3" && git status

Windows 上的 PowerShell 与 Bash

何时使用 PowerShell

以下情况使用 PowerShell：

• Windows 专属操作（注册表、服务等）
• 使用 Where-Object、Select-Object 进行复杂筛选
• 处理 .NET 对象
• Windows 系统管理任务

# PowerShell example
powershell -Command "Get-ChildItem -Path 'C:\KolyaRepositories' -Directory | Select-Object Name"

何时使用 Bash（Git Bash/WSL）

以下情况使用 Bash：

• Git 操作
• 标准 Unix 工具（grep、sed、awk）
• 跨平台脚本
• 大多数开发工具（npm、docker 等）

# Bash example
cd "C:\KolyaRepositories\repo" && git status --short

优先于 Bash 使用的工具

对于文件操作，请使用专用的 Claude Code 工具，而不是 Bash 命令：

操作	使用工具	不要使用 Bash
读取文件	Read 工具	cat、head、tail
搜索文件	Glob 工具	find、ls
搜索内容	Grep 工具	grep、rg
编辑文件	Edit 工具	sed、awk
写入文件	Write 工具	echo >、cat <<EOF

Bash 仅用于实际的终端操作：git、npm、docker、构建命令等。

摘要检查清单

运行 Windows 文件系统命令前：

• 用引号括起含反斜杠的路径："C:\Path\To\Dir"
• 在 Git Bash 中使用 /dev/null 重定向输出（不要使用会创建文件的 >nul）
• cd 后不要添加不必要的管道（尤其是 findstr、Where-Object）
• 文件操作使用专用工具（Read、Glob、Grep），而不是 bash
• 多个独立操作使用并行工具调用
• Skills 使用正斜杠：scripts/helper.py
• Windows 专属任务使用 PowerShell，类 Unix 操作使用 Bash
• PowerShell 中使用 -not 代替感叹号进行否定
• 复杂的 PowerShell 逻辑写入 .ps1 文件，而不是内联命令

实际错误示例

常见错误模式：

1. cd 后使用 findstr → FINDSTR: Cannot open [dirname]
2. PowerShell 中 cd 后使用管道 → The term 'C:...' is not recognized
3. 路径未加引号 → cd: C:KolyaRepositories...（反斜杠被去掉）
4. 在 Git Bash 中使用 >nul → 创建名为 "nul" 的实际文件，污染 git status
5. 在 Bash 中通过 PowerShell 使用感叹号 → 不识别反斜杠转义的感叹号
6. 在 PowerShell 中内联使用 $variable → 变量为空或被去掉

解决方法： 按照此技能中的模式即可解决所有问题：

• 给路径加引号：cd "C:\KolyaRepositories\repo"
• 避免在 cd 后使用管道：git status --short（不要加 | findstr）
• 在 Git Bash 中使用 /dev/null：command > /dev/null 2>&1（不要使用 >nul）
• 使用 -not 代替感叹号进行否定
• 复杂的 PowerShell 逻辑使用 .ps1 脚本文件