pwsh-guide 0.2.2 → 0.4.0

package/README.md

@@ -1,58 +1,75 @@
 # pwsh-guide
 
-生成项目级 Agent Skill：跨平台探测当前环境（Windows PowerShell / macOS / Linux shell）与本项目上下文，产出可靠的命令使用指南（`SKILL.md` + `references/`），供 Codex、Claude Code 等代理自动读取，减少命令失败、乱码与反复试错。
+生成项目级 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、特殊字符内联拼接）已固化进两变体模板。
+
 - Windows 下生成 PowerShell 指南；macOS/Linux 下生成 bash/zsh 指南（只生成当前环境可用内容，省 token）
 - 平台无关探测全部用 Node 原生实现（`os` / `process.env` / `fs`），不依赖特定 shell
+- 工具版本并行探测；项目上下文以 git 根为基准，并按 lock 文件推断推荐包管理器与项目命令
 
 ## 安装与使用
 
 ```bash
 # 项目根目录运行（npx 方式，无需全局安装）
 npx pwsh-guide init
-# 环境变化后更新
+# 环境变化后更新（重新生成 SKILL.md 与 references，两份输出）
 npx pwsh-guide refresh
-# 只输出探测 JSON，不写文件
+# 检测环境漂移（退出码 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/`：
+生成的 skill 有两份（内容一致，分别被不同代理发现）：
+
+- `.agents/skills/pwsh-guide/`（Codex）
+- `.claude/skills/pwsh-guide/`（Claude Code）
+
+每份包含：
 
-- `SKILL.md`：命令执行铁律、编码与乱码处理、失败分类诊断、禁止事项
+- `SKILL.md`：命令执行铁律、输入/输出编码处理、快速自检、代码库检索指引、失败诊断、项目命令
 - `references/environment.md`：探测到的本机环境事实（shell 版本/编码/locale/工具/项目上下文）
 - `references/commands.md`：按探测到的工具动态裁剪的命令模板
+- `.meta.json`：生成快照（`check` 漂移检测的基准）
 
 ## 探测内容（只读）
 
 - 平台与 OS：`os.platform()` / `os.release()` / `os.arch()` / 主机名 / 用户与临时目录
 - shell（按平台深度探测）：
-  - Windows：PowerShell 版本 / PSEdition / 控制台输出编码 / `$OutputEncoding` / chcp / 执行策略 / pwsh 7 可用性
+  - 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、第一层子目录
+- 工具：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、项目根第一层子目录
 
 ## 开发
 
 ```text
-bin/pwsh-guide.js              CLI 入口（init / refresh / --dry-run）
-src/probe.js                   跨平台主探测（Node 原生；按平台分发深度脚本）
-src/detect.js                  仓库根判定与目标目录解析
-src/render.js                  按 shell 族渲染 SKILL.md / environment.md / commands.md
+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 族 SKILL.md 模板（{{占位符}} 由 render.js 填充）
+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/`）：当前变更 `add-pwsh-guide`（已发布 v0.1.0）、`cross-platform-0.2`（进行中）。
+变更记录由 OpenSpec 管理（`openspec/`）。
 
 ## 验证范围
 
-- Windows：本机实测（探测 JSON / init / refresh）
-- macOS/Linux：静态审查（POSIX sh 脚本与 Node 分支），尚未真机运行
+- CI：windows-latest / ubuntu-latest / macos-latest 三平台自动运行单元测试与 `init`/`check` 集成验证
+- Windows：本机实测（探测 JSON / init / refresh / check）

package/bin/pwsh-guide.js

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
-// pwsh-guide CLI 入口：init / refresh / --dry-run
-// 用法：pwsh-guide init [--dry-run] | pwsh-guide refresh | pwsh-guide help
+// pwsh-guide CLI 入口：init / refresh / check / --dry-run
+// 用法：pwsh-guide init [--dry-run] | pwsh-guide refresh | pwsh-guide check | pwsh-guide help
 import { parseArgs } from 'node:util';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { probeEnvironment } from '../src/probe.js';
-import { resolveSkillDir } from '../src/detect.js';
+import { resolveSkillDirs } from '../src/detect.js';
 import { renderSkill, renderEnvironment, renderCommands } from '../src/render.js';
