| 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 写入文件时必须参照此模板