> ## Documentation Index
> Fetch the complete documentation index at: https://exosphere-auto-translate-docs-20260624-1149.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 仪表板

> 监控 Agent 会话、查看工具调用并管理策略

failproofai 仪表板是一个用于监控 AI Agent 会话和管理策略的本地 Web 应用程序。查看 Agent 在你离开时做了什么。

***

## 启动仪表板

```bash theme={null}
failproofai
```

在 `http://localhost:8020` 打开。

仪表板直接从文件系统读取数据——包括你的 Claude Code 项目文件夹和 failproofai 配置文件。不会向任何远程服务写入数据。

***

## 页面

### 项目

列出在你机器上发现的所有 Claude Code、OpenAI Codex、GitHub Copilot CLI *(测试版)*、Cursor Agent *(测试版)*、OpenCode *(测试版)*、Pi *(测试版)* 和 Gemini CLI *(测试版)* 项目。Claude 项目从 `~/.claude/projects/`（或通过 `CLAUDE_PROJECTS_PATH` 设置的路径）中发现；Codex 项目通过扫描 `~/.codex/sessions/<YYYY>/<MM>/<DD>/*.jsonl` 下的所有记录并按每个会话第一条记录中的 `cwd` 分组来发现；Copilot CLI 项目通过扫描 `~/.copilot/session-state/<sessionId>/workspace.yaml`（可通过 `COPILOT_HOME` 配置）并按其 `cwd` 字段分组来发现；Cursor Agent 项目通过扫描 `~/.cursor/agent-sessions/<sessionId>/`（可通过 `CURSOR_HOME` 配置，并以 `conversations/` 和 `sessions/` 作为备用路径）下的逐会话元数据，从 `meta.json` / `session.json` / `workspace.yaml` 中查找 `cwd` 标量来发现；OpenCode 项目通过 `opencode db --format json` 查询位于 `~/.local/share/opencode/opencode.db` 的 SQLite 数据库来发现（读取 `session` 和 `project` 表并按 `project_id` 分组）；Pi 项目通过扫描 `~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl`（可通过 `PI_SESSIONS_DIR` 配置）下的逐会话 JSONL 记录，并从每个会话的第一条记录中提取 `cwd` 来发现；Gemini CLI 项目通过扫描 `~/.gemini/tmp/<basename>/chats/session-<timestamp>-<uuid-prefix>.jsonl`（可通过 `GEMINI_SESSIONS_DIR` 配置），并从同级 `.project_root` 文本标记中恢复规范 cwd 来发现。被多个 CLI 使用的项目会渲染为单行并显示所有匹配的标记。使用表格上方的 **CLI** 下拉菜单按特定 Agent CLI 筛选；URL 会将你的选择保存为 `?cli=claude|codex|copilot|cursor|opencode|pi|gemini`。

每个项目显示：

* 项目名称（从文件夹路径派生）
* CLI 标记——`Claude Code`（橙色）、`OpenAI Codex`（紫色）、`GitHub Copilot`（蓝色）、`Cursor Agent`（翠绿色）、`OpenCode`（琥珀色）、`Pi`（粉色）和/或 `Gemini CLI`（天蓝色）
* 最近会话活动的日期

点击项目可查看其会话。

### 会话

列出某个项目中的所有会话。每个会话显示：

* 会话 ID
* 开始和结束时间戳
* 工具调用次数
* Hook 活动次数（触发的策略数）

使用日期范围筛选器和会话 ID 搜索来缩小列表范围。会话支持分页。

点击会话可打开会话查看器。

### 会话查看器

会话查看器回答了自主 Agent 的核心问题：Agent 做了什么，是否保持在正轨上？标题旁的 CLI 标记表明该会话是 Claude Code、OpenAI Codex、GitHub Copilot CLI、Cursor Agent、OpenCode、Pi 还是 Gemini CLI 的记录。它显示会话中发生的所有事情的时间线：

* **消息** - Claude 的文本回复和用户提示
* **工具调用** - Claude 调用的每个工具，包括其输入和输出
* **策略活动** - 针对每个工具调用，显示哪些策略触发了以及返回了什么决策

顶部的统计栏显示会话时长、工具调用总数以及 hook 决策摘要（allow / deny / instruct 计数）。

