# https://github.com/se-cli/se-cli 项目说明书

生成时间：2026-07-28 17:47:22 UTC

## 目录

- [项目概览与设计理念](#page-1)
- [系统架构与通信机制](#page-2)
- [核心命令、工具实现与 Aria 快照](#page-3)
- [AI 代理集成、代码生成与社区路线图](#page-4)

<a id='page-1'></a>

## 项目概览与设计理念

### 相关页面

相关主题：[系统架构与通信机制](#page-2), [核心命令、工具实现与 Aria 快照](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/se-cli/se-cli/blob/main/README.md)
- [package.json](https://github.com/se-cli/se-cli/blob/main/package.json)
- [docs/spec.md](https://github.com/se-cli/se-cli/blob/main/docs/spec.md)
- [docs/architecture.md](https://github.com/se-cli/se-cli/blob/main/docs/architecture.md)
- [docs/roadmap.md](https://github.com/se-cli/se-cli/blob/main/docs/roadmap.md)
- [skill/SKILL.md](https://github.com/se-cli/se-cli/blob/main/skill/SKILL.md)
</details>

# 项目概览与设计理念

## 项目定位与目标

`se-cli`（仓库名 `se-cli`，包名 `selenium-cli`）是一个面向 AI 代理（agent）的浏览器自动化命令行工具。它在 Selenium WebDriver 之上提供了一层精简的 CLI 封装，目的是让大语言模型驱动的代理能够以"低成本、可观察、可恢复"的方式操作真实浏览器。资料来源：[README.md:1-30]()

与直接让 agent 调用 Selenium 客户端库不同，`selenium-cli` 把每次交互压缩成一条短命令（例如 `open <url>`、`snapshot`、`click @e5`），并以稳定的元素引用（`ref`）替代脆弱的 CSS/XPath 选择器，从而显著减少 token 消耗。资料来源：[docs/spec.md:12-40]()

## 核心设计理念

`selenium-cli` 的设计围绕四个相互支撑的理念展开：

1. **代理优先（agent-first）**：命令语法、输出格式与错误信息都以"被 LLM 读取"为前提，避免冗长的堆栈与 JSON schema。资料来源：[docs/spec.md:42-58]()
2. **会话化（session-based）**：通过 `-s=<name>` 标志并行管理多个浏览器实例（`chrome`、`firefox`、`staging` 等），代理可以在不重启进程的前提下切换上下文。资料来源：[README.md:48-72]()
3. **引用驱动（ref-driven）**：每次 `snapshot` 生成可访问性树，元素以 `e1`、`e5` 等短引用暴露，后续动作只需 `click @e5`，这与 Playwright 的语义相近但更紧凑。资料来源：[docs/spec.md:60-88]()
4. **SKILL.md 协议**：仓库内置 `skill/SKILL.md`，向 agent 描述可用命令、约定与示例，等价于一份"agent 使用手册"。资料来源：[skill/SKILL.md:1-20]()

这四点共同支撑了 `selenium-cli` 的一个核心主张：在 CLI 形态下，它比 MCP 节省 token，因为不需要携带完整工具 schema。资料来源：[README.md:31-46]()

## 架构概览

系统采用"守护进程 + CLI 客户端"的双层结构：Node.js 守护进程持有真实的 WebDriver 会话并通过本地协议与 CLI 通信；CLI 进程负责解析命令、打印结果并返回给 agent。这种解耦让浏览器生命周期可以跨越多次 agent 调用而保持存活。资料来源：[docs/architecture.md:14-46]()

| 组件 | 角色 | 主要接口 |
| --- | --- | --- |
| daemon | 持有 WebDriver 会话、转发命令 | 本地 socket / stdio |
| CLI 客户端 | 解析参数、序列化输出 | `selenium-cli <cmd>` |
| SKILL.md | 向 agent 描述能力与约定 | 文件加载 |

进程间通过稳定的会话名而非 PID 寻址，因此 agent 重启不会丢失现有浏览器。资料来源：[docs/architecture.md:48-70]()

## 发展路线与社区关注

根据 `docs/roadmap.md` 与社区讨论，项目按版本节奏演进：

- **v0.5** 引入录制模式（recording）与 `generate-locator` 命令，让"人点击 + agent 生成测试"成为可能。资料来源：[docs/roadmap.md:18-34]()
- **v0.6** 关注可观测性：`show dashboard` 提供多会话实时预览，`show --annotate` 允许人类协作时在页面上标注区域；`attach --extension` 与 `--endpoint=<url>` 分别把控制面扩展到用户日常浏览器和 Selenium Grid 4 / 云端 Grid。资料来源：[docs/roadmap.md:36-62]()
- **v0.7** 借鉴 Playwright 体验，引入简化版 trace viewer 以及 `plan` → `generate` → `heal` 的测试维护工作流，并支持 `pytest-selenium` 暂停点接入。资料来源：[docs/roadmap.md:64-90]()
- **长期方向** 包括按 agent 定制 SKILL.md（issue #28）、暴露为 MCP 服务器以兼容 Claude Desktop / Cursor（issue #27）、接入 Browserbase / Browserless 等云浏览器（issue #26）、以及提供 Python / Java SDK 绑定（issue #25）。资料来源：[docs/roadmap.md:92-120]()

## 小结

`se-cli` 的整体思路是：用最小可行的 CLI 表面把浏览器暴露给 agent，用 session + ref 抽象降低每次交互的认知与 token 开销，用 SKILL.md 把"使用约定"显式化，再通过 daemon 架构为未来接入云 Grid、扩展与多语言 SDK 留出空间。对于希望让 LLM 真实地"看见并操作"网页的团队而言，它是一份比直接绑定 Selenium 更省心、比 MCP 更经济的中间层选择。资料来源：[README.md:74-96]()

---

<a id='page-2'></a>

## 系统架构与通信机制

### 相关页面

相关主题：[项目概览与设计理念](#page-1), [核心命令、工具实现与 Aria 快照](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/cli.ts](https://github.com/se-cli/se-cli/blob/main/src/cli.ts)
- [src/session.ts](https://github.com/se-cli/se-cli/blob/main/src/session.ts)
- [src/registry.ts](https://github.com/se-cli/se-cli/blob/main/src/registry.ts)
- [src/daemon/server.ts](https://github.com/se-cli/se-cli/blob/main/src/daemon/server.ts)
- [src/daemon/backend.ts](https://github.com/se-cli/se-cli/blob/main/src/daemon/backend.ts)
- [src/protocol.ts](https://github.com/se-cli/se-cli/blob/main/src/protocol.ts)
</details>

# 系统架构与通信机制

`selenium-cli` 是一个面向 AI 代理（agent）的浏览器自动化工具，其核心设计目标是在 CLI 通道内提供比 MCP（Model Context Protocol）更节省 token 的浏览器控制能力，同时保持对人类开发者的可操作性。整个系统采用「**CLI 客户端 + 后台守护进程（daemon）+ 浏览器后端**」的分层架构，使 agent 可以通过 shell 命令驱动本地或远程浏览器会话，而无需承担 MCP 的 schema 开销。

## 整体组件拓扑

系统由三个主要层次构成：CLI 前端、daemon 后台、以及浏览器驱动后端。

```mermaid
flowchart LR
    A[Agent / 用户] --> B[src/cli.ts<br/>CLI 入口]
    B --> C[src/protocol.ts<br/>IPC 协议]
    C --> D[src/daemon/server.ts<br/>守护进程]
    D --> E[src/registry.ts<br/>会话注册中心]
    D --> F[src/session.ts<br/>会话生命周期]
    F --> G[src/daemon/backend.ts<br/>WebDriver / CDP 后端]
    G --> H[(本地或远程浏览器)]
```

CLI 入口负责解析参数、定位目标会话，并把命令序列化后通过 `src/protocol.ts` 中定义的 IPC 协议发送给守护进程。守护进程是唯一的浏览器拥有者，所有会话状态都集中在它内部管理。资料来源：[src/cli.ts:1-80]()、[src/protocol.ts:1-60]()。

## 守护进程与会话注册

`src/daemon/server.ts` 是常驻 Node.js 进程，监听来自 CLI 的请求并分派给相应的会话处理器。`src/registry.ts` 充当会话注册中心，按会话名（`-s=<name>`，例如 `chrome`、`firefox`、`staging`）维护多个并发浏览器实例，使 agent 能够并行驱动多个独立会话。

会话的实际行为由 `src/session.ts` 抽象：每个会话封装了启动、关闭、命令派发、状态查询等生命周期方法。当收到 `attach` 类命令时，会话会复用现有浏览器；当收到 `open` 类命令时，会通过后端创建一个新会话。资料来源：[src/daemon/server.ts:1-120]()、[src/registry.ts:1-90]()、[src/session.ts:1-150]()。

## 浏览器后端抽象

`src/daemon/backend.ts` 把底层驱动差异（Selenium WebDriver、CDP attach、未来的 Selenium Grid `--endpoint`、Browserbase / Browserless / Sauce Labs 等云浏览器提供商）封装成统一接口。这一抽象层是实现「本地 MVP → 远程 Grid → 云端浏览器」演进路径的关键。社区讨论中提及的 `--cdp=<url>` 浏览器扩展控制（#20）、`--endpoint=<url>` Grid 4 接入（#21）以及长期云浏览器提供商集成（#26）都将通过扩展该后端实现。资料来源：[src/daemon/backend.ts:1-180]()。

## 通信协议与未来 MCP 兼容层

CLI 与 daemon 之间的通信由 `src/protocol.ts` 定义，采用基于 stdin/stdout 或本地 socket 的轻量级消息格式（具体由实现决定），避免 JSON-RPC 等重型 schema，从而降低每次调用的 token 占用。这一设计正是 issue #27 中讨论的「保留 token 高效 CLI 路径」的基础：未来计划在守护进程之上再暴露一个 MCP server 端点，让 Claude Desktop、Cursor MCP 模式等只能讲 MCP 的客户端也能复用现有会话，而 CLI 用户继续走轻量通道。资料来源：[src/protocol.ts:1-100]()。

## 多客户端扩展路径

长期路线图（issue #25）要求 daemon 保持 Node.js 实现，同时通过相同 `src/protocol.ts` 暴露 Python 与 Java SDK 绑定，使 pytest-selenium、Robot Framework 等生态可以直接驱动会话。由于协议与会话实现解耦，新增客户端类型不需要改动 daemon 核心。

此外，issue #18 提出的「实时仪表板」、issue #19 的页面标注、`show` 命令都将作为 daemon 提供的附加通道（事件流、批注回写）与现有 CLI 协议并存，而不是替换它。资料来源：[src/session.ts:80-150]()、[src/daemon/server.ts:60-120]()。

## 关键设计权衡

- **Token 效率优先**：CLI 命令输出经过压缩（如 `snapshot` 的 ref 化简），避免每步携带完整 DOM。
- **会话隔离**：每个 `-s=<name>` 会话独立注册、独立后端，故障不会跨会话传播。
- **后端可插拔**：所有浏览器特定代码收敛在 `src/daemon/backend.ts`，便于扩展 Grid / 云端 / 扩展协议。
- **协议演进友好**：`src/protocol.ts` 是新增客户端（MCP、Python、Java SDK）的唯一扩展点，守护进程内部保持稳定。

---

<a id='page-3'></a>

## 核心命令、工具实现与 Aria 快照

### 相关页面

相关主题：[系统架构与通信机制](#page-2), [AI 代理集成、代码生成与社区路线图](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/program.ts](https://github.com/se-cli/se-cli/blob/main/src/program.ts)
- [src/minimist.ts](https://github.com/se-cli/se-cli/blob/main/src/minimist.ts)
- [src/output.ts](https://github.com/se-cli/se-cli/blob/main/src/output.ts)
- [src/response.ts](https://github.com/se-cli/se-cli/blob/main/src/response.ts)
- [src/daemon/tools/index.ts](https://github.com/se-cli/se-cli/blob/main/src/daemon/tools/index.ts)
- [src/daemon/tools/shared.ts](https://github.com/se-cli/se-cli/blob/main/src/daemon/tools/shared.ts)
</details>

# 核心命令、工具实现与 Aria 快照

## 概述

`selenium-cli` 的整体架构围绕"守护进程 + CLI 客户端"的双层模型组织：用户在终端调用 CLI 命令，CLI 将请求转发给后台守护进程（daemon），守护进程再通过 Selenium WebDriver 与浏览器会话交互。本页聚焦这一链路中的三个关键环节——CLI 命令注册与参数解析、守护进程内部的工具（tool）实现、以及面向代理（agent）的 Aria 无障碍快照机制。

资料来源：[src/program.ts:1-40]()

## CLI 命令注册与参数解析

`src/program.ts` 是 CLI 的入口装配文件，负责注册所有用户可见的子命令（如 `attach`、`snapshot`、`show`、`generate-locator` 等）。它将每个命令映射到一个处理函数，并把全局选项（如 `-s=<sessionId>`、`--cdp=<url>`、`--endpoint=<url>`）注入到命令上下文中。

参数解析由 `src/minimist.ts` 提供，封装了 `minimist` 库并定义了 CLI 的标志位语法约定：
- `-s=<name>` 用于指定当前会话名称，支持多会话并行（参见 issue #18 的 dashboard 需求）；
- `--cdp=<url>` 与 `--endpoint=<url>` 分别用于附加到本地 CDP 端点和远程 Selenium Grid 4（对应 issue #20、#21）；
- 布尔标志与键值标志统一返回，便于在守护进程侧复用。

资料来源：[src/minimist.ts:1-60]()、[src/program.ts:41-120]()

## 守护进程工具系统

`src/daemon/tools/index.ts` 是守护进程内"工具（tool）"的总注册表。每一条 CLI 命令在服务端对应一个 tool，tool 接收 CLI 转发过来的参数，调用 Selenium API，并把结果序列化为统一响应。`src/daemon/tools/shared.ts` 提供了跨 tool 复用的辅助能力——例如元素引用（ref）的生成与解析、session 选择器、错误包装、以及对 Aria 角色/名称的标准化处理。

tool 的设计遵循"一个 tool 一个动作"的原则：`snapshot` 工具调用 `getAccessibleSnapshot` 生成 Aria 树；`click`、`type`、`hover` 等交互工具根据 ref 解析回元素后再驱动 WebDriver。这种拆分使得新增命令（如 issue #16 的 `generate-locator`、issue #17 的录制模式）只需新增一个 tool 文件并注册到 `index.ts`。

资料来源：[src/daemon/tools/index.ts:1-50]()、[src/daemon/tools/shared.ts:1-80]()

## 输出与响应协议

CLI 与 daemon 之间通过 JSON 协议通信，序列化与渲染由 `src/response.ts` 与 `src/output.ts` 共同完成。`response.ts` 定义了统一的响应结构：`{ ok: boolean, data?: any, error?: { code, message }, session? }`，所有 tool 必须返回该结构；`output.ts` 负责把响应渲染为代理友好的文本——成功时输出数据（必要时折叠长字段），失败时输出可被代理快速理解的错误码与消息。

为节省 token，输出层会主动省略与代理决策无关的字段（如 driver 内部状态），这正是 issue #27 中"MCP 兼容层 vs token 节省"权衡的源头：CLI 路径保持精简输出，而未来的 MCP 兼容层会在 daemon 侧增加 schema 展开。

资料来源：[src/response.ts:1-40]()、[src/output.ts:1-60]()

## Aria 快照机制

Aria 快照是代理理解页面结构的入口。`snapshot` tool 调用浏览器的无障碍树（accessibility tree）接口，将 DOM 节点序列化为带角色与名称的扁平列表，每行形如 `- button "Submit" [ref=e5]`。`ref` 是 tool 在快照时为每个可交互元素动态分配的短标识符，代理在后续 `click`、`type` 等命令中通过 ref 引用元素，`shared.ts` 中的 ref 解析逻辑再把 ref 映射回 WebElement。

```mermaid
flowchart LR
    A[CLI: snapshot] --> B[daemon tool]
    B --> C[Selenium getAccessibleSnapshot]
    C --> D[role/name 序列化]
    D --> E[ref 注入]
    E --> F[response 渲染]
    F --> G[agent 看到<br/>button ref=e5]
    G --> H[CLI: click ref=e5]
    H --> I[shared.ts 解析 ref]
    I --> J[WebDriver click]
```

这种"快照 + ref"的两段式协议避免把完整 DOM 喂给代理，显著降低 token 消耗，也是 issue #19 中 `--annotate`（人类在页面上框选区域）与 issue #24 中简化 trace viewer 的共同数据基底——Aria 树既是代理的可读视图，也是 trace 的事件来源。

资料来源：[src/daemon/tools/shared.ts:81-160]()、[src/daemon/tools/index.ts:51-100]()

---

<a id='page-4'></a>

## AI 代理集成、代码生成与社区路线图

### 相关页面

相关主题：[项目概览与设计理念](#page-1), [核心命令、工具实现与 Aria 快照](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skill/SKILL.md](https://github.com/se-cli/se-cli/blob/main/skill/SKILL.md)
- [README.md](https://github.com/se-cli/se-cli/blob/main/README.md)
- [docs/plan.md](https://github.com/se-cli/se-cli/blob/main/docs/plan.md)
- [docs/spec.md](https://github.com/se-cli/se-cli/blob/main/docs/spec.md)
</details>

# AI 代理集成、代码生成与社区路线图

## 1. AI 代理集成的设计取向

`selenium-cli`（仓库 `se-cli`）把自己定位为"代理友好"型浏览器自动化 CLI，刻意绕开 MCP 的 schema 开销以换取 token 经济性。其面向 AI 代理的核心入口是仓库根下的 `skill/SKILL.md` 技能描述文件：代理阅读该文件即可按命令行驱动会话，不必再加载额外 schema。资料来源：[README.md:1-40]()

代理启动会话的基本形态是 `selenium-cli session open <name>`，随后通过 `snapshot`、`click [ref=eN]`、`type [ref=eN] "..."` 等文本化命令与浏览器交互。所有可访问元素在快照里都带稳定 `[ref=eN]` 引用，代理直接把 ref 作为下一次操作的锚点，避免把完整 DOM 注入上下文。资料来源：[skill/SKILL.md:1-80]()

`docs/spec.md` 把"命令 + ref 快照"这套协议正式化，明确 CLI 是文本入口、守护进程是会话状态持有者、Selenium WebDriver / CDP 是底层执行器。这种分层让代理只关心会话与命令，不需要碰浏览器生命周期。资料来源：[docs/spec.md:1-60]()

## 2. 代码生成与测试工作流

代码生成相关能力集中在 v0.5 计划：一是 `generate-locator` 命令，可独立产出"最佳定位器"字符串供粘贴到测试或验证唯一性；二是"recording mode"录制模式，由人类手动点击浏览器，`selenium-cli` 把动作翻译成可运行的测试文件。两条路径互补——一个面向元素级精度，一个面向端到端场景录制。资料来源：[docs/plan.md:1-80](), [README.md:40-90]()

v0.7 进一步引入 `plan → generate → heal` 三段式工作流，对齐 Playwright 的同名理念：代理先读 spec 生成测试、再运行、最后在页面变更时自动修复失效定位器；同版本新增的 `pytest-selenium` 暂停点挂接允许 Python 测试在卡顿时把实时会话交给 `selenium-cli` 交互式调试，再恢复执行。资料来源：[docs/plan.md:80-160]()

| 工作流阶段 | 触发命令 | 产出物 |
|---|---|---|
| 元素定位 | `generate-locator [ref]` | 最优选择器字符串 |
| 录制回放 | `record start` / `record stop` | 可执行测试脚本 |
| 自愈修复 | `heal <test-file>` | 修复后的测试文件 |

## 3. 协作、调试与可视化扩展

针对"代理与人类协同时快照信息不足"的问题，v0.6 提出 `show --annotate`：人类在页面上框选区域并标注语义，代理据此收紧下一步操作上下文；同版本还引入 `show dashboard`，把 `-s=chrome`、`-s=firefox`、`-s=staging` 等多会话实时预览聚合到单一窗口，便于人类监督多代理并发。资料来源：[docs/plan.md:40-120]()

v0.7 的"simplified trace viewer"借鉴 Playwright Trace Viewer 体验，利用 Selenium 4 BiDi 事件流聚合 DOM 快照、截图、网络与控制台日志，按步骤回放失败用例，弥补 Selenium 在调试可视化上的原生空白。资料来源：[docs/plan.md:120-180]()

## 4. 长期生态与社区路线图

社区议题把长期方向拆为四条主线：

- **#28 按代理定制 `SKILL.md`**：为 Claude Code、Cursor、GitHub Copilot CLI 分别提供差异化技能文件与调用约定，替换当前通用描述。资料来源：[issue #28]()
- **#27 MCP 兼容层**：守护进程同时暴露为 MCP server，让只懂 MCP 的客户端（Claude Desktop、Cursor MCP 模式）也能消费 `selenium-cli` 会话，CLI 路径保持 token 高效。资料来源：[issue #27]()
- **#26 云浏览器接入**：对接 Browserbase、Browserless、Sauce Labs、LambdaTest，使代理在无本地浏览器的 CI / Serverless 环境运行。资料来源：[issue #26]()
- **#25 Python / Java SDK**：守护进程保持 Node，但提供 Python / Java 绑定，覆盖 pytest-selenium、Robot Framework、Selenium-Java 既有用户群。资料来源：[issue #25]()

短期到中期（v0.6）的另外两个关键项是 `--endpoint=<url>` 远程 Grid 接入（#21）与 `--extension` 浏览器扩展控制（#20）：前者让 `selenium-cli` 直接驱动 Selenium Grid 4 / BrowserStack / Sauce Labs 的远程节点，后者通过扩展接管用户日常的 Chrome / Edge（含真实标签、扩展与登录态），把"调试浏览器"与"工作浏览器"统一起来。资料来源：[issue #21](), [issue #20]()

整体上，`se-cli` 的代理集成策略可以概括为"以 CLI 为正路、以 MCP 为旁路、以 SDK 为多语种桥接、以 `SKILL.md` 为代理教学手册"——通过 ref 快照与文本化命令把 token 成本压到最低，同时为不同代理、不同语言栈、不同部署形态保留可扩展的协议边界。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：se-cli/se-cli

摘要：发现 23 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：feat(long-term): Python/Java client SDK bindings。

## 1. 安装坑 · 来源证据：feat(long-term): Python/Java client SDK bindings

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(long-term): Python/Java client SDK bindings
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/se-cli/se-cli/issues/25 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 来源证据：feat(long-term): per-agent SKILL.md optimization

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(long-term): per-agent SKILL.md optimization
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/se-cli/se-cli/issues/28 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 安装坑 · 来源证据：feat(v0.5): recording mode for test generation

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(v0.5): recording mode for test generation
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/se-cli/se-cli/issues/17 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 4. 安装坑 · 来源证据：feat(v0.5): role-based locator code generation

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(v0.5): role-based locator code generation
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/se-cli/se-cli/issues/15 | 来源类型 github_issue 暴露的待验证使用条件。

## 5. 安装坑 · 来源证据：feat(v0.6): show dashboard (live session previews)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(v0.6): show dashboard (live session previews)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/se-cli/se-cli/issues/18 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 6. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/se-cli/se-cli | host_targets=mcp_host, claude_code, claude, cursor

## 7. 配置坑 · 来源证据：feat(v0.4): browser console log capture

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat(v0.4): browser console log capture
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/se-cli/se-cli/issues/11 | 来源类型 github_issue 暴露的待验证使用条件。

## 8. 配置坑 · 来源证据：feat(v0.4): element highlight command

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat(v0.4): element highlight command
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/se-cli/se-cli/issues/13 | 来源类型 github_issue 暴露的待验证使用条件。

## 9. 配置坑 · 来源证据：feat(v0.4): network requests list and inspection

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat(v0.4): network requests list and inspection
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/se-cli/se-cli/issues/12 | 来源类型 github_issue 暴露的待验证使用条件。

## 10. 配置坑 · 来源证据：feat(v0.7): simplified trace viewer

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat(v0.7): simplified trace viewer
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/se-cli/se-cli/issues/24 | 来源类型 github_issue 暴露的待验证使用条件。

## 11. 能力坑 · 来源证据：feat(v0.7): plan/generate/heal test workflow

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：feat(v0.7): plan/generate/heal test workflow
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/se-cli/se-cli/issues/23 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 12. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/se-cli/se-cli | README/documentation is current enough for a first validation pass.

## 13. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/se-cli/se-cli | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/se-cli/se-cli | no_demo; severity=medium

## 15. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/se-cli/se-cli | no_demo; severity=medium

## 16. 安全/权限坑 · 来源证据：feat(long-term): MCP compatibility layer

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(long-term): MCP compatibility layer
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/se-cli/se-cli/issues/27 | 来源类型 github_issue 暴露的待验证使用条件。

## 17. 安全/权限坑 · 来源证据：feat(long-term): cloud browser provider integration

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(long-term): cloud browser provider integration
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/se-cli/se-cli/issues/26 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

## 18. 安全/权限坑 · 来源证据：feat(v0.5): run-code command for arbitrary Selenium snippets

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(v0.5): run-code command for arbitrary Selenium snippets
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/se-cli/se-cli/issues/14 | 来源类型 github_issue 暴露的待验证使用条件。

## 19. 安全/权限坑 · 来源证据：feat(v0.6): attach --extension (browser extension control)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(v0.6): attach --extension (browser extension control)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/se-cli/se-cli/issues/20 | 来源类型 github_issue 暴露的待验证使用条件。

## 20. 安全/权限坑 · 来源证据：feat(v0.6): attach to Selenium Grid 4 (--endpoint)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(v0.6): attach to Selenium Grid 4 (--endpoint)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/se-cli/se-cli/issues/21 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 21. 安全/权限坑 · 来源证据：feat(v0.7): attach to pytest-selenium pause point

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(v0.7): attach to pytest-selenium pause point
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/se-cli/se-cli/issues/22 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 22. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/se-cli/se-cli | issue_or_pr_quality=unknown

## 23. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/se-cli/se-cli | release_recency=unknown

<!-- canonical_name: se-cli/se-cli; human_manual_source: deepwiki_human_wiki -->