pwsh-guide 0.2.1 → 0.3.0

package/README.md

@@ -1,32 +1,43 @@
 # 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 再继续，不再用过期的指南。
+
 - 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` 漂移检测的基准）
 
 ## 探测内容（只读）
 
@@ -34,25 +45,28 @@ npx pwsh-guide --version
 - shell（按平台深度探测）：
   - Windows：PowerShell 版本 / PSEdition / 控制台输出编码 / `$OutputEncoding` / chcp / 执行策略 / pwsh 7 可用性
   - 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                  仓库根判定与目标目录解析
+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.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         重新探测并更新 references（SKILL.md 保持不变）
+  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,29 +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(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。');
+}
 
-  if (command === 'init') {
-    fs.writeFileSync(path.join(skillDir, 'SKILL.md'), renderSkill(env), 'utf8');
-    console.log(`[pwsh-guide] 已生成 ${path.join(skillDir, 'SKILL.md')}`);
+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);
   }
-  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/）。');
+  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.1",
+  "version": "0.3.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/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,124 @@
+// 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,
+      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],
+    ['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));
 }
@@ -131,20 +148,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 +215,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 +253,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 +283,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

@@ -13,6 +13,8 @@ const SKILL_TEMPLATES = {
   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) {
@@ -60,10 +62,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,8 +80,97 @@ 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');
 }
 
@@ -83,6 +180,7 @@ export function renderSkill(env) {
   const os = env.os || {};
   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 || '未知',
@@ -91,11 +189,14 @@ export function renderSkill(env) {
     executionPolicySummary: executionPolicySummary(env),
     pwsh7Note: shell.pwsh7Available ? '已检测到 pwsh 7，需要时可优先使用 `pwsh`（语法兼容、性能更好）。' : '',
     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);
 }
@@ -108,7 +209,7 @@ function renderEnvironment(env) {
   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('');
@@ -155,21 +256,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 +363,7 @@ const TOOL_COMMANDS = {
     '- 容器列表：`docker ps`',
   ],
   make: [
-    '- 查看可用目标：`make -n` 或 `make help`',
+    '- 查看目标：`make help`（若定义）或读取 Makefile',
     '- 执行目标：`make <target>`',
   ],
   rg: [
@@ -265,7 +375,7 @@ const TOOL_COMMANDS = {
     '- 创建 PR：`gh pr create`',
   ],
   pwsh: [
-    '- 版本：`pwsh -Version`',
+    '- 版本：`pwsh --version`',
     '- 运行脚本：`pwsh -File <script>.ps1`',
   ],
   cargo: [
@@ -285,6 +395,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 命令执行指南。需要执行 shell 命令、遇到 PowerShell 报错、中文乱码或不确定命令语法时使用；含本机环境事实、命令模板、快速自检与失败诊断。
 ---
 
 # PowerShell 操作指南（本环境）
 
-> 由 `pwsh-guide` 生成于 {{generatedAt}}。环境变化后运行 `pwsh-guide refresh` 更新。
+> 由 `pwsh-guide v{{generatorVersion}}` 生成于 {{generatedAt}}。环境变化后运行 `pwsh-guide refresh` 更新；`pwsh-guide check` 可检测环境漂移。
 
 ## 1. 执行命令前先确认
 
@@ -24,6 +24,7 @@ description: 本项目的 PowerShell 命令执行指南。需要执行 shell 命
 4. 环境变量读取 `$env:NAME`，写入 `$env:NAME = 'value'`（仅当前会话）。
 5. 只读操作优先；删除等危险操作先 `-WhatIf` 或展示计划再执行。
 6. 长命令优先写成 `.ps1` 再以 `-File` 执行，避免内联引号地狱。
+7. 含中文参数的原生命令（git/node/npm 等）先按第 4 节设置输入编码。
 
 ## 3. 常用命令模板
 
@@ -33,8 +34,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 +47,36 @@ description: 本项目的 PowerShell 命令执行指南。需要执行 shell 命
 | 症状 | 常见原因 | 处理 |
 | --- | --- | --- |
 | 命令找不到 | PATH 缺失 / 拼写错 | `Get-Command <name>` 确认；查看 `references/environment.md` 工具表 |
-| 中文乱码 | 代码页与输出编码不匹配 | 按第 4 节切换 UTF-8 |
+| 中文乱码 | 代码页与输出编码不匹配 | 按第 4 节切换 UTF-8（含 $OutputEncoding 输入侧） |
 | 引号/转义报错 | 内联 `-Command` 引号地狱 | 改用 `-File` 脚本或参数数组 |
 | 权限拒绝 | 执行策略 / 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. 快速自检（环境是否已变化）
+
+- 复核 shell：`$PSVersionTable.PSVersion.ToString()` 应为 `{{psVersion}}`；`chcp` 应为 `{{chcp}}`。
+- 复核工具：逐一运行第 3 节每个工具的 `--version`，输出应与列出的版本一致。
+- 规则：任一自检项与期望不符，或同一命令连续失败两次，先运行 `npx pwsh-guide refresh` 并重读本文件，不要继续猜测。
+
+## 7. 代码库检索指引
+
+{{searchGuide}}
+
+## 8. 项目上下文（来自探测）
+
+{{projectContext}}
+
+## 9. 项目命令（推荐）
+
+{{projectCommands}}
+
+## 10. 禁止事项
 
 - 禁止 bash 语法：`ls -la`、`grep`、`cat`、`rm -rf`、`export`、`&&`/`||`。
 - 删除一律用 `Remove-Item -Path <path> -Recurse -Force`，且先确认路径再执行。
 - 未读文件内容不得修改；不得批量格式化无关代码。
-- 仓库 AGENTS.md 规则优先于本文件。
-
-## 7. 项目上下文（来自探测）
-
-{{projectContext}}
+- 仓库 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 规则优先于本文件。