> ## 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 eval

> 直接评估本地 Skill 或 comet/eval.yaml，并生成可复查的评估报告。

`comet eval` 是独立的 Skill 评估入口。你可以直接评估已有的本地 Skill，不需要先运行 `/comet-any`，也不需要预先创建 `comet/eval.yaml`。

## 最短路径

```bash theme={null}
# 只检查 Skill、manifest 和任务发现
comet eval ./my-skill --collect

# 低成本冒烟评估
comet eval ./my-skill --quick --html

# 运行完整的本地评估
comet eval ./my-skill --html
```

`target` 可以是 Skill 目录、直接的 `SKILL.md`，或 `comet/eval.yaml`。传入目录时，Comet 会自动发现其中的 manifest；没有 manifest 时，普通运行会在受限快照上自动生成 2–4 个任务，不会改写 Skill 源文件。

* `--collect` 只做静态发现和配置检查，不启动 Agent、Docker、插件、凭据或网络请求。
* `--quick` 使用固定的 `generic-skill-smoke` 任务，适合早期冒烟。
* `--html` 同时生成 Markdown 和 HTML 报告。
* 报告和运行状态默认写入 Skill 或 `--project` 指定项目下的 `.comet/eval/runs/`。

如果 Skill 位于另一个项目中，可以显式指定包含 eval harness 的项目根目录：

```bash theme={null}
comet eval ./my-skill --project ./my-project --html
```

## 用户级 `.env` 配置

已发布的 Comet CLI 不需要用户拉取源码。把配置文件放在现有用户级 Eval 自定义目录旁：

```text theme={null}
Unix:    ~/.comet/eval/.env
Windows: %USERPROFILE%\.comet\eval\.env
```

主任务（Bench）和 LLM-as-judge 使用独立的模型、地址和凭据：

```dotenv theme={null}
BENCH_API_KEY=subject-key
BENCH_BASE_URL=https://subject.example/v1
BENCH_MODEL=subject-model

BENCH_JUDGE_API_KEY=judge-key
BENCH_JUDGE_BASE_URL=https://judge.example/v1
BENCH_JUDGE_MODEL=judge-model
```

当前进程环境变量优先于 `.env`；CLI 选项和 manifest 又优先于环境变量。Claude Code、Codex、CodeBuddy 会把通用配置映射到各自的原生配置；Codex 使用隔离的运行时 `config.toml`；Qoder 只使用其官方支持的认证和服务地址配置。显式的 Agent 原生变量优先于通用 fallback。

安全边界：Eval 不会把 API key 写入发布包、manifest、报告或 Skill 工作区。Docker 运行 Agent 时，Codex、Qoder、CodeBuddy 使用容器内独立的临时配置根；Codex 的 `config.toml` 只引用环境变量，CodeBuddy 的 `settings.json` 只使用 `apiKeyHelper`，实际密钥只存在于本次容器进程环境中，运行结束后销毁。

## 任务选择

任务按以下优先级选择：显式 `--task`、`--quick`、manifest 中的 `evaluation.tasks`、`recommendedTasks`，最后才是自动生成的任务。自动生成的任务会按 Skill 快照、Agent 和评估配置缓存，后续运行可以复用。

需要稳定验收条件时，可以在 `comet/eval.yaml` 中写 inline task：

```yaml theme={null}
evaluation:
  tasks:
    - name: writes-summary
      prompt: Create summary.md.
      expect:
        files:
          - summary.md
        contains:
          summary.md:
            - '# Summary'
```

也可以用 `source` 引用 Skill 包内带有 `task.toml` 和 `instruction.md` 的任务包。inline task 支持文件、文本、JSON 和命令检查；任务的工作区和期望产物必须留在允许的 Skill 包或评估工作区内。

## 选择评估 Agent

默认 Agent 是 `claude-code`，也可以选择 `codex`、`qoder` 或 `codebuddy`：

```bash theme={null}
comet eval ./my-skill --agent codex --model subject-model
```

主 Agent 和 LLM-as-Judge 可以分别设置：

```yaml theme={null}
execution:
  agent: codex
  model: subject-model
  baseUrl: https://subject.example/v1

judge:
  agent: claude-code
  model: judge-model
  baseUrl: https://judge.example/v1
```

CLI 选项优先于 manifest。启用 Judge 时，需要为 Judge 提供独立模型和凭据；它不会继承主 Agent 的凭据。

自定义 Agent 必须先注册适配器，不会因为可执行文件位于 PATH 就自动发现。适配器目录为：

```text theme={null}
~/.comet/eval/adapters/<agent-id>/adapter.yaml
```

注册后，通过同一个选项选择它：

```bash theme={null}
comet eval ./my-skill --agent my-agent
```

## 选择评估套件

`local` 是默认套件，适合本地开发和 HTML 报告。需要团队追踪时，可以选择已有的 LangSmith 套件：

```bash theme={null}
comet eval ./my-skill --suite langsmith --html
```

需要把任务轨迹、评分和实验摘要同步到 Langfuse 时，使用 beta18 新增的 Langfuse 套件：

```bash theme={null}
LANGFUSE_PUBLIC_KEY=pk-lf-... LANGFUSE_SECRET_KEY=sk-lf-... \
  comet eval ./my-skill --suite langfuse --html
```

Langfuse 套件会继续生成本地报告。`--collect --suite langfuse` 不初始化 SDK、不联网，也不会下载插件。

## 常用选项

```text theme={null}
comet eval [target] [options]
```

| 选项                       | 用途                                  |
| ------------------------ | ----------------------------------- |
| `--project <dir>`        | 指定包含 `eval/` 的项目根目录                 |
| `--manifest <path>`      | 直接指定 `comet/eval.yaml`              |
| `--skill-path <path>`    | 指定本地 Skill 目录或 `SKILL.md`           |
| `--skill-name <name>`    | 指定 Skill 名称                         |
| `--agent <agent>`        | 选择主评估 Agent                         |
| `--model <model>`        | 覆盖主评估模型                             |
| `--base-url <url>`       | 覆盖主评估 API 地址                        |
| `--judge-agent <agent>`  | 选择独立 Judge Agent                    |
| `--judge-model <model>`  | 选择独立 Judge 模型                       |
| `--judge-base-url <url>` | 覆盖 Judge API 地址                     |
| `--profile <name>`       | 选择评估配置 profile                      |
| `--report-config <path>` | 指定报告配置文件                            |
| `--suite <suite>`        | 选择 `local`、`langsmith` 或 `langfuse` |
| `--task <task>`          | 只运行指定任务                             |
| `--collect`              | 只做静态发现和预检查                          |
| `--quick`                | 使用固定冒烟任务                            |
| `--html`                 | 生成 HTML 报告                          |

## 如何看结果

运行前，CLI 会打印 target、suite、任务、Experiment 和报告路径。报告会区分 `harness`、`workflow`、`task` 和 `model` 归因：

* `harness`：依赖、Docker、路径或环境问题；
* `workflow`：Skill 流程没有达到预期；
* `task`：任务定义或验收条件有问题；
* `model`：模型行为或调用不稳定。

`comet eval` 评估 Skill 的产品能力；`comet skill check` 只检查某次 Skill Run 是否满足 runtime checks，两者用途不同。

## 下一步

* [Eval Agent 启动配置](/zh/eval/agent-setup) — 准备 Claude Code、Codex 或 Qoder 的 CLI、认证和模型协议
* [评估系统概览](/zh/eval/overview) — 了解评估配置和评分方式
* [读取评估报告](/zh/eval/reports) — 理解报告中的通过率和失败归因
* [comet publish](/zh/cli/publish) — 将评估证据用于发布判断