ln-005-environment-scanner

路径： 文件路径（shared/、references/、../ln-*）相对于 skills 仓库根目录。如果在当前工作目录中找不到，请定位此 SKILL.md 所在目录，并向上一级找到仓库根目录。

环境扫描器（独立实用工具）

类型： 独立实用工具 类别： 0XX 共享

探测 CLI Agent（Codex、Gemini）并写入 docs/environment_state.json。技能会读取此文件，在实时探测 Agent 前检查 disabled 标志。

---

何时使用此技能

• 首次设置项目（尚无 docs/environment_state.json）
• 安装或移除 CLI Agent（Codex、Gemini）后
• 运行 ln-004-agent-config-sync 后（同步可能会改变 Agent 的可用性）
• 技能报告 Agent 意外不可用时

---

输出文件

docs/environment_state.json — 根据 references/environment_state_schema.json 验证。

{
  "$schema": "environment_state_v1",
  "scanned_at": "2026-03-08T14:30:00Z",
  "agents": {
    "codex": { "available": true, "version": "0.1.2503" },
    "gemini": { "available": false, "detail": "Command not found in PATH" }
  }
}

用户覆盖设置

用户可以在任意 Agent 条目中添加 "disabled": true，以选择停用，同时保留检测状态：

"codex": { "available": true, "disabled": true, "version": "0.1.2503" }

扫描器重新扫描时会保留 disabled 字段——它会覆盖 available、detail、version，但绝不会修改 disabled。

技能如何使用此设置： 运行 --health-check 前，技能会读取此文件。如果 disabled: true → 立即跳过该 Agent（不进行探测）。如果 disabled: false 或不存在 → 执行实时健康检查。

---

工作流

Probe Agents → Write JSON → Summary

阶段 1：探测 CLI Agent

单次调用 agent_runner.mjs --health-check 即可探测所有已注册的 Agent：

node shared/agents/agent_runner.mjs --health-check

路径解析： shared/agents/agent_runner.mjs 相对于 skills 仓库根目录。通过此 SKILL.md 所在目录 → 父目录定位。

解析输出（包含各 Agent 状态的 JSON）：

Agent	注册表键	状态字段
Codex	codex（检查 codex --version）	available、version（版本输出的首行）
Gemini	gemini（检查 gemini --version）	available、version（版本输出的首行）

如果找不到 agent_runner.mjs 或运行出错： 将两个 Agent 的 available 都设为 false，detail 设为 "agent_runner.mjs not available"。

阶段 1.5：Hook 健康检查

必须阅读： 加载 shared/references/hook_health_check.md

验证 hooks 配置：JSON 语法、脚本是否存在、依赖是否可用。将结果追加到 docs/environment_state.json 的 hooks 键下：

"hooks": {
  "status": "ok",
  "events": 3,
  "scripts_found": "3/3",
  "dependencies": { "node": "22.0.0" }
}

如果找不到 hooks.json："hooks": { "status": "not_configured" }。

阶段 2：写入 JSON

1. 读取现有状态（如果 docs/environment_state.json 存在）：
   • 保留现有条目中的 disabled 字段
   • 保留任何用户添加的自定义字段
2. 构建新状态：
   • $schema："environment_state_v1"
   • scanned_at：当前 ISO 8601 时间戳
   • agents：将探测结果（新的 available/detail/version）与保留的 disabled 标志合并
3. 确保 docs/ 目录存在（若不存在则创建）
4. 写入 docs/environment_state.json，使用 2 个空格缩进
5. 验证写入的文件是否符合 references/environment_state_schema.json 结构（检查键是否存在）

阶段 3：汇总报告

以表格形式显示结果：

Environment Scan Complete:
| Agent  | Status      | Detail                    |
|--------|-------------|---------------------------|
| Codex  | available   | 0.1.2503                  |
| Gemini | unavailable | Command not found in PATH |

State written to: docs/environment_state.json

如果任何 Agent 的 disabled: true，则将状态显示为 disabled（而不是可用/不可用）。

---

关键规则

1. 探测所有 Agent。 此技能始终探测所有 Agent，不受现有状态影响。这是完整重新扫描。
2. 保留 disabled。 绝不覆盖用户的 disabled: true 标志。检测状态会更新，用户偏好保持不变。
3. 无副作用。 此技能只写入 docs/environment_state.json。不修改其他文件。
4. 优雅失败。 每次探测相互独立。一次失败 = 一条 available: false 记录，扫描继续。
5. 无 TTL。 状态文件不会过期。只有运行此技能时才会刷新。

反模式

不要	应该
跳过对“已知”Agent 的探测	始终探测所有 Agent——这是一次完整扫描
重新扫描时删除 disabled 标记	合并：覆盖检测字段，保留 disabled
重试失败的探测	每个 Agent 仅尝试一次。失败时设置 available: false
探测 MCP 工具或平台	仅探测 CLI Agent（Codex、Gemini）。MCP 工具在其他位置配置
添加 TTL 或缓存过期逻辑	状态仅支持手动刷新

---

完成定义

• 已探测两个 Agent（Codex、Gemini）
• 已完成钩子健康检查（hooks.json、脚本、依赖项）
• 已写入结构有效的 docs/environment_state.json（包含 agents 和 hooks）
• 重新扫描时保留现有的 disabled 标记
• 已向用户显示汇总表

---

版本： 2.0.0 最后更新： 2026-03-08