适配器架构

所有适配器均实现 API 版本 1，并公开稳定 ID 和显示名称。输入与输出都是可序列化的领域值。核心包不得导入 Hexo、COS、腾讯云、GitHub 或 Traefik 的具体实现。

边界

适配器	负责	不得负责
生成器	检测、内容模型、读写、永久链接、构建	远程发布
仓库	状态、检查点、推送	草稿持久化
资源服务商	文章资源的上传、列举和删除策略	生成网站的发布
发布器	应用清单差异和精确回滚	内容编辑
缓存服务商	失效请求和服务商任务结果	公网验证

集成前的一致性验证

适配器应先针对可复用的假上下文开发，再接触真实凭据。必备特性包括：确定性序列化、幂等重试、边界约束、等待失败结果、稳定诊断和日志脱敏。

服务商包向内依赖核心契约。Studio 适配器注册表由管理员控制；v0.1 不会在服务端进程内加载任意第三方 JavaScript。

生成器指南

生成器适配器应当：

1. 检测过程不写入文件；
2. 描述内容集合和输出路径；
3. 保留不支持的文档结构；
4. 计算稳定的公开 URL；
5. 使用参数数组、超时和允许的环境变量调用命令；
6. 从生产构建返回完整的内容哈希清单。

服务商指南

存储和发布适配器应明确所有权。文章媒体宜使用不可变键。发布器必须区分资源与页面，保留最后一份已验证清单，并恢复与此前完全一致的字节。缓存失效后还要独立验证公网内容。

如果发布器会在第一次修改目标前持久化回滚状态，就应实现 recoverInterrupted。重启后，只有在缺少持久状态足以证明目标从未被修改时，才能报告 not-started；否则必须执行并报告精确回滚。手动 rollback 仍须严格处理，不能把状态缺失或损坏误报为成功。

每次文档构建都会从当前 TypeScript 接口提取适配器 API 参考。