Imported from location-txl/adbx (AGENTS.md). Install upstream with npx skills add location-txl/adbx. Copyright stays with the author.

adbx 协作指南

本文件记录仓库级长期约定。任务目标和本次改动范围以用户当前明确指令为准；专项实现细节按需查阅下方开发文档。

沟通与执行

• 结论先行、言简意赅。发现需求与源码或实际行为不符时，说明证据和影响。
• 修改任务持续完成实现、相关验证和交付；常规实现细节自行判断，仅在缺失信息会实质改变范围或结果时询问。
• 审查、解释和诊断默认只读；用户要求修复后再改代码。
• 输出实现方案时附简短伪代码；复杂分支或状态流再附纯文本逻辑图。简单修改直接执行。

项目入口

adbx 是 Rust edition 2024 的 adb 扩展 CLI，同时提供库和二进制。它支持包名模糊匹配、应用管理和设备文件浏览，未识别的调用透传给 adb。

• src/main.rs：clap 参数定义、透传路由入口和子命令分发。
• src/lib.rs、src/commands/mod.rs：库与命令模块导出。
• src/commands/：按业务命令组织；browse/ 聚合文件浏览 TUI 的状态、交互和路径逻辑。
• src/adb.rs：唯一的 adb 进程调用出口。
• src/matching.rs：包名匹配纯函数。

本地需要支持 edition 2024 的 Rust 工具链；运行设备功能还需要 PATH 中的 adb 和已授权设备。以下命令在仓库根目录执行：

cargo build
cargo run -- --help
cargo run -- doctor

--help 不需要设备；doctor 检查本机 adb 安装及版本，不验证设备功能。

功能取舍

定位是减少日常 adb 操作成本的本地 CLI，功能取舍遵循以下原则；这些原则不是待实现的功能清单。

• 优先增强高频设备开发操作：应用定位与管理、设备信息诊断、文件浏览与传输，以及这些流程中的错误提示和交互体验。
• 新增功能应有具体使用场景，并明显减少命令拼接、重复操作或误操作；能由 adb 透传直接满足的需求，优先复用透传，不仅为了换名字增加子命令。
• 保持终端和脚本可用：交互操作有明确的取消路径，失败返回可识别的非零退出码；新增交互不能无意阻塞已有脚本。
• 不主动扩展为设备云平台、账号系统、后台常驻服务、通用工作流引擎或插件框架。用户明确提出此类需求时，先说明对项目定位、依赖和维护成本的影响，再确定范围。
• 不重写 adb 协议、设备驱动或已有工具链；不自动安装设备端代理、提权、修改系统设置来掩盖权限或环境问题。
• 不附带无关重构、遥测、联网同步或自动更新。新增子命令前检查是否遮蔽已有 adb 命令，明确兼容行为并补充路由测试。

安全边界

以下规则约束新增和修改的功能，不表示现有功能已具备全部保护措施。涉及既有行为变更时同步修改实现、测试和用户文档。

• 设备与目标：遵循显式 serial 或 adb 的设备选择结果；多设备歧义时返回错误，不自动选第一台。会改变应用状态的模糊匹配必须得到精确或唯一结果，不自动选第一个候选；批量操作需独立、明确的入口与目标集合。
• 读写分离：查询、列表、预览和诊断不得顺带清理、安装、重启或修改设置。读取设备文件到本机也属于本地写入，需要遵守输出目录与覆盖规则。
• 破坏性操作：新增删除、清空、覆盖或批量写入能力时，执行前展示解析后的目标与影响，并要求明确确认；若提供免确认参数，它只能跳过交互，不能跳过目标校验或扩大范围。现有 clear 无二次确认、uninstall 默认确认且支持 -y，不得将新规则描述为已实现行为，也不在无关任务中悄然改变这些契约。
• 路径与命令：设备返回的文件名、包名和用户输入均作为数据处理。进程参数使用参数列表；必须经过设备 shell 的值按 shell 语义转义。设备路径与本地路径分别处理，不能让文件名中的路径穿越或符号链接导致写入超出选定目标范围。
• 失败与取消：不得把部分完成报告为全部成功。失败或取消后说明已完成部分及可能残留的文件；不能通过重试自动扩大范围，或重复执行结果未知的破坏性操作。
• 权限与数据：沿用 adb 和操作系统已有授权，不绕过设备授权、自动提权或读取与任务无关的凭据。日志只记录排障所需信息，不默认输出文件正文、令牌或其他敏感内容；设备数据不自动上传外部服务。
• 透传边界：透传保留原生 adb 行为，不添加命令黑名单、确认弹窗或参数改写来假装提供沙箱。用户显式透传的命令仍可能破坏数据；adbx 自有命令的保护不能代表透传也安全。
• 开发验证：编写危险功能不等于获准在真实设备上执行。测试优先使用纯函数、模拟输入和临时目录；真实设备写入必须处于用户明确授权的设备、目标和操作范围内。

