> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# comet bundle

> 了解高级 Bundle 后端命令，以及它和 /comet-any、comet publish 的边界。

`comet bundle` 是 `/comet-any` 和 `comet publish` 背后的**高级后端**。它创建平台无关的 Skill Bundle，把它们编译成原生平台 install plan，并能携带 Engine metadata、要求结构化 Eval 证据、人工批准后才能发布和分发。

日常使用通常**不需要**直接调用它。`/comet-any` 的创建、恢复和 authoring flow 由 [comet creator](/zh/cli/creator) 暴露；`comet publish` 暴露 review、approve、publish 和 distribute。直接使用 Bundle CLI 的场景是**审计底层状态、调试平台 compile、capability gap、eval evidence 或 executable disclosure**。

<Warning>
  如果你只是想创建、评估、发布一个 Skill，请不要从 <code>comet bundle</code> 开始。常规路径是 <code>/comet-any</code> 创建，<code>comet eval</code> 验证，<code>comet creator next/status</code> 看下一步，再用 <code>comet publish</code> 完成评审、发布和分发。
</Warning>

## 日常使用该看哪里

| 你想做什么          | 应该使用                                              |
| -------------- | ------------------------------------------------- |
| 创建或组合 Skill    | [`/comet-any`](/zh/skill-creator/getting-started) |
| 查看创建状态或下一步     | [`comet creator`](/zh/cli/creator)                |
| 跑发布前评估         | [`comet eval`](/zh/cli/eval)                      |
| 评审、批准、发布、分发    | [`comet publish`](/zh/cli/publish)                |
| 审计 Bundle 后端状态 | 本页                                                |

## 什么时候需要直接用

* 审计 Bundle draft 和编译输出。
* 调试平台 compile、capability gap 或 executable disclosure。
* 手工记录结构化 eval evidence。
* 自动化集成需要 JSON 后端命令。

## 常见后端阶段

```mermaid theme={null}
flowchart LR
  A["draft create / optimize"] --> B["compile"]
  B --> C["eval-plan"]
  C --> D["eval-record"]
  D --> E["review-summary"]
  E --> F["review"]
  F --> G["publish"]
  G --> H["distribute"]
```

## Skill Creator 命令已移到 comet creator

0.4.0-beta.1 起，`comet creator` 是 Skill Creator 的用户 CLI 表面。下面这些旧的预发布 Bundle 别名不再是当前命令：

```text theme={null}
comet bundle factory-*
comet bundle authoring-*
comet bundle list
comet bundle status
```

对应关系：

| 旧预发布命令                          | 当前命令                             |
| ------------------------------- | -------------------------------- |
| `comet bundle factory-guide`    | `comet creator guide`            |
| `comet bundle candidates`       | `comet creator candidates`       |
| `comet bundle factory-propose`  | `comet creator propose`          |
| `comet bundle factory-init`     | `comet creator init`             |
| `comet bundle factory-resolve`  | `comet creator resolve`          |
| `comet bundle factory-generate` | `comet creator generate`         |
| `comet bundle authoring-plan`   | `comet creator authoring-plan`   |
| `comet bundle authoring-record` | `comet creator authoring-record` |
| `comet bundle list/status`      | `comet creator list/status`      |

## 创作协议（authoring）

0.4.0-beta.1 起，`/comet-any` 生成的 Skill 不再是薄确定性外壳，而是携带真实人工创作内容。这通过**创作协议**（authoring protocol）实现：一个确定性的 lane DAG，每个 lane 输出经过 schema 校验，最后做一次多票 Skill 评审。

### 创作流水线

创作按\*\*波次（wave）\*\*推进，每个 lane 是一个可并行的子任务：

```mermaid theme={null}
flowchart LR
    W1["wave 1<br/>script / reference / pause-points"] --> W2["wave 2<br/>workflow-entry / skill-core"]
    W2 --> B["barrier<br/>skill-review"]
    B --> R["记录到 Bundle<br/>authoring-record"]
```

| Lane             | 产出                                                                                            | 说明            |
| ---------------- | --------------------------------------------------------------------------------------------- | ------------- |
| `script`         | 运行时脚本（workflow-state、workflow-guard、workflow-handoff、comet-plan、comet-check、comet-hook-guard） | 6 个核心脚本       |
| `reference`      | workflow-protocol、resolved-skills、composition-report、authoring-lanes                          | 协议和组合证据       |
| `pause-points`   | decision-points、recovery                                                                      | 决策点和恢复        |
| `workflow-entry` | 入口 Skill 正文                                                                                   | 入口创作          |
| `skill-core`     | 节点 Skill 正文                                                                                   | 节点创作          |
| `skill-review`   | skill-review                                                                                  | 多票评审（barrier） |

运行创作协议时请用 `comet creator authoring-plan` 和 `comet creator authoring-record`。这些命令会：

* 返回创作计划：要跑哪些 lane、每个 lane 的预期产出、深度（`quick` 只覆盖必要 lane，`full` 覆盖全部）。

* 校验并记录某个 lane 的产出。

* **schema 校验**：lane 输出 JSON 必须符合该 lane 的 schema（status ∈ `DONE`/`DONE_WITH_CONCERNS`/`NEEDS_CONTEXT`/`BLOCKED`，artifacts、findings、evidence 等字段齐全）。

* **claim 校验**：lane 声称产出哪些内容（claims），实际产物文件必须存在且匹配。

* **写入状态**：校验通过后把 lane 产出固化到 Bundle 的创作状态（`BundleAuthoringState`），记录 lane status、findings（severity ∈ `critical`/`important`/`minor`）和 review evidence。

