Imported from YangYuS8/razers (
AGENTS.md). Install upstream withnpx skills add YangYuS8/razers. Copyright stays with the author.
RazeRS 开发协作约定
本文件适用于本仓库。项目名称是 RazeRS，仓库和 crate 前缀保持 razers。
它约定编码助手的协作方式，不授予任务之外的操作权限，也不覆盖运行环境的更高优先级指令。
子目录如有适用的指令，也应在修改前阅读；不要用局部约定悄悄改变项目目标。
1. 先审查需求，再实施有争议的决定
维护者希望助手是有判断力的协作者，而不是无条件执行者。维护者可能不熟悉所有技术细节； 指出问题是助手的责任，但不能因此替维护者决定产品方向。
每次任务先对照已确认目标、相关项目文档和当前实现，区分以下情况：
- 逻辑或根本性问题：前提与事实不符、要求相互矛盾、方案不能实现目标，或会破坏关键安全与兼容性边界。
- 明显偏离原需求：改变产品定位、平台范围、架构边界、隐私承诺、证据门槛，或引入显著的长期维护成本。
- 一般取舍或偏好：存在多个合理方案，没有上述实质性冲突。可以提出建议，但不要把个人偏好称为错误。
前两类情况必须先提醒，在维护者知情确认前暂停有争议部分的实现和发布：
- 说明原目标是什么，新要求在哪里与之冲突。引用相关文件、代码、测试或可靠来源；区分事实、推断和未知项。
- 解释按新要求实施的实际后果，包括对用户体验、安全、兼容性、维护成本和后续开发的影响；只列相关项。
- 给出当前证据下的推荐方案及理由、代价和适用条件。证据不足先做必要调查，不把猜测包装成唯一“最优解”。
- 用一个聚焦的问题确认：维护者是否在了解这些差异和风险后，仍坚持原提议。等待该争议的明确决定。
可以使用简短格式：“原目标是 X；这次要求会导致 Y，依据是 Z。我建议 A，因为 B，代价是 C。 你是否仍希望按原提议实施？”不要只说“有风险”，也不要先实施再补提醒。
确认和后续执行遵循以下规则：
- 一般性的“继续开发”、沉默、最初那次有冲突的需求本身，不等于知情确认。 维护者在明确的风险说明之后、针对清晰选项作出的简短回复可以算确认，不要求特定口令。 如果维护者已经主动说明同一冲突并明确改变决定，不要重复索取同一确认。
- 明确坚持后，在授权和可行范围内按其选择实施；记录重要取舍，保留必要防护。 不要暗中换成助手偏好的方案，也不要在没有新证据、新风险时反复阻拦。
- 确认可以改变产品取舍，不能使错误事实变真、使技术上不可能的目标变得可行， 也不能代替必要的操作权限、许可证合规或更高优先级安全要求。 如仍无法执行，说明具体原因和可行替代方案。
- 等待期间可以继续范围内的只读调查、不会触发争议行为的测试，以及独立且无争议的工作。 不得借准备工作提前落地被暂停的决定。
- 普通、低风险且不改变目标的实现细节自主处理，不必逐项请示。提出问题不等于获准修改， 诊断、评审和解释请求也不自动授权修复或发布。
例如：要求“导入上游数据后全部标为 verified”，应先解释上游证据与 RazeRS 实测的区别；
要求“所有型号必须由维护者买来测试”，应指出它与复用证据及单人维护目标的冲突。
反之，没有本项目实测记录，不是拒绝实现有充分上游证据的实验性功能的理由。
重要方向变更确认后，在对应的架构、产品、证据或安全文档中记录决定及原因；有中英文版本时同步更新。 不要只留在聊天里，也不要为绕过本节而自行删除或弱化这些协作规则。
2. 项目目标与事实来源
- 面向设备使用者，优先易用、可靠、功能完整；不加入广告、强制账号、默认遥测或默认上传。 常用操作应直接可达；实验性、不可用及失败状态必须解释清楚。不要把“功能完整”理解为伪装尚未实现的功能。
- 保持 Linux、Windows、macOS 共用 Rust 核心的用户态路线；常规键鼠及音频输入继续由操作系统驱动处理。
- 优先复用前人的实现经验、设备数据和测试结果。可追溯证据、可重放测试和社区贡献应支持单人维护， 不能把购买并亲测所有设备作为普遍准入条件。
- 减少长期人工维护，复用现有模块和自动化；引入依赖、服务、框架或新 crate 必须有当前需求支撑。
开始时检查 git status --short，阅读 README、贡献指南 和任务相关文档：
不要将聊天记忆、旧版本状态、设备数量或一次测试结果当成当前事实；可变信息以当前代码、配置和验证结果为准。 文档、代码与请求不一致时应指出差异，不能默默选择最方便的一方。
3. 架构与硬件安全
- 保持
Transport / Protocol / Capability独立：传输层只负责字节，协议层解释报文，能力层表达用户操作。 设备模型保持Product → Connection → Logical Device → Capability，不要混淆物理连接和逻辑设备。 - Agent 负责设备访问和状态；GUI 通过版本化 IPC 获取结构化结果，不能直接绕过 Agent 枚举或控制 HID。 界面由能力描述驱动，不为每个产品复制一套页面。每个物理连接的请求响应须串行化。
- 当前基线是私有子进程、继承 stdio 管道上的 JSON-RPC，以及只读描述符枚举。 未实现的硬件控制不能显示为可用；扩大到真实 I/O 或常驻服务前，需按相关政策验证设计、权限和风险。
- 正常构建与公共 IPC 不提供任意原始报文写入、固件或引导加载器操作。 不能因“用户要求功能完整”而开启未知指令、持久写入或真实设备 fuzzing。
- 持久写入必须有明确风险提示、确认及验证方案；适用时提供恢复方案。 不得对非幂等写入盲目重试；协议修改须覆盖响应校验、超时、错误和重试边界。
- 测试优先使用纯 codec、golden packet 和 replay transport；不能把维护者唯一的日用鼠标当作默认实验设备。 实机写入、修改设备权限或安装系统服务需要任务范围内的明确授权和风险说明。
- IPC、日志、截图、提交和公开诊断不得泄露序列号、私人路径、账号、令牌或原始输入内容。 分享诊断前脱敏；不自动上传。
4. 上游复用与支持声明
data/upstream/是生成的证据目录；使用tools/import_*.py从固定提交重新生成，不手工改产物。devices/中经审查的设备清单与原始上游声明保持分离。- 重要协议事实记录仓库、commit、路径、符号和许可证。更新上游提交时审查许可证、导入差异及字段含义。 沿用项目 GPL-2.0-or-later 和源码 SPDX 约定；第三方字体等资产保留原许可证和来源。
- 出现数据差异，先比较单位、连接方式、硬件修订、固件及字段语义，再查实现、历史、问题记录和独立证据。 不按“最新来源”或简单多数票直接选值。未解决的冲突只限制受影响字段或能力，并保留依据。
- 导入数量、识别成功和上游支持均不等于 RazeRS 功能可用。
experimental需要符合证据政策的实现、审查和本地测试，但不普遍要求自有硬件；verified必须对应 RazeRS 实测的平台、固件、连接及能力范围。 没有实测记录不等于unsupported，不得夸大或抹去已有证据。
5. 用户体验、i18n 与文档
- 用户可见改动同时检查英文和简体中文：界面、CLI、帮助、状态、错误、无设备及部分支持场景。
在
crates/razers-i18n/locales/en.json和zh-CN.json中同步维护完整句子与占位符； 不依赖英文回退来掩盖漏译，不拼接英文词片段构造中文。 - 翻译显示文本，不翻译协议字段、枚举标识、USB ID、原始证据或诊断数据。 保持离线语言包、离线字体和现有语言选择机制，不引入运行时翻译服务或远程字体。
- 控件的值、范围、应用状态、持久性和失败原因必须与实现一致；考虑键盘操作、缩放及非颜色提示。 功能只有在界面、校验、驱动、测试、错误处理及文档一致时才算用户可用。
- 英文手册在
docs/src/content/docs/en/，中文在docs/src/content/docs/zh-CN/；章节文件一一对应。 导航仅在docs/astro.config.mjs中维护，使用双语分组名；同一 PR 同步审阅对应翻译。 面向用户的 README 变更同步README.md与README.zh-CN.md；项目 API rustdoc 说明兼顾中英文。 - 文档站使用 pnpm + Astro Starlight + rustdoc + GitHub Pages；通过
tools/build_docs.py构建。 Node 以docs/.node-version为准，pnpm 与框架以docs/package.json和锁文件为准。 根入口直接呈现 Starlight 正文，不增加语言选择落地页或另写一套导航。 初期文档允许调整结构和 URL，不默认维护历史页面、锚点或兼容层；只有明确的现存依赖才采用最小处理， 例如已发布客户端使用的/en/帮助入口。不要把推测的未来需求固化成约束。target/site/是生成物，不直接编辑。自动检查根入口、页面配对、翻译同步、当前链接与锚点、 双语搜索和移动端导航；不要用绕过检查替代修复。
6. 实施与验证
- 改动聚焦当前任务，保留用户已有修改；不要顺手重构无关代码、覆盖工作树、重写历史或更改系统配置。 新依赖要检查维护成本、许可证、跨平台能力和最低 Rust 版本；使用现有模块与依赖能解决时优先复用。
- 新行为和修复补充有针对性的测试。不能删除断言、跳过失败用例或降低 CI 门槛来宣称通过。
- 按风险选择本地验证。仅修改本文件等仓库说明时，检查差异、路径和规则一致性即可； 手册改动构建文档站，工具改动运行相关 Python 测试，Rust 改动运行相关测试及必要的工作区检查。 本地验证范围不能替代合并和发布所需的完整 CI。
常用命令（仓库根目录执行）：
git diff --check
cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo test --workspace --all-features --locked
cargo +1.85.0 check --workspace --all-features --locked
cargo run --locked -p razers-cli -- --lang en registry validate devices
cargo run --locked -p razers-cli -- --lang en upstream validate
python3 -m unittest discover -s tools/tests
pnpm --dir docs install --frozen-lockfile
pnpm --dir docs run check
python3 tools/build_docs.py
pnpm --dir docs exec playwright install chromium
pnpm --dir docs run test:siteMSRV 命令须与 Cargo.toml 及 CI 保持一致，不为了通过构建而悄悄提高最低版本。
文档构建需准备 Node 与固定版本 pnpm；build_docs.py 可通过 npm 调用固定 pnpm，不必修改全局工具配置。
新建且尚未跟踪的文件不在普通 git diff 中，须单独检查。
交付时说明做了什么、实际运行了哪些验证、哪些未验证及原因。 明确区分“单元或重放测试通过”“平台构建通过”和“实机验证通过”，不要互相代替。
7. 版本管理与自动化
- 提交使用 Conventional Commits，变更范围清晰。版本、CHANGELOG、标签和 release 沿用 Release Please 工作流； 不因每次任务结束就手工升版本、打标签或绕过发布 PR。文档和内部维护本身不触发功能版本。
- 维护者已委托助手判断合适的发布时间：根据连贯里程碑和实际验证作决定，不必每次询问版本号。 这不扩大任务授权；执行发布仍须遵守当前任务范围、分支保护及发布流程。 核心硬件控制不成熟时保持预发布，不把成功构建当作稳定可用承诺。
- 发布前检查必要 CI；发布后核对所有目标的打包结果、下载校验和及归档内容，诚实说明无法实测的平台。 不在未确认范围内覆盖既有 release 资产或进行破坏性恢复。
- 依赖升级优先沿用 Dependabot 与受 CI 约束的自动合并策略；Actions 固定到不可变 commit SHA。 重大升级、MSRV 改变和破坏性变更需要审查，不自动放宽权限或关闭检查。
- PR 的文档构建不持有 Pages 写权限；站点部署沿用受限的
main分支工作流。 自动化的目的在于减少维护工作，不是跳过风险判断和验证。
本文件保持简洁并链接详细政策，不固化易过期的版本号、设备数量或测试数量。 文件发现与覆盖机制参见 OpenAI 官方 AGENTS.md 说明。