comet init 是安装入口。它会检测平台、安装 Comet Skill，并在项目级初始化时确定 /comet 的默认工作流。
基本用法
常用选项：
Native 与 Classic 初始化
交互式初始化在 project 和 global 范围都会提供 Native、Classic 或同时启用两者。项目级非交互初始化按以下规则选择默认工作流：
- 合法的
.comet/config.yaml 是事实源。
--workflow native|classic|both 是显式选择，不迁移已有 change；both 默认让 /comet 进入 Native。- 没有有效 workflow 配置，但存在 Classic
.comet.yaml 或旧版 Ambient Resume 证据时，保持 Classic。
- 其他项目默认 Native；已有代码、普通
openspec/ 或 docs/superpowers/ 不会改变这个默认值。
Native 初始化安装 Comet 自有 Skill/runtime、统一工作流 Rule，以及平台支持时的单一 Hook Router，并创建：
它不会安装 OpenSpec、Superpowers 或 CodeGraph，也不会创建 Classic/OpenSpec change 或 docs/superpowers/。统一 Rule 与 Router 会按 .comet/current-change.json 把一次写入交给唯一 workflow Guard，不会同时运行 Native 与 Classic Guard。Classic 初始化保留原来的完整依赖与阶段治理。
Comet 只会在所有选中平台的必需资产安装成功，且已有 /comet 入口与 bundled routing contract 兼容后，才写入并激活 .comet/config.yaml。如果检测到不兼容的自定义 /comet 内容，初始化会原样保留它并把本次结果标记为 incomplete；确认要替换时显式重跑 comet init --workflow native --overwrite。
global 范围下，--workflow 用于选择要全局安装的能力，但不会写入项目配置，也不会替项目选择默认工作流。非交互 global 初始化未传 --workflow 时仍默认使用 Classic。--root 仍只允许用于项目级 Native 初始化。
只处理一个平台
项目同时配置多个平台，但本次只需要安装或修复其中一个平台时，使用 --platform：
参数值可以是 Comet 支持的平台 ID，也可以是项目配置中定义的自定义平台。指定后只处理该目标；不指定时继续使用平台自动检测与现有回退规则。
非交互项目初始化还可以用 --codegraph init 明确创建或刷新 CodeGraph 索引，或用 --codegraph skip 明确跳过。普通检查不会自行修改索引；需要修复时可以先运行 comet doctor 查看状态。
项目级安装索引
0.4.0-beta.4 起，成功的项目级安装会登记到用户级项目索引。这个索引只保存后续更新和卸载所需的项目位置与已安装平台，不复制项目文件，也不上传使用数据。
登记后，交互式 comet update 和 comet uninstall 可以让你选择当前项目或所有已登记项目。--json 或显式 --current-project 会限定当前项目，comet uninstall --force 也保持当前项目；批量操作必须显式使用 --all-projects。自动化脚本应明确传入其中一个范围选项，不要依赖终端环境推断。
安装模式（复制 vs 符号链接）
Classic 或 both 初始化在选择平台后会询问安装模式，global 范围也一样（0.4.0-beta.1 起新增符号链接模式）。仅安装 Native 时固定使用 Copy；项目级 Native 不会创建 .comet/skills/，Native change 状态只存在于 <artifact-root>/comet/，共享项目配置与 selection 位于 .comet/。
- Copy（复制）：为每个平台独立复制一份 Skill 文件（传统方式）。
- Symlink（符号链接）：在各平台目录创建指向
.comet/skills/ 的符号链接，所有平台共享同一份中央存储，节省空间且一次更新即全部生效。
如果平台已经有自己的 skills/ 目录，Comet 会保留该目录，只在其中链接 Comet 管理的 Skill。已有的本地或第三方 Skill 不会因为选择 Symlink 而被删除或替换。
两种模式的详细区别和适用场景见 支持的平台 · 安装模式。
共享项目配置合并
Native 与 Classic 现在共用 .comet/config.yaml。初始化会按启用的工作流合并托管字段：
- 保留你的现有配置值（如
native.artifact_root、classic.review_mode）
- 补齐缺失的托管字段默认值
- 刷新注释，对齐当前版本
- 保留你额外添加的自定义字段
- 共享的
default_workflow、workflows、ambient_resume 与 native.*、classic.* 保持独立语义
- 无法安全解析的 workflow 配置会失败关闭，不会猜测默认值后覆盖
终端会提示 项目配置已合并 (.comet/config.yaml)。
OpenSpec CLI 的安装范围
OpenSpec CLI 是 Classic 的跨项目命令行工具。Classic 即使选择项目级安装，也会把 OpenSpec CLI 作为全局工具安装或升级；它不会为了这个依赖在当前项目创建 node_modules/。Native 不检查或安装它。
初始化后检查
如果缺少平台目录、Skill 文件或脚本，先修复这些问题再开始 /comet。
安装摘要怎么看
comet init（和 comet update）按平台输出每个组件的安装状态。Skill/脚本复制是这样展示的：
从 0.4.0-beta.1 起，部分失败的安装不再被掩盖成成功
。如果某个平台有文件复制失败，该平台会标记 failed 并带失败计数。Classic 缺少
comet-hook-guard.mjs 会破坏阶段检查；Native 缺少入口或 runtime
同样不能写入项目默认配置。重跑 comet init 或 comet update 补齐缺失文件。
