ln-005-environment-scanner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Paths: File paths (
shared/
,
references/
,
../ln-*
) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.

路径说明： 文件路径（
shared/
、
references/
、
../ln-*
）均相对于技能仓库根目录。如果在当前工作目录未找到，请定位到本SKILL.md所在目录，再向上一级即为仓库根目录。

Environment Scanner (Standalone Utility)

环境扫描器（独立工具）

Type: Standalone Utility Category: 0XX Shared

Probes CLI agents (Codex, Gemini) and writes

docs/environment_state.json

. Skills read this file to check

disabled

flags before live-probing agents.

类型： 独立工具 分类： 0XX 共享工具

探测CLI代理（Codex、Gemini）并生成

docs/environment_state.json

文件。其他技能会在实时探测代理前读取该文件，检查

disabled

标记。

When to Use This Skill

何时使用本技能

First-time project setup (no
```
docs/environment_state.json
```
yet)
After installing/removing CLI agents (Codex, Gemini)
After
```
ln-004-agent-config-sync
```
(sync may change agent availability)
When a skill reports unexpected agent unavailability

首次项目搭建（尚未生成
```
docs/environment_state.json
```
文件时）
安装/移除CLI代理（Codex、Gemini）后
执行
```
ln-004-agent-config-sync
```
后（同步操作可能会改变代理可用性）
当某技能报告代理意外不可用时

Output File

输出文件

docs/environment_state.json

— validated against

references/environment_state_schema.json

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" }
  }
}

docs/environment_state.json

—— 需符合

references/environment_state_schema.json

的校验规则。

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" }
  }
}

User Override

用户自定义覆盖

Users can add

"disabled": true

to any agent entry to opt out without losing detection state:

json

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

Scanner preserves

disabled

field on rescan — it overwrites

available

detail

version

but never touches

disabled

How skills use this: Before running

--health-check

, skills read this file. If

disabled: true

→ agent is skipped immediately (no probe). If

disabled: false

or absent → live health-check runs.

用户可在任意代理条目添加

"disabled": true

标记，无需丢失探测状态即可选择禁用该代理：

json

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

扫描器在重新扫描时会保留

disabled

字段——它会覆盖

available

、

detail

、

version

字段，但绝不会修改

disabled

字段。

技能如何使用该文件： 在执行

--health-check

前，技能会先读取此文件。如果

disabled: true

→ 直接跳过该代理（不进行实时探测）。如果

disabled: false

或未设置 → 执行实时健康检查。

Workflow

工作流程

Probe Agents → Write JSON → Summary

探测代理 → 生成JSON文件 → 生成汇总报告

Phase 1: Probe CLI Agents

阶段1：探测CLI代理

Single call to

agent_runner.py --health-check

probes all registered agents:

bash

python shared/agents/agent_runner.py --health-check

Path resolution:

shared/agents/agent_runner.py

is relative to skills repo root. Locate via this SKILL.md directory → parent.

Parse output (JSON with per-agent status):

Agent	Registry Key	State Fields
Codex	`codex` (checks `codex --version` )	`available` , `version` (first line of version output)
Gemini	`gemini` (checks `gemini --version` )	`available` , `version` (first line of version output)

If
agent_runner.py
not found or errors: Set both agents to

available: false

detail: "agent_runner.py not available"

调用一次

agent_runner.py --health-check

即可探测所有已注册的代理：

bash

python shared/agents/agent_runner.py --health-check

路径解析：

shared/agents/agent_runner.py

相对于技能仓库根目录。可通过本SKILL.md所在目录向上一级定位到该文件。

解析输出（包含各代理状态的JSON数据）：

代理	注册表键	状态字段
Codex	`codex` （检查 `codex --version` ）	`available` 、 `version` （版本输出的第一行内容）
Gemini	`gemini` （检查 `gemini --version` ）	`available` 、 `version` （版本输出的第一行内容）

如果
agent_runner.py
未找到或执行出错：将两个代理的状态均设为

available: false

，

detail: "agent_runner.py not available"

。

Phase 2: Write JSON

阶段2：生成JSON文件

Read existing state (if
```
docs/environment_state.json
```
exists):
- Preserve
```
disabled
```
  fields from existing entries
