pwsh-guide 0.1.0 → 0.2.0

package/README.md

@@ -1,47 +1,56 @@
 # pwsh-guide
 
-生成项目级 Agent Skill：探测当前 Windows/PowerShell 环境与本项目上下文，产出可靠的命令使用指南（`SKILL.md` + `references/`），供 Codex、Claude Code 等代理自动读取，减少命令失败、乱码与反复试错。
+生成项目级 Agent Skill：跨平台探测当前环境（Windows PowerShell / macOS / Linux shell）与本项目上下文，产出可靠的命令使用指南（`SKILL.md` + `references/`），供 Codex、Claude Code 等代理自动读取，减少命令失败、乱码与反复试错。
 
 ## 原理
 
-AI 代理在 Windows + PowerShell 下执行命令失败，本质是"生成即采样"：模型先验以 bash 为主、缺少本机环境事实。`pwsh-guide` 把环境探测结果固化进 skill 的 references（惰性加载、不占上下文），并用命令铁律 + 失败诊断约束生成空间。
+AI 代理执行命令失败，本质是"生成即采样"：模型先验以 bash 为主、缺少本机环境事实。`pwsh-guide` 把环境探测结果固化进 skill 的 references（惰性加载、不占上下文），并用命令铁律 + 失败诊断约束生成空间。
 
-## 安装（本地开发）
+- Windows 下生成 PowerShell 指南；macOS/Linux 下生成 bash/zsh 指南（只生成当前环境可用内容，省 token）
+- 平台无关探测全部用 Node 原生实现（`os` / `process.env` / `fs`），不依赖特定 shell
 
-```powershell
-npm link
-```
-
-## 用法
+## 安装与使用
 
-```powershell
-# 在任意项目根目录运行
-pwsh-guide init             # 探测并生成 .agents/skills/pwsh-guide/
-pwsh-guide refresh          # 环境变化后重新探测，更新 references
-pwsh-guide init --dry-run   # 只输出探测 JSON，不写文件
+```bash
+# 项目根目录运行（npx 方式，无需全局安装）
+npx pwsh-guide init
+# 环境变化后更新
+npx pwsh-guide refresh
+# 只输出探测 JSON，不写文件
+npx pwsh-guide init --dry-run
 ```
 
 生成的 skill 位于 `.agents/skills/pwsh-guide/`：
 
 - `SKILL.md`：命令执行铁律、编码与乱码处理、失败分类诊断、禁止事项
-- `references/environment.md`：探测到的本机环境事实（PS 版本/编码/执行策略/工具/项目上下文）
+- `references/environment.md`：探测到的本机环境事实（shell 版本/编码/locale/工具/项目上下文）
 - `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 的可用性与版本
+- 平台与 OS：`os.platform()` / `os.release()` / `os.arch()` / 主机名 / 用户与临时目录
+- 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、第一层子目录
 
 ## 开发
 
 ```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 填充）
+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
+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 模板
 ```
 
-变更记录由 OpenSpec 管理（`openspec/`），当前变更：`add-pwsh-guide`。
+变更记录由 OpenSpec 管理（`openspec/`）：当前变更 `add-pwsh-guide`（已发布 v0.1.0）、`cross-platform-0.2`（进行中）。
+
+## 验证范围
+
+- Windows：本机实测（探测 JSON / init / refresh）
+- macOS/Linux：静态审查（POSIX sh 脚本与 Node 分支），尚未真机运行

package/bin/pwsh-guide.js

