ITADN
software-mansion/argent
代码 动态 Issues5 合并请求10 版本
software-mansion/argent · 文件 下载 ZIP
文件最后提交记录最后更新时间
README.md
以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

argent-header

Ad Ad Ad

Argent 是一个 agentic toolkit，可让您的 AI 助手直接访问 iOS Simulators、Android emulators 和物理设备、TVs（Apple TV、Android TV、Fire TV）以及 Electron/Chromium 桌面和 Web 应用。您可以让它点击按钮、运行 profiler 或手动复现问题——全部在您的 CLI 中完成，无需切换上下文。

npx @swmansion/argent@latest init
# or, in a pnpm project (where npm's devEngines check may refuse to run npx):
pnpm dlx @swmansion/argent@latest init

支持的平台

Argent 通过单一工具包驱动不断扩展的目标集合，每个目标均配备合适的交互模型——触摸、远程或鼠标：

平台目标交互
iOS模拟器触摸 / 手势
Android通过 adb 连接的模拟器（AVD）和物理设备触摸 / 手势
TVApple TV (tvOS)、Android TV / Google TV、Amazon Fire TV (Vega)方向键 / 遥控器
桌面与 Web通过 CDP 连接的 Electron 和 Chromium 应用（包括 React Native Web / Expo web）鼠标 / 键盘

功能

  • 自主移动、电视和桌面开发 - 允许您的代理独立处理 iOS、Android、电视和 Electron/网页应用 - 让它构建、打开、与应用交互并调试。您可以要求复现问题、手动测试功能、分析应用性能等，而无需中断您的工作。
  • UI 交互 - 赋予您的代理完整的控制工具集 - 移动端的点击、滑动、捏合、输入、手势和硬件按钮；电视端的遥控器方向键；桌面/网页端的鼠标、滚动和拖拽。让它像用户一样精确地导航您的应用，无需您动手。
  • 录制与重放流程 - 捕获一次交互序列，让代理确定性地重放它，使手动复现和冒烟测试变得可重复。
  • 视觉回归 - 使用 OCR 和字体感知的比较来对比两张截图（或保存的基线与实时捕获），以捕捉非预期的 UI 变化。
  • 内置全套分析功能 - Argent 可以执行并分析 React Native (Hermes)、React DevTools 和原生 (Xcode Instruments / Android Perfetto) 分析会话 - 深入至 fiber 渲染、CPU 热点以及交叉相关的提交与挂起报告。获取全面的摘要，并在您认为合适的地方要求优化您的应用。
  • 调试与诊断 - 让您的智能体检查日志、捕获网络流量（JS fetch 和原生）、在运行中的应用中评估 JS、遍历原生 UIKit 和 React 组件树，并复现失败状态 - 以便您直接跳转到修复方案。
  • 桌面与 Web 控制 - 对于 Electron 和 Chromium 应用，您的智能体可以驱动标签页、读取和写入 Cookie 和存储、遍历 DOM 并通过 Chrome DevTools Protocol 检查网络。
  • 开箱即用的 React Native - Argent 原生支持 React Native 应用，因此您的智能体可以像处理任何原生应用一样构建、启动和迭代您的 RN 项目 - 无需额外设置。

提示： 安装完成后，向您的助手询问 “Argent 能做什么？” - 它将引导您了解所有可用功能。


argent showcase video gif

安装

先决条件

  • Node.js 20.12 或更高版本
  • 对于 iOS / tvOS：已安装 Xcode 的 macOS（Apple TV 使用 tvOS 模拟器 — Xcode 会按需下载 tvOS 运行时）
  • 对于 Android / Android TV：PATH 上的 Android SDK Platform Tools（adb），以及如果你希望从 Argent 启动 AVD，则还需要 Android Emulator 包。通过 Android Studio 或 avdmanager 创建 AVD。
  • 对于 Fire TV (Vega)：PATH 上的 Vega SDK（vega CLI）
  • 对于 Electron / Chromium：控制已运行的应用无需额外配置 - 只需使用 --remote-debugging-port 启动它，或者让 Argent 为你启动你的 Electron 应用
Linux 主机：Android 模拟器的额外先决条件

Argent 在 Linux 上运行 Android 模拟器，但如果某些主机端设置不正确，默认安装可能会很慢。只需配置一次这些设置，体验即可与 macOS 相当：

  • KVM 访问权限。 如果没有 /dev/kvm，模拟器将回退到缓慢的软件模拟（TCG）。请确保在 BIOS/UEFI 中启用了虚拟化（Intel 为 vmx，AMD 在 /proc/cpuinfo 中为 svm），并且你的用户可以读写 /dev/kvm — 在大多数发行版中，这意味着加入 kvm 组：

    sudo usermod -aG kvm "$USER"
