UI-TARS-desktop multimodal 工作区变更史实践：pnpm-dev-kit 驱动的 monorepo 版本与 Changelog 管理

multimodal/CHANGELOG.md 是 UI-TARS-desktop 仓库中 multimodal（Agent TARS）工作区的完整版本变更记录，横跨 0.1.12-beta 到 0.3.0 共 30 余个版本、500 余条变更项，覆盖 agent-tars、tarko、gui-agent、omni-agent 等全部核心模块。本篇基于该文档，并结合仓库中的 pnpm-dev-kit 工具链源码 与 工作区发布配置，讲清楚这份 Changelog 是如何被自动生成的、版本号与 npm dist-tag 策略是什么，以及如何从变更历史中定位某个功能进入发布的版本——读完你可以独立维护、审阅一份大型 monorepo 的变更史，并复用同一套发布流程。

Changelog 文档的结构与阅读方式

这份 Changelog 采用 GitHub Release Notes 风格，每一节由「版本头 + 分类小节 + 条目列表」组成：

• 版本头：形如 ## 0.3.0 (2025-11-07)，包含版本号、指向上一版本的 compare 链接和发布日期；
• 分类小节：### Features（新功能）、### Bug Fixes（缺陷修复）、### ⚠ BREAKING CHANGES（破坏性变更）、### Chores（杂项/发布动作）；
• 条目格式：**scope:** 描述 (#PR 号) (commit 短哈希) [@作者]，scope 即该条目影响的子包或模块。

以 0.3.0 正式版中的两条为例（原文第 12 行、第 52 行附近）：

* **gui-agent:** add image detail calculator for enhanced screenshot processing (#1724) (71e6e1a)
* **mcp:** RCE Vuln: Remove `DANGEROUSLY_OMIT_AUTH=true` from dev scripts (#1731) (e71fce1)

阅读时的三个实用要点：

1. 按 scope 过滤：本文档的 scope 命名与 multimodal 工作区 中的 filterScopes 对齐（tars、agent、tarko、o-agent、tars-stack、browser、infra、mcp、all），搜索 **agent-tars:** 或 **tarko:** 即可快速还原某条产品线的时间线；
2. 同一 PR 可能跨版本重复出现：例如 #1397（html renderer 默认白底背景）同时出现在 0.3.0-beta.10 与 0.3.0-beta.9，这是预发布版本基于同一 commit 基线（@agent-tars@0.3.0-beta.5）生成、正式版又重新汇总造成的，属正常现象，不代表重复发布；
3. 破坏性变更有独立小节：如 0.3.0-beta.0 标注的 **agent-tars-server:** add api version（commit be88515），提示服务端 API 从此带上了版本前缀（后文 API 路径可见 api/v1/...），是跨版本升级时需要重点关注的条目。

版本演进主线：从 0.2.x 到 0.3.0

整份文档按时间倒序排列，可以梳理出四条并行的演进主线：

版本区间	时间	主线内容（依据文档条目）
0.1.12-beta.2 ~ 0.2.0	2025-06	agent-tars CLI 成型：workspace 命令、agent-tars run、CLI bundle、--browser.cdpEndpoint 连接远程浏览器、browser_screenshot 工具、web-ui 首个稳定版
0.2.0 ~ 0.2.10	2025-06 ~ 07	会话能力补全：replay/分享、/api/v1/version、oneshot API、AGENT_TARS_BASE_URL 云部署支持、桌面端 deprecation 警告
0.3.0-beta.0 ~ beta.11	2025-07 ~ 09	架构切换期：agent-kernel 流式 tool call、enableStreamingToolCallEvents、MongoDB provider、AIO sandbox、agui CLI、@tarko/agent-ui-builder 初始化、guiAgent.renderBrowserShell 等 webui 配置项
0.3.0-beta.12 ~ 0.3.0	2025-09 ~ 11	稳定收口：runtime settings API（examples/enhanced-runtime-settings.config.ts 类配置结构）、事件流查看器、welcome cards、截图 detail 参数与游戏模式、RCE 漏洞修复（移除 DANGEROUSLY_OMIT_AUTH=true）

值得注意的横向事实：0.3.0 正式版（2025-11-07）是最后一节，其对比基线为 v0.3.0-beta.11-canary-...，说明正式版直接建立在 canary 通道之上——这正是后文要讲的 canary 版本机制的实际产物。

Changelog 是如何被生成的

文档本身不是手写的。生成逻辑位于 infra/pdk（pnpm-dev-kit）的 changelog 命令实现，核心流程：

1. 确定版本号：未显式传入 version 时，读取工作区根 package.json 的 version 字段（当前为 0.3.0）；
2. 确定标签区间：以 v{version} 构造 tag 名，优先匹配仓库中实际存在的 git tag，再通过 getPreviousTag 找到上一个非 canary tag，生成「上一版本 → 当前版本」的提交区间；
3. 生成 Release Notes：默认走 GitHub 风格的 conventional commit 汇总（generateReleaseNotes，按 scope 过滤）；开启 useAi 时改用 AIChangelogGenerator 生成；
4. 写入文件：在 # Changelog 标题之后插入新条目，保留全部历史：

// infra/pdk/src/commands/changelog.ts 的插入逻辑（简化）
const updatedContent = existingContent.replace(
  /# Changelog\s+/,
  `# Changelog\n\n${changelogContent}`,
);

这也解释了文档为什么是「最新在最上、历史完整保留」的结构，以及为什么文件头部只有孤零零的 # Changelog 一行。

工作区发布配置 pdk.config.ts

multimodal/pdk.config.ts 是该工作区发布行为的全部声明：

import { defineConfig } from 'pnpm-dev-kit';

export default defineConfig({
  // Release defaults for multimodal workspace
  pushTag: true,                    // 发布后自动推送 git tag
  build: true,                       // 发布前执行构建
  ignoreScripts: true,               // 发布时忽略 lifecycle scripts
  autoCreateReleaseBranch: true,     // 自动创建/回切 release 分支

  // Scope filtering for changelog
  filterScopes: ['tars', 'agent', 'tarko', 'o-agent', 'tars-stack', 'browser', 'infra', 'mcp', 'all'],

  // AI changelog configuration (opt-in)
  provider: 'azure-openai',
  model: 'aws_sdk_claude37_sonnet',
  baseURL: process.env.AWS_CLAUDE_API_BASE_URL,
});

其中 filterScopes 就是 Changelog 条目 scope 的白名单来源：只有提交信息 conventional scope 落在这些前缀下的变更才会进入这份文档；provider/model 一组则是 opt-in 的 AI changelog 通道，默认不使用，日常发布走的是传统 GitHub 风格汇总。defineConfig 只是类型安全的透传函数，见 infra/pdk/src/config.ts。

对应的 npm scripts

multimodal/package.json 把上述能力暴露为一组脚本，在 multimodal/ 目录下执行（要求 Node ≥ 22、pnpm 9）：

"release": "pdk release",                       // 交互式完整发布
"release:dryrun": "pdk release --dry-run",      // 预演：只打印将做的动作
"release:canary": "pdk release --canary",      // canary 通道发布
"release:full": "pdk release --create-github-release",  // 发布并创建 GitHub Release
"release:ai": "pdk release --use-ai",          // 使用 AI 生成 changelog
"changelog": "pdk changelog",                  // 仅生成/更新 CHANGELOG.md
"patch": "pdk patch"                           // 回滚修复失败的发布

完整发布流程：release 命令做什么

release 命令实现 串联了从版本选择到 tag 推送的全流程，执行顺序为：

1. 选择版本与 dist-tag：交互模式下提供 patch/minor/major 三种正式 bump、beta/alpha/rc 三种预发布 bump 与自定义输入；
2. （可选）创建 release 分支：autoCreateReleaseBranch: true 时由 ReleaseBranchManager 接管分支切换，失败自动回滚清理；
3. 统一更新所有包版本：在构建之前把 workspace 内每个包的 package.json 与根 package.json 写为同一版本号（monorepo 锁版本策略）；
4. 构建（build: true）→ 发布非 private 包（publishPackages 处理 workspace 依赖替换）；
5. 生成 Changelog（不单独提交，gitPush: false 把推送权交给主流程）；
6. Git 操作：git add -A 提交 chore(all): release {version} and changelog → 创建 v{version} tag → 推送 tag；
7. （可选）创建 GitHub Release；
8. 失败兜底：捕获异常时自动调用 patch 命令 回退已发布的版本。

版本策略：stable / beta / canary 三级通道

infra/pdk/src/utils/version.ts 定义了版本生成规则，对应 CHANGELOG 中三类版本头：

• 正式版：semver.inc(current, 'patch'|'minor'|'major')，dist-tag 默认 latest；
• 预发布版：semver.inc(current, 'prerelease', 'beta'|'alpha'|'rc')，如文档中的 0.3.0-beta.12，dist-tag 与预发布类型对应（beta、alpha、rc）；
• canary 版：格式为 {version}-canary-{commitHash}-{timestamp}，dist-tag 固定为 nightly：

// infra/pdk/src/utils/version.ts
const canaryVersion = `${currentVersion}-canary-${commitHash.trim()}-${timestamp}`;
return { version: canaryVersion, tag: 'nightly' };

对照文档可以验证：0.3.0 版本头的 compare 起点是 v0.3.0-beta.11-canary-e70d431f-20250917163005——即 commit e70d431f、时间戳 2025-09-17 16:30:05 的一次 canary 构建，后续 0.3.0-beta.12 与 0.3.0 都从它汇总而来。理解这一点对排查「某功能到底在哪个 tag 可复现」非常关键：canary 条目不入正式历史，但会作为正式版的 diff 基线。

从变更史追踪一个功能的落地路径

以 0.3.0 中 runtime settings 特性为例，仅凭这份 Changelog 即可还原完整的落地链路（跨多个版本的 scope 条目）：

1. **tarko-agent:** runtime settings（#1561，0.3.0-beta.11 区间）：服务端 runtime settings API 落地（**tarko:** add runtime settings api in server-next #1634）；
2. **tarko-agent:** enhance runtime settings with enum labels and UI placement control（#1638）：增加枚举标签与 UI 摆放控制；
3. **omni-agent:** add default runtimeSettings（#1657）→ update agent mode config structure（#1642）→ agentMode structure update; add game mode support（#1649）：上层 Agent 接入并迭代配置结构；
4. 修复项 **tarko-agent-server:** system setting api 404 issues（#1669）、ensure agent initialize events are persisted（#1660）收口稳定性。

配套的示例配置可直接参考 examples/enhanced-runtime-settings.config.ts 与 examples/conditional-visibility-settings.config.ts。这种「feature 条目 + 配套 bug fix 条目 + 仓库内示例文件」的三角验证，是阅读本 Changelog 定位任何特性的推荐方法。

小结

multimodal/CHANGELOG.md 既是一份可追溯的功能档案，也是 pnpm-dev-kit 发布工具链的产物：版本头、scope 过滤（filterScopes）、canary 基线（{version}-canary-{hash}-{ts}）与「插入式」追加写入都是确定性规则的结果。对使用者，按 scope 检索 + 版本头时间线即可定位能力的可用版本；对维护者，pnpm release:dryrun 预演、pnpm changelog 单独刷新、pnpm release:canary 走 nightly 通道，构成一套完整的 monorepo 变更史维护闭环。