首页
/ 从源码到发布：Agent TARS 多模态 Monorepo 的本地开发、调试与贡献指南

从源码到发布：Agent TARS 多模态 Monorepo 的本地开发、调试与贡献指南

2026-09-08 22:02:27作者：咎竹峻Karen
UI-TARS-desktop
The Open-Source Multimodal AI Agent Stack: Connecting Cutting-Edge AI Models and Agent Infra
项目地址：https://gitcode.com/GitHub_Trending/ui/UI-TARS-desktop

Agent TARS 是一个以多模态 AI Agent 为核心的开源工程，本指南聚焦其核心工作区 multimodal，完整梳理从环境初始化、开发调试、核心包热更到 GitHub Release 发布以及无头模式 HTTP 调用的全流程。读完你将掌握如何为 multimodal/CONTRIBUTING.md 中描述的 Agent TARS 贡献代码，并理解 monorepo 各层级包与底层工具链的实际组织方式。

1. 前置条件与开发环境初始化

在开始之前，请确认本机满足以下运行时要求（该约束同时写入了 multimodal/package.json 的 engines 字段）：

依赖 版本要求 用途
Node.js >= 22 运行 pnpm、构建工具链与 vitest 测试
pnpm 9.x（与 Node 22 配套） monorepo 包管理与脚本编排

multimodal 并不是 UI-TARS-desktop 仓库中唯一的工作区，但它承担着 Agent TARS 全链路（从底层 @tarko/agent 内核到 @agent-tars/cli 终端入口）的构建与发布职责。

进入仓库后，需要先完成多级子包的依赖安装与首次构建。文档给出的标准做法是：

# 在仓库根目录下先进入 multimodal 工作区
cd multimodal
pnpm bootstrap

从 multimodal/package.json 中可以看到 bootstrap 的真实执行内容，它并不是简单的安装步骤，而是按依赖顺序对四个子目录分组的包逐一执行构建：

"bootstrap": "pnpm --filter \"./tarko/**\" build && pnpm --filter \"./gui-agent/**\" build && pnpm --filter \"./agent-tars/**\" build && pnpm --filter \"./omni-tars/**\" build"

这意味着 bootstrap 依次编译：底层 tarko 系列包 → GUI Agent 相关包 → Agent TARS 包 → Omni Agent（omni-tars）包。层级越靠底层的包越先产出构建产物，供上层在构建时引用，这正是 monorepo 中保证依赖就绪的核心顺序逻辑。

2. 理解 Monorepo 包结构：层级划分与实际目录

2.1 贡献文档描述的六层架构

multimodal/CONTRIBUTING.md 用「Level 1 ~ Level 6」描述了 Agent TARS 的纵向分层架构，越往下越接近内核，越往上越接近用户交互入口：

.
├── agent                  # Level 1. Event-stream 多模态 Agent 内核
├── mcp-agent              # Level 2. MCP Agent
├── agent-tars             # Level 3. Agent TARS
├── agent-tars-server      # Level 4. Agent TARS Server
├── agent-tars-cli         # Level 5. Agent TARS CLI
└── agent-tars-web-ui      # Level 6. Agent TARS Web UI

需要说明的是，这份目录树描述的是按功能层级的理想划分。从当前仓库的实际结构（见 multimodal/pnpm-workspace.yaml）看，multimodal 下物理组织为 tarko、gui-agent、agent-tars、omni-tars、benchmark、websites 六个 glob 目录组，且 pnpm workspace 显式声明了它们：

packages:
  - 'agent-tars/*'   # Agent TARS
  - 'gui-agent/*'    # GUI Agent
  - 'tarko/*'        # 底层核心
  - 'benchmark/*'    # 基准测试
  - 'websites/*'     # 文档站点
  - 'omni-tars/*'    # Omni Agent

由此可以推断：文档中的「Level 1 Event-stream 内核」对应如今 tarko/agent（包名 @tarko/agent）；「Level 3 Agent TARS」对应 agent-tars 目录下的 @agent-tars/core、@agent-tars/interface、@agent-tars/cli 等包；而文档中列出的 agent-tars-server、agent-tars-web-ui 等概念，在现有仓库中由 @tarko/agent-server 系列与 tarko/agent-ui 等组件承担近似职责。贡献者在本地开发时，应以 pnpm-workspace.yaml 声明的实际目录为准，同时理解背后这套「内核 → MCP → Agent → Server → CLI → Web UI」的六层演进关系。

