# Yy Detect Terminal

> 识别并记录本地终端命令能力。用于创建或更新项目根目录 .terminal.local.md，或在执行终端命令前确认 shell、命令可用性和搜索命令； 不用于执行 lint、测试、构建、部署等业务命令。

- Skill: `bulls-cows/yy-detect-terminal` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add bulls-cows/yy-detect-terminal`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bulls-cows/yy-detect-terminal/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bulls-cows (https://skillmd.com/u/bulls-cows)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bulls-cows/yy-detect-terminal

---


# yy-detect-terminal

## 描述

识别当前环境可用的终端启动入口、命令判断方式、搜索工具和常用运行时，并将已验证结果记录到项目根目录 `.terminal.local.md`，供后续 AI 会话优先复用。

## 使用场景

- 用户要求创建或更新 `.terminal.local.md`
- 用户要求识别终端命令能力、shell 能力或本地命令可用性
- 项目规范要求执行终端命令前先读取或确认终端能力
- 已有 `.terminal.local.md` 与实际执行结果不一致，需要重新识别并修正

不应触发：

- 用户只是询问某个命令的用法，不需要记录本地终端能力
- 用户要求执行 lint、测试、构建、部署等业务命令
- 用户要求创建普通项目文档，且内容与终端能力记录无关

## 指令

### 步骤 1. 定位项目根目录

确定需要写入 `.terminal.local.md` 的项目根目录。

**决策分支**：

- **用户指定项目目录**：使用用户指定目录作为项目根目录
- **用户未指定项目目录**：使用当前工作目录作为项目根目录
- **当前目录明显位于子目录中**：向上查找包含 `package.json`、`.git`、`AGENTS.md` 或同类项目标识的目录，并将最接近当前任务的目录作为项目根目录
- **无法判断项目根目录**：先向用户确认目标目录，不直接写入文件

### 步骤 2. 读取现有记录

检查项目根目录下是否存在 `.terminal.local.md`。

**读取方式**：

- 优先使用 `node` 进程读取 `.terminal.local.md` 文件内容，不通过 shell 包装
- 若 `node` 读取不可用，则使用 Agent 原生文件读取能力
- 只有 `node` 读取与原生读取均不可用时，才按固定优先级执行最小 shell 读取探测
- 启动读取阶段只用于判断文件是否存在并读取内容，不代表终端能力结论

**决策分支**：

- **文件存在且有内容**：先读取记录，将其中的 shell 启动入口、命令可用性和命令写法作为候选信息，但不得直接视为已验证结论
- **文件不存在或内容为空**：进入步骤 3，执行本地能力识别
- **文件记录与实际执行结果冲突**：以实际识别结果为准，并在步骤 5 更新文件

**验证要求**：

- 已有记录只能作为候选来源，仍需对记录中的首选 shell、备用 shell 和不可用 shell 重新执行最小验证
- 只有完成步骤 3 的候选枚举和启动验证后，才能确定首选 shell、备用 shell 和不可用 shell

### 步骤 3. 识别 shell 启动入口

按固定优先级识别当前环境可调用的 shell 启动入口，优先级为 `bash`、`pwsh`、`powershell.exe`、`powershell`、`cmd.exe`。

**候选枚举规则**：

- 必须完整枚举上述候选列表，不得因为当前命令通过 `cmd.exe`、`bash` 或其他低优先级 shell 成功执行就停止识别
- 如果当前检测入口是低优先级 shell，仍需继续检查优先级更高的候选，例如从 `cmd.exe` 中使用 `where pwsh` 并尝试启动 `pwsh`
- 不可用 shell 只能记录已经完成存在性判断和启动验证且失败的候选；无法验证的候选必须记录为待确认，不得写入不可用 shell

**首选 shell 选择规则**：

按以下两步确定首选 shell：

1. **拓扑感知选择**：确定当前"检测入口 shell"（即 AI 工具实际用于执行命令的 shell 环境，通过 `$SHELL`、`$BASH_VERSION`、`$PSVersionTable` 等进程内变量判断）。如果检测入口 shell 已通过启动验证且能力完整（具备基本文件搜索和文本搜索工具），则直接选为首选 shell。
2. **固定优先级回退**：如果检测入口 shell 未通过启动验证，或能力不完整无法作为日常使用 shell，则按固定优先级 `bash` > `pwsh` > `powershell.exe` > `powershell` > `cmd.exe` 选择第一个通过启动验证的候选。

**备用 shell 选择规则**：

- 记录除首选 shell 外其余通过启动验证的候选，按固定优先级排序
- 无备用时填写"无"

**选择理由记录**：在 `.terminal.local.md` 中记录首选 shell 的选择依据，格式为 `首选 shell 选择依据：[拓扑感知选择 / 固定优先级回退] — [简要说明]`

**验证规则**：

- PowerShell 环境优先使用 `Get-Command <name> -ErrorAction SilentlyContinue` 判断命令是否存在
- Bash 环境优先使用 `command -v <name>` 判断命令是否存在
- CMD 环境优先使用 `where <name>` 判断命令是否存在
- 存在性判断通过后，必须执行无副作用启动验证：PowerShell 使用 `Write-Output OK`，Bash 使用 `echo OK`，CMD 使用 `echo OK`
- 版本信息只能作为补充证据，不能替代启动验证
- 不直接试运行可能缺失的业务命令，只做命令存在性判断、版本读取或无副作用启动验证
- 无法确认终端类型时，使用最保守的基础命令，避免链式命令和 shell 专属语法

**防误判要求**：

- 检测入口可用只证明该入口可用，不证明优先级更高的候选不可用
- 某个 shell 的启动命令在当前工具入口中失败时，应再使用当前可用 shell 的命令存在性判断交叉确认；只有交叉确认失败后才标记不可用
- 如果存在性判断与启动验证结果冲突，记录为待确认，并在输出中说明冲突证据

### 步骤 4. 识别常用命令能力

识别并记录后续命令执行需要的最小能力集合。

**必须识别的内容**：

- 首选 shell 启动入口和可用备用 shell 启动入口
- 不可用 shell 启动入口和待确认 shell 启动入口
- 每个 shell 候选的存在性判断结果、启动验证结果和版本或兼容性信息
- 命令存在性判断方式
- 文件搜索和文本搜索工具，优先级为 `rg`、PowerShell 原生命令、Bash `find` / `grep`、CMD `dir` / `findstr`

**按需识别的内容**：

- 项目需要的运行时，如 `node`、`npm`、`python`、`git`
- 用户指定需要验证的命令
- 项目文档明确要求的工具

### 步骤 5. 创建或更新 .terminal.local.md

将识别结果写入项目根目录 `.terminal.local.md`。

**写入规则**：

- 章节顺序和字段名称必须与 `templates/terminal-local-template.md` 保持一致
- 使用 Markdown 编写，标题为 `# .terminal.local.md`
- 标明记录用途、更新时间、工作目录、当前终端能力和命令选择建议
- 明确区分首选 shell、备用 shell、不可用 shell 和待确认 shell
- 记录首选 shell 时必须使用步骤 3 中”首选 shell 选择规则”确定的结果，并在记录中说明选择依据（拓扑感知选择或固定优先级回退）
- 使用相对稳定的命令名称和路径信息，路径优先使用正斜杠
- 记录只描述本机环境，不声明适用于其他开发者环境
- 如果已有文件存在，保留仍准确的信息，更新失效或缺失的信息

