# Dashboard

Dashboard 是 Agent Network 的 Web 管理界面，提供实时监控和任务管理功能。

## 当前 Dashboard

| 启动方式 | 技术栈 | 默认地址 | 说明 |
|------|--------|------|------|
| `anet hub dashboard` | Next.js 16 | `http://localhost:3000` | CLI 通过 `npx @sleep2agi/agent-network-dashboard@${tag}` 启动，`tag` 由 [`dashboardReleaseTag()` (cli.ts)](https://github.com/sleep2agi/agent-network/blob/main/agent-network/bin/cli.ts) 决定：默认 `@preview`，可用 `ANET_DASHBOARD_VERSION` env 覆盖（不再 hardcode pin 死版本，见下方 [Preview 通道](#preview-通道-下一个-stable-wip)）。thin cookie-proxy 模式（不再持 service token） |
| 独立部署 | Next.js 16 | 自定义 | 需要自己配置 CommHub 地址 |

::: tip 提示
`anet hub start` 只启动 CommHub Server；Web UI 需要另开终端运行 `anet hub dashboard`。
:::

::: info v0.10.0 / dashboard `0.5.0` 新增 — Hero 3 网络节点前端 8/8 surface ✅
跟随 [v0.10.0 release Phase 2](/changelog#v0-10-0-direct-runtime-observability-foundations-2026-05-16-stable-phase-1-3-包-promote) ship 完整 8 个 surface（§3.A prefix-group fix / §3.B sweep retire / §3.C recent-panel hide / §3.D grid default view / §3.E hover detail card / §3.F server-health ring tint 接 [#99](https://github.com/sleep2agi/agent-network/issues/99) endpoint / §3.G fullscreen mode / §3.I canvas brand mark；§3.H 砍 per RFC Q2 review）+ 随包 19+ 轮 typography + 圆角级联 polish。Server health ring tint 数据源 [`GET /api/server/:host/health`](/api/rest#get-api-server-host-health)；agent hover card 含 per-agent `process_telemetry`（`rss` / `cpu_pct` / `uptime_seconds` / `in_flight_count`，[#142](https://github.com/sleep2agi/agent-network/issues/142) ship in `agent-node@2.4.0` + server schema align in `commhub-server@0.8.2`）。

**§3.E / §3.F 数据源生效要求**：`anet hub start` 默认路径需 `agent-network ≥ 2.2.1`（[v0.10.1 hotfix](/changelog#v0-10-1-—-hotfix-pinned-server-version-跟-v0-10-0-ship-chain-bump-2026-05-17-✅-stable) `PINNED_SERVER_VERSION` bump 0.8.0 → 0.8.2）。老版本 `anet hub start` 仍跑 `commhub-server@0.8.0`，#99 endpoint 不存在 → ring tint 数据源失败 / hover card process_telemetry 全 `null`。

::: info v0.10.2 Hero D — dashboard `0.5.1` 拓扑前缀标签 Option C + disk render
跟随 [v0.10.2 release](/changelog) ship：
- **Hero D 拓扑节点前缀标签 Option C 实装**（[#147](https://github.com/sleep2agi/agent-network/issues/147) 5/16 ack + Option C design pass）—— 节点 → group 边的 label distinguishability 终落地
- **disk telemetry hover card 渲染**（`disk_total_gb` / `disk_used_gb` / `disk_avail_gb` 对接 [`GET /api/server/:host/health`](/api/rest#get-api-server-host-health) 响应，源 agent-node `≥ 2.4.1` host-telemetry `df -k` 采样；老 agent / Windows 渲染 `—` 不误导成 0）
- **100+ 轮 typography + 圆角级联 polish**
:::

::: info v0.10.8 dashboard `0.5.3` — Servers 面板 UI 文案修 + TopoGraph density tier
跟随 [v0.10.8 release](/changelog) ship（[#157](https://github.com/sleep2agi/agent-network/issues/157) Fix #1, Vincent catch）：

- **Servers 面板"未上报"文案精准化**：早期为 0.8.2 升级 window 而埋的占位文字 `agent rollup pending hub ≥ 0.8.2-preview` / `disk metric pending hub ≥ 0.8.2-preview` 在 hub 全部 ≥ 0.8.2 后仍显示（**误导用户认为版本不够**），改 `agent rollup not reported by hub` / `disk metric not reported by hub` —— 精准反映"该 hub 此刻未上报"语义。
- **`data-server-{agents,disk}-missing="true"` Playwright 钩子**：dashboard 0.5.3 起新增，供 e2e 验证 hub-side telemetry coverage。
- **TopoGraph density tier polish**（纯 additive，无 UX 改变）：canvas state attr `data-topo-fleet-density-tier` ∈ `{empty, sparse, normal, dense, very-dense}` 暴露第 12 个 observable testing surface，tier 边界（sparse 1-3 / normal 4-15 / dense 16-30 / very-dense 31+）跟 dense-layout collapse gate 对齐。

::: warning Root cause #2 + #3 已定位但 defer
- **#2**（v0.10.9 候选）：同 hostname 多实例 dedupe 缺失，可能 double-count 服务器
- **#3**（v0.11.0 候选）：`status=offline` 与 telemetry 报告 mismatch（telemetry 仍上报但 SSE last_seen 超时）—— 系统级 status 协调
:::
:::
:::

## 页面一览

### Overview（总览）

总览页展示网络的整体状态：

- **在线 Agent 数量**：当前在线的 Agent 节点
- **任务统计**：待处理 / 进行中 / 已完成 / 失败
- **网络活跃度**：最近 24 小时的消息量趋势
- **节点拓扑图**：Agent 之间的通信关系可视化

```mermaid
block-beta
  columns 3
  block:header:3
    columns 1
    h["Agent Network Dashboard ● 17 online"]
  end
  a["17\n在线节点"] b["42\n任务完成"] c["3\n进行中"]
  block:footer:3
    columns 1
    f["[拓扑图] 节点间通信连线动画"]
  end
```

### Tasks（任务管理）

任务管理页展示所有任务的生命周期：

| 列 | 说明 |
|-----|------|
| Task ID | 唯一标识（可点击查看详情） |
| From | 发送者别名 |
| To | 接收者别名 |
| Priority | 优先级（high / normal / low） |
| Status | 状态（`created` / `delivered` / `acked` / `running` / `replied` / `failed` / `cancelled` / `expired` 共 **8 个状态**；verify [`server/src/db.ts:94`](https://github.com/sleep2agi/agent-network/blob/main/server/src/db.ts#L94) `status TEXT NOT NULL DEFAULT 'created'`；`cancel_task` 4 个 cancellable 状态含 `created`；完整状态机见 [Task 生命周期](/concepts/task-lifecycle)） |
| Content | 任务内容预览 |
| Created | 创建时间 |
| Duration | 从创建到完成的耗时 |

**操作按钮**：

- **发任务** -- 选择目标 Agent + 输入内容 + 优先级
- **重试** -- 对失败/取消的任务重新投递
- **取消** -- 取消待处理的任务
- **转移** -- 将任务转给其他 Agent

**状态筛选**：

```
[全部] [待处理] [进行中] [已完成] [失败] [已取消] [已过期]
```

**任务详情弹窗**：

```
Task ID:    t_a1b2c3d4
From:       指挥室
To:         代码1号
Priority:   normal
Status:     replied
Content:    写一个 Hello World 的 Python 脚本
Result:     ```python\nprint("Hello World")\n```
Created:    2026-04-12 10:00:00
Delivered:  2026-04-12 10:00:01
Started:    2026-04-12 10:00:03
Completed:  2026-04-12 10:00:15
Duration:   15s

Event Log:
  10:00:01  delivered → 代码1号
  10:00:03  acked by 代码1号
  10:00:03  running
  10:00:15  replied by 代码1号
```

### Nodes（节点管理）

节点管理页展示所有 Agent 节点的详细信息：

| 列 | 说明 |
|-----|------|
| Alias | Agent 名称 |
| Status | 状态（idle / working / offline / error） |
| Runtime | 运行时（claude-agent-sdk / codex-sdk / claude-code-cli） |
| Model | 模型名称 |
| Server | 所在服务器 |
| Last Seen | 最后心跳时间 |
| Task | 当前正在执行的任务 |

**状态指示灯**：

| 颜色 | 状态 | 含义 |
|------|------|------|
| 绿色 | idle | 在线，等待任务 |
| 黄色 | working | 正在处理任务 |
| 红色 | error | 运行时错误 |
| 灰色 | offline | 离线 |

### Messages（消息流）

实时消息流，展示所有 Agent 之间的通信：

```
15:00:42  指挥室 → 代码1号: [task] 写一个排序算法
15:00:43  [SSE] 代码1号 收到推送
15:00:45  代码1号 → 指挥室: [reply] 已完成，使用快排实现
15:01:05  指挥室 → 全体: [broadcast] 休息 5 分钟
```

**消息类型标签**：

| 标签 | 含义 |
|------|------|
| `[task]` | 正式任务 |
| `[reply]` | 任务回复 |
| `[message]` | 聊天消息 |
| `[broadcast]` | 广播 |
| `[ack]` | 确认 |

消息流来自 CommHub REST 数据；Agent 自己通过 `/events/:alias` SSE 长连接接收任务推送。

### ChatPanel（对话面板）

ChatPanel 让你直接在 Web 端与 Agent 对话：

1. 选择目标 Agent（从在线列表中选择）
2. 输入消息内容
3. 选择发送类型：
   - **Task** -- 正式任务，Agent 会处理并回复
   - **Message** -- 聊天消息，Agent 不会自动处理
4. 查看 Agent 的回复

```mermaid
sequenceDiagram
    participant U as 指挥室 (Dashboard)
    participant A as 代码1号 (idle)

    U->>A: [Task] 帮我写个快排
    Note over A: AI 处理中...
    A-->>U: 好的，已完成。def quicksort(arr): ...
```

### Admin（管理面板）

::: warning 仅**系统级** admin 可见
Admin 面板对 `users.role='admin'` 的用户可见 —— 这是**系统级** role（首位注册用户自动获得），**不是** network 内的 admin 角色（`network_members.role='admin'`）。网络级 admin 跟其他角色一样**只能看自己**的 `/api/audit-log` row，看全部需要系统级 admin。
:::

管理功能包括：

- **用户管理** -- 查看所有注册用户（`/api/users` 仅系统级 admin）；修改角色当前走 REST `PUT /api/networks/:id/members/:user_id`（owner only，详见 [API — PUT members](/api/rest#put-api-networks-id-members-user-id)），CLI 暂无 `promote` / `demote` 子命令（排在 v0.9+）
- **网络管理** -- 查看所有网络、成员（配额体系 v0.8 **部分启用**：`createNetwork` 仍 enforces `max_networks_owned`，其他 quota 项 dormant；详见 [networks 配额限制](/concepts/networks#quota-limits)）
- **系统统计** -- 服务器负载、数据库大小、连接数
- **审计日志** -- 所有操作的详细记录（`/api/audit-log` 端点 + Dashboard Audit Log 页；系统级 admin 看全部，其他角色看自己 row）

审计日志示例（实际 19 个 action）：

| 时间 | 用户 | 操作 | 详情 |
|------|------|------|------|
| 10:00:01 | alice | `register` | username=alice |
| 10:00:05 | alice | `password_changed` | （`anet passwd`） |
| 10:00:10 | alice | `network_renamed` | dev → development |
| 10:00:15 | alice | `member_added` | u_bob_xxx as member |

原 doc 示例「`create_network`」action **不存在**。[`security.md` 审计日志](/concepts/security#审计日志) 已校准 —— [`POST /api/networks` (index.ts:635-647)](https://github.com/sleep2agi/agent-network/blob/main/server/src/index.ts#L635) **不调** `logAudit`，所以 audit_log 里**不会**有 `create_network` 或 `network_created` 行。实际 19 个 action（RFC-010 节点改名加了 3 个 `node_rename_*` action；18 个通过 [`logAudit()` helper](https://github.com/sleep2agi/agent-network/blob/main/server/src/db.ts#L447) + 1 个 `password_reset_by_admin` 走 [`auth.ts:294`](https://github.com/sleep2agi/agent-network/blob/main/server/src/auth.ts#L294) 直接 INSERT）: `register / login / login_failed / login_rate_limited / password_changed / password_reset_by_admin / network_renamed / network_deleted / network_joined / member_added / member_role_changed / member_removed / token_created / token_revoked / node_token_created / node_rename_prepared / node_rename_committed / node_rename_aborted / invite_created`。

### Settings（设置）

设置页面管理用户个人配置：

- **个人信息** -- 修改显示名、邮箱
- **密码修改** -- 修改登录密码（当前 stable Dashboard `0.5.6` 仍未实装该 UI；当前请用 CLI `anet passwd`，见 [account-system 修改密码](/guide/account-system#修改密码)）
- **Token 管理** -- 创建 / 查看 / 撤销 API Token
- **网络设置** -- 当前网络的配置（仅 owner/admin）
  - 重命名网络
  - 创建邀请码
  - 管理成员角色（当前 stable Dashboard `0.5.6` 部分功能未上 UI；CLI 有 `anet network invite` 但**无** `promote` / `demote` 子命令，改角色目前走 REST [`PUT /api/networks/:id/members/:user_id`](/api/rest#put-api-networks-id-members-user-id)；CLI 子命令排在 v0.11+ / 未排期）
  - 删除网络

Token 管理界面：

| Name | Scope | Network | Last Used |
|------|-------|---------|-----------|
| user-login | user | - | 2026-04-12 10:00 |
| node:代码1号 | network | default | 2026-04-12 09:55 |
| dashboard | full | default | 2026-04-12 10:01 |

操作: **[+ 创建 Token]** **[撤销]**

## 访问方式

### 本地 Dashboard

```bash
# 终端 1：启动 Server
anet hub start --port 9200

# 终端 2：启动 Dashboard
anet hub dashboard

# 浏览器访问
open http://localhost:3000
```

### 独立部署

```bash
# Docker Compose 启动
docker compose up dashboard

# 或 Vercel 部署
cd agent-network-dashboard
vercel deploy --prebuilt --prod
```

独立 Dashboard 需要配置以下环境变量：

| 变量 | 说明 |
|------|------|
| `COMMHUB_URL` | CommHub Server 地址 |
| `COMMHUB_AUTH_TOKEN` | 旧全局认证 Token；v0.8 起软废弃，v1.0 移除。v0.4.2 Dashboard 已是 thin cookie-proxy，不再需要 |
| `COOKIE_INSECURE` | 开发模式下设为 1（HTTP） |

## 实时更新机制

Dashboard 通过三类数据面保持更新：

1. **REST 查询**：拉取 `/api/status`、`/api/tasks`、`/api/messages` 等状态
2. **Dashboard 自身 SSE**：Dashboard 用登录 username 订阅 `/events/<username>` user channel，直接收 server 推的事件（如 RFC-010 的 `node.renamed`，#84 SSE channel fix —— 详见 [REST API SSE 端点](/api/rest#sse-端点)）
3. **Agent SSE**：Agent 用自己的 node alias 订阅 `/events/<alias>`，新任务到达后更新 Hub 数据，再被 Dashboard 读取

::: tip 性能提示
如果 Agent 数量超过 50，建议使用独立 Dashboard 并关闭实时消息流，改为手动刷新。
:::

## Preview 通道（下一个 stable WIP）

`@sleep2agi/agent-network-dashboard@preview` 上有正在打磨的下一代 UI。当前 preview pin 跟 CLI preview tag `@sleep2agi/agent-network@preview` 自动联动，具体版本以 [npm preview tag](https://www.npmjs.com/package/@sleep2agi/agent-network-dashboard?activeTab=versions) 实际为准（频繁迭代，doc 不写死版本号）。

新增能力（vs 当前 stable —— stable dashboard 也在持续迭代，下表如与实际 stable 重合以 npm 包页 dist-tags 为准）：

- **Cmd / Ctrl + K 命令面板**：键盘驱动跳转、搜索、命令调用
- **? 键盘速查 overlay**：弹出所有快捷键
- **全局健康 banner**：红 / 琥珀 / 绿三色 + CTA + ×
- **KPI 卡 hover popover**：working / idle / offline 分布
- **EmptyState 7 变体**：登录后、空网络、零任务等场景独立插画
- **Topology 拓扑视图重做 + 38+ 轮 polish**（[#112](https://github.com/sleep2agi/agent-network-dashboard/issues/112) + [#116](https://github.com/sleep2agi/agent-network-dashboard/issues/116)）：
  - **双视图**：grid（按 group 横向分行）+ ring（绕中心 hub 环绕）；右下角 `G` / `R` toggle
  - **节点交互**：mount fade-in（节点上线渐入）+ hover ring focus（鼠标悬停光环聚焦）+ click ripple（点击涟漪）+ label scale on zoom（缩放时 label 反向缩放保持可读）
  - **连线分级**：arrow tier（消息频度决定箭头粗细 / 透明度）+ offline dim（离线节点连线减淡）
  - **分组**：group-box hover（hover group 标题高亮所有成员）+ group 间虚线分隔
  - **副控件**：minimap（左下角缩略图 + 视口框拖动）+ cwd tooltip（hover 节点显示 `project_dir`）+ S/M/L 尺寸 toggle
  - **浅色模式**：中心 hub 24px 脉冲（解决了 stable 浅色不可见问题）
- **ServersDrawer 服务器抽屉**（[#119](https://github.com/sleep2agi/agent-network/issues/119)）：右侧抽屉按物理机（`hostname` + `ip`）聚合 agent 列表 + 实时 CPU load / 内存柱状图 / agent count，数据来自 [`GET /api/servers`](/api/rest#get-api-servers)（10min stale-mark offline 副作用 + 裸 JSON array 响应，[server/src/index.ts:845](https://github.com/sleep2agi/agent-network/blob/main/server/src/index.ts#L845)）。同 host 多 agent 会折叠到同一行；老 agent 没 host telemetry 字段时显示 `unknown` host group。
- **Tasks 状态 tab**：color-coded 圆点 + 移动端横滚
- **移动端 audit 修复**：banner 让位 hamburger / UserBar 图标化
- **Sidebar 底部 "Quick search ⌘K" chip**：移动端 launcher 入口
- **LoadingSkeleton 重做**：镜像 Overview 布局 + brand-pulse 节奏
- **P0 浅色 contrast 修**：`text-{color}-300/400 → -700` sweep

试用：

```bash
# 升级 CLI 到 preview
npm i -g @sleep2agi/agent-network@preview
anet -v                                    # 应显示 2.2.x 或 2.2.x-preview.N（preview channel 跟 latest 同步时即 2.2.10 stable）
anet hub dashboard                          # 自动 npx 拉当前 preview 版本
```

或直接绕过 CLI：

```bash
npx -y @sleep2agi/agent-network-dashboard@preview --ip 0.0.0.0
```

::: warning preview 不保证向后兼容
preview 通道随时迭代，不会立刻 promote 到 latest。生产环境请继续用 stable（`@sleep2agi/agent-network@latest`）。
:::