2.2 从代码看 CLI 如何组装内核

以 Agent TARS 的命令行入口为例，multimodal/agent-tars/cli/src/index.ts 中展示了 AgentTARSCLI 将 @agent-tars/core 的 AgentTARS 类装配为 agent 模块，并为服务端配置 SQLite 会话存储：

const DEFAULT_OPTIONS: Partial<AgentCLIInitOptions> = {
  binName: 'agent-tars',
  appConfig: {
    agent: {
      type: 'module',
      constructor: AgentTARS,
    },
    server: {
      storage: {
        type: 'sqlite',
        baseDir: path.join(homedir(), AGENT_TARS_CONSTANTS.GLOBAL_STORAGE_DIR),
        dbName: AGENT_TARS_CONSTANTS.SESSION_DATA_DB_NAME,
      },
    },
  },
  ...
};

可以看到：CLI 只是一个壳，真正的智能体逻辑来自 @agent-tars/core，会话数据默认落在用户主目录下由 AGENT_TARS_CONSTANTS 指定的全局目录中。这解释了为什么贡献文档强调「调试核心包时要预先构建好底层依赖」——改动 core 的源码后必须重新编译，CLI 才能拿到新逻辑。

3. 启动开发服务器：pnpm dev 与 pnpm dev:core

3.1 pnpm dev：监听全量子包变更

从 multimodal 目录运行下面的命令，即可进入开发模式，监听变更并增量构建需要的子包：

pnpm dev

该命令的真实底层是 multimodal/package.json 中声明的 pdk d，也就是仓库自研的 pnpm-dev-kit（缩写 pdk，代码位于 infra/pdk）提供的开发驱动命令。它负责在文件变更时按 workspace 依赖图调度相关包重建。

3.2 pnpm dev:core：预构建核心包，加快调试

当你在修改较底层的核心包（例如 @tarko/agent、@agent-tars/core）时，文档明确推荐改用：

pnpm dev:core

dev:core 对应的脚本为 pdk d --packages @agent-tars/core。与全量 pnpm dev 不同，它启动时就让核心包处于「已经构建好」的默认状态，而不是等待文件变更后再触发首次构建。为什么这样做更顺滑？因为部分高层包会把核心依赖直接打包进自己的产物（bundling），若核心包迟迟未构建，高层包启动后可能引用到过期产物甚至报模块缺失；预先构建则能保证调试时高层包拿到的是最新核心代码。

如果你需要监听自定义的包组合，可以不使用快捷脚本，直接调用底层命令并传入以逗号分隔的包名列表：

pnpm pdk d --packages @package/name1,@package/name2

⚠️ 注意：pdk（以及 dev:core 中的 --packages）匹配的是 package.json 中的包名（name 字段），而不是目录名。例如目录是 multimodal/agent-tars/core，但传入参数应写 @agent-tars/core。

4. 版本发布：补发历史版本与 Release 管理

Agent TARS monorepo 的发布工作统一由 pdk 驱动（相关实现见 infra/pdk/src/commands/release.ts 与 infra/pdk/src/commands/github-release.ts）。如果你的改动涉及包版本号，却漏掉了某个历史版本的发布，可以使用 GitHub Release 子命令补发。

4.1 先预览（dry-run）再正式补发

# 预览：以 dry-run 方式补发历史版本
pnpm run github-release:dryrun --release-version 0.3.0-beta.9

# 正式补发该历史版本
pnpm run github-release --release-version 0.3.0-beta.9

两个脚本在 multimodal/package.json 中分别对应：

"github-release": "pdk github-release",
"github-release:dryrun": "pdk github-release --dry-run"

执行补发后，工具链会完成以下几件事：

  • 为指定版本创建一个 GitHub Release；
  • 依据 Conventional Commits 规范自动生成规范的 Release Notes；
  • 使用正确的 tag 格式（如 v0.3.0-beta.9）；
  • 以干净的版本标题展示（如 v0.3.0-beta.9，不带多余前缀）。

