昆仑星幕 Studio · Apple 中文客户端 v1.1.5
==========================================

当前客户端契约：native-video-billing-rc4。

主菜单先选择“底层模型”，再选择“算力来源与网络协议模式”。私有 Spark H3 与官方供应商协议不能混用；客户端会在提交前拦截不兼容组合。

官方原生视频 API
----------------
官方模型全部经过当前选择的 tk.ai-xj.com 或 kunluncloudrelay.btcmg.com.cn，使用当前用户自己的 NewAPI Key，按供应商原样保留官方路径、模型 ID、任务号、状态和结果地址：
1. MiniMax H3 官方 V2：模型固定为 MiniMax-H3，支持官方 content[] 的图片、视频、音频混合和多素材；参考素材必须是供应商可访问的 HTTPS 地址，不使用客户端私有 /v1/files 上传。
2. HappyHorse / Wan 官方 DashScope：首版只开放已实现并验证的 happyhorse-1.1-t2v；Wan 尚未确认模型 ID，不冒充已接入。
3. Seedance 官方 Ark：接口已接入，但当前 Ark 渠道、余额和模型权限尚未完成真实验收，不能据此宣称生产可用。
官方任务有独立的查询、等待下载和取消入口；HappyHorse 官方接口没有取消操作。供应商签名成片地址只用于下载，不写入日志。

第一次使用
----------
1. 完整解压压缩包。
2. 打开 Apple 文件夹。
3. 双击 00-START-HERE.command。
4. 之后只需要按数字选择，不需要输入英文档位、声音模式或画面比例。

Apple 只保留 00-START-HERE.command 这一个可双击入口；全部功能都在主菜单中。

如果 macOS 第一次阻止打开：右键 00-START-HERE.command → 打开 → 再确认一次。

四种算力来源与网络协议
----------------------
1. tk.ai-xj.com：默认公网 NewAPI 中转，需要该站自己的用户 Key。
2. kunluncloudrelay.btcmg.com.cn：昆仑云公网 NewAPI 中转，需要独立用户 Key。
3. Spark Tailscale：可信内网直连，无 Key。
4. Spark 局域网：家庭局域网直连，无 Key。

两个公网中转的 Key 分别存入不同 macOS 钥匙串 service；tk.ai-xj.com 继续兼容读取旧 Keychain service。切换中转不会复制 Key，任务恢复会按历史记录回到原中转。

客户端不再自动探测或切换网络，也不会在失败时跨链路回退。需要内网功能时，从主菜单手动选择对应模式；旧版 auto 配置只按公网兼容处理。

可信内网流量强制绕过系统代理。公网若必须指定代理，可在 h3-config.json 的 public_proxy 中填写；留空为公网直连。

私有 Spark H3 与本地素材上传
----------------
私有 Spark H3 的三档模型固定为：快速预览 `MiniMax-H3-Preview-Spark`、标准质量 `MiniMax-H3-Standard-Spark`、最高质量 `MiniMax-H3-Quality-Spark`。客户端会：
1. 携带当前用户 NewAPI Key；
2. 按当前生成档位选择上述 `-Spark` 模型；
3. 上传到公网 /v1/files；
4. 获得仅属于当前用户和 Spark 节点的 asset_ 素材 ID；
5. 自动把素材 ID放入生成请求。

私有生成提交使用 /v1/videos。官方 MiniMax-H3 不得走 /v1/videos，也不使用私有 asset_ / file_ 素材号。

输入素材时，可把文件从 Finder 直接拖进窗口。客户端会在上传前检查本地文件的大类；例如把 MP4 放进“参考图片”会立即提示改选参考视频，不会等上传后才报错。

公网 asset_ 素材 ID 不能在 Spark 直连模式使用；内网 file_ 素材 ID 也不能经公网使用。直接选择本地文件即可避免混用。

Spark 当前上传素材通常约 24 小时有效。客户端会在服务返回到期时间时显示，请及时提交任务。

