🌠 Comet 安装指南

一句话总结：Comet（@rpamis/comet）是一个 Agent Skill Harness——给 AI 编码 agent 装一套可恢复、分阶段治理的开发工作流（Native / Classic）。通过 CLI 安装、comet init 装进各 agent 平台，同时支持 OpenCode 和 DeepSeek Harness。

---

是什么

Comet 为 AI 编码任务提供可恢复的开发工作流，外加 Skill 创建、评估、发布工具。它不是 MCP server，而是给 agent 装一套「怎么做」的 skill 工作流（和 Superpowers 同类，但范围更广、还带 CLI 状态管理）。

两条工作流：

工作流	面向	说明
Native（默认）	强编码模型（Fable 5、GPT-5.6 等）	约束需求、状态和验收结果，实现方法由模型自己选；Shape → Build → Verify → Archive
Classic	需要明确过程约束的模型	组合 OpenSpec + Superpowers（+ CodeGraph），按五阶段推进：open → design → build → verify → archive

🔑 和 OpenSpec / Superpowers 的关系：Comet 的 Classic 工作流直接连接 OpenSpec 和 Superpowers。也就是说装好 Comet，等于用一套 CLI 把 OpenSpec 安装指南 和 Superpower 安装指南 的流程串起来管理（comet handoff 还会把 OpenSpec 产物整理成 Superpowers 能读的上下文）。如果你本来就在用这两套，Comet 是它们之上的编排层。

前置要求：Node.js **22.16 及以上（22.x 系列）**或 24+；npm/npx；Git；一个受支持的 AI 编码平台。

---

安装（OpenCode 和 Harness 都走这套）

Comet 的安装是统一的 CLI 流程，装到哪个平台由 comet init 自动检测，不用分平台写配置。

1. 安装 CLI

npm install -g @rpamis/comet

验证：comet --version 能输出版本号即成功。

2. 初始化项目

进入项目根目录：

cd your-project
comet init

按向导选平台。新项目默认启用 Native，项目根目录生成 .comet/config.yaml。已有 Classic 状态的项目保持 Classic。

项目级 vs 全局：

# 项目级（默认，适合团队/仓库约定，配置可提交）
comet init
 
# 全局（个人默认环境，多项目共享）
comet init --scope global --workflow native

安装模式（Classic 或 both 时）：Copy（为每平台复制一份 Skill，跨设备同步）/ Symlink（各平台 skills/ 指到中央 .comet/skills/，一次更新全生效）。仅 Native 固定用 Copy。

3. 在 agent 里调用

打开 agent 平台，在项目里输入：

/comet 实现用户资料页的头像上传能力

/comet 读 .comet/config.yaml，把请求转发到 /comet-native 或 /comet-classic。默认 Native 会创建 change，按 Shape → Build → Verify → Archive 推进。

验证安装完整性：comet doctor，输出里没有 ✗ 失败项即完整。

4. 查看状态 / 继续中断的工作

comet status    # 看 Native / Classic / 未托管 OpenSpec change 当前状态
comet doctor    # 安装健康检查

会话中断后重开项目输入 /comet 继续，会从文件和运行证据继续。

---

OpenCode vs Harness 具体差异

comet init 会自动检测平台。两个平台在 Comet 的能力分层不同：

平台	平台 id	项目目录	全局目录	规则格式	Hooks
OpenCode	opencode	.opencode	~/.config/opencode	md	❌ 无
DeepSeek Harness	dsh	.dsh	.dsh	dsh	✅ hooks.json

• OpenCode：OpenCode 风格 slash 命令；项目目录 .opencode 与全局 ~/.config/opencode 不同。属「Skill + 规则、无 hooks」档。
• DeepSeek Harness：走 Claude 兼容的 OpenSpec 集成；规则写入托管的 AGENTS.md 块，Hook 配置写入 hooks.json。属「Skill + 规则 + hooks」档（支持 hook 的 platform 里 Comet 只装一个统一路由 Router，再按当前 change 交给对应阶段的 Guard）。

OpenCode 系的 ZCode、MimoCode 也基于 OpenCode 运行时，comet init 同样支持（ZCode 把 .opencode/{skills,commands} 镜像到 .zcode/，MimoCode 镜像 OpenSpec 输出到 .mimocode/）。

---

更新 / 卸载

comet update       # 先刷新本地 npm 包，再刷新已安装的 Skill/Rule/Hook/Runtime/config
comet doctor       # 状态异常先诊断
comet uninstall    # 只移除 Comet 装的 Skill/规则/hooks，保留你的 OpenSpec change 和项目代码

comet uninstall 卸载不会动你的 OpenSpec change、设计文档、实施计划和项目代码。

---

状态记录

• 2026-10-03：初版。⚠️ 此前误写成 Perplexity 的 comet-mcp，已整体订正为 @rpamis/comet（Agent Skill Harness）。整理 CLI 安装、comet init、OpenCode/Harness 能力差异、与 OpenSpec/Superpowers 的关系。未实测——按官方文档（llms.txt + quickstart + platforms + overview）整理，未在本机跑过。

🔗 相关

• OpenSpec 安装指南 — Classic 工作流连接的规格驱动框架
• Superpower 安装指南 — Classic 工作流连接的技能框架（comet handoff 会整理 OpenSpec 产物给 Superpowers 读）
• 官方文档站：docs.comet.rpamis.com（含中文，另有 llms.txt 全文索引）
• npm 包：@rpamis/comet