### 步骤 6. 保护本地记录文件

写入 `.terminal.local.md` 后，检查目标项目是否位于 Git 仓库中，并在允许范围内避免该本地记录文件被误提交。

**仓库判断规则**：

- 从项目根目录向上查找最近的 `.git` 目录或 `.git` 文件，将其所在目录作为仓库根目录
- 未找到 `.git` 目录或 `.git` 文件时，判定目标项目不在 Git 仓库中，不修改其他文件
- 只通过文件系统判断仓库根目录，不为了该步骤执行 `git` 命令

**`.gitignore` 处理规则**：

- **仓库根目录存在 `.gitignore`**：读取文件内容，检查是否已包含输出文件的忽略项
- **忽略项已存在**：不重复添加，仅在输出中说明无需修改
- **忽略项不存在**：将输出文件相对仓库根目录的路径追加到 `.gitignore`，路径使用正斜杠
- **仓库根目录不存在 `.gitignore`**：不主动创建 `.gitignore`，仅在输出中说明未添加原因

**忽略项格式**：

- 输出文件位于仓库根目录时，使用 `.terminal.local.md`
- 输出文件位于仓库子目录时，使用相对仓库根目录的路径，如 `subdir/.terminal.local.md`

### 步骤 7. 选择后续命令写法

根据 `.terminal.local.md` 中已验证的能力选择后续终端命令写法。

**决策分支**：

- **记录中有可用首选 shell**：优先使用首选 shell 启动入口执行后续命令
- **首选 shell 执行失败**：切换到可用备用 shell，并回到步骤 3 完整枚举所有候选后更新记录
- **当前只能通过备用 shell 执行命令**：将备用 shell 作为检测入口，先验证更高优先级候选，再决定是否临时继续使用备用 shell
- **需要搜索文件或文本**：优先使用记录中可用的最高优先级搜索工具
- **命令能力未被记录**：先按步骤 4 识别，再执行依赖该能力的命令

### 步骤 8. 输出结果

输出以下内容：

1. **识别结果**：检测入口、首选 shell、备用 shell、不可用 shell、待确认 shell、可用搜索工具
2. **验证证据**：说明首选 shell 的选择依据（拓扑感知选择或固定优先级回退），以及选择理由
3. **文件状态**：`.terminal.local.md` 是新建、更新还是无需修改，`.gitignore` 是已追加、无需修改、未找到还是不适用
4. **后续命令建议**：推荐的 shell 启动入口和搜索命令写法
5. **异常说明**：如有无法确认的命令能力，明确标记待确认

## 安全边界

- 不执行 lint、测试、构建、部署、安装依赖等业务命令
- 不读取或输出密钥、令牌、私有配置等敏感内容
- 不为识别命令能力而修改 `.terminal.local.md` 以外的文件；唯一例外是目标项目位于 Git 仓库且仓库根目录已有 `.gitignore` 时，只可追加 `.terminal.local.md` 对应忽略项
- 不删除已有 `.terminal.local.md`，只在确认失效信息后更新内容
- 无法判断项目根目录时，不主动创建 `.terminal.local.md`

## 相关资源

本技能包含以下辅助资源：

- `templates/terminal-local-template.md`：`.terminal.local.md` 输出格式模板，步骤 5 写入文件时必须参照此模板