agent-eyes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Eyes Skill

Agent Eyes 技能

When to Apply

适用场景

Apply this skill for UI tasks that need element-anchored precision (for example: “this button”, “当前这个区域”, breadcrumb path, DOM path, selected node).
Apply this skill when the user refers to “this element”, “当前选中的元素”, “这里”, “这个按钮”, “这个区域”, breadcrumb path, DOM path, or a visual target on the page.
Apply this skill when the task requires precise code modification and the target should be anchored to a selected element instead of guessed from text alone.
Apply this skill when the project may not yet have
```
@agent-eyes/agent-eyes
```
installed or may not yet have an
```
AGENTS.md
```
rule enforcing context-first behavior.
Do not apply this skill for tasks that can be completed from explicit file paths, code snippets, or clear textual requirements without selected-element context.

当UI任务需要元素锚定的精确性时，应用此技能（例如：“该按钮”、“当前这个区域”、面包屑路径、DOM路径、选定节点）。
当用户提及“该元素”、“当前选中的元素”、“这里”、“这个按钮”、“这个区域”、面包屑路径、DOM路径或页面上的视觉目标时，应用此技能。
当任务需要精确的代码修改，且目标需锚定到选定元素而非仅通过文本猜测时，应用此技能。
当项目尚未安装
```
@agent-eyes/agent-eyes
```
，或尚未拥有强制上下文优先行为的
```
AGENTS.md
```
规则时，应用此技能。
若任务无需选定元素上下文，仅通过明确的文件路径、代码片段或清晰的文本要求即可完成，则请勿应用此技能。

Apply Order

应用步骤

If
```
@agent-eyes/agent-eyes
```
is missing, install it first.
If installation was performed in this run, help the user finish minimal plugin configuration for their bundler.
If
```
AGENTS.md
```
is missing or lacks the Agent Eyes rule, create or update it.
If the task is element-anchored/ambiguous, request
```
GET /context/selected
```
before editing code.
If the response is
```
data: null
```
, the agent MUST continue with the default workflow and skip selected-context injection only.
The agent MUST NOT block execution or require element selection as a prerequisite; it may optionally suggest re-selection only when precision risk is high.

若缺失
```
@agent-eyes/agent-eyes
```
，先进行安装。
若本次运行中执行了安装操作，协助用户完成打包器的最小化插件配置。
若
```
AGENTS.md
```
缺失或未包含Agent Eyes规则，创建或更新该文件。
若任务为元素锚定/模糊类型，在编辑代码前请求
```
GET /context/selected
```
接口。
若响应为
```
data: null
```
，Agent必须继续执行默认工作流，仅跳过选定上下文注入步骤。
Agent不得阻塞执行或要求元素选择作为前提条件；仅当精确性风险较高时，可选择性建议重新选择。

Quick Workflow

快速工作流

Check whether
```
@agent-eyes/agent-eyes
```
is installed.
If missing, help install and provide minimal setup guidance.
If installed during this run, actively help configure plugin entry in bundler config files.
Verify config looks effective (plugin imported + plugin applied in config).
Check whether the project already has
```
AGENTS.md
```
.
If missing, create it. If present, append or refine the Agent Eyes workflow rule.
Resolve service base URL.
Request selected-context endpoint only when the target is element-anchored or ambiguous.
If no active selection exists, continue normal code analysis/edit flow and treat context as unavailable.
Validate and normalize response fields.
Build a compact context block for the next agent request.

检查
```
@agent-eyes/agent-eyes
```
是否已安装。
若缺失，协助安装并提供最小化设置指导。
若在本次运行中完成安装，主动协助在打包器配置文件中添加插件入口。
验证配置是否有效（已导入插件 + 已在配置中应用插件）。
检查项目是否已存在
```
AGENTS.md
```
。
若缺失则创建；若已存在，则追加或完善Agent Eyes工作流规则。
解析服务基础URL。
仅当目标为元素锚定或模糊类型时，请求选定上下文接口。
若当前无活动选择，继续正常的代码分析/编辑流程，将上下文视为不可用。
验证并标准化响应字段。
为后续Agent请求构建紧凑的上下文块。

