ZMK 贡献者同步会议纪要解析：从 Wired Split、Studio 到组合键行为重构的社区协作实录

固件嵌入式智能硬件蓝牙【免费下载链接】zmkZMK Firmware Repository项目地址https://gitcode.com/gh_mirrors/zm/zmk点击查看免费下载本文基于 ZMK 项目 2025 年 2 月 26 日贡献者同步会议Contributor Sync的公开纪要docs/blog/2025-03-20-contributor-sync-1.md展开。ZMK 是开源的无固件键盘固件项目README.md本次同步会议围绕指针设备Pointer工作、Wired Split 有线分体、组合键Combos行为重构、ZMK-CLI 迁移、zmk-locales 与模块生态建设等主线议题展开。读者通过本文可以理解 ZMK 社区当前的技术演进路线、核心 PR 与底层实现机制以及项目维护者在大版本发布、模块管理、文档体系建设上的真实决策逻辑。会议背景与透明化原则ZMK 项目定期举行贡献者同步会议Contributor Sync其核心目的在于同步各自工作进展、讨论阻塞项blockers以及大方向big picture工作。本次会议于 2025 年 2 月 26 日举行与会贡献者包括petejohansonPetecaksoylarCemnmunnichNick此外joelspadin在会后对会议纪要进行了补充评论相关笔记已据此调整。会议明确了两条基本原则会议本身是私密的不对外公开讨论过程会议纪要在 ZMK 官网页面上公开发布以体现项目透明度transparency。这种“私密讨论、公开纪要”的模式是 ZMK 社区协作的重要特色开发者可以在不受外界噪音干扰的环境中深入讨论技术方案同时社区成员能够及时了解项目走向与决策依据。Pete 的工作总结指针、Wired Split 与 v0.2 发布指针Pointer工作与 v0.2 发布Pete 将于 2025-03-03 开始新工作投入 ZMK 的时间会减少但自由度更高。会议时他手头有两份主要的 ZMK 合同任务contracts需要完成指针Pointer工作基本就绪只需PR 2721作为修复被测试验证后即可推进 ZMKv0.2 版本发布。纪要在发布时注明“这已经发生了”This has already happened即 v0.2 已随指针工作落地。Wired Split 有线分体工作被拆分为多个独立部分推进详见下文。从当前仓库的发布变更记录与源码目录可以印证指针与输入处理相关工作的落地app/src/pointing/下包含input_listener.c、input_processor_behaviors.c、input_processor_code_mapper.c、input_processor_scaler.c、input_processor_temp_layer.c、input_processor_transform.c等实现对应的设备树绑定位于 app/dts/bindings/input_processors/共 9 个 yaml 文件说明 ZMK 已将输入处理Input Processors抽象为可配置的独立子系统。Wired Split 的三步推进路线Wired Split 工作被明确拆分为三个阶段UART 全双工PR 2766现有实现非常扎实只差最后的打磨final touchups。会议决定v0.2 发布之后再合并该 PR纪要发布时已合并。单线半双工Half-duplex with a single wire作为独立 PR 推进UART 全双工合并后即可着手开发会议认为现有框架已经为半双工做好了铺垫。运行时动态切换有线/无线分体利用GPIO 作为有线连接的 sense 引脚sense pin实现在有线和无线传输之间的运行时动态切换。从当前仓库源码可以看到 Wired Split 已经完整落地源码位于 app/src/split/wired/central.c、peripheral.c、wired.c、wired.h传输协议在 wired.h 中定义消息使用魔数前缀ZmKwZMK_SPLIT_WIRED_ENVELOPE_MAGIC_PREFIX消息信封envelope由msg_prefix魔数 payload 大小和msg_postfixCRC 校验包裹载荷分为中央侧命令command_payload与外设侧事件event_payload两种传输模式在 Kconfig 中可选Async (DMA) 模式、Interrupt 模式和 Polling 模式三种并针对 nRF52 在异步/DMA 模式下的 RX 缺陷Zephyr 新版中已修复作了depends on限制半双工相关配置ZMK_SPLIT_WIRED_HALF_DUPLEX_RX_TIMEOUT、ZMK_SPLIT_WIRED_HALF_DUPLEX_RX_COMPLETE_TIMEOUT以及 UART 模式选择、命令/事件缓冲条目数ZMK_SPLIT_WIRED_CMD_BUFFER_ITEMS、ZMK_SPLIT_WIRED_EVENT_BUFFER_ITEMS均已在 Kconfig 中定义。设备树绑定 zmk,wired-split.yaml 中同样可以看到会议所述方向的落地痕迹该绑定定义了compatible: zmk,wired-split并提供half-duplex属性注释为 “Experimental: Enable half-duplex protocol mode”即半双工协议模式实验性dir-gpios属性方向控制 GPIO与半双工单线通信时的收发方向切换直接相关。这正好印证了会议中“单线半双工 GPIO 方向控制”的技术路线已经进入实现阶段。版本化、文档与 Studio 的后续规划合同任务完成后Pete 计划重新审视版本化versioning改进文档、完善默认值、优化工作流程等继续推进 Studio 工作节奏会放缓但方向明确希望社区在UI/UX方面提供帮助尤其是**编辑后 keymap 保存的清晰度clarity**问题下一步想增加**运行时属性修改runtime property modification**能力例如在 Studio 中直接修改 hold-tap 的 flavor。当前仓库中 Studio 实现位于 app/src/studio/core.c、keymap_subsystem.c、gatt_rpc_transport.c、uart_rpc_transport.c等相关文档见 docs/docs/config/studio.mdhold-tap 的可配置属性tapping-term-ms、flavor等定义于 app/dts/bindings/behaviors/zmk,behavior-hold-tap.yaml这与“运行时修改 hold-tap flavor”的规划目标一一对应。调研 zmk-cliPete 承认自己对 zmk-cli 调研不足计划获取完整概览。Nick 的工作总结组合键行为重构与锁定 PR组合键Combo行为内触发与 behavior_state_changed 事件Nick 正在推进让组合键可以在行为behavior内部触发的 PR例如实现仅点击不触发组合的 tap-only combos。该工作依赖引入behavior_state_changed事件而其前置工作参见 PR 573、532包括删除ZMK_BEHAVIOR_TRANSPARENT宏对传感器sensors/编码器encoders进行重构与调研因为它们目前依赖ZMK_BEHAVIOR_TRANSPARENT。从当前仓库代码可以清晰看到ZMK_BEHAVIOR_TRANSPARENT的现有使用位置定义于 app/include/zmk/behavior.h#define ZMK_BEHAVIOR_TRANSPARENT 1被 app/src/behaviors/behavior_transparent.c 中zmk_behavior_transparent的按下/释放回调返回on_keymap_binding_pressed/on_keymap_binding_released均返回ZMK_BEHAVIOR_TRANSPARENT在 app/src/behaviors/behavior_sensor_rotate_common.c 的传感器旋转公共逻辑中被引用两次约第 70 行与第 88 行用于将按键事件“透传”给下层绑定。这正是会议中所说“传感器/编码器依赖 ZMK_BEHAVIOR_TRANSPARENT、删除该宏需要先重构”的源码级证据。当前仓库中尚不存在behavior_state_changed事件实现仅出现在该会议纪要文档中说明该重构仍处于规划/推进状态。锁定LockingPR 与 RP2040-Zero 板级定义锁定 PR需要评审PR 2811同样待评审RP2040-Zero板级定义已与上游 Zephyr 保持一致作为临时板级定义temporary board definition使用直到 ZMK 升级到 Zephyr 4.1该板卡在 Zephyr 4.1 中被正式引入。参数化 mod-morph 与 tap-dance以及 hold-tap 兼容性演进Nick 正在推进参数化 mod-morph 和 tap-dance并提出了关键问题是否将 hold-tap 迁移到同一套参数化系统会议讨论后的计划是新增第二个 hold-tapcompatible并逐步迁移到新系统以避免破坏现有用户 keymap 的兼容性。这是一个典型的“向后兼容优先”的演进策略通过引入新的 compatible 标识新旧两种 hold-tap 可以并存旧 keymap 无需修改即可继续工作。文档体系优化Nick 还计划对**配置索引页Config index page**和“Customising ZMK”文档进行整体改造使其更醒目、更容易理解。Cem 的工作总结行为文档与示例优化Cem 的总结聚焦文档质量Keymap recipeskeymap 配方被暂时搁置优先在行为behavior页面本身提供更好的示例例如在 hold-tap 页面下给出**timeless homerow mods永恒主行修饰键**作为示例hold-tap 页面需要大改纪要发布时已完成新行为new behavior指南需要重写并应面向模块modules开发者撰写PR 2758需要评审并合并纪要发布时已完成。当前仓库的 hold-tap 文档位于 docs/docs/config/behaviors.md 及 docs/docs/keymaps/behaviors/ 目录下行为定义的设备树绑定在 app/dts/bindings/behaviors/共 33 个 yaml新行为指南参考 docs/docs/development/new-behavior.mdx均可作为理解该议题的入口。其他讨论ZMK-CLI、zmk-locales 与模块生态ZMK-CLI是时候切换了与会者一致认为是时候“撕掉创可贴”rip the bandaid off从旧的 setup 脚本切换到ZMK-CLICLI 存在一些需要改进的缺陷例如模块modules处理方面但已经比现有脚本好得多新的 shield 指南应调整以利用 ZMK-CLI 的模板templates能力Joel 请求社区针对待改进点开 issue。当前仓库中 CLI 相关脚本可见于 app/scripts/west_commands/、requirements.txt、west-commands.yml模块目录在 app/keymap-module/。zmk-locales组织归属与运行时切换zmk-locales 应迁移到 zmkfirmware 组织下zmk-locales-generator也应一并迁移并考虑通过 GitHub Action 自动向 zmk-locales 提交 PR先迁移再调整;在 keycode 列表页中带 locale 选择器是理想方案但实现复杂暂时在文档中直接引用头文件运行时 locale 切换是更理想的目标但工作量很大zmk-locales 可视为半长期的临时方案bandaid直到运行时切换实现。Modules 模块生态平衡与治理模块生态讨论是本次会议的重要议题需要在过度增加贡献者负担与**过度碎片化overfragmentation**之间找到平衡**ZMK module collection模块集合仓库**被认为是前进方向主要关注点包括优雅处理破坏性变更告知用户“新版本不可用是哪个模块导致的”为模块编写测试键盘能构建不等于其他东西都能工作需要自动化测试可维护性希望社区志愿者更容易地审查模块比审查 PR 简单得多、引入自动化测试、为未验证模块增加“experimental” 实验性分组标签尽管有顾虑模块集合的优势明显值得投入更多时间用户非常容易添加模块尤其是依赖其他模块的模块为模块所有者提供自动化测试与通知更好的可发现性discoverability集合与 ZMK 本体的版本对齐versioning parity便于升级未来很可能引入“RC” 发布给模块所有者留出时间在正式发布前修复各自模块的问题初期只接受键盘和驱动drivers模块因为它们更容易验证等工具与体系成熟后再扩展。其他备忘事项会议纪要的结尾部分记录了若干零散但值得关注的计划记录 BLE 测试documenting BLE tests将很有价值未来某个时间点需要新的显示display与灯光lighting系统本次会议未讨论 Zephyr 升级问题建议优先评审新贡献者的 PR以激励新参与者希望未来再举办一次SOTFState of the Firmware完整的提交总览commit overview目前不可行但聚焦主要问题的形式可行。当前仓库中 BLE 测试已有大量沉淀见 app/tests/ble/包含central/、profiles/、security/、split/等子目录测试框架与运行方式可参考 app/run-ble-test.sh 与 app/run-test.sh。总结一次典型的开源固件社区协作样本这份会议纪要为观察 ZMK 这类开源硬件固件项目的协作模式提供了难得的一手资料工程决策公开透明从 v0.2 的发布节奏先发版、再合并 Wired Split 全双工 PR到 hold-tap 双 compatible 的兼容性策略每个决策都附带清晰的权衡理由版本节奏与契约工作驱动指针与有线分体工作由外部契约contracts驱动反映了开源项目常见的“资金注入关键特性”模式生态治理是长期命题模块集合、RC 发布、实验性分组标签等设想勾勒出一个面向生态可维护性的治理蓝图源码印证与落地会议纪要中的 Wired Split 半双工half-duplex、dir-gpios、三种 UART 模式、ZMK_BEHAVIOR_TRANSPARENT的分布与重构难点都可以在 app/src/split/wired/、zmk,wired-split.yaml、behavior.h 与 behavior_transparent.c 等文件中找到对应证据体现出“纪要-计划-实现”之间的清晰链路。对于希望跟进 ZMK 开发动向、理解其模块与生态演进方向的开发者而言这份纪要连同仓库源码是理解该项目技术路线图的宝贵入口。赞分享固件嵌入式智能硬件蓝牙【免费下载链接】zmkZMK Firmware Repository项目地址https://gitcode.com/gh_mirrors/zm/zmk点击查看免费下载相关推荐wiliwili社区贡献者大会记录会议纪要wiliwili社区贡献者大会记录会议纪要 会议概述 wiliwili作为专为手柄控制设计的第三方跨平台B站客户端已实现多平台运行支持包括PC全平台、PS音视频桌面应用helm-diff社区活动线上meetup与贡献者会议纪要helm diff社区活动线上meetup与贡献者会议纪要 社区贡献指南与开发规范 helm diff作为Helm生态中重要的插件项目始终欢迎社区贡献者参与CLI云原生DevOps2024-06-15 贡献者会议纪要2024 06 15 贡献者会议纪要 决策事项 x 采用方案B实现泛型数组解析 1234 行动项 username: 7月1日前提交方案B的实现PR use开发工具代码生成文档上一篇Gorilla内存管理机制解析Agent持久化状态跟踪的实现方案下一篇SmartJavaAIJava开发者的终极AI集成解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考