仓库中 v 前缀 tag 的处理逻辑可以在 infra/pdk/src/tests/tag-prefix.test.ts 的测试中印证，且当前 multimodal 工作区的版本号恰好就是 0.3.0（见 multimodal/package.json 的 version 字段），与文档示例中的 0.3.0-beta.9 同属一个版本序列。

4.2 更多发布相关脚本

multimodal/package.json 还暴露了一整套发布与版本管理命令，日常贡献可参照下表按需选用：

命令 底层 用途
pnpm run release:dryrun pdk release --dry-run 预演正式发布
pnpm run release pdk release 执行正式发布
pnpm run release:full pdk release --create-github-release 发布并同步创建 GitHub Release
pnpm run release:ai pdk release --use-ai 使用 AI 生成变更日志
pnpm run github-release:dryrun pdk github-release --dry-run 仅补发 GitHub Release（预览）
pnpm run changelog pdk changelog 生成变更日志
pnpm run patch pdk patch 执行补丁流程

相关默认行为在 multimodal/pdk.config.ts 中集中配置，例如 pushTag: true（自动推送 tag）、build: true（发布前构建）、autoCreateReleaseBranch: true（自动创建 release 分支），以及 changelog 的 scope 过滤列表（tars、agent、tarko、o-agent、tars-stack、browser、infra、mcp、all）。

5. 本地运行 Agent TARS CLI

5.1 直接调用 CLI 入口

Agent TARS 提供了可直接执行的 CLI 脚本。当前仓库中，其 bin 声明位于 multimodal/agent-tars/cli/package.json，命令名为 agent-tars，指向 bin/cli.js。使用 Node 直接执行入口并传入 provider、model、API Key 与共享服务等参数即可启动：

# 请把下面的路径替换为你本机实际的仓库路径
/path/to/UI-TARS-desktop/multimodal/agent-tars/cli/bin/cli.js \
  --provider=foo \
  --model=bar \
  --apiKey=baz \
  --share-provider=https://aipa.bytedance.net/api/file-upload

字段含义如下：

  • --provider / --model / --apiKey：指定底层大模型服务的提供方、模型名与鉴权密钥；
  • --share-provider：媒体/文件上传共享服务的 HTTP 接口地址，用于把 Agent 运行过程中产生的截图等媒体上传到共享端点。

从 multimodal/agent-tars/cli/src/index.ts 的实现还可以看到，该 CLI 额外暴露了一批与浏览器、规划器、联网搜索相关的参数，开发调试时同样可以透传使用：

CLI 参数 含义 取值/默认
--browser.control <mode> 浏览器控制模式 hybrid、dom、visual-grounding
--browser.cdpEndpoint <endpoint> 连接的 CDP 端点 如 http://127.0.0.1:9222/json/version
--planner.enable 为复杂任务开启规划能力 布尔开关
--search.provider <provider> 联网搜索服务商 browser_search、tavily、bing_search
--search.count <count> 每次搜索返回结果数 默认 10
--search.apiKey <apiKey> 搜索服务 API Key 按服务商要求

（注意 --browser-control、--browser-cdp-endpoint 这类短横线写法是历史遗留的废弃参数，源码中会将其兼容映射到 --browser.control、--browser.cdpEndpoint 上。）

5.2 运行在无头（Headless）模式

与直接执行任务不同，无头模式是把 Agent TARS 作为后台服务跑起来，由外部程序通过 HTTP API 驱动。做法是在同一条启动命令上追加 serve 子命令，保持 provider、model、apiKey 等参数不变：

/path/to/UI-TARS-desktop/multimodal/agent-tars/cli/bin/cli.js serve \
  --provider=foo \
  --model=bar \
  --apiKey=baz \
  --share-provider=https://aipa.bytedance.net/api/file-upload

服务启动后默认监听 http://localhost:8888，暴露 api/v1 会话接口供调用。

6. 通过 HTTP API 驱动 Agent TARS Server

无头模式下，你可以用标准 REST 调用来创建会话、提交任务并实时收取 Agent 事件流。

6.1 创建会话（Session）

curl --location --request POST 'http://localhost:8888/api/v1/sessions/create'

正常响应会返回一个新生成的会话 ID：

{
    "sessionId": "session_1748938641871"
}

6.2 提交任务并流式获取事件