点击 **Download Logs** 按钮可导出会话。对于 Claude Code、Codex、Copilot、Cursor、Pi 和 Gemini 会话，你将获得磁盘上原始的 JSONL 记录（逐字节）；对于 OpenCode（其会话存储在 SQLite 中而非磁盘文件）,你将获得一个镜像底层 `session` / `messages` / `parts` 表的 JSON 文档。

### 审计

一份对 Agent 在过去会话中实际行为的个性化报告。运行与 `failproofai audit` CLI 相同的扫描，但将其渲染为单屏可分享的海报，以及四个折叠以下的区块：

1. **海报** — 填满第一个视口。自包含的 PNG 截图区域，包含 failproof\_ai 品牌标识 + 审计标签 · 原型索引（`№ NN of 08`）+ 审计日期 · 数字评分（0–100）+ 百分位排名标记（`top 15%`）· 原型名称（`the optimist`、`the cowboy`、`the explorer`、`the goldfish`、`the paranoid architect`、`the precision builder`、`the hammer`、`the ghost` 之一）+ 3 关键词条 · `// only N% of agents are this archetype` 稀有度说明 · 8×8 像素印记图块 · `audit yours → failproof.ai` 页脚。截图框外有三个分享按钮：`post your archetype`（X 分享意图）、`share on linkedin`、`download poster`。截图通过 `html-to-image` 运行，PNG 与屏幕渲染像素级一致（虚线边框、SVG logo 遮罩、渐变、字体度量——全部保留）。
2. **优势** — 平静的 ✓ 行列表，列出 Agent 已经做对的行为，从实时审计数据中派生（干净的工具调用率、无直接推送到主分支、零凭据泄露、零重试风暴）——每项仅在相关策略在审计窗口内记录干净时才会显示。
3. **问题** — 列出遗漏内容的表格，按严重程度排序：`时间 · 遗漏内容 + 本应捕获它的策略 · 严重程度标记 · 出现次数`，其中复现次数显示为 `new`（一次）、`N× seen`（2–9 次）或 `recurring`（10 次以上）。
4. **改进方法** — 平静的行列表，每条对应一个建议策略：白色策略名称、一行描述、右侧的安装命令 + 复制按钮。区块标题显示 `enable all N → projected <score> · <tier>`（应用所有修复后的预期评分），`[install all]` 按钮可复制所有建议策略的组合 `failproofai policy add a b c …` 命令。
5. **下次更好** — 两张并排卡片。左侧：设置提醒（`3d` / `7d` / `14d` / `30d` 周期选择器；通过 `/api/auth/reminder` 登录后持久化）。右侧：解锁 failproof 福利——`invite a friend` 打开一个弹窗，接受逗号/空格/换行分隔的好友邮件列表（每次最多发送 10 个），POST 到 `/api/audit/invite`，后者转发到 api-server 的 `POST /v0/invite`。api-server 从 `invite@failproof.ai` 向每位收件人发送一封邮件，发件人抄送并设置 `Reply-To`，这样收件人可以看到是谁邀请了他们，发件人也会在收件箱中收到副本。匿名用户会先通过 `AuthDialog` 验证，以便在发送邀请前获取发件人邮箱。权益/福利兑现将在后续跟进。

由 `failproofai audit` 运行时驱动——关于底层扫描引擎、支持的标志和每条记录的缓存不变性，请参阅 [Audit CLI](/zh/cli/audit)。仪表板将最新结果缓存在 `~/.failproofai/audit-dashboard.json`（模式 `0600`，单槽位，新运行覆盖），因此重新访问是即时的；**每条记录和完整结果的缓存在读取时一旦超过 7 天即被拒绝**，这样仪表板就不会静默返回一周前的结果——超过 TTL 后，`/audit` 会回退到空状态并提示重新运行。点击报告底部附近的 `[ re-audit now ]` 会向 `/api/audit/run` POST `noCache: true`——重新审计会绕过每条记录的缓存并从头重新扫描每条记录，而不是静默返回缓存结果——仪表板以 1Hz 轮询 `/api/audit/status` 直到运行完成；运行期间顶部会显示一个带有计时器的固定粉色进度条，成功后新结果会原地替换（无需全页刷新；重新审计失败时会保留之前的报告）。失败时进度条变红，并根据 `RerunError.kind`（`timeout` / `network` / `post_failed`）显示相应提示。空状态（无缓存或已过期）和零会话状态（缓存存在但扫描未找到记录）会分别显示。

