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

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。

读取方式：

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

决策分支：

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

验证要求：

已有记录只能作为候选来源，仍需对记录中的首选 shell、备用 shell 和不可用 shell 重新执行最小验证
如果当前会话只能通过某个低优先级 shell 启动命令，该 shell 只能作为检测入口，不得直接成为首选 shell
只有完成步骤 3 的候选枚举和启动验证后，才能确定首选 shell、备用 shell 和不可用 shell

步骤 3. 识别 shell 启动入口

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

候选枚举规则：

必须完整枚举上述候选列表，不得因为当前命令通过 cmd.exe、bash 或其他低优先级 shell 成功执行就停止识别
如果当前检测入口是低优先级 shell，仍需继续检查优先级更高的候选，例如从 cmd.exe 中使用 where pwsh 并尝试启动 pwsh
首选 shell 必须选择固定优先级中第一个通过启动验证的候选，而不是选择当前正在执行检测的 shell
备用 shell 按固定优先级记录其余通过启动验证的候选
不可用 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. 输出结果

输出以下内容：

识别结果：检测入口、首选 shell、备用 shell、不可用 shell、待确认 shell、可用搜索工具
验证证据：说明首选 shell 是按固定优先级完整枚举并通过启动验证后确定的
文件状态：.terminal.local.md 是新建、更新还是无需修改，.gitignore 是已追加、无需修改、未找到还是不适用
后续命令建议：推荐的 shell 启动入口和搜索命令写法
异常说明：如有无法确认的命令能力，明确标记待确认

安全边界

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

yy-detect-terminal