# log out and back in so the new group takes effect

  • GPU 模式（在 Linux 上为 -gpu swiftshader，可覆盖）。 Android 模拟器的 Linux GPU 支持情况较为混乱：-gpu auto 经常解析为 lavapipe（通过主机 libvulkan 实现的缓慢软件 Vulkan，在旗舰硬件上会导致约 10 倍的冷启动性能回退），而 -gpu host 在具有复杂 GL 栈的主机上会静默地产生损坏或黑屏的模拟器窗口——包括双 GPU / Optimus 笔记本、通过 libglvnd 共存 NVIDIA 和 Mesa 的环境、混合图形上的 Wayland 会话、无头 / 容器化主机。这种故障模式对基于帧缓冲区的 argent 截图工具是不可见的，因此代理会报告成功，而开发者看到的却是黑屏。

    Argent 在 Linux 上选择 -gpu swiftshader 以实现通用兼容性：它完全绕过了主机 GL 栈，并通过模拟器捆绑的 SwiftShader 进行渲染。在现代多核机器上，其流畅度与硬件加速的 -gpu host 无异（且远快于 lavapipe）。

    如果您已验证 -gpu host 在您的机器上可用（典型的单 GPU Mesa 环境且拥有健康的 X 会话），请使用 ARGENT_EMULATOR_GPU_MODE 环境变量进行覆盖：

    ARGENT_EMULATOR_GPU_MODE=host argent ...

Argent 的启动设备预检会在 /dev/kvm 不可用时打印警告 —— 该条件会导致 TCG 与 KVM 之间出现 10–50 倍的减速。

  • 系统镜像。 对于无头代理工作流，建议优先选择 x86_64 系统镜像的 default 或 google_apis 变体；google_apis_playstore 会因 Play 服务引入明显的启动时 CPU 负载。在 Intel/AMD 主机上务必选择 x86_64 —— ARM 镜像通过 QEMU 翻译运行，速度显著更慢。

  • AVD 配置。 通过 avdmanager create avd 创建的 AVD 默认使用 hw.gpu.enabled=no。Argent 在启动时通过显式的 -gpu 参数覆盖此设置（因此无需编辑磁盘上的配置）。为了在重度原生构建（与 AVD 并行的 gradle 编译）下获得最流畅的体验，请增加 AVD 的 RAM 和 CPU 数量 —— 编辑 ~/.android/avd/<name>.avd/config.ini：

    hw.ramSize = 8192
hw.cpu.ncore = 6
vm.heapSize = 512

2 GB / 4 vCPU 的 Stock AVD 可能会因并发的 gradle/Kotlin 编译而导致 CPU 资源耗尽，进而使 system_server 进入卡死状态。

  • 无头 / CI 模式（ARGENT_EMULATOR_NO_WINDOW=1）。 Argent 默认显示模拟器窗口，以便本地开发者查看 AVD UI。在无头环境——CI 运行器、容器，或仅支持 Wayland 的会话中，模拟器的捆绑 Qt 没有 wayland 平台插件，并在崩溃同意对话框上触发 SIGABRT——请在启动 tool-server 之前导出 ARGENT_EMULATOR_NO_WINDOW=1 以选择退出。这会将 -no-window 附加到生成参数中，选择 qemu-system-x86_64-headless，后者不需要 Qt 窗口。Argent 基于 screencap 的截图工具可以在没有可见窗口的情况下正确读取内存中的帧缓冲区。

在你的项目中运行 init

从你的项目根目录：

npx @swmansion/argent@latest init
# or, in a pnpm project (where npm's devEngines check may refuse to run npx):
pnpm dlx @swmansion/argent@latest init

此命令将触发一个安装向导，该向导会：

  • 全局安装 @swmansion/argent
  • 检测你的编辑器并注册 MCP 服务器
  • 将 skills、rules 和 agent 定义复制到你的工作区

偏好手动安装？

npm install -g @swmansion/argent
argent init

与团队共享 Argent（可提交安装）

默认情况下，Argent 会全局安装。若要使 Argent 的版本_与你的仓库_保持一致，以便每位 团队成员在 npm install 上获得相同的配置——无需每位开发者进行全局安装，无需 argent init——请选择本地模式：

npx @swmansion/argent@latest init --local
# or, in a pnpm project:
pnpm dlx @swmansion/argent@latest init --local

