﻿昆仑星幕 Studio · Windows 中文客户端 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. 打开 Windows 文件夹。
3. 双击 00-START-HERE.cmd。
4. 后续只按中文数字菜单操作。

Windows 只保留 00-START-HERE.cmd 这一个可双击入口；原来的分散快捷入口已经合并到同一个主菜单。

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

两个公网中转分别使用独立 DPAPI 文件；tk.ai-xj.com 继续兼容读取旧 .newapi-key.dpapi。切换中转不会复制 Key，任务恢复会按历史记录回到原中转。

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

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

私有 Spark H3 与本地素材上传
----------------
私有 Spark H3 三档模型固定为：快速预览 `MiniMax-H3-Preview-Spark`、标准质量 `MiniMax-H3-Standard-Spark`、最高质量 `MiniMax-H3-Quality-Spark`。客户端携带用户 NewAPI Key 调用 /v1/files，获得用户隔离的 asset_ 素材 ID，再提交 /v1/videos 生成任务。官方 MiniMax-H3 不得走 /v1/videos，也不使用私有 asset_ / file_ 素材号。

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

公网 asset_ 素材 ID 与内网 file_ 素材 ID 不能跨链路混用。最省事的方式是直接输入本地路径，让客户端自动上传。

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

隐私菜单
--------
全局队列和 Spark 视频库入口固定显示。公网全局队列只读取中转真实返回的脱敏汇总，缺少字段时明确说明而不伪造；Spark 视频库只有手动选择 Tailscale 或局域网后才能执行。

Spark 全局功能由主菜单调用内部脚本；即使绕过菜单直接调用内部脚本，仍会再次验证可信内网。

全局视频库通过列表和单任务 API 显示真实提示词、声音要求、参数与时间；本机 history 不回填提示词，历史缺失字段如实标记。索引只读，不修改任务。

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

生成、声音与速度
----------------
- 八种生成方式全部保留：文字、首帧、首尾帧、参考图片、参考视频、视频+音频、图片+音频、高级多参考。
- H3 支持图片、视频、音频混合参考；普通参考模式也可连续加入多个同类素材，上限为图片 9、视频 3、音频 3，直接回车结束输入。
- 普通任务选“环境声/拟音”，可减少模型无故唱歌。
- 明确台词选“对白/配音”，并填写准确台词；“高级自动”会先询问结构化声音提示，填写后写入声音提示字段，不填写则由模型自由决定，可控性最低。
- 快速预览适合测试；最高质量、15 秒和参考素材任务会明显更慢。
- 客户端展示服务返回的真实进度、阶段、步骤、ETA 和排队位置，不编固定百分比。

下载与恢复
----------
- 成片先写入 .part，验证 MP4 后再落为正式文件。
- 下载失败不丢任务，选择“继续上一次任务”即可重试。
- 公网成片下载自动携带 NewAPI Bearer。
- Windows 真机公网生成、等待和鉴权下载已经跑通，成片正常保存在 output 并显示 SHA256。v1.1.5 包含 Explorer 原生命令行精确选中文件和目录回退，仍须本包真机复验。

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

系统要求
--------
- Windows 10/11。
- Windows PowerShell 5.1 或 PowerShell 7。
- Windows 自带 curl.exe。
- 全局队列和视频库直接读取 Spark HTTP API，不需要 Windows OpenSSH；需手动选择可达的可信内网。

发行包不包含 Key、DPAPI 文件、历史任务、提示词、素材或成片。
logs、updates、diagnostics、state、history 和 output 都是运行期目录，不应复制进发行包。

版本：1.1.5 · 2026-09-16