+import { writeMeta, readMeta, compareEnv } from '../src/meta.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf8'));
@@ -15,8 +16,9 @@ const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', 'package.js
 const USAGE = `pwsh-guide - 生成项目级 Shell 操作指南 Agent Skill（跨平台：Windows PowerShell / macOS / Linux）
 
 用法:
-  pwsh-guide init            探测环境并在 .agents/skills/pwsh-guide/ 生成 skill
-  pwsh-guide refresh         重新探测并重新生成 SKILL.md 与 references
+  pwsh-guide init            探测环境并在 .agents/skills/ 与 .claude/skills/ 生成 skill
+  pwsh-guide refresh         重新探测并重新生成 SKILL.md 与 references（两份）
+  pwsh-guide check           重新探测并与上次生成快照对比，报告环境漂移（退出码 0=一致，1=有漂移，2=无快照）
   pwsh-guide init --dry-run  仅输出探测结果，不写任何文件
 
 选项:
@@ -45,16 +47,22 @@ async function main() {
     console.log(USAGE);
     return;
   }
-  if (command !== 'init' && command !== 'refresh') {
+  if (command !== 'init' && command !== 'refresh' && command !== 'check') {
     console.error(`[pwsh-guide] 未知命令: ${command}\n`);
     console.error(USAGE);
     process.exit(1);
   }
 
   const cwd = process.cwd();
+
+  if (command === 'check') {
+    await runCheck(cwd);
+    return;
+  }
+
   const dryRun = values['dry-run'];
 
-  console.log('[pwsh-guide] 正在探测环境（只读，不修改任何文件）...');
+  console.error('[pwsh-guide] 正在探测环境（只读，不修改任何文件）...');
   const env = await probeEnvironment(cwd);
 
   if (dryRun) {
@@ -62,27 +70,49 @@ async function main() {
     return;
   }
 
-  const skillDir = resolveSkillDir(cwd);
-  const skillExists = fs.existsSync(skillDir);
-  if (command === 'init' && skillExists) {
-    console.error(`[pwsh-guide] ${skillDir} 已存在，请改用 "pwsh-guide refresh" 更新，或先删除该目录后再 init。`);
+  const skillDirs = resolveSkillDirs(cwd);
+  const existing = skillDirs.filter((dir) => fs.existsSync(dir));
+  if (command === 'init' && existing.length > 0) {
+    console.error(`[pwsh-guide] ${existing.map((dir) => path.relative(cwd, dir)).join('、')} 已存在，请改用 "pwsh-guide refresh" 更新，或先删除该目录后再 init。`);
     process.exit(1);
   }
-  if (command === 'refresh' && !skillExists) {
-    console.error(`[pwsh-guide] ${skillDir} 不存在，请先运行 "pwsh-guide init"。`);
+  if (command === 'refresh' && existing.length === 0) {
+    console.error(`[pwsh-guide] 未找到 ${skillDirs.map((dir) => path.relative(cwd, dir)).join('、')}，请先运行 "pwsh-guide init"。`);
     process.exit(1);
   }
 
-  const refsDir = path.join(skillDir, 'references');
-  fs.mkdirSync(refsDir, { recursive: true });
+  for (const dir of skillDirs) {
+    const refsDir = path.join(dir, 'references');
+    fs.mkdirSync(refsDir, { recursive: true });
 
-  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/）。');
+    fs.writeFileSync(path.join(dir, 'SKILL.md'), renderSkill(env), 'utf8');
+    fs.writeFileSync(path.join(refsDir, 'environment.md'), renderEnvironment(env), 'utf8');
+    fs.writeFileSync(path.join(refsDir, 'commands.md'), renderCommands(env), 'utf8');
+    writeMeta(dir, env, pkg.version);
+    console.log(`[pwsh-guide] 已更新 ${dir}`);
+  }
+  console.log('\n完成。新会话中 Codex（.agents/skills/）与 Claude Code（.claude/skills/）会自动发现该 skill。');
+}
+
+async function runCheck(cwd) {
+  const skillDirs = resolveSkillDirs(cwd);
+  const withMeta = skillDirs.filter((dir) => readMeta(dir));
+  if (withMeta.length === 0) {
+    console.error('[pwsh-guide] 未找到 .meta.json 快照，请先运行 "pwsh-guide init" 或 "pwsh-guide refresh"。');
+    process.exit(2);
+  }
+  console.error('[pwsh-guide] 正在重新探测（只读）...');
+  const env = await probeEnvironment(cwd);
+  const meta = readMeta(withMeta[0]);
+  const drift = compareEnv(env, meta);
+  if (drift.length === 0) {
+    console.log(`[pwsh-guide] check：无漂移（快照 ${meta.generatedBy} @ ${meta.generatedAt}）。`);
+    process.exit(0);
+  }
+  console.log(`[pwsh-guide] check：发现 ${drift.length} 项漂移（相对 ${meta.generatedBy} @ ${meta.generatedAt}）：`);
+  for (const item of drift) console.log(`  - ${item}`);
+  console.log('运行 "pwsh-guide refresh" 更新 skill 后重读。');
+  process.exit(1);
 }
 
 main().catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pwsh-guide",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "Generate a project-level Agent Skill: probe the current environment (Windows PowerShell / macOS / Linux shell) and produce a reliable command guide (SKILL.md + references) for agents such as Codex and Claude Code.",
   "type": "module",
   "bin": {

package/scripts/probe.windows.ps1

@@ -17,11 +17,12 @@ try {
 } catch { $chcp = $null }
 
 $result = [pscustomobject]@{
-    defaultShell = 'powershell.exe'
+    defaultShell = if ($PSVersionTable.PSEdition -eq 'Core') { 'pwsh' } else { 'powershell.exe' }
     psVersion = $PSVersionTable.PSVersion.ToString()
     psEdition = $PSVersionTable.PSEdition
     hostName = $Host.Name
     pwsh7Available = ($null -ne (Get-Command pwsh -ErrorAction SilentlyContinue))
+    ps51Available = ($null -ne (Get-Command powershell.exe -ErrorAction SilentlyContinue))
     osVersion = [System.Environment]::OSVersion.VersionString
     consoleOutputEncoding = $originalConsoleEncoding
     outputEncoding = $OutputEncoding.WebName

package/src/detect.js

@@ -1,5 +1,5 @@
 // detect.js - 仓库根判定与 skill 目标目录解析
-// 用法：findGitRoot(cwd) -> string|null；findProjectRoot(cwd) -> string；resolveSkillDir(cwd) -> string
+// 用法：findGitRoot(cwd) -> string|null；findProjectRoot(cwd) -> string；resolveSkillDirs(cwd) -> string[]
 import fs from 'node:fs';
 import path from 'node:path';
 
@@ -18,6 +18,15 @@ export function findProjectRoot(startDir) {
   return findGitRoot(startDir) ?? path.resolve(startDir); // 找不到 .git，降级为当前目录
 }
 
-export function resolveSkillDir(cwd) {
-  return path.join(findProjectRoot(cwd), '.agents', 'skills', 'pwsh-guide');
+// 双输出：Codex 读取 .agents/skills/，Claude Code 读取 .claude/skills/
+export function resolveSkillDirs(cwd) {
+  const root = findProjectRoot(cwd);
+  return [
+    path.join(root, '.agents', 'skills', 'pwsh-guide'),
+    path.join(root, '.claude', 'skills', 'pwsh-guide'),
+  ];
 }
+
+export function resolveSkillDir(cwd) {
+  return resolveSkillDirs(cwd)[0];
+}

package/src/meta.js

@@ -0,0 +1,126 @@
+// meta.js - 生成快照与漂移对比
+// 用法：writeMeta(dir, env, generatorVersion)；readMeta(dir)；compareEnv(env, meta) -> string[]
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const META_SCHEMA_VERSION = 1;
+export const META_FILENAME = '.meta.json';
+
+// 快照只取"信号"字段，排除 cwd、hostname 等易变噪音，避免 check 误报
+export function buildMeta(env, generatorVersion) {
+  const tools = {};
+  for (const t of env.tools || []) tools[t.name] = t.version;
+  const shell = env.shell || {};
+  const project = env.project || {};
+  const pkgScripts = project.packageScripts || {};
+  const cwdScripts = project.cwdPackageScripts || {};
+  return {
+    schemaVersion: META_SCHEMA_VERSION,
+    generatedBy: generatorVersion,
+    generatedAt: new Date().toISOString(),
+    platform: env.platform,
+    family: env.family,
+    osRelease: (env.os && env.os.release) || null,
+    arch: (env.os && env.os.arch) || null,
+    shell: {
+      defaultShell: shell.defaultShell || null,
+      variant: shell.variant || null,
+      psVersion: shell.psVersion || null,
+      psEdition: shell.psEdition || null,
+      chcp: shell.chcp ?? null,
+      consoleOutputEncoding: shell.consoleOutputEncoding || null,
+      outputEncoding: shell.outputEncoding || null,
+      locale: (shell.locale && { ...shell.locale }) || null,
+    },
+    tools,
+    project: {
+      gitRoot: project.gitRoot || null,
+      markers: (project.markers || []).slice().sort(),
+      venv: project.venv || null,
+      packageManager: project.packageManager || null,
+      packageScripts: Object.keys(pkgScripts).length ? { ...pkgScripts } : null,
+      cwdPackageScripts: Object.keys(cwdScripts).length ? { ...cwdScripts } : null,
+      makefileTargets: (project.makefile && project.makefile.targets) || [],
+      compose: (project.compose && project.compose.file) || null,
+      readme: (project.readme && project.readme.file) || null,
+      subdirs: (project.subdirs || []).slice().sort(),
+    },
+  };
+}
+
+export function writeMeta(dir, env, generatorVersion) {
+  const meta = buildMeta(env, generatorVersion);
+  fs.writeFileSync(path.join(dir, META_FILENAME), `${JSON.stringify(meta, null, 2)}\n`, 'utf8');
+  return meta;
+}
+
+export function readMeta(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, META_FILENAME), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function eq(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+function fmt(value) {
+  if (value === null || value === undefined) return '无';
+  if (Array.isArray(value)) return value.length ? value.join(', ') : '无';
+  if (typeof value === 'object') return JSON.stringify(value);
+  return String(value);
+}
+
+// 对比当前环境与快照，返回差异项数组（空数组 = 无漂移）
+export function compareEnv(env, meta) {
+  const drift = [];
+  const shell = env.shell || {};
+  const project = env.project || {};
+  const tools = {};
+  for (const t of env.tools || []) tools[t.name] = t.version;
+
+  const expectShell = meta.shell || {};
+  const shellChecks = [
+    ['平台', env.platform, meta.platform],
+    ['OS 版本', (env.os && env.os.release) || null, meta.osRelease || null],
+    ['架构', (env.os && env.os.arch) || null, meta.arch || null],
+    ['默认 shell', shell.defaultShell || null, expectShell.defaultShell || null],
+    ['shell 变体', shell.variant || null, expectShell.variant || null],
+    ['PowerShell 版本', shell.psVersion || null, expectShell.psVersion || null],
+    ['chcp', shell.chcp ?? null, expectShell.chcp ?? null],
+    ['控制台输出编码', shell.consoleOutputEncoding || null, expectShell.consoleOutputEncoding || null],
+    ['$OutputEncoding', shell.outputEncoding || null, expectShell.outputEncoding || null],
+  ];
+  for (const [label, cur, old] of shellChecks) {
+    if (!eq(cur, old)) drift.push(`${label}: ${fmt(old)} → ${fmt(cur)}`);
+  }
+
+  const curLocale = shell.locale || {};
+  const oldLocale = expectShell.locale || {};
+  if (!eq(curLocale, oldLocale)) drift.push(`locale: ${fmt(oldLocale)} → ${fmt(curLocale)}`);
+
+  const toolNames = new Set([...Object.keys(meta.tools || {}), ...Object.keys(tools)]);
+  for (const name of [...toolNames].sort()) {
+    const oldVersion = (meta.tools || {})[name] || null;
+    const curVersion = tools[name] || null;
+    if (!eq(curVersion, oldVersion)) drift.push(`工具 ${name}: ${fmt(oldVersion)} → ${fmt(curVersion)}`);
+  }
+
+  const oldProject = meta.project || {};
+  const projectChecks = [
+    ['git 根', project.gitRoot || null, oldProject.gitRoot || null],
+    ['标记文件', (project.markers || []).slice().sort(), (oldProject.markers || []).slice().sort()],
+    ['venv', project.venv || null, oldProject.venv || null],
+    ['包管理器', project.packageManager || null, oldProject.packageManager || null],
+    ['package.json scripts', Object.keys(project.packageScripts || {}).length ? project.packageScripts : null, oldProject.packageScripts || null],
+    ['Makefile 目标', (project.makefile && project.makefile.targets) || [], oldProject.makefileTargets || []],
+    ['Docker Compose', (project.compose && project.compose.file) || null, oldProject.compose || null],
+  ];
+  for (const [label, cur, old] of projectChecks) {
+    if (!eq(cur, old)) drift.push(`${label}: ${fmt(old)} → ${fmt(cur)}`);
+  }
+
+  return drift;
+}

package/src/probe.js

@@ -7,7 +7,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { findGitRoot } from './detect.js';
+import { findGitRoot, findProjectRoot } from './detect.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const SCRIPTS_DIR = path.resolve(__dirname, '..', 'scripts');
@@ -27,6 +27,23 @@ const MARKER_NAMES = [
   'go.mod', 'Cargo.toml', 'pnpm-lock.yaml', 'yarn.lock', 'Dockerfile',
 ];
 
+// lock 文件 -> 推荐包管理器（优先级从高到低，多锁文件时取第一个命中的）
+const LOCK_PRIORITY = [
+  ['pnpm-lock.yaml', 'pnpm'],
+  ['bun.lockb', 'bun'],
+  ['bun.lock', 'bun'],
+  ['yarn.lock', 'yarn'],
+  ['package-lock.json', 'npm'],
+  ['uv.lock', 'uv'],
+  ['poetry.lock', 'poetry'],
+];
+
+const README_NAMES = ['README.md', 'readme.md', 'README', 'Readme.md'];
+const COMPOSE_NAMES = ['docker-compose.yml', 'docker-compose.yaml', 'compose.yml', 'compose.yaml'];
+const MAKEFILE_NAMES = ['Makefile', 'makefile', 'GNUmakefile'];
+const MAKEFILE_PSEUDO = new Set(['.PHONY', '.DEFAULT', '.SUFFIXES', '.EXPORT', '.ONESHELL', '.SILENT', '.NOTPARALLEL']);
+const MAKEFILE_MAX_TARGETS = 20;
+
 const IGNORED_SUBDIRS = new Set(['.git', '.venv', 'venv', 'node_modules']);
 const VERSION_TIMEOUT_MS = 5000;
 
@@ -41,7 +58,7 @@ const VERSION_ERROR_PATTERNS = [
   /找不到/,
 ];
 
-function isPlausibleVersion(text) {
+export function isPlausibleVersion(text) {
   if (!text) return false;
   return !VERSION_ERROR_PATTERNS.some((re) => re.test(text));
 }
@@ -75,6 +92,7 @@ export async function probeEnvironment(cwd) {
       defaultShell,
       defaultShellName: defaultShell.split(/[\\/]/).pop().toLowerCase(),
       ...deepShell,
+      variant: resolveShellVariant(platform, process.env, deepShell),
     },
     tools,
     project,
@@ -86,14 +104,34 @@ function resolveDefaultShell(platform, deepShell) {
   if (platform === 'win32') return 'powershell.exe';
   return process.env.SHELL || '/bin/sh';
 }
+// Windows shell 变体判定（可测纯函数）：'pwsh' | 'powershell' | null（非 Windows）
+// 优先级：PWSH_GUIDE_SHELL 覆盖 > $env:SHELL 指向 > 深度探测实际运行 shell > 默认 powershell
+export function resolveShellVariant(platform, env, deepShell) {
+  if (platform !== 'win32') return null;
+  const override = String(env.PWSH_GUIDE_SHELL || '').trim().toLowerCase();
+  if (override) return override.includes('pwsh') ? 'pwsh' : 'powershell';
+  const shellPath = String(env.SHELL || '').replace(/\\/g, '/').toLowerCase();
+  if (shellPath && /(^|\/)pwsh(\.exe)?$/.test(shellPath)) return 'pwsh';
+  if (shellPath && /(^|\/)powershell(\.exe)?$/.test(shellPath)) return 'powershell';
+  const deep = String((deepShell && deepShell.defaultShell) || '').toLowerCase();
+  if (deep.includes('pwsh')) return 'pwsh';
+  return 'powershell';
+}
 
 // 分平台深度探测：失败时降级为空对象，不中断主探测
 function runDeepProbe(platform, cwd) {
   const script = DEEP_SCRIPTS[platform] || DEEP_SCRIPTS.unix;
-  if (platform === 'win32') {
-    return runDeepScript('powershell.exe', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', script], cwd);
-  }
-  return runDeepScript('/bin/sh', [script], cwd);
+  if (platform !== 'win32') return runDeepScript('/bin/sh', [script], cwd);
+  const args = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', script];
+  const pwshPath = findToolPath('pwsh');
+  const preferred = resolveShellVariant(platform, process.env, {}) === 'pwsh' && pwshPath ? pwshPath : 'powershell.exe';
+  return runDeepScript(preferred, args, cwd).then((result) => {
+    if (Object.keys(result).length > 0) return result;
+    // 首选失败：若有 pwsh 且首选不是 pwsh，用 pwsh 重试一次；仍失败则降级
+    if (!pwshPath || preferred === pwshPath) return result;
+    console.warn('[pwsh-guide] powershell.exe 深度探测失败，改用 pwsh 重试...');
+    return runDeepScript(pwshPath, args, cwd);
+  });
 }
 
 function runDeepScript(file, args, cwd) {
@@ -131,20 +169,22 @@ function runDeepScript(file, args, cwd) {
   });
 }
 
-// 工具探测：PATH 遍历 + 版本命令，全部容错
+// 工具探测：PATH 遍历 + 版本命令，全部容错；版本探测并行执行，整体耗时受单工具超时上限约束
 async function probeTools() {
-  const results = [];
+  const paths = new Map();
   for (const name of TOOL_NAMES) {
     const toolPath = findToolPath(name);
-    if (!toolPath) {
-      results.push({ name, version: null, source: null });
-      continue;
-    }
-    const rawVersion = await runVersionCommand(toolPath);
-    const version = isPlausibleVersion(rawVersion) ? rawVersion : null;
-    results.push({ name, version, source: toolPath });
+    if (toolPath) paths.set(name, toolPath);
   }
-  return results;
+  const entries = await Promise.all(
+    [...paths.entries()].map(async ([name, toolPath]) => {
+      const rawVersion = await runVersionCommand(toolPath);
+      return { name, version: isPlausibleVersion(rawVersion) ? rawVersion : null, source: toolPath };
+    })
+  );
+  const byName = new Map(entries.map((entry) => [entry.name, entry]));
+  // 保持 TOOL_NAMES 顺序输出，缺失工具 version 为 null
+  return TOOL_NAMES.map((name) => byName.get(name) ?? { name, version: null, source: null });
 }
 
 function findToolPath(name) {
@@ -196,16 +236,30 @@ function runVersionCommand(toolPath) {
   });
 }
 
-// 项目上下文：全部 Node fs 实现
-function probeProject(cwd) {
+// 项目上下文：全部 Node fs 实现；以项目根（git 根 ?? 当前目录）为基准
+// 可选参数 projectRoot 仅供测试注入项目根
+export function probeProject(cwd, projectRoot) {
+  const root = projectRoot ?? findProjectRoot(cwd);
+  const rootSubdirs = readSubdirs(root);
   const subdirs = readSubdirs(cwd);
+  const venv = findVenv(root) ?? findVenv(cwd);
+  const packageScripts = readPackageScripts(root);
+  const cwdScripts = readPackageScripts(cwd);
+  const cwdHasOwn = cwd !== root && Object.keys(cwdScripts).length > 0;
+  const makefile = readMakefile(root);
   return {
     cwd,
+    projectRoot: root,
     gitRoot: findGitRoot(cwd),
-    markers: findMarkers(cwd, subdirs),
-    venv: findVenv(cwd),
-    packageScripts: readPackageScripts(cwd),
-    subdirs,
+    markers: findMarkers(root, rootSubdirs),
+    venv,
+    packageScripts,
+    cwdPackageScripts: cwdHasOwn ? cwdScripts : {},
+    packageManager: inferPackageManager(root),
+    makefile: makefile ? { file: makefile.file, targets: makefile.targets } : null,
+    compose: findFirst(root, COMPOSE_NAMES) ? { file: findFirst(root, COMPOSE_NAMES) } : null,
+    readme: findFirst(root, README_NAMES) ? { file: findFirst(root, README_NAMES) } : null,
+    subdirs: rootSubdirs.length ? rootSubdirs : subdirs,
   };
 }
 
@@ -220,24 +274,24 @@ function readSubdirs(cwd) {
   }
 }
 
-function findMarkers(cwd, subdirs) {
+function findMarkers(root, subdirs) {
   const found = [];
   const scope = ['.', ...subdirs];
   for (const marker of MARKER_NAMES) {
     for (const dir of scope) {
-      const target = dir === '.' ? path.join(cwd, marker) : path.join(cwd, dir, marker);
+      const target = dir === '.' ? path.join(root, marker) : path.join(root, dir, marker);
       if (fs.existsSync(target)) {
         found.push(dir === '.' ? marker : path.join(dir, marker));
-        break; // 每个 marker 只记录一次（优先当前目录）
+        break; // 每个 marker 只记录一次（优先项目根）
       }
     }
   }
   return found;
 }
 
-function findVenv(cwd) {
-  for (const dir of ['.venv', 'venv']) {
-    if (fs.existsSync(path.join(cwd, dir, 'pyvenv.cfg'))) return dir;
+function findVenv(dir) {
+  for (const name of ['.venv', 'venv']) {
+    if (fs.existsSync(path.join(dir, name, 'pyvenv.cfg'))) return name;
   }
   return null;
 }
@@ -250,4 +304,37 @@ function readPackageScripts(cwd) {
   } catch {
     return {};
   }
+}
+
+// 按 lock 文件推断推荐包管理器；多锁文件时按 LOCK_PRIORITY 取第一个命中的
+export function inferPackageManager(projectRoot) {
+  for (const [lock, pm] of LOCK_PRIORITY) {
+    if (fs.existsSync(path.join(projectRoot, lock))) return pm;
+  }
+  return null;
+}
+
+function readMakefile(dir) {
+  for (const name of MAKEFILE_NAMES) {
+    const file = path.join(dir, name);
+    if (!fs.existsSync(file)) continue;
+    const targets = [];
+    try {
+      const text = fs.readFileSync(file, 'utf8');
+      for (const line of text.split(/\r?\n/)) {
+        const match = line.match(/^([A-Za-z0-9_.-]+)\s*:/);
+        if (match && !MAKEFILE_PSEUDO.has(match[1])) targets.push(match[1]);
+        if (targets.length >= MAKEFILE_MAX_TARGETS) break;
+      }
+    } catch { /* 读取失败时返回空目标 */ }
+    return { file: name, targets };
+  }
+  return null;
+}
+
+function findFirst(dir, names) {
+  for (const name of names) {
+    if (fs.existsSync(path.join(dir, name))) return name;
+  }
+  return null;
 }

package/src/render.js

@@ -10,9 +10,12 @@ const TEMPLATES_DIR = path.resolve(__dirname, '..', 'templates');
 
 const SKILL_TEMPLATES = {
   powershell: path.join(TEMPLATES_DIR, 'SKILL.powershell.md'),
+  pwsh: path.join(TEMPLATES_DIR, 'SKILL.pwsh.md'),
   unix: path.join(TEMPLATES_DIR, 'SKILL.unix.md'),
 };
 
+const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf8'));
+
 const templateCache = new Map();
 
 function loadTemplate(key) {
@@ -26,6 +29,12 @@ function resolveFamily(env) {
   return env.family === 'unix' ? 'unix' : 'powershell';
 }
 
+// Windows 上按 shell 变体选模板：pwsh -> SKILL.pwsh.md，否则 -> SKILL.powershell.md
+function resolveTemplateKey(env) {
+  if (env.family === 'unix') return 'unix';
+  return (env.shell && env.shell.variant) === 'pwsh' ? 'pwsh' : 'powershell';
+}
+
 function fill(template, values) {
   let out = template;
   const placeholderRe = /\{\{([a-zA-Z0-9_]+)\}\}/g;
@@ -60,10 +69,16 @@ function localeSummary(env) {
   return parts.length ? parts.join(', ') : '未获取';
 }
 
+function langValue(env) {
+  const l = (env.shell && env.shell.locale) || {};
+  return l.LANG || l.LC_ALL || '未获取';
+}
+
 function projectContextBlock(env) {
   const p = env.project || {};
   const lines = [];
   lines.push(`- 当前目录：\`${p.cwd || '未知'}\``);
