Provider 扩展开发

支持矩阵只列下载后可以直接配置的实现。未列出的云厂商需要先完成适配开发，不能只修改配置字符串。

当前支持矩阵

类型	配置值	当前状态
对象存储	qiniu	已有上传、媒体存储与备份链路
数字商品私有文件	qiniu、filesystem	可使用七牛私有签名，或从服务器私有目录生成主站短时下载地址
支付	alipay_wechat	已有支付宝与微信支付订单/回调链路
邮件	smtp	已有 SMTP 发信链路
视频	tencent_vod、volcengine_vod、local	已有对应运行路径；生产环境禁止本地视频模式
AI	minimax、deepseek、rules	已有 AI / 规则模式选择边界，具体模块仍按自身环境配置启用

腾讯云 COS、阿里云 OSS、其他支付网关或事务邮件服务属于未来适配目标，不是 v1 的可选值。

统一适配器契约

共享边界位于 packages/template-core/src/providers.ts：

interface TemplateProviderAdapter<TContext = unknown> {
  readonly id: string;
  readonly kind: "ai" | "email" | "payment" | "storage" | "video";
  health(context: TContext): Promise<{
    ok: boolean;
    details?: Record<string, unknown>;
  }>;
}

TemplateProviderRegistry 会拒绝同类型同 ID 的重复注册，并在运行时明确报告缺失适配器。当前仍有部分调用由各领域服务直接管理，因此接入新 Provider 时必须按下方清单检查完整业务路径。

新增一个 Provider 的完整步骤

以未来的 aliyun_oss 为例，不能只在 schema 中增加字符串。一个完整变更必须同时包含：

1. 在领域包中实现上传、读取、删除、私有签名 URL 和健康检查，而不是在页面里直接调用 SDK。
2. 把 ID 加入配置 schema，并定义与现有 Provider 相同的业务语义。
3. 在服务启动阶段注册 adapter；未注册或健康检查失败时按模块策略 fail closed。
4. 在服务端环境 schema 中增加必填项，生产预检只检查存在性与格式，不输出值。
5. 处理对象 key 规范化、MIME/大小限制、超时、重试和厂商错误映射。
6. 对外 URL 进行 HTTPS 和允许域名校验；私有附件只返回短时签名 URL。
7. 增加 contract、单元测试、集成测试和失败模式测试。
8. 更新本页支持矩阵与模板站 Changelog，明确首次支持版本。

私有文件存储必须保证的语义

• 公共媒体与私有源码发布使用不同 bucket、私有目录或等价访问边界。
• 客户端永远拿不到 Access Key / Secret Key。
• 私有下载 URL 有短 TTL，数据库保存稳定的 artifact key，不保存临时签名 URL。
• 对象存储 URL 必须来自配置的 HTTPS origin；服务器目录必须只读挂载、拒绝路径穿越和符号链接逃逸。
• 健康检查只返回 bucket/region 等非敏感信息，不回显凭据。

支付适配器必须保证的语义

• 站内订单状态是业务真源，厂商回调只是有签名的状态输入。
• 回调验签、金额、币种、订单号和幂等键必须全部核对。
• 前端不能执行任意支付 HTML；支付宝表单需解析并重新创建受限 DOM。
• Mock 支付只允许本地开发，生产启动和预检均应拒绝。

Provider 与模块的关系

模块开启不等于 Provider 已健康。例如开启 assistant 但缺少 AI Key 时，服务必须明确降级到允许的规则模式或拒绝启用；不能等到用户操作时才暴露模糊的 500 错误。

当前 requiredConfig 和 health() 尚未完全聚合到统一模块 manifest；新增 Provider 时需要同时检查领域服务的环境 schema、启动注册和健康接口。