跳转到主要内容
你的项目可能已经存在一段时间——有代码、有 Git 历史，甚至已经在用 OpenSpec 或 Superpowers。本页说明这种存量项目接入 Comet 时的真实流程和需要注意的边界。

​
最短路径

npm install -g @rpamis/comet
cd your-existing-project
comet init
然后在你的 AI 编码平台里输入 /comet，描述你想做的变更。

​
comet init 在存量项目里会做什么

comet init 不会问你”是否已经在用 OpenSpec/Superpowers”。它逐个检测每个组件，然后让你决定覆盖还是跳过。

​
组件检测

comet init 检查以下三类组件是否已存在：
组件检测方式
OpenSpec目标平台的 skills 目录里是否有 openspec-* 开头的 Skill
Superpowers是否存在 brainstorming、writing-plans、test-driven-development 等 Skill；也会检查插件缓存（Claude/Codex/OpenCode 插件安装的 Superpowers）
Comet是否存在 comet* 开头的 Skill
CLI 依赖单独检测（openspec、codegraph 是否在 PATH 上），已安装的默认不勾选，不会重复安装。

​
已存在组件的处理

当检测到已存在的组件时： 如果同一平台检测到多个已存在组件，先批量选择（全部覆盖/全部跳过/逐个选择），再逐个处理。

​
init 会创建的目录和文件

项目级安装时，comet init 会：
  • 运行 openspec init 创建 openspec/ 目录结构（OpenSpec 自身幂等，已存在不会破坏）
  • 安装 Comet Skill、rules 和 hooks 到目标平台目录
  • 创建工作目录 docs/superpowers/specs、docs/superpowers/plans、.comet/
  • 写入默认 .comet/config.yaml（如果不存在）
# .comet/config.yaml（init 生成，不存在时才写）
context_compression: off
review_mode: off
auto_transition: true
.comet/config.yaml 是项目级配置；每个 change 的 .comet.yaml 由 /comet-open 创建，不是 init 创建的。

​
四种存量项目场景

​
场景一：纯代码库，没用过 OpenSpec/Superpowers

最常见的场景。comet init 检测不到已有组件，全部安装： 
comet init
然后 /comet 开始第一个变更。

​
场景二：已经在用 OpenSpec

你已经有 openspec/ 目录和活跃 change。comet init 检测到 OpenSpec Skill 和 CLI 已存在，会让你选择覆盖或跳过。推荐跳过已有组件，只补充 Comet 部分。 comet init 运行的 openspec init 是幂等的——OpenSpec 自己处理已存在的 openspec/ 目录，不会破坏你的 change。

​
场景三：已经在用 Superpowers

你已经有 brainstorming、writing-plans 等 Skill（可能通过插件安装）。comet init 检测到后同样让你选择。推荐跳过，避免覆盖你的自定义版本。
如果你之前用的是旧版 Superpowers（低于 6.0.0），升级到 6.0.0+ 大约快 2 倍、token 少 50%。升级时可选择覆盖 Superpowers 组件。

​
场景四：同时用 OpenSpec 和 Superpowers

两套组件都已存在。comet init 批量提示，选择”全部跳过”即可，它只补装 Comet Skill、规则、hooks 和工作目录。

​
历史change：已有 OpenSpec change 但没有 .comet.yaml

这是存量项目接入时最容易踩的坑。

​
问题

如果你之前用原始 /opsx:new 创建了 OpenSpec change，这些 change 没有 .comet.yaml。此时：
  • comet status 会静默跳过它们（不报错，但也不显示）。
  • comet doctor 同样不检测这类 change。
  • 只有在 Agent 平台里调用 /comet 时，openspec list --json 才会列出它们。

​
接管存量OpenSpec Change

Comet 没有 comet adopt 或 comet import 这样的接管命令。接管存量 OpenSpec change 靠的是 /comet-open 的幂等性：
  1. 在 Agent 平台调用 /comet。
  2. /comet 运行 openspec list --json，发现有活跃 change 但缺少 .comet.yaml。
  3. 路由到 /comet-open。
  4. /comet-open 发现 OpenSpec artifacts 已存在，跳过已完成的步骤，补创建 .comet.yaml。
这个接管路径只在 change 还在 open 阶段（或刚创建还没推进）时干净工作。如果一个 change 已经做到 build 或 verify 但没有 .comet.yaml，没有可靠的方式回溯挂载 Comet 状态——需要重新开 change。

​
建议

  • 存量 OpenSpec change 如果还没推进，直接 /comet 让它接管。
  • 如果已经推进到 build/verify，建议完成当前工作后用新 /comet 开新 change，而不是强行接管。
  • 接入后，确认 comet status 能看到你的 change（说明 .comet.yaml 已补上）。

​
升级已有 Comet 安装

如果项目已经在用 Comet，只是想升级： 
comet update
comet update 会刷新 Comet Skill、规则和脚本到已安装平台。--yes 在 init 里会把已存在组件解析为跳过，所以强制刷新要用 --overwrite。

​
接入后的检查清单

检查项命令预期
安装完整性comet doctor全部通过
活跃 change 可见comet status列出你的 change 和当前阶段
平台 Skill 就位comet doctor检测到的平台目录有 Comet Skill
项目配置存在查看 .comet/config.yaml存在且有 review_mode 等字段

​
常见问题

不会。Comet 非破坏性合并 hook 配置，保留你已有的 hooks，只替换它自己管理的命令。详见支持的平台。
不可以，Comet依赖OpenSpec和Superpowers。如已安装，可通过交互式提示的覆盖/跳过选择来控制，或靠检测自动跳过已安装的依赖。
这个 change 可能是原始 /opsx:new 创建的，缺少 .comet.yaml。用 /comet 让它接管补上状态文件。详见上文的”历史change”。

​
下一步