AGENTS.md git:20261014.d637267A

Immutable. This exact content never changes and is served at /api/v1/blob/eb2545b08460bfac.

# 模型发现输出约定

- 模型查询详情应提供可直接用于生成命令的参数值；图片 `ratio` 只接受服务端数字枚举，查询的 `options/default` 同样使用数字，并用 `option_labels` 展示比例含义；视频 `ratio` 保持其接口要求的比例字符串。不提供数字和比例字符串两套图片输入，映射不按数组位置或展示文案推断。
- 覆盖 IDL 已定义且生成入口可消费的枚举；未知枚举直接跳过，不猜测或回退到其他值。已定义但没有 CLI 请求表达方式的枚举须明确识别为不可用。
- 内部配置指纹不向用户输出；原始配置缓存和用户展示结构分离，保留可选字段缺失与零值的区别。参数通用元数据（`label`、`description`、`required_field`、`active_when_any`）统一保留，只在确有契约差异时按模型类型分支。创作模式的提交值按服务端下发的模式 key 映射，不额外硬编码模型名单；模型特例必须有明确契约依据。
- 模型级 `is_default` 不向 CLI 用户输出；服务端默认标记不等于用户授权代选模型。参数级默认值继续展示，原始配置缓存保持完整。
- API 模型查询保留上游 `name` 展示名称和 `key` 模型枚举，白名单只控制准入，不用枚举覆盖名称。CLI 图片模型列表、搜索、详情、帮助和示例只向宿主展示 `name`，详情不透传含枚举的计费等内部配置；查询和生成使用完整名称，仅提交时从原始配置解析 key。不维护静态名称映射，不按简称猜模型；名称缺失、与 key 相同、重复或未找到时明确失败。视频保持 key 契约。
- 模型发现验收必须分别核对用户确认的预期模型集合与真实接口返回值转换；CLI 与接口同时少返回模型不能判为完整通过。
- `Seedance_2.0_mini` 和 `Seedance_2.0_mini_lite` 允许省略生成分辨率，由服务端默认 `720p`；CLI 不主动补值，不因模型查询缺少分辨率维度而将该参数标为必填或伪造配置。

- 安装引导的最小兼容修复只补必需命令检查；可选参数已有 `--help` 判断约定时复用该约定，不另增能力返回字段或升级条件。

# 短剧 Skill 描述约定

- description 应覆盖剧本创作与解析、资产素材生成、故事板规划生成、视频产物交付的完整能力及触发场景，不能将短剧 Agent 缩窄为剧本文本创作或文件查询工具。

# 最小改动范围

- 用户要求最小接入时，只新增用户明确要求的能力和完成流程不可缺少的字段；不能因为下游协议包含某字段，就顺手扩展 CLI 参数、素材入口或配套抽象。先证明它属于本次必需范围，再修改。放宽某一阶段的参数要求时，只调整该阶段所需条件，保留无关的既有校验；服务端校验简化不得自动扩展为删除 CLI 原有校验。
- 验证独立配置时，配置值可以暂与原配置相同；以服务端实际选中的 scene 和同一 Run 的消费证据证明路由，单独报告值是否不同，不把数值必须不同当成额外准入条件。

# 宿主来源统计

- 评估 CLI 与 HTTP API 来源隔离时，应假设用户可以读取 CLI 源码、复现请求并使用自己取得的 CLI 凭证。独立 URL、Header、客户端签名或专属 AK 不能证明请求由官方 CLI 发出；专属凭证只能标识授权渠道。客户端自报来源可用于统计，差异价格、权益和配额应依据服务端核验的授权与计费策略，不能把来源声明当作防模拟边界。

- `--source` 由宿主 Agent 根据可信运行环境填写真实、稳定的平台标识；不得固定为 `codex` 或默认代填，来源未知时省略。示例中的平台名仅为示例，生成提交由 CLI 透传为服务端 `platform`；安装/更新的 `report_telemetry` 用新增 `host_platform` 承载宿主标识，保留已有 `source` 的安装入口语义和 `platform` 的操作系统语义。已有上报字段被消费时，不得改写其含义，应新增独立字段。

- 来源采集应尽力而为：显式 `--source` 优先，其次宿主提供的 `PIPPIT_CLI_SOURCE`，最后使用已核实的运行标记；显式空值禁用兜底。仅上报稳定宿主名，不上传会话 ID，不用安装痕迹、API Key 或 prompt 猜来源，冲突时省略。新增运行标记须有实际环境或官方实现依据。npm postinstall、install 向导和原生 update 都必须覆盖同一来源优先级；验证须检查各入口实际发出的请求体，不能只验证通用解析函数或原生命令。