实现约束

调用方向保持单向：

src/main.rs → src/commands/<命令> → src/adb.rs → adb

• 命令模块通过 adb.rs 执行设备 I/O，不直接创建 adb 进程；设备 serial、进程退出码和 adb 错误输出在该边界统一处理。
• 保持透传语义：保留原始参数、stdio、信号和退出码；不要给透传输出添加 adbx 的成功提示。
• adbx 命令入口返回 anyhow::Result；错误由 main 统一打印并以退出码 1 结束，成功动作沿用 ✓ 提示。
• 匹配、解析、路径和状态整理优先写成纯函数；设备 I/O 在明确的调用处执行。
• 按功能就近组织代码，复用现有实现。选择最小、易维护的改动，不为假设中的需求添加抽象层、依赖或防御分支。
• 新增类型（struct、enum、trait）及公共 API 使用 Rust doc 注释。核心函数说明职责、关键参数、返回值及实际存在的错误或副作用；复杂分支说明关键步骤和不直观的原因，简单私有函数不写重复注释。
• 新增命令同步修改 clap 定义、分发、模块注册和用户文档；改变实现机制时更新对应开发文档。

验证与完成标准

修改 Rust 源码或构建配置后运行：

cargo fmt --check
cargo build
cargo clippy --all-targets -- -D warnings
cargo test

• 行为变更补充有意义的回归测试，优先覆盖纯函数和错误分支；不为简单改动堆砌与实现重复的测试。
• 修改 CLI 参数或路由时核对相关帮助输出、解析测试和透传测试。
• 仅修改文档时，核对路径、链接、命令与源码的一致性，并运行 git diff --check；不要求完整 Rust 构建。
• 设备测试按明确的设备和操作范围执行；不要为验证擅自清数据、卸载应用或覆盖设备文件。普通 cargo test 不执行 ignored 测试，不等于设备验收。
• 完成前检查最终 diff，确认没有夹带无关修改。交付说明改动结果、已运行检查及结果、未验证项；检查受阻时说明具体原因。

文档导航与分层

• README.md：用途、安装和最短上手路径。
• docs/：完整操作指南、参数、快捷键、示例、限制和常见问题；不放源码路径、模块关系、依赖选择或内部算法。
• 架构与边界：模块职责、命令注册、透传和测试分工。
• browse 实现：TUI 状态、设备 I/O、编辑保存和进度处理；修改设备文件浏览功能时按需阅读。
• 构建与发布：工作流、目标平台和安装脚本；修改发布或安装流程时阅读。

README 和 docs 中的命令、参数、示例必须与 clap 定义和实际行为一致。发布资产、版本规则或安装参数变更时，同时核对 .github/workflows/release.yml、install.sh、install.ps1 和 README。

工作区与 Git 安全

• 开始修改前执行 git status --short --branch -uall，按需查看暂存区、工作区 diff 和未跟踪文件，保留用户已有改动。
• 没有用户明确的 Git 指令时，只允许只读 Git 命令；禁止 add、commit、reset、restore、checkout、switch、merge、rebase、cherry-pick、push、clean、stash 等改变仓库状态或历史的操作。
• 获得 Git 操作授权后也只处理指定范围；不要覆盖、清理或移动无关工作区内容。

本文件维护

保持指令简短、具体且可验证；专项细节放入开发文档，需要不同目录规则时再增加局部 AGENTS.md。不要在这里复制技能全文、临时任务计划或易过期的版本清单。

编写参考（2026-09-13 核对）：OpenAI AGENTS.md 指南、Codex 最佳实践。