发布你的应用业务 SDK
为应用自己的业务能力设计、测试、发布和维护领域 SDK；平台 SDK 与应用 SDK 的职责边界在这里一次说明。
本页讲的是你的应用自己的业务 SDK：例如一个应用把“项目、素材、任务、运行记录”开放给其他应用调用时，由该应用开发者维护的 Python、Go、JavaScript 等客户端包。
它和平台提供的 jusp-platform-sdk 不是一回事：
| 名称 | 谁维护 | 负责什么 | 是否上传到平台应用版本 |
|---|---|---|---|
jusp-platform-sdk | 平台 | Runtime、模型/媒体调用、会话、应用间通用授权等平台能力 | 作为应用依赖安装并随镜像打包；不单独作为应用版本源文件上传 |
jusp-cli（命令 jusp app） | 平台 | 在已有项目中生成接入文件、校验、打包和提交版本 | 是开发工具，不是应用业务 SDK |
| 应用业务 SDK | 提供该业务的应用开发者 | 该应用自己的 HTTP/OpenAPI、DTO、错误和业务方法 | 不上传到平台 SDK 索引；随应用自己的发行渠道发布 |
如果应用只供用户在自己的页面里使用，不需要被其他应用调用，可以不开发业务 SDK。只有明确存在跨应用调用、合作方集成或批量自动化需求时，才建立本页所说的 SDK。
一、先定清楚公开合同
SDK 不是把内部 Python 函数换一个名字。先写一份应用自己的、版本化的 HTTP/OpenAPI 合同，再从合同实现 SDK。合同至少应包含：
| 合同部分 | 要写清楚什么 |
|---|---|
| 资源与方法 | URL、HTTP 方法、用途、必填/可选参数、分页和排序 |
| 请求与返回 | JSON 字段、类型、枚举、单位、时间格式、空值规则和示例 |
| 错误 | 401、403、404、409、422、429、5xx 的含义、是否可重试和处理建议 |
| 幂等与并发 | 哪些写操作必须带幂等键，重复请求的结果，版本冲突规则 |
| 异步任务 | 创建、查询、恢复引用、终态和失败信息；不能把“请求已接受”写成“已完成” |
| 能力版本 | 例如 integrations/v1；这是应用领域 API 版本，不是平台 SDK 版本 |
| 安全边界 | 只接收平台签发的受限应用授权；不接受用户 token、RuntimeSession 转发或长期共享密钥 |
合同中的名称应是业务名称，不要把平台数据库表名、工作负载名、Helm/集群字段、内部 ServiceAccount 或内部服务地址暴露给 SDK 使用者。
如果其他应用调用你的应用，清单中只声明稳定的 appKey、apiVersion 和能力名。提供方应用自己维护 OpenAPI、SDK、固定成功/失败样例和本地 fake；平台只负责通用授权和受控路由，不替应用设计业务方法。
二、推荐的项目结构
下面是一个 Python 业务 SDK 的最小结构，名称按你的应用替换：
myapp-sdk/
├── pyproject.toml
├── src/myapp_sdk/
│ ├── __init__.py
│ ├── client.py # 同步客户端
│ ├── async_client.py # 异步客户端（如果业务需要）
│ ├── models.py # 对外 DTO
│ ├── errors.py # 稳定异常类型
│ └── transport.py # 超时、连接池、响应解析
├── openapi/
│ └── integrations-v1.yaml
├── tests/
│ ├── contract/
│ ├── fake_server/
│ └── test_errors.py
├── docs/
│ ├── quickstart.md
│ └── reference.md
├── CHANGELOG.md
└── LICENSESDK 的公开导出面要小而稳定。客户端应支持连接复用、明确的连接/读取超时和结构化错误；只对幂等的读取请求自动重试，创建任务、提交变更等非幂等写操作必须由调用方传稳定幂等键，不能盲目重试。
提供方 SDK 验证应用间授权时，可以使用平台 jusp-platform-sdk 的通用 AppGrantClient 原语；业务 SDK 不应把平台 RuntimeSession、用户凭据或内部 ServiceAccount 暴露给调用方。调用方只传自己的业务参数和一次性受限授权。
三、实现本地假服务和联网调试
本地模式：固定 fake，不访问平台
本地模式的目标是验证 DTO、错误分支、轮询和业务编排，不是模拟真实数据。提供方 SDK 应提供一个固定 fake 或测试 fixture：
- 请求路径、字段和响应结构与 OpenAPI 完全一致；
- 至少覆盖成功、参数错误、无权限、资源不存在、冲突、限流、超时和异步失败；
- 数据使用明显的测试值，不读取生产数据库；
- 可以由调用方测试进程启动，也可以作为独立本地 HTTP 服务启动。
调用方用 jusp app dev --local --dependency appKey=http://127.0.0.1:<port> 接入这个本地提供方。CLI 只接受清单中声明的依赖和回环地址，两个开发者进程可以直接联调；平台不访问开发者局域网，也不为应用猜测业务协议。
如果双方要验证真实 SDK 的授权和跳转，不要各自启动互不相通的模拟器。先用 --fixture ... --serve 启动一个共享模拟器，再分别 --attach，选择示例身份。具体命令见jusp app 使用指南中的“双应用本地联调”。共享模拟器检查声明、请求摘要和一次性启动码；它不替应用生成作品或课堂业务数据。
联网模式：验证真实授权和路由
联网调试由调用方在应用开发者工作台发起，平台签发短期、限应用和候选版本的调试授权。它用于验证真实公网路由、授权校验和响应，不等于正式用户会话。涉及平台模型或媒体能力时，按照当前账户的真实余额、限流和计费规则执行。
业务 SDK 应把 base URL、令牌和候选版本作为运行时配置，不写进源码、仓库、镜像或日志。调试完成后立即撤销或等待凭据过期；正式运行使用平台注入的应用运行环境，不能复用调试令牌。
双方应用都在本地时，提供方使用 --receive-from 登记接收许可，调用方使用 --dependency 和 --receiver 配对。两位开发者各自授权并选择同一个获批测试身份，仅共享配对编号，不共享凭据。业务 HTTP 请求直达本地提供方；平台只校验短期授权，不访问开发机。领域 SDK 对这类请求只发送 AppGrant，不能把调用方的调试 Bearer 转发给提供方。退出接收进程后配对撤销；最长一小时到期后重新授权。
四、测试门槛
每次改动至少执行下面四组检查，并把结果写入发布记录：
- 合同检查：OpenAPI 语法、必填字段、枚举和示例可解析；比较新旧合同，确认没有未声明的破坏性变化。
- 客户端检查：同步/异步方法、DTO 反序列化、异常映射、超时、幂等键和重试策略有单元测试。
- 假服务契约测试：客户端对固定 fake 的成功和失败响应都能得到与线上相同的类型和错误分类。
- 联网冒烟：用短期调试授权调用一个只读接口和一个受控写接口；确认 401/403、过期、跨应用和候选版本不匹配会失败关闭。
不要用“能安装”代替“合同正确”：还要在干净环境安装后运行最小示例，并检查包中没有凭据、内部地址、源码构建临时文件或未声明依赖。
五、版本和发布
应用业务 SDK 有自己的版本号，与平台 SDK 版本、应用显示版本、领域 API 版本分别管理：
| 变化 | SDK 版本建议 | API 版本 |
|---|---|---|
| 只增加可选字段、新方法或兼容的错误说明 | 小版本/次版本 | 保持，例如 v1 |
| 修复实现但不改变公开合同 | 修订版本 | 保持 |
| 删除方法、改变必填字段或改变返回语义 | 新主版本或新包名 | 新建 v2，旧版本按迁移期保留 |
一个可重复的 Python 发布流程如下（包源由应用开发者自己控制，示例域名不是平台地址）：
# 1. 干净环境安装依赖并运行测试
python -m pytest
# 2. 构建并检查发行包
python -m build
python -m twine check dist/*
# 3. 在应用开发者自己的受控包源发布不可变版本
python -m twine upload \
--repository-url https://packages.example.com/ \
-u "$PACKAGE_USERNAME" \
-p "$PACKAGE_TOKEN" \
dist/*
# 4. 用干净环境按精确版本安装验证
python -m venv /tmp/myapp-sdk-release-check
. /tmp/myapp-sdk-release-check/bin/activate
python -m pip install --index-url https://packages.example.com/simple/ myapp-sdk==0.1.0
python -c "import myapp_sdk; print(myapp_sdk.__version__)"发布前创建不可变 Git tag，CHANGELOG.md 写明合同变化、兼容范围、迁移方法和已验证的平台 SDK 版本；包源禁止覆盖同名版本。安装凭据使用短期、只读、最小权限令牌，不写入镜像和日志。
平台当前只负责 jusp-platform-sdk 与 jusp-cli 的正式发行。应用业务 SDK 不上传到平台 Python 索引，也不通过开发机内网 SSH 安装；应用开发者应维护自己的受控包源和安装说明。应用上架时提交的是应用版本接入包与镜像归档，SDK 包仍沿用应用自己的发布渠道。
六、维护和交接清单
每次发布后，在应用自己的教程中同步以下内容：
- 当前 SDK 版本、支持的 Python/运行时版本和兼容的领域 API 版本；
- 安装命令、最小示例、同步/异步方法和完整类型字典；
- 认证、超时、重试、幂等、分页、限流和错误处理；
- 本地 fake 的启动方式、联网调试的申请方式和真实计费提示；
- 变更日志、弃用时间、迁移示例和问题反馈入口。
平台应用中心只维护本页这类通用规范，以及平台 SDK 和 jusp app 的使用手册。应用的业务方法、领域模型、示例数据和应用 SDK 文档由应用开发者负责；平台不会把应用 SDK 的业务内容复制进公共平台手册。
以聚算可觅为例
如果 VideoForge 需要调用聚算可觅，聚算可觅开发者应维护自己的 coommc 领域 API、integrations/v1 OpenAPI、Python/HTTP SDK 和本地 fake。VideoForge 只依赖这些公开合同；平台 SDK 只提供通用会话、模型能力和一次性应用授权，不提供聚算可觅的项目、画布或创作方法。
发布前双方分别完成本地 fake 联调和联网调试，再由平台审核应用版本中的依赖声明与授权范围。任何内部服务地址、数据库结构或平台历史路由都不应进入双方 SDK。
七、发布前自检
- API/OpenAPI 合同有明确的领域版本和兼容策略。
- SDK 方法、类型、错误、超时、重试和幂等规则都有文档和测试。
- 本地 fake 覆盖成功、失败、异步和权限场景，且不访问平台。
- 联网调试使用短期授权，确认真实路由后已清理凭据。
- 发行包在干净环境可安装，版本不可覆盖，Git tag 与
CHANGELOG.md一致。 - 应用自己的教程已更新；平台手册只引用边界和入口，不复制应用业务文档。