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