ae-evaluation

ae-evaluation

对于现有操作，请使用 ae-cli evaluation +<command> [options]；对于新功能，请使用下方的资源命令。全部 121 条命令均面向 Agent Evaluation 平台。 AE Agent 资源管理归 ae-agent 负责；此 Skill 用于管理评估资产和被测 Agent。

只阅读相关参考文档

执行命令前，请先阅读该操作对应的参考文档。不要加载所有参考文档。 参考文档包含命令输入、JSON 契约和任务专属工作流；如需其他标志，请使用命令 --help。

任务	参考文档
创建／导入数据集、管理字段和用例、发布版本	datasets.md
配置 LLM 裁判／模板、发布评估器版本、校准或优化提示词	evaluators.md
创建／配置／启动／重试／取消运行、检查结果／追踪记录、导出结果	runs.md
配置／测试模型和 Agent、管理凭据	connections.md
更改资源可见性或管理项目成员	access-and-members.md
将导入／导出的文件下载到磁盘	files.md
创建／更新／删除定期评估计划	schedules.md
连接／导入 AI Monitor 数据、配置 TE 报告、发现 TE Claude 目录	integrations.md

端点和身份验证

• 在个人终端和 AE 沙箱中，评估命令默认使用当前 AE Host，并调用 <current-host>/agenteval/api/v1/...（如果主机地址末尾有可选的 /agent，会将其移除）。使用 --host 选择其他 AE Host。评估请求使用该 AE Host 配置的 HTTP 或 HTTPS 协议，与其他 AE 命令保持一致。旧版 --endpoint 和 AE_EVAL_BASE_URL 值只能与当前 AE Host 匹配；其他值会在发送凭据前报错。请移除这些设置，并使用 --host 选择主机。
• 会话交换和评估请求均拒绝重定向；会话交换超时时间为 30 秒。
• 路径资源 ID 只能包含字母、数字、连字符或下划线；分隔符和 URL 转义语法会在本地被拒绝。
• 请使用在线平台。不要建议使用 localhost／环回端点，也不要从本地的 agent-test/.env 获取令牌。
• 如果显式设置了 AE_EVAL_ACCESS_TOKEN，身份验证会使用该变量；令牌只会作为 Authorization: Bearer 发送，绝不能出现在命令参数或输出中。
• 在 AE 沙箱中，如果未设置 AE_EVAL_ACCESS_TOKEN，ae-cli 会自动通过 te-claude 将沙箱提供的 cli-token 交换为短期评估会话。CLI 令牌绝不会发送给 Agent Evaluation。如果该令牌可访问多个 TE 项目，请将 AE_EVAL_TE_PROJECT_ID 设为已授权的 TE 项目 ID。
• 在沙箱外，如果未设置令牌，CLI 会立即返回 EVAL_ACCESS_TOKEN_MISSING，并提供 token_missing 引导信息；不会发送网络请求。模块是否可用以及服务运行状况仍未经检查。请引导用户通过平台 Web 控制台（sessionStorage.getItem('agent.evaluation.session-token')）或 POST /agenteval/api/v1/auth/session 获取会话令牌。切勿在聊天中索要令牌。
• 成功的命令默认返回 JSON；请根据实际错误信封排查失败原因。

评估功能的可用性和引导

AI Evaluation Center 是可选的部署模块。CLI 命令／Skill 可用并不代表服务器已安装该模块，也不代表用户有权访问该模块。

• 当错误包含 error.details.onboarding 时，请按照下方针对状态的范围处理。不要盲目重复失败的操作、修改标志、刷新令牌，或使用直接 HTTP 调用绕过拒绝。这是针对主机 Agent 的指令，不是持久化的 CLI 熔断器。可以继续进行独立的本地工作。
• 首先保留本地工作：当用户要求整理并上传数据集时，尽可能完成并保存本地 CSV/JSON。确认文件的实际路径。如果写入超时、没有收到响应，或遇到网关/服务器故障，请说明写入结果尚未确认：服务器可能已经接受了写入。不要声称成功或失败，也不要盲目重新提交。恢复连接后，使用已知资源/导入 ID 进行授权的只读状态检查，以核实结果。如果没有可靠的标识符或查询方式，请先让管理员/支持人员核实，再进行其他写入。
• 读取 onboarding.status，使用用户所用的语言说明证据，并遵循其 next_steps：
  • module_not_detected：在确认受影响主机的部署/路由情况之前，停止在该主机上执行后续评估命令。API 路由未被检测到（通用路由 404 或 HTML 回退）。可选模块可能缺失，也可能是路由配置有误。联系 ThinkingData 服务代表（CSM 或技术支持）核实部署/路由，在需要时安装模块并授予访问权限。不要断言模块肯定未安装。
  • access_not_granted：只停止被拒绝的操作。可以继续执行其他独立且已获授权的操作；例如，删除操作被拒绝，并不妨碍读取已获授权的数据集。不要为了探查或绕过拒绝而运行其他命令。只有在确认访问范围后，才停止整个项目或模块。请管理员或 ThinkingData 支持检查所需权限（相应的 READER / EDITOR / ADMIN）。单凭 403 既不能证明整个集群都拒绝访问，也不能证明模块已安装；不要建议重新安装或轮换令牌。
  • token_missing：在该主机配置令牌之前，停止远程评估操作。外部终端没有令牌；未发送请求，也未检查端点是否可用。按照有条件的 Web 控制台说明操作；如果应用启动器中没有相应入口，请求管理员/支持人员核实，不要让用户前往并不存在的页面。此状态不能证明所有评估服务都运行正常。
  • availability_unknown：停止盲目重试失败的操作。网络错误、超时、服务器故障、无效响应以及缺少沙盒会话路由，都不能证明安装状态。请相关人员核实主机/网络/服务/路由情况；不要将服务中断说成必须安装模块。恢复连接后，可通过授权的只读状态检查核实尚未确认的写入，但不得重新提交。