Check Plugin Installation

插件安装检查

Detect package manager from lock files:
```
pnpm-lock.yaml
```
-> use
```
pnpm
```
```
yarn.lock
```
-> use
```
yarn
```
```
package-lock.json
```
-> use
```
npm
```
Check if
```
@agent-eyes/agent-eyes
```
exists in dependencies:
Inspect root
```
package.json
```
(
```
dependencies
```
and
```
devDependencies
```
).
If not found, install with the detected package manager:
```
pnpm add -D @agent-eyes/agent-eyes
```
```
yarn add -D @agent-eyes/agent-eyes
```
```
npm i -D @agent-eyes/agent-eyes
```
When replying to users, provide install commands on demand:
Default: only show one command that matches detected package manager.
If user asks for alternatives, then include
```
pnpm
```
/
```
yarn
```
/
```
npm
```
variants.
After install, do not stop at package installation:
Identify the active bundler/framework from project files (
```
vite.config.*
```
,
```
webpack.config.*
```
,
```
next.config.*
```
,
```
nuxt.config.*
```
, etc.).
Help the user update the real config file in-place (or give an exact patch) to include
```
codeInspectorPlugin(...)
```
.
Include minimal
```
bundler
```
+
```
showSwitch
```
+
```
agent.acp.command
```
fields in example config.
Confirm import + plugin registration both exist after edit.
If
```
package.json
```
cannot be found, ask user to confirm project root before installation.

从锁文件检测包管理器：
```
pnpm-lock.yaml
```
-> 使用
```
pnpm
```
```
yarn.lock
```
-> 使用
```
yarn
```
```
package-lock.json
```
-> 使用
```
npm
```
检查
```
@agent-eyes/agent-eyes
```
是否存在于依赖中：
检查根目录
```
package.json
```
的
```
dependencies
```
和
```
devDependencies
```
。
若未找到，使用检测到的包管理器进行安装：
```
pnpm add -D @agent-eyes/agent-eyes
```
```
yarn add -D @agent-eyes/agent-eyes
```
```
npm i -D @agent-eyes/agent-eyes
```
回复用户时，按需提供安装命令：
默认：仅展示与检测到的包管理器匹配的一条命令。
若用户询问替代方案，再提供
```
pnpm
```
/
```
yarn
```
/
```
npm
```
的变体命令。
安装完成后，不要仅停留在包安装步骤：
从项目文件（
```
vite.config.*
```
、
```
webpack.config.*
```
、
```
next.config.*
```
、
```
nuxt.config.*
```
等）识别当前使用的打包器/框架。
协助用户就地更新实际配置文件（或提供精确的补丁），以包含
```
codeInspectorPlugin(...)
```
。
示例配置中需包含最小化的
```
bundler
```
+
```
showSwitch
```
+
```
agent.acp.command
```
字段。
编辑后确认插件的导入和注册均已完成。
若无法找到
```
package.json
```
，请用户确认项目根目录后再进行安装。

Post-Install Configuration Requirement

安装后配置要求

Treat "install plugin" as incomplete until configuration is done.
If auto-edit is allowed, modify the detected config file directly and summarize changes.
If multiple candidate config files exist, prefer the one used by current scripts in
```
package.json
```
.
If bundler cannot be inferred, ask one short blocking question and provide 2-3 likely file candidates.
After config, instruct user to start/restart dev server and verify Agent Eyes switch appears.

仅当配置完成后，才算“安装插件”步骤完成。
若允许自动编辑，直接修改检测到的配置文件并总结变更内容。
若存在多个候选配置文件，优先选择
```
package.json
```
中当前脚本使用的文件。
若无法推断打包器，提出一个简短的封闭式问题，并提供2-3个可能的文件候选。
配置完成后，指导用户启动/重启开发服务器，并验证Agent Eyes开关是否显示。

Bundler Configuration Examples (On Demand)

