pwsh-guide 0.1.0

package/README.md

@@ -0,0 +1,47 @@
+# pwsh-guide
+
+生成项目级 Agent Skill：探测当前 Windows/PowerShell 环境与本项目上下文，产出可靠的命令使用指南（`SKILL.md` + `references/`），供 Codex、Claude Code 等代理自动读取，减少命令失败、乱码与反复试错。
+
+## 原理
+
+AI 代理在 Windows + PowerShell 下执行命令失败，本质是"生成即采样"：模型先验以 bash 为主、缺少本机环境事实。`pwsh-guide` 把环境探测结果固化进 skill 的 references（惰性加载、不占上下文），并用命令铁律 + 失败诊断约束生成空间。
+
+## 安装（本地开发）
+
+```powershell
+npm link
+```
+
+## 用法
+
+```powershell
+# 在任意项目根目录运行
+pwsh-guide init             # 探测并生成 .agents/skills/pwsh-guide/
+pwsh-guide refresh          # 环境变化后重新探测，更新 references
+pwsh-guide init --dry-run   # 只输出探测 JSON，不写文件
+```
+
+生成的 skill 位于 `.agents/skills/pwsh-guide/`：
+
+- `SKILL.md`：命令执行铁律、编码与乱码处理、失败分类诊断、禁止事项
+- `references/environment.md`：探测到的本机环境事实（PS 版本/编码/执行策略/工具/项目上下文）
+- `references/commands.md`：按探测到的工具动态裁剪的命令模板
+
+## 探测内容（只读）
+
+- shell：PowerShell 版本/PSEdition/编码/代码页/执行策略/OS/用户与临时目录
+- 工具：git、node、npm、npx、pnpm、yarn、bun、python、py、uv、pip、docker、make、rg、gh、pwsh、cargo、go 的可用性与版本
+- 项目：git 根（向上查找，无则用当前目录）、标记文件、venv、package.json scripts、第一层子目录
+
+## 开发
+
+```text
+bin/pwsh-guide.js   CLI 入口（init / refresh / --dry-run）
+src/probe.js        spawn powershell.exe 执行探测并解析 JSON
+src/detect.js       仓库根判定与目标目录解析
+src/render.js       渲染 SKILL.md / environment.md / commands.md
+scripts/probe.ps1   只读探测脚本（PS 5.1 兼容，输出 UTF-8 JSON）
+templates/SKILL.md  SKILL.md 模板（{{占位符}} 由 render.js 填充）
+```
+
+变更记录由 OpenSpec 管理（`openspec/`），当前变更：`add-pwsh-guide`。

