diff --git a/.trae/documents/auto-flow.solo.md b/.trae/documents/auto-flow.solo.md deleted file mode 100644 index d0825567f1..0000000000 --- a/.trae/documents/auto-flow.solo.md +++ /dev/null @@ -1,34 +0,0 @@ -# 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，请人工完善后再创建 diff --git a/.trae/documents/auto-test.solo.md b/.trae/documents/auto-test.solo.md deleted file mode 100644 index 1508ed6f56..0000000000 --- a/.trae/documents/auto-test.solo.md +++ /dev/null @@ -1,60 +0,0 @@ -# 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 -s test` 与 `test-cov` -- TypeScript 诊断与覆盖率结果会写入临时报告以便复核 - -## 注意事项 -- 若差异范围为空，建议指定 `project` 以运行目标包测试 -- 对低覆盖模块，建议补充手动测试并复跑 Auto Test 以提升覆盖率 diff --git a/.trae/documents/changelog-rush-smart.solo.md b/.trae/documents/changelog-rush-smart.solo.md deleted file mode 100644 index 6d6819b84e..0000000000 --- a/.trae/documents/changelog-rush-smart.solo.md +++ /dev/null @@ -1,24 +0,0 @@ -# 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` diff --git a/.trae/documents/create-branch.solo.md b/.trae/documents/create-branch.solo.md deleted file mode 100644 index 2e1f20ac18..0000000000 --- a/.trae/documents/create-branch.solo.md +++ /dev/null @@ -1,20 +0,0 @@ -# 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` 确认当前分支与工作树状态 diff --git a/.trae/documents/pr-create.solo.md b/.trae/documents/pr-create.solo.md deleted file mode 100644 index d3e0f8c9ef..0000000000 --- a/.trae/documents/pr-create.solo.md +++ /dev/null @@ -1,52 +0,0 @@ -# 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 摘要是否完整 diff --git a/.trae/jobs/README.md b/.trae/jobs/README.md deleted file mode 100644 index 3eef56aedd..0000000000 --- a/.trae/jobs/README.md +++ /dev/null @@ -1,80 +0,0 @@ -# 通过说明文件驱动执行 - -## 目的 - -- 不依赖“工作流模版”概念，仅在仓库中放置一个说明文件，描述任务与参数；我将按说明执行并回传报告。 - -## 放置位置 - -- 目录：`.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)` diff --git a/.trae/jobs/auto-flow.md b/.trae/jobs/auto-flow.md deleted file mode 100644 index 015eb762bf..0000000000 --- a/.trae/jobs/auto-flow.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -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 ""` - - 若 `pushAfterCommit==true`：`git push -u origin {{head}}` - - 提交后校验（当 `enforceCommit==true`）： - - 运行 `git status --porcelain`，若非空则视为失败；进行最多 `commitRetry` 次重试（`git add --all && git commit -m ''`），仍失败则中止流程并提示处理 -- 若 `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` diff --git a/.trae/jobs/auto-test.md b/.trae/jobs/auto-test.md deleted file mode 100644 index 4d556199ee..0000000000 --- a/.trae/jobs/auto-test.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -job: unit-test-autogen -intent: generate-unit-tests-from-diff -version: v1 -domain: testing -runner: trae-solo -parameters: - sinceBranch: develop - project: auto - mode: full - noSnapshot: false - onlyNew: false - reportFormat: md - applyManualOverrides: true - replaceAutogen: true - 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) -constraints: - framework: jest-ts-jest - layout: __tests__/*.test.ts - comments: function-level-jsdoc -outputs: - - test_files - - snapshots - - coverage_report - - manual_nodes - - temp_markdown_report -success_criteria: - - tests_generated_for_changed_exports - - compile_without_errors - - coverage_increase_or_maintained -manual_overrides: [] ---- - -# Auto Test Job（差异驱动单元测试自动生成） - -## 步骤 - -1. 差异采集 - -- 运行 `git fetch --all --prune` -- 运行 `git diff --name-status --diff-filter=AMR {{sinceBranch}}...HEAD` -- 对每个变更文件，运行 `git diff --unified=0 {{sinceBranch}}...HEAD ` 获取行级差异 - -2. 影响分析 - -- 识别导出符号、类型签名与逻辑分支；在包内搜索已有 `__tests__` 及缺口 - -3. 测试生成 - -- 在 `__tests__` 下创建或更新 `.test.ts` 文件；为每个 `describe/it` 添加函数级注释（JSDoc，说明目的、前置/输入、断言点） -- 策略： - - 纯函数/工具：正常/边界/异常分支 - - 主题 JSON：`toMatchSnapshot()` + 关键字段断言（颜色、字体、间距） - - 转换器：代表性输入，断言输出结构与关键键值；必要时增量快照 -- Mock/Spy：固定时间与随机数；隔离外部依赖（网络/FS） -- 自动化区块命名规则： - - `describe('autogen:/::')` - - `it('autogen::')` - -4. 放置与命名 - -- `src/foo.ts` → `__tests__/foo.test.ts`；若已有则增量插入新的自动化区块 -- 导入路径优先使用公开 API（例如 `src/index.ts`） - -5. 执行与覆盖率 - -- 若指定 `project`：`rush run -p {{project}} -s test` 与 `test-cov` -- 未指定则按变更包批量执行上述命令 - -6. 诊断与报告 - -- TypeScript 诊断：收集编译错误并在报告中标注阻断项 -- 报告输出（`{{reportFormat}}`）：列出变更文件 → 新增/更新测试 → 通过/失败 → 覆盖率增量 → 人工节点清单 -- 临时报告写入：将本次执行结果以 Markdown 形式写入 `{{tempReportPath}}` - - - 必含内容： - - 变更摘要（文件列表与关键行级片段定位） - - 新增/更新测试用例与断言点说明 - - 运行结果（套件/用例通过统计、覆盖率摘要、TS 诊断） - - 重点一致性问题与潜在错误点（类型/注释一致性、契约风险、默认值依赖、测试桩稳定性） - - 建议与后续动作（文档补充、契约确认、健壮性增强） - - 示例结构： - - ```md - # Autotest 临时报告 - - ## 变更摘要 - - ## 行级差异（关键片段） - - ## 新增/更新的测试 - - ## 运行结果 - - ## 一致性与潜在风险（重点） - - ## 建议与后续动作 - ``` - -7. 人工节点与二次执行 - -- 初次生成时对不明确 Mock/快照的用例插入占位并标记：`it('autogen:MANUAL_REQUIRED:')` 与 `test.skip(...)` -- 二次执行流程： - - 在本文件 `manual_overrides` 段中添加结构化覆写策略（见下例）或直接编辑测试文件中的占位并移除 `skip` - - 默认不覆盖人工命名块（不含 `autogen:` 前缀）；仅增量生成缺失的自动化区块 - - 若 `replaceAutogen=true`，允许替换已有 `autogen:` 区块 - -## manual_overrides 示例 - -```yaml -manual_overrides: - - target: packages/vchart-theme/src/foo.ts#exportedFn - mocks: - date: fixed(2020-01-01T00:00:00Z) - random: seed(42) - external: "jest.mock('@pkg/bar', () => ({ /* ... */ }))" - inputs: - - { args: [1, 2], desc: '正常路径' } - - { args: [null], desc: '异常路径' } - asserts: - - { expect: 'toEqual', value: { ok: true } } -``` - -## 执行（Solo 模式） - -- 最简用法（使用默认参数）：在聊天中发起“执行 Auto Test Job（.trae/jobs/auto-test.md）”。 -- 可选覆盖参数示例：`project=@visactor/vchart-theme`、`reportFormat=json`、`replaceAutogen=true`。 -- 我将按上述步骤顺序执行，并返回报告与人工节点处理结果。 -- 临时报告路径可通过 `tempReportPath` 覆盖，默认：`.trae/output/autotest.report.local.md`。 diff --git a/.trae/jobs/changelog-rush-smart.md b/.trae/jobs/changelog-rush-smart.md deleted file mode 100644 index fbbde29082..0000000000 --- a/.trae/jobs/changelog-rush-smart.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -job: generate-rush-changes-smart -intent: rush-change-smart -version: v1 -domain: release -runner: trae-solo -parameters: - sinceBranch: develop - message: '' - bumpType: auto - notCommit: true - githubToken: '' -required_parameters: [] -outputs: - - rush_change_entries - - computed_bump_type - - final_message -success_criteria: - - rush_changes_generated - - commitlint_passed -manual_overrides: [] ---- - -# Changelog Job（智能 Rush 变更日志生成） - -## 参数检查 - -- 无必填参数，均有默认值 -- 如需“关联 Issue 标题”自动聚合，请提供 `githubToken` - -## 步骤 - -1. 采集差异与提交 - -- 运行 `git diff --name-only {{sinceBranch}}...HEAD`，按文件路径映射到变更包 -- 运行 `git log --pretty=%H:::%s {{sinceBranch}}...HEAD`，收集提交主题 - -2. 自动判定 bumpType（可被参数覆盖） - -- 规则： - - 含 `BREAKING CHANGE` 或 `!` → `major` - - 含 `feat` → `minor` - - 其余（`fix|perf|refactor|docs|chore|test`）→ `patch` -- 若 `parameters.bumpType != auto`，则使用显式值 -- 将结果写入输出：`computed_bump_type` - -3. 构建富消息（可被参数覆盖） - -- 若 `parameters.message` 为空： - - 提取关键提交的主题（优先 `feat`/`fix`）形成“提交概览” - - 从提交中解析 `#`，调用 GitHub API 读取 Issue 标题（需 `githubToken`），形成“关联 Issue” - - 构建最终消息：首行摘要 + 提交概览 + 关联 Issue + 影响包 -- 将最终消息写入输出：`final_message` - -4. 提交信息校验 - -- 使用 `common/autoinstallers/lint/commitlint.config.js` 与本地 `commitlint` 执行校验 -- 命令：`echo "{{final_message}}" | commitlint --config common/autoinstallers/lint/commitlint.config.js` - -5. 生成 Rush 变更条目 - -- 执行 `rush change --bulk --bump-type '{{computed_bump_type}}' --message '{{final_message}}'` -- 输出文件位于 `common/changes/**`，收集为 `rush_change_entries` - -6. 可选提交 - -- 若 `notCommit != true`： - - 运行 `git add --all` - - 运行 `git commit -m 'docs: update changlog of rush'` - -7. 人工检查点 - -- 展示 `rush_change_entries`：路径、包名、bumpType、摘要 -- 如摘要需细化，编辑 `parameters.message` 或在二次执行中通过 `manual_overrides` 指定 - -## manual_overrides 示例 - -```yaml -manual_overrides: - - bumpType: minor - message: 'feat(core): 新增交互缩放配置，修复事件抛出问题 (#123)' -``` diff --git a/.trae/jobs/create-branch.md b/.trae/jobs/create-branch.md deleted file mode 100644 index 7fc334ff4c..0000000000 --- a/.trae/jobs/create-branch.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -job: create-dev-branch -intent: gitflow-create-branch -version: v1 -domain: git -runner: trae-solo -parameters: - baseBranch: develop - branchPrefix: chore/trae - topic: '' - useDateSuffix: true -required_parameters: - - topic -outputs: - - branch_name -success_criteria: - - branch_created - - clean_working_tree ---- - -# Create Branch Job（创建开发分支） - -## 参数检查 - -- 必填参数：`topic` -- 若未提供：请在执行入口中补充 `topic`（示例：`topic: perf-legend-opt`），再继续后续步骤。 - -## 步骤 - -1. 同步基础分支 - -- 运行 `git fetch --all --prune` -- 运行 `git checkout {{baseBranch}} && git pull origin {{baseBranch}}` - -2. 生成分支名 - -- 命名规则：`{{branchPrefix}}-{{topic}}-{{YYYYMMDD-HHMM}}` -- 将生成的分支名写入输出：`branch_name` - -3. 创建分支 - -- 运行 `git checkout -b {{branch_name}}` - -4. 人工检查点 - -- 运行 `git status` 并确认： - - 当前分支为 `{{branch_name}}` - - 工作树干净或仅包含预期改动 - -## 结果 - -- 成功则输出 `branch_name`，并保证后续任务在该分支上执行。 diff --git a/.trae/jobs/pr-create.md b/.trae/jobs/pr-create.md deleted file mode 100644 index 5843884e99..0000000000 --- a/.trae/jobs/pr-create.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -job: create-pr -intent: github-pr -version: v1 -domain: github -runner: trae-solo -parameters: - base: develop - head: '' - title: '' - lang: zh - labels: [] - draft: false - useGhCli: true - mode: auto # auto|gh|rest|browser - localBodyFile: false - openBrowser: true - commitBeforeCreate: false - commitMessage: '' - commitAllowEmpty: false - pushAfterCommit: true - commitMessageStrategy: auto # auto|topic|manual -required_parameters: - - title -inputs: - autotestReport: .trae/output/autotest.report.local.md - rushChangesDir: common/changes - bumpType: '' - message: '' -outputs: - - pr_url - - compare_url - - generated_title - - generated_body_preview -success_criteria: - - pr_created ---- - -# PR Job（根据模版创建 Pull Request） - -## 参数检查 - -- 必填参数：`title` -- 分支参数 `head` 可选：若未提供，将在执行阶段通过 `git rev-parse --abbrev-ref HEAD` 推导当前分支 - -## 步骤 - -1. 提交未提交的变更并推送（可选） - -- 获取 `head`：若未提供，通过 `git rev-parse --abbrev-ref HEAD` 推导 -- 检查工作树：`git status --porcelain` -- 若存在未提交变更且 `commitBeforeCreate == true`： - - 运行 `git add --all` - - 生成提交信息（按 `commitMessageStrategy`）： - - `auto`： - - 类型判定：包含 `docs/` → `docs`；包含 `__tests__`/`*.test.*` → `test`；否则 → `chore` - - 作用域：变更路径为 `packages//...` 时取 ``；否则取顶层目录（如 `docs`、`tools`、`common`、`.trae`） - - 主题：若提供 `message` 则使用其首行摘要；否则生成 `sync changes before PR ( files)` 并附加关键作用域 - - 结果示例：`chore(vchart,tools): sync changes before PR (5 files)` - - `topic`：使用 `title` 或外层 `topic` 作为主题，类型与作用域同上 - - `manual`：使用显式 `commitMessage` - - 运行 `git commit {{#commitAllowEmpty}}--allow-empty{{/commitAllowEmpty}} -m "{{}}"` - - 若 `pushAfterCommit == true`：运行 `git push -u origin {{head}}` -- 人工检查点： - - 若存在未提交变更但未开启自动提交，请先人工完成提交与推送再继续创建 PR - -2. 选择 PR 模版 - -- 当 `{{lang}} == zh`：使用 `.github/PULL_REQUEST_TEMPLATE/pr_cn.md` -- 否则使用 `.github/PULL_REQUEST_TEMPLATE.md` - -3. 准备正文 - -- 若已提供完整 `message`（摘要）与必要信息（关联链接等），可直接使用作为 PR body -- 若需要补充人工内容：提示用户完善 body 文本后再继续（不生成临时文件） - -- 生成可复制内容： -- `generated_title = [Auto] {{title || (topic || head)}}` -- 生成完整 PR 正文预览（Markdown 代码块），基于 `.github/PULL_REQUEST_TEMPLATE/pr_cn.md` 自动填充： - - 勾选项：`{{branch_type_checks}}`（如：新功能、Workflow 等） - - 关联：`{{issue_links}}`、`{{related_pr_links}}`、`{{bugserver_ids}}` - - 背景与方案：`{{background_solution}}`（从 `message` 与上下文生成） - - Changelog 表：`{{changelog_en}}` 与 `{{changelog_zh}}`（解析 `common/changes/**`） - - 自测勾选项：`{{self_check_items}}` - - Summary 与 Walkthrough：`{{summary_text}}`、`{{walkthrough_text}}`（包含分支、模板来源、测试摘要） -- 代码块示例结构： - - ```markdown - ### 🤔 这个分支是... - - - [x] 新功能 - - [x] Workflow - - ### 🔗 相关 issue 链接 - - {{issue_links}} - - ### 🔗 相关的 PR 链接 - - {{related_pr_links}} - - ### 🐞 Bugserver 用例 id - - {{bugserver_ids}} - - ### 💡 问题的背景&解决方案 - - {{background_solution}} - - ### 📝 Changelog - - | Language | Changelog | - | ---------- | ---------------- | - | 🇺🇸 English | {{changelog_en}} | - | 🇨🇳 Chinese | {{changelog_zh}} | - - ### ☑️ 自测 - - {{self_check_items}} - - --- - - ### 🚀 Summary - - {{summary_text}} - - ### 🔍 Walkthrough - - {{walkthrough_text}} - ``` - -- 若 `localBodyFile=true`：以完整代码块形式写入 `./.trae/output/pr.body.local.md`（被忽略提交） - -4. 人工检查点 - -- 若 body 需要补充，请人工完成后继续（不生成临时文件） - -5. 创建 PR - -- 模式选择： - - - `auto`：优先使用 `gh`（若已安装并登录）；其次使用 `GITHUB_TOKEN` 的 REST；最后提供浏览器 URL 手动创建 - - `gh`：使用 GitHub CLI 创建（需本机已登录） - - `rest`：使用 `GITHUB_TOKEN` 调用 REST API 创建 - - `browser`：生成 compare URL，打开浏览器页面手动确认 - -- 检测与执行： - - 若未提供 `head`：先运行 `git rev-parse --abbrev-ref HEAD` 以推导当前分支 - - 检测 `gh`：`command -v gh` 成功则执行： - - `gh pr create --base {{base}} --title "{{title}}" --body "{{message}}" --head {{head}} {{#labels}}--label {{labels}}{{/labels}} {{#draft}}--draft{{/draft}}` - - 若无 `gh` 而存在 `GITHUB_TOKEN`：使用 REST API `POST /repos/{owner}/{repo}/pulls`，body 使用 `{{message}}` - - 否则生成 compare URL： - - `compare_url = https://github.com/VisActor/VChart/compare/{{base}}...{{head}}?expand=1` - - 输出 `generated_title` 与以完整 Markdown 代码块格式的 `generated_body_preview`，便于直接复制到 PR 页面；若 `openBrowser=true` 在 macOS 运行 `open {{compare_url}}` - -6. 结果 - -- 返回 `pr_url`，并在成功标准中标记为 `pr_created` -- 在 `browser` 模式：返回 `compare_url`、`generated_title` 与完整的 `generated_body_preview` - （其中 `generated_body_preview` 为包含所有模板栏目且已自动填充的 Markdown 代码块） - -## 额外提示 - -- 自动创建 PR 有三种方式： - - 本机已登录 `gh`：无需额外令牌（SSH 仅用于 git 操作，API 权限由 `gh` 登录提供） - - 本机无 `gh`：提供 `GITHUB_TOKEN` 用 REST API 创建 - - 两者都不可用：生成 compare URL，使用浏览器登录后手动创建 diff --git a/.trae/skills/auto-flow/SKILL.md b/.trae/skills/auto-flow/SKILL.md new file mode 100755 index 0000000000..ff8661260f --- /dev/null +++ b/.trae/skills/auto-flow/SKILL.md @@ -0,0 +1,132 @@ +--- +name: auto-flow +description: 'Orchestrates a complete, standardized workflow for preparing a pull request in the VChart project. Use this skill to run a sequence of tasks: automated testing, changelog generation, smart commit, PR body creation, and PR submission. It provides a fixed 5-step process with manual checkpoints, ensuring quality and consistency for every contribution.' +--- + +# PR 准备全流程编排 (auto-flow) + +## 概述 + +本技能是一个固定的五步编排工作流，旨在自动化 `VChart` 项目从代码变更到创建 Pull Request 的整个准备过程。它将一系列独立的子技能（测试、变更日志、提交、PR 内容生成、PR 创建）串联成一个连贯的、带有人工检查点的流程。 + +## 前置条件 + +- **环境**: 必须在配置了 Rush、Git 的有效工作区中执行。 +- **依赖与凭证**: 所有被编排的子技能所需的前置条件都必须满足，特别是 `pr-create-from-body` 技能需要的 `GITHUB_TOKEN` 或 `gh` CLI。 + +## 输入参数 + +本技能的流程是固定的，不通过参数选择执行步骤。它会按顺序执行所有五个步骤。 + +| 参数 | 类型 | 是否必填 | 默认值 | 描述 | +| ------------- | ------- | -------- | ------------ | -------------------------------------------------------------------- | +| `baseBranch` | string | 否 | `develop` | 整个流程所围绕的基准分支，用于差异计算和 PR 目标。 | +| `topic` | string | 否 | (空) | 用于优化 PR 标题的可选主题。 | +| `message` | string | 否 | (空) | 用于 `changelog` 和 `commit` 的自定义消息。 | +| `bumpType` | string | 否 | `auto` | Rush 变更日志的版本升级类型。 | +| `head` | string | 否 | (空) | 当前开发分支。如果为空，将自动推导。 | +| `labels` | array | 否 | `[changelog, test]` | 附加到最终 PR 的标签。 | + +## 输出与成功标准 + +- **主要输出**: + - `autotest_report`: 单元测试报告文件路径。 + - `rush_change_entries`: 生成的 Rush 变更条目列表。 + - `commit_message`: 创建的提交信息。 + - `pr_url`: 最终创建的 Pull Request 链接。 +- **成功标准**: + - `flow_step_completed`: 流程中的每一步或整个流程已成功完成。 + +## 执行步骤 + +本技能按固定顺序依次执行以下子技能，并在每一步之间设置人工检查点： + +1. **差异驱动单测** + - **执行**: `auto-test` 技能。 + - **目的**: 为代码变更生成并运行单元测试。 + - **报告输出**: 默认总是将报告写入 `./.trae/output/autotest.report.local.md`（即 `auto-test` 的 `tempReportPath`），即便本次没有生成新的测试用例也会包含“无新增自动化测试 (No new tests generated)”等说明。 + - **检查点**: Agent 会返回测试报告路径。**你需要检查报告中的测试覆盖率和结果，确认无误后指示 Agent 继续。** + +2. **生成 Rush 变更日志** + - **执行**: `changelog-rush-smart` 技能。 + - **目的**: 根据提交历史创建 `common/changes/**` 下的变更条目。 + - **检查点**: Agent 会提示已生成变更条目。**你需要检查这些文件的内容是否准确反映了你的变更，然后指示 Agent 继续。** + +3. **智能提交** + - **执行**: `commit-smart` 技能。 + - **目的**: 将所有变更（代码、测试、changelog 文件）创建一个符合规范的 Git 提交并推送到远程。 + - **检查点**: Agent 会返回生成的提交信息和推送结果。**你需要确认提交信息是正确的，然后指示 Agent 继续。** + +4. **生成 PR 正文** + - **执行**: `pr-body-generate` 技能。 + - **目的**: 自动填充 PR 模板，生成包含所有上下文信息的 PR 正文。 + - **输入输出约定**: 默认会从 `./.trae/output/autotest.report.local.md` 读取 auto-test 生成的报告摘要，并将生成的正文写入 `./.trae/output/pr.body.local.md`。即使缺少 changelog 或自动化测试报告，也会生成一个结构完整的最小正文，并在相应小节中标注“暂无 changelog”或“尚未提供自动化测试报告”等说明。 + - **检查点**: Agent 会返回生成的 PR 正文预览和本地文件路径。**你应审阅正文内容，确保其完整和准确（可在此步之后手动修改文件），然后指示 Agent 继续。** + +5. **创建 PR** + - **执行**: `pr-create-from-body` 技能。 + - **目的**: 使用上一步生成的正文文件，在 GitHub 上创建 Pull Request。 + - **执行方式**: 在默认的 `mode: auto` 下，技能会优先尝试使用本机已登录的 `gh` CLI 创建 PR；仅当 `gh` 不可用时，才会回退到使用 `GITHUB_TOKEN` 的 REST API。 + - **检查点**: Agent 会返回最终的 PR 链接。**你需要访问链接确认 PR 是否按预期创建。** + +## Quick Fixes（PR 创建失败时） + +在第 5 步调用 `pr-create-from-body` 时，如果因为 GitHub 认证问题导致 PR 创建失败，可以快速尝试以下两条“人工兜底”路径： + +### 路径一：使用 gh CLI 直接创建 PR（推荐） + +```bash +# 1. 通过 gh 登录 GitHub（如尚未登录） +gh auth login + +# 2. 在 VChart 仓库根目录，使用本地正文文件创建 PR +gh pr create \ + -B develop \ + -H \ + -t "" \ + -F ./.trae/output/pr.body.local.md \ + --label changelog \ + --label test +``` + +### 路径二：使用 GITHUB_TOKEN + REST API + +```bash +export GITHUB_TOKEN="your_token_here" + +curl -X POST \ + -H "Authorization: Bearer $GITHUB_TOKEN" \ + -H "Accept: application/vnd.github+json" \ + https://api.github.com/repos/VisActor/VChart/pulls \ + -d '{ + "title": "", + "head": "", + "base": "develop", + "body": "从 .trae/output/pr.body.local.md 复制正文内容到此处，或改用 pr-create-from-body(mode: rest) 自动填充" + }' +``` + +> 提醒：在正常情况下，`auto-flow` 的第 5 步会通过 `pr-create-from-body` 以 `mode: auto` 方式优先使用 `gh` 创建 PR，仅在 `gh` 不可用时回退到 REST（`GITHUB_TOKEN`）。上述命令仅作为认证异常时的应急方案。 + +## 何时使用 / 边界 + +- **使用时机**: + - 当你完成一个功能或修复，准备发起一个完整的、高质量的 Pull Request 时，这是推荐的标准化流程。 + - 特别适用于发布前准备工作，确保所有检查项（测试、changelog）都已完成。 +- **边界**: + - 此技能是一个编排层，它不执行实际工作，而是调用其他技能。因此，它的成功依赖于所有子技能的正确配置和执行。 + - 流程中的任何一步失败，整个流程都会中断，并报告失败的步骤和原因。 + +## 使用示例 + +> **你**: “启动 `auto-flow` 流程，为我的新功能做发布准备。” +> +> **Agent**: *(执行 `auto-test`)* “第一步：测试已完成，报告位于 `.../autotest.report.local.md`。请检查后告诉我是否继续。” +> +> **你**: *(检查报告后)* “继续。” +> +> **Agent**: *(执行 `changelog-rush-smart`)* “第二步：变更日志已生成。请检查 `common/changes/` 目录。确认无误后，请告诉我是否继续。” +> +> **你**: “继续。” +> +> **Agent**: *(继续执行后续步骤，并在每一步后请求确认)* diff --git a/.trae/skills/auto-flow/docs/USAGE.md b/.trae/skills/auto-flow/docs/USAGE.md new file mode 100755 index 0000000000..6fdeb0e7bf --- /dev/null +++ b/.trae/skills/auto-flow/docs/USAGE.md @@ -0,0 +1,90 @@ +# 使用说明：auto-flow + +本技能将创建 Pull Request 的所有准备工作（测试、变更日志、提交、生成正文、创建 PR）串联成一个标准化的五步流程。 + +## 何时使用 + +- **发布准备**: 当你完成一个功能或修复，准备发起一个完整的、高质量的 Pull Request 时，使用此技能可以确保所有检查项都已完成。 +- **标准化贡献**: 团队成员可以使用此流程来确保所有贡献都遵循相同的质量标准。 + +## 流程与人工检查点 + +本技能是一个带有“门禁”的流水线，每一步完成后都会暂停，等待你的确认： + +1. **自动测试**: 技能首先为你的代码变更生成并运行测试，并将结果写入 `./.trae/output/autotest.report.local.md`（即使没有新增测试也会包含“无新增自动化测试 (No new tests generated)” 说明）。 + * **你需要**: 打开该报告，检查覆盖率和测试结果是否符合预期。 + +2. **生成变更日志**: 接着，它会为你的提交创建 `changelog` 文件。 + * **你需要**: 检查 `common/changes/` 目录下生成的文件内容是否准确。 + +3. **智能提交**: 然后，所有变更会被打包成一个规范的 Git 提交并推送。 + * **你需要**: 确认自动生成的提交信息是正确的。 + +4. **生成 PR 正文**: 技能会自动填充 PR 模板，从 `./.trae/output/autotest.report.local.md` 和 `common/changes` 中汇总信息，并将正文写入 `./.trae/output/pr.body.local.md`。 + * **你需要**: 审阅生成的 PR 正文，可选择在本地修改 `.md` 文件。 + +5. **创建 PR**: 最后，使用准备好的正文创建 PR。 + * **你需要**: 访问返回的 PR 链接，做最终确认；如失败，优先检查 `gh auth status`、`git remote -v` 与 `GITHUB_TOKEN` 配置是否正确。 + +## 示例对话 + +> **你**: “启动 `auto-flow` 流程，为我的新功能做发布准备。” +> +> **Agent**: (执行第一步) “第一步：测试已完成，报告位于 `.../autotest.report.local.md`。请检查后告诉我是否继续。” +> +> **你**: (检查后) “继续。” +> +> **Agent**: (执行第二步) “第二步：变更日志已生成。请检查 `common/changes/` 目录。确认无误后，请告诉我是否继续。” +> +> **你**: “继续。” +> +> *... (Agent 会继续执行后续步骤，并在每一步后请求确认)* + +## 关键参数 + +- `baseBranch`: PR 的目标分支，默认为 `develop`。 +- `topic`: 用于生成 PR 标题，建议提供。 +- `message`: 用于 `changelog` 和 `commit` 的自定义消息。 + +## 注意事项 + +- **凭证**: 确保 `gh` CLI 已安装并通过 `gh auth status` 登录成功；同时建议配置好 `GITHUB_TOKEN` 作为备用。`pr-create-from-body` 在 `mode: auto` 下会优先使用 `gh` 创建 PR，`gh` 不可用时才回退到 REST。 +- **顺序固定**: 本技能的五个步骤是固定的，不能跳过或重排。 +- **失败中断**: 流程中任何一步失败都会导致整个流程中断。 + +## Quick Fixes（PR 创建失败时） + +当流程执行到第 5 步“创建 PR”时，如果因为权限或认证问题导致失败，可以直接在终端执行以下命令完成创建： + +### 路径一：gh CLI + +```bash +gh auth login + +gh pr create \ + -B develop \ + -H \ + -t "" \ + -F ./.trae/output/pr.body.local.md \ + --label changelog \ + --label test +``` + +### 路径二：GITHUB_TOKEN + REST + +```bash +export GITHUB_TOKEN="your_token_here" + +curl -X POST \ + -H "Authorization: Bearer $GITHUB_TOKEN" \ + -H "Accept: application/vnd.github+json" \ + https://api.github.com/repos/VisActor/VChart/pulls \ + -d '{ + "title": "", + "head": "", + "base": "develop", + "body": "从 .trae/output/pr.body.local.md 复制正文内容到此处，或改用 pr-create-from-body(mode: rest) 自动填充" + }' +``` + +> 自动流程中 `pr-create-from-body` 默认使用 `mode: auto`，即“gh 优先，其次 REST”。Quick Fixes 主要用于你需要手动接管 PR 创建时的快速路径。 diff --git a/.trae/skills/auto-test/SKILL.md b/.trae/skills/auto-test/SKILL.md new file mode 100755 index 0000000000..49a7d2532a --- /dev/null +++ b/.trae/skills/auto-test/SKILL.md @@ -0,0 +1,116 @@ +--- +name: auto-test +description: 'Automates unit testing for incremental code changes in the VChart project. Use this skill to automatically generate and run tests for your modifications against a base branch (default: develop). It identifies changes, creates/updates Jest test cases and snapshots, and provides a coverage report. This skill requires a functional Rush and Git environment.' +--- + +# 差异驱动的单元测试 (auto-test) + +## 概述 + +本技能用于对 `VChart` 项目中指定基准分支与当前 `HEAD` 之间的代码差异，自动生成、更新和执行单元测试。它能够处理已提交和未提交的变更，并生成一份详细的测试报告。 + +## 前置条件 + +- **环境**: 必须在配置了 Rush 和 Git 的有效工作区中执行。 +- **GitHub 凭证 (可选)**: 某些高级功能可能需要有效的 `GITHUB_TOKEN` 或已登录的 `gh` CLI。 + +## 输入参数 + +| 参数 | 类型 | 默认值 | 描述 | +| -------------------- | ------- | --------------------------------- | ---------------------------------------------------------- | +| `sinceBranch` | string | `develop` | 用于差异计算的基准分支。 | +| `project` | string | `auto` | 要测试的 Rush 项目，`auto` 表示自动识别变更所属的项目。 | +| `mode` | string | `full` | 测试模式。 | +| `noSnapshot` | boolean | `false` | 是否跳过快照测试。 | +| `reportFormat` | string | `md` | 生成报告的格式 (`md` 或 `json`)。 | +| `tempReportPath` | string | `.trae/output/autotest.report.local.md` | 临时报告的输出路径。 | +| `replaceAutogen` | boolean | `false` | 是否允许替换已有的 `autogen:` 测试块。 | +| `includeWorkingTree` | boolean | `true` | 是否包含工作树（未提交的）的变更。 | + +## 输出与成功标准 + +- **主要输出**: + - `test_files`: 生成或更新的测试文件列表。 + - `snapshots`: 生成或更新的快照文件。 + - `coverage_report`: 覆盖率报告摘要。 + - `manual_nodes`: 提示需要人工介入的测试点。 + - `temp_markdown_report`: 本地生成的 Markdown 格式临时报告，其路径通常与 `tempReportPath` 一致（默认 `./.trae/output/autotest.report.local.md`）。**无论本次是否实际生成了新的测试用例，此报告都会写入，用于解释执行结果。** +- **成功标准**: + - `tests_generated_for_changed_exports`: 已为所有变更的导出项生成测试。 + - `compile_without_errors`: 生成的测试代码编译无误。 + - `coverage_increase_or_maintained`: 代码覆盖率持平或有所提升。 + +## 执行步骤 + +1. **差异采集**: Agent 会使用 `git diff` 和 `git status` 命令，识别出从 `{{sinceBranch}}` 到当前 `HEAD` 的所有已提交和未提交的文件与代码行级变更。 +2. **影响分析**: 分析变更内容，识别出哪些导出函数、类型或逻辑分支受到了影响，并检查 `__tests__` 目录下是否存在对应的测试缺口。 +3. **测试生成**: + - 在受影响模块的 `__tests__` 目录下创建或更新测试文件 (`*.test.ts`)。 + - 为纯函数、UI 组件、工具函数等生成不同策略的测试用例，并附带说明性注释。 + - 对不确定的 Mock 或断言，会生成带 `test.skip` 和 `MANUAL_REQUIRED` 标记的占位符。 +4. **执行与覆盖率分析**: + - 根据 `project` 参数，运行 `rush run test` 和 `rush run test-cov` 命令。 + - 收集测试结果和覆盖率数据。 +5. **报告生成**: + - 将所有变更、测试生成情况、运行结果、覆盖率变化及潜在风险点汇总成一份报告，并保存到 `{{tempReportPath}}`（默认 `./.trae/output/autotest.report.local.md`）。 + - 报告结构至少包含：变更摘要、新增/更新测试列表、运行结果、覆盖率摘要（整体与关键文件）、覆盖率变化，以及风险与改进建议等板块。 + - **当本次执行没有生成任何新的自动化测试时，报告中必须包含一个明确的“无新增自动化测试 (No new tests generated)”小节，说明原因（例如仅文档变更、仅样式调整或变更被过滤等）以及当前测试覆盖情况。** + +## 命令示例（本地等价操作） + +如果需要在不依赖技能的情况下手动完成一次最小化的测试与覆盖率检查，可以在 VChart 仓库根目录执行： + +```bash +# 1. 运行单元测试 +rush run -p -s test + +# 2. 运行覆盖率 +rush run -p -s test-cov + +# 3. 将结果整理成临时报告（与 Skill 输出路径保持一致） +mkdir -p ./.trae/output +cat > ./.trae/output/autotest.report.local.md << 'EOF' +# Auto Test Report + +## Summary +- Project: +- Base: develop + +## Test Result +- Test Suites: ... +- Tests: ... + +## Coverage Summary +- Lines: ... +- Statements: ... +- Functions: ... +- Branches: ... + +## Notes +- No new tests generated +EOF +``` + +> 实际技能会根据差异自动生成/更新测试文件，并将完整报告写入 `tempReportPath`（默认 `./.trae/output/autotest.report.local.md`），包括“无新增自动化测试 (No new tests generated)” 小节。 + +## 覆盖率提升建议 + +在阅读 auto-test 报告中的覆盖率摘要时，如果发现新增或关键文件的覆盖率偏低，可以优先考虑补充如下类型的用例： + +- **边界场景**：空数据、单元素、大量数据、极端配置等； +- **错误与异常路径**：非法参数、抛错分支、网络/IO 失败等； +- **组合与分支**：不同配置组合、开关量 on/off、不同枚举值； +- **回滚与降级逻辑**：fallback 分支、默认值逻辑； +- **与外部依赖的交互**：mock 出第三方服务异常、超时或返回空结果。 + +你可以在补充这些用例后再次执行 `auto-test`，观察报告中覆盖率摘要与“风险与建议”板块是否有所改善。 + +## 何时使用 / 边界 + +- **使用时机**: + - 在完成一部分代码开发后，需要快速验证变更的正确性并补充单元测试时。 + - 在准备提交代码前，确保所有改动都被测试覆盖。 + - 作为持续集成流程的一部分，用于自动化回归测试。 +- **边界**: + - 此技能专注于单元测试，无法替代集成测试或端到端测试。 + - 对于复杂的业务逻辑或需要精细 Mock 的场景，生成的测试用例可能需要人工调整。 diff --git a/.trae/skills/auto-test/docs/USAGE.md b/.trae/skills/auto-test/docs/USAGE.md new file mode 100755 index 0000000000..41dafb53eb --- /dev/null +++ b/.trae/skills/auto-test/docs/USAGE.md @@ -0,0 +1,54 @@ +# 使用说明：auto-test + +本技能根据代码增量自动生成单元测试，确保变更得到充分验证。 + +## 何时使用 + +- **编码后**: 开发了新功能或修复了缺陷后，运行此技能可快速为你的变更生成测试用例。 +- **提交前**: 在 `git commit` 之前，使用此技能确保所有改动都已被测试覆盖，满足合入标准。 +- **CI/CD**: 可作为自动化流水线的一环，对每次提交进行回归测试。 + +## 示例对话 + +**场景一：对所有变更运行测试** + +> **你**: “帮我运行 `auto-test`，检查下我最近的改动。” +> +> **Agent**: (执行技能) “测试已完成，报告位于 `./.trae/output/autotest.report.local.md`。新增测试 `X` 个，覆盖率提升 `Y%`。请查阅报告确认。” + +**场景二：仅测试特定包** + +> **你**: “为 `@visactor/vchart` 项目执行 `auto-test`。” +> +> **Agent**: (将测试范围限定在指定包内执行) “已完成对 `@visactor/vchart` 的测试。报告已生成。” + +## 关键参数 + +- `sinceBranch`: 定义进行比较的基准分支，默认为 `develop`。 +- `project`: 指定要测试的 Rush 项目。`auto` 会自动识别变更影响的包；你也可以明确指定，如 `'@visactor/vchart'`。 +- `reportFormat`: 输出报告的格式，支持 `md` (默认) 和 `json`。 +- `tempReportPath`: 测试报告的本地输出路径，默认为 `./.trae/output/autotest.report.local.md`。 + +## 注意事项 + +- **此技能专注于单元测试，不能完全替代集成测试或端到端测试。** +- 自动生成的测试可能需要人工干预，特别是在涉及复杂模拟(Mock)或特定业务逻辑的场景中。 +- 执行前请确保 `rush` 依赖已正确安装。 +- 每次执行都会在 `tempReportPath`（默认 `./.trae/output/autotest.report.local.md`）写入一份临时报告；**即使没有生成新的测试用例，也会包含“无新增自动化测试 (No new tests generated)”说明小节，解释原因与执行结果。** + +## 命令示例（本地运行） + +```bash +# 在 VChart 仓库根目录，针对某个 Rush 项目运行测试与覆盖率 +rush run -p -s test +rush run -p -s test-cov +``` + +> 如需与技能保持一致，可以在测试完成后，把关键信息手动整理到 `./.trae/output/autotest.report.local.md` 中；技能会自动在相同路径生成报告。 + +## 覆盖率提升建议 + +- 优先补充边界场景（空数据、极大/极小值等）； +- 补足错误/异常路径（无效参数、抛错分支）； +- 覆盖重要配置组合和分支选择； +- 针对关键函数或模块查看报告中的覆盖率摘要，优先拉高这些热点文件的覆盖率。 diff --git a/.trae/skills/changelog-rush-smart/SKILL.md b/.trae/skills/changelog-rush-smart/SKILL.md new file mode 100755 index 0000000000..f195fed15f --- /dev/null +++ b/.trae/skills/changelog-rush-smart/SKILL.md @@ -0,0 +1,68 @@ +--- +name: changelog-rush-smart +description: 'Generates standardized changelog entries for a Rush-based monorepo like VChart. Use this skill to create changelog files based on Git commits since a base branch (default: develop). It intelligently determines the version bump type, aggregates commit messages, and can enrich them with linked GitHub issue titles if a GITHUB_TOKEN is provided.' +--- + +# 智能 Rush 变更日志 (changelog-rush-smart) + +## 概述 + +本技能依据自 `develop` 分支以来的 Git 提交历史，为 `VChart` 项目自动生成符合 Rush 规范的变更日志条目。它能智能地推断版本变更类型（major/minor/patch），并聚合提交信息来创建消息内容。 + +## 前置条件 + +- **Rush 环境**: 项目依赖 `rush` 已正确安装。 +- **GitHub Token (可选)**: 若想自动拉取并聚合关联 Issue 的标题，需在环境中配置 `GITHUB_TOKEN`。 + +## 输入参数 + +| 参数 | 类型 | 是否必填 | 默认值 | 描述 | +| ------------- | ------ | -------- | --------- | ---------------------------------------------------------- | +| `sinceBranch` | string | 否 | `develop` | 用于差异计算的基准分支。 | +| `bumpType` | string | 否 | `auto` | 版本变更类型 (`auto`, `major`, `minor`, `patch`)。`auto` 会根据提交信息自动推断。 | +| `message` | string | 否 | (空) | 手动指定的变更摘要。如果为空，将根据提交记录自动生成。 | +| `notCommit` | boolean| 否 | `true` | 是否在生成变更条目后自动执行 `git commit`。 | +| `githubToken` | string | 否 | (空) | 用于访问 GitHub API 以获取 Issue 标题的个人访问令牌。 | + +## 输出与成功标准 + +- **主要输出**: + - `rush_change_entries`: 生成的 Rush 变更条目文件路径列表（位于 `common/changes/**`）。 + - `computed_bump_type`: 最终采纳的版本变更类型。 + - `final_message`: 用于生成变更条目的最终消息文本。 +- **成功标准**: + - `rush_changes_generated`: 变更条目已成功生成。 + - `commitlint_passed`: 生成的消息摘要符合 `commitlint` 规范。 + +## 执行步骤 + +1. **采集差异与提交**: Agent 会收集从 `{{sinceBranch}}` 到 `HEAD` 的文件变更和提交记录。 +2. **判定版本变更类型 (`bumpType`)**: + - Agent 会分析提交信息中的关键字（如 `BREAKING CHANGE`, `feat`, `fix` 等）来自动判断版本变更级别。 + - 如果用户显式提供了 `bumpType` 参数，则优先使用用户指定的值。 +3. **构建变更消息**: + - 如果 `message` 参数为空，Agent 会智能地从提交历史中提取关键信息，并（在有 `githubToken` 的情况下）拉取关联 Issue 的标题，共同构成一条内容丰富的变更消息。 +4. **生成 Rush 变更条目**: + - Agent 会执行 `rush change` 命令，使用上一步确定的 `bumpType` 和消息，为每个受影响的包生成对应的变更文件。 +5. **（可选）提交变更**: 如果 `notCommit` 未设置为 `true`，Agent 会将新生成的变更文件添加到 Git 暂存区并创建一个提交。 + +## 命令示例（本地等价操作） + +在 VChart 仓库根目录，你可以用 `rush change --bulk` 近似完成此技能的核心步骤： + +```bash +# 基于 develop...HEAD 的变更，为所有受影响的包批量生成变更条目 +rush change --bulk +``` + +在运行前，建议先检查 `common/changes/**` 中是否已经存在覆盖当前提交集的条目；若已有合适的记录，可以跳过本次执行，避免重复生成。 + +## 何时使用 / 边界 + +- **使用时机**: + - 在完成一个或多个功能的开发、即将发起 Pull Request 之前，用于生成标准的 `changelog` 条目。 + - 当你需要遵循 `VChart` 项目的版本发布流程，为你的变更创建记录时。 +- **边界**: + - 此技能只负责生成 `common/changes/**` 下的变更文件，它本身不执行版本发布 (`rush publish`)。 + - 自动生成的消息质量依赖于良好、规范的 Git 提交历史。 + - 如果 `common/changes/**` 中已经存在覆盖当前提交集的条目，可以只复核既有文件，无需强行生成新的变更记录，以避免重复。 diff --git a/.trae/skills/changelog-rush-smart/docs/USAGE.md b/.trae/skills/changelog-rush-smart/docs/USAGE.md new file mode 100755 index 0000000000..6cd3fa15bb --- /dev/null +++ b/.trae/skills/changelog-rush-smart/docs/USAGE.md @@ -0,0 +1,45 @@ +# 使用说明：changelog-rush-smart + +本技能用于根据 Git 提交记录为 Rush monorepo 项目智能生成变更日志。 + +## 何时使用 + +- **PR 前**: 在发起 Pull Request 之前，使用此技能为你的变更生成标准的 `changelog` 条目。 +- **发布准备**: 作为 `auto-flow` 编排的一部分，在 `auto-test` 之后自动执行，确保版本历史的完整性。 + +## 示例对话 + +**场景一: 自动生成** + +> **你**: “请为我最近的提交生成 changelog。” +> +> **Agent**: (执行技能) “变更日志已生成。`bumpType` 被自动判断为 `patch`。文件已创建于 `common/changes/` 目录。” + +**场景二: 手动指定类型和消息** + +> **你**: “执行 `changelog-rush-smart`，`bumpType` 设为 `minor`，并使用消息 '新增图表系列，支持交互式图例'。” +> +> **Agent**: (使用指定参数执行) “好的，已使用 `minor` 类型和你的自定义消息生成了变更日志。” + +## 关键参数 + +- `sinceBranch`: 定义比较的基准分支，默认为 `develop`。 +- `bumpType`: 版本变更类型，可以是 `auto`, `major`, `minor`, `patch`。`auto` 会基于提交信息自动推断。 +- `message`: 手动指定的变更摘要。如果留空，将根据提交记录自动生成。 +- `githubToken`: （可选）提供 GitHub 个人访问令牌，以便自动拉取并聚合关联 Issue 的标题。 + +## 命令示例 + +```bash +# 在 VChart 仓库根目录，基于 develop...HEAD 的变更批量生成 changelog 条目 +rush change --bulk +``` + +在交互过程中选择合适的变更类型（major/minor/patch）并填写简明的 message，生成的文件会位于 `common/changes/**`。 + +## 注意事项 + +- 自动生成的消息质量高度依赖于规范、清晰的 Git 提交历史。 +- 本技能仅生成 `common/changes/**` 下的文件，不执行 `rush version` 或 `rush publish`。 +- 如果需要自动关联 Issue 标题，请确保 `GITHUB_TOKEN` 已在环境中正确配置。 +- 如果 `common/changes/**` 中已经存在覆盖当前提交的条目（例如之前已经为某次修复创建过记录），可以只复核这些文件，不必重复生成新的条目。 diff --git a/.trae/skills/commit-smart/SKILL.md b/.trae/skills/commit-smart/SKILL.md new file mode 100755 index 0000000000..f632223fbe --- /dev/null +++ b/.trae/skills/commit-smart/SKILL.md @@ -0,0 +1,75 @@ +--- +name: commit-smart +description: 'Creates a well-formed, intelligent Git commit for all pending changes in the VChart project. Use this skill to bundle your work into a single, clean commit that follows Conventional Commits standards. It automatically determines the commit type and scope, generates a message, and then performs the `git commit` and `git push`. Ideal for finalizing changes before creating a pull request.' +--- + +# 智能提交 (commit-smart) + +## 概述 + +本技能用于将当前工作树中所有未提交的变更（staged 和 unstaged）进行一次智能化的 Git 提交，并可选地推送到远程仓库。它会自动根据文件路径和 `common/changes` 目录下的内容生成符合 Conventional Commits 规范的提交信息。 + +## 前置条件 + +- **Git 环境**: 一个配置好的 Git 环境，且当前位于一个 Git 仓库目录中。 +- **远程分支**: 远程仓库需要存在与本地对应的分支，以便推送。 + +## 输入参数 + +| 参数 | 类型 | 是否必填 | 默认值 | 描述 | +| ----------------------- | ------- | -------- | ------ | -------------------------------------------------------------------- | +| `head` | string | 否 | (空) | 要推送的分支名。如果为空，将自动推导当前所在分支。 | +| `message` | string | 否 | (空) | 手动指定的提交信息。如果提供，将以此为基础生成最终提交。 | +| `commitMessageStrategy` | string | 否 | `auto` | 提交信息的生成策略，目前仅支持 `auto`。 | +| `pushAfterCommit` | boolean | 否 | `true` | 是否在提交后自动执行 `git push`。 | +| `commitAllowEmpty` | boolean | 否 | `false`| 是否允许在没有文件变更时创建一个空提交。 | + +## 输出与成功标准 + +- **主要输出**: + - `commit_message`: 最终生成的完整提交信息。 + - `pushed_branch`: 成功推送到的远程分支名。 +- **成功标准**: + - `commit_created_or_skipped`: 提交被成功创建；或者因为没有变更而安全地跳过。 + +## 执行步骤 + +1. **分支与状态检查**: + - Agent 首先会确定目标分支，如果 `head` 参数未提供，则自动获取当前分支名。 + - 接着，它会检查工作树的状态，如果没有任何变更且 `commitAllowEmpty` 为 `false`，则会跳过后续步骤。 + +2. **生成提交信息**: + - **类型(Type)**: Agent 会根据变更文件的路径（例如 `docs/` -> `docs`, `__tests__/` -> `test`）和 `common/changes/` 下的变更类型来推断。 + - **作用域(Scope)**: 根据文件所在的包（如 `packages/`）或顶层目录来确定。 + - **主题(Subject)**: 优先使用 `message` 参数的首行；如果 `message` 为空，则会尝试从 `common/changes/` 的最新条目中提取 `comment` 作为主题；如果两者都无，则生成一个通用主题，如 `sync changes before PR (N files)`。 + +3. **执行提交与推送**: + - Agent 会运行 `git add --all` 将所有变更添加到暂存区。 + - 然后使用生成的提交信息执行 `git commit`。 + - 如果 `pushAfterCommit` 为 `true`，它会接着执行 `git push -u origin {{head}}` 将提交推送到远程仓库。 + +## 安全命令示例（避免提交环境文档） + +为了避免将 `.trae/skills` 等环境/文档目录意外提交到远程，可以在使用本技能前或之后配合以下命令： + +```bash +# 查看当前暂存内容 +git status + +# 如果发现 .trae/skills 被错误地加入暂存区，可以将其移除： +git restore --staged .trae/skills + +# 如需手动提交时缩小范围，可使用路径前缀而不是 add --all： +git add packages/vchart src tests +``` + +> 提示：`commit-smart` 在内部会使用 `git add --all` 聚合变更，执行前请先用 `git status` 确认没有不希望提交的目录（如 `.trae/skills`），必要时可先执行 `git restore --staged .trae/skills` 清理暂存区。 + +## 何时使用 / 边界 + +- **使用时机**: + - 在执行了 `auto-test` 和 `changelog-rush-smart` 之后，需要将所有自动生成的文件和你的代码变更一起提交时。 + - 在准备发起 Pull Request 之前的最后一步，用于创建一个干净、规范的提交。 +- **边界**: + - 此技能会提交工作区中 **所有** 的变更，请在执行前确认没有不想被提交的文件。 + - 它不会处理 Git 冲突，执行前请确保分支是干净的。 diff --git a/.trae/skills/commit-smart/docs/USAGE.md b/.trae/skills/commit-smart/docs/USAGE.md new file mode 100755 index 0000000000..1f53c0ed95 --- /dev/null +++ b/.trae/skills/commit-smart/docs/USAGE.md @@ -0,0 +1,48 @@ +# 使用说明：commit-smart + +本技能用于将所有待处理的变更创建为一个符合规范的 Git 提交，并推送到远程仓库。 + +## 何时使用 + +- **PR 准备**: 在生成了测试和变更日志后，使用此技能将所有相关文件（源代码、测试文件、`changelog` 条目）捆绑成一个原子提交。 +- **快速同步**: 当你想快速将本地所有工作同步到远程分支时，此技能提供了一键式的 `add`, `commit`, 和 `push` 操作。 + +## 示例对话 + +**场景一: 自动提交** + +> **你**: “代码、测试和 changelog 都好了，帮我提交所有变更。” +> +> **Agent**: (执行技能) “好的。已生成提交信息 'feat(vchart): add new interactive features' 并成功推送到 `origin/your-branch`。” + +**场景二: 使用自定义消息** + +> **你**: "执行 `commit-smart`，并使用 'refactor(core): 优化图表渲染性能' 作为提交信息。" +> +> **Agent**: (使用指定消息执行) “提交已创建并推送，提交信息为 'refactor(core): 优化图表渲染性能'。” + +## 关键参数 + +- `head`: 要推送的分支名。如果留空，将自动使用当前分支。 +- `message`: 手动指定的提交信息。若提供，将作为提交主题。否则，将根据 `common/changes/` 内容或文件变更自动生成。 +- `pushAfterCommit`: 是否在提交后自动推送，默认为 `true`。 + +## 注意事项 + +- **危险区域**: 此技能会使用 `git add --all` 命令，将工作目录中 **所有** 未被 `.gitignore` 忽略的变更添加到提交中。请在执行前仔细检查你的工作区，确保没有不想提交的临时文件或改动。 +- 执行前请确保当前分支没有合并冲突，且远程分支已存在。 + +## 安全命令示例 + +```bash +# 提交前检查暂存状态 +git status + +# 如发现 .trae/skills 被加入暂存区，撤销暂存： +git restore --staged .trae/skills + +# 需要更精细控制时，可以只对代码目录执行 add： +git add packages/vchart src tests +``` + +> 建议在调用 `commit-smart` 前先清理暂存区中不需要的文件（尤其是 `.trae/skills` 等环境文档），以免被自动提交。 diff --git a/.trae/skills/create-branch/SKILL.md b/.trae/skills/create-branch/SKILL.md new file mode 100755 index 0000000000..a37811936d --- /dev/null +++ b/.trae/skills/create-branch/SKILL.md @@ -0,0 +1,52 @@ +--- +name: create-branch +description: 'Creates a new development branch in the VChart project following standard naming conventions. Use this skill to start new work on a clean, synchronized branch based on a specified base branch (default: develop). You must provide a `topic` for the branch name.' +--- + +# 创建开发分支 (create-branch) + +## 概述 + +本技能用于在 `VChart` 仓库中，基于指定的基础分支（默认为 `develop`）创建一个符合团队命名规范的、干净的开发分支。 + +## 前置条件 + +- **Git 环境**: 需要一个配置好 git 的环境。 +- **工作树状态**: 为保证分支创建的纯净，建议在干净的工作树上执行。 + +## 输入参数 + +| 参数 | 类型 | 是否必填 | 默认值 | 描述 | +| -------------- | ------- | -------- | -------------- | ---------------------------------------------- | +| `topic` | string | 是 | (无) | 分支主题，用于构成最终的分支名（例如 `perf-legend-opt`）。 | +| `baseBranch` | string | 否 | `develop` | 创建新分支所基于的基础分支。 | +| `branchPrefix` | string | 否 | `chore/trae` | 分支名的前缀。 | +| `useDateSuffix`| boolean | 否 | `true` | 是否在分支名末尾追加日期和时间后缀。 | + +## 输出与成功标准 + +- **主要输出** (`branch_name`): 成功创建并切换到的新分支的完整名称。 +- **成功标准**: + - `branch_created`: 新分支被成功创建。 + - `clean_working_tree`: 执行后工作树保持干净。 + +## 执行步骤 + +1. **同步基础分支**: + - Agent 会首先运行 `git fetch --all --prune` 来获取所有远程更新。 + - 接着，它会切换到 `{{baseBranch}}` 并执行 `git pull` 以确保其为最新状态。 + +2. **生成并创建分支**: + - 根据 `branchPrefix`、`topic` 和 `useDateSuffix` 参数组合生成标准格式的分支名。 + - 执行 `git checkout -b {{branch_name}}` 创建并切换到新分支。 + +3. **状态检查**: + - Agent 会运行 `git status` 检查并确认当前已在新分支上，且工作树是干净的。 + +## 何时使用 / 边界 + +- **使用时机**: + - 当你需要为新功能、修复或任何其他编码任务，在 `VChart` 项目中创建一个新的、遵循团队规范的开发分支时。 +- **边界**: + - 此技能不负责提交任何代码，仅创建和切换分支。 + - 执行前，请确保你的工作区中没有需要保存的未提交变更，因为切换分支可能会导致问题。 diff --git a/.trae/skills/create-branch/docs/USAGE.md b/.trae/skills/create-branch/docs/USAGE.md new file mode 100755 index 0000000000..31512fa496 --- /dev/null +++ b/.trae/skills/create-branch/docs/USAGE.md @@ -0,0 +1,28 @@ +# 使用说明：create-branch + +本技能用于在 `VChart` 项目中快速创建一个符合命名规范的、干净的开发分支。 + +## 何时使用 + +- **开始新任务**: 当你准备开始一个新功能、修复一个 bug 或进行任何需要独立分支的工作时，使用此技能可以确保你从一个与 `develop` 同步的、命名规范的分支开始。 + +## 示例对话 + +> **你**: “我想开始一个关于图例性能优化的工作，请帮我创建一个开发分支。” +> +> **Agent**: “好的，请为你的分支提供一个 `topic`。” +> +> **你**: “topic 是 `perf-legend-opt`” +> +> **Agent**: (执行技能) “分支 `chore/trae-perf-legend-opt-20260105-1130` 已创建并切换成功。你现在可以在这个新分支上开始工作了。” + +## 关键参数 + +- `topic`: **(必填)** 分支的主题，将成为分支名的一部分。例如 `feature-new-axis`。 +- `baseBranch`: 新分支基于哪个分支创建，默认为 `develop`。 +- `branchPrefix`: 分支名的前缀，默认为 `chore/trae`。 + +## 注意事项 + +- **干净的工作区**: 建议在执行此技能前，先提交或储藏你的本地变更，因为 `git checkout` 操作可能会覆盖未提交的改动。 +- 本技能只负责创建和切换分支，不处理任何代码的提交或合并。 diff --git a/.trae/skills/pr-body-generate/SKILL.md b/.trae/skills/pr-body-generate/SKILL.md new file mode 100755 index 0000000000..ff44a9a4a4 --- /dev/null +++ b/.trae/skills/pr-body-generate/SKILL.md @@ -0,0 +1,134 @@ +--- +name: pr-body-generate +description: 'Generates a well-formed Pull Request body for the VChart project based on its template. Use this skill to automatically populate the PR body with details like linked issues, changelog entries, self-test checklists, and a code walkthrough. The output is saved to a local file for review and modification before creating the PR.' +--- + +# 生成 PR 正文 (pr-body-generate) + +## 概述 + +本技能用于根据 `VChart` 仓库中预设的 Pull Request 模板，自动生成一份内容丰富、格式规范的 PR 正文。它能够智能地聚合来自 Rush 变更日志、测试报告和 Git 提交历史的信息。 + +## 前置条件 + +- **Git 环境**: 一个配置好的 Git 环境。 +- **本地变更**: 建议在本地已有代码变更和 `common/changes` 变更条目的情况下运行，以生成最完整的 PR 正文。 + +## 输入参数 + +| 参数 | 类型 | 是否必填 | 默认值 | 描述 | +| ---------------- | ------- | -------- | --------------------------------------- | -------------------------------------------------------------- | +| `lang` | string | 否 | `zh` | PR 模板的语言 (`zh` 或 `en`)。 | +| `title` | string | 否 | (空) | 用于生成建议 PR 标题的素材。 | +| `head` | string | 否 | (空) | PR 的源分支名。如果为空，将自动推导当前分支。 | +| `labels` | array | 否 | `[]` | 附加到 PR 的标签，会体现在正文的元信息中。 | +| `rushChangesDir` | string | 否 | `common/changes` | Rush 变更日志条目所在的目录。 | +| `localBodyFile` | boolean | 否 | `true` | 是否将生成的正文保存到本地文件。 | +| `autotestReport` | string | 否 | `.trae/output/autotest.report.local.md` | `auto-test` 技能生成的临时报告路径，其内容会被摘要进 PR 正文。 | +| `autoCheckType` | boolean | 否 | `true` | 是否自动勾选模板中的“分支类型/This is a ...”。 | +| `typeOverride` | string | 否 | (空) | 手动覆盖类型（如 `Workflow`、`New feature` 等），优先级最高。 | + +## 输出与成功标准 + +- **主要输出**: + - `generated_title`: 推荐的 PR 标题。 + - `generated_body_preview`: 生成的完整 PR 正文的 Markdown 预览。 + - `generated_body_file`: 本地保存 PR 正文的文件路径（默认为 `.trae/output/pr.body.local.md`）。 +- **成功标准**: + - `body_generated`: PR 正文已成功生成并按需保存到本地文件。 + +## 执行步骤 + +1. **选择模板（严格遵循）**: 根据 `lang` 参数，精确选择对应的 PR 模板文件（中文：`.github/PULL_REQUEST_TEMPLATE/pr_cn.md`，英文：`.github/PULL_REQUEST_TEMPLATE.md`），并严格保留其章节结构与标题，不新增任何自定义章节或尾注。 +2. **任务类型自动识别与勾选（This is a ... / 这个分支是...）**: + - 勾选策略优先级（从高到低）： + 1. `typeOverride` 显式指定 + 2. 分支名前缀（例如 `feat/`、`fix/`、`chore/auto-flow-...`） + 3. 最近一次提交的 Conventional Commits 类型（如 `feat:`、`fix:`） + 4. 分支名关键词（如 `docs`、`demo`、`perf`、`refactor`、`style`、`test`、`merge`、`release`、`types`、`deps`、`bundle`） + 5. 标签 `labels` 的类型暗示（如包含 `workflow`、`documentation`） + - 英文模板 `.github/PULL_REQUEST_TEMPLATE.md` 的映射： + - `feat` → New feature + - `fix` → Bug fix + - `types`/`typings` → TypeScript definition update + - `bundle`/`size`/`chore(bundle)` → Bundle size optimization + - `perf` → Performance optimization + - `enhance`/`improve` → Enhancement feature + - `refactor` → Refactoring + - `deps`/`chore(deps)` → Update dependency + - `style` → Code style optimization + - `test` → Test Case + - `merge`/`branch-merge` → Branch merge + - `release` → Release + - `docs`/`site` → Site / documentation update + - `demo` → Demo update + - `chore/auto-flow*`、`workflow`、`ci` → Workflow + - 未匹配 → Other (about what?) + - 中文模板 `.github/PULL_REQUEST_TEMPLATE/pr_cn.md` 的映射与上面对应（如 `feat` → 新功能、`fix` → Bug fix、`docs` → 网站/文档更新、`chore/auto-flow*`/`workflow`/`ci` → Workflow 等）。 + - 仅勾选一个“主类型”，避免多选造成歧义；若同时匹配多个类型，选择优先级更高者。 + - 示例： + - `chore/auto-flow-experience` → 勾选 Workflow + - `feat/heatmap-color-scale` → 勾选 New feature / 新功能 + - `fix/tooltip-crash` → 勾选 Bug fix + - `docs/site-nav` → 勾选 Site / documentation update + - `refactor/scale` → 勾选 Refactoring + - `perf/heatmap` → 勾选 Performance optimization + - `test/heatmap` → 勾选 Test Case + - `style/eslint` → 勾选 Code style optimization + - `merge/develop` → 勾选 Branch merge + - `release/vX.Y.Z` → 勾选 Release + - `types/vchart` → 勾选 TypeScript definition update + - `chore(deps): bump lodash` → 勾选 Update dependency +3. **填充内容（仅在模板章节内）**: 仅在模板既有章节下补充内容： + - **Changelog**: 解析 `{{rushChangesDir}}` 目录下的变更条目，并填充到正文的 Changelog 部分。 + - **自测项**: 如果 `autotestReport` 文件存在（默认路径为 `./.trae/output/autotest.report.local.md`），会将其中的测试摘要信息（包括“无新增自动化测试”说明）填充到自测/走查部分；若文件不存在，则在正文中保留空白或占位说明，提示尚未提供自动化测试报告。 + - **背景与方案**: 基于 `message` 参数（如果提供）和提交历史，生成简要的背景与方案描述。 + - **缺失数据的占位处理**: 当未找到 `{{rushChangesDir}}` 下的 changelog 或未提供 `autotestReport` 时，正文仍会生成对应的小节，并使用“暂无 changelog”或“尚未提供自动化测试报告”等最小占位文案，确保结构完整而不会报错。 + - **元信息**: 如需提供分支、标签等信息，放入“背景&解决方案”或相应模板章节的正文中，不新增“提交与后续”等额外章节。 +4. **输出与保存**: + - Agent 会生成一个建议的 PR 标题。 + - 将完整的 PR 正文以 Markdown 预览形式展示。 + - 当 `localBodyFile` 为 `true`（默认行为）时，将模板原文复制并在既有章节内补充内容，保存到 `.trae/output/pr.body.local.md`。输出不包含任何模板外的额外段落（例如“提交与后续”）。 +5. **验证 (Validation)**: + - 生成完成后，请打开 `.trae/output/pr.body.local.md`，检查至少以下几点： + - 标题、背景与方案是否准确概括本次变更。 + - “这个分支是.../This is a ...”是否已正确勾选，且与分支名/提交类型一致。 + - Changelog 小节是否与 `common/changes` 中的内容一致；如没有 changelog，正文中是否有明确的“暂无 changelog”说明。 + - 自测/走查小节是否正确引用了 auto-test 报告；当没有新增测试时，应能看到“无新增自动化测试 (No new tests generated)” 等说明。 + - Summary / Walkthrough 等收尾小节是否存在，整体结构是否完整。 + - 如发现缺失或需要补充的信息，可直接编辑该 Markdown 文件后再执行 `pr-create-from-body`。 + +## 命令示例（本地等价操作） + +如果希望在不依赖技能的情况下，用命令行完成一个最小可用的 PR 正文生成流程，可以在 VChart 仓库根目录参考以下步骤： + +```bash +# 1. 确定当前分支（head） +head="$(git rev-parse --abbrev-ref HEAD)" + +# 2. 选择 PR 模板文件 +# 中文模板： +template=".github/PULL_REQUEST_TEMPLATE/pr_cn.md" +# 英文模板： +# template=".github/PULL_REQUEST_TEMPLATE.md" + +# 3. 确保输出目录存在 +mkdir -p ./.trae/output + +# 4. 将模板内容写入本地临时 PR 正文文件 +cp "$template" ./.trae/output/pr.body.local.md + +# 5. 在编辑器中打开并补充变更摘要、自测结果与覆盖率信息 +${EDITOR:-vim} ./.trae/output/pr.body.local.md +``` + +> 说明：`pr-body-generate` 在内部会在此基础上自动整合 `common/changes` 与 `./.trae/output/autotest.report.local.md` 中的信息，但无论数据是否齐全，都会按照 `localBodyFile: true` 的默认行为写出 `.trae/output/pr.body.local.md` 文件。 + +## 何时使用 / 边界 + +- **使用时机**: + - 在提交代码并生成变更日志之后，创建 PR 之前，用于准备 PR 的描述内容。 + - 作为 `auto-flow` 工作流的一部分，在 `commit-smart` 步骤之后自动调用。 +- **边界**: + - 此技能只生成 PR 正文，不会创建 PR。创建 PR 是 `pr-create-from-body` 技能的职责。 + - 生成内容的丰富程度依赖于前序步骤的产出（如 `changelog` 和 `auto-test` 报告）。 diff --git a/.trae/skills/pr-body-generate/docs/GH_CLI.md b/.trae/skills/pr-body-generate/docs/GH_CLI.md new file mode 100755 index 0000000000..e2bd4c6c93 --- /dev/null +++ b/.trae/skills/pr-body-generate/docs/GH_CLI.md @@ -0,0 +1,41 @@ +# GitHub CLI (gh) 核心指南 + +GitHub CLI (`gh`) 是与 GitHub 交互（尤其是创建 Pull Request）的首选执行器。在 `mode: auto` 下，`pr-create-from-body` 等技能会优先使用 `gh` 来创建 PR；只有在 `gh` 不可用时才回退到使用 `GITHUB_TOKEN` 的 REST API。 + +## 安装与登录 + +1. **安装**: + * **macOS**: `brew install gh` + * **Windows**: `winget install GitHub.cli` 或 `choco install gh` + +2. **登录**: + * 在终端运行 `gh auth login`。 + * 按照交互式提示操作：选择 `GitHub.com` -> `HTTPS` -> `Login with a web browser`。 + * 浏览器将打开一个页面要求授权。授权后，`gh` 会在本地安全地存储你的凭证。 + +3. **验证**: + * 运行 `gh auth status` 检查你的登录状态和权限。 + +## SSO (单点登录) + +如果目标仓库所属的组织强制使用 SSO，`gh` 在首次访问该组织资源时会自动触发浏览器进行 SSO 授权。只需按提示操作即可。 + +## 使用 + +`pr-create-from-body` 技能在 `mode: auto` 时，会优先使用本机已登录的 `gh` 命令来创建 PR；只有在 `gh` 未安装或未登录时，才会回退到使用 `GITHUB_TOKEN` 的 REST API。 + +**示例命令 (由技能在内部执行):** +```bash +gh pr create \ + --base develop \ + --head your-feature-branch \ + --title "feat: Your great feature" \ + --body-file ./.trae/output/pr.body.local.md +``` + +## 常见问题 + +- **`gh` 命令未找到**: 确保 `gh` 已安装并且其路径已添加到系统的 `PATH` 环境变量中。 +- **403 Forbidden**: + - **权限不足**: 你的 GitHub 账户可能没有对该仓库的写权限。 + - **SSO 问题**: 运行 `gh auth status` 并检查是否已为目标组织授权。如果没有，尝试访问该组织的任一仓库页面，`gh` 可能会自动提示你重新授权。 diff --git a/.trae/skills/pr-body-generate/docs/GITHUB_TOKEN.md b/.trae/skills/pr-body-generate/docs/GITHUB_TOKEN.md new file mode 100755 index 0000000000..0bf6974720 --- /dev/null +++ b/.trae/skills/pr-body-generate/docs/GITHUB_TOKEN.md @@ -0,0 +1,31 @@ +# GitHub Token 核心指南 + +为了让 `pr-body-generate` 和 `pr-create-from-body` 等技能能够与 GitHub 交互（例如，拉取 Issue 标题、创建 PR），你需要一个具有适当权限的个人访问令牌 (Personal Access Token, PAT)。 + +## 获取与配置 + +1. **生成 Token**: + * 前往 GitHub [**Developer settings**](https://github.com/settings/tokens) > **Personal access tokens** > **Fine-grained tokens**。 + * 创建一个新 Token，将其权限范围限定到 `VisActor/VChart` 仓库。 + * **必须权限**: + * `Pull requests`: **Read and write** + * `Contents`: **Read** + +2. **配置环境变量**: + * 将获取到的 Token (通常以 `github_pat_` 开头) 设置为本地环境变量 `GITHUB_TOKEN`。 + * **macOS/Linux**: `export GITHUB_TOKEN="your_token_here"` + * **Windows**: `$env:GITHUB_TOKEN = "your_token_here"` + * 为使其永久生效，请将此命令添加到你的 shell 配置文件中 (如 `.zshrc`, `.bash_profile` 或 PowerShell 的 `$PROFILE`)。 + +## SSO (单点登录) + +如果 `VisActor` 组织开启了 SSO，你的 Token 必须经过授权才能访问组织资源。 + +* **Fine-grained Token**: 在创建时，将 `Resource owner` 设置为 `VisActor` 组织，即可自动关联 SSO。 +* **Classic Token**: 创建后，你可能需要在 Token 列表中找到它，并点击 `Enable SSO` 或 `Configure SSO` 来完成授权。 + +## 安全须知 + +- **最小权限**: 始终为 Token 授予完成任务所需的最小权限。 +- **保护 Token**: 绝不要将 Token 硬编码到代码、提交记录或日志中。环境变量是推荐的安全存储方式。 +- **定期轮换**: 为你的 Token 设置一个合理的过期时间（如 30-90 天），并定期更换。 diff --git a/.trae/skills/pr-body-generate/docs/USAGE.md b/.trae/skills/pr-body-generate/docs/USAGE.md new file mode 100755 index 0000000000..05b1c236e6 --- /dev/null +++ b/.trae/skills/pr-body-generate/docs/USAGE.md @@ -0,0 +1,62 @@ +# 使用说明：pr-body-generate + +本技能用于自动生成一份内容丰富、格式规范的 Pull Request 正文。 + +## 何时使用 + +- **创建 PR 前**: 在代码提交和 `changelog` 生成之后，使用此技能可以一键生成 PR 的完整描述，节省手动填写模板的时间。 +- **作为流程的一部分**: 在 `auto-flow` 编排中，此技能是创建 PR 之前的关键准备步骤。 + +## 示例对话 + +**场景一: 自动生成正文** + +> **你**: “我已提交了代码和 changelog，现在请帮我生成 PR 正文。” +> +> **Agent**: (执行技能) “PR 正文已生成并保存到 `./.trae/output/pr.body.local.md`。建议标题为 '[Auto] feat: your feature summary'。请审阅内容，然后执行 `pr-create-from-body` 来创建 PR。” + +**场景二: 生成时指定标题和标签** + +> **你**: "执行 `pr-body-generate`，标题是 'feat(vis-component): 新增 Tooltip 组件'，标签是 'feature', 'component'。" +> +> **Agent**: (执行技能) “好的，已生成 PR 正文，其中包含了你指定的标签信息，并为你推荐了标题。” + +## 关键参数 + +- `lang`: PR 模板的语言，支持 `zh` (默认) 和 `en`。 +- `title`: 用于生成建议 PR 标题的素材。 +- `rushChangesDir`: Rush 变更日志条目的目录，默认为 `common/changes`。 +- `localBodyFile`: 是否将生成的正文保存到本地文件，默认为 `true`。 +- `autotestReport`: `auto-test` 技能的报告路径，其内容会被摘要进 PR 正文。 + +## 注意事项 + +- **仅生成不创建**: 此技能只负责生成 PR 正文的 `.md` 文件，**不会** 在 GitHub 上创建 PR。创建操作由 `pr-create-from-body` 技能完成。 +- **依赖前序产出**: 正文内容的丰富程度依赖于之前步骤的产出，例如 `common/changes` 目录下的 `changelog` 文件，以及 `auto-test` 在 `./.trae/output/autotest.report.local.md` 写入的测试报告。若这些信息缺失，技能仍会生成一个结构完整但内容较为精简的正文，并在相应小节中标注“暂无 changelog”或“尚未提供自动化测试报告”等提示。 +- **人工审查与验证**: 自动生成的内容是草稿，强烈建议在执行下一步前打开 `./.trae/output/pr.body.local.md`，至少检查：标题是否准确、Changelog 是否匹配实际变更、自测小节是否正确引用 auto-test 报告（或在无新增测试时包含“无新增自动化测试 (No new tests generated)” 说明）、总体结构是否完整。如有需要可直接编辑该文件后再执行 `pr-create-from-body`。 + +## 命令示例（本地等价操作） + +在 VChart 仓库根目录，你可以用下面的命令快速生成一个基于模板的本地 PR 正文文件： + +```bash +# 1. 获取当前分支名 +head="$(git rev-parse --abbrev-ref HEAD)" + +# 2. 选择 PR 模板路径 +# 中文模板： +template=".github/PULL_REQUEST_TEMPLATE/pr_cn.md" +# 英文模板： +# template=".github/PULL_REQUEST_TEMPLATE.md" + +# 3. 准备输出目录 +mkdir -p ./.trae/output + +# 4. 将模板复制为临时 PR 正文文件 +cp "$template" ./.trae/output/pr.body.local.md + +# 5. 在编辑器中补充本次修改的摘要、自测结果和风险说明 +${EDITOR:-vim} ./.trae/output/pr.body.local.md +``` + +> 提示：`pr-body-generate` 会在此基础上自动整合 `common/changes` 与 `./.trae/output/autotest.report.local.md` 中的信息，并始终按 `localBodyFile: true` 的默认设置写出 `.trae/output/pr.body.local.md` 文件。 diff --git a/.trae/skills/pr-create-from-body/SKILL.md b/.trae/skills/pr-create-from-body/SKILL.md new file mode 100755 index 0000000000..11ecaf1b0b --- /dev/null +++ b/.trae/skills/pr-create-from-body/SKILL.md @@ -0,0 +1,134 @@ +--- +name: pr-create-from-body +description: 'Creates a GitHub Pull Request for the VChart project using a local markdown file as its body. Use this skill as the final step in the PR-creation process, after the PR body has been generated and reviewed. It requires either a `GITHUB_TOKEN` or a logged-in `gh` CLI environment to operate.' +--- + +# 从本地文件创建 PR (pr-create-from-body) + +## 概述 + +本技能用于读取一个本地 Markdown 文件作为 Pull Request 的正文，并在 GitHub 上创建该 PR。它是 `pr-body-generate` 技能的后续步骤，负责将准备好的内容发布出去。 + +## 前置条件 + +- **GitHub 凭证**: 必须在环境中配置 `GITHUB_TOKEN`，或者已安装并登录了 `gh` CLI。 +- **PR 正文文件**: 必须存在一个包含 PR 正文的本地 Markdown 文件。通常由 `pr-body-generate` 技能生成。 +- **分支已推送**: 源分支必须已经推送到远程仓库。 + +## 输入参数 + +| 参数 | 类型 | 是否必填 | 默认值 | 描述 | +| ----------- | ------- | -------- | ---------------------------------- | -------------------------------------------------------------- | +| `title` | string | 是 | (无) | Pull Request 的标题。 | +| `base` | string | 否 | `develop` | PR 的目标分支。 | +| `head` | string | 否 | (空) | PR 的源分支。如果为空，将自动推导当前分支。 | +| `bodyFile` | string | 否 | `./.trae/output/pr.body.local.md` | 包含 PR 正文的本地 Markdown 文件的路径。 | +| `mode` | string | 否 | `auto` | 创建 PR 的方式 (`auto`, `gh`, `rest`)。`auto` 会优先使用 `gh`，其次是 `rest` (基于 `GITHUB_TOKEN`)。 | +| `draft` | boolean | 否 | `false` | 是否将 PR 创建为草稿（Draft）状态。 | +| `labels` | array | 否 | `[]` | 要附加到 PR 的标签列表。 | + +## 输出与成功标准 + +- **主要输出** (`pr_url`): 成功创建的 Pull Request 的 URL。 +- **成功标准** (`pr_created`): Pull Request 已在 GitHub 上成功创建。 + +## 执行步骤 + +1. **参数与环境检查**: + - Agent 会检查 `title` 是否已提供。 + - 确认 `head` 分支，如果未提供则自动检测当前分支。 + - 检查 `bodyFile` 指定的文件是否存在且内容不为空。 + - 根据 `mode` 参数检查 `GITHUB_TOKEN` 或 `gh` CLI 是否可用。 + +2. **（可选）提交变更**: 如果 `commitBeforeCreate` 设置为 `true` 且有未提交的变更，Agent 会先执行一次智能提交（类似于 `commit-smart` 技能）。 + +3. **创建 PR**: + - **gh 模式**: Agent 会使用 `gh pr create` 命令，并通过 `--body-file` 参数直接传入正文文件。 + - **rest 模式**: Agent 会读取 `bodyFile` 的内容，然后通过调用 GitHub REST API (`POST /repos/{owner}/{repo}/pulls`) 来创建 PR。 + - **auto 模式（推荐）**: 首先尝试使用已登录且指向正确远程仓库的 `gh` CLI 创建 PR；只有在 `gh` 不可用（未安装、未登录或无法识别当前仓库）时，才会回退到使用 `GITHUB_TOKEN` 的 REST API。若两种方式都不可用或调用失败，技能会返回清晰的错误信息和排查建议。 + +4. **输出结果**: 如果 PR 创建成功，Agent 会返回该 PR 的 URL。如果失败，则会返回详细的错误信息。 + +## Quick Actions（快速操作示例） + +### 路径一：使用 gh CLI 一键创建 PR（推荐） + +在 VChart 仓库根目录： + +```bash +# 1. 确认 gh 已登录 +gh auth login + +# 2. 使用本地正文文件创建 PR（以 develop 为 base） +gh pr create \ + -B develop \ + -H \ + -t "" \ + -F ./.trae/output/pr.body.local.md \ + --label changelog \ + --label test +``` + +> 说明：当 `mode: auto` 时，`pr-create-from-body` 会在内部执行与上述命令等价的 `gh pr create`，仅在 `gh` 不可用时才回退到 REST。 + +### 路径二：使用 GITHUB_TOKEN + REST API + +在终端中先配置 Token： + +```bash +export GITHUB_TOKEN="your_token_here" +``` + +然后可以直接调用 GitHub PR 接口（示例）： + +```bash +curl -X POST \ + -H "Authorization: Bearer $GITHUB_TOKEN" \ + -H "Accept: application/vnd.github+json" \ + https://api.github.com/repos/VisActor/VChart/pulls \ + -d '{ + "title": "", + "head": "", + "base": "develop", + "body": "请将 .trae/output/pr.body.local.md 中的内容粘贴到这里，或改用 pr-create-from-body 技能自动填充" + }' +``` + +> 建议优先通过技能并设置 `mode: rest` 来使用 REST 路径：在对话中明确 base/head/title，技能会自动读取 `.trae/output/pr.body.local.md` 并调用同一个接口。 + +## 错误处理与排查 + +当在 `mode: auto` 或 `mode: gh` 下创建 PR 失败时，可以按以下顺序排查： + +1. **检查 gh 安装与登录状态** + - 运行 `gh --version` 确认命令可用。 + - 运行 `gh auth status` 确认已登录 `github.com`，并具备访问 `VisActor/VChart` 的权限。 + +2. **确认仓库远程指向正确** + - 在仓库根目录执行 `git remote -v`，确认 `origin` 指向 GitHub 上的 `VisActor/VChart`。 + - 执行 `gh repo view` 验证 `gh` 能识别当前目录对应的仓库。 + +3. **处理组织 SSO 授权问题** + - 如果组织启用了 SSO，按 `gh auth status` 提示完成 SSO 授权，或在浏览器中重新授权访问 `VisActor` 组织。 + +当在 `mode: rest` 或自动回退到 REST 时失败，可继续检查： + +4. **验证 GITHUB_TOKEN 是否配置正确** + - 确认环境变量 `GITHUB_TOKEN` 已设置且非空。 + - 使用 `curl` 测试：`curl -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user`，确保返回 200。 + +5. **检查 Token 权限与 SSO** + - 确认 Token 至少拥有 `Pull requests: Read and write` 与 `Contents: Read` 权限。 + - 若为组织仓库，确保已在 GitHub 的 Token 管理页面为 `VisActor` 组织完成 SSO 授权。 + +若以上步骤均正常但仍报错，建议记录错误信息（HTTP 状态码与提示内容），并根据提示进一步排查或联系仓库维护者。 + +## 何时使用 / 边界 + +- **使用时机**: + - 在使用 `pr-body-generate` 生成并（可选地）人工审查了 PR 正文之后，作为发布的最后一步。 + - 当你有一个准备好的 Markdown 文件，并希望用它作为 PR 的描述来快速创建 PR 时。 +- **边界**: + - 此技能强依赖于一个已存在的、内容完备的本地正文文件。 + - 它不会修改 PR 正文内容，只是“按原样”上传。 + - 创建 PR 前，请确保你的 `head` 分支已经包含了所有需要合并的提交，并已推送到远程仓库。 diff --git a/.trae/skills/pr-create-from-body/docs/GH_CLI.md b/.trae/skills/pr-create-from-body/docs/GH_CLI.md new file mode 100755 index 0000000000..e2bd4c6c93 --- /dev/null +++ b/.trae/skills/pr-create-from-body/docs/GH_CLI.md @@ -0,0 +1,41 @@ +# GitHub CLI (gh) 核心指南 + +GitHub CLI (`gh`) 是与 GitHub 交互（尤其是创建 Pull Request）的首选执行器。在 `mode: auto` 下，`pr-create-from-body` 等技能会优先使用 `gh` 来创建 PR；只有在 `gh` 不可用时才回退到使用 `GITHUB_TOKEN` 的 REST API。 + +## 安装与登录 + +1. **安装**: + * **macOS**: `brew install gh` + * **Windows**: `winget install GitHub.cli` 或 `choco install gh` + +2. **登录**: + * 在终端运行 `gh auth login`。 + * 按照交互式提示操作：选择 `GitHub.com` -> `HTTPS` -> `Login with a web browser`。 + * 浏览器将打开一个页面要求授权。授权后，`gh` 会在本地安全地存储你的凭证。 + +3. **验证**: + * 运行 `gh auth status` 检查你的登录状态和权限。 + +## SSO (单点登录) + +如果目标仓库所属的组织强制使用 SSO，`gh` 在首次访问该组织资源时会自动触发浏览器进行 SSO 授权。只需按提示操作即可。 + +## 使用 + +`pr-create-from-body` 技能在 `mode: auto` 时，会优先使用本机已登录的 `gh` 命令来创建 PR；只有在 `gh` 未安装或未登录时，才会回退到使用 `GITHUB_TOKEN` 的 REST API。 + +**示例命令 (由技能在内部执行):** +```bash +gh pr create \ + --base develop \ + --head your-feature-branch \ + --title "feat: Your great feature" \ + --body-file ./.trae/output/pr.body.local.md +``` + +## 常见问题 + +- **`gh` 命令未找到**: 确保 `gh` 已安装并且其路径已添加到系统的 `PATH` 环境变量中。 +- **403 Forbidden**: + - **权限不足**: 你的 GitHub 账户可能没有对该仓库的写权限。 + - **SSO 问题**: 运行 `gh auth status` 并检查是否已为目标组织授权。如果没有，尝试访问该组织的任一仓库页面，`gh` 可能会自动提示你重新授权。 diff --git a/.trae/skills/pr-create-from-body/docs/GITHUB_TOKEN.md b/.trae/skills/pr-create-from-body/docs/GITHUB_TOKEN.md new file mode 100755 index 0000000000..0bf6974720 --- /dev/null +++ b/.trae/skills/pr-create-from-body/docs/GITHUB_TOKEN.md @@ -0,0 +1,31 @@ +# GitHub Token 核心指南 + +为了让 `pr-body-generate` 和 `pr-create-from-body` 等技能能够与 GitHub 交互（例如，拉取 Issue 标题、创建 PR），你需要一个具有适当权限的个人访问令牌 (Personal Access Token, PAT)。 + +## 获取与配置 + +1. **生成 Token**: + * 前往 GitHub [**Developer settings**](https://github.com/settings/tokens) > **Personal access tokens** > **Fine-grained tokens**。 + * 创建一个新 Token，将其权限范围限定到 `VisActor/VChart` 仓库。 + * **必须权限**: + * `Pull requests`: **Read and write** + * `Contents`: **Read** + +2. **配置环境变量**: + * 将获取到的 Token (通常以 `github_pat_` 开头) 设置为本地环境变量 `GITHUB_TOKEN`。 + * **macOS/Linux**: `export GITHUB_TOKEN="your_token_here"` + * **Windows**: `$env:GITHUB_TOKEN = "your_token_here"` + * 为使其永久生效，请将此命令添加到你的 shell 配置文件中 (如 `.zshrc`, `.bash_profile` 或 PowerShell 的 `$PROFILE`)。 + +## SSO (单点登录) + +如果 `VisActor` 组织开启了 SSO，你的 Token 必须经过授权才能访问组织资源。 + +* **Fine-grained Token**: 在创建时，将 `Resource owner` 设置为 `VisActor` 组织，即可自动关联 SSO。 +* **Classic Token**: 创建后，你可能需要在 Token 列表中找到它，并点击 `Enable SSO` 或 `Configure SSO` 来完成授权。 + +## 安全须知 + +- **最小权限**: 始终为 Token 授予完成任务所需的最小权限。 +- **保护 Token**: 绝不要将 Token 硬编码到代码、提交记录或日志中。环境变量是推荐的安全存储方式。 +- **定期轮换**: 为你的 Token 设置一个合理的过期时间（如 30-90 天），并定期更换。 diff --git a/.trae/skills/pr-create-from-body/docs/USAGE.md b/.trae/skills/pr-create-from-body/docs/USAGE.md new file mode 100755 index 0000000000..160c3eddae --- /dev/null +++ b/.trae/skills/pr-create-from-body/docs/USAGE.md @@ -0,0 +1,80 @@ +# 使用说明：pr-create-from-body + +本技能用于将在本地准备好的 Pull Request 正文文件发布到 GitHub，完成 PR 的创建。 + +## 何时使用 + +- **发布的最后一步**: 当你已经生成并审查了 PR 正文后，使用此技能来完成最后的创建步骤。 +- **手动创建**: 如果你手动编写了一个 `.md` 文件作为 PR 正文，也可以使用此技能来创建 PR。 + +## 示例对话 + +**场景一: 使用默认正文文件创建 PR** + +> **你**: “PR 正文已经准备好了，现在请帮我用 'feat: add new chart type' 这个标题创建一个 PR。” +> +> **Agent**: (执行技能) “好的。正在读取 `./.trae/output/pr.body.local.md` 的内容... Pull Request 已创建：https://github.com/VisActor/VChart/pull/123” + +**场景二: 创建一个草稿 PR 并添加标签** + +> **你**: “执行 `pr-create-from-body`，标题是 'WIP: refactor data processor'，设为草稿模式，并加上 'refactor' 和 'WIP' 标签。” +> +> **Agent**: (执行技能) “已成功创建一个草稿 Pull Request，并添加了指定标签。链接是: ...” + +## 关键参数 + +- `title`: **(必填)** Pull Request 的标题。 +- `base`: PR 的目标分支，默认为 `develop`。 +- `head`: PR 的源分支。如果留空，将自动使用当前分支。 +- `bodyFile`: 包含 PR 正文的本地文件路径，默认为 `./.trae/output/pr.body.local.md`。 +- `mode`: 创建 PR 的方式，`auto` (默认) 会优先尝试 `gh` CLI，失败则回退到使用 `GITHUB_TOKEN` 的 REST API。 +- `draft`: 是否将 PR 创建为草稿状态，默认为 `false`。 + +## 注意事项 + +- **凭证**: 执行前，必须确保 `GITHUB_TOKEN` 环境变量已设置，或 `gh` CLI 已安装并登录。请参阅本技能目录下的 `docs/GITHUB_TOKEN.md` 和 `docs/GH_CLI.md`。 +- **分支推送**: 在创建 PR 之前，请务必确保你的本地分支 (`head`) 已经推送到 GitHub 远程仓库，否则 GitHub 无法找到该分支。 +- **正文文件**: 确认 `bodyFile` 指向的文件存在且内容正确。 +- **常见失败的排查清单**（特别是 `mode: auto`）： + - 使用 `gh auth status` 检查 CLI 登录状态以及是否已为目标组织完成 SSO 授权； + - 在仓库根目录运行 `git remote -v` 与 `gh repo view`，确认当前目录映射到 GitHub 上的 `VisActor/VChart` 仓库； + - 若使用 REST 模式或自动回退到 REST，确认 `GITHUB_TOKEN` 已设置且权限正确（可用 `curl -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user` 做快速验证）。 + +## Quick Actions（一键命令示例） + +### 路径一：gh CLI + +在 VChart 仓库根目录执行： + +```bash +# 登录（如尚未登录） +gh auth login + +# 使用本地正文文件创建 PR +gh pr create \ + -B develop \ + -H \ + -t "" \ + -F ./.trae/output/pr.body.local.md \ + --label changelog \ + --label test +``` + +### 路径二：GITHUB_TOKEN + REST + +```bash +export GITHUB_TOKEN="your_token_here" + +curl -X POST \ + -H "Authorization: Bearer $GITHUB_TOKEN" \ + -H "Accept: application/vnd.github+json" \ + https://api.github.com/repos/VisActor/VChart/pulls \ + -d '{ + "title": "", + "head": "", + "base": "develop", + "body": "从 .trae/output/pr.body.local.md 复制正文内容到此处" + }' +``` + +> 提示：在技能中使用 `mode: auto` 时，会优先走“路径一”（`gh` 创建 PR），当 `gh` 不可用时自动回退到“路径二”（REST + `GITHUB_TOKEN`）。 diff --git a/common/changes/@visactor/vchart/chore-auto-flow-experience_2025-12-26-07-42.json b/common/changes/@visactor/vchart/chore-auto-flow-experience_2025-12-26-07-42.json new file mode 100644 index 0000000000..dd524f3bdf --- /dev/null +++ b/common/changes/@visactor/vchart/chore-auto-flow-experience_2025-12-26-07-42.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "comment": "chore(auto-flow): optimize auto flow", + "type": "none", + "packageName": "@visactor/vchart" + } + ], + "packageName": "@visactor/vchart", + "email": "lixuef1313@163.com" +} \ No newline at end of file