itsmeadarsh2008/backlit-kbd 源码：https://github.com/itsmeadarsh2008/backlit-kbd # backlit-kbd CI（https://github.com/itsmeadarsh2008/backlit-kbd/actions/workflows/ci.yml） 发布（https://github.com/itsmeadarsh2008/backlit-kbd/actions/workflows/publish.yml） PyPI 版本（https://pypi.org/project/backlit-kbd/） Python（https://pypi.org/project/backlit-kbd/） 许可证 下载量（https://pypi.org/project/backlit-kbd/） 请我喝咖啡（https://buymeacoffee.com/itsmeadarsh） 赞助（https://github.com/sponsors/itsmeadarsh2008） 超友好的 Python 包，用来控制键盘背光亮度。支持： - 真实 Linux 键盘背光设备（自动从 sysfs 发现） - 模拟后端，无需触碰笔记本硬件即可安全测试 ## 这意味着什么 - 使用 --mock 时，命令只在内存中运行（学习用，绝对安全）。 - 不使用 --mock 时，自动尝试操作真实硬件。 - 通常无需手动指定 --device-path。 ## 安装 步骤 1：从 PyPI 安装 bash pip install backlit-kbd 步骤 2（可选）：本地可编辑安装，方便开发 bash pip install -e . 步骤 3（可选）：安装开发依赖 bash pip install -e .[dev] ## 快速上手（Python） 步骤 1：导入 python from backlit_kbd import NotificationBlinker, create_controller 步骤 2：创建安全控制器（失败自动回退到模拟） python controller = create_controller(fallback_to_mock=True) 步骤 3：亮度开到 60% python controller.turn_on(60.0) 步骤 4：通知闪烁 python controller.blink(count=3, on_ms=120, off_ms=120, level_percent=100.0) 步骤 5：使用异步通知管理器 python blinker = NotificationBlinker(controller) blinker.start("chat-message", count=5, on_ms=80, off_ms=120) ## CLI 指南（新手友好） ### 1）查看当前状态 使用模拟后端： bash backlit-kbd --mock info 使用真实硬件： bash backlit-kbd info ### 2）按原始等级设置亮度 模拟： bash backlit-kbd --mock set 2 真实硬件： bash backlit-kbd set 2 ### 3）按百分比设置亮度 模拟： bash backlit-kbd --mock percent 75 真实硬件： bash backlit-kbd percent 75 ### 4）增加与减少 默认步长（1）增加： bash backlit-kbd --mock inc 自定义步长增加： bash backlit-kbd --mock inc 2 自定义步长减少： bash backlit-kbd --mock dec 2 真实硬件同理： bash backlit-kbd inc backlit-kbd inc 2 backlit-kbd dec 2 ### 5）开关背光 模拟： bash backlit-kbd --mock on --percent 40 backlit-kbd --mock off 真实硬件： bash backlit-kbd on --percent 40 backlit-kbd off ### 6）同步闪烁模式 模拟： bash backlit-kbd --mock blink --count 4 --on-ms 100 --off-ms 100 --level-percent 100 真实硬件： bash backlit-kbd blink --count 4 --on-ms 100 --off-ms 100 --level-percent 100 ### 7）通知闪烁（异步风格） 模拟： bash backlit-kbd --mock notify --name chat --count 5 --on-ms 80 --off-ms 120 --level-percent 100 真实硬件： bash backlit-kbd notify --name chat --count 5 --on-ms 80 --off-ms 120 --level-percent 100 ## 完整 CLI 命令 全局选项： - --mock 使用内存后端（安全，不写硬件） - --device-path PATH 可选高级用法，手动指定 sysfs 设备 命令： - info - set <level> - percent <0–100> - inc [step] - dec [step] - on [--percent N] - off - blink [--count N --on-ms N --off-ms N --level-percent N] - notify [--name NAME --count N --on-ms N --off-ms N --level-percent N] ## 示例文件夹 脚本： - examples/blink_notification.py - examples/brightness_wave.py - examples/disco_light.py 运行： bash python examples/blink_notification.py bash python examples/brightness_wave.py bash python examples/disco_light.py ## 测试 运行测试： bash python -m pytest 若使用项目虚拟环境： bash .venv/bin/pytest ## 常见问题 1. 真实硬件模式下出现 Permission denied： - 可能需要合适权限或 udev 规则才能写入 sysfs。 2. 真实硬件模式下找不到设备： - 学习/测试请用 --mock。 - 或在代码里用 create_controller(fallback_to_mock=True)。 3. 想永远使用安全练习模式： - CLI 加 --mock，或代码里用 force_mock=True / fallback_to_mock=True。 ## 发布与部署 本仓库已配置 GitHub Actions 工作流： - CI 在 push 和 PR 时自动跑测试 - Publish 构建并发布到 PyPI - 使用 astral-sh/setup-uv - 采用 PyPI 可信发布（OIDC） 发布新版本步骤： 1. 修改 pyproject.toml 中的版本号 2. 创建并推送形如 v0.1.1 的标签 3. 或直接发布 GitHub Release ## 支持 - 请我喝咖啡：https://buymeacoffee.com/itsmeadarsh - GitHub 赞助（个人/公司）：https://github.com/sponsors/itsmeadarsh2008 ## 贡献 - 从 examples/ 开始 - 查看 tests/ 里的测试 - 欢迎提 issue 和 PR ## 许可证 MIT 许可证。作者 Adarsh Gourab Mahalik。