comet dashboard 启动一个本地只读的浏览器仪表盘，让你用图形界面查看项目的所有 OpenSpec change：活跃和归档的变更、五阶段进度、artifact 检查清单、任务摘要、verify 状态、下一步建议和 Git 快照。
它只读，不会修改任何文件，可以随时安全启动。
本页是 comet dashboard 的命令参考。想了解仪表盘的界面布局、产物分组、任务环形图、亮色/暗色主题和截图，请看 Dashboard 总览。 快速开始
在含有change的项目根目录运行：
默认会在 http://localhost:4321 启动并自动打开浏览器。终端会显示：
Comet Dashboard running at http://localhost:4321
Press Ctrl+C to stop.
命令选项
comet dashboard [path] [options]
| 选项 | 说明 |
|---|
[path] | 项目路径（默认 .） |
--port <port> | HTTP 端口（默认 4321，被占用时自动递增） |
--no-open | 不自动打开浏览器 |
--json | 打印一次快照后退出（不启动服务器） |
—port 被占用时会自动向上找可用端口（最多重试 50 次）。—port 0 让系统自动分配。端口必须是 0–65535 的整数，否则报错。
脚本 / CI 用法
不启动服务器，只打印一次 JSON 快照：
指定端口且不自动打开（适合远程开发）：
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 总览 · 主题切换。
演示模式
在 URL 加 ?demo 可以加载演示数据（不读真实 change），方便预览界面：
http://localhost:4321/?demo
- 服务器只绑定
127.0.0.1（localhost），不对外暴露。
- 静态文件服务有路径穿越防护。
- artifact 预览有大小限制（256 KiB，超出标记
truncated）。
- artifact 抽屉打开时锁定背景滚动（fixed 定位），避免内容错位。
下一步