打包器配置示例（按需提供）

If user asks for "how to configure", provide the example matching their actual bundler/framework.
Do not dump all examples by default. Return one best-match snippet first, plus alternatives only when requested.
Load examples from references/bundler-examples.md.
Prefer reading only the relevant section in that file to keep context small.
All snippets should include minimal Agent Eyes config:
```
bundler
```
```
showSwitch: true
```
```
agent.acp.command
```

若用户询问“如何配置”，提供与其实际使用的打包器/框架匹配的示例。
默认不要输出所有示例。先返回一个最匹配的代码片段，仅在用户请求时再提供替代方案。
从references/bundler-examples.md加载示例。
优先仅读取该文件中的相关部分，以保持上下文简洁。
所有代码片段应包含最小化的Agent Eyes配置：
```
bundler
```
```
showSwitch: true
```
```
agent.acp.command
```

Ensure AGENTS.md Exists

确保AGENTS.md存在

Look for
```
AGENTS.md
```
in the current project root first.
If it does not exist, create
```
AGENTS.md
```
with the Agent Eyes workflow template from references/agents-template.md.
If it exists, preserve user content and append a short Agent Eyes section rather than replacing the whole file.
The inserted rule must require:
checking
```
@agent-eyes/agent-eyes
```
installation
fetching
```
GET /context/selected
```
before element-anchored/ambiguous UI modification
when
```
data: null
```
, continue with default workflow; skip selected-context injection only
do not force re-selection; only suggest it when precision risk is high

先在当前项目根目录查找
```
AGENTS.md
```
。
若不存在，使用references/agents-template.md中的Agent Eyes工作流模板创建
```
AGENTS.md
```
。
若已存在，保留用户原有内容，追加简短的Agent Eyes部分，而非替换整个文件。
插入的规则必须包含：
检查
```
@agent-eyes/agent-eyes
```
的安装情况
在进行元素锚定/模糊的UI修改前，请求
```
GET /context/selected
```
若响应为
```
data: null
```
，继续执行默认工作流；仅跳过选定上下文注入步骤
不得强制重新选择；仅当精确性风险较高时建议重新选择

Resolve Base URL

解析基础URL

Prefer an explicit value from user/tool input.

