putio-sdk-dev

put.io SDK 开发

遵循目标仓库自身的指南后，再应用 put.io SDK 约定。

共享默认原则

• 将每个 SDK 视为公共软件包，而非内部兼容层。
• 将 TypeScript 视为规范的完整 put.io API 客户端，而不只是功能最丰富的参考实现。
• 确保所有公共接口都以领域为先、类型严格，并符合宿主语言的习惯。
• 同步更新请求、响应和类型化错误契约。
• 通过确定性测试验证行为；当真实 API 行为很重要时，再进行安全的线上测试。
• 只有在产品使用情况有充分理由时，Swift 和 Kotlin 的范围才应窄于 TypeScript。

来源顺序

当来源内容不一致时，优先采用本地后端行为和测试、当前第一方应用的使用情况、维护中的 SDK、已归档的客户端，最后才是已发布的 API 文档。

先从目标仓库中已有的来源开始。只有在获得授权且可用时，才补充后端或第一方使用方的证据。

只有在真实应用使用情况和已验证的后端行为足以证明合理时，才扩展 SDK 接口。

开始

只阅读必需内容：

• 使用 git ls-files '*AGENTS.md' '*SKILL.md' 查找嵌套指南
• 从 README.md、AGENTS.md 或 docs/* 中查找规范的验证和线上测试命令
• 阅读 SDK 愿景，了解范围规则、共享工程原则和验证策略；产品方向位于 put.io Notion 工作区的 Frontend 中心页（页面：Products）
• 阅读 模式，了解类型化边界、错误映射、分页和线上测试分层
• 阅读 语言说明，了解 TypeScript、Swift 或 Kotlin 的特定指导
• 在发布、签名、上线或构建可分发二进制文件时，阅读 发布安全

目标仓库指南、匹配的仓库本地技能、仓库的规范验证命令，以及其交付或供应链政策，优先于此共享技能。

工作流

1. 检查目标命名空间以及共享传输层或客户端运行时。
2. 在扩展或更改契约前，检查后端行为、后端测试和当前应用的使用情况。
3. 同步更新类型化请求输入、响应解析和操作专属错误映射。
4. 为请求构造、解析、错误和公共客户端契约添加或更新确定性测试覆盖。
5. 当生产环境行为很重要且接口可逆时，添加或更新安全的线上验证。
6. 如果仓库提供多种接口风格，确保多个公共客户端保持一致。
7. 运行所有者文档中针对受影响契约及其依赖项规定的检查；在相关情况下，还应验证已安装软件包和下游使用方。若有强制要求、共享输入发生变化或针对性测试覆盖不确定，则运行完整的规范检查。
8. 当公共接口发生变化时，更新面向软件包用户的文档和发布说明。

端点变更

对于新增或变更的端点，先查找已跟踪的源代码、测试、固定数据和使用方路径。只搜索实际存在的路径：

git ls-files -z -- \
  ':(glob)**/src/**' \
  ':(glob)**/test/**' \
  ':(glob)**/tests/**' \
  ':(glob)**/Tests/**' \
  ':(glob)**/Sources/**' \
  ':(glob)**/docs/**' \
  ':(glob)**/fixtures/**' \
  ':(glob)**/Package.swift' \
  ':(glob)**/build.gradle' \
  ':(glob)**/package.json' |
  xargs -0 rg -n "route_name|endpoint_path|field_name" -- || true

只有在后端、固定数据或第一方使用方代码库可用且获得授权时，才从这些代码库中重复此搜索。

然后按以下顺序更新 SDK：

1. 请求输入类型或查询模型
2. 响应解析器或原生解码模型
3. 操作专属错误映射
4. 公共客户端方法或命名空间导出
5. 请求、响应和错误行为的单元测试
6. 当无法在本地验证端点行为时，添加安全的线上测试
7. 当公共接口发生变化时，更新 README、API 文档或发布说明

验证

使用所属仓库文档中规定的命令。不要根据这项共享技能推断 Vite+、Gradle 或 Make 入口。

SDK 仓库应同时提供：

• 默认的确定性单元测试路径，适用于 CI 和本地迭代
• 单独记录在文档中的实时测试路径，用于验证真实 API

如果缺少其中一个层级，应将其视为仓库缺陷并记录或修复，而不是默默接受较弱的验证方案。

进行运行时验证时，优先使用仓库文档中规定的实时测试入口，并遵循该仓库测试文档中的共享账户安全规则。

边界

• 应通过当前文档、源代码、测试夹具或实时探测来验证后端契约，而不能只依赖旧版 SDK。
• 只有在与此次更改相关的单元测试、测试夹具和实时测试层均已执行时，才能声称完成了全面验证。
• 针对共享账户的实时测试覆盖应保持非破坏性。
• 合并到 main 即表示交付，包括由此启动的发布 CI。手动发布或编写发布内容、更改覆盖率阈值，以及执行无法撤销的实时写入操作前，应先征得许可。
• 除非有文档说明的理由，否则应保留命名一致性、对等性和类型安全。
• 仓库专属的实现指南应保留在该仓库的 AGENTS.md 或 docs/* 中。
• 通用 SDK 工作、终端用户应用代码和 CLI 使用者操作不属于此技能的范围。