拿到 sessionId 后，通过流式查询接口（SSE/事件流）把用户指令发给 Agent：

curl --location 'http://localhost:8888/api/v1/sessions/query/stream' \
--header 'Content-Type: application/json' \
--data '{
        "sessionId": "session_1748934177009",
        "query": "Search the GUI Agent paper"
}'

服务端返回的是一个按时间序排列的事件数组，每条事件都携带全局唯一 id、事件 type、Unix 毫秒 timestamp 以及关联的 sessionId。贡献文档给出的典型流如下（为突出重点已省略中间事件）：

{
  "events": [
    {
      "id": "77c7b4d3-1358-442b-a06b-9745cc4e97d3",
      "type": "agent_run_start",
      "timestamp": 1748935684768,
      "sessionId": "1748935684768-bskf6nj",
      "runOptions": {
        "input": "Please book me the earliest flight from Hangzhou to Shenzhen on 10.1",
        "stream": true
      }
    },
    {
      "id": "361a7d77-0308-4306-850c-cd30bb72f62d",
      "type": "user_message",
      "timestamp": 1748935684768,
      "content": "Please book me the earliest flight from Hangzhou to Shenzhen on 10.1"
    },
    {
      "id": "d8703eec-2a7d-4ad5-a360-50c90c52ac49",
      "type": "assistant_streaming_message",
      "timestamp": 1748935686136,
      "content": "Search",
      "isComplete": false,
      "messageId": "msg_1748935686054_3kdw42u1"
    }
  ]
}

从中可以观察到 Agent TARS 的核心事件模型：

  • agent_run_start：一次 Agent 运行开始，runOptions 中携带原始输入与是否流式的开关；
  • user_message：回显本轮用户消息；
  • assistant_streaming_message：助手分片产出（isComplete: false 表示仍在流式生成中），可借此实现打字机式实时渲染。

理解这套事件流结构，是接入 Agent TARS Server 作为后端、构建自定义前端或自动化测试的关键。对事件语义与处理链路的进一步开发，建议结合 @agent-tars/core 中 Agent 运行时的实现代码进行断点调试。

7. 测试、构建与更多命令速查

除开发与发布外，multimodal/package.json 还提供了完善的测试与构建配套：

# 运行全部子包测试（vitest）
pnpm test

# 监听模式运行测试
pnpm test:watch

# 生成覆盖率报告
pnpm coverage

# 构建全部子包
pnpm build

# 仅构建某一大组（按 pnpm-workspace glob）
pnpm build:agent-tars
pnpm build:tarko
pnpm build:gui-agent
pnpm build:omni-tars

# 代码格式化（prettier 全量写入）
pnpm format

对应脚本的实际写法为 pnpm run -r build 或 pnpm --filter "./agent-tars/**" --include-dependencies build 等，可在 multimodal/package.json 中逐一核对。其中 --include-dependencies 保证构建指定大组时会先构建其引用的底层依赖，与 bootstrap 的顺序思想一致。

8. 贡献流程小贴士

最后汇总几点来自贡献文档与仓库配置的注意事项，能显著减少踩坑：

  1. 版本约束不可绕过：multimodal/package.json 的 engines 明确要求 node >= 22、pnpm 9，Node 版本过低会导致 pdk 与相关构建脚本不可用。
  2. 改动核心包用 dev:core：正在改 @tarko/agent、@agent-tars/core 这类底层包时，优先 pnpm dev:core 而非全量 pnpm dev，避免等待变更触发首次构建、或高层包引用到未更新的打包产物。
  3. --packages 按包名匹配：pdk d --packages ... 的取值是 package.json 的 name 而非目录名，写错将无法命中目标包。
  4. 发布先 dry-run：涉及补发历史版本时，务必先执行 pnpm run github-release:dryrun --release-version <version> 预览生成结果，确认 tag 格式（v 前缀）与 Release Notes 无误后再正式执行。
  5. 无头模式通过 HTTP 驱动：serve 子命令 + /api/v1/sessions/create + /api/v1/sessions/query/stream 是标准接入方式，事件流请按 type 字段做分发，不要假设 assistant_streaming_message 一次返回完整内容。

按上述流程，你就可以在本地把 Agent TARS 的六层架构跑通——从底层内核改动、核心包热构建，到 CLI/无头服务联调，再到版本发布，形成一条完整的贡献闭环。