If not provided, prefer environment (

AGENT_EYES_BASE_URL

CODE_INSPECTOR_BASE_URL

If still missing, read current project
```
.code-inspector/record.json
```
and use its
```
port
```
.
Fallback to
```
http://127.0.0.1:5678
```
.
Keep path configurable; do not hardcode if caller provides a different endpoint.

优先使用用户/工具输入的显式值。
若未提供，优先使用环境变量（
```
AGENT_EYES_BASE_URL
```
/
```
CODE_INSPECTOR_BASE_URL
```
）。
若仍缺失，读取当前项目的
```
.code-inspector/record.json
```
并使用其中的
```
port
```
。
回退值为
```
http://127.0.0.1:5678
```
。
保持路径可配置；若调用者提供了不同的接口，请勿硬编码。

Request Context Endpoint

请求上下文接口

Prefer
```
GET /context/selected
```
for read-only context retrieval.
If API requires POST, send an empty JSON body
```
{}
```
unless caller specifies filters.
Set
```
Accept: application/json
```
.
Use a short timeout (3-5 seconds) and report endpoint + timeout on failure.
Treat
```
data: null
```
as "there is no current selection". Do not reuse stale context from earlier requests; continue with default workflow without context injection.
For endpoint details and payload schema, read references/context-api.md.

优先使用
```
GET /context/selected
```
进行只读上下文获取。
若API要求使用POST，除非调用者指定过滤器，否则发送空JSON体
```
{}
```
。
设置请求头
```
Accept: application/json
```
。
使用短超时（3-5秒），请求失败时报告接口地址和超时信息。
将
```
data: null
```
视为“当前无选定内容”。请勿重用之前请求的陈旧上下文；不注入上下文，继续执行默认工作流。
接口详情和负载 schema，请查阅references/context-api.md。

Normalize Response

响应标准化

Accept either
```
data
```
wrapper or flat object.
Prefer multi-selection fields first:
```
activeSelectionId
```
```
selections
```
/
```
contexts
```
```
data.active
```
and
```
data.selections
```
Normalize into this shape:
```
activeSelectionId
```
: string
```
active
```
: object | null
```
contexts
```
: object[]
```
selections
```
: object[] (same as
```
contexts
```
)
For each context item, normalize:
```
filePath
```
: string
```
line
```
: number
```
column
```
: number
```
elementName
```
: string
```
dom.tagName
```
: string
```
dom.className
```
: string
```
dom.textContent
```
: string (truncate to 200 chars)
```
domPath
```
: string[]
If
```
domPath
```
is an object array, map with
```
label || name
```
.
If multi-selection fields are missing, fallback to single-selection fields from
```
data
```
or root object.
If required fields are missing, return a clear error listing missing keys.

接受
```
data
```
包装器或扁平对象两种格式。
优先使用多选字段：
```
activeSelectionId
```
```
selections
```
/
```
contexts
```
```
data.active
```
和
```
data.selections
```
标准化为以下格式：
```
activeSelectionId
```
: string
```
active
```
: object | null
```
contexts
```
: object[]
```
selections
```
: object[]（与
```
contexts
```
相同）
对每个上下文项，标准化以下字段：
```
filePath
```
: string
```
line
```
: number
```
column
```
: number
```
elementName
```
: string
```
dom.tagName
```
: string
```
dom.className
```
: string
```
dom.textContent
```
: string（截断至200字符）
```
domPath
```
: string[]
若
```
domPath
```
为对象数组，使用
```
label || name
```
进行映射。
若缺失多选字段，回退到
```
data
```
或根对象中的单选字段。
若缺失必填字段，返回清晰的错误信息，列出缺失的键。

Build Prompt Block

构建提示块

Use this template for downstream agent requests:

text

There are {selectionCount} selected DOM contexts. Consider all of them together.

{activePrefix}Selection #{index}
Source: {filePath}:{line}:{column}
Element: <{elementName} ...>
DOM: {tagName}, className: {className}, text: {textContent}
Path: {domPathJoined}

使用以下模板用于下游Agent请求：

text

当前有{selectionCount}个选定的DOM上下文，请综合考虑所有上下文。

{activePrefix}选择项#{index}
来源：{filePath}:{line}:{column}
元素：<{elementName} ...>
DOM：{tagName}，className: {className}，文本：{textContent}
路径：{domPathJoined}

Request Example

请求示例

bash

curl -sS "${BASE_URL}/context/selected" \
  -H "Accept: application/json"

bash

curl -sS "${BASE_URL}/context/selected" \
  -H "Accept: application/json"

Failure Handling

故障处理

If request fails, provide:
attempted URL
status code or network error
one concrete retry action (check server port, endpoint path, CORS, or auth header)
If the endpoint returns
```
data: null
```
, do not block the workflow; continue with default workflow and skip selected-context injection.
If context is stale, re-request immediately before sending code-modification prompt.

若请求失败，提供：
尝试调用的URL
状态码或网络错误信息
一个具体的重试操作（检查服务器端口、接口路径、CORS或认证头）
若接口返回
```
data: null
```
，请勿阻塞工作流；继续执行默认工作流，跳过选定上下文注入。
若上下文已过期，在发送代码修改请求前立即重新请求。

Notes

注意事项

Keep this skill focused on plugin readiness + context retrieval + normalization.
Do not mix this skill with full code-edit workflows unless the user asks.
Prefer making the
```
AGENTS.md
```
rule persistent so future agent turns follow it even if this skill is not re-triggered.

保持此技能聚焦于插件就绪、上下文获取与标准化。
除非用户要求，请勿将此技能与完整的代码编辑工作流混合使用。
优先确保
```
AGENTS.md
```
规则持久化，以便后续Agent即使未重新触发此技能，也能遵循该规则。