Merge pull request #4380 from VisActor/release/2.0.12

[Auto release] release 2.0.12

Author: xuefei1313

.gitignore

@@ -47,6 +47,7 @@ report.html
 coverage/
 
 *.local.ts
+*.local.md
 
 # Dependency directories
 node_modules/
@@ -132,4 +133,4 @@ packages/vchart/__tests__/runtime/node/**.png
 # env files
 .env.local
 
-*.tsbuildinfo
+*.tsbuildinfo

.trae/documents/auto-flow.solo.md

@@ -0,0 +1,34 @@
+# Auto Flow（串行编排）Solo 使用说明
+
+- 入口文件：`./.trae/jobs/auto-flow.md`
+- 流程：分支预检查 → 自动化测试 → Rush 变更日志 → 创建 PR
+
+## 参数
+- `baseBranch`：默认 `develop`
+- `lang`：`zh|en`，默认 `zh`
+- `labels`：默认 `[changelog, test]`
+- `topic`：可选；用于 PR 标题优化（未提供时用当前分支名）
+- `message`：可选；作为 PR body 摘要
+- `bumpType`：默认 `auto`
+- `notCommit`：默认 `true`
+- `head`：可选；未提供时自动推导当前分支
+
+## 前置
+- 若需自动创建 PR 或聚合 Issue 标题，请先设置 `GITHUB_TOKEN`（参考 `./.trae/github-token.local.md`）
+
+## 使用（Solo）
+- 在聊天中发起：“执行 Auto Flow（.trae/jobs/auto-flow.md）”，可附加：
+  - `topic: feature-legend`
+  - `message: 'docs: chore(trae): add auto-flow'`
+  - `mode: browser`（默认以浏览器创建 PR，输出可复制内容与 compare URL）
+  - （可选）`openBrowser: true`（自动打开浏览器）
+
+## 输出
+- `autotest_report`：`./.trae/jobs/autotest.report.local.md`
+- `rush_change_entries`：`common/changes/**`
+- `pr_url`：PR 链接（若已创建）
+
+## 人工检查
+- 单测后检查报告与覆盖率摘要
+- 变更日志后检查 `common/changes/**`
+- PR 前检查标题与正文信息；如需补充 body，请人工完善后再创建

.trae/documents/auto-test.solo.md

@@ -0,0 +1,60 @@
+# Autotest（差异驱动单元测试生成）Solo 使用说明
+
+- 入口文件：`./.trae/jobs/auto-test.md`
+- 作用：根据 `develop...HEAD` 的代码差异，自动生成/更新测试用例与快照，并运行覆盖率与报告
+
+## 参数
+- `sinceBranch`：默认 `develop`
+- `project`：默认 `auto`（自动识别变更包）；可指定如 `@visactor/vchart`
+- `mode`：`full`（默认）
+- `noSnapshot`：是否跳过快照，默认 `false`
+- `onlyNew`：仅生成新的自动化区块，默认 `false`
+- `reportFormat`：`md|json`，默认 `md`
+- `applyManualOverrides`：应用人工覆写，默认 `true`
+- `replaceAutogen`：允许替换已有 `autogen:` 块，默认 `false`
+- `dryRun`：仅预览不写文件，默认 `false`
+- `preview`：是否预览模式，默认 `false`
+- `stopOnError`：遇错停止，默认 `true`
+- `focusChangedOnly`：仅聚焦变更，默认 `true`
+- `snapshotStrategy`：`combined`（默认）
+- `tempReportPath`：默认 `./.trae/output/autotest.report.local.md`
+- `mockDefaults`：默认 `time=fixed(2020-01-01T00:00:00Z)`、`random=seed(42)`
+
+## 使用（Solo）
+- 最简：在聊天中发起“执行 Auto Test Job（.trae/jobs/auto-test.md）”
+- 指定包：`project: '@visactor/vchart'`
+- 指定输出格式：`reportFormat: 'json'`
+
+## 输出
+- `test_files`：新增/更新的 `.test.ts`
+- `snapshots`：快照文件
+- `coverage_report`：覆盖率摘要
+- `manual_nodes`：需人工处理的用例占位
+- `temp_markdown_report`：临时报告（默认写入 `./.trae/output/autotest.report.local.md`）
+
+## 成功标准
+- `tests_generated_for_changed_exports`
+- `compile_without_errors`
+- `coverage_increase_or_maintained`
+
+## 人工覆写示例
+```yaml
+manual_overrides:
+  - target: packages/vchart/src/util/color.ts#parseColor
+    mocks:
+      date: fixed(2020-01-01T00:00:00Z)
+      random: seed(42)
+    inputs:
+      - { args: ['#ff0000'], desc: '基本路径' }
+      - { args: ['invalid'], desc: '异常路径' }
+    asserts:
+      - { expect: 'toEqual', value: { r: 255, g: 0, b: 0 } }
+```
+
+## 运行与诊断
+- 我会自动执行 `rush run -p <project> -s test` 与 `test-cov`
+- TypeScript 诊断与覆盖率结果会写入临时报告以便复核
+
+## 注意事项
+- 若差异范围为空，建议指定 `project` 以运行目标包测试
+- 对低覆盖模块，建议补充手动测试并复跑 Auto Test 以提升覆盖率

.trae/documents/changelog-rush-smart.solo.md

@@ -0,0 +1,24 @@
+# Changelog（Rush 智能变更日志）Solo 使用说明
+
+- 入口文件：`./.trae/jobs/changelog-rush-smart.md`
+- 作用：对齐并增强 `change-all.ts`，生成 Rush 变更条目（`common/changes/**`）
+
+## 参数
+- `sinceBranch`：默认 `develop`
+- `message`：可选；若为空自动生成富摘要
+- `bumpType`：`auto|major|minor|patch`，默认 `auto`
+- `notCommit`：是否跳过 `git commit`，默认 `true`
+- `githubToken`：可选，聚合 Issue 标题时需要
+
+## 使用（Solo）
+- 在聊天中发起：“执行 Changelog Job（.trae/jobs/changelog-rush-smart.md）”，可附加：
+  - `message: 'docs: chore(trae): add auto-flow'`
+  - `bumpType: patch`
+
+## 输出
+- `rush_change_entries`：新增的变更条目路径集合
+- `computed_bump_type`：自动判定的 bump 类型
+- `final_message`：最终用于 `rush change` 的消息
+
+## 人工检查
+- 复核 `common/changes/**` 的内容（包名、类型、comment），必要时重新执行并覆盖 `message/bumpType`

.trae/documents/create-branch.solo.md

@@ -0,0 +1,20 @@
+# Create Branch Job（Solo 使用说明）
+
+- 入口文件：`./.trae/jobs/create-branch.md`
+- 适用场景：需要在本地通过 Job 统一创建开发分支
+
+## 参数
+- `baseBranch`：默认 `develop`
+- `branchPrefix`：默认 `chore/trae`
+- `topic`：必填，主题描述（例如 `feature-legend`）
+- `useDateSuffix`：是否追加日期后缀，默认 `true`
+
+## 使用（Solo）
+- 在聊天中发起：“执行 Create Branch Job（.trae/jobs/create-branch.md）”，并传入：
+  - `topic: feature-legend`
+
+## 输出
+- `branch_name`：生成的分支名
+
+## 人工检查
+- 执行完成后：`git status` 确认当前分支与工作树状态

.trae/documents/pr-create.solo.md

@@ -0,0 +1,52 @@
+# PR 创建 Job（Solo 使用说明）
+
+- 入口文件：`./.trae/jobs/pr-create.md`
+- 作用：依据仓库 PR 模版生成正文并创建 PR
+
+## 参数
+- `base`：默认 `develop`
+- `head`：可选；未提供时自动推导当前分支
+- `title`：必填；PR 标题
+- `lang`：`zh|en`，默认 `zh`
+- `labels`：可选标签数组
+- `draft`：是否草稿，默认 `false`
+- `useGhCli`：是否使用 `gh` 创建，默认 `true`
+- `mode`：`auto|gh|rest|browser`（默认 `auto`，优先浏览器免安装）
+- `localBodyFile`：是否生成本地可复制正文文件（默认 `false`）
+- `openBrowser`：是否自动打开 compare URL（默认 `true`）
+- `commitBeforeCreate`：创建 PR 前是否自动提交未提交变更（默认 `false`）
+- `commitMessage`：自动提交的 commit 消息（默认 `chore: auto commit before pr`）
+- `commitAllowEmpty`：是否允许空提交（默认 `false`）
+- `pushAfterCommit`：提交后是否自动推送当前分支（默认 `true`）
+- `commitMessageStrategy`：提交信息生成策略（`auto|topic|manual`，默认 `auto`）
+  - `auto`：按变更内容自动判定类型（`docs|test|chore`）、作用域（包名或顶层目录），主题取 `message` 首行或自动摘要
+  - `topic`：主题优先使用 `title`/外层 `topic`
+  - `manual`：使用 `commitMessage`
+
+## 前置（登录/令牌）
+- 优先方案：使用 GitHub CLI（`gh`）并已登录 → 不需要额外令牌
+- 备选方案：无 `gh` 时提供 `GITHUB_TOKEN`（参见 `./.trae/github-token.local.md`）
+- 兜底方案：生成浏览器 compare URL，使用你浏览器的登录态手动创建 PR
+
+## 使用（Solo）
+- 在聊天中发起：“执行 PR Job（.trae/jobs/pr-create.md）”，并传：
+  - `title: '[Auto] feature-legend'`
+  - （可选）`head: chore/trae-feature-legend-20251222-1030`
+  - （可选）`mode: auto|gh|rest|browser`（默认 `auto`）
+  - （可选）`localBodyFile: true|false`（默认 `false`）
+  - （可选）`openBrowser: true|false`（默认 `true`）
+  - （可选）`commitBeforeCreate: true`、`commitMessage: 'chore: auto commit before pr'`、`pushAfterCommit: true`
+  - （可选）`commitMessageStrategy: auto`
+
+## 正文准备
+- 若 `message` 已包含摘要与关联信息，可直接作为 body
+- 若需要补充，请先人工完善 body 文本，再执行创建（不生成临时文件）
+
+## 输出
+- `pr_url`：创建的 PR 链接（`gh/rest`）
+- `compare_url`：浏览器 compare 页面（`browser`）
+- `generated_title`：建议标题（便于复制）
+- `generated_body_preview`：建议正文（便于复制）
+
+## 人工检查
+- 提交前检查标题、关联链接与 Changelog 摘要是否完整

.trae/jobs/README.md

@@ -0,0 +1,80 @@
+# 通过说明文件驱动执行
+
+## 目的
+
+- 不依赖“工作流模版”概念，仅在仓库中放置一个说明文件，描述任务与参数；我将按说明执行并回传报告。
+
+## 放置位置
+
+- 目录：`.trae/jobs/`
+- 文件：建议使用 `*.request.md` 或 `*.request.json`，便于版本化与审阅。
+
+## 通用字段
+
+- `Task`：任务标识，例如 `Auto Test (diff-with-develop)`。
+- `Parameters`：运行参数，例如 `sinceBranch`、`project`、`mode`、`noSnapshot`、`onlyNew`、`reportFormat`、`tempReportPath`。
+- `ExecutionHints`（可选）：执行提示，如是否跳过快照、是否仅分析、不写补丁、选择包。
+- `StepsOverride`（可选）：覆盖默认执行步骤的命令或动作（如自定义 diff 命令）。
+
+## 示例（Markdown 请求）
+
+```
+# Task
+Auto Test (diff-with-develop)
+
+# Parameters
+sinceBranch: develop
+project: ''
+mode: full
+noSnapshot: false
+onlyNew: false
+reportFormat: md
+
+# ExecutionHints
+- skipWrite: false
+- stopOnError: true
+
+# StepsOverride
+- git fetch --all --prune
+- git diff --name-status --diff-filter=AMR develop...HEAD
+- rush run -s test
+- rush run -s test-cov
+```
+
+## 使用方式
+
+- 推荐入口文件：`.trae/jobs/auto-test.md`（已提供，含参数、步骤、人工覆写与成功标准）
+- 最简用法（默认参数）：在聊天中发起“执行 Auto Test Job（.trae/jobs/auto-test.md）”。
+- 可选覆盖参数：`project=@visactor/vchart-theme`、`reportFormat=json`、`replaceAutogen=true` 等。
+- 我将按 `.trae/jobs/auto-test.md` 的步骤顺序执行：采集差异、分析缺口、生成/更新测试（含函数级注释）、运行覆盖率、生成报告、插入人工节点。
+
+## 结果与报告
+
+- 报告以 `reportFormat` 指定（`md` 或 `json`）。
+- 默认临时报告写入 `./.trae/output/autotest.report.local.md`（可通过 `tempReportPath` 覆盖）。
+- 我会附带执行日志摘要、受影响包、生成/跳过的测试、覆盖率与人工节点清单。
+
+## 旧方案清理
+
+- 旧的“工作流模版”文件与文档已移除：
+  - `.trae/workflows/autotest.diff-with-develop.json`
+  - `docs/autotest-workflow.md`
+- 现仅保留 Job 文件方案（`.trae/jobs/auto-test.md`）。
+
+## 默认参数（参考）
+
+- `sinceBranch=develop`
+- `project=auto`（自动按 diff 识别变更包）
+- `mode=full`
+- `noSnapshot=false`
+- `onlyNew=false`
+- `reportFormat=md`
+- `applyManualOverrides=true`
+- `replaceAutogen=false`
+- `dryRun=false`
+- `preview=false`
+- `stopOnError=true`
+- `focusChangedOnly=false`
+- `snapshotStrategy=combined`
+- `tempReportPath=./.trae/output/autotest.report.local.md`
+- `mockDefaults: time=fixed(2020-01-01T00:00:00Z), random=seed(42)`

.trae/jobs/auto-flow.md

@@ -0,0 +1,95 @@
+---
+job: release-prep-pipeline
+intent: prepare-release
+version: v1
+domain: pipeline
+runner: trae-solo
+parameters:
+  baseBranch: develop
+  lang: zh
+  labels:
+    - changelog
+    - test
+  topic: ''
+  message: ''
+  bumpType: auto
+  notCommit: true
+  head: ''
+  mode: auto
+  commitBeforeFlow: true
+  commitAllowEmpty: false
+  pushAfterCommit: true
+  commitMessageStrategy: auto
+  enforceCommit: true
+  commitRetry: 1
+required_parameters: []
+outputs:
+  - autotest_report
+  - rush_change_entries
+  - pr_url
+success_criteria:
+  - flow_completed
+---
+
+# Auto Flow Job（分支 → 单测 → 变更日志 →PR 串行编排）
+
+## 参数检查
+
+- 分支参数 `head` 可选：若未提供，将通过 `git rev-parse --abbrev-ref HEAD` 推导当前分支
+- 建议提供 `topic` 以优化 PR 标题；未提供时将回退为当前分支名
+
+## 步骤
+
+1. 分支预检查
+
+- 运行 `git rev-parse --abbrev-ref HEAD` 获取当前分支作为 `head`
+- 确认当前分支不是 `main`/`develop`，且工作树状态符合提交规范
+- 人工检查点：如不在开发分支，请先自行创建并切换到正确分支
+
+  1.1 自动提交未提交变更（当 `commitBeforeFlow==true`）
+
+- 检查工作树：`git status --porcelain`
+- 若存在未提交变更：
+  - `git add --all`
+  - 生成提交信息（按 `commitMessageStrategy`）：
+    - `auto`：类型 `chore`；作用域为顶层或包名（如 `vchart`）；主题为 `sync changes before Auto Flow`
+    - 最终示例：`chore(vchart): sync changes before Auto Flow`
+  - 运行 `git commit {{#commitAllowEmpty}}--allow-empty{{/commitAllowEmpty}} -m "<auto_message>"`
+  - 若 `pushAfterCommit==true`：`git push -u origin {{head}}`
+  - 提交后校验（当 `enforceCommit==true`）：
+    - 运行 `git status --porcelain`，若非空则视为失败；进行最多 `commitRetry` 次重试（`git add --all && git commit -m '<auto_message>'`），仍失败则中止流程并提示处理
+- 若 `commitBeforeFlow==false` 且存在未提交变更：直接失败并提示先完成提交
+
+2. 运行差异驱动单测
+
+- 执行 Job：`.trae/jobs/auto-test.md`
+- 传参：`sinceBranch={{baseBranch}}`（其余沿用默认）
+- 接收输出：`autotest_report=.trae/output/autotest.report.local.md`
+- 人工检查点：打开临时报告，确认新增/更新测试与覆盖率
+
+3. 生成 Rush 变更日志
+
+- 执行 Job：`.trae/jobs/changelog-rush-smart.md`
+- 传参：`sinceBranch={{baseBranch}}`、`message={{message}}`、`bumpType={{bumpType}}`、`notCommit={{notCommit}}`
+- 接收输出：`rush_change_entries`
+- 人工检查点：检查 `common/changes/**` 条目与摘要
+
+4. 创建 PR
+
+- 执行 Job：`.trae/jobs/pr-create.md`
+- 传参：
+  - `base={{baseBranch}}`
+  - `head={{head}}`
+  - `title='[Auto] {{topic || head}}'`
+  - `lang={{lang}}`
+  - `labels={{labels}}`
+  - `message={{message}}`（用于正文摘要）
+  - `bumpType={{bumpType}}`
+  - `mode={{mode}}`（auto 优先 gh → token → 浏览器 URL）
+  - `commitBeforeCreate=false`（已在 1.1 阶段完成自动提交）
+- 接收输出：`pr_url`
+- 人工检查点：最终确认并提交
+
+5. 完成
+
+- 标记 `flow_completed`，返回 `autotest_report`、`rush_change_entries` 与 `pr_url`