### 策略

一个包含两个标签页的页面，用于管理策略和查看活动。

<Tabs>
  <Tab title="策略标签页">
    * 从单个面板多选 failproofai 保护哪些 Agent CLI——Claude Code、OpenAI Codex、GitHub Copilot、Cursor Agent、OpenCode、Pi 和 Gemini CLI 均有一行显示安装状态（`Active` / `Detected` / `Inactive`）、用户范围的设置路径和品牌色调。勾选或取消勾选所需的 CLI，然后点击 `Apply changes` 一步完成安装/卸载差异。PATH 上检测到二进制文件的 CLI 会被预先勾选。
    * 单击即可开启或关闭单个策略（写入 `~/.failproofai/policies-config.json`——所有已安装 CLI 共享）
    * 展开策略以配置其参数（适用于支持 `policyParams` 的策略）
    * 设置自定义策略文件路径
  </Tab>

  <Tab title="活动标签页">
    * 所有会话中触发的每个 hook 事件的完整分页历史记录
    * 按决策、事件类型、CLI（Claude Code / OpenAI Codex / GitHub Copilot *(测试版)* / Cursor Agent *(测试版)* / OpenCode *(测试版)* / Pi *(测试版)* / Gemini CLI *(测试版)*）、策略名称或会话 ID 筛选
    * 每行显示：时间戳、策略名称、决策、CLI 标记（橙色 = Claude Code，紫色 = OpenAI Codex，蓝色 = GitHub Copilot，翠绿色 = Cursor Agent，琥珀色 = OpenCode，粉色 = Pi，天蓝色 = Gemini CLI）、工具名称、会话 ID 以及 deny/instruct 决策的原因
    * 点击会话 ID 可打开其记录——查看器会自动检测是哪个 CLI 触发了 hook（Claude `~/.claude/projects/…`、Codex `~/.codex/sessions/…`、Copilot CLI `~/.copilot/session-state/<id>/events.jsonl`、Cursor Agent `~/.cursor/agent-sessions/<id>/events.jsonl`、OpenCode `~/.local/share/opencode/opencode.db`、Pi `~/.pi/agent/sessions/<encoded-cwd>/<id>.jsonl`、Gemini CLI `~/.gemini/tmp/<basename>/chats/<session>.jsonl`），并在标题中渲染匹配的 CLI 标记
  </Tab>
</Tabs>

***

## 自动刷新

仪表板在顶部导航中提供自动刷新开关。启用后，当前页面会定期刷新，以实时显示新会话和策略活动。这对于监控长时间运行的自主 Agent 会话至关重要。

***

## 禁用页面

如果只需要仪表板的某些部分，可将 `FAILPROOFAI_DISABLE_PAGES` 设置为以逗号分隔的页面名称列表：

```bash theme={null}
FAILPROOFAI_DISABLE_PAGES=policies failproofai
```

有效值：`policies`、`projects`、`audit`。

***

## 配置项目路径

默认情况下，仪表板从标准 Claude Code 项目目录读取。对于自定义设置，可以覆盖此路径：

```bash theme={null}
CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai
```

***

## 从非 localhost 主机访问

在**开发模式**（`npm run dev`）下运行仪表板，并从 `localhost` 以外的主机名访问时——例如自定义域名、远程 IP 或隧道 URL——你可能会看到如下警告：

```text theme={null}
⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com".
```

这是 Next.js 阻止对其 HMR（热模块重载）websocket 的跨域访问，这是一个仅限开发环境的功能。要允许你的主机，请使用 `--allowed-origins` 标志：

```bash theme={null}
npm run dev -- --allowed-origins dashboard.example.com
```

对于多个主机或 IP，传入以逗号分隔的列表：

```bash theme={null}
npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5
```

你也可以设置 `FAILPROOFAI_ALLOWED_DEV_ORIGINS` 环境变量：

```bash theme={null}
FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev
```

<Note>
  这仅适用于开发模式。运行 `failproofai`（生产模式）时，不存在 HMR websocket，也不存在跨域开发资源问题。
</Note>