> ## 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.

# comet dashboard

> 启动一个本地只读浏览器仪表盘，查看活跃和归档的 change、阶段进度、artifact、任务和风险。

`comet dashboard` 启动一个**本地只读**的浏览器仪表盘，让你用图形界面查看项目的所有 OpenSpec change：活跃和归档的变更、五阶段进度、artifact 检查清单、任务摘要、verify 状态、下一步建议和 Git 快照。

它**只读**，不会修改任何文件，可以随时安全启动。

<Info>
  本页是 <code>comet dashboard</code> 的命令参考。想了解仪表盘的界面布局、产物分组、任务环形图、亮色/暗色主题和截图，请看 <a href="/zh/dashboard/overview">Dashboard 总览</a>。
</Info>

## 快速开始

在含有change的项目根目录运行：

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

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

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

## 命令选项

```bash theme={null}
comet dashboard [path] [options]
```

| 选项              | 说明                          |
| --------------- | --------------------------- |
| `[path]`        | 项目路径（默认 `.`）                |
| `--port <port>` | HTTP 端口（默认 `4321`，被占用时自动递增） |
| `--no-open`     | 不自动打开浏览器                    |
| `--json`        | 打印一次快照后退出（不启动服务器）           |

<Info>
  <code>--port</code> 被占用时会自动向上找可用端口（最多重试 50 次）。<code>--port 0</code> 让系统自动分配。端口必须是 0–65535 的整数，否则报错。
</Info>

### 脚本 / CI 用法

不启动服务器，只打印一次 JSON 快照：

```bash theme={null}
comet dashboard . --json
```

指定端口且不自动打开（适合远程开发）：

```bash theme={null}
comet dashboard . --port 4399 --no-open
```

## 仪表盘能看到什么

仪表盘读取 `openspec/changes/`（活跃）和 `openspec/changes/archive/`（归档），**只读、尽力而为**：单个 change 出错不会让整个页面空白（错误被隔离并跳过）。

### 项目级信息

* 项目名称、路径、生成时间
* 汇总：活跃 change 数、归档数、verify 失败数、任务未完成数、脏文件数
* Git 快照：分支、HEAD、脏文件列表、最近提交

### 每个 change

* 名称、状态（活跃/归档）、路径、更新时间
* 工作流和**阶段**（open/design/build/verify/archive）——以生命周期步进条展示
* 任务完成度（completed/total、未完成项、各 section）——以环形图展示
* artifact **按来源分组**（OpenSpec / Superpowers / Comet），每组内显示存在性状态（已生成/未生成/无需生成）
* artifact 存在性（proposal、design、tasks、plan、verifyReport、cometYaml）+ 内容预览（最大 256 KiB，含文件大小和更新时间元数据）
* verify 结果（pending/pass/fail/unknown）和摘要
* **下一步**（仅活跃 change）：推荐的 slash 命令和原因
* 风险项（info/warning/error 级别 + 恢复建议）

### 风险码

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

## 自动刷新与主题

前端每 **30 秒**自动刷新一次，也有手动刷新按钮、搜索框和标签页（活跃/归档/全部）。artifact 抽屉带一个简易 Markdown 渲染器。

顶部工具栏右侧有**亮色/暗色主题切换**按钮：首次访问按系统偏好（`prefers-color-scheme`）选择，手动切换后持久化到 `localStorage`。详见 [Dashboard 总览 · 主题切换](/zh/dashboard/overview#主题切换：亮色-暗色)。

## 演示模式

在 URL 加 `?demo` 可以加载演示数据（不读真实 change），方便预览界面：

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

## 安全

* 服务器只绑定 `127.0.0.1`（localhost），不对外暴露。
* 静态文件服务有路径穿越防护。
* artifact 预览有大小限制（256 KiB，超出标记 `truncated`）。
* artifact 抽屉打开时锁定背景滚动（fixed 定位），避免内容错位。

## 下一步

* [Dashboard 总览](/zh/dashboard/overview) — 仪表盘界面、产物分组、主题切换和截图
* [comet status](/zh/cli/status) — 命令行版的活跃 change 状态
* [comet doctor](/zh/cli/doctor) — 安装和健康诊断