pwsh-guide

生成项目级 Agent Skill：跨平台探测当前环境（Windows PowerShell / macOS / Linux shell）与本项目上下文，产出可靠的命令使用指南（SKILL.md + references/），供 Codex（.agents/skills/）与 Claude Code（.claude/skills/）自动读取，减少命令失败、乱码与反复试错。

原理

AI 代理执行命令失败，本质是"生成即采样"：模型先验以 bash 为主、缺少本机环境事实。pwsh-guide 把环境探测结果固化进 skill 的 references（惰性加载、不占上下文），并用命令铁律 + 失败诊断约束生成空间。

v0.3 起补上"验证闭环"：init/refresh 生成快照（.meta.json）→ check 检测环境漂移 → SKILL.md 内嵌快速自检指令；环境变化后 AI 先 refresh 再继续，不再用过期的指南。

v0.4 起按"默认 shell 变体"渲染：Windows 上区分 pwsh（PowerShell 7）与 powershell.exe（Windows PowerShell 5.1）——pwsh 指南默认 UTF-8、无需输入侧编码 hack，并包含 -Parallel/??/三元等特性；5.1 指南保留输入侧 hack。两个实测参数陷阱（内联 splatting、特殊字符内联拼接）已固化进两变体模板。

v0.5 起增加会话环境确认：生成的 skill 在执行环境、数据、服务或远程路径相关操作前，会直接询问用户当前是开发、测试/预发布、生产还是不确定。没有明确回答时按“未知环境 + 仅本地数据”处理，不会根据目录、Git 分支、主机名或 NODE_ENV 自动推断生产环境。确认答案只在当前会话有效，不写入项目文件。

• Windows 下生成 PowerShell 指南；macOS/Linux 下生成 bash/zsh 指南（只生成当前环境可用内容，省 token）
• 平台无关探测全部用 Node 原生实现（os / process.env / fs），不依赖特定 shell
• 工具版本并行探测；项目上下文以 git 根为基准，并按 lock 文件推断推荐包管理器与项目命令

安装与使用

# 项目根目录运行（npx 方式，无需全局安装）
npx pwsh-guide init
# 环境变化后更新（重新生成 SKILL.md 与 references，两份输出）
npx pwsh-guide refresh
# 检测环境漂移（退出码 0=一致，1=有漂移，2=无快照）
npx pwsh-guide check
# 只输出探测 JSON，不写任何文件（stdout 为纯 JSON）
npx pwsh-guide init --dry-run
# 查看版本
npx pwsh-guide --version

生成的 skill 有两份（内容一致，分别被不同代理发现）：

• .agents/skills/pwsh-guide/（Codex）
• .claude/skills/pwsh-guide/（Claude Code）

每份包含：

• SKILL.md：命令执行铁律、输入/输出编码处理、快速自检、代码库检索指引、失败诊断、项目命令
• references/environment.md：探测到的本机环境事实（shell 版本/编码/locale/工具/项目上下文）
• references/commands.md：按探测到的工具动态裁剪的命令模板
• .meta.json：生成快照（check 漂移检测的基准）

环境边界：环境确认是会话级安全提示，不是生产数据授权。开发环境缺少数据时，代理应报告数据不可用，不得自行切换到生产数据源。

探测内容（只读）

• 平台与 OS：os.platform() / os.release() / os.arch() / 主机名 / 用户与临时目录
• shell（按平台深度探测）：
  • Windows：PowerShell 版本 / PSEdition / shell 变体（pwsh 或 powershell，按 $env:SHELL 判定，可用 PWSH_GUIDE_SHELL=pwsh 强制）/ 控制台输出编码 / $OutputEncoding / chcp / 执行策略 / pwsh 7 可用性；powershell.exe 探测失败时自动用 pwsh 重试
  • macOS/Linux：默认 shell（$SHELL）/ 可用 shell（bash / zsh / fish）/ locale（LANG / LC_ALL / LC_CTYPE）/ WSL 标注
• 工具：git、node、npm、npx、pnpm、yarn、bun、python、py、uv、pip、docker、make、rg、gh、pwsh、cargo、go 的可用性与版本（PATH 遍历 + --version，并行探测，超时/缺失记为 null）
• 项目（以 git 根为基准）：标记文件、venv、package.json scripts、推荐包管理器（lock 文件推断）、README / Makefile 目标 / Docker Compose、项目根第一层子目录

开发

bin/pwsh-guide.js              CLI 入口（init / refresh / check / --dry-run）
src/probe.js                   跨平台主探测（Node 原生；并行工具探测；项目根基准）
src/detect.js                  仓库根判定与双输出目录解析
src/render.js                  按 shell 族与变体渲染 SKILL.md / environment.md / commands.md
src/meta.js                    生成快照与漂移对比（check 用）
scripts/probe.windows.ps1      Windows 深度探测（PS 5.1 兼容，输出 UTF-8 JSON）
scripts/probe.unix.sh          Unix 深度探测（POSIX sh 兼容，输出 UTF-8 JSON）
templates/SKILL.powershell.md  PowerShell 5.1 变体 SKILL.md 模板（{{占位符}} 由 render.js 填充）
templates/SKILL.pwsh.md        pwsh 7 变体 SKILL.md 模板
templates/SKILL.unix.md        Unix 族 SKILL.md 模板
test/probe.test.js             单元测试（node --test）
.github/workflows/ci.yml       三平台（windows/ubuntu/macos）测试与集成验证

变更记录由 OpenSpec 管理（openspec/）。

验证范围

• CI：windows-latest / ubuntu-latest / macos-latest 三平台自动运行单元测试与 init/check 集成验证
• Windows：本机实测（探测 JSON / init / refresh / check）
• 会话边界：模板包含环境确认问句与未知环境下的仅本地数据策略