主菜单与隐私
------------
主菜单固定提供生成、底层模型、算力来源、统一任务中心、全局队列、本机任务记录、视频库、成片、Key、诊断、更新、日志和说明。

公网全局队列只读取中转真实返回的脱敏汇总，没有字段时明确说明；不会伪造节点或排队数。Spark 视频库只有手动选择可信内网后才能执行，通过列表和单任务 API 显示真实提示词、声音要求、参数与时间；本机 history 不回填提示词，历史缺失字段如实标记。

实时视频库显示服务/引擎、运行/排队、进度/步骤/ETA 和观察时间；活跃约 5 秒、空闲约 15 秒刷新，耗时受网络和任务数影响。保留搜索和正在播放的视频；断网保留快照并告警。可立即刷新、暂停页面同步或关闭查看器。
本地查看器仅监听 127.0.0.1，不需要安装服务。离开页面约 2 分钟或运行满 8 小时停止，需从主菜单重开。播放时才取新签名链接，本地索引不保存签名 URL。暂停/关闭页面不会取消生成任务。
本机任务记录可检索并选择：复制任务号、查询、等待下载、定位已有成片；支持取消的链路会显示需确认的取消选项。记录坏行跳过，保存失败不重新提交任务。
列表显示最近观测状态/时间与成片是否存在，原始历史保留，新观测单独存于 state/task-observations；只有真实查询才更新状态。预览失败点击“立即刷新”重试，不打断正在播放的视频。

生成与声音
----------
- H3 支持图片、视频、音频混合参考；普通参考模式也可连续加入多个同类素材，上限为图片 9、视频 3、音频 3，直接回车结束输入。
- 普通任务的声音选“环境声/拟音”，可减少模型无故唱歌。
- 有明确台词时选“对白/配音”，并填写准确台词或声音要求。
- “高级自动”会先询问“结构化声音提示（建议填写）”；填写后写入声音提示字段，不填写则由模型自由决定，结果可控性最低。
- “快速预览”适合试玩；“最高质量”、15 秒和参考素材任务会明显更慢。

下载与恢复
----------
- 下载先写入 .part，验证 MP4 后再成为正式文件。
- 下载失败不会丢任务；从主菜单选择“继续上一次任务”即可恢复。
- 公网下载自动携带 NewAPI Bearer。
- 成片保存在 output 目录，并显示 SHA256。v1.1.5 会尝试打开 Finder 并选中成片，但仍须 Apple 真机验收；失败时可从主菜单打开本机成片目录。

更新、日志与诊断包
------------------
- 客户端启动时最多每 24 小时自动检查一次；没有新版本或暂时断网时不打扰，发现更高版本才询问是否更新。也可随时从主菜单手动检查。
- 更新读取 h3-config.json 的 update_manifest_url；正式使用只接受 HTTPS。
- 本版为 v1.1.5 stable；后续正式版本继续通过同一清单自动发现。
- 只有用户明确选择“立即安全更新并重启”后，才会下载到 updates，核对 size 与 SHA256，检查 ZIP 路径、平台和 VERSION.txt，再备份并替换程序文件；失败自动恢复原版本。
- 更新保留 h3-config.json 中的用户设置、钥匙串 Key、state、history、output、logs 和 diagnostics；也可以选择仅下载校验而不安装。不会静默更新。
- 默认日志写入 logs/studio.log.jsonl，包含时间、版本、平台、run_id、动作、链路、HTTP/curl、耗时、任务状态和错误类别，并按大小/数量轮转。
- 日志默认不写完整提示词、素材内容或用户 Key，并自动脱敏 Bearer、sk-类 Key和签名 URL 查询串。
- “导出脱敏诊断包”只打包二次脱敏日志与非敏感系统摘要，不包含 state/history/output、提示词、素材或成片。

系统要求
--------
- macOS 自带 Python 3、curl。
- 全局队列和视频库直接读取 Spark HTTP API，不需要 SSH 登录；需手动选择可达的可信内网。

logs、updates、diagnostics、state、history 和 output 都是运行期目录，不应复制进发行包。

版本：1.1.5 · 2026-09-16
