如何给 Argent 写工具：开发者指南从源码构建到贡献第一个 PR

如何给 Argent 写工具开发者指南从源码构建到贡献第一个 PR【免费下载链接】argentAn agentic toolkit to control, debug, and profile iOS and Android apps. Made by Software Mansion.项目地址: https://gitcode.com/gh_mirrors/arg/argentArgent 是 Software Mansion 出品的 agentic toolkit让 AI 助手直接控制 iOS 模拟器、Android 模拟器与真机、TV 和 Electron 应用。本指南带你从源码构建 Argent理解它的工具架构并写出自己的第一个 Argent 工具贡献 PR。无论你是想扩展设备交互能力还是想深入 AI 工具链开发这套完整的 Argent 工具开发流程都适用。为什么给 Argent 写工具Argent 的每一个能力——点按、截图、性能分析、网络抓包——都是一个独立的tool。这些工具以 HTTP API 暴露给 MCP 适配器AI 助手调用它们完成真实操作能力对应工具目录设备交互点按/滑动/输入gesture-tap、gesture-swipe、keyboard性能分析Hermes、Instruments、Perfettoprofiler视觉回归screenshot-diff调试日志、网络、JS 求值debugger、network当你发现AI 还缺一个能……的工具时答案往往就是给 packages/tool-server/src/tools/ 里加一个新工具。一键搭建本地开发环境按照 CONTRIBUTING.md 的官方要求先确认环境macOS XcodeiOS 模拟器支持需要xcrun simctlNode.js 20.19lint 工具链下限发布包只需 20.12然后三步走克隆仓库Fork 后请替换为你自己的地址git clone https://gitcode.com/gh_mirrors/arg/argent cd argent安装依赖npm workspaces 会一次装完所有包npm install启动开发环境npm run devnpm run dev会自动编译 MCP TypeScript、把~/.claude.json指向本地 MCP并从源码启动 tool-server。CtrlC停止时会自动恢复你全局的 Argent 配置放心折腾。没有 SSH 权限访问私有子模块packages/argent-private也没关系——会回退到仓库里已构建好的 dylib。看懂项目结构工具到底写在哪里Argent 是一个 npm workspaces 单仓所有包都在packages/下。与写工具最相关的只有 4 个包路径作用argent/registrypackages/registry核心库服务生命周期、蓝图、工具与 URNargent/tool-serverpackages/tool-server注册所有工具并暴露 HTTP API默认端口 3001argent/mcppackages/argent-mcpMCP 协议适配器把 Claude/Cursor 的调用代理给 tool-serverargent/clipackages/argent-cli命令行入口argent run、argent tools等TypeScript 采用 project references 管理构建共享编译选项strict模式、ES2022集中在 tsconfig.base.json。官方文档站点在 packages/docs/ 目录下维护。构建并验证 Tool-Server日常开发推荐npm run dev需要完整构建产物时npm run build # 构建全部包 npm run start # 构建后从编译产物启动服务启动后一条命令确认所有工具已注册curl http://localhost:3001/tools能打印出工具清单说明你的本地源码版 Argent 已经跑起来了。解剖一个真实工具以 shake 为例在写新工具前先读懂最简单的现有工具。shake模拟摇一摇是绝佳样本整个工具只有 4 个文件packages/tool-server/src/tools/shake/schema.ts —— Zod 校验参数packages/tool-server/src/tools/shake/index.ts —— 工具定义packages/tool-server/src/tools/shake/platforms/ios.ts —— iOS 平台实现platforms/android.ts—— Android 平台实现工具定义的核心字段所有工具都实现 ToolDefinition 接口关键字段字段作用shake 的写法id工具唯一标识AI 按它调用shakezodSchema运行时参数校验JSON Schema 自动派生shakeZodSchemadescription写给 AI 看的说明书直接决定模型会不会用它详细说明适用场景capability平台/设备能力矩阵如仅 iOS 模拟器 Android 模拟器apple: { simulator: true }services声明依赖的注册表服务() ({})execute真正执行逻辑跨平台工具用dispatchByPlatform分发ios/android两个实现两个容易被忽略的细节searchHint是一段短词供 Claude Code 的 ToolSearch BM25 检索命中工具capability让不支持的设备在调用前就被能力门拦截而不是运行到一半报错。四步写出你的第一个工具建目录在packages/tool-server/src/tools/下新建my-tool/包含schema.ts、types.ts、index.ts。写参数校验用 Zod 描述入参每个参数加.describe()——这段文字会被 AI 看到。定义工具照 shake/index.ts 的骨架填好id、zodSchema、capability、execute。跨平台场景复用dispatchByPlatform分发到各平台实现。注册工具在 setup-registry.ts 中registry.registerTool(myTool)一行即可。写完重启npm run devcurl http://localhost:3001/tools里就能看到你的新工具了。跑测试与死代码检查Argent 的测试用 Vitest。为工具补充测试的参考模板工具行为测试packages/tool-server/test/shake.test.ts契约级测试如输入 schema 不得出现顶层组合关键字packages/tool-server/test/tool-input-schema-contract.test.tsnpm test -w argent/tool-server npm run test:watch -w argent/tool-server # 开发时 watch 模式提 PR 前还有一道 CI 会卡的关knip 死代码检查。必须在未构建的树上运行报告必须为空npx tsc --build --clean npm run knip 若某导出符号只被另一个 workspace 调用而 knip 看不见给它加/** public */注释并写明调用方而不是直接删掉。提交 PR从分支到合并CONTRIBUTING.md 给出的 8 步流程浓缩成要点✅ 从main拉描述性分支feat/add-my-tool、fix/session-leak✅ 保持 PR 小而聚焦一个 PR 只做一件事✅ 构建通过npm run build 触碰过的包测试通过✅ 提交信息带类型前缀feat:、fix:、chore:、docs:、refactor:、test:——它直接进自动生成的 changelog✅ PR 标题同样使用这套前缀合并后会出现在发布说明里✅ 审查开始后追加新 commit不要 force-push如果对方案拿不准先开 Discussion 或在 issue 里留言比闷头写一个大 PR 更高效。结语从npm run dev到注册自己的第一个工具Argent 为贡献者准备了完整的本地开发闭环严格的 TypeScript、能力矩阵、Vitest 测试与 knip 死代码门禁。挑一个你真正需要的设备能力参考shake的骨架写起来——你的第一个 PR离合并只差一次npm run build。【免费下载链接】argentAn agentic toolkit to control, debug, and profile iOS and Android apps. Made by Software Mansion.项目地址: https://gitcode.com/gh_mirrors/arg/argent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考