# 模型发现输出约定

- 模型查询详情应提供可直接用于生成命令的参数值；图片 `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 命令入口时，以该命令的实际注册和请求路径为准；不能因业务场景相近而改到另一条命令。共享 helper 的扩展只对目标入口暴露，并同步纠正方案、示例和验收范围。
- 用户要求最小接入时，只新增用户明确要求的能力和完成流程不可缺少的字段；不能因为下游协议包含某字段，就顺手扩展 CLI 参数、素材入口或配套抽象。先证明它属于本次必需范围，再修改。改动前检查实际调用入口和相邻实现，复用现有逻辑与组织方式；例如命令统一注册后，由 `adaptercli.Configure` 过滤可用性，不在各注册点另加开关。注册、命令判断和日志共用的命令名统一放入 `internal/commandnames`，不要重复维护字符串。只复用语义兼容的实现，不为表面相似另建通用层。用户要求删除某方法的配置依赖时，只收敛该方法及直接关联的断言、说明，不扩大为删除全局配置或其他调用路径。能力限制按实际依赖判断：关闭本地登录不等于禁止 adapter 已能认证的业务查询；账号配置的读写只校验账号是否可识别，不能扩大成禁用整组命令。本地空间记录与 API 鉴权分开：缺少本地账号标识或 Store 不应单独阻断显式 --team-id，账号标识只用于本地记录隔离；请求仍复用既有认证并由 API 校验团队权限。用户质疑限制时先纠正前提，不能只移动判断位置。无需空间的命令跳过空间初始化即可，不要仅因携带合法的全局 `--team-id` 额外拒绝执行。放宽某一阶段的参数要求时，只调整该阶段所需条件，保留无关的既有校验；服务端校验简化不得自动扩展为删除 CLI 原有校验。已固定或缓存的值不等同于用户显式输入，不能据此放宽恢复条件；范围解析复用最终请求数据，避免在预处理和业务入口分别处理 ID 导致不一致。空间选择优先级由 Session 统一维护，Store 提供记录读写，不重复决定空间；当前团队的 TeamID 统一透传给 API origin，由 API 决定是否消费，不用接口白名单限制请求头；操作分类只用于成功后的本地记录保存，外部域名仍不携带身份头。实际请求的账号检查集中在发送前，离线预览单独检查，避免同一请求重复解析和读取凭证。命令精简先核对参照 CLI 的真实行为；列表已能标识当前选择时复用该输出，不重复增加 current 入口；同步移除仅为被删交互服务的辅助代码、测试和文档。
- 验证独立配置时，配置值可以暂与原配置相同；以服务端实际选中的 scene 和同一 Run 的消费证据证明路由，单独报告值是否不同，不把数值必须不同当成额外准入条件。空间积分查询还须对照同账号、同团队、同查询范围的 Web 真实余额，并核对下游实际查询的积分资产；请求成功、TeamID 透传或两个空间返回相同数值，都不能单独证明团队余额正确。团队总余额、待分配余额和成员余额须分别报告。
- 定位到下游返回不符，不等于必须修改下游服务。先核对当前接入层是否能复用已验证的正确接口；推荐修法须比较调用契约、现有依赖及 RPC ACL，不能把扩大到另一服务作为唯一方案。

# 宿主来源统计

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

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

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