package/bin/pwsh-guide.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// pwsh-guide CLI 入口：init / refresh / --dry-run
+// 用法：pwsh-guide init [--dry-run] | pwsh-guide refresh | pwsh-guide help
+import { parseArgs } from 'node:util';
+import fs from 'node:fs';
+import path from 'node:path';
+import { probeEnvironment } from '../src/probe.js';
+import { resolveSkillDir } from '../src/detect.js';
+import { renderSkill, renderEnvironment, renderCommands } from '../src/render.js';
+
+const USAGE = `pwsh-guide - 生成项目级 PowerShell/cmd 操作指南 Agent Skill
+
+用法:
+  pwsh-guide init            探测环境并在 .agents/skills/pwsh-guide/ 生成 skill
+  pwsh-guide refresh         重新探测并更新 references（SKILL.md 保持不变）
+  pwsh-guide init --dry-run  仅输出探测结果，不写任何文件
+
+选项:
+  --dry-run  只输出探测 JSON（用于调试）
+  -h, --help 显示本帮助
+`;
+
+async function main() {
+  const { positionals, values } = parseArgs({
+    allowPositionals: true,
+    options: {
+      'dry-run': { type: 'boolean', default: false },
+      help: { type: 'boolean', short: 'h', default: false },
+    },
+  });
+
+  const command = positionals[0] ?? 'help';
+  if (values.help || command === 'help') {
+    console.log(USAGE);
+    return;
+  }
+  if (command !== 'init' && command !== 'refresh') {
+    console.error(`[pwsh-guide] 未知命令: ${command}\n`);
+    console.error(USAGE);
+    process.exit(1);
+  }
+
+  const cwd = process.cwd();
+  const dryRun = values['dry-run'];
+
+  console.log('[pwsh-guide] 正在探测环境（只读，不修改任何文件）...');
+  const env = await probeEnvironment(cwd);
+
+  if (dryRun) {
+    console.log(JSON.stringify(env, null, 2));
+    return;
+  }
+
+  const skillDir = resolveSkillDir(cwd);
+  const skillExists = fs.existsSync(skillDir);
+  if (command === 'init' && skillExists) {
+    console.error(`[pwsh-guide] ${skillDir} 已存在，请改用 "pwsh-guide refresh" 更新，或先删除该目录后再 init。`);
+    process.exit(1);
+  }
+  if (command === 'refresh' && !skillExists) {
+    console.error(`[pwsh-guide] ${skillDir} 不存在，请先运行 "pwsh-guide init"。`);
+    process.exit(1);
+  }
+
+  const refsDir = path.join(skillDir, 'references');
+  fs.mkdirSync(refsDir, { recursive: true });
+
+  if (command === 'init') {
+    fs.writeFileSync(path.join(skillDir, 'SKILL.md'), renderSkill(env), 'utf8');
+    console.log(`[pwsh-guide] 已生成 ${path.join(skillDir, 'SKILL.md')}`);
+  }
+  fs.writeFileSync(path.join(refsDir, 'environment.md'), renderEnvironment(env), 'utf8');
+  fs.writeFileSync(path.join(refsDir, 'commands.md'), renderCommands(env), 'utf8');
+  console.log(`[pwsh-guide] 已更新 ${path.join(refsDir, 'environment.md')}`);
+  console.log(`[pwsh-guide] 已更新 ${path.join(refsDir, 'commands.md')}`);
+  console.log('\n完成。新会话中 Codex/Claude Code 会自动发现该 skill（项目级 .agents/skills/）。');
+}
+
+main().catch((err) => {
+  console.error(`[pwsh-guide] 失败: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "pwsh-guide",
+  "version": "0.1.0",
+  "description": "Generate a project-level Agent Skill: probe the current Windows/PowerShell environment and produce a reliable command guide (SKILL.md + references) for agents such as Codex and Claude Code.",
+  "type": "module",
+  "bin": {
+    "pwsh-guide": "bin/pwsh-guide.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin",
+    "src",
+    "scripts",
+    "templates"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "agent-skills",
+    "powershell",
+    "windows",
+    "codex",
+    "claude-code"
+  ],
+  "license": "MIT"
+}

package/scripts/probe.ps1

@@ -0,0 +1,107 @@
+# probe.ps1 - pwsh-guide 环境探测脚本（只读，不修改任何文件或系统设置）
+# 用法：powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File probe.ps1
+# 输出：UTF-8 JSON 到 stdout（shell / tools / project 三部分）
+# 兼容：Windows PowerShell 5.1+（不使用 PS7 新语法：??、&&、三元等）
+
+$originalConsoleEncoding = [Console]::OutputEncoding.WebName
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+$ErrorActionPreference = 'Continue'
+
+function Get-ToolInfo {
+    param([string]$Name)
+    $cmd = Get-Command $Name -ErrorAction SilentlyContinue
+    if ($null -eq $cmd) { return $null }
+    $version = $null
+    try {
+        $raw = & $Name --version 2>$null | Select-Object -First 1
+        if ($null -ne $raw -and -not [string]::IsNullOrWhiteSpace([string]$raw)) { $version = [string]$raw }
+    } catch { $version = $null }
+    if ($null -eq $version -and $cmd.Source) {
+        try {
+            $v = (Get-Item $cmd.Source -ErrorAction Stop).VersionInfo.FileVersion
+            if ($null -ne $v -and -not [string]::IsNullOrWhiteSpace($v) -and $v -ne '0.0.0.0') { $version = $v }
+        } catch { $version = $null }
+    }
+    return [pscustomobject]@{ name = $Name; version = $version; source = $cmd.Source }
+}
+
+$executionPolicy = @{}
+Get-ExecutionPolicy -List | ForEach-Object { $executionPolicy[[string]$_.Scope] = [string]$_.ExecutionPolicy }
+
+$chcp = $null
+try {
+    $chcpText = (& chcp 2>$null | Select-Object -First 1)
+    if ($chcpText -match '(\d+)') { $chcp = [int]$Matches[1] }
+} catch { $chcp = $null }
+
+$toolNames = @('git','node','npm','npx','pnpm','yarn','bun','python','py','uv','pip','docker','make','rg','gh','pwsh','cargo','go')
+$tools = @()
+foreach ($n in $toolNames) {
+    $info = Get-ToolInfo $n
+    if ($null -ne $info) { $tools += $info }
+}
+
+$cwd = (Get-Location).Path
+
+$gitRoot = $null
+if (Get-Command git -ErrorAction SilentlyContinue) {
+    try {
+        $line = git rev-parse --show-toplevel 2>$null | Select-Object -First 1
+        if ($line -and (Test-Path $line)) { $gitRoot = $line }
+    } catch { $gitRoot = $null }
+}
+
+$markerNames = @('package.json','pyproject.toml','requirements.txt','uv.lock','go.mod','Cargo.toml','pnpm-lock.yaml','yarn.lock','Dockerfile')
+$subdirs = @(Get-ChildItem -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -notin @('.git','.venv','venv','node_modules') } | Select-Object -ExpandProperty Name)
+$foundMarkers = @()
+foreach ($m in $markerNames) {
+    foreach ($d in (@('.') + $subdirs)) {
+        $p = Join-Path $cwd (Join-Path $d $m)
+        if (Test-Path $p) {
+            if ($d -eq '.') { $rel = $m } else { $rel = "$d\$m" }
+            $foundMarkers += $rel
+        }
+    }
+}
+
+$venv = $null
+foreach ($d in @('.venv','venv')) {
+    if (Test-Path (Join-Path $cwd (Join-Path $d 'pyvenv.cfg'))) { $venv = $d; break }
+}
+
+$packageScripts = @{}
+$pkgPath = Join-Path $cwd 'package.json'
+if (Test-Path $pkgPath) {
+    try {
+        $pkg = Get-Content -Raw $pkgPath | ConvertFrom-Json
+        if ($null -ne $pkg.scripts) {
+            $pkg.scripts.PSObject.Properties | ForEach-Object { $packageScripts[$_.Name] = [string]$_.Value }
+        }
+    } catch { $packageScripts = @{} }
+}
+
+$result = [pscustomobject]@{
+    shell = [pscustomobject]@{
+        psVersion = $PSVersionTable.PSVersion.ToString()
+        psEdition = $PSVersionTable.PSEdition
+        hostName = $Host.Name
+        pwsh7Available = ($null -ne (Get-Command pwsh -ErrorAction SilentlyContinue))
+        osVersion = [System.Environment]::OSVersion.VersionString
+        consoleOutputEncoding = $originalConsoleEncoding
+        outputEncoding = $OutputEncoding.WebName
+        chcp = $chcp
+        executionPolicy = $executionPolicy
+        userProfile = $env:USERPROFILE
+        tempDir = $env:TEMP
+    }
+    tools = $tools
+    project = [pscustomobject]@{
+        cwd = $cwd
+        gitRoot = $gitRoot
+        markers = $foundMarkers
+        venv = $venv
+        packageScripts = $packageScripts
+        subdirs = $subdirs
+    }
+}
+$result | ConvertTo-Json -Depth 5

package/src/detect.js

@@ -0,0 +1,19 @@
+// detect.js - 仓库根判定与 skill 目标目录解析
+// 用法：findProjectRoot(cwd) -> string；resolveSkillDir(cwd) -> string
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function findProjectRoot(startDir) {
+  const start = path.resolve(startDir);
+  let dir = start;
+  for (;;) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return start; // 找不到 .git，降级为当前目录
+    dir = parent;
+  }
+}
+
+export function resolveSkillDir(cwd) {
+  return path.join(findProjectRoot(cwd), '.agents', 'skills', 'pwsh-guide');
+}

package/src/probe.js

@@ -0,0 +1,41 @@
+// probe.js - 调用 scripts/probe.ps1 探测环境并解析 JSON
+// 用法：probeEnvironment(cwd) -> Promise<object>
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PROBE_SCRIPT = path.resolve(__dirname, '..', 'scripts', 'probe.ps1');
+
+export async function probeEnvironment(cwd) {
+  return new Promise((resolve, reject) => {
+    const args = [
+      '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass',
+      '-File', PROBE_SCRIPT,
+    ];
+    const child = spawn('powershell.exe', args, { cwd, shell: false, windowsHide: true });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', (err) => reject(new Error(`无法启动 powershell.exe: ${err.message}`)));
+    child.on('close', (code) => {
+      if (code !== 0) {
+        reject(new Error(`probe.ps1 退出码 ${code}: ${stderr.trim()}`));
+        return;
+      }
+      const jsonStart = stdout.indexOf('{');
+      if (jsonStart === -1) {
+        reject(new Error(`探测输出不含 JSON:\n${stdout}\n${stderr}`));
+        return;
+      }
+      try {
+        resolve(JSON.parse(stdout.slice(jsonStart)));
+      } catch (err) {
+        reject(new Error(`解析探测 JSON 失败: ${err.message}`));
+      }
+    });
+  });
+}

package/src/render.js

@@ -0,0 +1,245 @@
+// render.js - 将探测 JSON 渲染为 SKILL.md / references/environment.md / references/commands.md
+// 用法：renderSkill(env)、renderEnvironment(env)、renderCommands(env)
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATE = fs.readFileSync(path.resolve(__dirname, '..', 'templates', 'SKILL.md'), 'utf8');
+
+function fill(template, values) {
+  let out = template;
+  for (const [key, value] of Object.entries(values)) {
+    out = out.split(`{{${key}}}`).join(String(value));
+  }
+  return out;
+}
+
+function getTool(env, name) {
+  return (env.tools || []).find((t) => t.name === name);
+}
+
+function toolVersion(env, name) {
+  const t = getTool(env, name);
+  return t && t.version ? String(t.version) : null;
+}
+
+function toolsSummary(env) {
+  const tools = (env.tools || []).filter((t) => t.version);
+  if (tools.length === 0) return '- 未探测到常用工具，请检查 PATH 后运行 pwsh-guide refresh。';
+  return tools.map((t) => `- ${t.name}: \`${t.version}\``).join('\n');
+}
+
+function executionPolicySummary(env) {
+  const ep = (env.shell && env.shell.executionPolicy) || {};
+  const parts = Object.entries(ep).map(([scope, policy]) => `${scope}=${policy}`);
+  return parts.length ? parts.join(', ') : '未获取';
+}
+
+function projectContextBlock(env) {
+  const p = env.project || {};
+  const lines = [];
+  lines.push(`- 当前目录：\`${p.cwd || '未知'}\``);
+  lines.push(`- git 仓库根：${p.gitRoot ? `\`${p.gitRoot}\`` : '未发现 .git（已用当前目录作为根）'}`);
+  lines.push(`- venv：${p.venv ? `\`${p.venv}\`` : '未发现'}`);
+  const markers = p.markers && p.markers.length ? p.markers.join(', ') : '未发现';
+  lines.push(`- 项目标记文件：${markers}`);
+  const scripts = p.packageScripts && Object.keys(p.packageScripts).length
+    ? Object.entries(p.packageScripts).map(([k, v]) => `${k}: ${v}`).join('；')
+    : '未发现 package.json scripts';
+  lines.push(`- package.json scripts：${scripts}`);
+  const subdirs = p.subdirs && p.subdirs.length ? p.subdirs.join(', ') : '（空）';
+  lines.push(`- 第一层子目录：${subdirs}`);
+  return lines.join('\n');
+}
+
+export function renderSkill(env) {
+  const shell = env.shell || {};
+  return fill(TEMPLATE, {
+    generatedAt: new Date().toISOString(),
+    psVersion: shell.psVersion || '未知',
+    consoleOutputEncoding: shell.consoleOutputEncoding || '未知',
+    chcp: shell.chcp ?? '未知',
+    executionPolicySummary: executionPolicySummary(env),
+    gitRoot: (env.project && env.project.gitRoot) || '未发现 .git',
+    cwd: (env.project && env.project.cwd) || process.cwd(),
+    toolsSummary: toolsSummary(env),
+    projectContext: projectContextBlock(env),
+  });
+}
+
+function renderEnvironment(env) {
+  const shell = env.shell || {};
+  const p = env.project || {};
+  const lines = [];
+  lines.push('# 环境事实（pwsh-guide 探测结果）');
+  lines.push('');
+  lines.push('> 本文件由 pwsh-guide 生成；环境变化后运行 `pwsh-guide refresh` 更新。');
+  lines.push('');
+  lines.push('## Shell 环境');
+  lines.push('');
+  lines.push('| 项 | 值 |');
+  lines.push('| --- | --- |');
+  lines.push(`| PowerShell 版本 | ${shell.psVersion ?? '-'} |`);
+  lines.push(`| PSEdition | ${shell.psEdition ?? '-'} |`);
+  lines.push(`| 主机 | ${shell.hostName ?? '-'} |`);
+  lines.push(`| pwsh 7 可用 | ${shell.pwsh7Available ? '是' : '否'} |`);
+  lines.push(`| OS | ${shell.osVersion ?? '-'} |`);
+  lines.push(`| 控制台输出编码 | ${shell.consoleOutputEncoding ?? '-'} |`);
+  lines.push(`| $OutputEncoding | ${shell.outputEncoding ?? '-'} |`);
+  lines.push(`| 代码页 chcp | ${shell.chcp ?? '-'} |`);
+  lines.push(`| 执行策略 | ${executionPolicySummary(env)} |`);
+  lines.push(`| 用户目录 | ${shell.userProfile ?? '-'} |`);
+  lines.push(`| 临时目录 | ${shell.tempDir ?? '-'} |`);
+  lines.push('');
+  lines.push('## 可用工具');
+  lines.push('');
+  const tools = (env.tools || []).filter((t) => t.version);
+  if (tools.length === 0) {
+    lines.push('未探测到常用工具。');
+  } else {
+    lines.push('| 工具 | 版本 | 路径 |');
+    lines.push('| --- | --- | --- |');
+    for (const t of tools) {
+      lines.push(`| ${t.name} | ${t.version} | \`${t.source || '-'}\` |`);
+    }
+  }
+  lines.push('');
+  lines.push('## 项目上下文');
+  lines.push('');
+  lines.push('| 项 | 值 |');
+  lines.push('| --- | --- |');
+  lines.push(`| 当前目录 | ${p.cwd ?? '-'} |`);
+  lines.push(`| git 仓库根 | ${p.gitRoot ?? '未发现 .git'} |`);
+  lines.push(`| venv | ${p.venv ?? '未发现'} |`);
+  lines.push(`| 标记文件 | ${p.markers && p.markers.length ? p.markers.join(', ') : '未发现'} |`);
+  const scriptsText = p.packageScripts && Object.keys(p.packageScripts).length
+    ? Object.entries(p.packageScripts).map(([k, v]) => `${k}: ${v}`).join('<br>')
+    : '未发现 package.json scripts';
+  lines.push(`| package.json scripts | ${scriptsText} |`);
+  lines.push(`| 第一层子目录 | ${p.subdirs && p.subdirs.length ? p.subdirs.join(', ') : '-'} |`);
+  return `${lines.join('\n')}\n`;
+}
+
+const COMMON_COMMANDS = [
+  '- 列出目录：`Get-ChildItem -Path . -Force`',
+  '- 递归查找文件：`Get-ChildItem -Recurse -Filter \'*.py\'`',
+  '- 文本搜索：`Select-String -Path \'**\\*.py\' -Pattern \'关键词\'`',
+  '- 读文件：`Get-Content -Path \'<file>\' -Encoding UTF8`',
+  '- 写文件：`Set-Content -Path \'<file>\' -Value \'<text>\' -Encoding UTF8`',
+  '- 判断路径存在：`Test-Path \'<path>\'`',
+  '- 环境变量读：`$env:NAME`；写：`$env:NAME = \'value\'`',
+  '- 进程列表：`Get-Process`；结束：`Stop-Process -Name <name> -Force`',
+  '- 端口占用：`Get-NetTCPConnection -LocalPort <port>`',
+];
+
+const TOOL_ORDER = [
+  'git', 'node', 'npm', 'npx', 'pnpm', 'yarn', 'bun',
+  'python', 'py', 'uv', 'pip', 'docker', 'make', 'rg', 'gh', 'pwsh', 'cargo', 'go',
+];
+
+const TOOL_COMMANDS = {
+  git: [
+    '- 状态：`git status`',
+    '- 未暂存差异：`git diff`；暂存差异：`git diff --cached`',
+    '- 最近提交：`git log --oneline -10`',
+    '- 当前分支：`git branch --show-current`',
+    '- 仓库根：`git rev-parse --show-toplevel`',
+  ],
+  node: [
+    '- 版本：`node --version`',
+    '- 运行脚本：`node <file>.js`',
+    '- 语法检查：`node --check <file>.js`',
+  ],
+  npm: [
+    '- 安装依赖（改 package.json 后）：`npm install`',
+    '- 运行脚本：`npm run <script>`；查看脚本：`npm run`（不带参数）',
+    '- 安装依赖到项目：`npm install <pkg>`',
+  ],
+  npx: [
+    '- 临时运行包：`npx <pkg> <args>`',
+    '- 查看包信息：`npx <pkg> --help`',
+  ],
+  pnpm: [
+    '- 安装依赖：`pnpm install`',
+    '- 运行脚本：`pnpm run <script>`',
+  ],
+  yarn: [
+    '- 安装依赖：`yarn install`',
+    '- 运行脚本：`yarn run <script>`',
+  ],
+  bun: [
+    '- 安装依赖：`bun install`',
+    '- 运行脚本：`bun run <script>`',
+  ],
+  python: [
+    '- 版本：`python --version`',
+    '- 运行：`python <file>.py`',
+    '- 单行执行：`python -c \'print("hi")\'`',
+  ],
+  py: [
+    '- 版本：`py --version`（Windows Python 启动器）',
+    '- 运行：`py <file>.py`',
+  ],
+  uv: [
+    '- 版本：`uv --version`',
+    '- 创建虚拟环境：`uv venv`',
+    '- 在 venv 中运行：`uv run <cmd>`',
+    '- 添加依赖：`uv add <pkg>`',
+  ],
+  pip: [
+    '- 安装：`pip install <pkg>`',
+    '- 冻结依赖：`pip freeze`',
+  ],
+  docker: [
+    '- 版本：`docker --version`',
+    '- 容器列表：`docker ps`',
+  ],
+  make: [
+    '- 查看可用目标：`make -n` 或 `make help`',
+    '- 执行目标：`make <target>`',
+  ],
+  rg: [
+    '- 文本搜索：`rg \'<pattern>\' <path>`',
+    '- 列出文件：`rg --files`',
+  ],
+  gh: [
+    '- 仓库概览：`gh repo view`',
+    '- 创建 PR：`gh pr create`',
+  ],
+  pwsh: [
+    '- 版本：`pwsh -Version`',
+    '- 运行脚本：`pwsh -File <script>.ps1`',
+  ],
+  cargo: [
+    '- 构建：`cargo build`',
+    '- 测试：`cargo test`',
+  ],
+  go: [
+    '- 构建：`go build ./...`',
+    '- 测试：`go test ./...`',
+  ],
+};
+
+function renderCommands(env) {
+  const lines = [];
+  lines.push('# 命令模板（按工具）');
+  lines.push('');
+  lines.push('> 仅列出探测到可用的工具；`<...>` 为占位参数，执行前替换。');
+  lines.push('');
+  lines.push('## 通用操作（PowerShell 原生，始终可用）');
+  for (const c of COMMON_COMMANDS) lines.push(c);
+  lines.push('');
+  for (const tool of TOOL_ORDER) {
+    const info = getTool(env, tool);
+    if (!info || !info.version) continue;
+    const cmds = TOOL_COMMANDS[tool];
+    if (!cmds) continue;
+    lines.push(`## ${tool}（${info.version}）`);
+    for (const c of cmds) lines.push(c);
+    lines.push('');
+  }
+  return `${lines.join('\n')}`;
+}
+
+export { renderEnvironment, renderCommands };