@@ -8,7 +8,7 @@ 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
+const USAGE = `pwsh-guide - 生成项目级 Shell 操作指南 Agent Skill（跨平台：Windows PowerShell / macOS / Linux）
 
 用法:
   pwsh-guide init            探测环境并在 .agents/skills/pwsh-guide/ 生成 skill
@@ -79,4 +79,4 @@ async function main() {
 main().catch((err) => {
   console.error(`[pwsh-guide] 失败: ${err.message}`);
   process.exit(1);
-});
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "0.2.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": {
     "pwsh-guide": "bin/pwsh-guide.js"
@@ -21,9 +21,13 @@
   "keywords": [
     "agent-skills",
     "powershell",
+    "bash",
+    "shell",
     "windows",
+    "macos",
+    "linux",
     "codex",
     "claude-code"
   ],
   "license": "MIT"
-}
+}

package/scripts/probe.unix.sh

@@ -0,0 +1,56 @@
+#!/bin/sh
+# probe.unix.sh - pwsh-guide Unix 深度探测脚本（只读，不修改任何文件或系统设置）
+# 用法：sh probe.unix.sh
+# 输出：UTF-8 JSON 到 stdout（shell 深度字段，供 src/probe.js 合并）
+# 兼容：POSIX sh（macOS / Linux）
+
+# JSON 字符串转义（最小实现）
+json_escape() {
+  printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'
+}
+
+# locale 单项取值：优先 locale 命令，缺失时回退环境变量
+get_locale() {
+  key="$1"
+  value=$(locale 2>/dev/null | sed -n "s/^$key=//p" | tr -d '"')
+  if [ -z "$value" ]; then
+    case "$key" in
+      LANG) value="$LANG" ;;
+      LC_ALL) value="$LC_ALL" ;;
+      LC_CTYPE) value="$LC_CTYPE" ;;
+    esac
+  fi
+  printf '%s' "$value"
+}
+
+# 查找 shell 路径；找不到输出空
+shell_path() {
+  command -v "$1" 2>/dev/null || printf ''
+}
+
+default_shell="${SHELL:-/bin/sh}"
+temp_dir="${TMPDIR:-/tmp}"
+
+# WSL 标注：uname -r 含 microsoft
+wsl=no
+uname_r=$(uname -r 2>/dev/null || printf '')
+case "$uname_r" in
+  *[Mm]icrosoft*) wsl=yes ;;
+esac
+
+cat <<EOF
+{
+  "defaultShell": "$(json_escape "$default_shell")",
+  "bash": "$(shell_path bash)",
+  "zsh": "$(shell_path zsh)",
+  "fish": "$(shell_path fish)",
+  "locale": {
+    "LANG": "$(json_escape "$(get_locale LANG)")",
+    "LC_ALL": "$(json_escape "$(get_locale LC_ALL)")",
+    "LC_CTYPE": "$(json_escape "$(get_locale LC_CTYPE)")"
+  },
+  "userProfile": "$(json_escape "$HOME")",
+  "tempDir": "$(json_escape "$temp_dir")",
+  "wsl": "$wsl"
+}
+EOF

package/scripts/probe.windows.ps1

@@ -0,0 +1,33 @@
+# probe.windows.ps1 - pwsh-guide Windows 深度探测脚本（只读，不修改任何文件或系统设置）
+# 用法：powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File probe.windows.ps1
+# 输出：UTF-8 JSON 到 stdout（shell 深度字段，供 src/probe.js 合并）
+# 兼容：Windows PowerShell 5.1+（不使用 PS7 新语法：??、&&、三元等）
+
+$originalConsoleEncoding = [Console]::OutputEncoding.WebName
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+$ErrorActionPreference = 'Continue'
+
+$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 }
+
+$result = [pscustomobject]@{
+    defaultShell = 'powershell.exe'
+    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
+}
+$result | ConvertTo-Json -Depth 5

package/src/detect.js

@@ -1,19 +1,23 @@
 // detect.js - 仓库根判定与 skill 目标目录解析
-// 用法：findProjectRoot(cwd) -> string；resolveSkillDir(cwd) -> string
+// 用法：findGitRoot(cwd) -> string|null；findProjectRoot(cwd) -> string；resolveSkillDir(cwd) -> string
 import fs from 'node:fs';
 import path from 'node:path';
 
-export function findProjectRoot(startDir) {
+export function findGitRoot(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，降级为当前目录
+    if (parent === dir) return null; // 找不到 .git
     dir = parent;
   }
 }
 
+export function findProjectRoot(startDir) {
+  return findGitRoot(startDir) ?? path.resolve(startDir); // 找不到 .git，降级为当前目录
+}
+
 export function resolveSkillDir(cwd) {
   return path.join(findProjectRoot(cwd), '.agents', 'skills', 'pwsh-guide');
 }

package/src/probe.js

@@ -1,41 +1,236 @@
-// probe.js - 调用 scripts/probe.ps1 探测环境并解析 JSON
+// probe.js - 跨平台环境主探测（Node 原生，零 shell 依赖）
 // 用法：probeEnvironment(cwd) -> Promise<object>
-import { spawn } from 'node:child_process';
+// 平台无关信息（platform/os/default shell/tools/project）由 Node 原生探测；
+// 平台深度信息（PS 版本表、locale 等）由分平台脚本补充（Windows powershell.exe / Unix /bin/sh）。
+import os from 'node:os';
+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';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const PROBE_SCRIPT = path.resolve(__dirname, '..', 'scripts', 'probe.ps1');
+const SCRIPTS_DIR = path.resolve(__dirname, '..', 'scripts');
+
+const DEEP_SCRIPTS = {
+  win32: path.join(SCRIPTS_DIR, 'probe.windows.ps1'),
+  unix: path.join(SCRIPTS_DIR, 'probe.unix.sh'),
+};
+
+const TOOL_NAMES = [
+  'git', 'node', 'npm', 'npx', 'pnpm', 'yarn', 'bun',
+  'python', 'py', 'uv', 'pip', 'docker', 'make', 'rg', 'gh', 'pwsh', 'cargo', 'go',
+];
+
+const MARKER_NAMES = [
+  'package.json', 'pyproject.toml', 'requirements.txt', 'uv.lock',
+  'go.mod', 'Cargo.toml', 'pnpm-lock.yaml', 'yarn.lock', 'Dockerfile',
+];
+
+const IGNORED_SUBDIRS = new Set(['.git', '.venv', 'venv', 'node_modules']);
+const VERSION_TIMEOUT_MS = 5000;
 
 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 });
+  const platform = process.platform; // 'win32' | 'darwin' | 'linux'（其它平台按 unix 处理）
+  const family = platform === 'win32' ? 'powershell' : 'unix';
+
+  const [deepShell, tools, project] = await Promise.all([
+    runDeepProbe(platform, cwd),
+    probeTools(),
+    probeProject(cwd),
+  ]);
+
+  const defaultShell = resolveDefaultShell(platform, deepShell);
+
+  return {
+    schemaVersion: 2,
+    platform,
+    family,
+    os: {
+      platform,
+      release: os.release(),
+      arch: os.arch(),
+      hostname: os.hostname(),
+      homeDir: os.homedir(),
+      tmpDir: os.tmpdir(),
+    },
+    shell: {
+      family,
+      defaultShell,
+      defaultShellName: defaultShell.split(/[\\/]/).pop().toLowerCase(),
+      ...deepShell,
+    },
+    tools,
+    project,
+  };
+}
+
+function resolveDefaultShell(platform, deepShell) {
+  if (deepShell && deepShell.defaultShell) return deepShell.defaultShell;
+  if (platform === 'win32') return 'powershell.exe';
+  return process.env.SHELL || '/bin/sh';
+}
+
+// 分平台深度探测：失败时降级为空对象，不中断主探测
+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);
+}
+
+function runDeepScript(file, args, cwd) {
+  return new Promise((resolve) => {
+    const child = spawn(file, 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('error', (err) => {
+      console.warn(`[pwsh-guide] 深度探测脚本无法启动（${file}）：${err.message}`);
+      resolve({});
+    });
     child.on('close', (code) => {
       if (code !== 0) {
-        reject(new Error(`probe.ps1 退出码 ${code}: ${stderr.trim()}`));
+        console.warn(`[pwsh-guide] 深度探测脚本退出码 ${code}：${stderr.trim() || stdout.trim()}`);
+        resolve({});
         return;
       }
       const jsonStart = stdout.indexOf('{');
       if (jsonStart === -1) {
-        reject(new Error(`探测输出不含 JSON:\n${stdout}\n${stderr}`));
+        console.warn('[pwsh-guide] 深度探测脚本未输出 JSON，已降级');
+        resolve({});
         return;
       }
       try {
         resolve(JSON.parse(stdout.slice(jsonStart)));
       } catch (err) {
-        reject(new Error(`解析探测 JSON 失败: ${err.message}`));
+        console.warn(`[pwsh-guide] 深度探测 JSON 解析失败：${err.message}`);
+        resolve({});
       }
     });
   });
 }
+
+// 工具探测：PATH 遍历 + 版本命令，全部容错
+async function probeTools() {
+  const results = [];
+  for (const name of TOOL_NAMES) {
+    const toolPath = findToolPath(name);
+    if (!toolPath) {
+      results.push({ name, version: null, source: null });
+      continue;
+    }
+    const version = await runVersionCommand(toolPath);
+    results.push({ name, version, source: toolPath });
+  }
+  return results;
+}
+
+function findToolPath(name) {
+  const exts = toolExtensions();
+  const dirs = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = path.join(dir, name + ext);
+      try {
+        if (fs.statSync(candidate).isFile()) return candidate;
+      } catch { /* 继续查找 */ }
+    }
+  }
+  return null;
+}
+
+function toolExtensions() {
+  if (process.platform !== 'win32') return [''];
+  return (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD')
+    .split(';').map((e) => e.trim().toLowerCase()).filter(Boolean);
+}
+
+function runVersionCommand(toolPath) {
+  return new Promise((resolve) => {
+    let file;
+    let args;
+    let options = { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true };
+    if (process.platform === 'win32' && /\.(cmd|bat)$/i.test(toolPath)) {
+      // .cmd/.bat 需经 cmd.exe 执行；shell:true 时命令串内的引号不被 Node 转义，可正确处理带空格/中文路径
+      file = `"${toolPath}" --version`;
+      options = { ...options, shell: true };
+    } else {
+      file = toolPath;
+      args = ['--version'];
+    }
+    const child = spawn(file, args, options);
+    let out = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => { out += chunk; });
+    child.stderr.on('data', (chunk) => { out += chunk; });
+    const timer = setTimeout(() => { child.kill(); resolve(null); }, VERSION_TIMEOUT_MS);
+    child.on('error', () => { clearTimeout(timer); resolve(null); });
+    child.on('close', () => {
+      clearTimeout(timer);
+      const line = out.split(/\r?\n/).map((s) => s.trim()).find((s) => s.length > 0);
+      resolve(line ?? null);
+    });
+  });
+}
+
+// 项目上下文：全部 Node fs 实现
+function probeProject(cwd) {
+  const subdirs = readSubdirs(cwd);
+  return {
+    cwd,
+    gitRoot: findGitRoot(cwd),
+    markers: findMarkers(cwd, subdirs),
+    venv: findVenv(cwd),
+    packageScripts: readPackageScripts(cwd),
+    subdirs,
+  };
+}
+
+function readSubdirs(cwd) {
+  try {
+    return fs.readdirSync(cwd, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && !IGNORED_SUBDIRS.has(entry.name))
+      .map((entry) => entry.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+function findMarkers(cwd, 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);
+      if (fs.existsSync(target)) {
+        found.push(dir === '.' ? marker : path.join(dir, 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;
+  }
+  return null;
+}
+
+function readPackageScripts(cwd) {
+  const pkgPath = path.join(cwd, 'package.json');
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    return pkg.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
+  } catch {
+    return {};
+  }
+}

package/src/render.js

@@ -1,16 +1,36 @@
 // render.js - 将探测 JSON 渲染为 SKILL.md / references/environment.md / references/commands.md
 // 用法：renderSkill(env)、renderEnvironment(env)、renderCommands(env)
+// env.family 与 env.shell.family：'powershell' | 'unix'（由 src/probe.js 探测）
 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');
+const TEMPLATES_DIR = path.resolve(__dirname, '..', 'templates');
+
+const SKILL_TEMPLATES = {
+  powershell: path.join(TEMPLATES_DIR, 'SKILL.powershell.md'),
+  unix: path.join(TEMPLATES_DIR, 'SKILL.unix.md'),
+};
+
+const templateCache = new Map();
+
+function loadTemplate(key) {
+  if (!templateCache.has(key)) {
+    templateCache.set(key, fs.readFileSync(SKILL_TEMPLATES[key], 'utf8'));
+  }
+  return templateCache.get(key);
+}
+
+function resolveFamily(env) {
+  return env.family === 'unix' ? 'unix' : 'powershell';
+}
 
 function fill(template, values) {
   let out = template;
-  for (const [key, value] of Object.entries(values)) {
-    out = out.split(`{{${key}}}`).join(String(value));
+  const placeholderRe = /\{\{([a-zA-Z0-9_]+)\}\}/g;
+  for (const match of template.matchAll(placeholderRe)) {
+    out = out.split(`{{${match[1]}}}`).join(String(values[match[1]] ?? ''));
   }
   return out;
 }
@@ -19,11 +39,6 @@ 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。';
@@ -36,6 +51,15 @@ function executionPolicySummary(env) {
   return parts.length ? parts.join(', ') : '未获取';
 }
 
+function localeSummary(env) {
+  const l = (env.shell && env.shell.locale) || {};
+  const parts = [];
+  for (const key of ['LANG', 'LC_ALL', 'LC_CTYPE']) {
+    if (l[key]) parts.push(`${key}=${l[key]}`);
+  }
+  return parts.length ? parts.join(', ') : '未获取';
+}
+
 function projectContextBlock(env) {
   const p = env.project || {};
   const lines = [];
@@ -54,22 +78,32 @@ function projectContextBlock(env) {
 }
 
 export function renderSkill(env) {
+  const family = resolveFamily(env);
   const shell = env.shell || {};
-  return fill(TEMPLATE, {
+  const os = env.os || {};
+  const values = {
     generatedAt: new Date().toISOString(),
+    osVersion: `${os.platform || ''} ${os.release || ''}`.trim() || '未知',
+    shellName: shell.defaultShellName || shell.defaultShell || (family === 'powershell' ? 'powershell' : 'sh'),
     psVersion: shell.psVersion || '未知',
     consoleOutputEncoding: shell.consoleOutputEncoding || '未知',
     chcp: shell.chcp ?? '未知',
     executionPolicySummary: executionPolicySummary(env),
+    pwsh7Note: shell.pwsh7Available ? '已检测到 pwsh 7，需要时可优先使用 `pwsh`（语法兼容、性能更好）。' : '',
+    localeSummary: localeSummary(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),
-  });
+  };
+  return fill(loadTemplate(family), values);
 }
 
 function renderEnvironment(env) {
+  const family = resolveFamily(env);
   const shell = env.shell || {};
+  const os = env.os || {};
   const p = env.project || {};
   const lines = [];
   lines.push('# 环境事实（pwsh-guide 探测结果）');
@@ -80,17 +114,28 @@ function renderEnvironment(env) {
   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 ?? '-'} |`);