UI-TARS-desktop
The Open-Source Multimodal AI Agent Stack: Connecting Cutting-Edge AI Models and Agent Infra
项目地址：https://gitcode.com/GitHub_Trending/ui/UI-TARS-desktop
登录后查看全文

相关内容推荐

1 UI-TARS Desktop 开源贡献指南：Monorepo 开发、构建、测试与发布流程全解析2 TARS 多模态 AI Agent Stack 技术全景：UI-TARS-desktop 仓库中 Agent TARS 与桌面 GUI Agent 的架构、CLI 实战与源码剖析3 Tarko 多模态 Agent 框架文档贡献指南：文档-源码映射与内容准确性校验4 让 UI-TARS 跑在 Web 上：UI-TARS-desktop 仓库 Open Operator 示例，基于 Browserbase 与 Stagehand 构建 Web GUI Agent5 突破云端依赖：Midscene.js本地化部署全攻略6 UI-TARS-desktop multimodal 工作区变更史实践：pnpm-dev-kit 驱动的 monorepo 版本与 Changelog 管理7 基于事件流驱动的多模态 MCP Agent 框架 @tarko/mcp-agent 实战指南与源码解析8 @tarko/agio 详解：为多模态 Agent 服务端打造标准化监控事件协议9 使用 @ui-tars/cli 驱动 ADB 操作 Android 设备：UI-TARS 多模态 GUI Agent 的命令行实战指南10 Tarko Agent 实战指南：基于 @tarko/agent 构建事件流驱动的多模态 Agent 框架
热门项目推荐
相关项目推荐

热门内容推荐

1 编程实践项目探索指南：从零构建技术能力体系2 技术解构式学习：从0到1构建你的编程知识体系3 构建自己的技术世界：build-your-own-x项目的实践探索指南4 解锁编程技能的实践之旅：从零构建你的技术世界5 技术实践探索：从零开始构建核心系统的实践指南6 亲手锻造技术引擎：从0到1构建核心系统的实践指南

最新内容推荐

EIP-7503 零知识虫洞（Zero-Knowledge Wormholes）：为以太坊原生隐私引入的秘密燃烧与再铸造机制Quickwit 缓存架构缺口分析：Parquet 元数据缓存（GAP-007）与多层缓存演进路径SpeechBrain 实战：使用 DNS 嘈杂语音合成器离线生成大规模语音增强训练数据为五种 LoRA 任务定制 Gradio 演示界面：huggingface-lora-space-builder 任务基线 UI 模式实战指南Hindsight Retain 深度解析：如何把对话与文档转化为可检索的结构化记忆Mealie AI 集成完全指南：AI Provider 配置、Import with AI 与提示词定制Bytebot 自托管 AI 桌面 Agent 完全指南：让大模型拥有一台属于自己的电脑Axolotl 集成 Cut Cross Entropy 指南：用低显存交叉熵损失优化大词表模型微调WTF Solidity 链上威胁分析工具全解：交易调试、函数签名解析与反编译实战zstd 在 Linux 内核中的集成与升级全流程：基于 contrib/linux-kernel 的自动化转换指南

项目优选

收起
kernelkernel
deepin linux kernel
C
34
18
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.21 K
2.81 K
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
945
1.86 K
docsdocs
暂无描述
Markdown
906
5.84 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
537
607
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
864
1.36 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
4.28 K
1.03 K
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
1.39 K
1.48 K
AscendNPU-IRAscendNPU-IR
AscendNPU-IR是基于MLIR（Multi-Level Intermediate Representation）构建的，面向昇腾亲和算子编译时使用的中间表示，提供昇腾完备表达能力，通过编译优化提升昇腾AI处理器计算效率，支持通过生态框架使能昇腾AI处理器与深度调优
C++
550
401
flutter_flutterflutter_flutter
本仓库是 Flutter SDK 与 Flutter Engine 的 OpenHarmony 适配版本，由 CPF-Flutter 团队维护。开发者可使用熟悉的 Flutter 技术栈开发 OpenHarmony 应用，3.35.7 及以后的适配版本可基于本仓库源码构建支持 OpenHarmony 的 Flutter Engine。
Dart
1.19 K
347