| 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
相关资源
本技能包含以下辅助资源：
templates/terminal-local-template.md：.terminal.local.md 输出格式模板，步骤 5 写入文件时必须参照此模板