+  if (family === 'powershell') {
+    lines.push(`| OS | ${os.release ?? '-'} |`);
+    lines.push(`| 默认 shell | ${shell.defaultShell ?? '-'} |`);
+    lines.push(`| PowerShell 版本 | ${shell.psVersion ?? '-'} |`);
+    lines.push(`| PSEdition | ${shell.psEdition ?? '-'} |`);
+    lines.push(`| 主机 | ${shell.hostName ?? '-'} |`);
+    lines.push(`| pwsh 7 可用 | ${shell.pwsh7Available ? '是' : '否'} |`);
+    lines.push(`| 控制台输出编码 | ${shell.consoleOutputEncoding ?? '-'} |`);
+    lines.push(`| $OutputEncoding | ${shell.outputEncoding ?? '-'} |`);
+    lines.push(`| 代码页 chcp | ${shell.chcp ?? '-'} |`);
+    lines.push(`| 执行策略 | ${executionPolicySummary(env)} |`);
+  } else {
+    lines.push(`| OS | ${os.release ?? '-'} |`);
+    lines.push(`| 默认 shell | ${shell.defaultShell ?? '-'} |`);
+    lines.push(`| bash | ${shell.bash ? `\`${shell.bash}\`` : '-'} |`);
+    lines.push(`| zsh | ${shell.zsh ? `\`${shell.zsh}\`` : '-'} |`);
+    lines.push(`| fish | ${shell.fish ? `\`${shell.fish}\`` : '-'} |`);
+    lines.push(`| locale | ${localeSummary(env)} |`);
+    lines.push(`| WSL | ${String(shell.wsl).toLowerCase() === 'yes' ? '是' : '否'} |`);
+  }
+  lines.push(`| 用户目录 | ${shell.userProfile || os.homeDir || '-'} |`);
+  lines.push(`| 临时目录 | ${shell.tempDir || os.tmpDir || '-'} |`);
   lines.push('');
   lines.push('## 可用工具');
   lines.push('');
@@ -121,7 +166,7 @@ function renderEnvironment(env) {
   return `${lines.join('\n')}\n`;
 }
 
-const COMMON_COMMANDS = [
+const COMMON_COMMANDS_POWERSHELL = [
   '- 列出目录：`Get-ChildItem -Path . -Force`',
   '- 递归查找文件：`Get-ChildItem -Recurse -Filter \'*.py\'`',
   '- 文本搜索：`Select-String -Path \'**\\*.py\' -Pattern \'关键词\'`',
@@ -133,6 +178,18 @@ const COMMON_COMMANDS = [
   '- 端口占用：`Get-NetTCPConnection -LocalPort <port>`',
 ];
 
+const COMMON_COMMANDS_UNIX = [
+  '- 列出目录：`ls -la`；目录树：`find . -maxdepth 2 -type d`',
+  '- 递归查找文件：`find . -type f -name \'*.py\'`',
+  '- 文本搜索：`rg \'<pattern>\' <path>`（rg 可用时），否则 `grep -rn \'<pattern>\' <path>`',
+  '- 读文件：`cat <file>`；分页：`less <file>`',
+  '- 写文件：`cat > <file> <<\'EOF\'` 多行写入；追加：`cat >> <file> <<\'EOF\'`',
+  '- 判断路径存在：`test -e <path>`；文件判断：`[ -f <path> ]`',
+  '- 环境变量读：`echo $NAME`；写：`export NAME=\'value\'`（仅当前会话）',
+  '- 进程列表：`ps aux | grep <name>`；结束：`kill <pid>`',
+  '- 端口占用：`lsof -i :<port>`（macOS/Linux）或 `ss -tlnp | grep <port>`',
+];
+
 const TOOL_ORDER = [
   'git', 'node', 'npm', 'npx', 'pnpm', 'yarn', 'bun',
   'python', 'py', 'uv', 'pip', 'docker', 'make', 'rg', 'gh', 'pwsh', 'cargo', 'go',
@@ -222,13 +279,15 @@ const TOOL_COMMANDS = {
 };
 
 function renderCommands(env) {
+  const family = resolveFamily(env);
+  const common = family === 'unix' ? COMMON_COMMANDS_UNIX : COMMON_COMMANDS_POWERSHELL;
   const lines = [];
   lines.push('# 命令模板（按工具）');
   lines.push('');
   lines.push('> 仅列出探测到可用的工具；`<...>` 为占位参数，执行前替换。');
   lines.push('');
-  lines.push('## 通用操作（PowerShell 原生，始终可用）');
-  for (const c of COMMON_COMMANDS) lines.push(c);
+  lines.push(family === 'unix' ? '## 通用操作（bash/zsh）' : '## 通用操作（PowerShell 原生，始终可用）');
+  for (const c of common) lines.push(c);
   lines.push('');
   for (const tool of TOOL_ORDER) {
     const info = getTool(env, tool);
@@ -239,7 +298,7 @@ function renderCommands(env) {
     for (const c of cmds) lines.push(c);
     lines.push('');
   }
-  return `${lines.join('\n')}`;
+  return lines.join('\n');
 }
 
-export { renderEnvironment, renderCommands };
+export { renderEnvironment, renderCommands };

package/templates/{SKILL.md → SKILL.powershell.md}

@@ -1,15 +1,16 @@
 ---
 name: pwsh-guide
-description: 本项目的 Windows PowerShell/cmd 命令执行指南。需要执行 shell 命令、遇到 PowerShell 报错、中文乱码或不确定命令语法时使用；含本机环境事实、命令模板与失败诊断。
+description: 本项目的 PowerShell 命令执行指南。需要执行 shell 命令、遇到 PowerShell 报错、中文乱码或不确定命令语法时使用；含本机环境事实、命令模板与失败诊断。
 ---
 
-# PowerShell/cmd 操作指南（本环境）
+# PowerShell 操作指南（本环境）
 
 > 由 `pwsh-guide` 生成于 {{generatedAt}}。环境变化后运行 `pwsh-guide refresh` 更新。
 
 ## 1. 执行命令前先确认
 
-- Shell 是 `powershell.exe`（PS {{psVersion}}），**不是 bash**：禁止 `ls -la`、`grep`、`cat`、`rm -rf`、`export`。
+- 默认 shell 是 `{{shellName}}`（PS {{psVersion}}），**不是 bash/cmd**：禁止 `ls -la`、`grep`、`cat`、`rm -rf`、`export`、`dir`、`copy`。
+- OS：{{osVersion}}。{{pwsh7Note}}
 - 控制台输出编码：{{consoleOutputEncoding}}（代码页 chcp {{chcp}}）。
 - 执行策略：{{executionPolicySummary}}。
 - 当前目录：`{{cwd}}`；git 根：`{{gitRoot}}`。
@@ -17,7 +18,7 @@ description: 本项目的 Windows PowerShell/cmd 命令执行指南。需要执
 
 ## 2. 命令执行铁律
 
-1. 一条命令一次执行；禁止 `&&`、`||`、`;` 链式（PowerShell 5.1 不支持 `&&`）。
+1. 一条命令一次执行；禁止 `&&`、`||`、`;` 链式（Windows PowerShell 5.1 不支持 `&&`）。
 2. 执行后检查退出状态：外部命令看 `$LASTEXITCODE`，cmdlet 看 `$?`，并查看 stderr。
 3. 路径含空格或中文时用单引号包裹：`Get-Content 'E:\path with 中文\file.txt'`。
 4. 环境变量读取 `$env:NAME`，写入 `$env:NAME = 'value'`（仅当前会话）。
@@ -58,4 +59,4 @@ description: 本项目的 Windows PowerShell/cmd 命令执行指南。需要执
 
 ## 7. 项目上下文（来自探测）
 
-{{projectContext}}
+{{projectContext}}

package/templates/SKILL.unix.md

@@ -0,0 +1,58 @@
+---
+name: pwsh-guide
+description: 本项目的 Unix shell（bash/zsh）命令执行指南。需要执行 shell 命令、遇到 shell 报错、编码问题或不确定命令语法时使用；含本机环境事实、命令模板与失败诊断。
+---
+
+# Shell 操作指南（本环境）
+
+> 由 `pwsh-guide` 生成于 {{generatedAt}}。环境变化后运行 `pwsh-guide refresh` 更新。
+
+## 1. 执行命令前先确认
+
+- 默认 shell 是 `{{shellName}}`，**不是 PowerShell/cmd**：禁止 `Get-ChildItem`、`Get-Content`、`Set-Content`、`dir`、`copy`、`$env:`。
+- OS：{{osVersion}}。{{fishNote}}
+- locale：{{localeSummary}}（非 UTF-8 时中文可能乱码）。
+- 当前目录：`{{cwd}}`；git 根：`{{gitRoot}}`。
+- 完整环境事实见 `references/environment.md`；可用命令模板见 `references/commands.md`。
+
+## 2. 命令执行铁律
+
+1. 一条命令一次执行；避免 `&&`/`||` 链式（出错时难以定位）。
+2. 执行后检查退出码 `$?` 与 stderr。
+3. 路径含空格时用引号包裹：`cat 'path with space/file.txt'`。
+4. 环境变量读取 `echo $NAME`，写入 `export NAME='value'`（仅当前会话）。
+5. 只读操作优先；删除等危险操作先展示计划再执行，`rm` 谨慎使用。
+6. 长命令优先写成脚本文件（`.sh`）再 `bash <script>` 执行，避免内联引号地狱。
+
+## 3. 常用命令模板
+
+可用工具与命令见 `references/commands.md`。本机探测到的工具：
+
+{{toolsSummary}}
+
+## 4. 编码处理
+
+- 确认 locale：`locale`；乱码排查：`echo $LANG` 应含 `UTF-8`。
+- 文件编码转换：`iconv -f GBK -t UTF-8 <input> > <output>`。
+- 终端乱码时先切 UTF-8：`export LANG=C.UTF-8`（仅当前会话）。
+
+## 5. 失败分类诊断
+
+| 症状 | 常见原因 | 处理 |
+| --- | --- | --- |
+| command not found | PATH 缺失 / 拼写错 | `command -v <name>` 确认；查看 `references/environment.md` 工具表 |
+| Permission denied | 无执行权限 | `chmod +x <file>`；需要 sudo 时先说明原因 |
+| 引号/转义报错 | 嵌套引号 | 用单引号或写成脚本文件 |
+| 中文乱码 | locale 非 UTF-8 | 按第 4 节处理 |
+| 程序假死 | 交互式命令等待输入 | 加非交互参数，或 `< /dev/null` |
+
+## 6. 禁止事项
+
+- 禁止 PowerShell/cmd 语法：`Get-ChildItem`、`Get-Content`、`Set-Content`、`dir`、`copy`、`$env:`。
+- `rm -rf` 前必须确认路径；删除操作先展示计划。
+- 未读文件内容不得修改；不得批量格式化无关代码。
+- 仓库 AGENTS.md 规则优先于本文件。
+
+## 7. 项目上下文（来自探测）
+
+{{projectContext}}

package/scripts/probe.ps1

@@ -1,107 +0,0 @@
-# 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