Comate UI

Comate UI 是一个本地只读的浏览器工作区，用于 OpenSpec 和 Comate 项目。它整合了变更生命周期状态、规约、PRD、Superpowers 文档、验证报告、集成文档和架构文档，无需引入数据库或修改项目文件。

安装

npm install -g @house365/comate-ui@latest

需要 Node.js 20 或更高版本。

也可以不全局安装直接运行：

npx @house365/comate-ui@latest

使用

在包含 openspec/ 目录的项目内运行命令：

comate-ui

或指定项目路径：

comate-ui D:\work\my-project
comate-ui /work/my-project --port 4300
comate-ui --no-open

服务器仅绑定 127.0.0.1，当首选端口被占用时会自动选择下一个可用端口，并保持前台运行直到按 Ctrl+C 停止。

查看内置的示例项目：

comate-ui --demo

项目数据

Comate UI 索引以下来源：

• openspec/changes/<name>/ 和 openspec/changes/archive/<name>/
• openspec/specs/**/spec.md
• .comate.yaml、关联的 Design Doc、计划、验证报告和源清单
• docs/superpowers/
• docs/knowledge-base/requirements/
• docs/knowledge-base/integrations/
• docs/architecture/

没有 .comate.yaml 的纯 OpenSpec 变更仍然可见，其阶段根据可用产物和任务进度推断。有效的 .comate.yaml 对 Comate 工作流状态始终具有优先权。

变更详情遵循三部分模型：

• WHAT · OpenSpec：提案、OpenSpec 设计、增量规约、受影响的规范规约和 tasks.md
• HOW · Superpowers：Design Doc、实施计划、任务进度和交接上下文
• EVIDENCE · 验证：权威验证结果、验证报告和分支状态

openspec/specs/**/spec.md 被视为当前能力的事实标准。openspec/changes/<change>/specs/ 下的文件是变更范围的增量，而 docs/superpowers/specs/*-design.md 是 Design Doc 而非能力规约。

安全模型

• 所有应用路由均为只读 GET 端点
• HTTP 服务器仅监听回环接口
• 请求的文件通过真实路径解析，必须保持在所选项目内
• 仅渲染 2 MB 以内的 Markdown 文档
• 渲染的 Markdown 经过清理，原始 HTML 不受信任
• 浏览器资源受限制性内容安全策略保护

开发

npm install
npm test
npm run demo

浏览器客户端是纯 HTML、CSS 和 JavaScript。运行时服务器使用 Node 内置的 HTTP 模块、Chokidar 用于文件监视、Server-Sent Events 用于刷新通知、YAML 用于状态解析、Marked 加 sanitize-html 用于文档渲染。

参考

信息架构和实时更新模型参考了：

• ToruAI/openspec-ui：产物链和工作流概览
• MusicAdam/openspec-viewer：本地文档浏览、搜索和实时刷新

本项目未复制任何第三方源代码。

许可证

Apache-2.0