remote-api-footguns 是 kotlin-footguns 技能集合中的远程 API 专题部分，内容来自一个生产环境的 Kotlin 与 Compose Multiplatform 应用，共整理 17 个陷阱，每个陷阱对应 references/ 目录下的一个短文件。每个文件都给出可用的实现模式、具体的失败方式与成因（Traps），以及一节针对使用者自己的代码树运行命令的验证说明（Verifying it）。
使用方式：把即将编写的代码或正在排查的症状与索引条目对照，每个条目都标明主题和触发应查阅该条目的症状；在提出代码或修复方案前，先用 Read 工具阅读所有可能适用的文件，每个文件均不超过 150 行。验证命令若提到源项目的路径，需替换为用户代码树中的对应路径。文件内部出现的反引号陷阱名若不在本索引中，则属于相邻领域的技能，可通过 glob ../*/references/<name>.md 打开。
客户端、解析与响应处理：ktor-kmp-client-architecture 介绍通过一个 expect/actual 返回引擎、各集成自行构建客户端的多平台 HTTP 栈，区分用于 API 调用的插桩客户端与用于批量下载的裸客户端，按格式注册内容协商，设置变更时重建客户端而非修改客户端；curl-logger-ktor-plugin 将每个出站请求记录为可直接粘贴的 curl 命令，采用 POSIX 单引号转义，整条命令一次日志调用输出，带脱敏列表，且读取 body 不消耗一次性通道；parallel-chunked-download 把一个文件拆成 N 个并行字节范围请求，各块写入独立临时文件后按序合并，进度通过基于通道的 flow 上报，并说明范围请求何时安全、块大小如何选择、失败为何重试单个块；structural-defensive-parsing 处理形状漂移的响应，按载荷自身声明的标记而非位置分类字段，把过滤映射视为数据丢失并统计丢弃数量，拒绝用占位值替代解析失败，从稳定末端解析复合字符串；response-to-domain-flow 描述远程响应经过的五个阶段（各集成服务模块中的传输模型、纯解析层、领域模型、结果封装、收集），每个集成为独立模块，并给出防止传输类型进入界面的放置规则；api-ok-but-ignored 指出远程写入可能返回成功却丢弃了发送内容，只在随成功返回的次要字段中说明，应将"接受但丢弃"建模为独立结果，在每次写入时读取该字段并大声记录丢弃；unknown-not-a-valid-score 要求解析失败回退值必须是合法领域之外的哨兵或体现在类型中，不能与成功路径产生相同值；enum-normalize-over-legacy-data 读取远程源自行声明的类型标记，每次比较前先归一化，null 表示"源未声明"而非默认值，暴露 is-known 谓词，并用写穿而非迁移修正旧行。
认证、重试与账户状态：oauth-callback-not-through-nav 让返回的认证回调令牌直接进入会话状态，登录界面通过观察已存会话自行关闭，避免经导航传递导致重复登录界面；retry-needs-backoff-and-cap 要求每个重连循环都有指数退避、上限、拒绝重试的失败类别和生命周期门控，并为该功能提供健康信号；login-state-fans-out-to-settings 要求在登出关键点重置所有依赖登录状态的设置；nested-flag-settings-auto-disable 说明受父条件门控的子开关应以父当前值为自动禁用依据，关闭时置灰而非隐藏，并在消费端再次门控。
实时会话与线协议：monotonic-clock-offset-sync 通过 ping/pong 往返估计对端时钟偏移，扣除对端处理时间再取半，按最佳往返加权，坚持使用单调时间源，估计不可用时回退未校正值；protobuf-without-codegen-kmp 在共享 Kotlin 中用字段号注解普通 data class 来使用 protobuf，涵盖使字节与生成编码器一致的编码器设置、字节数组字段所需的 equals 覆写及一致性测试；borrowed-wire-protocol-discipline 给出实现他人定义协议的规则：不重命名、不重排，schema 未给出的常量从对端实现读取而非猜测，未知消息类型解码为 null 而非抛出，协商能力只收窄不放宽；websocket-session-handshake-lifecycle 说明 WebSocket 会话建立与拆除的顺序，读取器先于首条消息启动，握手用带超时的 deferred 敲定，关闭帧在不可取消上下文中发送，事件缓冲区应挂起而非丢弃；publish-a-snapshot-on-taking-the-role 指出共享会话中的发布者均为边沿触发，中途接管发布角色的人不会发出任何内容，因此应在成为数据源时以及新成员加入时发布完整快照。
适用场景：正在为 Kotlin Multiplatform 模块搭建网络层，排查仅在部分请求中被忽略的代理设置，下载大文件缓慢或日志泛滥，希望重放失败请求，大型下载慢于链路能力或中途归零，解析器在不同区域表现不一致，界面导入响应类，登录后仍停留在登录界面，后台连接耗电或凭据错误导致无限重连，开关卡住无法关闭，设备间对时漂移，与不受控实现互操作，WebSocket 连接后不可用或客户端失步等。
限制：资料仅以索引形式概括各文件主题，未提供各文件的完整代码、具体 API 名称、版本要求、依赖坐标或安装命令；验证命令的具体内容与源项目路径未给出，需使用者自行替换路径；未说明支持的目标平台清单、性能数据或兼容性保证。