一句话：MCP 桥把"页面调试能力"变成任意 AI agent 的工具 —— 配置 aiti-devtools 使用；改造 AI agent；支持 aiti-devtools、aiti-devtools-vscode/idea 等插件完成注入；通过 aiti-bridge 直接把消息发到 IDE 里的 AI agent 窗口。
| 包 | 形态 | 职责 |
|---|
@aiti-ai/aiti-bridge | 本地桥服务（CLI） | 桥地址/pageId 配置、会话登记与路由、事件广播、对接 IDE AI 窗口；内置 MCP 端点（stdio shim + HTTP + Streamable HTTP，暴露 page_* / user_* 工具族） |
| 痛点 | 解决 |
|---|
| AI 看不到页面 | page_exec（类 CDP 命令）/ page_snapshot 让 AI 操作并读取真实页面 |
| AI 需要用户配合 | user_* 工具族：点选元素、是/否确认、方案选择、文本输入、在线探测、非阻塞通知 |
| 配置繁琐 | 配置最小化：inspect 只需传 AI 地址，宿主把环境（pageId）构建好，AI 窗口打开即用 |
| token 写死、多连接混淆 | token → instanceId（连接身份，短数字/字母数字），uid → frameId（目标 frame），组合 pageId |
| 刷新就断线 | instanceId 持久化 + TTL 保留 + secret 校验，reload 不断线 |
| 消息到不了 IDE 的 AI | IDE 插件 + bridge 直连：AI agent 窗口实时收到页面事件/交互结果 |
IDE AI agent 窗口 / Claude Code / Cursor / aiti-agent
│ MCP (stdio / HTTP / SSE)
▼
┌─────────────────────────────┐
│ aiti-bridge（本地服务） │ session 登记 / 路由 / 广播
│ ├─ /bridge/claim │ 连接登记/复用（instanceId + secret）
│ ├─ /bridge/sessions │ 发现：全部可操作 pageId
│ ├─ /bridge/sse │ 持久连接（role=page|ai）
│ ├─ /bridge/result │ 执行结果回桥
│ ├─ /bridge/event │ 页面事件（open_file 等）
│ └─ /mcp/mcp │ MCP JSON-RPC（tools/list / tools/call；Streamable HTTP）
└────────────┬────────────────┘
│ SSE
▼
aiti-devtools（页面注入）→ aiti-devtools client → 目标 frame 执行
| 工具 | 说明 |
|---|
page_exec | 在 pageId 目标 frame 执行类 CDP 命令（DOM/CSS/Input/Page/Runtime/Storage/Performance/Browser） |
page_snapshot | 采集页面快照（DOM 概要 + 视口 + 框架识别） |
bridge_status | 桥连接状态、活跃连接、可操作 pageId 列表 |
| 工具 | 场景 | 用户在哪作答 |
|---|
user_pick_element | AI 请用户点选页面元素 | 页面（点选面板 + Inspector） |
user_confirm | 是/否（批准/拒绝，带理由） | AI 窗口作答卡 |
user_choose | 方案 A/B/C 选择（可多选） | AI 窗口作答卡 |
user_input | 文本输入 | AI 窗口作答卡 |
user_presence | 探测用户是否在线 | AI 窗口作答卡 |
user_notify | 非阻塞通知 | 浏览器 Notification |
统一语义：超时可控（前端倒计时 + 服务器同步暂停）、通知到位（Notification + 标题闪烁 + 提示音）、拒绝有语义（预设 + 自定义理由）。
# 1. 启动桥
npx @aiti-ai/aiti-bridge --port 8777
# 2. 配置任意 MCP 客户端（一键注册 stdio shim，幂等；agent 启动带 env AITI_BRIDGE_URL 即接入）
npx @aiti-ai/aiti-bridge --register-shim
# 或 MCP client 直连 HTTP 端点：http://127.0.0.1:8777/aiti/mcp/mcp
# 3. 告诉 AI 目标页面
# 「用 bridge_status 看一下当前有哪些 pageId，然后对 01234/f0 执行 page_snapshot」
- token/secret 认证（SSE / result / event 全部校验）
- secret 防跨页面冲突：只有原页面能复用自己的 instanceId
- 危险命令确认 + 手势桥（transient activation）
- 桥端点默认仅本机监听（127.0.0.1）；页面连接经 claim/secret 校验
- MCP 端点外网鉴权：计划适配 service-tunnels（auth + token 并存）
| 能力 | 说明 | 文档 |
|---|
| Streamable HTTP 传输 | GET /mcp/mcp 持久流 + Mcp-Session-Id，服务端可主动写消息 | MCP Server |
aiti_inbox 消息主通道 | 人发消息/异步作答/页面事件进队列，agent 调工具取走——任何 agent 100% 可用 | 接入 AI agent |
/bridge/push | 人 → AI 主动发消息（sampling 推 / inbox 入队 降级） | MCP Server |
| 消息 session 存储 | 参照 pi session 同款 JSONL（append-only 事件流），consumed 历史保留 | MCP Server |
| cockpit 通用 AI 窗口 | 引导页 + 地址配置中枢 + 操作台；无 aiUrl 时默认打开 | cockpit |
| 消息消费状态 | pending → delivered → consumed，窗口滑动窗口显示 | cockpit |
会话体系详解见 MCP 桥 · 会话，改造 AI agent 见 MCP 桥 · AI agent，人侧界面见 cockpit。