* **review evidence**：`skill-review` lane 的 evidence source ∈ `deterministic-check-only`/`llm-single`/`llm-multivote`，记录真实评审结论（voters、lenses、findings），不再硬编码 `approved`。

### Authored 内容分区

生成的 SKILL.md 由两部分组成：

* **Auto zone（自动区）**：frontmatter、路由表、Entry/Exit 检查、证据格式、恢复——不变的控制面，由模板生成。
* **Authored zone（创作区）**：入口的 `## Decision Core`、节点的 `## Guidance`——由 skill-core / workflow-entry 子 Agent 动态创作。

节点分为 `delegates`（覆盖层 → 安装富 Skill，薄指导正确）和 `substance`（工作流内核，必须有富创作指导）。一个 `substance` 节点如果缺少创作内容会渲染显式的 `AUTHORING PENDING` stub，并出现在 `unauthoredSubstanceNodes` 里——**这会阻止发布就绪**，确保生成器不能再以假完整的薄 Skill 冒充完成。

## draft 和 compile 命令

```bash theme={null}
# 手动创建或优化 draft（排障或显式优化时）
comet bundle draft create <name> --default-locale en --json
comet bundle draft optimize <bundle> --name <name> --json

# 编译到参考平台
comet bundle compile <name> --platform <id> --json
```

## eval 命令

```bash theme={null}
# 规划 eval 工作量
comet bundle eval-plan <name> --level quick --json
comet bundle eval-plan <name> --level full --json

# 记录 eval 证据
comet bundle eval-record <name> --result <file> --json
```

### eval-plan

返回 `BundleEvalPlan { level, components[], estimatedRuns, tokenWorkload, explanation }`，是**描述性估算**，不是 token 承诺：

| 级别      | components                                                     | estimatedRuns           |
| ------- | -------------------------------------------------------------- | ----------------------- |
| `quick` | static、entry-smoke、baseline、assertion-grading、platform-compile | `4 + entries*2`         |
| `full`  | quick 全部 + trigger-accuracy、routing-overlap、failure-analysis 等 | `quick + 6 + entries*3` |

### eval-record

结果必须绑定当前 draft hash 和当前 eval manifest hash。校验规则：

* `result.schemaVersion !== 2` 或 `result.provider !== "comet-eval"` → 拒绝。
* `result.draftHash !== state.currentHash` → 只写文件，不推进状态。
* `result.evalManifestHash` 不等于当前生成的 `comet/eval.yaml` hash → 只写文件，不推进状态。
* 全部通过（`result.passed` 且 `failures` 为空）→ status 推进到 `eval-passed`。
* 否则回退到 `draft`，清除 review/ready/conflict。

eval-result JSON 的 schema 见[发布和分发 Skill · eval-record 证据契约](/zh/skill-creator/publishing#eval-record-证据契约)。

## review 和 publish 命令

```bash theme={null}
# 生成评审摘要
comet bundle review-summary <name> --platform <id> --json

# 批准或拒绝
comet bundle review <name> --approve --reviewer <reviewer> --json
comet bundle review <name> --reject --reviewer <reviewer> --json

# 发布
comet bundle publish <name> --platform <id> --json

# 分发
comet bundle distribute <name> --platform <id> --scope project --preview --json
comet bundle distribute <name> --platform <id> --scope project --json
```

发布前必须读取 review summary 的 readiness：存在 unresolved candidate、缺失当前 hash 的 Eval 证据、缺失当前 hash 的人工 approval、capability gap 或 executable disclosure 未确认时，不得发布 ready。详见[发布和分发 Skill](/zh/skill-creator/publishing)。

## 通用选项

| 选项                          | 说明                        |
| --------------------------- | ------------------------- |
| `--project <dir>`           | 项目根目录（默认 `.`）             |
| `--json`                    | 输出结构化 JSON                |
| `--platform <id>`           | 目标平台（可多次传）                |
| `--scope <project\|global>` | 分发范围                      |
| `--level <quick\|full>`     | eval 工作量级别                |
| `--result <path>`           | eval 结果文件路径               |
| `--approve` / `--reject`    | 批准或拒绝                     |
| `--reviewer <name>`         | 评审人                       |
| `--preview`                 | 分发预览                      |
| `--confirm-executables`     | 确认可执行披露                   |
| `--skip-capability <cap>`   | 跳过 optional 能力            |
| `--default-locale <locale>` | 默认语言（`draft create`）      |
| `--locale-option <locale>`  | 语言选项（可多次传）                |
| `--engine`                  | 启用 Engine（`draft create`） |

## Bundle 和 publish 的关系

`comet creator` 是创建和恢复入口，`comet publish` 是发布入口。`comet bundle` 是高级后端，直接操作内部状态。

| 命令              | 定位           | 适合谁         |
| --------------- | ------------ | ----------- |
| `comet creator` | 创建状态和恢复入口    | 日常使用、自动化    |
| `comet publish` | 用户发布入口       | 日常使用        |
| `comet bundle`  | 高级 Bundle 后端 | 审计、调试、自动化集成 |

<Info>
  面向用户的发布路径请优先使用 <a href="/zh/cli/publish">comet publish</a>。<code>comet bundle</code> 只在排障或审计时直接使用。
</Info>

## 下一步

* [comet publish](/zh/cli/publish) — 用户发布入口
* [comet creator](/zh/cli/creator) — `/comet-any` 创建状态和恢复入口
* [Skill Creator 概览](/zh/skill-creator/overview) — `/comet-any` 如何在内部使用 Bundle
* [发布和分发 Skill](/zh/skill-creator/publishing) — readiness 和分发流程