repository-resource-flow-pattern
这是一个面向 Kotlin 多平台项目仓库层的结果封装模式，定义 Resource、LocalResource、NoResponseResource 三种结果封装类型，配合 wrap 侧与 collect 侧的辅助函数，统一处理远端读取、本地读取和无需返回数据的操作，并给出取消异常传播、映射位置、空载荷等常见陷阱的规避方法。
Skill 广场
找到适合任务的 Agent Skill，阅读介绍并复制安装命令。
更新于 11-15 00:13
编程与开发
41,128 个结果
restricted-marker-is-not-an-opt-in
本文介绍 Kotlin/Android 库中两种易混淆的注解标记：@RequiresOptIn（需要显式确认的实验性 API 标记）与 @RestrictTo（库内部使用的 lint 可见标记）。两者虽名字相近，但由完全不同的机制约束：前者由编译器强制要求调用方显式 opt-in，后者编译器并不检查，仅依赖 lint 规则提示。文章指出误判二者会导致两类相反的错误——无效的抑制注解，以及因代码能编译而产生的 API 公开性错觉。文中给出了用 grep 统计现有 @OptIn 注解、用 javap 反编译库类识别标记类型、检查 gradle 中模块级 optIn 配置是否掩盖证据、以及验证错误确认仅产生警告等具体命令和步骤，并建议优先使用函数级而非文件级确认、在调用处留下注释说明决策依据。
retry-needs-backoff-and-cap
该技能针对 Kotlin 重连循环，要求为每次重连加入指数退避、延迟上限、不可重试失败分类和生命周期闸门四类限制，并补充健康信号。资料以代码片段说明重试路径应调用私有启动函数而非公开 connect，避免重试重置计数导致上限失效；退避应在握手成功而非 socket 打开时重置；等待就绪需加超时；空闲时应关闭连接；失败要有可见日志或状态提示。还给出用 grep 查找重试站点与上限的核查方法，以及瞬时、终态、耗尽、恢复四类故障的验证步骤。
room-kmp-setup
room-kmp-setup 是一份面向 Kotlin 多平台（KMP）开发者的配置实践，说明如何在 Android、JVM/桌面和 iOS 三个目标之间共享同一个 Room 数据库。核心做法是把数据库类、实体和 DAO 放在 commonMain，仅通过一个 expect/actual 构建器按平台处理文件路径和 Room.databaseBuilder 的调用方式，并在共享注入点统一设置 BundledSQLiteDriver 与 IO 查询调度器。资料还集中列出常见陷阱：每个声明目标都必须单独配置 KSP 注解处理器，否则链接期才会报缺少生成的实现；迁移、回调和打开策略等 builder 调用写在平台 actual 中时只会对已注册平台生效；expect 签名无法接收 Android Context，只能通过服务定位器获取并因此把编译期问题推迟到运行期；必须导出 schema 目录并提交每个版本文件以保留升级路径；需要实测 bundled SQLite 驱动的原生切片覆盖，避免因缺少某一 CPU 架构导致整个目标不可用；最后应以注入点日志确认实际使用的驱动，而不是只读配置文件。分类为编程与开发。
run-discriminating-experiment-first
这是一个在调试或排查问题时优先执行“区分性实验”的方法指南。当两个几乎相同的事物表现不同时，不要急于根据猜测修改代码，而应先统计两者之间仍然不同的变量数量；如果差异变量多于一个，则必须设计一个交换或交换属性的实验，在运行前明确每个结果能排除哪些候选原因，从而通过一轮实验至少排除一半的可能性。该方法强调避免“边修边猜”、设计可区分的测试、保持实验纯净、保护实验不被清理、在昂贵构建中批量运行多个变体、警惕部分改善被误认为确认、不轻信注释或变更日志，并尽量自己验证而非委托他人。文中还提供了一套在 Kotlin 项目中统计差异、检查实验存活性的具体命令和步骤，适用于调试复杂界面效果、多平台应用问题定位等场景。
runtime-override-not-preference-write
这篇内容来自 kotlin-footguns 技能集合，讲解在 Kotlin 开发中，如何通过组件上的运行时覆盖（runtime override）在某种模式期间临时关闭面向用户的功能，而不是改写用户存储的偏好设置。因为退出路径不保证执行，进程崩溃、任务被杀或异常都可能导致存储的偏好被静默改写。该技能建议增加一个内存中的抑制标志，与启用标志组合使用，并详细说明实现方式、常见陷阱、线程安全、模式计数、日志记录和验证方法。
sampled-supplier-vs-per-handle-reapply
这是一个关于音频播放后端设置同步的Kotlin编程技巧条目，描述了两种后端架构（采样后端与句柄后端）对播放级设置（如音量、速度、淡入淡出因子、滤波器曲线）的不同处理方式。采样后端让每个流消费者共享一个字段，由工厂保证正确性；句柄后端需在每次创建时重新应用设置。条目还列出了跨淡入淡出时遗漏句柄、进程级音量互相覆盖、线程安全等陷阱，并提供了grep验证方法。
search-over-a-paged-list-queries-the-source
这是 Kotlin Paging 开发中的一条技术要点：分页流（PagingData）本质上是集合的一个窗口，对分页流直接使用 filter 只会检索已加载的页面，因此条目能否被搜索到取决于用户已滚动到多远。该内容主张把搜索作为独立数据读取路径，直接向数据存储发起查询，并在界面中以覆盖层形式与分页列表并列展示，同时给出 debounce、flatMapLatest、查询长度门槛、LIKE 通配符转义、结果重新排序、关闭搜索时清空查询等修正与排查要点。
self-hiding-child-cannot-hide-its-slot
该条目来自 maxrave-dev/kotlin-footguns，讨论 Kotlin/Compose 中一个常见的 UI 陷阱：当可选控件因条件不满足而自身不渲染时，包裹它的容器（容器、权重、分隔线）仍会被绘制，留下空白框。条文主张在声明组件的同一文件中导出可用的判定函数（谓词），由调用方据此门控容器；并指出分段组中移除槽位会影响相邻端帽与圆角、无点击槽位需要真实分支而非空 lambda、谓词须在组合期保持轻量纯函数、瞬态不可用应保留占位而永久不可用才移除。文中还给出用 grep 审计判定函数与调用点的验证方法及相应命令。
server-default-overrides-client-intent
这是 Kotlin Footguns 项目中的一条经验记录，记录了 Kotlin 客户端在与中继（relay）共享会话状态时的典型陷阱：中继会为客户端未设置的字段填上自己的默认值，其中运行/暂停标志通常默认为 false，导致每次换曲命令都携带“未运行”，让跟随端加载新曲目后立即停止。记录给出了客户端侧的补偿写法，即将会话此前的播放意图跨换曲保留下来，同时要求发布端在换曲后单独发出一条运行/暂停命令。文中还列出了补偿条件过宽或过窄、携带值更新时机、离开会话时清理、快照需发两条命令、中继可能因条目过期丢弃纠正等注意事项，并提供了 grep 检查方式和需要两个客户端参与的验证场景。
settings-value-round-tripped-through-its-label
这个页面是 maxrave-dev/kotlin-footguns 技能合集中的一个条目，主题是 Kotlin 与 Compose 设置界面里的一类典型缺陷：把存储的值与本地化显示标签互相往返映射。当两个选项在某种语言下翻译相同时，按标签字符串反查就会失配或误匹配，导致设置写入被静默跳过，或写入错误的值。页面解释了该问题模式、解释器静默吞错的危害、改用 id/索引按位置映射的做法，以及如何保证列表只构建一次；同时给出重影默认值、正向查找回退空串等相邻问题，并提供 grep 审计命令和手动验证方法。
small-collection-utilities
这是一组值得放入共享模块的 Kotlin 小工具集合，主要包含四个辅助实现：用于比对两个 id 集合的对称差集、把一个列表映射为“元素到位置”索引的 indexMap、带时间戳文本的容错解析与序列化函数对，以及把外部 http(s) 链接转换为应用内深链接的函数。页面重点并不在实现本身，而在逐一说明每种工具容易误导人的地方：对称差集只回答成员关系，重复元素会被合并、顺序会丢失，元素位置变动也不会报告为变更；indexMap 对重复元素只保留最后位置，导致映射结果数量少于列表长度；容错解析中，比例的数字位数决定单位，切片会去掉分隔符，无法解析的字段会默默回退为 0，整体失败才返回 null；链接转换则应复用现有深链接处理入口，避免另写一套规则。文中还给出用 grep 检查解析入口失败模式、调用方对 null 的处理以及集合工具输入是否唯一的验证方法。
sql-not-in-nullable-trap
该技能条目说明 SQL 中 x NOT IN (子查询) 的一种常见问题：只要子查询结果里出现一个 NULL，外层查询就可能一行都匹配不到，但语句仍正常执行、不报错。条目解释了原因：与 NULL 比较得到 NULL，而不是 false，所以 NOT IN 的结果不会为 TRUE，使条件无法成立。它建议用 NOT EXISTS、给子查询加 IS NOT NULL 条件或使用 LEFT JOIN 来规避，并给出验证办法：统计 NULL 数量、用两种写法对比结果、让 DAO 返回并记录影响行数。
stacked-bars-double-consume-window-insets
该页面讨论 Jetpack Compose 中窗口 Insets（系统栏留白）在堆叠组件间的消费规则：Insets 的消费沿组合树的父子关系传递，不会横向传给兄弟节点。因此，在一个 Column 中堆叠两个能感知 Insets 的顶栏时，每个顶栏都会各自预留一次状态栏空间，导致中间出现一条与状态栏等高的空白带。页面给出了正确做法（容器统一消费一次，或由第一个子项消费）、参数默认值设计建议、验证用 grep 命令，以及横向系统栏 Insets、Scaffold PaddingValues 等易错点。
stateflow-conflation-inverts-state
该技能页面剖析 Kotlin 开发中 MutableStateFlow 因“合并”（conflation）特性导致状态被写反的问题：StateFlow 只保留一个槽位，同一回调内多次写入时，只有最后一次写入会生效，最后一次写入的顺序就成了正确性关键。页面给出具体案例、排查命令与修复写法，强调每个事件只写一次、在末尾统一决定状态值，并提醒辅助函数（如 stopX）可能隐式发布状态、周期性发射器需先取消再重启才能避免泄漏，以及合并行为在测试中难以复现、需通过收集器日志验证。
string-resource-format-limits
这是 Kotlin 多平台（Compose Multiplatform）字符串资源格式限制的实践笔记。它指出，多平台资源查找只识别 %1$s、%1$d 这类纯位置占位符，不支持标志位、宽度、精度和字面百分号的转义；未识别的格式说明符会被原样渲染到界面上，而且不会抛出异常。因此数值的补零、取整、单位换算和百分比拼接都应在 Kotlin 代码中完成，资源只负责拼接。文中还提醒翻译过程容易破坏占位符、硬编码字面量不会被导出翻译、日期库只有英文月份名常量等问题，并给出用 grep 扫描全部语言资源、检查硬编码英文月份和未进资源文件字面量的命令。
structural-defensive-parsing
该技能介绍了一种处理形状不稳定的非官方 API 响应的防御式解析方法。核心思想是让载荷自身声明字段类型：通过链接标记、正则匹配等结构性线索识别每个字段的用途，而不是依赖列的位置。内容涵盖了常见的解析陷阱，如位置猜测导致二次错误猜测、过滤型 map 操作造成静默数据丢失、缺失字段应作为形状而非失败处理、复合字符串解析需要从稳定端（末尾）开始、文本启发式检查需两端防护、双向控制符等不可见字符应写成转义等。同时提供了检测数据丢失、位置读取、左到右时长解析的 grep 验证命令，以及以每行变体为夹具的测试策略。适用于消费非官方或易变 API 的 Kotlin 解析层开发与代码审查。
sync-room-bridge-echo-guard
该技能针对 Kotlin 共享房间组件中本地与远程状态同步的回声问题，提出“一个桥接、两种方向、由角色决定”的模式。用一个标志位（如 applyingRemote）在应用远端更新时抑制本地发布，避免反馈循环，并强调异常安全、幂等启动、身份去重、角色实时读取及每个发布器独立守卫等陷阱。适用于多点同步客户端开发。
ttl-keyed-json-cache-lenient-decode
这是一个面向 Kotlin（Kotlin Multiplatform/Android 常见写法）的带过期时间（TTL）的键值缓存示例，属于“kotlin-footguns”系列，专门演示如何在偏好存储（Preferences）中以单个 JSON 字符串保存整份缓存、如何判断条目是否过期，以及这种写法容易踩的坑。它不是库或服务，而是一段可借鉴的实现与陷阱说明：每个条目记录 url 与 cachedAt，按 TTL 判断是否过期；命中且未过期直接返回，否则远程解析并回写。文中重点指出：ignoreUnknownKeys 只处理字段被删除的情况，新增字段、改名都会导致解码失败，真正兜底的是 runCatching 与 orEmpty；合并回写是无锁的读改写，可能丢条目；没有淘汰机制，键无限增长时不适合；过期依赖系统时钟；解析为空的“未命中”结果不会被缓存；新鲜命中先返回、不采用先陈旧后校验的策略。并给出过期、回退、增长三条验证思路。
two-vendors-one-package-kmp-api-skew
该技能面向 Kotlin Multiplatform（KMP）UI 构建中「同一包名、两个厂商、两种 API 形态」的编译期陷阱：平台厂商产物只覆盖平台目标，多平台移植版覆盖全部目标，二者发布同一包名但版本节奏不同，导致某个符号在一侧是接口成员、在另一侧是顶层扩展，使共享源码中的导入写法只能在一个目标上编译通过。技能说明如何用带注释的通配符导入同时兼容两种形态、如何用版本目录（version catalog）锁定两侧版本并记录对应关系，以及如何用仓库根目录下的命令检查重复坐标、审查共享源码中的未注释通配符、确认各源集使用的厂商，并要求在任一版本升级后对全部目标编译共享源集。
type-safe-nav-graph-organization
这是一个关于在 Jetpack Navigation Compose 中组织类型安全导航图的技能指南。它主张用可序列化对象替代字符串路径作为路由，并按应用功能区域将路由拆分为包，每个路由对象单独一个文件；宿主 NavHost 只声明一次转场动画并注册底部栏标签等入口，其余区域通过 NavGraphBuilder 扩展函数按文件分组调用。指南强调这些扩展函数并非嵌套导航图，因此不提供按区域独立的返回栈或 ViewModel 作用域；跨切面参数（窗口内边距、NavController、底部栏显隐回调）应作为函数参数传递而非放入路由；深色主题应按路由在注册处用包装组件单独施加。文档还列出路由参数保持可序列化原始类型、常量放进路由伴生对象、空路由需注释说明、深链接在导航图外解析等约定，并给出一组 find、grep、comm 校验命令，用于检查路由可序列化、声明路由均已注册、扩展函数与宿主数量、是否存在私有转场覆盖。
unbounded-for-shares-capped-for-lists
该技能来自 maxrave-dev/kotlin-footguns 项目，讨论 Kotlin/JPA 查询中一个统计陷阱：同一个 GROUP BY 查询既用于排行榜展示，又用于计算占比或多样性，但加了 LIMIT 的查询会截断尾部数据，使分母和熵的归一化因子同时变小，从而导致聚集度（如 top5 占比）和多样性指标被系统性高估，而不是仅仅给出近似值。资料建议把两种用途拆成两个查询：列表展示用带 LIMIT 的查询，任何需要除以总数的统计用不带上限的查询，并指出被截断的结果本身不会提示截断、无上限查询的 ORDER BY 是实际依赖而非装饰、只有当分组键的基数有限（如用户交互过的实体数）时无上限才安全。还给出用 grep 查找可疑查询和消费者、用 Python 脚本复现偏差的验证方法。
unknown-not-a-valid-score
这是一篇关于 Kotlin 解析器回退值设计的技术文档，核心主张是：解析失败时的回退值不应落在合法成功域内，否则调用方无法区分“真实值”与“解析失败”。文章讨论了三种诚实的回退方式（合法域之外的哨兵值、用类型表达缺失、不做回退直接失败），并给出哨兵值被多个环节独立读取、合法范围内回退、布尔折叠未知、比较前未归一化、UI 颜色占位、伪造非空占位字段、本地失败复用远端错误码等陷阱，最后提供 grep 命令用于审计代码库。
upstream-lib-bug-workaround-template
这是一个用于编写“上游库缺陷临时规避方案”的模板与写作指南，面向无法直接修复的上游库缺陷。它要求在工作代码旁的注释中写清五个部分：已追踪到的机制及追踪停止的位置、明确列出的取舍、在规避本身失效时能降级而非静默失败的逃生通道、可供外部核查的移除条件，以及为什么本项目的用法会触发该缺陷。文中以跨平台音频输出初始化失败导致监听器泄漏并引发原生崩溃为例，演示如何定位机制、缩小规避范围、区分“不支持”与“失败”，并强调不能用症状反推原因、应订阅库日志、在依赖升级时复查移除条件。