内容
# 代理仪表盘
**您的代理在此报告。** 一个自托管的AI代理推送 inbox — 在Cloudflare的免费计划上部署您自己的，并且任何代理（Claude Code、Codex、Cursor、Antigravity、Kimi或原始ChatGPT/Claude聊天）都可以向您的手机发送更新并**询问您一个问题并等待您的答案**，然后继续。
这类似于"ntfy for agents，具有回复按钮"。供应商中立，单用户，免费运行。
<p align="center"><img src="public/icon.svg" width="96" alt="代理仪表盘"></p>
---
## 为什么
每个AI供应商都有一个配套应用程序 — 但它只与**它们自己的**代理对话。当您在Claude Code/Codex/Cursor中启动一个长时间的研究运行、重构或构建时，您要么会盯着终端，要么会错过它完成或卡住的时刻。
代理仪表盘是所有这些的**一个** inbox：
- 🔔 **推送更新** — 里程碑和完成情况会作为通知出现在您的手机上（可安装的PWA，适用于iOS + Android）。
- ❓ **询问并等待** — 代理可以发布一个问题（一个选择或整个表单）并轮询，直到您回答，然后继续。 *"我完成了研究 — 用于推介的VC或客户框架？"* → 您点击 → 它继续进行。
- 🧱 **结构化消息** — 代理发送类型化的块（markdown、进度条、表格、表单），而不是原始文本。安全渲染，永远不会作为HTML。
- 🔌 **连接任何东西** — 一个便携的[技能](skills/agent-dash/SKILL.md)，一个一行[MCP](#连接代理)服务器，一个OpenAPI规范用于ChatGPT操作，以及[Claude Code钩子](examples/claude-code-hooks)。
- 🆓 **免费托管** — 一个Cloudflare Worker + D1 + KV。没有Durable Objects，没有Postgres，没有Firebase。舒适地适应一个人的免费层。
## 部署您自己的（≈5分钟）
您需要一个免费的[Cloudflare账户](https://dash.cloudflare.com/sign-up)和Node 20+。
```bash
git clone https://github.com/Prajeevan/agent-dash.git
cd agent-dash
pnpm install # 或 npm install
npx wrangler login # 使用您的Cloudflare账户授权wrangler
# 创建数据库 + KV，然后将它们的ID写入wrangler.jsonc：
npx wrangler d1 create agent-dash
npx wrangler kv namespace create SESSIONS
# → 粘贴打印的database_id和id到wrangler.jsonc
pnpm setup # 生成密钥，设置机密，迁移DB，部署
```
`pnpm setup`打印您的**工作器URL**，一个**神奇的登录链接**，和您的**代理连接代码段**。然后：
1. **扫描打印的二维码**与您的手机（或打开链接）→ **添加到主屏幕** → 打开应用程序 → **设置 → 启用通知**。
2. 给代理MCP代码段或[技能](skills/agent-dash/SKILL.md)。
重新运行`pnpm run login`，随时获取一个新的15分钟登录链接 + 二维码（在您的终端中本地渲染 — 神奇链接令牌永远不会离开您的机器）。重新运行`pnpm setup --rotate`以重新生成所有密钥。
## 连接代理
**MCP**（Claude Code、Cursor、Codex、任何MCP客户端）— 一个条目：
```json
{
"mcpServers": {
"agent-dash": {
"url": "https://agent-dash.your-name.workers.dev/mcp",
"headers": { "Authorization": "Bearer YOUR_AGENT_KEY" }
}
}
}
```
工具：`notify(title, blocks?, priority?)`，`ask(title, blocks)`，`wait_for_answer(question_id)`。
**技能** — 直接从GitHub安装到任何Agent-Skills运行时（Claude Code、Cursor、Codex、…）：
```bash
npx skills add Prajeevan/agent-dash
```
这将`skills/agent-dash/SKILL.md`放入您的代理中，以便它知道如何到达您的中心；然后给它您的URL + `AGENT_KEY`。
**curl**（任何可以发出HTTP请求的工具，包括原始聊天）— 一行命令：
```bash
curl -X POST "$AGENT_DASH_URL/api/v1/events" \
-H "Authorization: Bearer $AGENT_KEY" -H "Content-Type: application/json" \
-d '{"agent":"claude","title":"Build finished","priority":1}'
```
**CLI** — [`npx agent-dash`](cli)连接代理，在您的手机上登录（二维码），并从脚本发送更新/问题：
```bash
npx agent-dash login # 保存 + 验证您的中心URL和代理密钥
npx agent-dash connect # 编写./.mcp.json为您的代理
npx agent-dash notify "Build finished" --priority 1 --project "API"
```
**ChatGPT操作** — 导入`https://your-url/api/v1/openapi.json`。
**Claude Code钩子** — [插入开始/完成/需要输入推送](examples/claude-code-hooks)。
## 工作原理
```
代理 ──POST /api/v1/events─────▶ Cloudflare Worker (TanStack Start SSR + API)
──POST /api/v1/questions──▶ ├─ /api/v1/* 代理REST (bearer AGENT_KEY)
◀─GET /api/v1/questions/:id ├─ /mcp 无状态MCP
├─ /app 仪表盘PWA（神奇链接会话）
您（PWA） ◀── Web推送（VAPID） ─── └─ 绑定：D1（事件/问题/订阅），KV（会话）
──轮询馈送同时打开─▶ Cron：过期问题 + 清理旧事件
```
- **没有Durable Objects。** 交付是Web Push（实时，免费）加上轮询 — 代理每10秒检查答案；仪表盘仅在选项卡打开时轮询游标馈送。单用户工作负载保持在免费限制内。
- **两个凭证，独立的关注点。** `AGENT_KEY`（代理发布/轮询）和`APP_SECRET`（签名您的神奇登录链接 + 会话）。它们独立轮换。会话存储在KV中，带有TTL；"全局注销"会增加一个纪元，使所有会话失效。
- **块，而不是HTML。** 代理消息是`zod`验证的类型块；UI渲染一组已知的 — 代理提供的标记永远不会执行。
参见[`PLAN.md`](PLAN.md)以获取完整设计原理。
## 技术
TanStack Start（React 19）在Cloudflare Workers · D1 · KV · Web Push（手工制作的VAPID + RFC 8291在WebCrypto上，无Node依赖）· Vite · TypeScript。
开发：`pnpm dev`。类型检查：`pnpm typecheck`。部署：`pnpm run deploy`。
## 即时模式（可选）
默认情况下，交付是通过轮询（免费层，没有Durable Objects）。要获取亚秒级实时更新，只需切换一个标志：在`wrangler.jsonc`和`pnpm run deploy`中设置`"INSTANT": "1"`。这激活了一个**休眠的Durable Object** — 休眠的套接字不会计费时长，因此对于一个用户来说，它仍然是免费层友好的。仪表盘会自动从轮询切换到实时的WebSocket。将其设置回`"0"`以禁用。
## 路线图
- [x] 通过休眠的Durable Object（上面的可选标志）实现即时模式。
- [ ] 用于原生应用商店构建的电容器壳，当PWA推送不方便时。
- [ ] 更多块类型（图表，差异） — 欢迎PR（原始HTML块由于设计原因将被拒绝）。
## 许可证
MIT — 见[LICENSE](LICENSE)。单用户核心永久保持MIT。