- Preserve any user-added custom fields
Build new state:
- ```
$schema
```
  :
```
"environment_state_v1"
```
- ```
scanned_at
```
  : current ISO 8601 timestamp
- ```
agents
```
  : merge probe results (new
```
available
```
  /
```
detail
```
  /
```
version
```
  ) with preserved
```
disabled
```
  flags
Ensure
docs/
directory exists (create if missing)
Write
```
docs/environment_state.json
```
with 2-space indentation
Validate written file against
```
references/environment_state_schema.json
```
structure (key presence check)

读取现有状态（如果
```
docs/environment_state.json
```
已存在）：
- 保留现有条目中的
```
disabled
```
  字段
- 保留所有用户添加的自定义字段
构建新状态：
- ```
$schema
```
  :
```
"environment_state_v1"
```
- ```
scanned_at
```
  : 当前ISO 8601格式时间戳
- ```
agents
```
  : 将探测结果（新的
```
available
```
  /
```
detail
```
  /
```
version
```
  ）与保留的
```
disabled
```
  标记合并
确保
docs/
目录存在（如果不存在则创建）
写入
```
docs/environment_state.json
```
文件，使用2空格缩进
校验写入的文件是否符合
```
references/environment_state_schema.json
```
的结构要求（检查必填键是否存在）

Phase 3: Summary Report

阶段3：汇总报告

Display results as a table:

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

If any agent has

disabled: true

, show status as

disabled

(not available/unavailable).

以表格形式展示结果：

环境扫描完成：
| 代理  | 状态        | 详情                    |
|--------|-------------|---------------------------|
| Codex  | 可用        | 0.1.2503                  |
| Gemini | 不可用      | Command not found in PATH |

状态已写入：docs/environment_state.json

如果任何代理的

disabled: true

，则状态显示为

已禁用

（而非可用/不可用）。

Critical Rules

核心规则

Probe all agents. This skill always probes ALL agents, regardless of existing state. It is the full rescan.
Preserve
disabled
. Never overwrite user's
```
disabled: true
```
flags. Detection state updates, user preference stays.
No side effects. This skill only writes
```
docs/environment_state.json
```
. No other files modified.
Fail gracefully. Each probe is independent. One failure = one
```
available: false
```
entry, scan continues.
No TTL. State file has no expiration. It is refreshed only by running this skill.

探测所有代理：本技能始终会探测所有代理，不受现有状态影响。这是一次完整的重新扫描。
保留
disabled
标记：绝不能覆盖用户设置的
```
disabled: true
```
标记。探测状态会更新，但用户偏好会被保留。
无副作用：本技能仅会写入
```
docs/environment_state.json
```
文件，不会修改其他任何文件。
优雅容错：每个探测操作都是独立的。某一个探测失败只会对应一个
```
available: false
```
条目，扫描仍会继续。
无过期时间：状态文件没有过期时间，仅在运行本技能时才会刷新。

Anti-Patterns

反模式

DON'T	DO
Skip probes for "known" agents	Always probe all agents — this is a full scan
Delete `disabled` flags on rescan	Merge: overwrite detection fields, preserve `disabled`
Retry failed probes	One attempt per agent. Failure = `available: false`
Probe MCP tools or platform	Only probe CLI agents (Codex, Gemini). MCP tools configured elsewhere
Add TTL or cache expiry logic	State is manual-refresh only

禁止操作	正确做法
跳过对"已知"代理的探测	始终探测所有代理——这是一次完整扫描
重新扫描时删除 `disabled` 标记	合并数据：覆盖探测字段，保留 `disabled` 标记
重试失败的探测	每个代理仅尝试一次。失败则设为 `available: false`
探测MCP工具或平台	仅探测CLI代理（Codex、Gemini）。MCP工具的配置在其他地方进行
添加过期时间或缓存过期逻辑	状态仅支持手动刷新

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

Definition of Done

—

#	Criterion
1	Both agents probed (Codex, Gemini)
2	`docs/environment_state.json` written with valid structure
3	Existing `disabled` flags preserved across rescan
4	Summary table displayed to user

Version: 2.0.0 Last Updated: 2026-03-08

—