注意：在刚刚 pnpm init 过的项目中，npx 本身可能会拒绝运行 （npm 的 devEngines 检查）—— 请在那里使用 pnpm dlx 形式。

这会将 @swmansion/argent 添加到您项目的 devDependencies 中，并写入启动项目本地副本（node node_modules/@swmansion/argent/dist/cli.js mcp）的 MCP 配置。 提交 package.json + 您的 lockfile，生成的 MCP 配置（.mcp.json、 .cursor/mcp.json、…），.argent/install.json，以及 skills/rules/agents 文件。 团队成员只需运行 npm install 即可。

传递 --global 以在脚本中强制使用默认模式；--local 和 --global 是 互斥的。非交互式（--yes）运行默认使用全局模式，除非项目 已选择本地模式（已提交的 .argent/install.json，或 在项目自身的 package.json 中声明的 @swmansion/argent）。

在本地模式下，已提交的 MCP 配置运行的是项目本地副本，因此裸 argent 命令不在团队成员的 PATH 上。请注意，npm install 会在每台机器上构建 Argent 的原生依赖（tree-sitter）—— 已为 macOS、Linux x64 和 Windows x64 预构建；其他目标（Linux arm64、Windows arm）将从源码编译 并且需要 C/C++ 工具链。

CLI Reference

CommandDescription
argent init在当前工作区安装并配置 MCP（--global 为默认，--local 用于可提交的 devDependency）
argent installinit 命令的别名
argent update拉取最新版本并刷新工作区配置（作用于当前安装——当全局安装和项目 devDependency 共存时；--global/--local 用于显式选择）
argent uninstall注销 MCP 服务器并卸载包（--global/--local 选择移除哪个安装——及其配置；非交互式运行绝不会移除共存的全局安装）
argent removeuninstall 命令的别名
argent mcp启动 MCP 服务器实例，供 agent 内部使用
argent tools列出 tool-server 暴露的工具（详见 describe <name>）
argent run按名称调用工具
argent server管理共享的 tool-server：start / status / stop / logs
argent lens打开绑定到全新 coding-agent 会话的 Argent Lens — 默认使用 Claude，--agent 可选择 codex/gemini/opencode/cursor（macOS；位于 argent-lens 标志之后 — 请先运行 argent enable argent-lens）
argent link将客户端请求路由到远程 tool-server
argent unlink移除已持久化的远程 tool-server 链接
argent enable启用预定义的功能标志（项目本地使用 --scope project）
argent disable禁用功能标志（项目本地使用 --scope project）
argent flags列出可用的功能标志及其状态
argent telemetry管理遥测：status / enable / disable

支持的编辑器

argent init 会自动检测并配置以下编辑器的 MCP：

编辑器配置位置
Claude Code.mcp.json（项目）或 ~/.claude.json（全局）
Cursor.cursor/mcp.json（项目）或 ~/.cursor/mcp.json（全局）
VS Code.vscode/mcp.json
Windsurf~/.codeium/windsurf/mcp_config.json（全局）
Zed.zed/settings.json（项目）或 ~/.config/zed/settings.json（全局）
Gemini CLI.gemini/settings.json
Codex CLI.codex/config.toml（项目）或 ~/.codex/config.toml（全局）
Hermes~/.hermes/config.yaml（全局）
opencodeopencode.json（项目）或 ~/.config/opencode/opencode.json（全局）
Kiro.kiro/settings/mcp.json（项目）或 ~/.kiro/settings/mcp.json（全局）

隐私

Argent 会收集可退出的使用情况和诊断遥测数据，以帮助我们确定功能优先级并修复问题。

您可以随时退出：

argent telemetry disable   # check status with: argent telemetry status

有关完整详情 — 请参阅 Argent 隐私声明（遥测）。

许可证

Argent 采用混合许可模式。

源代码 依据 Apache License 2.0 发布。

专有二进制文件（各平台的 bin/<platform>/simulator-server 和 bin/darwin/ax-service 可执行文件以及 native-devtools-ios 中的 .dylib 文件）是 Software Mansion S.A. 的知识产权，仅授权在本项目内使用。未经明确书面许可，禁止对其进行反编译、逆向工程或再分发。

使用 Argent 即表示您确认并同意此结构。有关完整详情，请参阅 LICENSE。

Argent 由 Software Mansion 创建

自 2012 年以来，Software Mansion 是一家拥有构建 Web 和移动应用经验的软件代理机构。我们是核心 React Native 贡献者，也是处理各类 React Native 问题的专家。我们可以帮助您打造下一个梦想产品 – 雇佣我们。

swm