package/templates/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: pwsh-guide
+description: 本项目的 Windows PowerShell/cmd 命令执行指南。需要执行 shell 命令、遇到 PowerShell 报错、中文乱码或不确定命令语法时使用；含本机环境事实、命令模板与失败诊断。
+---
+
+# PowerShell/cmd 操作指南（本环境）
+
+> 由 `pwsh-guide` 生成于 {{generatedAt}}。环境变化后运行 `pwsh-guide refresh` 更新。
+
+## 1. 执行命令前先确认
+
+- Shell 是 `powershell.exe`（PS {{psVersion}}），**不是 bash**：禁止 `ls -la`、`grep`、`cat`、`rm -rf`、`export`。
+- 控制台输出编码：{{consoleOutputEncoding}}（代码页 chcp {{chcp}}）。
+- 执行策略：{{executionPolicySummary}}。
+- 当前目录：`{{cwd}}`；git 根：`{{gitRoot}}`。
+- 完整环境事实见 `references/environment.md`；可用命令模板见 `references/commands.md`。
+
+## 2. 命令执行铁律
+
+1. 一条命令一次执行；禁止 `&&`、`||`、`;` 链式（PowerShell 5.1 不支持 `&&`）。
+2. 执行后检查退出状态：外部命令看 `$LASTEXITCODE`，cmdlet 看 `$?`，并查看 stderr。
+3. 路径含空格或中文时用单引号包裹：`Get-Content 'E:\path with 中文\file.txt'`。
+4. 环境变量读取 `$env:NAME`，写入 `$env:NAME = 'value'`（仅当前会话）。
+5. 只读操作优先；删除等危险操作先 `-WhatIf` 或展示计划再执行。
+6. 长命令优先写成 `.ps1` 再以 `-File` 执行，避免内联引号地狱。
+
+## 3. 常用命令模板
+
+可用工具与命令见 `references/commands.md`。本机探测到的工具：
+
+{{toolsSummary}}
+
+## 4. 编码与乱码处理
+
+- 临时切 UTF-8 输出：`[Console]::OutputEncoding = [System.Text.Encoding]::UTF8`。
+- 切换代码页：`chcp 65001`（UTF-8）。
+- 写文件指定编码：`Set-Content -Path <file> -Value <text> -Encoding UTF8`（PS 5.1 会写 BOM）。
+- 读文件乱码：`Get-Content -Path <file> -Encoding UTF8`。
+- 重定向中文输出优先 `Out-File -Encoding UTF8`，避免 `>` 按控制台编码写出。
+
+## 5. 失败分类诊断
+
+| 症状 | 常见原因 | 处理 |
+| --- | --- | --- |
+| 命令找不到 | PATH 缺失 / 拼写错 | `Get-Command <name>` 确认；查看 `references/environment.md` 工具表 |
+| 中文乱码 | 代码页与输出编码不匹配 | 按第 4 节切换 UTF-8 |
+| 引号/转义报错 | 内联 `-Command` 引号地狱 | 改用 `-File` 脚本或参数数组 |
+| 权限拒绝 | 执行策略 / ACL | `Get-ExecutionPolicy -List`；脚本加 `-ExecutionPolicy Bypass` |
+| 路径找不到 | 空格/中文/反斜杠 | 单引号包裹；先 `Test-Path` |
+| 程序假死 | 交互式命令等待输入 | 加 `-NonInteractive`，或 `echo y | <cmd>` |
+
+## 6. 禁止事项
+
+- 禁止 bash 语法：`ls -la`、`grep`、`cat`、`rm -rf`、`export`、`&&`/`||`。
+- 删除一律用 `Remove-Item -Path <path> -Recurse -Force`，且先确认路径再执行。
+- 未读文件内容不得修改；不得批量格式化无关代码。
+- 仓库 AGENTS.md 规则优先于本文件。
+
+## 7. 项目上下文（来自探测）
+
+{{projectContext}}