内容
# ✳ 代理端车
[](https://github.com/smarchetti/agent-sidecar/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/agent-sidecar)
[](https://agent-sidecar.vercel.app/docs.html)
**编码代理的可视化画布。** 您的代理在浏览器中向您展示交互式 HTML — 设计选项、表单、预览、仪表盘 — 并且您的点击直接反馈到对话中。与 Claude Code、Cursor、Codex 或任何 MCP 客户端配合使用。
[](https://agent-sidecar.vercel.app/)
> *"给我显示设置屏幕的三个布局选项"* → 三个可点击的模型出现在画布上 → 您点击其中一个 → Claude 继续处理您的选择。
agent-sidecar 是一个 MCP 服务器，带有嵌入式 Web 服务器，包装为 Claude Code 插件 — 可从[任何 MCP 客户端](#与其他代理配合使用)。它不需要推送机制（适用于阻止 Claude Code 通道的组织）：浏览器到代理的返回路径是一个长轮询，服务器将其转换为普通的工具输出。
**网站和完整文档 → [agent-sidecar.vercel.app](https://agent-sidecar.vercel.app/)** ([文档](https://agent-sidecar.vercel.app/docs.html))
## 快速开始
在您的 PATH 上需要 [Bun](https://bun.sh)。在任何 Claude Code 会话中：
```
/plugin marketplace add smarchetti/agent-sidecar
/plugin install agent-sidecar@agent-sidecar
```
重启 Claude Code，然后请求可视化内容： *"在画布上给我显示三个布局选项，用于定价页面。"* 浏览器打开，工件渲染，点击回答 Claude。
## 与其他代理配合使用
agent-sidecar 是一个标准的 MCP stdio 服务器，因此任何 MCP 客户端都可以运行它 — 插件只是 Claude Code 包装。将您的代理指向：
```json
{ "mcpServers": { "agent-sidecar": { "command": "bunx", "args": ["agent-sidecar"] } } }
```
| 代理 | 配置文件 |
| --- | --- |
| Cursor | `.cursor/mcp.json`（项目）或 `~/.cursor/mcp.json`（全局） |
| VS Code (Copilot) | `.vscode/mcp.json` — 相同条目在 `"servers"` 键下 |
| Codex CLI | `~/.codex/config.toml` — `[mcp_servers.agent-sidecar]` 带有 `command`/`args` |
| Gemini CLI | `~/.gemini/settings.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
所有内容都会转移：工具、画布、令牌身份验证、`.sidecar/` 文件。两个 Claude 特色细节：注入的浏览器助手仍命名为 `claude.send()`，后台观察者模式需要一个可以在后台运行 shell 命令的代理 — 阻塞的 `await_interaction` 工具在任何地方都有效。
## 工作原理
一个进程，两个界面：
```
Claude Code ⇄ MCP/stdio ⇄ agent-sidecar ⇄ HTTP 127.0.0.1 ⇄ 浏览器画布
│
└── POST /api/webhook ← CI、脚本、任何内容
```
1. **Claude 显示** — `create_artifact` 在画布上放置一个完整的 HTML 文档（SSE 直播；新工件获取焦点，更新热重载）。
2. **您点击** — 每个工件都注入一个 `claude.send(payload)` 助手。它跨越一个 postMessage 桥，离开沙盒 iframe；画布外壳将其转发到带有会话令牌的 webhook。
3. **Claude 继续** — 要么一个阻塞的 `await_interaction` 调用立即返回您的有效载荷（快速决策），要么一个后台 `curl /api/wait` 观察者重新调用 Claude 当您点击时（长时间等待，Claude 同时继续工作）。
每次交互也追加到 `.sidecar/interactions.jsonl` — 一个持久的、可 `tail -f` 的审计日志。
## 参考（简版）
**MCP 工具** — `create_artifact`、`update_artifact`、`await_interaction`（阻塞，`artifact_id` 过滤）、`get_interactions`（排空）、`list_artifacts`、`remove_artifact`。
**HTTP** — `GET /` 画布 · `GET /events` SSE · `GET /artifact/:id` · `POST /api/webhook`（令牌）· `GET /api/wait` 长轮询（令牌）· `GET /health`。
**会话** — 每个代理会话运行自己的 agent-sidecar：端口 `8765` 是首选，如果被占用则使用临时端口。坐标（端口、URL、身份验证令牌）存活在 `.sidecar/session.json` 中，这是外部系统推送事件的方式：
```bash
url=$(jq -r .url .sidecar/session.json); token=$(jq -r .token .sidecar/session.json)
curl -X POST -H "X-Sidecar-Token: $token" -d "build failed on main" "$url/api/webhook"
```
完整的参数表、工件创作模式和安全模型在 **[文档](https://agent-sidecar.vercel.app/docs.html)** 中。
## 安全
本地主机绑定；一个随机的每个会话令牌需要在 `/api/webhook` 和 `/api/wait` 上（击败来自 localhost 网页的跨站点 POST 请求）；工件在不透明源的沙盒 iframe 中运行，无权访问令牌、画布外壳、存储或同源网络 — `claude.send()` 是他们的唯一输出通道。不要隧道或端口转发服务器：任何到达 webhook 的内容最终都放在 Claude 前面。 [详情](https://agent-sidecar.vercel.app/docs.html#security)。
## 开发
```bash
bun install
bun test # 24 个端到端测试，覆盖真实的 MCP stdio
claude --mcp-config dev.mcp.json # 运行您的工作副本（禁用插件）
```
源代码是 `src/sidecar.ts`（整个服务器）和 `src/canvas.html`（浏览器外壳，内联到 bundle 中）。发布：增加 `package.json`、`.claude-plugin/plugin.json` 中的 `agent-sidecar@<version>` 固定值和 CHANGELOG，然后推送并标记 `vX.Y.Z` — GitHub Actions 测试、发布到 npm 并具有溯源信息、并剪切发布。
## 许可证
MIT