• 简要说明这三种能力与用户任务的关系：Datasets 用于管理单轮/多轮测试用例及其版本，支持通过 CSV/JSON 导入和使用 AI Monitor 跟踪；Evaluators 提供模板/自定义 LLM 裁判、人工校准和提示词优化；Evaluation Runs 用于测试在线 Agent 或对预设输出评分、安排回归测试，以及检查低分案例和跟踪。请为中文或英文用户自然地翻译这段说明；CLI 封装信息保持英文。
• 如果用户只询问功能，请直接说明，无需发起网络调用。如果用户还请求查看当前数据集/运行记录，而首次调用报告了 onboarding 状态，则按照上述状态对应的停止范围处理；不要仅仅为了展示其他功能而再次调用。
• 现有业务错误代码、错误类型（api）和退出代码保持不变。Onboarding 是附加信息；普通业务 404 错误（例如 DATASET_NOT_FOUND）并不表示模块缺失。较旧的 CLI 可能不包含 onboarding 信息；应谨慎使用其诊断证据，不要仅凭一个 404/5xx 推断安装状态。

ID、版本和变更

• 使用 list/get 命令查找真实 ID。UUID 是版本 7 字符串；切勿猜测 ID、JSON 负载结构、频率字段或 lock_version 值。
• 已发布的数据集、评估器和评估任务版本不可变，且与草稿分开。运行和计划会固定版本；现有已发布版本无法覆盖。发布未更改的资源会返回 ASSET_VERSION_NO_CHANGES。
• 输入已知后即可执行读取操作。写入操作需要用户明确意图；除非用户通过 --yes 授权跳过确认，否则高风险操作仍需确认。
• 启用/停用凭据、取消运行、删除、转移所有权、停用模板、更改访问范围，以及成员准入/权限变更都属于高风险写入。查看命令帮助，了解风险和角色要求；参考文档会标明仅限 ADMIN 的操作。
• 每次执行需要 --lock-version 的变更前，都要读取当前资源。每次成功变更都会递增其版本；下一次变更前应重新读取。
• 对运行、数据集、评估器、模型、Agent、凭据、数据集用例、TE 报告配置和 AI Monitor 连接，使用相应的 get 命令。计划使用 +list_schedules；校准用例使用 +list_calibration_cases。
• 字段变更使用数据集版本；用例变更使用用例版本。首次创建 TE 报告配置或 AI Monitor 连接时省略 --lock-version；更新时必须提供当前值，包括 0。
• 异步数据集导入、评估集导入和结果导出，每次尝试都需要全新的唯一 --idempotency-key。轮询相应状态直至完成；仅创建资源并不代表其已就绪。
• 对尚未验证目标的广泛/破坏性写入，优先使用 --dry-run。它会预览请求，但不会执行。
• 评估错误会对提交的凭据值和会话令牌进行脱敏；服务器提供的错误消息和提示不会写入 CLI 日志。稳定的业务错误代码保持不变；非敏感诊断信息仍会保留在 JSON 错误信封中。
• 对单用例和批量写入，用例数据都会在命令日志中脱敏。敏感 JSON 解析失败时，只会报告标志和语法说明，不会回显输入内容。
• 凭据密钥只能写入，无法读取。切勿回显密钥、会话声明或敏感跟踪证据；请使用脱敏的试运行输出。

评估生命周期

1. 使用 +list_dataset_versions 选择已发布的数据集版本。
2. 选择 LIVE_AGENT（默认）以调用 Agent/模型，或选择 PRESET_RESULT 以评估存储在数据集中的输出。PRESET_RESULT 必须省略 Agent/模型配置 ID。IMPORTED_OUTPUT 仅用于旧版数据；切勿推荐使用。
3. 创建草稿运行，绑定至少一个 ACTIVE 评估器（优先使用固定了版本的已发布评估器），并配置完整的字段映射和结果筛选字段。未选择任何字段时，必须显式设置空结果筛选器。
4. 优先在启动前使用 +validate_run。它会在不传入请求正文或锁定版本的情况下执行启动预检。读取最新运行，然后使用其当前锁定版本调用 +start_run。
5. 检查概览/分布，深入查看用例，并参照运行文档了解重试、跟踪和导出的语义。

请阅读 runs.md，了解可执行的操作流程和映射示例。设置数据集、评估器或连接时，只需查阅上文对应的参考文档。

传输方式迁移

现有平台契约公开的是 REST 操作，而不是本仓库中注册的评估能力。新命令继续使用该传输方式处理类型化输入、权限确认和文件操作。这些命令处于过渡阶段；迁移记录请参阅对应参考文档。扩展这些命令前，请检查部署的 Gateway 覆盖情况；优先使用已有的等效能力。

迁移状态：过渡中 所属模块：Agent Evaluation (agent-test) 当前传输方式：经过身份验证的 REST /agenteval/api/v1 Gateway 目标：待定（评估能力注册） 复审日期：2027-01-21 退出条件：一旦有等效的评估能力可用，就将选定的类型化／文件命令迁移到 L2，或将简单包装器替换为 L3；仅在兼容性或编排需求足以构成理由时，保留现有的 + 命令。

此记录也适用于现有 evaluator/run 参考文档中的区域设置和流程证据更新。这是一项迁移计划，并不表示已检查过某个特定的已部署 Gateway。