> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dashboard 总览

> comet dashboard 是一个本地只读浏览器仪表盘：用图形界面查看活跃和归档的 change、五阶段进度、产物分组、任务完成度、风险和 Git 快照，支持亮色/暗色主题与持久化偏好。

`comet dashboard` 启动一个**本地只读**的浏览器仪表盘，把命令行里散落在多个文件里的状态——活跃和归档的 change、五阶段进度、产物清单、任务完成度、verify 结果、下一步建议、风险项和 Git 快照——汇总成一个可视化界面。

它**只读**，不会修改任何文件，可以随时安全启动，适合在开发过程中常驻一个标签页观察进度。

仪表盘支持亮色和暗色两种主题（见下方[主题切换](#主题切换：亮色-暗色)）：

<p align="center">
  <img src="https://mintcdn.com/comet-bb5f5294/NLqKFpbM6BQ5m8iA/img/dashboard-light.png?fit=max&auto=format&n=NLqKFpbM6BQ5m8iA&q=85&s=2e3da5e7533705e2f7a6c943ff745b37" alt="Comet Dashboard 亮色模式" width="800" data-path="img/dashboard-light.png" />
</p>

<p align="center">
  <img src="https://mintcdn.com/comet-bb5f5294/NLqKFpbM6BQ5m8iA/img/dashboard-dark.png?fit=max&auto=format&n=NLqKFpbM6BQ5m8iA&q=85&s=434b003e8bacac69a688cad0e75e64ae" alt="Comet Dashboard 暗色模式" width="800" data-path="img/dashboard-dark.png" />
</p>

<p align="center">活跃变更概览：阶段步进条、产物分组、任务完成度环形图与风险提示</p>

<p align="center">
  <img src="https://mintcdn.com/comet-bb5f5294/NLqKFpbM6BQ5m8iA/img/dashboard-preview.png?fit=max&auto=format&n=NLqKFpbM6BQ5m8iA&q=85&s=dd24be270131665c2930fa1c24b6b982" alt="Comet Dashboard md预览" width="800" data-path="img/dashboard-preview.png" />
</p>

<p align="center">支持产物markdown预览</p>

## 启动

在项目根目录运行：

```bash theme={null}
comet dashboard
```

默认会在 `http://localhost:4321` 启动并自动打开浏览器。终端会显示：

```text theme={null}
Comet Dashboard running at http://localhost:4321
Press Ctrl+C to stop.
```

完整命令选项和脚本/CI 用法见 [comet dashboard 命令](/zh/cli/dashboard)。

<Info>
  服务器只绑定 <code>127.0.0.1</code>（localhost），不对外暴露。静态文件服务有路径穿越防护，产物预览有大小限制（256 KiB，超出标记 <code>truncated</code>）。
</Info>

## 界面布局

仪表盘采用三栏布局：左侧导航栏、中间变更详情、右侧侧边面板，顶部是项目信息和工具栏。

```mermaid theme={null}
flowchart LR
    A["左侧 Sidebar<br/>工作区导航"] --- B["顶部 Topbar<br/>搜索 / 刷新 / 主题切换"]
    B --- C["中间 Dashboard<br/>概览卡片 + 变更详情"]
    C --- D["右侧 SidePanel<br/>下一步 / 风险 / Git 快照"]
    D --- E["产物抽屉<br/>点击产物预览内容"]
```

### 项目概览卡片

页面顶部是五张汇总卡片，每张都有一个从 0 开始的数字动画，一眼看清整个项目的健康度：

| 卡片            | 含义                     | 健康状态                |
| ------------- | ---------------------- | ------------------- |
| **活跃变更**      | 当前 repo 中进行中的 change 数 | 标记「进行中」             |
| **已归档变更**     | 历史迭代数                  | 标记「已完成」             |
| **Verify 失败** | verify 阶段失败的 change 数  | 0 时标记「健康」，否则标记「阻塞」  |
| **未完成任务**     | 跨变更统计的未完成任务项           | 0 时标记「清零」，否则标记「待办」  |
| **Git 未提交**   | 工作区脏文件数                | 0 时标记「干净」，否则标记「未提交」 |

### 变更工作区

概览下方是变更工作区，左侧是 **Changes Explorer** 列表，右侧是被选中 change 的详情和侧边面板。

**Changes Explorer** 支持：

* **标签页筛选**：活跃 / 已归档 / 全部
* **搜索框**：按 change 名称、工作流、阶段实时筛选
* **每张卡片**显示：change 名称、当前阶段、任务完成度进度条（completed/total）和 verify 状态药丸（通过/失败/待验证/未知）

## 每个 change 能看到什么

选中一个 change 后，中间和右侧会展示它的完整状态。

### 生命周期阶段步进条

以五个圆点 + 连接线展示 open → design → build → verify → archive 的当前位置：

* 已完成的阶段显示为 ✓ 蓝色实心
* 当前阶段高亮显示阶段名
* 未开始的阶段为灰色

右上角标记**下一步**推荐的 slash 命令（活跃 change）或归档状态。

### 关键产物（按来源分组）

产物不再是一个平铺列表，而是**按来源分三组**展示，并显示每个产物的状态：

| 分组              | 产物                                                         | 来源                                              |
| --------------- | ---------------------------------------------------------- | ----------------------------------------------- |
| **OpenSpec**    | proposal、design、tasks、deltaSpec                            | 变更目录内的规格文件                                      |
| **Superpowers** | designDoc、plan、verifyReport                                | 通过 `.comet.yaml` 路径指针引用的 `docs/superpowers/` 文件 |
| **Comet**       | .comet.yaml、handoff、checkpoint、brainstorm、subagentProgress | `.comet/` 中间产物                                  |

每个产物行显示三种状态：

* **已生成**（蓝点）：文件存在，点击可预览全文
* **未生成**（空心点）：预期产物但尚未创建
* **无需生成**（灰点）：当前模式/阶段不适用，例如 `subagent-progress` 在 `executing-plans` 模式下

点击任意已生成的产物，会从右侧滑出**产物预览抽屉**（见下文）。

### 任务进度环形图

任务进度用一个环形图（donut）+ 三列统计展示：

* **环形图**：完成度百分比，从 0% 动画填充；全部完成时变绿
* **三列统计**：已完成 / 剩余 / 分组数
* **分组进度条**：tasks.md 里每个 section 的完成度
* **下一步提示**：全部完成时提示「可以进入 Verify」，否则提示剩余多少项

### 右侧侧边面板

侧边面板根据 change 状态显示不同卡片：

<Columns>
  <Column>
    **活跃 change**

    * **下一步建议**：推荐的 slash 命令 + 原因 + 说明
    * **风险提示**：检测到的 info/warning/error 级风险项和恢复建议
    * **Git 快照**：分支、HEAD、最近提交、未提交文件
  </Column>

  <Column>
    **已归档 change**

    * **归档摘要**：归档名、原名、归档时间和路径、任务完成度
    * **风险提示**：归档时的遗留风险
    * **Git 快照**：归档时的 Git 状态
  </Column>
</Columns>

## 产物预览抽屉

点击任意已生成的产物，会从右侧滑出一个全屏高度的抽屉：

* **标题区**：产物名、完整文件路径
* **元数据**：文件大小（B/KB/MB）和更新时间
* **内容区**：带简易 Markdown 渲染（标题、列表、代码块、行内代码、加粗），超过 256 KiB 时截断并提示

抽屉打开时背景固定，不会随滚动；点击遮罩或右上角 × 关闭。

<Tip>
  如果产物文件存在但抽屉显示「当前 dashboard 服务返回的数据里没有全文内容」，重启 dashboard 服务后再刷新页面即可。
</Tip>

## 主题切换：亮色 / 暗色

仪表盘支持**亮色**和**暗色**两种主题，在顶部工具栏右侧点击太阳/月亮图标切换。

* 首次访问时，根据**系统偏好**（`prefers-color-scheme`）自动选择主题
* 手动切换后，选择会**持久化**到 `localStorage`（key 为 `comet-theme`），下次打开沿用
* 切换在 `<html data-theme>` 属性上生效，避免首次渲染闪烁

<Note>
  主题偏好存储在浏览器本地，不会跨设备同步。在另一台机器或另一个浏览器上打开 dashboard 时，会重新读取系统偏好。
</Note>

## 自动刷新

前端每 **30 秒**自动刷新一次快照，无需手动操作。也可以点击工具栏的「立即刷新」按钮手动刷新，刷新成功会弹出 toast 提示。

* 自动刷新不会和手动刷新并发（有锁保护，避免重复请求）
* 演示模式（`?demo`）下同样每 30 秒重新加载演示数据

## 演示模式

在 URL 加 `?demo` 可以加载演示数据（不读真实 change），方便预览界面、截图或检查布局：

```text theme={null}
http://localhost:4321/?demo
```

演示数据来自 `web/demo.js`，覆盖首屏、侧边栏、卡片、产物分组和抽屉的全部 UI 状态。

## 风险码参考

仪表盘的风险提示卡片会显示检测到的风险码：

| 风险码                        | 含义                      |
| -------------------------- | ----------------------- |
| `MISSING_COMET_YAML`       | change 缺少 `.comet.yaml` |
| `UNKNOWN_PHASE`            | 阶段无法识别                  |
| `TASKS_MISSING`            | 缺少 tasks 文件             |
| `TASKS_INCOMPLETE`         | 任务未完成                   |
| `VERIFY_FAILED`            | verify 失败               |
| `VERIFY_PENDING`           | verify 待跑               |
| `ARTIFACT_MISSING`         | 缺少关键产物                  |
| `ARCHIVE_METADATA_MISSING` | 归档元数据缺失                 |
| `GIT_DIRTY`                | （项目级）工作区有未提交改动          |

<Info>
  仪表盘读取 <code>openspec/changes/</code>（活跃）和 <code>openspec/changes/archive/</code>（归档），采用<strong>尽力而为</strong>策略：单个 change 出错不会让整个页面空白，错误会被隔离并跳过。
</Info>

## 下一步

* [comet dashboard 命令](/zh/cli/dashboard) — 完整命令选项和脚本/CI 用法
* [comet status](/zh/cli/status) — 命令行版的活跃 change 状态
* [中间产物](/zh/concepts/intermediate-artifacts) — `.comet/` 中间产物的作用