+  lines.push(`- 项目根：\`${p.projectRoot || '未知'}\``);
   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(', ') : '未发现';
@@ -72,32 +87,135 @@ function projectContextBlock(env) {
     ? Object.entries(p.packageScripts).map(([k, v]) => `${k}: ${v}`).join('；')
     : '未发现 package.json scripts';
   lines.push(`- package.json scripts：${scripts}`);
+  lines.push(`- 推荐包管理器：${p.packageManager || '未推断'}`);
+  const extras = [];
+  if (p.readme) extras.push(`README: ${p.readme.file}`);
+  if (p.makefile) extras.push(`Makefile: ${p.makefile.file}（${p.makefile.targets.length ? p.makefile.targets.join(', ') : '无目标'}）`);
+  if (p.compose) extras.push(`Compose: ${p.compose.file}`);
+  if (extras.length) lines.push(`- 其它：${extras.join('；')}`);
   const subdirs = p.subdirs && p.subdirs.length ? p.subdirs.join(', ') : '（空）';
-  lines.push(`- 第一层子目录：${subdirs}`);
+  lines.push(`- 项目根第一层子目录：${subdirs}`);
+  return lines.join('\n');
+}
+
+// 项目命令：直接给出本项目"怎么装、怎么跑、怎么测"的推荐命令
+function renderProjectCommands(env) {
+  const p = env.project || {};
+  const pm = p.packageManager;
+  const scripts = p.packageScripts || {};
+  const scriptNames = Object.keys(scripts);
+  const lines = [];
+  const push = (s) => lines.push(`- ${s}`);
+
+  if (pm === 'uv') {
+    push(`推荐包管理器：\`uv\`（检测到 uv.lock）`);
+    push(`安装依赖：\`uv sync\``);
+    push(`在项目环境中运行：\`uv run <cmd>\``);
+    push(`添加依赖：\`uv add <pkg>\``);
+  } else if (pm === 'pnpm') {
+    push(`推荐包管理器：\`pnpm\`（检测到 pnpm-lock.yaml）`);
+    push(`安装依赖：\`pnpm install\``);
+  } else if (pm === 'yarn') {
+    push(`推荐包管理器：\`yarn\`（检测到 yarn.lock）`);
+    push(`安装依赖：\`yarn install\``);
+  } else if (pm === 'bun') {
+    push(`推荐包管理器：\`bun\`（检测到 bun.lockb / bun.lock）`);
+    push(`安装依赖：\`bun install\``);
+  } else if (pm === 'npm' || (scriptNames.length > 0 && !pm)) {
+    push(`包管理器：\`npm\``);
+    push(`安装依赖：\`npm install\``);
+  }
+
+  if (scriptNames.length > 0) {
+    const runner = ['pnpm', 'yarn', 'bun'].includes(pm) ? pm : 'npm';
+    const labels = { dev: '开发', test: '测试', build: '构建', start: '启动', lint: 'Lint', typecheck: '类型检查' };
+    const interesting = scriptNames.filter((name) => ['dev', 'test', 'build', 'start', 'lint', 'typecheck'].includes(name));
+    const names = interesting.length > 0 ? interesting : scriptNames.slice(0, 6);
+    for (const name of names) {
+      const label = labels[name] || '运行';
+      const cmd = name === 'test' ? `${runner} test` : `${runner} run ${name}`;
+      push(`${label}：\`${cmd}\``);
+    }
+  }
+
+  if (p.venv) {
+    const sep = p.venv === 'venv' ? 'venv' : '.venv';
+    push(`Python venv：\`${p.venv}\`；Windows 激活 \`.\\${sep}\\Scripts\\Activate.ps1\`，Unix 激活 \`source ${sep}/bin/activate\``);
+  }
+
+  if (p.makefile && p.makefile.targets.length > 0) {
+    push(`Makefile 目标（${p.makefile.file}）：${p.makefile.targets.join(', ')}`);
+  }
+
+  if (p.compose) {
+    push(`Docker Compose：\`docker compose -f ${p.compose.file} up -d\``);
+  }
+
+  if (p.readme) {
+    push(`动手前先读 \`${p.readme.file}\` 了解结构与约定`);
+  }
+
+  if (lines.length === 0) {
+    lines.push('未探测到可推导的项目命令；先读 README / AGENTS.md 确认项目结构再操作。');
+  }
+  return lines.join('\n');
+}
+
+// 代码库检索指引：rg 可用时优先 rg，否则用平台原生搜索
+function renderSearchGuide(env) {
+  const family = resolveFamily(env);
+  const rg = getTool(env, 'rg');
+  const lines = [];
+  if (rg && rg.version) {
+    lines.push('- 定位定义/引用：`rg -n \'<pattern>\' <dir>`；列文件：`rg --files <dir>`');
+    lines.push('- 排除噪音目录：`rg --glob \'!node_modules/**\' --glob \'!.git/**\' \'<pattern>\'`');
+  } else if (family === 'powershell') {
+    lines.push('- 文本搜索：`Get-ChildItem -Recurse -File | Select-String -Pattern \'<pattern>\'`（范围大时先限定 `-Path` 子目录）');
+    lines.push('- 列文件：`Get-ChildItem -Recurse -File | Where-Object { $_.Name -like \'<pattern>\' }`');
+  } else {
+    lines.push('- 文本搜索：`grep -rn \'<pattern>\' <dir>`；排除噪音：`grep -rn --exclude-dir=node_modules --exclude-dir=.git \'<pattern>\' .`');
+  }
+  lines.push(family === 'powershell'
+    ? '- 先读文件再修改：`Get-Content -Path \'<file>\' -Encoding UTF8`'
+    : '- 先读文件再修改：`cat <file>`');
   return lines.join('\n');
 }
 
 export function renderSkill(env) {
+  const tplKey = resolveTemplateKey(env);
   const family = resolveFamily(env);
   const shell = env.shell || {};
   const os = env.os || {};
+  const pwshTool = getTool(env, 'pwsh');
+  const pwshVersion = (pwshTool && pwshTool.version) || '未知';
+  const ps51Installed = Boolean(shell.psVersion && /^5\./.test(shell.psVersion));
   const values = {
     generatedAt: new Date().toISOString(),
+    generatorVersion: pkg.version,
     osVersion: `${os.platform || ''} ${os.release || ''}`.trim() || '未知',
     shellName: shell.defaultShellName || shell.defaultShell || (family === 'powershell' ? 'powershell' : 'sh'),
     psVersion: shell.psVersion || '未知',
+    pwshVersion,
     consoleOutputEncoding: shell.consoleOutputEncoding || '未知',
     chcp: shell.chcp ?? '未知',
     executionPolicySummary: executionPolicySummary(env),
-    pwsh7Note: shell.pwsh7Available ? '已检测到 pwsh 7，需要时可优先使用 `pwsh`（语法兼容、性能更好）。' : '',
+    pwsh7Note: shell.pwsh7Available
+      ? `本机也装有 pwsh ${pwshVersion === '未知' ? '7' : pwshVersion}（PowerShell 7）。如实际执行环境是 pwsh：\`&&\`/\`??\` 等新语法可用、中文参数默认 UTF-8 不乱码，可优先使用 \`pwsh\`。`
+      : '',
+    ps51Note: (shell.ps51Available || ps51Installed)
+      ? '本机也装有 Windows PowerShell 5.1（powershell.exe）。若实际执行环境是 powershell.exe：`&&`/`??` 等新语法不可用、`$OutputEncoding` 默认非 UTF-8（中文参数需先设置）。'
+      : '',
     localeSummary: localeSummary(env),
+    langValue: langValue(env),
     fishNote: shell.defaultShellName === 'fish' ? '注意：默认 shell 是 fish，语法与 bash/zsh 不同（本文以 bash/zsh 为主）。' : '',
     gitRoot: (env.project && env.project.gitRoot) || '未发现 .git',
     cwd: (env.project && env.project.cwd) || process.cwd(),
     toolsSummary: toolsSummary(env),
     projectContext: projectContextBlock(env),
+    projectCommands: renderProjectCommands(env),
+    searchGuide: renderSearchGuide(env),
   };
-  return fill(loadTemplate(family), values);
+  return fill(loadTemplate(tplKey), values);
 }
 
 function renderEnvironment(env) {
@@ -105,10 +223,11 @@ function renderEnvironment(env) {
   const shell = env.shell || {};
   const os = env.os || {};
   const p = env.project || {};
+  const pwshTool = getTool(env, 'pwsh');
   const lines = [];
   lines.push('# 环境事实（pwsh-guide 探测结果）');
   lines.push('');
-  lines.push('> 本文件由 pwsh-guide 生成；环境变化后运行 `pwsh-guide refresh` 更新。');
+  lines.push('> 本文件由 pwsh-guide 生成；环境变化后运行 `pwsh-guide refresh` 更新，运行 `pwsh-guide check` 检测漂移。');
   lines.push('');
   lines.push('## Shell 环境');
   lines.push('');
@@ -117,10 +236,12 @@ function renderEnvironment(env) {
   if (family === 'powershell') {
     lines.push(`| OS | ${os.release ?? '-'} |`);
     lines.push(`| 默认 shell | ${shell.defaultShell ?? '-'} |`);
+    lines.push(`| shell 变体 | ${shell.variant === 'pwsh' ? 'pwsh（PowerShell 7）' : shell.variant === 'powershell' ? 'powershell.exe（Windows PowerShell 5.1）' : '-'} |`);
     lines.push(`| PowerShell 版本 | ${shell.psVersion ?? '-'} |`);
     lines.push(`| PSEdition | ${shell.psEdition ?? '-'} |`);
     lines.push(`| 主机 | ${shell.hostName ?? '-'} |`);
     lines.push(`| pwsh 7 可用 | ${shell.pwsh7Available ? '是' : '否'} |`);
+    lines.push(`| pwsh 7 版本 | ${(pwshTool && pwshTool.version) ?? '-'} |`);
     lines.push(`| 控制台输出编码 | ${shell.consoleOutputEncoding ?? '-'} |`);
     lines.push(`| $OutputEncoding | ${shell.outputEncoding ?? '-'} |`);
     lines.push(`| 代码页 chcp | ${shell.chcp ?? '-'} |`);
@@ -155,21 +276,30 @@ function renderEnvironment(env) {
   lines.push('| 项 | 值 |');
   lines.push('| --- | --- |');
   lines.push(`| 当前目录 | ${p.cwd ?? '-'} |`);
+  lines.push(`| 项目根 | ${p.projectRoot ?? '-'} |`);
   lines.push(`| git 仓库根 | ${p.gitRoot ?? '未发现 .git'} |`);
   lines.push(`| venv | ${p.venv ?? '未发现'} |`);
   lines.push(`| 标记文件 | ${p.markers && p.markers.length ? p.markers.join(', ') : '未发现'} |`);
+  lines.push(`| 推荐包管理器 | ${p.packageManager ?? '未推断'} |`);
   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(', ') : '-'} |`);
+  const cwdScriptsText = p.cwdPackageScripts && Object.keys(p.cwdPackageScripts).length
+    ? Object.entries(p.cwdPackageScripts).map(([k, v]) => `${k}: ${v}`).join('<br>')
+    : '-';
+  lines.push(`| 当前目录 scripts | ${cwdScriptsText} |`);
+  lines.push(`| README | ${p.readme ? p.readme.file : '未发现'} |`);
+  lines.push(`| Makefile | ${p.makefile ? `${p.makefile.file}（目标：${p.makefile.targets.join(', ')}）` : '未发现'} |`);
+  lines.push(`| Docker Compose | ${p.compose ? p.compose.file : '未发现'} |`);
+  lines.push(`| 项目根第一层子目录 | ${p.subdirs && p.subdirs.length ? p.subdirs.join(', ') : '-'} |`);
   return `${lines.join('\n')}\n`;
 }
 
 const COMMON_COMMANDS_POWERSHELL = [
   '- 列出目录：`Get-ChildItem -Path . -Force`',
   '- 递归查找文件：`Get-ChildItem -Recurse -Filter \'*.py\'`',
-  '- 文本搜索：`Select-String -Path \'**\\*.py\' -Pattern \'关键词\'`',
+  '- 文本搜索：`Get-ChildItem -Recurse -Filter \'*.py\' | Select-String -Pattern \'关键词\'`',
   '- 读文件：`Get-Content -Path \'<file>\' -Encoding UTF8`',
   '- 写文件：`Set-Content -Path \'<file>\' -Value \'<text>\' -Encoding UTF8`',
   '- 判断路径存在：`Test-Path \'<path>\'`',
@@ -253,7 +383,7 @@ const TOOL_COMMANDS = {
     '- 容器列表：`docker ps`',
   ],
   make: [
-    '- 查看可用目标：`make -n` 或 `make help`',
+    '- 查看目标：`make help`（若定义）或读取 Makefile',
     '- 执行目标：`make <target>`',
   ],
   rg: [
@@ -265,7 +395,7 @@ const TOOL_COMMANDS = {
     '- 创建 PR：`gh pr create`',
   ],
   pwsh: [
-    '- 版本：`pwsh -Version`',
+    '- 版本：`pwsh --version`',
     '- 运行脚本：`pwsh -File <script>.ps1`',
   ],
   cargo: [
@@ -285,6 +415,7 @@ function renderCommands(env) {
   lines.push('# 命令模板（按工具）');
   lines.push('');
   lines.push('> 仅列出探测到可用的工具；`<...>` 为占位参数，执行前替换。');
+  lines.push('> 本文件为通用模板，未逐条在本机实测；复杂场景执行前先 `--help` 确认参数，破坏性操作先 `-WhatIf` 或展示计划。');
   lines.push('');
   lines.push(family === 'unix' ? '## 通用操作（bash/zsh）' : '## 通用操作（PowerShell 原生，始终可用）');
   for (const c of common) lines.push(c);

package/templates/SKILL.powershell.md

@@ -1,11 +1,11 @@
 ---
 name: pwsh-guide
-description: 本项目的 PowerShell 命令执行指南。需要执行 shell 命令、遇到 PowerShell 报错、中文乱码或不确定命令语法时使用；含本机环境事实、命令模板与失败诊断。
+description: 本项目的 PowerShell（Windows PowerShell 5.1）命令执行指南。需要执行 shell 命令、遇到 PowerShell 报错、中文乱码或不确定命令语法时使用；含本机环境事实、命令模板、快速自检与失败诊断。
 ---
 
-# PowerShell 操作指南（本环境）
+# PowerShell 操作指南（本环境 · Windows PowerShell 5.1）
 
-> 由 `pwsh-guide` 生成于 {{generatedAt}}。环境变化后运行 `pwsh-guide refresh` 更新。
+> 由 `pwsh-guide v{{generatorVersion}}` 生成于 {{generatedAt}}。环境变化后运行 `pwsh-guide refresh` 更新；`pwsh-guide check` 可检测环境漂移。
 
 ## 1. 执行命令前先确认
 
@@ -24,6 +24,9 @@ description: 本项目的 PowerShell 命令执行指南。需要执行 shell 命
 4. 环境变量读取 `$env:NAME`，写入 `$env:NAME = 'value'`（仅当前会话）。
 5. 只读操作优先；删除等危险操作先 `-WhatIf` 或展示计划再执行。
 6. 长命令优先写成 `.ps1` 再以 `-File` 执行，避免内联引号地狱。
+7. 含中文参数的原生命令（git/node/npm 等）先按第 4 节设置输入编码。
+8. 传参用具名参数或变量 splatting：先 `$h = @{ ... }` 再 `命令 @h`；**禁止 `命令 @{ ... }`**（内联 splatting 不生效，会把 hashtable 当普通参数）。
+9. 含特殊字符（引号/逗号/中文）的参数：禁止内联拼接进 `-Command "..."` 字符串（会被拆碎）；改用 `.ps1` 脚本 `param()`、环境变量或参数数组传递。
 
 ## 3. 常用命令模板
 
@@ -33,8 +36,10 @@ description: 本项目的 PowerShell 命令执行指南。需要执行 shell 命
 
 ## 4. 编码与乱码处理
 
-- 临时切 UTF-8 输出：`[Console]::OutputEncoding = [System.Text.Encoding]::UTF8`。
-- 切换代码页：`chcp 65001`（UTF-8）。
+- 输出乱码：`[Console]::OutputEncoding = [System.Text.Encoding]::UTF8`；切换代码页 `chcp 65001`。
+- **输入乱码（中文参数）**：`$OutputEncoding` 默认是 us-ascii，原生命令收到的中文参数会乱码。含中文参数的命令须在同一命令内先设置：
+  `[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; $OutputEncoding = [System.Text.Encoding]::UTF8; <cmd>`
+- 写 `.ps1` 时在文件头部设置一次上述两行。
 - 写文件指定编码：`Set-Content -Path <file> -Value <text> -Encoding UTF8`（PS 5.1 会写 BOM）。
 - 读文件乱码：`Get-Content -Path <file> -Encoding UTF8`。
 - 重定向中文输出优先 `Out-File -Encoding UTF8`，避免 `>` 按控制台编码写出。
@@ -44,19 +49,38 @@ description: 本项目的 PowerShell 命令执行指南。需要执行 shell 命
 | 症状 | 常见原因 | 处理 |
 | --- | --- | --- |
 | 命令找不到 | PATH 缺失 / 拼写错 | `Get-Command <name>` 确认；查看 `references/environment.md` 工具表 |
-| 中文乱码 | 代码页与输出编码不匹配 | 按第 4 节切换 UTF-8 |
+| 中文乱码 | 代码页与输出编码不匹配 | 按第 4 节切换 UTF-8（含 $OutputEncoding 输入侧） |
 | 引号/转义报错 | 内联 `-Command` 引号地狱 | 改用 `-File` 脚本或参数数组 |
+| 参数被拆分/丢失 | 特殊字符内联拼接进 `-Command` | 改用 `.ps1` 脚本 `param()` / 环境变量 / 参数数组 |
+| 参数收到 Hashtable | 误用内联 splatting `命令 @{...}` | 先存变量 `$h = @{...}` 再 `命令 @h` |
 | 权限拒绝 | 执行策略 / ACL | `Get-ExecutionPolicy -List`；脚本加 `-ExecutionPolicy Bypass` |
 | 路径找不到 | 空格/中文/反斜杠 | 单引号包裹；先 `Test-Path` |
 | 程序假死 | 交互式命令等待输入 | 加 `-NonInteractive`，或 `echo y | <cmd>` |
+| npm/网络报错 | registry/代理/锁文件不匹配 | `npm config get registry`、`npm ping`；确认包管理器与锁文件一致 |
+| 端口被占用 | 端口冲突 | `Get-NetTCPConnection -LocalPort <port>` 找 PID，确认后 `Stop-Process -Id <pid> -Force` |
+| git 凭据弹窗 | 需要认证 | 先确认凭据；必要时 `$env:GIT_TERMINAL_PROMPT = '0'` 避免挂起 |
 
-## 6. 禁止事项
+## 6. 快速自检（环境是否已变化）
 
-- 禁止 bash 语法：`ls -la`、`grep`、`cat`、`rm -rf`、`export`、`&&`/`||`。
-- 删除一律用 `Remove-Item -Path <path> -Recurse -Force`，且先确认路径再执行。
-- 未读文件内容不得修改；不得批量格式化无关代码。
-- 仓库 AGENTS.md 规则优先于本文件。
+- 复核 shell：`$PSVersionTable.PSVersion.ToString()` 应为 `{{psVersion}}`；`chcp` 应为 `{{chcp}}`。
+- 复核工具：逐一运行第 3 节每个工具的 `--version`，输出应与列出的版本一致。
+- 规则：任一自检项与期望不符，或同一命令连续失败两次，先运行 `npx pwsh-guide refresh` 并重读本文件，不要继续猜测。
+
+## 7. 代码库检索指引
+
+{{searchGuide}}
+
+## 8. 项目上下文（来自探测）
 
-## 7. 项目上下文（来自探测）
+{{projectContext}}
 
-{{projectContext}}
+## 9. 项目命令（推荐）
+
+{{projectCommands}}
+
+## 10. 禁止事项
+
+- 禁止 bash 语法：`ls -la`、`grep`、`cat`、`rm -rf`、`export`、`dir`、`copy`。
+- 删除一律用 `Remove-Item -Path <path> -Recurse -Force`，且先确认路径再执行。
+- 未读文件内容不得修改；不得批量格式化无关代码。
+- 仓库 AGENTS.md 规则优先于本文件。

package/templates/SKILL.pwsh.md

@@ -0,0 +1,91 @@
+---
+name: pwsh-guide
+description: 本项目的 PowerShell（pwsh 7）命令执行指南。需要执行 shell 命令、遇到 PowerShell 报错、中文乱码或不确定命令语法时使用；含本机环境事实、命令模板、快速自检与失败诊断。
+---
+
+# PowerShell 操作指南（本环境 · pwsh 7）
+
+> 由 `pwsh-guide v{{generatorVersion}}` 生成于 {{generatedAt}}。环境变化后运行 `pwsh-guide refresh` 更新；`pwsh-guide check` 可检测环境漂移。
+
+## 1. 执行命令前先确认
+
+- 默认 shell 是 `{{shellName}}`（pwsh {{psVersion}}），**不是 bash/cmd**：禁止 `ls -la`、`grep`、`cat`、`rm -rf`、`export`、`dir`、`copy`。
+- OS：{{osVersion}}。{{ps51Note}}
+- 编码：`$OutputEncoding` 与 `[Console]::OutputEncoding` 均为 UTF-8，中文参数/输出一般不会乱码（代码页 chcp {{chcp}}）。
+- 执行策略：{{executionPolicySummary}}。
+- 当前目录：`{{cwd}}`；git 根：`{{gitRoot}}`。
+- 完整环境事实见 `references/environment.md`；可用命令模板见 `references/commands.md`。
+
+## 2. 命令执行铁律
+
+1. 一条命令一次执行；pwsh 7 支持 `&&`/`||`，但链式出错时难以定位，仍建议一次一条。
+2. 执行后检查退出状态：外部命令看 `$LASTEXITCODE`，cmdlet 看 `$?`，并查看 stderr。
+3. 路径含空格或中文时用单引号包裹：`Get-Content 'E:\path with 中文\file.txt'`。
+4. 环境变量读取 `$env:NAME`，写入 `$env:NAME = 'value'`（仅当前会话）。
+5. 只读操作优先；删除等危险操作先 `-WhatIf` 或展示计划再执行。
+6. 长命令优先写成 `.ps1` 再以 `pwsh -File` 执行，避免内联引号地狱。
+7. 含特殊字符（引号/逗号/中文）的参数：禁止内联拼接进 `-Command "..."` 字符串（会被拆碎）；改用 `.ps1` 脚本 `param()`、环境变量或参数数组传递。
+8. 传参用具名参数或变量 splatting：先 `$h = @{ ... }` 再 `命令 @h`；**禁止 `命令 @{ ... }`**（内联 splatting 不生效，会把 hashtable 当普通参数）。
+
+## 3. 常用命令模板
+
+可用工具与命令见 `references/commands.md`。本机探测到的工具：
+
+{{toolsSummary}}
+
+## 4. 编码与乱码处理
+
+- pwsh 7 默认 UTF-8：`$OutputEncoding` 与 `[Console]::OutputEncoding` 均为 UTF-8，中文一般不会乱码。
+- 写文件指定编码：`Set-Content -Path <file> -Value <text> -Encoding utf8`（pwsh 7 写 UTF-8 无 BOM）；`Out-File -Encoding utf8` 同理。
+- 读文件乱码：`Get-Content -Path <file> -Encoding UTF8`。
+- 读 GBK 旧文件：`[System.IO.File]::ReadAllText('<file>', [System.Text.Encoding]::GetEncoding('GBK'))`。
+- 仍乱码时：确认 `[Console]::OutputEncoding.WebName` 为 `utf-8`；必要时 `chcp 65001`。
+
+## 5. 失败分类诊断
+
+| 症状 | 常见原因 | 处理 |
+| --- | --- | --- |
+| 命令找不到 | PATH 缺失 / 拼写错 | `Get-Command <name>` 确认；查看 `references/environment.md` 工具表 |
+| 中文乱码 | 代码页与输出编码不匹配 | 按第 4 节处理（pwsh 默认 UTF-8，一般不会出现） |
+| 引号/转义报错 | 内联 `-Command` 引号地狱 | 改用 `-File` 脚本或参数数组 |
+| 参数被拆分/丢失 | 特殊字符内联拼接进 `-Command` | 改用 `.ps1` 脚本 `param()` / 环境变量 / 参数数组 |
+| 参数收到 Hashtable | 误用内联 splatting `命令 @{...}` | 先存变量 `$h = @{...}` 再 `命令 @h` |
+| 新语法报错 | 实际 shell 是 powershell.exe 5.1 | `&&`/`??`/三元仅在 pwsh 7 可用；确认实际执行 shell |
+| 权限拒绝 | 执行策略 / ACL | `Get-ExecutionPolicy -List`；脚本加 `-ExecutionPolicy Bypass` |
+| 路径找不到 | 空格/中文/反斜杠 | 单引号包裹；先 `Test-Path` |
+| 程序假死 | 交互式命令等待输入 | 加 `-NonInteractive`，或 `echo y | <cmd>` |
+| npm/网络报错 | registry/代理/锁文件不匹配 | `npm config get registry`、`npm ping`；确认包管理器与锁文件一致 |
+| 端口被占用 | 端口冲突 | `Get-NetTCPConnection -LocalPort <port>` 找 PID，确认后 `Stop-Process -Id <pid> -Force` |
+| git 凭据弹窗 | 需要认证 | 先确认凭据；必要时 `$env:GIT_TERMINAL_PROMPT = '0'` 避免挂起 |
+
+## 6. 快速自检（环境是否已变化）
+
+- 复核 shell：`pwsh --version` 应为 `{{pwshVersion}}`；`$OutputEncoding.WebName` 应为 `utf-8`。
+- 复核工具：逐一运行第 3 节每个工具的 `--version`，输出应与列出的版本一致。
+- 规则：任一自检项与期望不符，或同一命令连续失败两次，先运行 `npx pwsh-guide refresh` 并重读本文件，不要继续猜测。
+
+## 7. 代码库检索指引
+
+{{searchGuide}}
+
+## 8. 项目上下文（来自探测）
+
+{{projectContext}}
+
+## 9. 项目命令（推荐）
+
+{{projectCommands}}
+
+## 10. pwsh 7 特性（与 powershell.exe 5.1 的差异）
+
+- `&&`/`||`、空合并 `??`、三元 `?:`、`Get-Content -Raw` 等新语法仅 pwsh 7 可用（5.1 会报错）。
+- 并行：`1..10 | ForEach-Object -Parallel { <块> } -ThrottleLimit 4`；块内用 `$using:变量` 读外部变量，输出顺序不保证。
+- JSON：`Get-Content -Raw -Encoding utf8 | ConvertFrom-Json -AsHashtable`（保留键大小写）。
+- 原生命令非 0 退出触发错误处理：`$PSNativeCommandUseErrorActionPreference = $true`（谨慎使用，会影响所有原生命令）。
+
+## 11. 禁止事项
+
+- 禁止 bash 语法：`ls -la`、`grep`、`cat`、`rm -rf`、`export`、`dir`、`copy`。
+- 删除一律用 `Remove-Item -Path <path> -Recurse -Force`，且先确认路径再执行。
+- 未读文件内容不得修改；不得批量格式化无关代码。
+- 仓库 AGENTS.md 规则优先于本文件。

package/templates/SKILL.unix.md

@@ -1,11 +1,11 @@
 ---
 name: pwsh-guide
-description: 本项目的 Unix shell（bash/zsh）命令执行指南。需要执行 shell 命令、遇到 shell 报错、编码问题或不确定命令语法时使用；含本机环境事实、命令模板与失败诊断。
+description: 本项目的 Unix shell（bash/zsh）命令执行指南。需要执行 shell 命令、遇到 shell 报错、编码问题或不确定命令语法时使用；含本机环境事实、命令模板、快速自检与失败诊断。
 ---
 
 # Shell 操作指南（本环境）
 
-> 由 `pwsh-guide` 生成于 {{generatedAt}}。环境变化后运行 `pwsh-guide refresh` 更新。
+> 由 `pwsh-guide v{{generatorVersion}}` 生成于 {{generatedAt}}。环境变化后运行 `pwsh-guide refresh` 更新；`pwsh-guide check` 可检测环境漂移。
 
 ## 1. 执行命令前先确认
 
@@ -45,14 +45,31 @@ description: 本项目的 Unix shell（bash/zsh）命令执行指南。需要执
 | 引号/转义报错 | 嵌套引号 | 用单引号或写成脚本文件 |
 | 中文乱码 | locale 非 UTF-8 | 按第 4 节处理 |
 | 程序假死 | 交互式命令等待输入 | 加非交互参数，或 `< /dev/null` |
+| npm/网络报错 | registry/代理/锁文件不匹配 | `npm config get registry`、`npm ping`；确认包管理器与锁文件一致 |
+| 端口被占用 | 端口冲突 | `lsof -i :<port>` 找 PID，确认后 `kill <pid>` |
+| git 凭据弹窗 | 需要认证 | 先确认凭据；必要时 `GIT_TERMINAL_PROMPT=0` 避免挂起 |
 
-## 6. 禁止事项
+## 6. 快速自检（环境是否已变化）
+
+- 复核 shell：`echo $SHELL` 应为 `{{shellName}}`；`echo $LANG` 应为 `{{langValue}}`。
+- 复核工具：逐一运行第 3 节每个工具的 `--version`，输出应与列出的版本一致。
+- 规则：任一自检项与期望不符，或同一命令连续失败两次，先运行 `npx pwsh-guide refresh` 并重读本文件，不要继续猜测。
+
+## 7. 代码库检索指引
+
+{{searchGuide}}
+
+## 8. 项目上下文（来自探测）
+
+{{projectContext}}
+
+## 9. 项目命令（推荐）
+
+{{projectCommands}}
+
+## 10. 禁止事项
 
 - 禁止 PowerShell/cmd 语法：`Get-ChildItem`、`Get-Content`、`Set-Content`、`dir`、`copy`、`$env:`。
 - `rm -rf` 前必须确认路径；删除操作先展示计划。
 - 未读文件内容不得修改；不得批量格式化无关代码。
-- 仓库 AGENTS.md 规则优先于本文件。
-
-## 7. 项目上下文（来自探测）
-
-{{projectContext}}
+- 仓库 AGENTS.md 规则优先于本文件。