From 84dc84ac560712e6c0f3a6f0b0b66aca7773ac42 Mon Sep 17 00:00:00 2001 From: "lixuefei.1313" Date: Fri, 26 Dec 2025 11:48:28 +0800 Subject: [PATCH 01/10] chore(auto-flow): optimize auto flow --- .trae/jobs/auto-flow.md | 74 +++++++++---------- .trae/jobs/auto-test.md | 13 +++- .trae/jobs/commit-smart.md | 54 ++++++++++++++ ...auto-flow-experience_2025-12-26-07-42.json | 11 +++ 4 files changed, 110 insertions(+), 42 deletions(-) create mode 100644 .trae/jobs/commit-smart.md create mode 100644 common/changes/@visactor/vchart/chore-auto-flow-experience_2025-12-26-07-42.json diff --git a/.trae/jobs/auto-flow.md b/.trae/jobs/auto-flow.md index 015eb762bf..cbc9fc27d9 100644 --- a/.trae/jobs/auto-flow.md +++ b/.trae/jobs/auto-flow.md @@ -15,66 +15,64 @@ parameters: bumpType: auto notCommit: true head: '' - mode: auto - commitBeforeFlow: true + mode: browser commitAllowEmpty: false pushAfterCommit: true commitMessageStrategy: auto - enforceCommit: true - commitRetry: 1 + flowStep: 1 required_parameters: [] outputs: - autotest_report - rush_change_entries - - pr_url + - commit_message + - pushed_branch + - compare_url + - next_step_hint success_criteria: - - flow_completed + - flow_step_completed --- -# Auto Flow Job（分支 → 单测 → 变更日志 →PR 串行编排） +# Auto Flow Job（单步执行：单测 → 变更日志 → 提交 → PR） ## 参数检查 - 分支参数 `head` 可选：若未提供，将通过 `git rev-parse --abbrev-ref HEAD` 推导当前分支 - 建议提供 `topic` 以优化 PR 标题；未提供时将回退为当前分支名 -## 步骤 - -1. 分支预检查 +## 单步模式说明 -- 运行 `git rev-parse --abbrev-ref HEAD` 获取当前分支作为 `head` -- 确认当前分支不是 `main`/`develop`，且工作树状态符合提交规范 -- 人工检查点：如不在开发分支，请先自行创建并切换到正确分支 +- 本 Job 每次仅执行一个步骤，由 `parameters.flowStep` 指定（取值：`1|2|3|4`）。 +- 步骤完成后进入人工暂停，返回 `next_step_hint` 提示你在对话中输入“执行下一步”推进到下一步。 - 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. 运行差异驱动单测 +1. 差异驱动单测（flowStep=1） - 执行 Job：`.trae/jobs/auto-test.md` -- 传参：`sinceBranch={{baseBranch}}`（其余沿用默认） +- 传参：`sinceBranch={{baseBranch}}`、`includeWorkingTree=true`、`replaceAutogen=false` - 接收输出：`autotest_report=.trae/output/autotest.report.local.md` -- 人工检查点：打开临时报告，确认新增/更新测试与覆盖率 +- 人工检查点：打开临时报告，确认新增/更新测试与覆盖率是否合理 -3. 生成 Rush 变更日志 +2. 生成 Rush 变更日志（flowStep=2） - 执行 Job：`.trae/jobs/changelog-rush-smart.md` - 传参：`sinceBranch={{baseBranch}}`、`message={{message}}`、`bumpType={{bumpType}}`、`notCommit={{notCommit}}` -- 接收输出：`rush_change_entries` -- 人工检查点：检查 `common/changes/**` 条目与摘要 +- 接收输出：`rush_change_entries`、`computed_bump_type`、`final_message` +- 人工检查点：检查 `common/changes/**` 条目与摘要是否合理 + +3. 智能提交（flowStep=3） + +- 执行 Job：`.trae/jobs/commit-smart.md` +- 传参： + - `head={{head || (git rev-parse --abbrev-ref HEAD)}}` + - `commitAllowEmpty={{commitAllowEmpty}}` + - `pushAfterCommit={{pushAfterCommit}}` + - `commitMessageStrategy={{commitMessageStrategy}}` + - `message={{message}}`（为空时使用步骤 2 的 `final_message`） +- 接收输出：`commit_message`、`pushed_branch` +- 人工检查点：确认提交信息与推送分支是否正确 -4. 创建 PR +4. 创建 PR（flowStep=4） - 执行 Job：`.trae/jobs/pr-create.md` - 传参： @@ -85,11 +83,11 @@ success_criteria: - `labels={{labels}}` - `message={{message}}`（用于正文摘要） - `bumpType={{bumpType}}` - - `mode={{mode}}`（auto 优先 gh → token → 浏览器 URL） - - `commitBeforeCreate=false`（已在 1.1 阶段完成自动提交） -- 接收输出：`pr_url` -- 人工检查点：最终确认并提交 + - `mode={{mode}}`（交互默认 `browser`，生成 Compare URL 与本地正文） + - `localBodyFile=true` +- 接收输出：`compare_url`、`generated_body_preview` +- 人工检查点：在浏览器页面完成最终提交 5. 完成 -- 标记 `flow_completed`，返回 `autotest_report`、`rush_change_entries` 与 `pr_url` +- 标记 `flow_step_completed`，返回本步骤对应输出与 `next_step_hint` diff --git a/.trae/jobs/auto-test.md b/.trae/jobs/auto-test.md index 4d556199ee..35e4dc174d 100644 --- a/.trae/jobs/auto-test.md +++ b/.trae/jobs/auto-test.md @@ -12,13 +12,14 @@ parameters: onlyNew: false reportFormat: md applyManualOverrides: true - replaceAutogen: true + replaceAutogen: false dryRun: false preview: false stopOnError: true focusChangedOnly: false snapshotStrategy: combined tempReportPath: .trae/output/autotest.report.local.md + includeWorkingTree: true mockDefaults: time: fixed(2020-01-01T00:00:00Z) random: seed(42) @@ -43,11 +44,15 @@ manual_overrides: [] ## 步骤 -1. 差异采集 +1. 差异采集（含未提交内容，当 `includeWorkingTree==true`） - 运行 `git fetch --all --prune` -- 运行 `git diff --name-status --diff-filter=AMR {{sinceBranch}}...HEAD` -- 对每个变更文件，运行 `git diff --unified=0 {{sinceBranch}}...HEAD ` 获取行级差异 +- 收集已提交差异：`git diff --name-status --diff-filter=AMR {{sinceBranch}}...HEAD` +- 收集工作树差异：`git status --porcelain` +- 行级差异： + - 已提交：`git diff --unified=0 {{sinceBranch}}...HEAD ` + - 暂存未提交：`git diff --cached --unified=0 -- ` + - 未暂存：`git diff --unified=0 -- ` 2. 影响分析 diff --git a/.trae/jobs/commit-smart.md b/.trae/jobs/commit-smart.md new file mode 100644 index 0000000000..ade43ab4bf --- /dev/null +++ b/.trae/jobs/commit-smart.md @@ -0,0 +1,54 @@ +--- +job: commit-smart +intent: git-commit-push +version: v1 +domain: git +runner: trae-solo +parameters: + head: '' + commitAllowEmpty: false + pushAfterCommit: true + commitMessageStrategy: auto + message: '' +required_parameters: [] +outputs: + - commit_message + - pushed_branch +success_criteria: + - commit_created_or_skipped +--- + +# Commit Job（智能提交与推送） + +## 步骤 + +1. 推导分支 + +- 若 `parameters.head` 为空：`git rev-parse --abbrev-ref HEAD` + +2. 工作树检查 + +- `git status --porcelain`；若无变更且 `commitAllowEmpty==false`，返回 `commit_created_or_skipped`（跳过） + +3. 生成提交信息（策略 `auto`） + +- 类型：按路径前缀判定（含 `docs/` → `docs`；含 `__tests__/`/`*.test.*` → `test`；否则 `chore|fix|feat` 依据 `common/changes/**` 的 `type`，缺省 `chore`） +- 作用域：`packages/` 或顶层目录 +- 主题：若 `message` 非空用其首行，否则： + - 有 `common/changes/**`：取最新条目的 `comment` + - 否则：`sync changes before PR (N files)` + +4. 执行提交与推送 + +- `git add --all` +- `git commit {{#commitAllowEmpty}}--allow-empty{{/commitAllowEmpty}} -m ""` +- 若 `pushAfterCommit==true`：`git push -u origin {{head}}` + +5. 输出 + +- `commit_message` 与 `pushed_branch` + +## 人工检查点 + +- 返回提交信息与结果，待确认后继续 PR 步骤。 + 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 From 3fcf685608891798a3f4f6fa1c65f3f6a01e9390 Mon Sep 17 00:00:00 2001 From: "lixuefei.1313" Date: Mon, 29 Dec 2025 17:05:37 +0800 Subject: [PATCH 02/10] feat: upgrade auto flow --- .trae/jobs/auto-flow.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/.trae/jobs/auto-flow.md b/.trae/jobs/auto-flow.md index cbc9fc27d9..ca898d69a8 100644 --- a/.trae/jobs/auto-flow.md +++ b/.trae/jobs/auto-flow.md @@ -38,6 +38,7 @@ success_criteria: - 分支参数 `head` 可选：若未提供，将通过 `git rev-parse --abbrev-ref HEAD` 推导当前分支 - 建议提供 `topic` 以优化 PR 标题；未提供时将回退为当前分支名 +- 原则：不覆盖子 Job 默认参数；仅透传用户显式提供的参数 ## 单步模式说明 @@ -49,7 +50,7 @@ success_criteria: 1. 差异驱动单测（flowStep=1） - 执行 Job：`.trae/jobs/auto-test.md` -- 传参：`sinceBranch={{baseBranch}}`、`includeWorkingTree=true`、`replaceAutogen=false` +- 传参：`sinceBranch={{baseBranch}}` - 接收输出：`autotest_report=.trae/output/autotest.report.local.md` - 人工检查点：打开临时报告，确认新增/更新测试与覆盖率是否合理 @@ -57,6 +58,7 @@ success_criteria: - 执行 Job：`.trae/jobs/changelog-rush-smart.md` - 传参：`sinceBranch={{baseBranch}}`、`message={{message}}`、`bumpType={{bumpType}}`、`notCommit={{notCommit}}` +- 说明：仅透传用户显式提供的参数，未提供时不传，使用子 Job 默认值 - 接收输出：`rush_change_entries`、`computed_bump_type`、`final_message` - 人工检查点：检查 `common/changes/**` 条目与摘要是否合理 @@ -65,10 +67,8 @@ success_criteria: - 执行 Job：`.trae/jobs/commit-smart.md` - 传参： - `head={{head || (git rev-parse --abbrev-ref HEAD)}}` - - `commitAllowEmpty={{commitAllowEmpty}}` - - `pushAfterCommit={{pushAfterCommit}}` - - `commitMessageStrategy={{commitMessageStrategy}}` - `message={{message}}`（为空时使用步骤 2 的 `final_message`） +- 说明：除 `head` 与 `message` 外，其余参数不强制设置；未提供时使用子 Job 默认值 - 接收输出：`commit_message`、`pushed_branch` - 人工检查点：确认提交信息与推送分支是否正确 @@ -85,6 +85,7 @@ success_criteria: - `bumpType={{bumpType}}` - `mode={{mode}}`（交互默认 `browser`，生成 Compare URL 与本地正文） - `localBodyFile=true` +- 说明：仅透传上述必要编排参数，不改变子 Job 输出；未提供的可选项不透传，使用子 Job 默认值 - 接收输出：`compare_url`、`generated_body_preview` - 人工检查点：在浏览器页面完成最终提交 From f513d83e476a56e974b5aea08906ef312eb13b1e Mon Sep 17 00:00:00 2001 From: "lixuefei.1313" Date: Tue, 30 Dec 2025 18:44:16 +0800 Subject: [PATCH 03/10] feat: optimiz trae flow --- .trae/documents/github-gh-local.md | 96 ++++++++++ .trae/documents/github-token-local.md | 199 ++++++++++++++++++++ .trae/documents/pr-body-generate.solo.md | 36 ++++ .trae/documents/pr-create-from-body.solo.md | 42 +++++ .trae/documents/pr-create.solo.md | 52 ----- .trae/jobs/auto-flow.md | 48 +++-- .trae/jobs/pr-body-generate.md | 60 ++++++ .trae/jobs/pr-create-from-body.md | 63 +++++++ .trae/jobs/pr-create.md | 167 ---------------- 9 files changed, 527 insertions(+), 236 deletions(-) create mode 100644 .trae/documents/github-gh-local.md create mode 100644 .trae/documents/github-token-local.md create mode 100644 .trae/documents/pr-body-generate.solo.md create mode 100644 .trae/documents/pr-create-from-body.solo.md delete mode 100644 .trae/documents/pr-create.solo.md create mode 100644 .trae/jobs/pr-body-generate.md create mode 100644 .trae/jobs/pr-create-from-body.md delete mode 100644 .trae/jobs/pr-create.md diff --git a/.trae/documents/github-gh-local.md b/.trae/documents/github-gh-local.md new file mode 100644 index 0000000000..d2f58abb93 --- /dev/null +++ b/.trae/documents/github-gh-local.md @@ -0,0 +1,96 @@ +# GitHub CLI（gh）使用说明（创建 PR） + +- 作用：指导在 macOS 上安装与登录 `gh`，并用于创建 PR；与 `GITHUB_TOKEN` 文档保持一致的权限与注意事项 + +## 安装与更新（macOS） + +- 安装：`brew install gh` +- 更新：`brew upgrade gh` +- 验证：`gh --version`（建议使用较新版本以支持 `--body-file`） + +## 登录与授权 + +- 交互登录：`gh auth login` + - 选择 `GitHub.com` + - 选择协议：推荐 `HTTPS`（SSH 仅用于 git 操作） + - 选择登录方式：`Login with a web browser` 或 `Paste an authentication token` + - 完成浏览器授权后返回终端，`gh` 会在本地安全存储凭据 +- 组织 SSO：若目标仓库在组织下且开启 SSO，需为 `gh` 的凭据完成 SSO 授权，否则会出现 403 +- 状态查看：`gh auth status`（显示当前登录主机与权限） +- 登出与切换：`gh auth logout`（可指定主机 `-h github.com`）后重新登录 + +## 本地凭据存储 + +- `gh` 会将 OAuth/PAT 凭据安全存储在 macOS Keychain 中 +- 无需手动设置环境变量；与 `GITHUB_TOKEN` 互为备选方案（Job 默认优先 REST，再回退 `gh`） + +## 在 Job 中的使用 + +- `./.trae/jobs/pr-create-from-body.md` + - `mode: auto`：默认优先 REST（读取 `GITHUB_TOKEN`），其次使用 `gh` + - 正文仅从文件读取：`bodyFile` 或默认 `./.trae/output/pr.body.local.md` + - `gh` 创建命令示例： + - `gh pr create --base --head --title "" --body-file <path> --label <label1> --label <label2> --draft` + - 成功输出 `pr_url`；失败输出错误信息，不展示 compare URL + +## 注意事项（与 Token 文档同步） + +- 最小权限原则：`gh` 登录时仅授权必要范围；组织仓库需完成 SSO 授权 +- 不要将凭据写入仓库或日志；避免在聊天中粘贴敏感信息 +- 定期检查与轮换凭据；遇到 401/403 优先排查授权与 SSO 状态 +- 仓库识别：`gh` 默认从当前目录的 git 远程推断目标仓库（确保 `origin` 指向 GitHub 仓库） + +## 常见问题排查 + +- 命令不可用：`gh --version` 检查是否已安装；`brew reinstall gh` +- 未登录或失效：`gh auth status`；如需重登：`gh auth logout && gh auth login` +- 403 权限不足：检查组织 SSO 授权、仓库可见性与权限范围 +- `--body-file` 不生效：升级 `gh` 到较新版本；或退化为读取文件内容并传入 `--body` +- 仓库识别失败：`gh repo view` 测试当前目录是否已关联 GitHub 仓库；必要时在仓库根目录执行命令 + +## 快速命令示例（macOS） + +- 安装与版本： + - `brew install gh && gh --version` +- 登录（浏览器方式）： + - `gh auth login` +- 查看状态： + - `gh auth status` +- 创建 PR（从文件正文）： + - `gh pr create --base develop --head chore/feature-xyz --title "feat(xyz): add auto layout" --body-file ./.trae/output/pr.body.local.md` + +## 安装与使用（Windows） + +### 安装与更新（Windows） + +- 通过 `winget` 安装：`winget install GitHub.cli` +- 或通过 `chocolatey` 安装：`choco install gh` +- 或到官方发布页下载 MSI 安装包：`https://github.com/cli/cli/releases` +- 验证：`gh --version` + +### 登录与授权（Windows） + +- 执行：`gh auth login` + - 选择 `GitHub.com` + - 选择协议：推荐 `HTTPS` + - 选择登录方式：`Login with a web browser` 或 `Paste an authentication token` +- 组织 SSO：若目标仓库在组织下且开启 SSO，需完成 SSO 授权 +- 查看状态：`gh auth status` +- 退出/切换：`gh auth logout -h github.com` + +### 本地凭据存储（Windows） + +- `gh` 默认使用 Windows Credential Manager 安全存储凭据 +- 无需设置环境变量；作为 `GITHUB_TOKEN` 的备选方案 + +### 在 Job 中的使用（Windows） + +- 同 macOS，`mode: auto` 优先 REST（读取 `GITHUB_TOKEN`），其次 `gh` +- 从文件正文创建： + - `gh pr create --base develop --head <branch> --title "<title>" --body-file ./.trae/output/pr.body.local.md` + +### 常见问题排查（Windows） + +- `gh` 未找到：确认已安装并检查 PATH；`winget list GitHub.cli` 或 `choco upgrade gh` +- 403：检查组织 SSO 授权与仓库权限 +- `--body-file` 不生效：升级 `gh` 到较新版本；退化为 `--body` 读取文件内容 diff --git a/.trae/documents/github-token-local.md b/.trae/documents/github-token-local.md new file mode 100644 index 0000000000..f9ab69f6f6 --- /dev/null +++ b/.trae/documents/github-token-local.md @@ -0,0 +1,199 @@ +# GitHub Token 使用说明（REST 创建 PR） + +- 作用：指导如何获取并在本地配置 `GITHUB_TOKEN`，用于通过 REST API 创建 PR（仓库 Job 在 `mode: auto` 时优先使用 REST）。 + +## 获取 Token（网页端） + +- 登录 GitHub → 右上角头像 → `Settings` +- 左侧导航底部 → `Developer settings` → `Personal access tokens` +- 建议使用 Fine-grained token（推荐）或 Classic token（简化）： + - Fine-grained（推荐）： + - 选择仓库：`VisActor/VChart`（或你需要的目标仓库） + - Permissions（最小权限）： + - 在 `Repository permissions` 列表中勾选： + - `Pull requests` → `Read and write` + - `Contents` → `Read` + - `Metadata` → `Read` + - 若看不到以上权限项，请参考下文“Fine-grained 权限项不可见的排查” + - 设置过期时间（建议 30–90 天）与备注（如：`trae-pr-rest`），点击生成并复制 Token + - Classic（简化）： + - 公有仓库：勾选 `public_repo` + - 私有仓库：勾选 `repo` + - 设置过期时间与备注，生成并复制 Token + +### Classic token 权限最小集合（结合组织仓库场景） + +- 公有仓库（个人仓库）：`public_repo` +- 公有仓库（组织仓库）：`public_repo` + `read:org` + - 若组织开启 SSO：必须在组织的 `Tokens` 页面为该 Token 完成 SSO 授权 + +#### 如何查看组织是否开启了 SSO + +- 组织主页右上角 → `Settings` → `Security` → 查看 `SAML Single Sign-On` 是否为 `Enabled` +- 在 `Organization` → `People` 页面，成员列表顶部若显示 `SAML SSO is enforced`/`Requires SSO` 提示，说明已启用 +- 在 `Settings` → `Developer settings` → `Personal access tokens` 中，已创建的 Token 条目旁若出现 `Enable SSO`/`Configure SSO`/`SSO authorization required` 提示，通常该组织启用了 SSO + +#### 如何为 Token 进行 SSO 授权 + +- 路径一（Token 页面）： + - 进入 `Settings` → `Developer settings` → `Personal access tokens` + - 找到需使用的 Token，点击 `Enable SSO` 或 `Configure SSO` + - 在弹出的授权面板中勾选目标组织（如：`VisActor`），点击 `Authorize` + + 详细步骤（Fine-grained，推荐）： + 1. 登录 GitHub → 右上角头像 → `Settings` + 2. 左侧 `Developer settings` → `Personal access tokens` → `Fine-grained tokens` + 3. 点击 `Generate new token` + 4. `Token name` 与 `Expiration`（建议 30–90 天） + 5. `Resource owner` 选择目标组织（如 `VisActor`） + 6. `Repository access` 选择 `Only select repositories`，勾选 `VChart` + 7. `Repository permissions` 勾选： + - `Pull requests` → `Read and write` + - `Contents` → `Read` + - `Metadata` → `Read` + 8. 点击生成并复制 `github_pat_...` + 9. 在生成完成页，点击 `Configure SSO`（若可见），选择组织并 `Authorize` + +> 注意：Fine‑grained token 通常不会显示 `Configure SSO` 按钮。这是正常行为，因为 Fine‑grained 已在创建阶段绑定了“资源归属（组织）”与“仓库范围”。如果后续 API 访问仍出现 403，请按下方步骤排查。 + +#### Fine‑grained 生成后未出现 “Configure SSO” 的处理（详细） + +- 验证令牌类型与绑定： + - 令牌前缀应为 `github_pat_...`（Fine‑grained），而非 `ghp_...`（Classic） + - 创建时 `Resource owner` 必须选择目标组织（如 `VisActor`） + - `Repository access` 必须选择 `Only select repositories` 并勾选 `VChart` + - `Repository permissions` 勾选：`Pull requests: Read and write`、`Contents: Read`、`Metadata: Read` +- 组织策略检查： + - 让组织管理员在 `Organization → Settings → Policies → Personal access tokens` 确认允许成员使用 Fine‑grained PAT 访问仓库；部分组织需 Owner 审批后方可生效 + - 确认你是组织成员并已完成 SAML SSO 登录（IdP 中被分配到 GitHub 应用） +- 接口级验证： + - 列表 PR 接口：`curl -s -o /dev/null -D - -H "Authorization: Bearer $GITHUB_TOKEN" "https://api.github.com/repos/VisActor/VChart/pulls?per_page=1" | head -n 1` 期望 `HTTP/2 200` + - 若返回 403 且提示禁止 Classic，说明当前使用的并非 Fine‑grained 或未生效；重新导出 `github_pat_...` + - 若返回 403 `Resource not accessible by personal access token`，通常为仓库未被选择或权限未勾选；重新检查 `Repository access/permissions` +- 无需额外 SSO 按钮： + - Fine‑grained 场景下，一般不需要在 Token 列表页额外执行 `Configure SSO`；只需确保组织成员身份、完成组织 SSO 登录，以及令牌绑定到组织与仓库并具备所需权限 + 10. 在终端设置环境变量：`export GITHUB_TOKEN="github_pat_..."` → `source ~/.zshrc` + 11. 验证： + - `curl -s -o /dev/null -D - -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/repos/VisActor/VChart/pulls?per_page=1 | head -n 1` 期待 `HTTP/2 200` + - 若为 `403` 且提示禁止 Classic，则说明未正确使用 Fine-grained 或未完成组织授权 +- 路径二（组织页面）： + - 进入目标组织主页 → `Settings` → `Security` → `SAML Single Sign-On` + - 在 `Authorized credentials`/`Tokens` 区域选择你的 Token，点击授权 + + 详细步骤（Classic，若组织允许）： + 1. 确认组织策略未禁止 Classic PAT；若禁止将出现 403 并提示使用 Fine-grained + 2. 在 `Personal access tokens (classic)` 中创建包含 `repo`、`read:org` 的 Token（`ghp_...`） + 3. 返回 Token 列表，若条目旁出现 `Enable SSO`/`Configure SSO`，点击并为组织授权 + 4. 若按钮不可见，使用以下方式触发授权链接： + - `curl -s -D - -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/orgs/<组织名> | grep -i "X-GitHub-SSO"` + - 从响应头复制 `url=https://github.com/orgs/<组织名>/sso?...`，在浏览器打开并完成授权 + 5. 验证接口同上；若依旧 403，说明组织策略禁止 Classic 或 SSO 未完成 +- CLI 辅助（可选）： + - 使用 `gh` 进行授权刷新：`gh auth refresh -h github.com -s read:org -s repo -s workflow` + - 浏览器会弹出 SSO 授权流程，完成后本地凭据具备组织访问权限 + + 详细步骤（CLI）： + 1. 本机安装并登录 GitHub CLI：`gh auth login` + 2. 触发组织权限刷新：`gh auth refresh -h github.com -s read:org -s repo -s workflow` + 3. 浏览器弹出 SSO 页，选择目标组织并确认授权；完成后返回终端成功提示 + 4. 若希望优先使用本机 CLI 凭据而非环境变量 Token，执行命令时加前缀：`env -u GITHUB_TOKEN` + 5. 示例：`env -u GITHUB_TOKEN gh pr create --base develop --head <branch> --title "<title>" --body-file ./.trae/output/pr.body.local.md` + +#### 看不到 “Enable SSO/Configure SSO” 按钮时的处理 + +- 先确认前置条件： + - 你是目标组织成员；组织已启用并强制 SAML SSO（见上文“如何查看组织是否开启了 SSO”） + - 该 Token 为 Classic token（前缀通常为 `ghp_...`），且作用域包含会访问组织资源的权限（如：`repo`、`read:org`）。仅 `public_repo` 往往不会显示授权入口 +- 使用接口触发授权链接： + - 运行：`curl -s -D - -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/orgs/<组织名> | head -n 20` + - 若组织启用 SSO，响应头会包含 `X-GitHub-SSO: required; url=https://github.com/orgs/<组织名>/sso?authorization_request=...` + - 复制该 `url` 在浏览器打开，按页面提示为当前 Token 完成 SSO 授权 +- 使用 CLI 触发授权： + - `gh auth refresh -h github.com -s read:org -s repo` 后跟随浏览器流程为组织授权 +- 常见原因与修复： + - 组织未启用或未强制 SSO → 按组织设置页确认；未启用时不会出现授权入口 + - 不是组织成员 → 先加入组织，或让管理员邀请 + - Token 作用域不足（仅 `public_repo`）→ 重新生成包含 `repo` 与 `read:org` 的 Classic token，并完成 SSO 授权 + - 已授权过该 Token → 授权入口不再显示，可在组织 SSO 的 `Authorized credentials/Tokens` 区查看 +- 私有仓库（个人/组织）：`repo` + - 若为组织仓库：额外需要 `read:org`，并完成 SSO 授权（如启用） +- 使用 GitHub CLI（gh）进行 PR/工作流相关操作：建议额外授予 `workflow` + +说明：在组织仓库中，仅有 `public_repo` 往往无法通过 REST 或 gh 创建 PR，常见报错为权限不足（Missing scopes: `repo`, `read:org`）。为确保最小可用，请按上面矩阵配置。 +- 若目标仓库在组织（Org）下且开启 SSO，请在 Org 的 `Tokens` 页面对该 Token 进行 SSO 授权，否则 REST 会返回 403。 + +> 组织仓库最小权限提示：公有仓库至少需要 `public_repo + read:org`；私有仓库需要 `repo + read:org`；若使用 gh 并涉及工作流，建议加上 `workflow`。 + +### Fine-grained 权限项不可见的排查 + +1. 选择资源归属：在创建 Fine-grained token 时，`Resource owner` 需选择目标组织（如 `VisActor`），而非个人账户；否则无法选择组织仓库与权限项 +2. 仓库访问范围：在 `Repository access` 选择 `Only select repositories` 并勾选 `VChart`；选择 `All repositories` 在部分组织策略下会隐藏或限制可用权限 +3. 组织策略限制：组织可能限制 Fine-grained token 的可用权限或需要 Owner 审批；若权限列表不出现或出现“需要审批”提示，请联系组织管理员在 `Organization → Settings → Policies → Personal access tokens` 开启并允许仓库访问 +4. 成员与 SSO：需为组织成员且完成 SSO 绑定；非成员或未完成 SSO 时，权限项可能不可用或后续调用被 403 拒绝 +5. 页面刷新与账号切换：确保使用目标 GitHub 账号登录；切换后刷新页面并重新选择组织与仓库 + +验证：创建完成后在终端执行 `curl -s -o /dev/null -D - -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/repos/VisActor/VChart/pulls?per_page=1 | head -n 1`，期待 `HTTP/2 200`。若为 403 且信息提示使用 Fine-grained，则说明当前 Token 未具备所需仓库权限或未完成组织授权。 + +## 在本地存储与加载（macOS） + +- 临时（当前终端会话）： + - `export GITHUB_TOKEN="<你的 Token>"` +- 永久（所有新终端）： + - 编辑 `~/.zshrc`，追加一行： + - `export GITHUB_TOKEN="<你的 Token>"` + - 使其生效： + - `source ~/.zshrc` +- 验证： + - `echo $GITHUB_TOKEN` 应有值（不应为空） + - `curl -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user` 返回 200/用户信息即正常 + +## 在本地存储与加载（Windows） + +- 临时（当前 PowerShell 会话）： + - `$env:GITHUB_TOKEN = "<你的 Token>"` +- 永久（用户环境变量）： + - `setx GITHUB_TOKEN "<你的 Token>"` + - 注意：`setx` 对当前会话不生效，需重启终端或重新登录 +- PowerShell 配置文件（可选）： + - 将以下命令加入 `$PROFILE`： + - `[Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "<你的 Token>", "User")` +- Git Bash（可选）： + - 在 `~/.bashrc` 中追加：`export GITHUB_TOKEN="<你的 Token>"` +- 验证： + - `echo $Env:GITHUB_TOKEN` 应有值 + - `curl -H "Authorization: Bearer $Env:GITHUB_TOKEN" https://api.github.com/user` 返回 200/用户信息即正常 + - 或使用 PowerShell： + - `Invoke-WebRequest -Headers @{ Authorization = "Bearer $Env:GITHUB_TOKEN" } https://api.github.com/user` + +## 在 Job 中的使用 + +- `./.trae/jobs/pr-create-from-body.md`： + - `mode: auto` 默认优先 REST（读取 `GITHUB_TOKEN`），其次 `gh` CLI + - 正文仅从文件读取：`bodyFile` 或默认 `./.trae/output/pr.body.local.md` + - 成功输出 `pr_url`；失败输出错误信息，不展示 compare URL + +## 注意事项 + +- 切勿将 Token 写入仓库文件、提交记录或日志；不要粘贴到聊天或截图 +- 仅授予最小权限：优先使用 Fine-grained 并限定到具体仓库与必要权限 +- 设置合理过期时间并定期轮换；过期后需重新生成并替换本地配置 +- 组织仓库需完成 SSO 授权；否则会出现 403（权限不足） +- 新开终端需确保 `~/.zshrc` 已被加载（`source ~/.zshrc`） + +## 常见问题排查 + +- 401 未授权：检查 `GITHUB_TOKEN` 是否为空、是否过期 +- 403 权限不足： + - 组织仓库缺少 `read:org` 或未完成 SSO 授权 + - Classic token 缺少必要作用域：公有仓库缺 `public_repo`；私有/组织仓库缺 `repo` + - Fine-grained token 权限不足：确认 `Pull requests: Read and write`、`Contents: Read`、`Metadata: Read` +- REST 错误：查看 Job 输出中的错误信息；必要时用 `curl` 测试接口是否返回正常用户/仓库信息 + +## 快速命令示例（macOS） + +- 设置环境变量（一次性）： + - `export GITHUB_TOKEN="ghp_xxx..."` +- 永久配置： + - `echo 'export GITHUB_TOKEN="ghp_xxx..."' >> ~/.zshrc && source ~/.zshrc` +- 验证： + - `curl -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user` diff --git a/.trae/documents/pr-body-generate.solo.md b/.trae/documents/pr-body-generate.solo.md new file mode 100644 index 0000000000..6fb8322f1e --- /dev/null +++ b/.trae/documents/pr-body-generate.solo.md @@ -0,0 +1,36 @@ +# PR 正文生成 Job（Solo 使用说明） + +- 入口文件：`./.trae/jobs/pr-body-generate.md` +- 作用：依据仓库 PR 模版生成完整正文（`pr.body`），输出预览与本地文件，等待人工修订 + +## 参数 +- `lang`：`zh|en`，默认 `zh` +- `title`：可选；用于生成 `generated_title` +- `head`：可选；未提供时自动推导当前分支仅用于展示 +- `labels`：可选标签数组（用于正文元信息展示） +- `rushChangesDir`：默认 `common/changes` +- `localBodyFile`：是否写入本地正文文件（默认 `true`） +- `openEditor`：是否生成后自动在编辑器中打开正文文件（默认 `false`） +- `message`：可选；用于摘要与“背景&方案”的素材 + +## 前置 +- 推荐先完成本地变更与自测；该 Job 不进行提交或推送，仅生成正文。 + +## 使用（Solo） +- 在聊天中发起：“执行 PR Body Job（.trae/jobs/pr-body-generate.md）”，可传： + - `title: '[Auto] feature-legend'` + - （可选）`head: chore/trae-feature-legend-20251222-1030` + - （可选）`localBodyFile: true` + - （可选）`openEditor: true` + - （可选）`message: 'Add legend auto layout and tests'` + +## 输出 + +- `generated_title`：建议标题 +- `generated_body_preview`：完整 Markdown 代码块正文（便于复制） +- `generated_body_file`：默认 `./.trae/output/pr.body.local.md`（纯 Markdown，无外层三引号，不追加任何“Generated by ...”类提示） + +## 人工检查 +- 在编辑器中打开并修订 `./.trae/output/pr.body.local.md` +- 确保以下栏目完整：勾选项、关联链接、背景&方案、Changelog、自测、Summary、Walkthrough +- 修订完成后，执行“创建 PR” Job（`./.trae/jobs/pr-create-from-body.md`） diff --git a/.trae/documents/pr-create-from-body.solo.md b/.trae/documents/pr-create-from-body.solo.md new file mode 100644 index 0000000000..ce69cb6de8 --- /dev/null +++ b/.trae/documents/pr-create-from-body.solo.md @@ -0,0 +1,42 @@ +# 使用正文创建 PR Job（Solo 使用说明） + +- 入口文件：`./.trae/jobs/pr-create-from-body.md` +- 作用：读取经过人工确认的正文（仅本地文件），创建 GitHub PR（支持 REST/gh） + +## 参数 +- `base`：默认 `develop` +- `head`：可选；未提供时自动推导当前分支 +- `title`：必填；PR 标题 +- `lang`：`zh|en`，默认 `zh` +- `labels`：可选标签数组 +- `draft`：是否草稿，默认 `false` +- `useGhCli`：是否使用 `gh` 创建，默认 `true` +- `mode`：`auto|rest|gh`（默认 `auto`，优先 REST） +- `localBodyFile`：是否从默认路径读取正文（默认 `true`） +- `bodyFile`：正文文件路径（优先使用） +- `commitBeforeCreate`：创建前是否自动提交未提交变更（默认 `false`） +- `commitMessage`：自动提交的 commit 消息（默认空） +- `commitAllowEmpty`：是否允许空提交（默认 `false`） +- `pushAfterCommit`：提交后是否自动推送当前分支（默认 `true`） +- `commitMessageStrategy`：提交信息生成策略（`auto|topic|manual`，默认 `auto`） + +## 前置（登录/令牌） +- 优先方案：提供 `GITHUB_TOKEN`（参见 `./.trae/documents/github-token-local.md`） +- 备选方案：本机已登录 GitHub CLI（`gh`）（参见 `./.trae/documents/github-gh-local.md`） + +## 使用（Solo） +- 在聊天中发起：“执行 PR Create Job（.trae/jobs/pr-create-from-body.md）”，参数示例： + - `title: 'feat(legend): add auto layout'` + - `base: develop` + - （可选）`head: chore/trae-feature-legend-20251222-1030` + - `mode: auto` + - `localBodyFile: true` 或 `bodyFile: './.trae/output/pr.body.local.md'` + - （可选）`labels: ['feature', 'legend']` + - （可选）`draft: false` + - （可选）`commitBeforeCreate: true`、`commitMessageStrategy: auto` + +## 输出 +- `pr_url`：创建的 PR 链接（`rest/gh`） + +## 人工检查 +- 提交前确认 `title`、`head` 与正文是否与预期一致 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/auto-flow.md b/.trae/jobs/auto-flow.md index ca898d69a8..6507372567 100644 --- a/.trae/jobs/auto-flow.md +++ b/.trae/jobs/auto-flow.md @@ -20,13 +20,14 @@ parameters: pushAfterCommit: true commitMessageStrategy: auto flowStep: 1 + autoNext: true required_parameters: [] outputs: - autotest_report - rush_change_entries - commit_message - pushed_branch - - compare_url + - pr_url - next_step_hint success_criteria: - flow_step_completed @@ -40,10 +41,10 @@ success_criteria: - 建议提供 `topic` 以优化 PR 标题；未提供时将回退为当前分支名 - 原则：不覆盖子 Job 默认参数；仅透传用户显式提供的参数 -## 单步模式说明 +## 模式说明 -- 本 Job 每次仅执行一个步骤，由 `parameters.flowStep` 指定（取值：`1|2|3|4`）。 -- 步骤完成后进入人工暂停，返回 `next_step_hint` 提示你在对话中输入“执行下一步”推进到下一步。 +- 单步模式：本 Job 每次仅执行一个步骤，由 `parameters.flowStep` 指定（取值：`1|2|3|4|5`）。步骤完成后进入人工暂停，返回 `next_step_hint` 提示你在对话中输入“执行下一步”。 +- 串行模式：当 `parameters.autoNext == true` 时，从当前 `flowStep` 开始按既有步骤顺序自动推进至“完成”，不再返回 `next_step_hint`，而是直接继续下一步。 ## 步骤 @@ -52,7 +53,7 @@ success_criteria: - 执行 Job：`.trae/jobs/auto-test.md` - 传参：`sinceBranch={{baseBranch}}` - 接收输出：`autotest_report=.trae/output/autotest.report.local.md` -- 人工检查点：打开临时报告，确认新增/更新测试与覆盖率是否合理 +- 人工检查点：打开临时报告，确认新增/更新测试与覆盖率是否合理；当 `autoNext==true` 时，在报告生成后自动继续执行下一步。 2. 生成 Rush 变更日志（flowStep=2） @@ -60,7 +61,7 @@ success_criteria: - 传参：`sinceBranch={{baseBranch}}`、`message={{message}}`、`bumpType={{bumpType}}`、`notCommit={{notCommit}}` - 说明：仅透传用户显式提供的参数，未提供时不传，使用子 Job 默认值 - 接收输出：`rush_change_entries`、`computed_bump_type`、`final_message` -- 人工检查点：检查 `common/changes/**` 条目与摘要是否合理 +- 人工检查点：检查 `common/changes/**` 条目与摘要是否合理；当 `autoNext==true` 时，在条目生成后自动继续执行下一步。 3. 智能提交（flowStep=3） @@ -70,25 +71,38 @@ success_criteria: - `message={{message}}`（为空时使用步骤 2 的 `final_message`） - 说明：除 `head` 与 `message` 外，其余参数不强制设置；未提供时使用子 Job 默认值 - 接收输出：`commit_message`、`pushed_branch` -- 人工检查点：确认提交信息与推送分支是否正确 +- 人工检查点：确认提交信息与推送分支是否正确；当 `autoNext==true` 时，在提交与推送完成后自动继续执行下一步。 -4. 创建 PR（flowStep=4） +4. 生成 PR 正文（flowStep=4） -- 执行 Job：`.trae/jobs/pr-create.md` +- 执行 Job：`.trae/jobs/pr-body-generate.md` +- 传参： + - `title='[Auto] {{topic || head}}'` + - `head={{head}}` + - `lang={{lang}}` + - `labels={{labels}}` + - `rushChangesDir=common/changes` + - `localBodyFile=true` +- 说明：仅透传上述必要编排参数，不改变子 Job 默认；未提供的可选项不透传 +- 接收输出：`generated_title`、`generated_body_preview`、`generated_body_file=.trae/output/pr.body.local.md` +- 人工检查点：打开并审阅本地正文文件；当 `autoNext==true` 时，在正文生成后自动继续执行下一步。 + +5. 创建 PR（flowStep=5） + +- 执行 Job：`.trae/jobs/pr-create-from-body.md` - 传参： - `base={{baseBranch}}` - `head={{head}}` - `title='[Auto] {{topic || head}}'` - `lang={{lang}}` - `labels={{labels}}` - - `message={{message}}`（用于正文摘要） - - `bumpType={{bumpType}}` - - `mode={{mode}}`（交互默认 `browser`，生成 Compare URL 与本地正文） + - `mode=auto` - `localBodyFile=true` -- 说明：仅透传上述必要编排参数，不改变子 Job 输出；未提供的可选项不透传，使用子 Job 默认值 -- 接收输出：`compare_url`、`generated_body_preview` -- 人工检查点：在浏览器页面完成最终提交 + - `bodyFile='./.trae/output/pr.body.local.md'` +- 说明：默认优先使用 `GITHUB_TOKEN`（REST），其次 `gh`；不展示 compare URL +- 接收输出：`pr_url` +- 人工检查点：确认 PR 链接与页面内容；当 `autoNext==true` 时，在创建成功后进入“完成”阶段。 -5. 完成 +6. 完成 -- 标记 `flow_step_completed`，返回本步骤对应输出与 `next_step_hint` +- 标记 `flow_step_completed`，返回本步骤对应输出与 `next_step_hint`；当 `autoNext==true` 时，返回本次串行执行的综合输出并结束。 diff --git a/.trae/jobs/pr-body-generate.md b/.trae/jobs/pr-body-generate.md new file mode 100644 index 0000000000..f0163affec --- /dev/null +++ b/.trae/jobs/pr-body-generate.md @@ -0,0 +1,60 @@ +--- +job: pr-body-generate +intent: github-pr-body +version: v1 +domain: github +runner: trae-solo +parameters: + lang: zh + title: '' + head: '' + labels: [] + rushChangesDir: common/changes + localBodyFile: true + openEditor: false +required_parameters: [] +inputs: + autotestReport: .trae/output/autotest.report.local.md +outputs: + - generated_title + - generated_body_preview + - generated_body_file +success_criteria: + - body_generated +--- + +# 生成 PR 正文（支持人工修订） + +## 参数检查 + +- 可选参数：`title`、`head`、`labels` +- 模板语言：`lang`（`zh|en`，默认 `zh`） +- 输出文件：当 `localBodyFile == true`，写入 `./.trae/output/pr.body.local.md` + +## 步骤 + +1. 解析上下文与选择模板 + +- 推导 `head`：`git rev-parse --abbrev-ref HEAD` +- 模板选择：`lang == zh` → `.github/PULL_REQUEST_TEMPLATE/pr_cn.md`；否则 → `.github/PULL_REQUEST_TEMPLATE.md` + +2. 自动填充内容 + +- 勾选项：`branchTypeChecks`（未提供则生成默认占位，如“新功能”、“Workflow”） +- 关联：`issue_links`、`related_pr_links`、`bugserver_ids`（未提供保留占位） +- 背景与方案：基于 `message` 首行摘要与变更上下文生成 +- Changelog：解析 `rushChangesDir`（默认 `common/changes`），填充 `changelog_en` 与 `changelog_zh` +- 自测项：生成默认勾选列表；若存在 `autotestReport`，合并摘要至 Walkthrough +- Summary 与 Walkthrough：包含分支、模板来源、测试摘要与生成信息 + +3. 输出与保存 + +- 生成标题建议：`generated_title = [Auto] {{title || (topic || head)}}` +- 输出完整 `generated_body_preview`（Markdown 代码块，便于复制） +- 当 `localBodyFile == true`：写入 `./.trae/output/pr.body.local.md`（纯 Markdown，无外层三引号）并输出 `generated_body_file` +- 不在文件中追加任何生成标记或提示文本（如“Generated by ...”）；写入内容即为 PR body 原文 +- 当 `openEditor == true`：在编辑器中打开正文文件以便人工修订 + +4. 人工检查点 + +- 请人工审阅并完善 `pr.body`，然后执行“创建 PR” Job（`pr-create-from-body`） diff --git a/.trae/jobs/pr-create-from-body.md b/.trae/jobs/pr-create-from-body.md new file mode 100644 index 0000000000..5392f39c2a --- /dev/null +++ b/.trae/jobs/pr-create-from-body.md @@ -0,0 +1,63 @@ +--- +job: pr-create-from-body +intent: github-pr +version: v1 +domain: github +runner: trae-solo +parameters: + base: develop + head: '' + title: '' + lang: zh + labels: [] + draft: false + useGhCli: true + mode: auto + localBodyFile: true + bodyFile: '' + commitBeforeCreate: false + commitMessage: '' + commitAllowEmpty: false + pushAfterCommit: true + commitMessageStrategy: auto +required_parameters: + - title +inputs: + autotestReport: .trae/output/autotest.report.local.md +outputs: + - pr_url +success_criteria: + - pr_created +--- + +# 使用本地/提供的正文创建 PR + +## 参数检查 + +- 必填参数：`title` +- 正文来源仅支持文件：`bodyFile` → 默认本地 `./.trae/output/pr.body.local.md`（当 `localBodyFile==true`） + +## 步骤 + +1. 前置与正文确定 + +- 推导 `head`：`git rev-parse --abbrev-ref HEAD` +- 确认正文来源：读取 `bodyFile` 或默认文件；若均不可用或正文为空，则失败并提示先执行正文生成 Job +- 使用正文时按“原样传递”，不进行包裹、注释或追加任何提示文本 + +2. 可选自动提交与推送 + +- 检查工作树：`git status --porcelain` +- 当 `commitBeforeCreate == true` 且存在未提交变更：按 `commitMessageStrategy` 生成提交信息，执行提交；当 `pushAfterCommit == true` 推送当前分支 + +3. 创建 PR（模式） + +- `auto`：优先 `GITHUB_TOKEN` 的 REST；其次 `gh`（本机已安装并登录）；否则失败并提示令牌或 CLI 不可用 +- `gh`：`gh pr create --base {{base}} --title "{{title}}" --head {{head}} {{#labels}}--label {{labels}}{{/labels}} {{#draft}}--draft{{/draft}}`；正文优先 `--body-file {{bodyFile}}`，若不支持则读取文件内容传 `--body "..."` +- `rest`：`POST /repos/{owner}/{repo}/pulls`，body 使用正文文本 + + +4. 输出 + +- 成功：输出 `pr_url` +- 失败：输出错误信息，不展示 compare URL 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/<name>/...` 时取 `<name>`；否则取顶层目录（如 `docs`、`tools`、`common`、`.trae`） - - 主题：若提供 `message` 则使用其首行摘要；否则生成 `sync changes before PR (<N> files)` 并附加关键作用域 - - 结果示例：`chore(vchart,tools): sync changes before PR (5 files)` - - `topic`：使用 `title` 或外层 `topic` 作为主题，类型与作用域同上 - - `manual`：使用显式 `commitMessage` - - 运行 `git commit {{#commitAllowEmpty}}--allow-empty{{/commitAllowEmpty}} -m "{{<auto_generated_message>}}"` - - 若 `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，使用浏览器登录后手动创建 From 4ff676882263b2c3f9451647c4cdf71ed59db3aa Mon Sep 17 00:00:00 2001 From: "lixuefei.1313" <lixuef1313@163.com> Date: Wed, 31 Dec 2025 14:39:00 +0800 Subject: [PATCH 04/10] =?UTF-8?q?feat(auto-flow):=20=E5=8D=87=E7=BA=A7?= =?UTF-8?q?=E8=87=AA=E5=8A=A8=E6=B5=81=E7=A8=8B=E5=B9=B6=E4=BC=98=E5=8C=96?= =?UTF-8?q?=20Trae=20=E6=89=A7=E8=A1=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .trae/jobs/auto-flow.md | 2 +- .trae/jobs/pr-create-from-body.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.trae/jobs/auto-flow.md b/.trae/jobs/auto-flow.md index 6507372567..5ae79968b5 100644 --- a/.trae/jobs/auto-flow.md +++ b/.trae/jobs/auto-flow.md @@ -20,7 +20,7 @@ parameters: pushAfterCommit: true commitMessageStrategy: auto flowStep: 1 - autoNext: true + autoNext: false required_parameters: [] outputs: - autotest_report diff --git a/.trae/jobs/pr-create-from-body.md b/.trae/jobs/pr-create-from-body.md index 5392f39c2a..8d009a3882 100644 --- a/.trae/jobs/pr-create-from-body.md +++ b/.trae/jobs/pr-create-from-body.md @@ -12,7 +12,7 @@ parameters: labels: [] draft: false useGhCli: true - mode: auto + mode: gh localBodyFile: true bodyFile: '' commitBeforeCreate: false @@ -52,7 +52,7 @@ success_criteria: 3. 创建 PR（模式） -- `auto`：优先 `GITHUB_TOKEN` 的 REST；其次 `gh`（本机已安装并登录）；否则失败并提示令牌或 CLI 不可用 +- `auto`：优先 `gh`（本机已安装并登录）；其次 `GITHUB_TOKEN` 的 REST；否则失败并提示令牌或 CLI 不可用 - `gh`：`gh pr create --base {{base}} --title "{{title}}" --head {{head}} {{#labels}}--label {{labels}}{{/labels}} {{#draft}}--draft{{/draft}}`；正文优先 `--body-file {{bodyFile}}`，若不支持则读取文件内容传 `--body "..."` - `rest`：`POST /repos/{owner}/{repo}/pulls`，body 使用正文文本 From 7643508bcf7847063190bec69c2dcfdabb57244f Mon Sep 17 00:00:00 2001 From: "lixuefei.1313" <lixuef1313@163.com> Date: Sun, 4 Jan 2026 14:18:11 +0800 Subject: [PATCH 05/10] chore: sync changes before PR (3 files) --- ...36\346\226\275\350\256\241\345\210\222.md" | 91 ++++++++++++ .trae/scripts/dry-run-autotest.sh | 14 ++ .trae/scripts/dry-run-changelog.sh | 16 ++ .trae/scripts/dry-run-commit-smart.sh | 34 +++++ .trae/scripts/dry-run-create-branch.sh | 14 ++ .trae/scripts/dry-run-create-pr.sh | 24 +++ .trae/scripts/dry-run-diff-collect.sh | 12 ++ .trae/scripts/dry-run-pr-body.sh | 13 ++ .trae/scripts/dry-run-release-prep.sh | 10 ++ .trae/scripts/validate-skill.sh | 39 +++++ .trae/skills/ADAPTERS.md | 14 ++ .trae/skills/EXAMPLES.md | 63 ++++++++ .trae/skills/OUTPUTS.md | 14 ++ .trae/skills/README.md | 24 +++ .trae/skills/git.commit-push-smart.skill.yaml | 78 ++++++++++ .trae/skills/git.commit-push-smart/README.md | 40 +++++ .trae/skills/git.create-branch.skill.yaml | 52 +++++++ .trae/skills/git.create-branch/README.md | 32 ++++ .../github.create-pr-from-file.skill.yaml | 132 +++++++++++++++++ .../github.create-pr-from-file/README.md | 45 ++++++ .../skills/github.pr-body-generate.skill.yaml | 85 +++++++++++ .../skills/github.pr-body-generate/README.md | 29 ++++ .trae/skills/pipeline.release-prep.skill.yaml | 140 ++++++++++++++++++ .trae/skills/pipeline.release-prep/README.md | 30 ++++ .../release.changelog-rush-smart.skill.yaml | 92 ++++++++++++ .../release.changelog-rush-smart/README.md | 33 +++++ .../skills/test.autogen-from-diff.skill.yaml | 105 +++++++++++++ .trae/skills/test.autogen-from-diff/README.md | 43 ++++++ .trae/skills/vcs.diff-collect.skill.yaml | 69 +++++++++ .trae/skills/vcs.diff-collect/README.md | 30 ++++ 30 files changed, 1417 insertions(+) create mode 100644 ".trae/documents/\345\260\206 .trae \345\267\245\344\275\234\346\265\201\350\277\201\347\247\273\344\270\272\345\217\257\345\244\215\347\224\250 Skills \347\232\204\350\256\276\350\256\241\344\270\216\345\256\236\346\226\275\350\256\241\345\210\222.md" create mode 100644 .trae/scripts/dry-run-autotest.sh create mode 100644 .trae/scripts/dry-run-changelog.sh create mode 100644 .trae/scripts/dry-run-commit-smart.sh create mode 100644 .trae/scripts/dry-run-create-branch.sh create mode 100644 .trae/scripts/dry-run-create-pr.sh create mode 100644 .trae/scripts/dry-run-diff-collect.sh create mode 100644 .trae/scripts/dry-run-pr-body.sh create mode 100644 .trae/scripts/dry-run-release-prep.sh create mode 100644 .trae/scripts/validate-skill.sh create mode 100644 .trae/skills/ADAPTERS.md create mode 100644 .trae/skills/EXAMPLES.md create mode 100644 .trae/skills/OUTPUTS.md create mode 100644 .trae/skills/README.md create mode 100644 .trae/skills/git.commit-push-smart.skill.yaml create mode 100644 .trae/skills/git.commit-push-smart/README.md create mode 100644 .trae/skills/git.create-branch.skill.yaml create mode 100644 .trae/skills/git.create-branch/README.md create mode 100644 .trae/skills/github.create-pr-from-file.skill.yaml create mode 100644 .trae/skills/github.create-pr-from-file/README.md create mode 100644 .trae/skills/github.pr-body-generate.skill.yaml create mode 100644 .trae/skills/github.pr-body-generate/README.md create mode 100644 .trae/skills/pipeline.release-prep.skill.yaml create mode 100644 .trae/skills/pipeline.release-prep/README.md create mode 100644 .trae/skills/release.changelog-rush-smart.skill.yaml create mode 100644 .trae/skills/release.changelog-rush-smart/README.md create mode 100644 .trae/skills/test.autogen-from-diff.skill.yaml create mode 100644 .trae/skills/test.autogen-from-diff/README.md create mode 100644 .trae/skills/vcs.diff-collect.skill.yaml create mode 100644 .trae/skills/vcs.diff-collect/README.md diff --git "a/.trae/documents/\345\260\206 .trae \345\267\245\344\275\234\346\265\201\350\277\201\347\247\273\344\270\272\345\217\257\345\244\215\347\224\250 Skills \347\232\204\350\256\276\350\256\241\344\270\216\345\256\236\346\226\275\350\256\241\345\210\222.md" "b/.trae/documents/\345\260\206 .trae \345\267\245\344\275\234\346\265\201\350\277\201\347\247\273\344\270\272\345\217\257\345\244\215\347\224\250 Skills \347\232\204\350\256\276\350\256\241\344\270\216\345\256\236\346\226\275\350\256\241\345\210\222.md" new file mode 100644 index 0000000000..81f52123a8 --- /dev/null +++ "b/.trae/documents/\345\260\206 .trae \345\267\245\344\275\234\346\265\201\350\277\201\347\247\273\344\270\272\345\217\257\345\244\215\347\224\250 Skills \347\232\204\350\256\276\350\256\241\344\270\216\345\256\236\346\226\275\350\256\241\345\210\222.md" @@ -0,0 +1,91 @@ +## 背景与现状 +- 当前仓库在 .trae 目录下以“Job + Solo 文档”的方式描述自动化任务流，包括单测自动生成、智能提交与推送、PR 创建、分支管理、Changelog 等。 +- 典型 Job 文件包含清晰的元数据与参数约束，结构化步骤与成功标准，示例： + - 作业总览与用法：[README.md](file:///Users/bytedance/Documents/GitHub/VChart/.trae/jobs/README.md) + - 自动化单测生成：[auto-test.md](file:///Users/bytedance/Documents/GitHub/VChart/.trae/jobs/auto-test.md) 与说明文档：[auto-test.solo.md](file:///Users/bytedance/Documents/GitHub/VChart/.trae/documents/auto-test.solo.md) + - 智能提交推送：[commit-smart.md](file:///Users/bytedance/Documents/GitHub/VChart/.trae/jobs/commit-smart.md) + - 本地正文创建 PR：[pr-create-from-body.md](file:///Users/bytedance/Documents/GitHub/VChart/.trae/jobs/pr-create-from-body.md) + +## 适配性评估（是否适合迁移为 Skills） +- 结构化良好：现有 Job 已具备“名称/意图/参数/输入输出/成功标准/步骤”的技能化必要元素，迁移成本低。 +- 可移植性可控：多数步骤依赖标准 CLI（git、gh、rush、jest），通过工具抽象与参数化可跨 IDE 复用。 +- 领域清晰：任务聚焦“测试/Git/GitHub”，适合拆分为多个职责单一的技能单元，便于组合编排。 +- 风险与边界： + - 环境依赖（rush、ts-jest、gh CLI）需在技能层声明“前置条件 + 兜底模式（REST/跳过）”。 + - 写文件与运行测试属“有副作用”，Skills 需提供 dry-run/preview/stopOnError 等保护与可观测性。 +- 结论：适合迁移。推荐“分层拆分 + 通用工具适配 + 渐进迁移”，先迁 Git/PR 类，随后迁 Autotest 编排与子技能。 + +## 迁移目标与原则 +- 目标：将 .trae/jobs 中的任务流标准化为跨 IDE 可复用的 Skills（带清晰的输入/输出/依赖/步骤），保留 Solo 可运行性，同时增设通用工具适配（兼容 gh/REST、CLI/协议）。 +- 原则： + - 单一职责、可组合：一个技能只解决一个明确问题；复杂流程由编排技能调用多个子技能。 + - 明确契约：参数类型/默认值/必填项、输出物路径与结构需固定、错误与成功标准一致可测。 + - 安全与幂等：dry-run 默认开启于危险操作；文件写入有覆盖策略；外部 API 使用令牌与最小权限。 + +## 技能清单与映射 +- github.create-pr-from-file（来源：pr-create-from-body） + - 输入：base、head、title（必填）、labels、draft、mode（auto|gh|rest）、bodyFile/localBodyFile、commitBeforeCreate 等 + - 工具适配：优先 gh CLI，其次 GitHub REST（GITHUB_TOKEN），失败时明确报错与指引 + - 输出：pr_url；成功标准：pr_created +- git.commit-push-smart（来源：commit-smart） + - 输入：head、commitAllowEmpty、pushAfterCommit、commitMessageStrategy、message + - 步骤：检测工作树 → 生成信息（路径/changes 类型推断）→ commit → push（可选） + - 输出：commit_message、pushed_branch；成功标准：commit_created_or_skipped +- vcs.diff-collect（Autotest 子技能） + - 输入：sinceBranch、includeWorkingTree + - 输出：变更文件与行级差异结构体（JSON） +- test.autogen-from-diff（来源：auto-test） + - 输入：project、mode、noSnapshot、onlyNew、applyManualOverrides、replaceAutogen 等 + - 步骤：分析导出符号 → 生成/增量更新 __tests__/*.test.ts（含函数级 JSDoc 注释）→ 运行覆盖率 → 写临时报告 + - 输出：test_files、snapshots、coverage_report、manual_nodes、temp_markdown_report；成功标准同原 Job +- github.pr-body-generate（来源：pr-body-generate）与 changelog.rush-smart、branch.create 等（按现有 Job 逐项映射） + +## 技能规范（建议的 Skill Manifest） +- 顶层字段：id、version、description、domain、tags、runner（solo|orchestrator|mcp）、dependencies（cli/tools）、env（必需变量）。 +- parameters：name、type（string|boolean|enum|file）、default、required、validate、visibility（advanced）。 +- inputs/outputs：路径与结构约定（例如输出报告默认至 .trae/output/**，可覆盖）。 +- success_criteria：机器可判定的条件列表；errors：常见失败及建议。 +- steps： + - type: command|tool|script|composite + - uses: git/gh/github-rest/rush/jest 等适配器 + - with: 具体参数映射；guards：前置检查与兜底策略；dryRun: true/false；continueOnError: bool； +- 观测性：每步产生日志事件与可视化摘要，临时报告路径可配置。 + +## 通用工具抽象与 MCP 适配 +- GitHub：抽象两种实现 + - gh CLI：gh pr create ... + - REST：POST /repos/{owner}/{repo}/pulls（从环境读取 GITHUB_TOKEN） +- Git：抽象常用命令（rev-parse、status、add/commit/push、diff），允许替换成 IDE 的 Shell 执行器。 +- 测试与覆盖率：抽象 rush/jest 执行器，支持 project 定位与并行；无 rush 环境时回退至 npm/yarn。 +- 报告：统一写入（md|json），在不同 IDE 通过文件系统可见。 + +## 迁移步骤（渐进式） +1. 定义 Skill 模板与约束 + - 提炼通用 manifest 与步骤 DSL；建立“工具适配”层（gh/rest、git/shell、rush/jest）。 +2. 先迁 Git/PR 类（低风险） + - 将 commit-smart 与 pr-create-from-body 转为 skills；实现 gh/rest 双路；发布 dry-run 默认开。 +3. 引入编排技能 + - 将 auto-test 拆为 orchestrator + 子技能（diff-collect、analysis、generate-tests、run-coverage、report）。 +4. 标准化输出物与路径 + - 报告/快照/测试文件命名与路径统一；保留 .trae/output，允许通过参数覆盖。 +5. 加入校验与回退 + - 环境检查（CLI、令牌、rush）；无法满足时按策略回退或提示。 +6. 文档与示例 + - 为每个技能提供独立 README 与示例调用；保留原 .trae/documents 作为技能说明。 +7. 验证与兼容发布 + - 在 Trae 中以 Solo 运行验证；在其他 IDE 通过“工具适配器 + 文件 IO”验证；发布 v1。 + +## 验证与发布策略 +- 单元验证：每个技能提供“模拟输入 → 期望输出”的用例；dry-run 模式检查日志与报告。 +- 集成验证：在真实仓库上跑全流程（先 Git/PR，再 Autotest）。 +- 版本与回滚：语义化版本；变更日志；失败可回滚到 Job 运行方式。 + +## 风险与注意事项 +- 环境差异：Windows/Mac/Linux 下命令差异与路径分隔符；rush/jest 可用性。 +- 令牌与安全：不在仓库写入任何密钥；按环境变量读取；失败明确提示。 +- 幂等与覆盖：replaceAutogen 参数遵循默认“增量插入，不覆盖人工块”。 + +## 里程碑与交付 +- M1：完成 Skill 模板与工具适配层；迁移 commit-smart、pr-create-from-body。 +- M2：完成 Autotest 子技能与编排；发布一致性报告格式；形成复用规范。 +- M3：补齐 changelog、branch、pr-body-generate 等技能；完善文档与示例。 \ No newline at end of file diff --git a/.trae/scripts/dry-run-autotest.sh b/.trae/scripts/dry-run-autotest.sh new file mode 100644 index 0000000000..f5e22cbff8 --- /dev/null +++ b/.trae/scripts/dry-run-autotest.sh @@ -0,0 +1,14 @@ +#!/usr/bin/env bash +set -euo pipefail + +## 函数：检查 rush/jest 可用性 +check_tools() { + local has_rush=0; command -v rush >/dev/null 2>&1 && has_rush=1 + local has_jest=0; command -v jest >/dev/null 2>&1 && has_jest=1 + echo "$has_rush:$has_jest" +} + +tools=$(check_tools) +echo "[DRY-RUN] rush/jest = $tools" +echo "[DRY-RUN] report path = ./.trae/output/autotest.report.local.md" + diff --git a/.trae/scripts/dry-run-changelog.sh b/.trae/scripts/dry-run-changelog.sh new file mode 100644 index 0000000000..6983bfd398 --- /dev/null +++ b/.trae/scripts/dry-run-changelog.sh @@ -0,0 +1,16 @@ +#!/usr/bin/env bash +set -euo pipefail + +## 函数：判定 bump 类型 +compute_bump() { + local base=${1:-develop} + local subjects + subjects=$(git log --pretty=%s "$base"...HEAD | tr 'A-Z' 'a-z') + if echo "$subjects" | grep -E 'breaking change|!'; then echo major; return; fi + if echo "$subjects" | grep -E '^feat'; then echo minor; return; fi + echo patch +} + +bt=$(compute_bump "${1:-develop}") +echo "[DRY-RUN] computed_bump_type=$bt" + diff --git a/.trae/scripts/dry-run-commit-smart.sh b/.trae/scripts/dry-run-commit-smart.sh new file mode 100644 index 0000000000..1305d3f5e8 --- /dev/null +++ b/.trae/scripts/dry-run-commit-smart.sh @@ -0,0 +1,34 @@ +#!/usr/bin/env bash +set -euo pipefail + +## 函数：检查 git 与工作树状态 +check_git() { + git --version >/dev/null 2>&1 || { echo "[ERROR] git 未安装"; exit 1; } + git rev-parse --is-inside-work-tree >/dev/null 2>&1 || { echo "[ERROR] 非 git 仓库"; exit 1; } +} + +## 函数：推导分支名 +resolve_head() { + git rev-parse --abbrev-ref HEAD +} + +## 函数：模拟提交信息生成 +derive_message() { + local strategy=${1:-auto} + local message=${2:-} + if [[ "$strategy" == "manual" && -n "$message" ]]; then + echo "$message" + else + local count + count=$(git status --porcelain | wc -l | tr -d ' ') + echo "chore: sync changes before PR (${count} files)" + fi +} + +check_git +HEAD_BRANCH=$(resolve_head) +COMMIT_MSG=$(derive_message "${1:-auto}" "${2:-}") +echo "[DRY-RUN] head=$HEAD_BRANCH" +echo "[DRY-RUN] commit_message=$COMMIT_MSG" +echo "[DRY-RUN] pushAfterCommit=${3:-true}" + diff --git a/.trae/scripts/dry-run-create-branch.sh b/.trae/scripts/dry-run-create-branch.sh new file mode 100644 index 0000000000..7f9168cb45 --- /dev/null +++ b/.trae/scripts/dry-run-create-branch.sh @@ -0,0 +1,14 @@ +#!/usr/bin/env bash +set -euo pipefail + +## 函数：生成分支名 +gen_branch() { + local prefix=${1:-chore/trae} + local topic=${2:?topic 必填} + local ts; ts=$(date +%Y%m%d-%H%M) + echo "$prefix-$topic-$ts" +} + +bn=$(gen_branch "${1:-chore/trae}" "${2:-}") +echo "[DRY-RUN] branch_name=$bn" + diff --git a/.trae/scripts/dry-run-create-pr.sh b/.trae/scripts/dry-run-create-pr.sh new file mode 100644 index 0000000000..d4d22f77f1 --- /dev/null +++ b/.trae/scripts/dry-run-create-pr.sh @@ -0,0 +1,24 @@ +#!/usr/bin/env bash +set -euo pipefail + +## 函数：检查 gh 或 REST 可用性 +check_channels() { + local has_gh=0 + command -v gh >/dev/null 2>&1 && has_gh=1 + local has_token=0 + [[ -n "${GITHUB_TOKEN:-}" ]] && has_token=1 + echo "$has_gh:$has_token" +} + +## 函数：读取正文文件 +read_body() { + local file=${1:-./.trae/output/pr.body.local.md} + [[ -f "$file" ]] || { echo "[ERROR] 正文文件不存在: $file"; exit 1; } + wc -c "$file" | awk '{print $1}' +} + +chan=$(check_channels) +size=$(read_body "${1:-./.trae/output/pr.body.local.md}") +echo "[DRY-RUN] channels gh/token = $chan" +echo "[DRY-RUN] body size = $size bytes" + diff --git a/.trae/scripts/dry-run-diff-collect.sh b/.trae/scripts/dry-run-diff-collect.sh new file mode 100644 index 0000000000..2d0cdb801b --- /dev/null +++ b/.trae/scripts/dry-run-diff-collect.sh @@ -0,0 +1,12 @@ +#!/usr/bin/env bash +set -euo pipefail + +## 函数：采集差异摘要 +collect_diff() { + local base=${1:-develop} + git fetch --all --prune >/dev/null 2>&1 || true + git diff --name-status --diff-filter=AMR "$base"...HEAD | head -n 20 +} + +collect_diff "${1:-develop}" + diff --git a/.trae/scripts/dry-run-pr-body.sh b/.trae/scripts/dry-run-pr-body.sh new file mode 100644 index 0000000000..316a2f2298 --- /dev/null +++ b/.trae/scripts/dry-run-pr-body.sh @@ -0,0 +1,13 @@ +#!/usr/bin/env bash +set -euo pipefail + +## 函数：模板选择 +select_tpl() { + local lang=${1:-zh} + if [[ "$lang" == "zh" ]]; then echo .github/PULL_REQUEST_TEMPLATE/pr_cn.md; else echo .github/PULL_REQUEST_TEMPLATE.md; fi +} + +tpl=$(select_tpl "${1:-zh}") +echo "[DRY-RUN] template=$tpl" +echo "[DRY-RUN] output=./.trae/output/pr.body.local.md" + diff --git a/.trae/scripts/dry-run-release-prep.sh b/.trae/scripts/dry-run-release-prep.sh new file mode 100644 index 0000000000..793ee8ac1b --- /dev/null +++ b/.trae/scripts/dry-run-release-prep.sh @@ -0,0 +1,10 @@ +#!/usr/bin/env bash +set -euo pipefail + +## 函数：展示串行步骤 +show_steps() { + echo "1) Autotest → 2) Changelog → 3) Commit → 4) PR Body → 5) PR Create" +} + +show_steps + diff --git a/.trae/scripts/validate-skill.sh b/.trae/scripts/validate-skill.sh new file mode 100644 index 0000000000..5fd39d5654 --- /dev/null +++ b/.trae/scripts/validate-skill.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +set -euo pipefail + +skill="${1:-}" +if [[ -z "$skill" ]]; then + echo "usage: validate-skill <skill-id> [args]"; exit 1 +fi +shift || true + +case "$skill" in + git.commit-push-smart) + exec ./.trae/scripts/dry-run-commit-smart.sh "$@" + ;; + github.create-pr-from-file) + exec ./.trae/scripts/dry-run-create-pr.sh "$@" + ;; + vcs.diff-collect) + exec ./.trae/scripts/dry-run-diff-collect.sh "$@" + ;; + test.autogen-from-diff) + exec ./.trae/scripts/dry-run-autotest.sh "$@" + ;; + release.changelog-rush-smart) + exec ./.trae/scripts/dry-run-changelog.sh "$@" + ;; + git.create-branch) + exec ./.trae/scripts/dry-run-create-branch.sh "$@" + ;; + github.pr-body-generate) + exec ./.trae/scripts/dry-run-pr-body.sh "$@" + ;; + pipeline.release-prep) + exec ./.trae/scripts/dry-run-release-prep.sh "$@" + ;; + *) + echo "unknown skill: $skill"; exit 1 + ;; +esac + diff --git a/.trae/skills/ADAPTERS.md b/.trae/skills/ADAPTERS.md new file mode 100644 index 0000000000..e4b9d2de55 --- /dev/null +++ b/.trae/skills/ADAPTERS.md @@ -0,0 +1,14 @@ +# 工具适配与回退策略 + +## 映射 +- gh-cli: 使用 GitHub CLI 创建 PR、管理 Issue 等。 +- github-rest: 使用 REST API（读取环境变量 GITHUB_TOKEN）。 +- git-cli: 执行 rev-parse、status、add/commit/push、diff 等。 +- rush-cli: 执行测试与覆盖率；无 rush 时回退 npm/yarn。 +- jest-cli: 测试运行器；可由框架插件替换。 + +## 回退 +- PR 创建：优先 gh-cli；不可用则使用 github-rest；均不可用则返回明确错误。 +- 覆盖率运行：无 rush 时改用 npm/yarn 脚本。 +- 差异采集：无 git 时直接失败并返回环境提示。 + diff --git a/.trae/skills/EXAMPLES.md b/.trae/skills/EXAMPLES.md new file mode 100644 index 0000000000..7685ca5265 --- /dev/null +++ b/.trae/skills/EXAMPLES.md @@ -0,0 +1,63 @@ +# Skills 示例调用 + +## git.commit-push-smart + +- 调用：`skill: git.commit-push-smart { pushAfterCommit: true, commitMessageStrategy: 'auto' }` +- 预期输出：commit_message、pushed_branch + +## github.create-pr-from-file + +- 调用：`skill: github.create-pr-from-file { title: 'feat: add legend', mode: 'auto' }` +- 预期输出：pr_url + +## vcs.diff-collect + +- 调用：`skill: vcs.diff-collect { sinceBranch: 'develop', includeWorkingTree: true }` +- 预期输出：diff_json => `./.trae/output/diff.json` + +## test.autogen-from-diff + +- 调用：`skill: test.autogen-from-diff { project: '@visactor/vchart', onlyNew: false }` +- 预期输出：test_files、snapshots、coverage_report、manual_nodes、temp_markdown_report + +## release.changelog-rush-smart + +- 调用：`skill: release.changelog-rush-smart { sinceBranch: 'develop', bumpType: 'auto' }` +- 预期输出：rush_change_entries、computed_bump_type、final_message + +## git.create-branch + +- 调用：`skill: git.create-branch { baseBranch: 'develop', branchPrefix: 'feat/chart', topic: 'v2-legend', useDateSuffix: true }` +- 预期输出：branch_name + +## pipeline.release-prep + +- 调用（单步）：`skill: pipeline.release-prep { flowStep: 1 }` +- 调用（串行）：`skill: pipeline.release-prep { autoNext: true }` +- 预期输出：autotest_report、rush_change_entries、commit_message、pushed_branch、pr_url + +## 验证入口 + +- 统一入口脚本：`./.trae/scripts/validate-skill.sh <skill-id> [args]` +- 示例： + - `./.trae/scripts/validate-skill.sh github.create-pr-from-file ./.trae/output/pr.body.local.md` + - `./.trae/scripts/validate-skill.sh vcs.diff-collect develop` + +## 单步执行说明（pipeline.release-prep） + +- 步骤一（Autotest）： + - 调用：`skill: pipeline.release-prep { flowStep: 1 }` + - 输出：`autotest_report`，并返回 `next_step_hint` 提示下一步为 `flowStep=2` +- 步骤二（Changelog）： + - 调用：`skill: pipeline.release-prep { flowStep: 2, message: 'feat: xxx', bumpType: 'auto' }` + - 输出：`rush_change_entries`、`computed_bump_type`、`final_message`，`next_step_hint=flowStep=3` +- 步骤三（Commit）： + - 调用：`skill: pipeline.release-prep { flowStep: 3, commitMessageStrategy: 'auto', pushAfterCommit: true }` + - 输出：`commit_message`、`pushed_branch`，`next_step_hint=flowStep=4` +- 步骤四（PR 正文生成）： + - 调用：`skill: pipeline.release-prep { flowStep: 4, title: '[Auto] xxx', lang: 'zh', labels: ['changelog','test'] }` + - 输出：`generated_body_file=.trae/output/pr.body.local.md`，`next_step_hint=flowStep=5` +- 步骤五（创建 PR）： + - 调用：`skill: pipeline.release-prep { flowStep: 5 }` + - 输出：`pr_url` +- 说明：单步模式仅执行指定步骤；完成后按 `next_step_hint` 继续调用下一步。若希望自动推进，使用 `autoNext: true`。 diff --git a/.trae/skills/OUTPUTS.md b/.trae/skills/OUTPUTS.md new file mode 100644 index 0000000000..36e7f567eb --- /dev/null +++ b/.trae/skills/OUTPUTS.md @@ -0,0 +1,14 @@ +# 输出物与路径规范 + +## 默认位置 +- 差异 JSON：`./.trae/output/diff.json` +- Autotest 报告：`./.trae/output/autotest.report.local.md` +- PR 正文：`./.trae/output/pr.body.local.md` + +## 可覆盖 +- 所有输出路径均可通过技能参数覆盖，要求为相对仓库根路径的可写位置。 + +## 命名约定 +- 测试文件：`__tests__/*.test.ts` +- 自动化区块：名称前缀 `autogen:`，避免覆盖人工块。 + diff --git a/.trae/skills/README.md b/.trae/skills/README.md new file mode 100644 index 0000000000..f0367609e0 --- /dev/null +++ b/.trae/skills/README.md @@ -0,0 +1,24 @@ +# Skills 概述与迁移规范 + +## 目标 +- 将现有 .trae/jobs 中的任务流标准化为跨 IDE 可复用的 Skills，保留 Solo 可运行性，并提供工具适配（gh/REST、git/shell、rush/jest）。 + +## 结构 +- 每个技能以 `.skill.yaml` 描述：id、version、description、domain、runner、dependencies、env、parameters、inputs、outputs、success_criteria、steps。 +- 步骤支持 command、tool、composite 类型，具备 guards、dryRun、continueOnError 与 uses 映射（gh-cli、github-rest、git-cli、rush-cli、jest-cli）。 + +## 适配层 +- gh-cli 与 github-rest 双路；git-cli 基于系统 Shell；rush-cli 与 jest-cli 可替换为 npm/yarn。 + +## 输出 +- 报告与中间产物默认写入 `.trae/output/**`，可通过参数覆盖。 + +## 示例调用 +- 提交并推送：`skill: git.commit-push-smart { pushAfterCommit: true, commitMessageStrategy: 'auto' }` +- 创建 PR：`skill: github.create-pr-from-file { title: 'feat: add legend', mode: 'auto' }` +- 采集差异：`skill: vcs.diff-collect { sinceBranch: 'develop' }` +- 单测生成：`skill: test.autogen-from-diff { project: '@visactor/vchart' }` + +## 环境前置 +- gh-cli 或 GITHUB_TOKEN；git 已安装；rush/jest（或 npm/yarn 替代）。 +- 未满足前置时按技能中的 guards 与回退策略处理。 diff --git a/.trae/skills/git.commit-push-smart.skill.yaml b/.trae/skills/git.commit-push-smart.skill.yaml new file mode 100644 index 0000000000..f3d3809185 --- /dev/null +++ b/.trae/skills/git.commit-push-smart.skill.yaml @@ -0,0 +1,78 @@ +id: git.commit-push-smart +version: v1 +description: 智能生成提交信息并推送当前分支 +domain: git +runner: orchestrator +dependencies: + - git-cli +env: {} +parameters: + - name: head + type: string + default: '' + required: false + - name: commitAllowEmpty + type: boolean + default: false + required: false + - name: pushAfterCommit + type: boolean + default: true + required: false + - name: commitMessageStrategy + type: enum + values: [auto, manual] + default: auto + required: false + - name: message + type: string + default: '' + required: false +inputs: {} +outputs: + - name: commit_message + - name: pushed_branch +success_criteria: + - commit_created_or_skipped +steps: + - name: resolve-head + type: command + uses: git-cli + with: + command: git rev-parse --abbrev-ref HEAD + when: "parameters.head == ''" + save_as: head + - name: check-working-tree + type: command + uses: git-cli + with: + command: git status --porcelain + save_as: workingTree + - name: skip-if-empty + type: composite + with: + condition: "workingTree == '' && parameters.commitAllowEmpty == false" + set_outputs: + commit_message: '' + pushed_branch: "${head}" + mark_success: commit_created_or_skipped + - name: derive-message + type: composite + with: + strategy: "parameters.commitMessageStrategy" + manual_message: "parameters.message" + save_as: commitMessage + - name: commit + type: command + uses: git-cli + with: + command: "git add --all && git commit ${parameters.commitAllowEmpty ? '--allow-empty ' : ''}-m \"${commitMessage}\"" + save_as: commit_message + - name: push + type: command + uses: git-cli + with: + command: "git push -u origin ${head}" + when: "parameters.pushAfterCommit == true" + save_as: pushed_branch + diff --git a/.trae/skills/git.commit-push-smart/README.md b/.trae/skills/git.commit-push-smart/README.md new file mode 100644 index 0000000000..9fc61bcf25 --- /dev/null +++ b/.trae/skills/git.commit-push-smart/README.md @@ -0,0 +1,40 @@ +## 概述 +- 技能：git.commit-push-smart（智能提交并可选推送） +- 作用：检测工作树、生成提交信息、执行 commit 与 push（可选） + +## 参数 +- head（string，默认 ''）：目标分支；为空时自动推导当前分支 +- commitAllowEmpty（boolean，默认 false）：允许空提交 +- pushAfterCommit（boolean，默认 true）：提交后推送当前分支 +- commitMessageStrategy（enum: auto|manual，默认 auto）：提交信息生成策略 +- message（string，默认 ''）：手动消息（当 strategy=manual 或用于覆盖自动主题） + +## 输出 +- commit_message：实际提交信息 +- pushed_branch：推送分支名（当 pushAfterCommit=true） + +## 成功标准 +- commit_created_or_skipped：当工作树为空且不允许空提交时，视为“跳过但成功” + +## 失败案例与指引 +- 无 git/仓库未初始化：请在仓库根目录执行，确保已安装 git 且有有效远程 +- commitlint 不通过（如后续校验触发）：调整 message 或使用自动策略生成 +- 推送失败（权限/网络）：检查远程权限与网络代理；必要时稍后重试 + +## 示例调用 +- skill: git.commit-push-smart { pushAfterCommit: true, commitMessageStrategy: 'auto' } + +## 失败返回示例 +- 工作树为空且不允许空提交： + - 返回：commit_created_or_skipped + - 日志示例： + - `[INFO] working tree clean, skip commit` +- 推送失败（远程拒绝）： + - 返回：错误信息（非零退出） + - 日志示例： + - `! [rejected] HEAD -> origin/HEAD (fetch first)` + +## 修复步骤 +- 若需强制提交：设置 `commitAllowEmpty: true` 或在工作树中加入实际变更 +- 推送被拒绝：先执行 `git pull --rebase` 或 `git fetch && git merge`，解决冲突后再推送 +- 无远程权限：检查凭据与网络代理，确保 `origin` 指向可写仓库 diff --git a/.trae/skills/git.create-branch.skill.yaml b/.trae/skills/git.create-branch.skill.yaml new file mode 100644 index 0000000000..ab719f161b --- /dev/null +++ b/.trae/skills/git.create-branch.skill.yaml @@ -0,0 +1,52 @@ +id: git.create-branch +version: v1 +description: 从基础分支创建开发分支并返回分支名 +domain: git +runner: orchestrator +dependencies: + - git-cli +env: {} +parameters: + - name: baseBranch + type: string + default: develop + required: false + - name: branchPrefix + type: string + default: chore/trae + required: false + - name: topic + type: string + required: true + - name: useDateSuffix + type: boolean + default: true + required: false +outputs: + - name: branch_name +success_criteria: + - branch_created + - clean_working_tree +steps: + - name: sync-base + type: command + uses: git-cli + with: + command: "git fetch --all --prune && git checkout ${parameters.baseBranch} && git pull origin ${parameters.baseBranch}" + - name: gen-name + type: composite + with: + rule: "${parameters.branchPrefix}-${parameters.topic}-${parameters.useDateSuffix ? '${YYYYMMDD-HHMM}' : ''}" + save_as: branch_name + - name: create + type: command + uses: git-cli + with: + command: "git checkout -b ${branch_name}" + - name: verify + type: command + uses: git-cli + with: + command: "git status --porcelain" + save_as: workingTree + diff --git a/.trae/skills/git.create-branch/README.md b/.trae/skills/git.create-branch/README.md new file mode 100644 index 0000000000..9beb82d742 --- /dev/null +++ b/.trae/skills/git.create-branch/README.md @@ -0,0 +1,32 @@ +## 概述 +- 技能：git.create-branch（创建开发分支） +- 作用：同步基础分支、生成规范分支名并创建新分支 + +## 参数 +- baseBranch（string，默认 develop） +- branchPrefix（string，默认 chore/trae） +- topic（string，必填） +- useDateSuffix（boolean，默认 true） + +## 输出 +- branch_name：创建的分支名 + +## 成功标准 +- branch_created、clean_working_tree + +## 失败案例与指引 +- checkout/pull 失败：检查远程权限与网络 +- 命名冲突：修改 topic 或关闭日期后缀避免重复 + +## 示例调用 +- skill: git.create-branch { baseBranch: 'develop', branchPrefix: 'feat/chart', topic: 'v2-legend' } + +## 失败返回示例 +- 拉取基础分支失败： + - 返回：`fatal: could not read from remote repository` +- 分支名冲突： + - 返回：`fatal: A branch named '<name>' already exists` + +## 修复步骤 +- 检查网络与远程权限；必要时重新登录凭据或更新远程 URL +- 修改 `topic` 或关闭日期后缀以生成唯一分支名 diff --git a/.trae/skills/github.create-pr-from-file.skill.yaml b/.trae/skills/github.create-pr-from-file.skill.yaml new file mode 100644 index 0000000000..2a76ee5883 --- /dev/null +++ b/.trae/skills/github.create-pr-from-file.skill.yaml @@ -0,0 +1,132 @@ +id: github.create-pr-from-file +version: v1 +description: 使用本地或指定正文文件创建 GitHub PR +domain: github +runner: orchestrator +dependencies: + - gh-cli + - github-rest +env: + GITHUB_TOKEN: optional +parameters: + - name: base + type: string + default: develop + required: false + - name: head + type: string + default: '' + required: false + - name: title + type: string + required: true + - name: labels + type: array + default: [] + required: false + - name: draft + type: boolean + default: false + required: false + - name: mode + type: enum + values: [auto, gh, rest] + default: auto + required: false + - name: localBodyFile + type: boolean + default: true + required: false + - name: bodyFile + type: string + default: ./.trae/output/pr.body.local.md + required: false + - name: commitBeforeCreate + type: boolean + default: false + required: false + - name: commitMessage + type: string + default: '' + required: false + - name: commitAllowEmpty + type: boolean + default: false + required: false + - name: pushAfterCommit + type: boolean + default: true + required: false + - name: commitMessageStrategy + type: enum + values: [auto, manual] + default: auto + required: false +inputs: + - name: body_file + type: file + default: ./.trae/output/pr.body.local.md +outputs: + - name: pr_url +success_criteria: + - pr_created +steps: + - name: resolve-head + type: command + uses: git-cli + with: + command: git rev-parse --abbrev-ref HEAD + when: "parameters.head == ''" + save_as: head + - name: read-body + type: command + uses: shell + with: + command: "cat ${parameters.bodyFile}" + save_as: prBody + - name: fail-if-empty-body + type: composite + with: + condition: "prBody == ''" + error: "PR 正文为空或文件不存在" + - name: optional-commit + type: composite + with: + condition: "parameters.commitBeforeCreate == true" + sequence: + - type: command + uses: git-cli + with: + command: git status --porcelain + save_as: workingTree + - type: command + uses: git-cli + with: + command: "git add --all && git commit ${parameters.commitAllowEmpty ? '--allow-empty ' : ''}-m \"${parameters.commitMessage != '' ? parameters.commitMessage : 'sync changes before PR'}\"" + when: "workingTree != ''" + - type: command + uses: git-cli + with: + command: "git push -u origin ${head}" + when: "parameters.pushAfterCommit == true" + - name: create-pr-gh + type: command + uses: gh-cli + with: + command: "gh pr create --base ${parameters.base} --title \"${parameters.title}\" --head ${head} ${parameters.draft ? '--draft' : ''} --body-file ${parameters.bodyFile}" + when: "parameters.mode in ['auto','gh'] && tools.gh_cli_available == true" + save_as: pr_url + - name: create-pr-rest + type: tool + uses: github-rest + with: + endpoint: create-pull-request + base: "${parameters.base}" + head: "${head}" + title: "${parameters.title}" + body: "${prBody}" + labels: "${parameters.labels}" + draft: "${parameters.draft}" + when: "(parameters.mode == 'rest') || (parameters.mode == 'auto' && tools.gh_cli_available == false && env.GITHUB_TOKEN != '')" + save_as: pr_url + diff --git a/.trae/skills/github.create-pr-from-file/README.md b/.trae/skills/github.create-pr-from-file/README.md new file mode 100644 index 0000000000..62c9069129 --- /dev/null +++ b/.trae/skills/github.create-pr-from-file/README.md @@ -0,0 +1,45 @@ +## 概述 +- 技能：github.create-pr-from-file（使用本地或指定正文文件创建 PR） +- 作用：从文件读取 PR 正文，使用 gh 或 REST 创建 PR + +## 参数 +- base（string，默认 develop）：目标基线分支 +- head（string，默认 ''）：来源分支；为空自动推导当前分支 +- title（string，必填）：PR 标题 +- labels（array，默认 []）：标签列表 +- draft（boolean，默认 false）：是否草稿 +- mode（enum: auto|gh|rest，默认 auto）：创建方式 +- localBodyFile（boolean，默认 true）：是否使用默认正文路径 +- bodyFile（string，默认 ./.trae/output/pr.body.local.md）：正文文件路径 +- commitBeforeCreate（boolean，默认 false）：创建前是否自动提交 +- commitMessage/commitAllowEmpty/pushAfterCommit/commitMessageStrategy：提交相关配置 + +## 输出 +- pr_url：创建成功后的 PR 链接 + +## 成功标准 +- pr_created：接口或 CLI 返回成功，拿到链接 + +## 失败案例与指引 +- 正文为空或文件不存在：先执行 PR 正文生成技能或提供有效 bodyFile +- REST 403：参考 GitHub Token 文档，检查 Fine‑grained 权限与组织 SSO 授权 + - 文档参考：[github-token-local.md](file:///Users/bytedance/Documents/GitHub/VChart/.trae/documents/github-token-local.md) +- gh 未登录或权限不足：参考 GitHub CLI 文档，完成登录与 SSO 授权 + - 文档参考：[github-gh-local.md](file:///Users/bytedance/Documents/GitHub/VChart/.trae/documents/github-gh-local.md) + +## 示例调用 +- skill: github.create-pr-from-file { title: 'feat: add legend', mode: 'auto' } + +## 失败返回示例 +- 正文为空或文件不存在： + - 返回：`PR 正文为空或文件不存在` + - 日志示例：`[ERROR] body file not found: ./.trae/output/pr.body.local.md` +- REST 403（权限不足/未授权）： + - 返回：HTTP 403，`Resource not accessible by personal access token` +- gh 未登录： + - 返回：`gh: Not authenticated` + +## 修复步骤 +- 先执行 PR 正文生成技能或提供有效 `bodyFile` +- 使用 Fine‑grained `GITHUB_TOKEN` 并完成组织 SSO 授权（参考 token 文档）；或登录 `gh` 并授权（参考 gh 文档） +- 重新运行 dry-run：`./.trae/scripts/dry-run-create-pr.sh` 确认通道与正文文件 diff --git a/.trae/skills/github.pr-body-generate.skill.yaml b/.trae/skills/github.pr-body-generate.skill.yaml new file mode 100644 index 0000000000..18741b95a0 --- /dev/null +++ b/.trae/skills/github.pr-body-generate.skill.yaml @@ -0,0 +1,85 @@ +id: github.pr-body-generate +version: v1 +description: 生成 PR 正文与标题建议并写入本地文件 +domain: github +runner: orchestrator +dependencies: + - git-cli + - shell +env: {} +parameters: + - name: lang + type: enum + values: [zh, en] + default: zh + required: false + - name: title + type: string + default: '' + required: false + - name: head + type: string + default: '' + required: false + - name: labels + type: array + default: [] + required: false + - name: rushChangesDir + type: string + default: common/changes + required: false + - name: localBodyFile + type: boolean + default: true + required: false + - name: openEditor + type: boolean + default: false + required: false +inputs: + - name: autotestReport + type: file + default: ./.trae/output/autotest.report.local.md +outputs: + - name: generated_title + - name: generated_body_preview + - name: generated_body_file +success_criteria: + - body_generated +steps: + - name: resolve-head + type: command + uses: git-cli + with: + command: git rev-parse --abbrev-ref HEAD + when: "parameters.head == ''" + save_as: head + - name: select-template + type: composite + with: + path: "${parameters.lang == 'zh' ? '.github/PULL_REQUEST_TEMPLATE/pr_cn.md' : '.github/PULL_REQUEST_TEMPLATE.md'}" + save_as: templatePath + - name: build-body + type: composite + with: + head: head + rush_dir: "${parameters.rushChangesDir}" + autotest_report: inputs.autotestReport + labels: "${parameters.labels}" + lang: "${parameters.lang}" + title_hint: "${parameters.title}" + save_as: generated_body_preview + - name: gen-title + type: composite + with: + rule: "[Auto] ${parameters.title != '' ? parameters.title : head}" + save_as: generated_title + - name: write-file + type: command + uses: shell + with: + command: "echo \"${generated_body_preview}\" > ./.trae/output/pr.body.local.md" + when: "parameters.localBodyFile == true" + save_as: generated_body_file + diff --git a/.trae/skills/github.pr-body-generate/README.md b/.trae/skills/github.pr-body-generate/README.md new file mode 100644 index 0000000000..62ff330a67 --- /dev/null +++ b/.trae/skills/github.pr-body-generate/README.md @@ -0,0 +1,29 @@ +## 概述 +- 技能：github.pr-body-generate（生成 PR 正文与标题建议） +- 作用：选择模板、填充内容、输出预览与本地文件 + +## 参数 +- lang（enum: zh|en，默认 zh）、title、head、labels、rushChangesDir（默认 common/changes）、localBodyFile（默认 true）、openEditor（默认 false） + +## 输出 +- generated_title、generated_body_preview、generated_body_file（默认写入 ./.trae/output/pr.body.local.md） + +## 成功标准 +- body_generated + +## 失败案例与指引 +- 模板缺失：检查 .github/PULL_REQUEST_TEMPLATE 目录与路径 +- 关联信息为空：保留占位，后续人工补充 + +## 示例调用 +- skill: github.pr-body-generate { title: '[Auto] legend', lang: 'zh' } + +## 失败返回示例 +- 模板缺失： + - 返回：`[ERROR] template not found: .github/PULL_REQUEST_TEMPLATE/pr_cn.md` +- 写入失败（权限/路径不可写）： + - 返回：`[ERROR] cannot write to ./.trae/output/pr.body.local.md` + +## 修复步骤 +- 补齐模板文件或改用英文模板路径；确保路径正确 +- 确认仓库路径可写，或变更输出路径；必要时以管理员权限运行 diff --git a/.trae/skills/pipeline.release-prep.skill.yaml b/.trae/skills/pipeline.release-prep.skill.yaml new file mode 100644 index 0000000000..94d72066b2 --- /dev/null +++ b/.trae/skills/pipeline.release-prep.skill.yaml @@ -0,0 +1,140 @@ +id: pipeline.release-prep +version: v1 +description: 单步/串行编排 Autotest→Changelog→Commit→PR 的发布准备流程 +domain: pipeline +runner: orchestrator +dependencies: + - skill +env: {} +parameters: + - name: baseBranch + type: string + default: develop + required: false + - name: lang + type: enum + values: [zh, en] + default: zh + required: false + - name: labels + type: array + default: [changelog, test] + required: false + - name: topic + type: string + default: '' + required: false + - name: message + type: string + default: '' + required: false + - name: bumpType + type: enum + values: [auto, major, minor, patch] + default: auto + required: false + - name: notCommit + type: boolean + default: true + required: false + - name: head + type: string + default: '' + required: false + - name: commitAllowEmpty + type: boolean + default: false + required: false + - name: pushAfterCommit + type: boolean + default: true + required: false + - name: commitMessageStrategy + type: enum + values: [auto, manual] + default: auto + required: false + - name: flowStep + type: integer + default: 1 + required: false + - name: autoNext + type: boolean + default: false + required: false +outputs: + - name: autotest_report + - name: rush_change_entries + - name: commit_message + - name: pushed_branch + - name: pr_url + - name: next_step_hint +success_criteria: + - flow_step_completed +steps: + - name: step-1-autotest + type: composite + with: + call: test.autogen-from-diff + params: + tempReportPath: ./.trae/output/autotest.report.local.md + focusChangedOnly: false + save_as: autotest_report + when: "(parameters.autoNext == true && parameters.flowStep <= 1) || (parameters.autoNext != true && parameters.flowStep == 1)" + - name: step-2-changelog + type: composite + with: + call: release.changelog-rush-smart + params: + sinceBranch: "${parameters.baseBranch}" + message: "${parameters.message}" + bumpType: "${parameters.bumpType}" + notCommit: "${parameters.notCommit}" + save_as: rush_change_entries + when: "(parameters.autoNext == true && parameters.flowStep <= 2) || (parameters.autoNext != true && parameters.flowStep == 2)" + - name: step-3-commit + type: composite + with: + call: git.commit-push-smart + params: + head: "${parameters.head}" + commitAllowEmpty: "${parameters.commitAllowEmpty}" + pushAfterCommit: "${parameters.pushAfterCommit}" + commitMessageStrategy: "${parameters.commitMessageStrategy}" + message: "${parameters.message}" + save_as: commit_message + when: "(parameters.autoNext == true && parameters.flowStep <= 3) || (parameters.autoNext != true && parameters.flowStep == 3)" + - name: step-4-body + type: composite + with: + call: github.pr-body-generate + params: + title: "[Auto] ${parameters.topic != '' ? parameters.topic : parameters.head}" + head: "${parameters.head}" + lang: "${parameters.lang}" + labels: "${parameters.labels}" + rushChangesDir: common/changes + localBodyFile: true + save_as: generated_body_file + when: "(parameters.autoNext == true && parameters.flowStep <= 4) || (parameters.autoNext != true && parameters.flowStep == 4)" + - name: step-5-pr + type: composite + with: + call: github.create-pr-from-file + params: + base: "${parameters.baseBranch}" + head: "${parameters.head}" + title: "[Auto] ${parameters.topic != '' ? parameters.topic : parameters.head}" + lang: "${parameters.lang}" + labels: "${parameters.labels}" + mode: auto + localBodyFile: true + bodyFile: ./.trae/output/pr.body.local.md + save_as: pr_url + when: "(parameters.autoNext == true && parameters.flowStep <= 5) || (parameters.autoNext != true && parameters.flowStep == 5)" + - name: next-step-hint + type: composite + with: + condition: "parameters.autoNext != true && parameters.flowStep < 5" + value: "在单步模式，下一步：flowStep=${parameters.flowStep + 1}" + save_as: next_step_hint diff --git a/.trae/skills/pipeline.release-prep/README.md b/.trae/skills/pipeline.release-prep/README.md new file mode 100644 index 0000000000..9921c832fe --- /dev/null +++ b/.trae/skills/pipeline.release-prep/README.md @@ -0,0 +1,30 @@ +## 概述 +- 技能：pipeline.release-prep（发布准备编排） +- 作用：单步/串行执行 Autotest→Changelog→Commit→PR + +## 参数 +- baseBranch、lang、labels、topic、message、bumpType、notCommit、head、commitAllowEmpty、pushAfterCommit、commitMessageStrategy、flowStep、autoNext + +## 输出 +- autotest_report、rush_change_entries、commit_message、pushed_branch、pr_url、next_step_hint + +## 成功标准 +- flow_step_completed + +## 失败案例与指引 +- 任一步骤失败：依据该子技能 README 的排查指引；串行模式会在失败处停止 + +## 示例调用 +- 单步：skill: pipeline.release-prep { flowStep: 1 } +- 串行：skill: pipeline.release-prep { autoNext: true } + +## 失败返回示例 +- 任一步骤失败时： + - 返回：子技能的错误信息，编排在该步骤停止 + - 示例：`[step-3-commit] push rejected` / `[step-2-changelog] commitlint failed` + +## 修复步骤 +- 依据错误源查看对应技能 README 并按指引修复 +- 使用 dry-run 脚本定位问题： + - `./.trae/scripts/dry-run-release-prep.sh` 展示流程 + - 逐步运行各子脚本验证环境与凭据 diff --git a/.trae/skills/release.changelog-rush-smart.skill.yaml b/.trae/skills/release.changelog-rush-smart.skill.yaml new file mode 100644 index 0000000000..3a21f804b1 --- /dev/null +++ b/.trae/skills/release.changelog-rush-smart.skill.yaml @@ -0,0 +1,92 @@ +id: release.changelog-rush-smart +version: v1 +description: 根据差异与提交生成 Rush 变更条目并构建消息 +domain: release +runner: orchestrator +dependencies: + - git-cli + - rush-cli + - shell + - github-rest +env: + GITHUB_TOKEN: optional +parameters: + - name: sinceBranch + type: string + default: develop + required: false + - name: message + type: string + default: '' + required: false + - name: bumpType + type: enum + values: [auto, major, minor, patch] + default: auto + required: false + - name: notCommit + type: boolean + default: true + required: false + - name: githubToken + type: string + default: '' + required: false +outputs: + - name: rush_change_entries + - name: computed_bump_type + - name: final_message +success_criteria: + - rush_changes_generated + - commitlint_passed +steps: + - name: diff-files + type: command + uses: git-cli + with: + command: "git diff --name-only ${parameters.sinceBranch}...HEAD" + save_as: changedFiles + - name: log-subjects + type: command + uses: git-cli + with: + command: "git log --pretty=%H:::%s ${parameters.sinceBranch}...HEAD" + save_as: commitSubjects + - name: compute-bump + type: composite + with: + strategy: "auto-from-commits" + override: "${parameters.bumpType}" + save_as: computed_bump_type + - name: build-message + type: composite + with: + base_message: "${parameters.message}" + commits: commitSubjects + use_github: "${env.GITHUB_TOKEN != '' || parameters.githubToken != ''}" + save_as: final_message + - name: commitlint + type: command + uses: shell + with: + command: "echo \"${final_message}\" | commitlint --config common/autoinstallers/lint/commitlint.config.js" + - name: rush-change + type: command + uses: rush-cli + with: + command: "rush change --bulk --bump-type '${computed_bump_type}' --message '${final_message}'" + save_as: rush_change_entries + - name: optional-commit + type: composite + with: + condition: "parameters.notCommit != true" + sequence: + - type: command + uses: git-cli + with: + command: git add --all + - type: command + uses: git-cli + with: + command: "git commit -m 'docs: update changlog of rush'" + diff --git a/.trae/skills/release.changelog-rush-smart/README.md b/.trae/skills/release.changelog-rush-smart/README.md new file mode 100644 index 0000000000..221859c828 --- /dev/null +++ b/.trae/skills/release.changelog-rush-smart/README.md @@ -0,0 +1,33 @@ +## 概述 +- 技能：release.changelog-rush-smart（生成 Rush 变更条目与富消息） +- 作用：采集差异与提交、自动判定 bump 类型、构建消息并运行 rush change + +## 参数 +- sinceBranch（string，默认 develop） +- message（string，默认 ''） +- bumpType（enum: auto|major|minor|patch，默认 auto） +- notCommit（boolean，默认 true） +- githubToken（string，默认 ''）：用于聚合 Issue 标题 + +## 输出 +- rush_change_entries、computed_bump_type、final_message + +## 成功标准 +- rush_changes_generated、commitlint_passed + +## 失败案例与指引 +- commitlint 不通过：调整 message 或按提交主题自动生成 +- GitHub 标题聚合失败：检查 token、组织 SSO 与仓库权限 + +## 示例调用 +- skill: release.changelog-rush-smart { sinceBranch: 'develop', bumpType: 'auto' } + +## 失败返回示例 +- commitlint 不通过： + - 返回：`✖ subject may not be empty [subject-empty]` +- rush change 失败： + - 返回：`Error: rush change ...`（权限/路径问题） + +## 修复步骤 +- 按规范修订 `message` 或使用自动生成；必要时在 `common/autoinstallers/lint/commitlint.config.js` 验证规则 +- 确认 Rush 环境与仓库结构；在仓库根目录运行，确保有 `common/changes/` diff --git a/.trae/skills/test.autogen-from-diff.skill.yaml b/.trae/skills/test.autogen-from-diff.skill.yaml new file mode 100644 index 0000000000..ea86987f94 --- /dev/null +++ b/.trae/skills/test.autogen-from-diff.skill.yaml @@ -0,0 +1,105 @@ +id: test.autogen-from-diff +version: v1 +description: 根据分支差异与导出符号，自动生成或增量更新单测并输出报告 +domain: testing +runner: orchestrator +dependencies: + - rush-cli + - jest-cli +env: {} +parameters: + - name: project + type: string + default: auto + required: false + - name: mode + type: enum + values: [full] + default: full + required: false + - name: noSnapshot + type: boolean + default: false + required: false + - name: onlyNew + type: boolean + default: false + required: false + - name: applyManualOverrides + type: boolean + default: true + required: false + - name: replaceAutogen + type: boolean + default: false + required: false + - name: dryRun + type: boolean + default: false + required: false + - name: preview + type: boolean + default: false + required: false + - name: stopOnError + type: boolean + default: true + required: false + - name: focusChangedOnly + type: boolean + default: false + required: false + - name: snapshotStrategy + type: enum + values: [combined] + default: combined + required: false + - name: tempReportPath + type: string + default: ./.trae/output/autotest.report.local.md + required: false +inputs: + - name: diff_json + type: file + default: ./.trae/output/diff.json +outputs: + - name: test_files + - name: snapshots + - name: coverage_report + - name: manual_nodes + - name: temp_markdown_report +success_criteria: + - tests_generated_for_changed_exports + - compile_without_errors + - coverage_increase_or_maintained +steps: + - name: analyze + type: composite + with: + source: diff_json + strategy: exports-and-branches + - name: generate-tests + type: composite + with: + layout: __tests__/*.test.ts + comments: function-level-jsdoc + autogen_block: true + only_new: "${parameters.onlyNew}" + replace_autogen: "${parameters.replaceAutogen}" + - name: run-tests + type: command + uses: rush-cli + with: + command: "rush run ${parameters.project != 'auto' ? '-p ' + parameters.project : ''} -s test" + - name: run-coverage + type: command + uses: rush-cli + with: + command: "rush run ${parameters.project != 'auto' ? '-p ' + parameters.project : ''} -s test-cov" + - name: write-report + type: command + uses: shell + with: + command: "echo '# Autotest 报告' > ${parameters.tempReportPath}" + save_as: temp_markdown_report + diff --git a/.trae/skills/test.autogen-from-diff/README.md b/.trae/skills/test.autogen-from-diff/README.md new file mode 100644 index 0000000000..3261acd6df --- /dev/null +++ b/.trae/skills/test.autogen-from-diff/README.md @@ -0,0 +1,43 @@ +## 概述 + +- 技能：test.autogen-from-diff（根据差异自动生成/增量更新单测） +- 作用：识别导出符号与分支，生成 **tests**/\*.test.ts（含函数级 JSDoc 注释），执行覆盖率与报告 + +## 参数 + +- project（string，默认 auto）：自动识别变更包或指定包名 +- mode（enum: full，默认 full） +- noSnapshot/onlyNew/applyManualOverrides/replaceAutogen/dryRun/preview/stopOnError/focusChangedOnly/snapshotStrategy/tempReportPath + +## 输出 + +- test_files、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 + +## 失败案例与指引 + +- 编译/类型错误：修复 TS 诊断后重试；报告中会标注阻断项 +- rush/jest 不可用：改用 npm/yarn 脚本或安装 rush；参数 preview/dryRun 可用于生成但不执行 +- 快照不稳定：使用固定时间与随机数的 mock；必要时增量快照策略 + +## 示例调用 + +- skill: test.autogen-from-diff { project: '@visactor/vchart', onlyNew: false } + +## 失败返回示例 + +- TypeScript 编译错误： + - 返回：`TSxxxx: ...` +- rush 不可用： + - 返回：`rush: command not found` +- 覆盖率任务失败： + - 返回：jest 失败摘要与非零退出 + +## 修复步骤 + +- 修复 TS 诊断与依赖，再重试；必要时启用 `dryRun: true` 仅生成测试不执行 +- 安装或改用 npm/yarn 脚本运行测试；确保 `package.json` 有对应脚本 +- 快照问题：固定时间/随机数 mock，必要时调整 `snapshotStrategy` diff --git a/.trae/skills/vcs.diff-collect.skill.yaml b/.trae/skills/vcs.diff-collect.skill.yaml new file mode 100644 index 0000000000..552e274bc1 --- /dev/null +++ b/.trae/skills/vcs.diff-collect.skill.yaml @@ -0,0 +1,69 @@ +id: vcs.diff-collect +version: v1 +description: 采集分支差异与工作树变更并生成结构化 JSON +domain: vcs +runner: orchestrator +dependencies: + - git-cli +env: {} +parameters: + - name: sinceBranch + type: string + default: develop + required: false + - name: includeWorkingTree + type: boolean + default: true + required: false +inputs: {} +outputs: + - name: diff_json + path: ./.trae/output/diff.json +success_criteria: + - diff_collected +steps: + - name: fetch + type: command + uses: git-cli + with: + command: git fetch --all --prune + - name: diff-files + type: command + uses: git-cli + with: + command: "git diff --name-status --diff-filter=AMR ${parameters.sinceBranch}...HEAD" + save_as: changedFiles + - name: working-tree + type: command + uses: git-cli + with: + command: git status --porcelain + when: "parameters.includeWorkingTree == true" + save_as: workingTree + - name: line-diff + type: composite + with: + for_each: changedFiles + do: + - type: command + uses: git-cli + with: + command: "git diff --unified=0 ${parameters.sinceBranch}...HEAD ${item}" + save_as: lineDiffCommitted + - type: command + uses: git-cli + with: + command: "git diff --cached --unified=0 -- ${item}" + save_as: lineDiffStaged + - type: command + uses: git-cli + with: + command: "git diff --unified=0 -- ${item}" + save_as: lineDiffUnstaged + - name: write-json + type: command + uses: shell + with: + command: "echo '{}' > ./.trae/output/diff.json" + save_as: diff_json + diff --git a/.trae/skills/vcs.diff-collect/README.md b/.trae/skills/vcs.diff-collect/README.md new file mode 100644 index 0000000000..25aa4122c3 --- /dev/null +++ b/.trae/skills/vcs.diff-collect/README.md @@ -0,0 +1,30 @@ +## 概述 +- 技能：vcs.diff-collect（采集分支差异与工作树变更） +- 作用：生成结构化差异信息（文件列表与行级片段），输出 JSON + +## 参数 +- sinceBranch（string，默认 develop）：对比基线分支 +- includeWorkingTree（boolean，默认 true）：是否包含工作树变更 + +## 输出 +- diff_json：写入 ./.trae/output/diff.json + +## 成功标准 +- diff_collected：完成差异采集 + +## 失败案例与指引 +- 无 git/远程不可用：先执行 git fetch 或确认仓库状态 +- 差异为空：按需改用指定 project 的 Autotest 运行方式 + +## 示例调用 +- skill: vcs.diff-collect { sinceBranch: 'develop' } + +## 失败返回示例 +- 基线分支不存在： + - 返回：`fatal: bad revision 'develop...HEAD'` +- 差异为空： + - 返回：`changedFiles=[]` + +## 修复步骤 +- 先 `git fetch --all --prune` 同步远程；确认 `sinceBranch` 存在 +- 若差异为空而需继续流程：在 Autotest 中指定 `project` 明确运行目标包 From e222afaeea1bef849cf3f64cd2ad4fe40959c696 Mon Sep 17 00:00:00 2001 From: "lixuefei.1313" <lixuef1313@163.com> Date: Mon, 5 Jan 2026 10:41:24 +0800 Subject: [PATCH 06/10] feat: revert skills --- ...36\346\226\275\350\256\241\345\210\222.md" | 91 ------------ .trae/scripts/dry-run-autotest.sh | 14 -- .trae/scripts/dry-run-changelog.sh | 16 -- .trae/scripts/dry-run-commit-smart.sh | 34 ----- .trae/scripts/dry-run-create-branch.sh | 14 -- .trae/scripts/dry-run-create-pr.sh | 24 --- .trae/scripts/dry-run-diff-collect.sh | 12 -- .trae/scripts/dry-run-pr-body.sh | 13 -- .trae/scripts/dry-run-release-prep.sh | 10 -- .trae/scripts/validate-skill.sh | 39 ----- .trae/skills/ADAPTERS.md | 14 -- .trae/skills/EXAMPLES.md | 63 -------- .trae/skills/OUTPUTS.md | 14 -- .trae/skills/README.md | 24 --- .trae/skills/git.commit-push-smart.skill.yaml | 78 ---------- .trae/skills/git.commit-push-smart/README.md | 40 ----- .trae/skills/git.create-branch.skill.yaml | 52 ------- .trae/skills/git.create-branch/README.md | 32 ---- .../github.create-pr-from-file.skill.yaml | 132 ----------------- .../github.create-pr-from-file/README.md | 45 ------ .../skills/github.pr-body-generate.skill.yaml | 85 ----------- .../skills/github.pr-body-generate/README.md | 29 ---- .trae/skills/pipeline.release-prep.skill.yaml | 140 ------------------ .trae/skills/pipeline.release-prep/README.md | 30 ---- .../release.changelog-rush-smart.skill.yaml | 92 ------------ .../release.changelog-rush-smart/README.md | 33 ----- .../skills/test.autogen-from-diff.skill.yaml | 105 ------------- .trae/skills/test.autogen-from-diff/README.md | 43 ------ .trae/skills/vcs.diff-collect.skill.yaml | 69 --------- .trae/skills/vcs.diff-collect/README.md | 30 ---- 30 files changed, 1417 deletions(-) delete mode 100644 ".trae/documents/\345\260\206 .trae \345\267\245\344\275\234\346\265\201\350\277\201\347\247\273\344\270\272\345\217\257\345\244\215\347\224\250 Skills \347\232\204\350\256\276\350\256\241\344\270\216\345\256\236\346\226\275\350\256\241\345\210\222.md" delete mode 100644 .trae/scripts/dry-run-autotest.sh delete mode 100644 .trae/scripts/dry-run-changelog.sh delete mode 100644 .trae/scripts/dry-run-commit-smart.sh delete mode 100644 .trae/scripts/dry-run-create-branch.sh delete mode 100644 .trae/scripts/dry-run-create-pr.sh delete mode 100644 .trae/scripts/dry-run-diff-collect.sh delete mode 100644 .trae/scripts/dry-run-pr-body.sh delete mode 100644 .trae/scripts/dry-run-release-prep.sh delete mode 100644 .trae/scripts/validate-skill.sh delete mode 100644 .trae/skills/ADAPTERS.md delete mode 100644 .trae/skills/EXAMPLES.md delete mode 100644 .trae/skills/OUTPUTS.md delete mode 100644 .trae/skills/README.md delete mode 100644 .trae/skills/git.commit-push-smart.skill.yaml delete mode 100644 .trae/skills/git.commit-push-smart/README.md delete mode 100644 .trae/skills/git.create-branch.skill.yaml delete mode 100644 .trae/skills/git.create-branch/README.md delete mode 100644 .trae/skills/github.create-pr-from-file.skill.yaml delete mode 100644 .trae/skills/github.create-pr-from-file/README.md delete mode 100644 .trae/skills/github.pr-body-generate.skill.yaml delete mode 100644 .trae/skills/github.pr-body-generate/README.md delete mode 100644 .trae/skills/pipeline.release-prep.skill.yaml delete mode 100644 .trae/skills/pipeline.release-prep/README.md delete mode 100644 .trae/skills/release.changelog-rush-smart.skill.yaml delete mode 100644 .trae/skills/release.changelog-rush-smart/README.md delete mode 100644 .trae/skills/test.autogen-from-diff.skill.yaml delete mode 100644 .trae/skills/test.autogen-from-diff/README.md delete mode 100644 .trae/skills/vcs.diff-collect.skill.yaml delete mode 100644 .trae/skills/vcs.diff-collect/README.md diff --git "a/.trae/documents/\345\260\206 .trae \345\267\245\344\275\234\346\265\201\350\277\201\347\247\273\344\270\272\345\217\257\345\244\215\347\224\250 Skills \347\232\204\350\256\276\350\256\241\344\270\216\345\256\236\346\226\275\350\256\241\345\210\222.md" "b/.trae/documents/\345\260\206 .trae \345\267\245\344\275\234\346\265\201\350\277\201\347\247\273\344\270\272\345\217\257\345\244\215\347\224\250 Skills \347\232\204\350\256\276\350\256\241\344\270\216\345\256\236\346\226\275\350\256\241\345\210\222.md" deleted file mode 100644 index 81f52123a8..0000000000 --- "a/.trae/documents/\345\260\206 .trae \345\267\245\344\275\234\346\265\201\350\277\201\347\247\273\344\270\272\345\217\257\345\244\215\347\224\250 Skills \347\232\204\350\256\276\350\256\241\344\270\216\345\256\236\346\226\275\350\256\241\345\210\222.md" +++ /dev/null @@ -1,91 +0,0 @@ -## 背景与现状 -- 当前仓库在 .trae 目录下以“Job + Solo 文档”的方式描述自动化任务流，包括单测自动生成、智能提交与推送、PR 创建、分支管理、Changelog 等。 -- 典型 Job 文件包含清晰的元数据与参数约束，结构化步骤与成功标准，示例： - - 作业总览与用法：[README.md](file:///Users/bytedance/Documents/GitHub/VChart/.trae/jobs/README.md) - - 自动化单测生成：[auto-test.md](file:///Users/bytedance/Documents/GitHub/VChart/.trae/jobs/auto-test.md) 与说明文档：[auto-test.solo.md](file:///Users/bytedance/Documents/GitHub/VChart/.trae/documents/auto-test.solo.md) - - 智能提交推送：[commit-smart.md](file:///Users/bytedance/Documents/GitHub/VChart/.trae/jobs/commit-smart.md) - - 本地正文创建 PR：[pr-create-from-body.md](file:///Users/bytedance/Documents/GitHub/VChart/.trae/jobs/pr-create-from-body.md) - -## 适配性评估（是否适合迁移为 Skills） -- 结构化良好：现有 Job 已具备“名称/意图/参数/输入输出/成功标准/步骤”的技能化必要元素，迁移成本低。 -- 可移植性可控：多数步骤依赖标准 CLI（git、gh、rush、jest），通过工具抽象与参数化可跨 IDE 复用。 -- 领域清晰：任务聚焦“测试/Git/GitHub”，适合拆分为多个职责单一的技能单元，便于组合编排。 -- 风险与边界： - - 环境依赖（rush、ts-jest、gh CLI）需在技能层声明“前置条件 + 兜底模式（REST/跳过）”。 - - 写文件与运行测试属“有副作用”，Skills 需提供 dry-run/preview/stopOnError 等保护与可观测性。 -- 结论：适合迁移。推荐“分层拆分 + 通用工具适配 + 渐进迁移”，先迁 Git/PR 类，随后迁 Autotest 编排与子技能。 - -## 迁移目标与原则 -- 目标：将 .trae/jobs 中的任务流标准化为跨 IDE 可复用的 Skills（带清晰的输入/输出/依赖/步骤），保留 Solo 可运行性，同时增设通用工具适配（兼容 gh/REST、CLI/协议）。 -- 原则： - - 单一职责、可组合：一个技能只解决一个明确问题；复杂流程由编排技能调用多个子技能。 - - 明确契约：参数类型/默认值/必填项、输出物路径与结构需固定、错误与成功标准一致可测。 - - 安全与幂等：dry-run 默认开启于危险操作；文件写入有覆盖策略；外部 API 使用令牌与最小权限。 - -## 技能清单与映射 -- github.create-pr-from-file（来源：pr-create-from-body） - - 输入：base、head、title（必填）、labels、draft、mode（auto|gh|rest）、bodyFile/localBodyFile、commitBeforeCreate 等 - - 工具适配：优先 gh CLI，其次 GitHub REST（GITHUB_TOKEN），失败时明确报错与指引 - - 输出：pr_url；成功标准：pr_created -- git.commit-push-smart（来源：commit-smart） - - 输入：head、commitAllowEmpty、pushAfterCommit、commitMessageStrategy、message - - 步骤：检测工作树 → 生成信息（路径/changes 类型推断）→ commit → push（可选） - - 输出：commit_message、pushed_branch；成功标准：commit_created_or_skipped -- vcs.diff-collect（Autotest 子技能） - - 输入：sinceBranch、includeWorkingTree - - 输出：变更文件与行级差异结构体（JSON） -- test.autogen-from-diff（来源：auto-test） - - 输入：project、mode、noSnapshot、onlyNew、applyManualOverrides、replaceAutogen 等 - - 步骤：分析导出符号 → 生成/增量更新 __tests__/*.test.ts（含函数级 JSDoc 注释）→ 运行覆盖率 → 写临时报告 - - 输出：test_files、snapshots、coverage_report、manual_nodes、temp_markdown_report；成功标准同原 Job -- github.pr-body-generate（来源：pr-body-generate）与 changelog.rush-smart、branch.create 等（按现有 Job 逐项映射） - -## 技能规范（建议的 Skill Manifest） -- 顶层字段：id、version、description、domain、tags、runner（solo|orchestrator|mcp）、dependencies（cli/tools）、env（必需变量）。 -- parameters：name、type（string|boolean|enum|file）、default、required、validate、visibility（advanced）。 -- inputs/outputs：路径与结构约定（例如输出报告默认至 .trae/output/**，可覆盖）。 -- success_criteria：机器可判定的条件列表；errors：常见失败及建议。 -- steps： - - type: command|tool|script|composite - - uses: git/gh/github-rest/rush/jest 等适配器 - - with: 具体参数映射；guards：前置检查与兜底策略；dryRun: true/false；continueOnError: bool； -- 观测性：每步产生日志事件与可视化摘要，临时报告路径可配置。 - -## 通用工具抽象与 MCP 适配 -- GitHub：抽象两种实现 - - gh CLI：gh pr create ... - - REST：POST /repos/{owner}/{repo}/pulls（从环境读取 GITHUB_TOKEN） -- Git：抽象常用命令（rev-parse、status、add/commit/push、diff），允许替换成 IDE 的 Shell 执行器。 -- 测试与覆盖率：抽象 rush/jest 执行器，支持 project 定位与并行；无 rush 环境时回退至 npm/yarn。 -- 报告：统一写入（md|json），在不同 IDE 通过文件系统可见。 - -## 迁移步骤（渐进式） -1. 定义 Skill 模板与约束 - - 提炼通用 manifest 与步骤 DSL；建立“工具适配”层（gh/rest、git/shell、rush/jest）。 -2. 先迁 Git/PR 类（低风险） - - 将 commit-smart 与 pr-create-from-body 转为 skills；实现 gh/rest 双路；发布 dry-run 默认开。 -3. 引入编排技能 - - 将 auto-test 拆为 orchestrator + 子技能（diff-collect、analysis、generate-tests、run-coverage、report）。 -4. 标准化输出物与路径 - - 报告/快照/测试文件命名与路径统一；保留 .trae/output，允许通过参数覆盖。 -5. 加入校验与回退 - - 环境检查（CLI、令牌、rush）；无法满足时按策略回退或提示。 -6. 文档与示例 - - 为每个技能提供独立 README 与示例调用；保留原 .trae/documents 作为技能说明。 -7. 验证与兼容发布 - - 在 Trae 中以 Solo 运行验证；在其他 IDE 通过“工具适配器 + 文件 IO”验证；发布 v1。 - -## 验证与发布策略 -- 单元验证：每个技能提供“模拟输入 → 期望输出”的用例；dry-run 模式检查日志与报告。 -- 集成验证：在真实仓库上跑全流程（先 Git/PR，再 Autotest）。 -- 版本与回滚：语义化版本；变更日志；失败可回滚到 Job 运行方式。 - -## 风险与注意事项 -- 环境差异：Windows/Mac/Linux 下命令差异与路径分隔符；rush/jest 可用性。 -- 令牌与安全：不在仓库写入任何密钥；按环境变量读取；失败明确提示。 -- 幂等与覆盖：replaceAutogen 参数遵循默认“增量插入，不覆盖人工块”。 - -## 里程碑与交付 -- M1：完成 Skill 模板与工具适配层；迁移 commit-smart、pr-create-from-body。 -- M2：完成 Autotest 子技能与编排；发布一致性报告格式；形成复用规范。 -- M3：补齐 changelog、branch、pr-body-generate 等技能；完善文档与示例。 \ No newline at end of file diff --git a/.trae/scripts/dry-run-autotest.sh b/.trae/scripts/dry-run-autotest.sh deleted file mode 100644 index f5e22cbff8..0000000000 --- a/.trae/scripts/dry-run-autotest.sh +++ /dev/null @@ -1,14 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -## 函数：检查 rush/jest 可用性 -check_tools() { - local has_rush=0; command -v rush >/dev/null 2>&1 && has_rush=1 - local has_jest=0; command -v jest >/dev/null 2>&1 && has_jest=1 - echo "$has_rush:$has_jest" -} - -tools=$(check_tools) -echo "[DRY-RUN] rush/jest = $tools" -echo "[DRY-RUN] report path = ./.trae/output/autotest.report.local.md" - diff --git a/.trae/scripts/dry-run-changelog.sh b/.trae/scripts/dry-run-changelog.sh deleted file mode 100644 index 6983bfd398..0000000000 --- a/.trae/scripts/dry-run-changelog.sh +++ /dev/null @@ -1,16 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -## 函数：判定 bump 类型 -compute_bump() { - local base=${1:-develop} - local subjects - subjects=$(git log --pretty=%s "$base"...HEAD | tr 'A-Z' 'a-z') - if echo "$subjects" | grep -E 'breaking change|!'; then echo major; return; fi - if echo "$subjects" | grep -E '^feat'; then echo minor; return; fi - echo patch -} - -bt=$(compute_bump "${1:-develop}") -echo "[DRY-RUN] computed_bump_type=$bt" - diff --git a/.trae/scripts/dry-run-commit-smart.sh b/.trae/scripts/dry-run-commit-smart.sh deleted file mode 100644 index 1305d3f5e8..0000000000 --- a/.trae/scripts/dry-run-commit-smart.sh +++ /dev/null @@ -1,34 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -## 函数：检查 git 与工作树状态 -check_git() { - git --version >/dev/null 2>&1 || { echo "[ERROR] git 未安装"; exit 1; } - git rev-parse --is-inside-work-tree >/dev/null 2>&1 || { echo "[ERROR] 非 git 仓库"; exit 1; } -} - -## 函数：推导分支名 -resolve_head() { - git rev-parse --abbrev-ref HEAD -} - -## 函数：模拟提交信息生成 -derive_message() { - local strategy=${1:-auto} - local message=${2:-} - if [[ "$strategy" == "manual" && -n "$message" ]]; then - echo "$message" - else - local count - count=$(git status --porcelain | wc -l | tr -d ' ') - echo "chore: sync changes before PR (${count} files)" - fi -} - -check_git -HEAD_BRANCH=$(resolve_head) -COMMIT_MSG=$(derive_message "${1:-auto}" "${2:-}") -echo "[DRY-RUN] head=$HEAD_BRANCH" -echo "[DRY-RUN] commit_message=$COMMIT_MSG" -echo "[DRY-RUN] pushAfterCommit=${3:-true}" - diff --git a/.trae/scripts/dry-run-create-branch.sh b/.trae/scripts/dry-run-create-branch.sh deleted file mode 100644 index 7f9168cb45..0000000000 --- a/.trae/scripts/dry-run-create-branch.sh +++ /dev/null @@ -1,14 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -## 函数：生成分支名 -gen_branch() { - local prefix=${1:-chore/trae} - local topic=${2:?topic 必填} - local ts; ts=$(date +%Y%m%d-%H%M) - echo "$prefix-$topic-$ts" -} - -bn=$(gen_branch "${1:-chore/trae}" "${2:-}") -echo "[DRY-RUN] branch_name=$bn" - diff --git a/.trae/scripts/dry-run-create-pr.sh b/.trae/scripts/dry-run-create-pr.sh deleted file mode 100644 index d4d22f77f1..0000000000 --- a/.trae/scripts/dry-run-create-pr.sh +++ /dev/null @@ -1,24 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -## 函数：检查 gh 或 REST 可用性 -check_channels() { - local has_gh=0 - command -v gh >/dev/null 2>&1 && has_gh=1 - local has_token=0 - [[ -n "${GITHUB_TOKEN:-}" ]] && has_token=1 - echo "$has_gh:$has_token" -} - -## 函数：读取正文文件 -read_body() { - local file=${1:-./.trae/output/pr.body.local.md} - [[ -f "$file" ]] || { echo "[ERROR] 正文文件不存在: $file"; exit 1; } - wc -c "$file" | awk '{print $1}' -} - -chan=$(check_channels) -size=$(read_body "${1:-./.trae/output/pr.body.local.md}") -echo "[DRY-RUN] channels gh/token = $chan" -echo "[DRY-RUN] body size = $size bytes" - diff --git a/.trae/scripts/dry-run-diff-collect.sh b/.trae/scripts/dry-run-diff-collect.sh deleted file mode 100644 index 2d0cdb801b..0000000000 --- a/.trae/scripts/dry-run-diff-collect.sh +++ /dev/null @@ -1,12 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -## 函数：采集差异摘要 -collect_diff() { - local base=${1:-develop} - git fetch --all --prune >/dev/null 2>&1 || true - git diff --name-status --diff-filter=AMR "$base"...HEAD | head -n 20 -} - -collect_diff "${1:-develop}" - diff --git a/.trae/scripts/dry-run-pr-body.sh b/.trae/scripts/dry-run-pr-body.sh deleted file mode 100644 index 316a2f2298..0000000000 --- a/.trae/scripts/dry-run-pr-body.sh +++ /dev/null @@ -1,13 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -## 函数：模板选择 -select_tpl() { - local lang=${1:-zh} - if [[ "$lang" == "zh" ]]; then echo .github/PULL_REQUEST_TEMPLATE/pr_cn.md; else echo .github/PULL_REQUEST_TEMPLATE.md; fi -} - -tpl=$(select_tpl "${1:-zh}") -echo "[DRY-RUN] template=$tpl" -echo "[DRY-RUN] output=./.trae/output/pr.body.local.md" - diff --git a/.trae/scripts/dry-run-release-prep.sh b/.trae/scripts/dry-run-release-prep.sh deleted file mode 100644 index 793ee8ac1b..0000000000 --- a/.trae/scripts/dry-run-release-prep.sh +++ /dev/null @@ -1,10 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -## 函数：展示串行步骤 -show_steps() { - echo "1) Autotest → 2) Changelog → 3) Commit → 4) PR Body → 5) PR Create" -} - -show_steps - diff --git a/.trae/scripts/validate-skill.sh b/.trae/scripts/validate-skill.sh deleted file mode 100644 index 5fd39d5654..0000000000 --- a/.trae/scripts/validate-skill.sh +++ /dev/null @@ -1,39 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -skill="${1:-}" -if [[ -z "$skill" ]]; then - echo "usage: validate-skill <skill-id> [args]"; exit 1 -fi -shift || true - -case "$skill" in - git.commit-push-smart) - exec ./.trae/scripts/dry-run-commit-smart.sh "$@" - ;; - github.create-pr-from-file) - exec ./.trae/scripts/dry-run-create-pr.sh "$@" - ;; - vcs.diff-collect) - exec ./.trae/scripts/dry-run-diff-collect.sh "$@" - ;; - test.autogen-from-diff) - exec ./.trae/scripts/dry-run-autotest.sh "$@" - ;; - release.changelog-rush-smart) - exec ./.trae/scripts/dry-run-changelog.sh "$@" - ;; - git.create-branch) - exec ./.trae/scripts/dry-run-create-branch.sh "$@" - ;; - github.pr-body-generate) - exec ./.trae/scripts/dry-run-pr-body.sh "$@" - ;; - pipeline.release-prep) - exec ./.trae/scripts/dry-run-release-prep.sh "$@" - ;; - *) - echo "unknown skill: $skill"; exit 1 - ;; -esac - diff --git a/.trae/skills/ADAPTERS.md b/.trae/skills/ADAPTERS.md deleted file mode 100644 index e4b9d2de55..0000000000 --- a/.trae/skills/ADAPTERS.md +++ /dev/null @@ -1,14 +0,0 @@ -# 工具适配与回退策略 - -## 映射 -- gh-cli: 使用 GitHub CLI 创建 PR、管理 Issue 等。 -- github-rest: 使用 REST API（读取环境变量 GITHUB_TOKEN）。 -- git-cli: 执行 rev-parse、status、add/commit/push、diff 等。 -- rush-cli: 执行测试与覆盖率；无 rush 时回退 npm/yarn。 -- jest-cli: 测试运行器；可由框架插件替换。 - -## 回退 -- PR 创建：优先 gh-cli；不可用则使用 github-rest；均不可用则返回明确错误。 -- 覆盖率运行：无 rush 时改用 npm/yarn 脚本。 -- 差异采集：无 git 时直接失败并返回环境提示。 - diff --git a/.trae/skills/EXAMPLES.md b/.trae/skills/EXAMPLES.md deleted file mode 100644 index 7685ca5265..0000000000 --- a/.trae/skills/EXAMPLES.md +++ /dev/null @@ -1,63 +0,0 @@ -# Skills 示例调用 - -## git.commit-push-smart - -- 调用：`skill: git.commit-push-smart { pushAfterCommit: true, commitMessageStrategy: 'auto' }` -- 预期输出：commit_message、pushed_branch - -## github.create-pr-from-file - -- 调用：`skill: github.create-pr-from-file { title: 'feat: add legend', mode: 'auto' }` -- 预期输出：pr_url - -## vcs.diff-collect - -- 调用：`skill: vcs.diff-collect { sinceBranch: 'develop', includeWorkingTree: true }` -- 预期输出：diff_json => `./.trae/output/diff.json` - -## test.autogen-from-diff - -- 调用：`skill: test.autogen-from-diff { project: '@visactor/vchart', onlyNew: false }` -- 预期输出：test_files、snapshots、coverage_report、manual_nodes、temp_markdown_report - -## release.changelog-rush-smart - -- 调用：`skill: release.changelog-rush-smart { sinceBranch: 'develop', bumpType: 'auto' }` -- 预期输出：rush_change_entries、computed_bump_type、final_message - -## git.create-branch - -- 调用：`skill: git.create-branch { baseBranch: 'develop', branchPrefix: 'feat/chart', topic: 'v2-legend', useDateSuffix: true }` -- 预期输出：branch_name - -## pipeline.release-prep - -- 调用（单步）：`skill: pipeline.release-prep { flowStep: 1 }` -- 调用（串行）：`skill: pipeline.release-prep { autoNext: true }` -- 预期输出：autotest_report、rush_change_entries、commit_message、pushed_branch、pr_url - -## 验证入口 - -- 统一入口脚本：`./.trae/scripts/validate-skill.sh <skill-id> [args]` -- 示例： - - `./.trae/scripts/validate-skill.sh github.create-pr-from-file ./.trae/output/pr.body.local.md` - - `./.trae/scripts/validate-skill.sh vcs.diff-collect develop` - -## 单步执行说明（pipeline.release-prep） - -- 步骤一（Autotest）： - - 调用：`skill: pipeline.release-prep { flowStep: 1 }` - - 输出：`autotest_report`，并返回 `next_step_hint` 提示下一步为 `flowStep=2` -- 步骤二（Changelog）： - - 调用：`skill: pipeline.release-prep { flowStep: 2, message: 'feat: xxx', bumpType: 'auto' }` - - 输出：`rush_change_entries`、`computed_bump_type`、`final_message`，`next_step_hint=flowStep=3` -- 步骤三（Commit）： - - 调用：`skill: pipeline.release-prep { flowStep: 3, commitMessageStrategy: 'auto', pushAfterCommit: true }` - - 输出：`commit_message`、`pushed_branch`，`next_step_hint=flowStep=4` -- 步骤四（PR 正文生成）： - - 调用：`skill: pipeline.release-prep { flowStep: 4, title: '[Auto] xxx', lang: 'zh', labels: ['changelog','test'] }` - - 输出：`generated_body_file=.trae/output/pr.body.local.md`，`next_step_hint=flowStep=5` -- 步骤五（创建 PR）： - - 调用：`skill: pipeline.release-prep { flowStep: 5 }` - - 输出：`pr_url` -- 说明：单步模式仅执行指定步骤；完成后按 `next_step_hint` 继续调用下一步。若希望自动推进，使用 `autoNext: true`。 diff --git a/.trae/skills/OUTPUTS.md b/.trae/skills/OUTPUTS.md deleted file mode 100644 index 36e7f567eb..0000000000 --- a/.trae/skills/OUTPUTS.md +++ /dev/null @@ -1,14 +0,0 @@ -# 输出物与路径规范 - -## 默认位置 -- 差异 JSON：`./.trae/output/diff.json` -- Autotest 报告：`./.trae/output/autotest.report.local.md` -- PR 正文：`./.trae/output/pr.body.local.md` - -## 可覆盖 -- 所有输出路径均可通过技能参数覆盖，要求为相对仓库根路径的可写位置。 - -## 命名约定 -- 测试文件：`__tests__/*.test.ts` -- 自动化区块：名称前缀 `autogen:`，避免覆盖人工块。 - diff --git a/.trae/skills/README.md b/.trae/skills/README.md deleted file mode 100644 index f0367609e0..0000000000 --- a/.trae/skills/README.md +++ /dev/null @@ -1,24 +0,0 @@ -# Skills 概述与迁移规范 - -## 目标 -- 将现有 .trae/jobs 中的任务流标准化为跨 IDE 可复用的 Skills，保留 Solo 可运行性，并提供工具适配（gh/REST、git/shell、rush/jest）。 - -## 结构 -- 每个技能以 `.skill.yaml` 描述：id、version、description、domain、runner、dependencies、env、parameters、inputs、outputs、success_criteria、steps。 -- 步骤支持 command、tool、composite 类型，具备 guards、dryRun、continueOnError 与 uses 映射（gh-cli、github-rest、git-cli、rush-cli、jest-cli）。 - -## 适配层 -- gh-cli 与 github-rest 双路；git-cli 基于系统 Shell；rush-cli 与 jest-cli 可替换为 npm/yarn。 - -## 输出 -- 报告与中间产物默认写入 `.trae/output/**`，可通过参数覆盖。 - -## 示例调用 -- 提交并推送：`skill: git.commit-push-smart { pushAfterCommit: true, commitMessageStrategy: 'auto' }` -- 创建 PR：`skill: github.create-pr-from-file { title: 'feat: add legend', mode: 'auto' }` -- 采集差异：`skill: vcs.diff-collect { sinceBranch: 'develop' }` -- 单测生成：`skill: test.autogen-from-diff { project: '@visactor/vchart' }` - -## 环境前置 -- gh-cli 或 GITHUB_TOKEN；git 已安装；rush/jest（或 npm/yarn 替代）。 -- 未满足前置时按技能中的 guards 与回退策略处理。 diff --git a/.trae/skills/git.commit-push-smart.skill.yaml b/.trae/skills/git.commit-push-smart.skill.yaml deleted file mode 100644 index f3d3809185..0000000000 --- a/.trae/skills/git.commit-push-smart.skill.yaml +++ /dev/null @@ -1,78 +0,0 @@ -id: git.commit-push-smart -version: v1 -description: 智能生成提交信息并推送当前分支 -domain: git -runner: orchestrator -dependencies: - - git-cli -env: {} -parameters: - - name: head - type: string - default: '' - required: false - - name: commitAllowEmpty - type: boolean - default: false - required: false - - name: pushAfterCommit - type: boolean - default: true - required: false - - name: commitMessageStrategy - type: enum - values: [auto, manual] - default: auto - required: false - - name: message - type: string - default: '' - required: false -inputs: {} -outputs: - - name: commit_message - - name: pushed_branch -success_criteria: - - commit_created_or_skipped -steps: - - name: resolve-head - type: command - uses: git-cli - with: - command: git rev-parse --abbrev-ref HEAD - when: "parameters.head == ''" - save_as: head - - name: check-working-tree - type: command - uses: git-cli - with: - command: git status --porcelain - save_as: workingTree - - name: skip-if-empty - type: composite - with: - condition: "workingTree == '' && parameters.commitAllowEmpty == false" - set_outputs: - commit_message: '' - pushed_branch: "${head}" - mark_success: commit_created_or_skipped - - name: derive-message - type: composite - with: - strategy: "parameters.commitMessageStrategy" - manual_message: "parameters.message" - save_as: commitMessage - - name: commit - type: command - uses: git-cli - with: - command: "git add --all && git commit ${parameters.commitAllowEmpty ? '--allow-empty ' : ''}-m \"${commitMessage}\"" - save_as: commit_message - - name: push - type: command - uses: git-cli - with: - command: "git push -u origin ${head}" - when: "parameters.pushAfterCommit == true" - save_as: pushed_branch - diff --git a/.trae/skills/git.commit-push-smart/README.md b/.trae/skills/git.commit-push-smart/README.md deleted file mode 100644 index 9fc61bcf25..0000000000 --- a/.trae/skills/git.commit-push-smart/README.md +++ /dev/null @@ -1,40 +0,0 @@ -## 概述 -- 技能：git.commit-push-smart（智能提交并可选推送） -- 作用：检测工作树、生成提交信息、执行 commit 与 push（可选） - -## 参数 -- head（string，默认 ''）：目标分支；为空时自动推导当前分支 -- commitAllowEmpty（boolean，默认 false）：允许空提交 -- pushAfterCommit（boolean，默认 true）：提交后推送当前分支 -- commitMessageStrategy（enum: auto|manual，默认 auto）：提交信息生成策略 -- message（string，默认 ''）：手动消息（当 strategy=manual 或用于覆盖自动主题） - -## 输出 -- commit_message：实际提交信息 -- pushed_branch：推送分支名（当 pushAfterCommit=true） - -## 成功标准 -- commit_created_or_skipped：当工作树为空且不允许空提交时，视为“跳过但成功” - -## 失败案例与指引 -- 无 git/仓库未初始化：请在仓库根目录执行，确保已安装 git 且有有效远程 -- commitlint 不通过（如后续校验触发）：调整 message 或使用自动策略生成 -- 推送失败（权限/网络）：检查远程权限与网络代理；必要时稍后重试 - -## 示例调用 -- skill: git.commit-push-smart { pushAfterCommit: true, commitMessageStrategy: 'auto' } - -## 失败返回示例 -- 工作树为空且不允许空提交： - - 返回：commit_created_or_skipped - - 日志示例： - - `[INFO] working tree clean, skip commit` -- 推送失败（远程拒绝）： - - 返回：错误信息（非零退出） - - 日志示例： - - `! [rejected] HEAD -> origin/HEAD (fetch first)` - -## 修复步骤 -- 若需强制提交：设置 `commitAllowEmpty: true` 或在工作树中加入实际变更 -- 推送被拒绝：先执行 `git pull --rebase` 或 `git fetch && git merge`，解决冲突后再推送 -- 无远程权限：检查凭据与网络代理，确保 `origin` 指向可写仓库 diff --git a/.trae/skills/git.create-branch.skill.yaml b/.trae/skills/git.create-branch.skill.yaml deleted file mode 100644 index ab719f161b..0000000000 --- a/.trae/skills/git.create-branch.skill.yaml +++ /dev/null @@ -1,52 +0,0 @@ -id: git.create-branch -version: v1 -description: 从基础分支创建开发分支并返回分支名 -domain: git -runner: orchestrator -dependencies: - - git-cli -env: {} -parameters: - - name: baseBranch - type: string - default: develop - required: false - - name: branchPrefix - type: string - default: chore/trae - required: false - - name: topic - type: string - required: true - - name: useDateSuffix - type: boolean - default: true - required: false -outputs: - - name: branch_name -success_criteria: - - branch_created - - clean_working_tree -steps: - - name: sync-base - type: command - uses: git-cli - with: - command: "git fetch --all --prune && git checkout ${parameters.baseBranch} && git pull origin ${parameters.baseBranch}" - - name: gen-name - type: composite - with: - rule: "${parameters.branchPrefix}-${parameters.topic}-${parameters.useDateSuffix ? '${YYYYMMDD-HHMM}' : ''}" - save_as: branch_name - - name: create - type: command - uses: git-cli - with: - command: "git checkout -b ${branch_name}" - - name: verify - type: command - uses: git-cli - with: - command: "git status --porcelain" - save_as: workingTree - diff --git a/.trae/skills/git.create-branch/README.md b/.trae/skills/git.create-branch/README.md deleted file mode 100644 index 9beb82d742..0000000000 --- a/.trae/skills/git.create-branch/README.md +++ /dev/null @@ -1,32 +0,0 @@ -## 概述 -- 技能：git.create-branch（创建开发分支） -- 作用：同步基础分支、生成规范分支名并创建新分支 - -## 参数 -- baseBranch（string，默认 develop） -- branchPrefix（string，默认 chore/trae） -- topic（string，必填） -- useDateSuffix（boolean，默认 true） - -## 输出 -- branch_name：创建的分支名 - -## 成功标准 -- branch_created、clean_working_tree - -## 失败案例与指引 -- checkout/pull 失败：检查远程权限与网络 -- 命名冲突：修改 topic 或关闭日期后缀避免重复 - -## 示例调用 -- skill: git.create-branch { baseBranch: 'develop', branchPrefix: 'feat/chart', topic: 'v2-legend' } - -## 失败返回示例 -- 拉取基础分支失败： - - 返回：`fatal: could not read from remote repository` -- 分支名冲突： - - 返回：`fatal: A branch named '<name>' already exists` - -## 修复步骤 -- 检查网络与远程权限；必要时重新登录凭据或更新远程 URL -- 修改 `topic` 或关闭日期后缀以生成唯一分支名 diff --git a/.trae/skills/github.create-pr-from-file.skill.yaml b/.trae/skills/github.create-pr-from-file.skill.yaml deleted file mode 100644 index 2a76ee5883..0000000000 --- a/.trae/skills/github.create-pr-from-file.skill.yaml +++ /dev/null @@ -1,132 +0,0 @@ -id: github.create-pr-from-file -version: v1 -description: 使用本地或指定正文文件创建 GitHub PR -domain: github -runner: orchestrator -dependencies: - - gh-cli - - github-rest -env: - GITHUB_TOKEN: optional -parameters: - - name: base - type: string - default: develop - required: false - - name: head - type: string - default: '' - required: false - - name: title - type: string - required: true - - name: labels - type: array - default: [] - required: false - - name: draft - type: boolean - default: false - required: false - - name: mode - type: enum - values: [auto, gh, rest] - default: auto - required: false - - name: localBodyFile - type: boolean - default: true - required: false - - name: bodyFile - type: string - default: ./.trae/output/pr.body.local.md - required: false - - name: commitBeforeCreate - type: boolean - default: false - required: false - - name: commitMessage - type: string - default: '' - required: false - - name: commitAllowEmpty - type: boolean - default: false - required: false - - name: pushAfterCommit - type: boolean - default: true - required: false - - name: commitMessageStrategy - type: enum - values: [auto, manual] - default: auto - required: false -inputs: - - name: body_file - type: file - default: ./.trae/output/pr.body.local.md -outputs: - - name: pr_url -success_criteria: - - pr_created -steps: - - name: resolve-head - type: command - uses: git-cli - with: - command: git rev-parse --abbrev-ref HEAD - when: "parameters.head == ''" - save_as: head - - name: read-body - type: command - uses: shell - with: - command: "cat ${parameters.bodyFile}" - save_as: prBody - - name: fail-if-empty-body - type: composite - with: - condition: "prBody == ''" - error: "PR 正文为空或文件不存在" - - name: optional-commit - type: composite - with: - condition: "parameters.commitBeforeCreate == true" - sequence: - - type: command - uses: git-cli - with: - command: git status --porcelain - save_as: workingTree - - type: command - uses: git-cli - with: - command: "git add --all && git commit ${parameters.commitAllowEmpty ? '--allow-empty ' : ''}-m \"${parameters.commitMessage != '' ? parameters.commitMessage : 'sync changes before PR'}\"" - when: "workingTree != ''" - - type: command - uses: git-cli - with: - command: "git push -u origin ${head}" - when: "parameters.pushAfterCommit == true" - - name: create-pr-gh - type: command - uses: gh-cli - with: - command: "gh pr create --base ${parameters.base} --title \"${parameters.title}\" --head ${head} ${parameters.draft ? '--draft' : ''} --body-file ${parameters.bodyFile}" - when: "parameters.mode in ['auto','gh'] && tools.gh_cli_available == true" - save_as: pr_url - - name: create-pr-rest - type: tool - uses: github-rest - with: - endpoint: create-pull-request - base: "${parameters.base}" - head: "${head}" - title: "${parameters.title}" - body: "${prBody}" - labels: "${parameters.labels}" - draft: "${parameters.draft}" - when: "(parameters.mode == 'rest') || (parameters.mode == 'auto' && tools.gh_cli_available == false && env.GITHUB_TOKEN != '')" - save_as: pr_url - diff --git a/.trae/skills/github.create-pr-from-file/README.md b/.trae/skills/github.create-pr-from-file/README.md deleted file mode 100644 index 62c9069129..0000000000 --- a/.trae/skills/github.create-pr-from-file/README.md +++ /dev/null @@ -1,45 +0,0 @@ -## 概述 -- 技能：github.create-pr-from-file（使用本地或指定正文文件创建 PR） -- 作用：从文件读取 PR 正文，使用 gh 或 REST 创建 PR - -## 参数 -- base（string，默认 develop）：目标基线分支 -- head（string，默认 ''）：来源分支；为空自动推导当前分支 -- title（string，必填）：PR 标题 -- labels（array，默认 []）：标签列表 -- draft（boolean，默认 false）：是否草稿 -- mode（enum: auto|gh|rest，默认 auto）：创建方式 -- localBodyFile（boolean，默认 true）：是否使用默认正文路径 -- bodyFile（string，默认 ./.trae/output/pr.body.local.md）：正文文件路径 -- commitBeforeCreate（boolean，默认 false）：创建前是否自动提交 -- commitMessage/commitAllowEmpty/pushAfterCommit/commitMessageStrategy：提交相关配置 - -## 输出 -- pr_url：创建成功后的 PR 链接 - -## 成功标准 -- pr_created：接口或 CLI 返回成功，拿到链接 - -## 失败案例与指引 -- 正文为空或文件不存在：先执行 PR 正文生成技能或提供有效 bodyFile -- REST 403：参考 GitHub Token 文档，检查 Fine‑grained 权限与组织 SSO 授权 - - 文档参考：[github-token-local.md](file:///Users/bytedance/Documents/GitHub/VChart/.trae/documents/github-token-local.md) -- gh 未登录或权限不足：参考 GitHub CLI 文档，完成登录与 SSO 授权 - - 文档参考：[github-gh-local.md](file:///Users/bytedance/Documents/GitHub/VChart/.trae/documents/github-gh-local.md) - -## 示例调用 -- skill: github.create-pr-from-file { title: 'feat: add legend', mode: 'auto' } - -## 失败返回示例 -- 正文为空或文件不存在： - - 返回：`PR 正文为空或文件不存在` - - 日志示例：`[ERROR] body file not found: ./.trae/output/pr.body.local.md` -- REST 403（权限不足/未授权）： - - 返回：HTTP 403，`Resource not accessible by personal access token` -- gh 未登录： - - 返回：`gh: Not authenticated` - -## 修复步骤 -- 先执行 PR 正文生成技能或提供有效 `bodyFile` -- 使用 Fine‑grained `GITHUB_TOKEN` 并完成组织 SSO 授权（参考 token 文档）；或登录 `gh` 并授权（参考 gh 文档） -- 重新运行 dry-run：`./.trae/scripts/dry-run-create-pr.sh` 确认通道与正文文件 diff --git a/.trae/skills/github.pr-body-generate.skill.yaml b/.trae/skills/github.pr-body-generate.skill.yaml deleted file mode 100644 index 18741b95a0..0000000000 --- a/.trae/skills/github.pr-body-generate.skill.yaml +++ /dev/null @@ -1,85 +0,0 @@ -id: github.pr-body-generate -version: v1 -description: 生成 PR 正文与标题建议并写入本地文件 -domain: github -runner: orchestrator -dependencies: - - git-cli - - shell -env: {} -parameters: - - name: lang - type: enum - values: [zh, en] - default: zh - required: false - - name: title - type: string - default: '' - required: false - - name: head - type: string - default: '' - required: false - - name: labels - type: array - default: [] - required: false - - name: rushChangesDir - type: string - default: common/changes - required: false - - name: localBodyFile - type: boolean - default: true - required: false - - name: openEditor - type: boolean - default: false - required: false -inputs: - - name: autotestReport - type: file - default: ./.trae/output/autotest.report.local.md -outputs: - - name: generated_title - - name: generated_body_preview - - name: generated_body_file -success_criteria: - - body_generated -steps: - - name: resolve-head - type: command - uses: git-cli - with: - command: git rev-parse --abbrev-ref HEAD - when: "parameters.head == ''" - save_as: head - - name: select-template - type: composite - with: - path: "${parameters.lang == 'zh' ? '.github/PULL_REQUEST_TEMPLATE/pr_cn.md' : '.github/PULL_REQUEST_TEMPLATE.md'}" - save_as: templatePath - - name: build-body - type: composite - with: - head: head - rush_dir: "${parameters.rushChangesDir}" - autotest_report: inputs.autotestReport - labels: "${parameters.labels}" - lang: "${parameters.lang}" - title_hint: "${parameters.title}" - save_as: generated_body_preview - - name: gen-title - type: composite - with: - rule: "[Auto] ${parameters.title != '' ? parameters.title : head}" - save_as: generated_title - - name: write-file - type: command - uses: shell - with: - command: "echo \"${generated_body_preview}\" > ./.trae/output/pr.body.local.md" - when: "parameters.localBodyFile == true" - save_as: generated_body_file - diff --git a/.trae/skills/github.pr-body-generate/README.md b/.trae/skills/github.pr-body-generate/README.md deleted file mode 100644 index 62ff330a67..0000000000 --- a/.trae/skills/github.pr-body-generate/README.md +++ /dev/null @@ -1,29 +0,0 @@ -## 概述 -- 技能：github.pr-body-generate（生成 PR 正文与标题建议） -- 作用：选择模板、填充内容、输出预览与本地文件 - -## 参数 -- lang（enum: zh|en，默认 zh）、title、head、labels、rushChangesDir（默认 common/changes）、localBodyFile（默认 true）、openEditor（默认 false） - -## 输出 -- generated_title、generated_body_preview、generated_body_file（默认写入 ./.trae/output/pr.body.local.md） - -## 成功标准 -- body_generated - -## 失败案例与指引 -- 模板缺失：检查 .github/PULL_REQUEST_TEMPLATE 目录与路径 -- 关联信息为空：保留占位，后续人工补充 - -## 示例调用 -- skill: github.pr-body-generate { title: '[Auto] legend', lang: 'zh' } - -## 失败返回示例 -- 模板缺失： - - 返回：`[ERROR] template not found: .github/PULL_REQUEST_TEMPLATE/pr_cn.md` -- 写入失败（权限/路径不可写）： - - 返回：`[ERROR] cannot write to ./.trae/output/pr.body.local.md` - -## 修复步骤 -- 补齐模板文件或改用英文模板路径；确保路径正确 -- 确认仓库路径可写，或变更输出路径；必要时以管理员权限运行 diff --git a/.trae/skills/pipeline.release-prep.skill.yaml b/.trae/skills/pipeline.release-prep.skill.yaml deleted file mode 100644 index 94d72066b2..0000000000 --- a/.trae/skills/pipeline.release-prep.skill.yaml +++ /dev/null @@ -1,140 +0,0 @@ -id: pipeline.release-prep -version: v1 -description: 单步/串行编排 Autotest→Changelog→Commit→PR 的发布准备流程 -domain: pipeline -runner: orchestrator -dependencies: - - skill -env: {} -parameters: - - name: baseBranch - type: string - default: develop - required: false - - name: lang - type: enum - values: [zh, en] - default: zh - required: false - - name: labels - type: array - default: [changelog, test] - required: false - - name: topic - type: string - default: '' - required: false - - name: message - type: string - default: '' - required: false - - name: bumpType - type: enum - values: [auto, major, minor, patch] - default: auto - required: false - - name: notCommit - type: boolean - default: true - required: false - - name: head - type: string - default: '' - required: false - - name: commitAllowEmpty - type: boolean - default: false - required: false - - name: pushAfterCommit - type: boolean - default: true - required: false - - name: commitMessageStrategy - type: enum - values: [auto, manual] - default: auto - required: false - - name: flowStep - type: integer - default: 1 - required: false - - name: autoNext - type: boolean - default: false - required: false -outputs: - - name: autotest_report - - name: rush_change_entries - - name: commit_message - - name: pushed_branch - - name: pr_url - - name: next_step_hint -success_criteria: - - flow_step_completed -steps: - - name: step-1-autotest - type: composite - with: - call: test.autogen-from-diff - params: - tempReportPath: ./.trae/output/autotest.report.local.md - focusChangedOnly: false - save_as: autotest_report - when: "(parameters.autoNext == true && parameters.flowStep <= 1) || (parameters.autoNext != true && parameters.flowStep == 1)" - - name: step-2-changelog - type: composite - with: - call: release.changelog-rush-smart - params: - sinceBranch: "${parameters.baseBranch}" - message: "${parameters.message}" - bumpType: "${parameters.bumpType}" - notCommit: "${parameters.notCommit}" - save_as: rush_change_entries - when: "(parameters.autoNext == true && parameters.flowStep <= 2) || (parameters.autoNext != true && parameters.flowStep == 2)" - - name: step-3-commit - type: composite - with: - call: git.commit-push-smart - params: - head: "${parameters.head}" - commitAllowEmpty: "${parameters.commitAllowEmpty}" - pushAfterCommit: "${parameters.pushAfterCommit}" - commitMessageStrategy: "${parameters.commitMessageStrategy}" - message: "${parameters.message}" - save_as: commit_message - when: "(parameters.autoNext == true && parameters.flowStep <= 3) || (parameters.autoNext != true && parameters.flowStep == 3)" - - name: step-4-body - type: composite - with: - call: github.pr-body-generate - params: - title: "[Auto] ${parameters.topic != '' ? parameters.topic : parameters.head}" - head: "${parameters.head}" - lang: "${parameters.lang}" - labels: "${parameters.labels}" - rushChangesDir: common/changes - localBodyFile: true - save_as: generated_body_file - when: "(parameters.autoNext == true && parameters.flowStep <= 4) || (parameters.autoNext != true && parameters.flowStep == 4)" - - name: step-5-pr - type: composite - with: - call: github.create-pr-from-file - params: - base: "${parameters.baseBranch}" - head: "${parameters.head}" - title: "[Auto] ${parameters.topic != '' ? parameters.topic : parameters.head}" - lang: "${parameters.lang}" - labels: "${parameters.labels}" - mode: auto - localBodyFile: true - bodyFile: ./.trae/output/pr.body.local.md - save_as: pr_url - when: "(parameters.autoNext == true && parameters.flowStep <= 5) || (parameters.autoNext != true && parameters.flowStep == 5)" - - name: next-step-hint - type: composite - with: - condition: "parameters.autoNext != true && parameters.flowStep < 5" - value: "在单步模式，下一步：flowStep=${parameters.flowStep + 1}" - save_as: next_step_hint diff --git a/.trae/skills/pipeline.release-prep/README.md b/.trae/skills/pipeline.release-prep/README.md deleted file mode 100644 index 9921c832fe..0000000000 --- a/.trae/skills/pipeline.release-prep/README.md +++ /dev/null @@ -1,30 +0,0 @@ -## 概述 -- 技能：pipeline.release-prep（发布准备编排） -- 作用：单步/串行执行 Autotest→Changelog→Commit→PR - -## 参数 -- baseBranch、lang、labels、topic、message、bumpType、notCommit、head、commitAllowEmpty、pushAfterCommit、commitMessageStrategy、flowStep、autoNext - -## 输出 -- autotest_report、rush_change_entries、commit_message、pushed_branch、pr_url、next_step_hint - -## 成功标准 -- flow_step_completed - -## 失败案例与指引 -- 任一步骤失败：依据该子技能 README 的排查指引；串行模式会在失败处停止 - -## 示例调用 -- 单步：skill: pipeline.release-prep { flowStep: 1 } -- 串行：skill: pipeline.release-prep { autoNext: true } - -## 失败返回示例 -- 任一步骤失败时： - - 返回：子技能的错误信息，编排在该步骤停止 - - 示例：`[step-3-commit] push rejected` / `[step-2-changelog] commitlint failed` - -## 修复步骤 -- 依据错误源查看对应技能 README 并按指引修复 -- 使用 dry-run 脚本定位问题： - - `./.trae/scripts/dry-run-release-prep.sh` 展示流程 - - 逐步运行各子脚本验证环境与凭据 diff --git a/.trae/skills/release.changelog-rush-smart.skill.yaml b/.trae/skills/release.changelog-rush-smart.skill.yaml deleted file mode 100644 index 3a21f804b1..0000000000 --- a/.trae/skills/release.changelog-rush-smart.skill.yaml +++ /dev/null @@ -1,92 +0,0 @@ -id: release.changelog-rush-smart -version: v1 -description: 根据差异与提交生成 Rush 变更条目并构建消息 -domain: release -runner: orchestrator -dependencies: - - git-cli - - rush-cli - - shell - - github-rest -env: - GITHUB_TOKEN: optional -parameters: - - name: sinceBranch - type: string - default: develop - required: false - - name: message - type: string - default: '' - required: false - - name: bumpType - type: enum - values: [auto, major, minor, patch] - default: auto - required: false - - name: notCommit - type: boolean - default: true - required: false - - name: githubToken - type: string - default: '' - required: false -outputs: - - name: rush_change_entries - - name: computed_bump_type - - name: final_message -success_criteria: - - rush_changes_generated - - commitlint_passed -steps: - - name: diff-files - type: command - uses: git-cli - with: - command: "git diff --name-only ${parameters.sinceBranch}...HEAD" - save_as: changedFiles - - name: log-subjects - type: command - uses: git-cli - with: - command: "git log --pretty=%H:::%s ${parameters.sinceBranch}...HEAD" - save_as: commitSubjects - - name: compute-bump - type: composite - with: - strategy: "auto-from-commits" - override: "${parameters.bumpType}" - save_as: computed_bump_type - - name: build-message - type: composite - with: - base_message: "${parameters.message}" - commits: commitSubjects - use_github: "${env.GITHUB_TOKEN != '' || parameters.githubToken != ''}" - save_as: final_message - - name: commitlint - type: command - uses: shell - with: - command: "echo \"${final_message}\" | commitlint --config common/autoinstallers/lint/commitlint.config.js" - - name: rush-change - type: command - uses: rush-cli - with: - command: "rush change --bulk --bump-type '${computed_bump_type}' --message '${final_message}'" - save_as: rush_change_entries - - name: optional-commit - type: composite - with: - condition: "parameters.notCommit != true" - sequence: - - type: command - uses: git-cli - with: - command: git add --all - - type: command - uses: git-cli - with: - command: "git commit -m 'docs: update changlog of rush'" - diff --git a/.trae/skills/release.changelog-rush-smart/README.md b/.trae/skills/release.changelog-rush-smart/README.md deleted file mode 100644 index 221859c828..0000000000 --- a/.trae/skills/release.changelog-rush-smart/README.md +++ /dev/null @@ -1,33 +0,0 @@ -## 概述 -- 技能：release.changelog-rush-smart（生成 Rush 变更条目与富消息） -- 作用：采集差异与提交、自动判定 bump 类型、构建消息并运行 rush change - -## 参数 -- sinceBranch（string，默认 develop） -- message（string，默认 ''） -- bumpType（enum: auto|major|minor|patch，默认 auto） -- notCommit（boolean，默认 true） -- githubToken（string，默认 ''）：用于聚合 Issue 标题 - -## 输出 -- rush_change_entries、computed_bump_type、final_message - -## 成功标准 -- rush_changes_generated、commitlint_passed - -## 失败案例与指引 -- commitlint 不通过：调整 message 或按提交主题自动生成 -- GitHub 标题聚合失败：检查 token、组织 SSO 与仓库权限 - -## 示例调用 -- skill: release.changelog-rush-smart { sinceBranch: 'develop', bumpType: 'auto' } - -## 失败返回示例 -- commitlint 不通过： - - 返回：`✖ subject may not be empty [subject-empty]` -- rush change 失败： - - 返回：`Error: rush change ...`（权限/路径问题） - -## 修复步骤 -- 按规范修订 `message` 或使用自动生成；必要时在 `common/autoinstallers/lint/commitlint.config.js` 验证规则 -- 确认 Rush 环境与仓库结构；在仓库根目录运行，确保有 `common/changes/` diff --git a/.trae/skills/test.autogen-from-diff.skill.yaml b/.trae/skills/test.autogen-from-diff.skill.yaml deleted file mode 100644 index ea86987f94..0000000000 --- a/.trae/skills/test.autogen-from-diff.skill.yaml +++ /dev/null @@ -1,105 +0,0 @@ -id: test.autogen-from-diff -version: v1 -description: 根据分支差异与导出符号，自动生成或增量更新单测并输出报告 -domain: testing -runner: orchestrator -dependencies: - - rush-cli - - jest-cli -env: {} -parameters: - - name: project - type: string - default: auto - required: false - - name: mode - type: enum - values: [full] - default: full - required: false - - name: noSnapshot - type: boolean - default: false - required: false - - name: onlyNew - type: boolean - default: false - required: false - - name: applyManualOverrides - type: boolean - default: true - required: false - - name: replaceAutogen - type: boolean - default: false - required: false - - name: dryRun - type: boolean - default: false - required: false - - name: preview - type: boolean - default: false - required: false - - name: stopOnError - type: boolean - default: true - required: false - - name: focusChangedOnly - type: boolean - default: false - required: false - - name: snapshotStrategy - type: enum - values: [combined] - default: combined - required: false - - name: tempReportPath - type: string - default: ./.trae/output/autotest.report.local.md - required: false -inputs: - - name: diff_json - type: file - default: ./.trae/output/diff.json -outputs: - - name: test_files - - name: snapshots - - name: coverage_report - - name: manual_nodes - - name: temp_markdown_report -success_criteria: - - tests_generated_for_changed_exports - - compile_without_errors - - coverage_increase_or_maintained -steps: - - name: analyze - type: composite - with: - source: diff_json - strategy: exports-and-branches - - name: generate-tests - type: composite - with: - layout: __tests__/*.test.ts - comments: function-level-jsdoc - autogen_block: true - only_new: "${parameters.onlyNew}" - replace_autogen: "${parameters.replaceAutogen}" - - name: run-tests - type: command - uses: rush-cli - with: - command: "rush run ${parameters.project != 'auto' ? '-p ' + parameters.project : ''} -s test" - - name: run-coverage - type: command - uses: rush-cli - with: - command: "rush run ${parameters.project != 'auto' ? '-p ' + parameters.project : ''} -s test-cov" - - name: write-report - type: command - uses: shell - with: - command: "echo '# Autotest 报告' > ${parameters.tempReportPath}" - save_as: temp_markdown_report - diff --git a/.trae/skills/test.autogen-from-diff/README.md b/.trae/skills/test.autogen-from-diff/README.md deleted file mode 100644 index 3261acd6df..0000000000 --- a/.trae/skills/test.autogen-from-diff/README.md +++ /dev/null @@ -1,43 +0,0 @@ -## 概述 - -- 技能：test.autogen-from-diff（根据差异自动生成/增量更新单测） -- 作用：识别导出符号与分支，生成 **tests**/\*.test.ts（含函数级 JSDoc 注释），执行覆盖率与报告 - -## 参数 - -- project（string，默认 auto）：自动识别变更包或指定包名 -- mode（enum: full，默认 full） -- noSnapshot/onlyNew/applyManualOverrides/replaceAutogen/dryRun/preview/stopOnError/focusChangedOnly/snapshotStrategy/tempReportPath - -## 输出 - -- test_files、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 - -## 失败案例与指引 - -- 编译/类型错误：修复 TS 诊断后重试；报告中会标注阻断项 -- rush/jest 不可用：改用 npm/yarn 脚本或安装 rush；参数 preview/dryRun 可用于生成但不执行 -- 快照不稳定：使用固定时间与随机数的 mock；必要时增量快照策略 - -## 示例调用 - -- skill: test.autogen-from-diff { project: '@visactor/vchart', onlyNew: false } - -## 失败返回示例 - -- TypeScript 编译错误： - - 返回：`TSxxxx: ...` -- rush 不可用： - - 返回：`rush: command not found` -- 覆盖率任务失败： - - 返回：jest 失败摘要与非零退出 - -## 修复步骤 - -- 修复 TS 诊断与依赖，再重试；必要时启用 `dryRun: true` 仅生成测试不执行 -- 安装或改用 npm/yarn 脚本运行测试；确保 `package.json` 有对应脚本 -- 快照问题：固定时间/随机数 mock，必要时调整 `snapshotStrategy` diff --git a/.trae/skills/vcs.diff-collect.skill.yaml b/.trae/skills/vcs.diff-collect.skill.yaml deleted file mode 100644 index 552e274bc1..0000000000 --- a/.trae/skills/vcs.diff-collect.skill.yaml +++ /dev/null @@ -1,69 +0,0 @@ -id: vcs.diff-collect -version: v1 -description: 采集分支差异与工作树变更并生成结构化 JSON -domain: vcs -runner: orchestrator -dependencies: - - git-cli -env: {} -parameters: - - name: sinceBranch - type: string - default: develop - required: false - - name: includeWorkingTree - type: boolean - default: true - required: false -inputs: {} -outputs: - - name: diff_json - path: ./.trae/output/diff.json -success_criteria: - - diff_collected -steps: - - name: fetch - type: command - uses: git-cli - with: - command: git fetch --all --prune - - name: diff-files - type: command - uses: git-cli - with: - command: "git diff --name-status --diff-filter=AMR ${parameters.sinceBranch}...HEAD" - save_as: changedFiles - - name: working-tree - type: command - uses: git-cli - with: - command: git status --porcelain - when: "parameters.includeWorkingTree == true" - save_as: workingTree - - name: line-diff - type: composite - with: - for_each: changedFiles - do: - - type: command - uses: git-cli - with: - command: "git diff --unified=0 ${parameters.sinceBranch}...HEAD ${item}" - save_as: lineDiffCommitted - - type: command - uses: git-cli - with: - command: "git diff --cached --unified=0 -- ${item}" - save_as: lineDiffStaged - - type: command - uses: git-cli - with: - command: "git diff --unified=0 -- ${item}" - save_as: lineDiffUnstaged - - name: write-json - type: command - uses: shell - with: - command: "echo '{}' > ./.trae/output/diff.json" - save_as: diff_json - diff --git a/.trae/skills/vcs.diff-collect/README.md b/.trae/skills/vcs.diff-collect/README.md deleted file mode 100644 index 25aa4122c3..0000000000 --- a/.trae/skills/vcs.diff-collect/README.md +++ /dev/null @@ -1,30 +0,0 @@ -## 概述 -- 技能：vcs.diff-collect（采集分支差异与工作树变更） -- 作用：生成结构化差异信息（文件列表与行级片段），输出 JSON - -## 参数 -- sinceBranch（string，默认 develop）：对比基线分支 -- includeWorkingTree（boolean，默认 true）：是否包含工作树变更 - -## 输出 -- diff_json：写入 ./.trae/output/diff.json - -## 成功标准 -- diff_collected：完成差异采集 - -## 失败案例与指引 -- 无 git/远程不可用：先执行 git fetch 或确认仓库状态 -- 差异为空：按需改用指定 project 的 Autotest 运行方式 - -## 示例调用 -- skill: vcs.diff-collect { sinceBranch: 'develop' } - -## 失败返回示例 -- 基线分支不存在： - - 返回：`fatal: bad revision 'develop...HEAD'` -- 差异为空： - - 返回：`changedFiles=[]` - -## 修复步骤 -- 先 `git fetch --all --prune` 同步远程；确认 `sinceBranch` 存在 -- 若差异为空而需继续流程：在 Autotest 中指定 `project` 明确运行目标包 From 90f1718763757575dcc3276c00bbf14123851695 Mon Sep 17 00:00:00 2001 From: "lixuefei.1313" <lixuef1313@163.com> Date: Mon, 5 Jan 2026 16:17:04 +0800 Subject: [PATCH 07/10] feat: add skills --- .trae/skills/auto-flow/SKILL.md | 90 +++++++++++++++++++ .trae/skills/auto-flow/docs/USAGE.md | 53 +++++++++++ .trae/skills/auto-test/SKILL.md | 65 ++++++++++++++ .trae/skills/auto-test/docs/USAGE.md | 36 ++++++++ .trae/skills/changelog-rush-smart/SKILL.md | 56 ++++++++++++ .../skills/changelog-rush-smart/docs/USAGE.md | 35 ++++++++ .trae/skills/commit-smart/SKILL.md | 58 ++++++++++++ .trae/skills/commit-smart/docs/USAGE.md | 33 +++++++ .trae/skills/create-branch/SKILL.md | 52 +++++++++++ .trae/skills/create-branch/docs/USAGE.md | 28 ++++++ .trae/skills/pr-body-generate/SKILL.md | 58 ++++++++++++ .trae/skills/pr-body-generate/docs/GH_CLI.md | 41 +++++++++ .../pr-body-generate/docs/GITHUB_TOKEN.md | 31 +++++++ .trae/skills/pr-body-generate/docs/USAGE.md | 36 ++++++++ .trae/skills/pr-create-from-body/SKILL.md | 60 +++++++++++++ .../skills/pr-create-from-body/docs/GH_CLI.md | 41 +++++++++ .../pr-create-from-body/docs/GITHUB_TOKEN.md | 31 +++++++ .../skills/pr-create-from-body/docs/USAGE.md | 37 ++++++++ 18 files changed, 841 insertions(+) create mode 100755 .trae/skills/auto-flow/SKILL.md create mode 100755 .trae/skills/auto-flow/docs/USAGE.md create mode 100755 .trae/skills/auto-test/SKILL.md create mode 100755 .trae/skills/auto-test/docs/USAGE.md create mode 100755 .trae/skills/changelog-rush-smart/SKILL.md create mode 100755 .trae/skills/changelog-rush-smart/docs/USAGE.md create mode 100755 .trae/skills/commit-smart/SKILL.md create mode 100755 .trae/skills/commit-smart/docs/USAGE.md create mode 100755 .trae/skills/create-branch/SKILL.md create mode 100755 .trae/skills/create-branch/docs/USAGE.md create mode 100755 .trae/skills/pr-body-generate/SKILL.md create mode 100755 .trae/skills/pr-body-generate/docs/GH_CLI.md create mode 100755 .trae/skills/pr-body-generate/docs/GITHUB_TOKEN.md create mode 100755 .trae/skills/pr-body-generate/docs/USAGE.md create mode 100755 .trae/skills/pr-create-from-body/SKILL.md create mode 100755 .trae/skills/pr-create-from-body/docs/GH_CLI.md create mode 100755 .trae/skills/pr-create-from-body/docs/GITHUB_TOKEN.md create mode 100755 .trae/skills/pr-create-from-body/docs/USAGE.md diff --git a/.trae/skills/auto-flow/SKILL.md b/.trae/skills/auto-flow/SKILL.md new file mode 100755 index 0000000000..3c19275e2e --- /dev/null +++ b/.trae/skills/auto-flow/SKILL.md @@ -0,0 +1,90 @@ +--- +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` 技能。 + - **目的**: 为代码变更生成并运行单元测试。 + - **检查点**: 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 正文。 + - **检查点**: Agent 会返回生成的 PR 正文预览和本地文件路径。**你应审阅正文内容，确保其完整和准确（可在此步之后手动修改文件），然后指示 Agent 继续。** + +5. **创建 PR** + - **执行**: `pr-create-from-body` 技能。 + - **目的**: 使用上一步生成的正文文件，在 GitHub 上创建 Pull Request。 + - **检查点**: Agent 会返回最终的 PR 链接。**你需要访问链接确认 PR 是否按预期创建。** + +## 何时使用 / 边界 + +- **使用时机**: + - 当你完成一个功能或修复，准备发起一个完整的、高质量的 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..c4da10d50f --- /dev/null +++ b/.trae/skills/auto-flow/docs/USAGE.md @@ -0,0 +1,53 @@ +# 使用说明：auto-flow + +本技能将创建 Pull Request 的所有准备工作（测试、变更日志、提交、生成正文、创建 PR）串联成一个标准化的五步流程。 + +## 何时使用 + +- **发布准备**: 当你完成一个功能或修复，准备发起一个完整的、高质量的 Pull Request 时，使用此技能可以确保所有检查项都已完成。 +- **标准化贡献**: 团队成员可以使用此流程来确保所有贡献都遵循相同的质量标准。 + +## 流程与人工检查点 + +本技能是一个带有“门禁”的流水线，每一步完成后都会暂停，等待你的确认： + +1. **自动测试**: 技能首先为你的代码变更生成并运行测试。 + * **你需要**: 检查测试报告，确认覆盖率和测试结果符合预期。 + +2. **生成变更日志**: 接着，它会为你的提交创建 `changelog` 文件。 + * **你需要**: 检查 `common/changes/` 目录下生成的文件内容是否准确。 + +3. **智能提交**: 然后，所有变更会被打包成一个规范的 Git 提交并推送。 + * **你需要**: 确认自动生成的提交信息是正确的。 + +4. **生成 PR 正文**: 技能会自动填充 PR 模板。 + * **你需要**: 审阅生成的 PR 正文，可选择在本地修改 `.md` 文件。 + +5. **创建 PR**: 最后，使用准备好的正文创建 PR。 + * **你需要**: 访问返回的 PR 链接，做最终确认。 + +## 示例对话 + +> **你**: “启动 `auto-flow` 流程，为我的新功能做发布准备。” +> +> **Agent**: (执行第一步) “第一步：测试已完成，报告位于 `.../autotest.report.local.md`。请检查后告诉我是否继续。” +> +> **你**: (检查后) “继续。” +> +> **Agent**: (执行第二步) “第二步：变更日志已生成。请检查 `common/changes/` 目录。确认无误后，请告诉我是否继续。” +> +> **你**: “继续。” +> +> *... (Agent 会继续执行后续步骤，并在每一步后请求确认)* + +## 关键参数 + +- `baseBranch`: PR 的目标分支，默认为 `develop`。 +- `topic`: 用于生成 PR 标题，建议提供。 +- `message`: 用于 `changelog` 和 `commit` 的自定义消息。 + +## 注意事项 + +- **凭证**: 确保 `GITHUB_TOKEN` 或 `gh` CLI 已正确配置，否则最后一步会失败。 +- **顺序固定**: 本技能的五个步骤是固定的，不能跳过或重排。 +- **失败中断**: 流程中任何一步失败都会导致整个流程中断。 diff --git a/.trae/skills/auto-test/SKILL.md b/.trae/skills/auto-test/SKILL.md new file mode 100755 index 0000000000..b8bb2996b8 --- /dev/null +++ b/.trae/skills/auto-test/SKILL.md @@ -0,0 +1,65 @@ +--- +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 格式临时报告。 +- **成功标准**: + - `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}}`。 + +## 何时使用 / 边界 + +- **使用时机**: + - 在完成一部分代码开发后，需要快速验证变更的正确性并补充单元测试时。 + - 在准备提交代码前，确保所有改动都被测试覆盖。 + - 作为持续集成流程的一部分，用于自动化回归测试。 +- **边界**: + - 此技能专注于单元测试，无法替代集成测试或端到端测试。 + - 对于复杂的业务逻辑或需要精细 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..cb2d7bc0e3 --- /dev/null +++ b/.trae/skills/auto-test/docs/USAGE.md @@ -0,0 +1,36 @@ +# 使用说明：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` 依赖已正确安装。 diff --git a/.trae/skills/changelog-rush-smart/SKILL.md b/.trae/skills/changelog-rush-smart/SKILL.md new file mode 100755 index 0000000000..a5a7a5a4a6 --- /dev/null +++ b/.trae/skills/changelog-rush-smart/SKILL.md @@ -0,0 +1,56 @@ +--- +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 暂存区并创建一个提交。 + +## 何时使用 / 边界 + +- **使用时机**: + - 在完成一个或多个功能的开发、即将发起 Pull Request 之前，用于生成标准的 `changelog` 条目。 + - 当你需要遵循 `VChart` 项目的版本发布流程，为你的变更创建记录时。 +- **边界**: + - 此技能只负责生成 `common/changes/**` 下的变更文件，它本身不执行版本发布 (`rush publish`)。 + - 自动生成的消息质量依赖于良好、规范的 Git 提交历史。 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..17b724bf85 --- /dev/null +++ b/.trae/skills/changelog-rush-smart/docs/USAGE.md @@ -0,0 +1,35 @@ +# 使用说明：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 的标题。 + +## 注意事项 + +- 自动生成的消息质量高度依赖于规范、清晰的 Git 提交历史。 +- 本技能仅生成 `common/changes/**` 下的文件，不执行 `rush version` 或 `rush publish`。 +- 如果需要自动关联 Issue 标题，请确保 `GITHUB_TOKEN` 已在环境中正确配置。 diff --git a/.trae/skills/commit-smart/SKILL.md b/.trae/skills/commit-smart/SKILL.md new file mode 100755 index 0000000000..bd65815114 --- /dev/null +++ b/.trae/skills/commit-smart/SKILL.md @@ -0,0 +1,58 @@ +--- +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/<name>`）或顶层目录来确定。 + - **主题(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}}` 将提交推送到远程仓库。 + +## 何时使用 / 边界 + +- **使用时机**: + - 在执行了 `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..d55a1bc8e8 --- /dev/null +++ b/.trae/skills/commit-smart/docs/USAGE.md @@ -0,0 +1,33 @@ +# 使用说明：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` 忽略的变更添加到提交中。请在执行前仔细检查你的工作区，确保没有不想提交的临时文件或改动。 +- 执行前请确保当前分支没有合并冲突，且远程分支已存在。 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..6dacbc3b91 --- /dev/null +++ b/.trae/skills/pr-body-generate/SKILL.md @@ -0,0 +1,58 @@ +--- +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 正文。 | + +## 输出与成功标准 + +- **主要输出**: + - `generated_title`: 推荐的 PR 标题。 + - `generated_body_preview`: 生成的完整 PR 正文的 Markdown 预览。 + - `generated_body_file`: 本地保存 PR 正文的文件路径（默认为 `.trae/output/pr.body.local.md`）。 +- **成功标准**: + - `body_generated`: PR 正文已成功生成并按需保存到本地文件。 + +## 执行步骤 + +1. **选择模板**: 根据 `lang` 参数，Agent 会选择对应的 PR 模板文件（例如 `.github/PULL_REQUEST_TEMPLATE/pr_cn.md`）。 +2. **填充内容**: Agent 会自动执行以下填充操作： + - **Changelog**: 解析 `{{rushChangesDir}}` 目录下的变更条目，并填充到正文的 Changelog 部分。 + - **自测项**: 如果 `autotestReport` 文件存在，会将其中的测试摘要信息填充到自测/走查部分。 + - **背景与方案**: 基于 `message` 参数（如果提供）和提交历史，生成简要的背景与方案描述。 + - **元信息**: 填充分支、标签等信息。 +3. **输出与保存**: + - Agent 会生成一个建议的 PR 标题。 + - 将完整的 PR 正文以 Markdown 预览形式展示。 + - 如果 `localBodyFile` 为 `true`，会将纯净的 Markdown 正文内容保存到 `.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..b231442426 --- /dev/null +++ b/.trae/skills/pr-body-generate/docs/GH_CLI.md @@ -0,0 +1,41 @@ +# GitHub CLI (gh) 核心指南 + +GitHub CLI (`gh`) 是 `pr-create-from-body` 技能的备选执行器。当 `GITHUB_TOKEN` 未设置时，技能会尝试使用 `gh` 来创建 Pull Request。 + +## 安装与登录 + +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` 时，会优先检查 `GITHUB_TOKEN`。如果未找到，则会调用本机的 `gh` 命令来创建 PR。 + +**示例命令 (由技能在内部执行):** +```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..5a8a7c4094 --- /dev/null +++ b/.trae/skills/pr-body-generate/docs/USAGE.md @@ -0,0 +1,36 @@ +# 使用说明：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` 生成的测试报告。 +- **人工审查**: 自动生成的内容是草稿，强烈建议在执行下一步前，打开本地生成的 `.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..067639a402 --- /dev/null +++ b/.trae/skills/pr-create-from-body/SKILL.md @@ -0,0 +1,60 @@ +--- +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 模式**: 自动选择可用的最佳方式。 + +4. **输出结果**: 如果 PR 创建成功，Agent 会返回该 PR 的 URL。如果失败，则会返回详细的错误信息。 + +## 何时使用 / 边界 + +- **使用时机**: + - 在使用 `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..b231442426 --- /dev/null +++ b/.trae/skills/pr-create-from-body/docs/GH_CLI.md @@ -0,0 +1,41 @@ +# GitHub CLI (gh) 核心指南 + +GitHub CLI (`gh`) 是 `pr-create-from-body` 技能的备选执行器。当 `GITHUB_TOKEN` 未设置时，技能会尝试使用 `gh` 来创建 Pull Request。 + +## 安装与登录 + +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` 时，会优先检查 `GITHUB_TOKEN`。如果未找到，则会调用本机的 `gh` 命令来创建 PR。 + +**示例命令 (由技能在内部执行):** +```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..6acb1c330e --- /dev/null +++ b/.trae/skills/pr-create-from-body/docs/USAGE.md @@ -0,0 +1,37 @@ +# 使用说明：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` 指向的文件存在且内容正确。 From 22b388cd6e459a21567e3964eea4e499866b8ba9 Mon Sep 17 00:00:00 2001 From: "lixuefei.1313" <lixuef1313@163.com> Date: Mon, 5 Jan 2026 16:31:10 +0800 Subject: [PATCH 08/10] feat: remove jobs --- .trae/documents/auto-flow.solo.md | 34 ---- .trae/documents/auto-test.solo.md | 60 ------ .trae/documents/changelog-rush-smart.solo.md | 24 --- .trae/documents/create-branch.solo.md | 20 -- .trae/documents/github-gh-local.md | 96 --------- .trae/documents/github-token-local.md | 199 ------------------- .trae/documents/pr-body-generate.solo.md | 36 ---- .trae/documents/pr-create-from-body.solo.md | 42 ---- .trae/jobs/README.md | 80 -------- .trae/jobs/auto-flow.md | 108 ---------- .trae/jobs/auto-test.md | 142 ------------- .trae/jobs/changelog-rush-smart.md | 82 -------- .trae/jobs/commit-smart.md | 54 ----- .trae/jobs/create-branch.md | 52 ----- .trae/jobs/pr-body-generate.md | 60 ------ .trae/jobs/pr-create-from-body.md | 63 ------ 16 files changed, 1152 deletions(-) delete mode 100644 .trae/documents/auto-flow.solo.md delete mode 100644 .trae/documents/auto-test.solo.md delete mode 100644 .trae/documents/changelog-rush-smart.solo.md delete mode 100644 .trae/documents/create-branch.solo.md delete mode 100644 .trae/documents/github-gh-local.md delete mode 100644 .trae/documents/github-token-local.md delete mode 100644 .trae/documents/pr-body-generate.solo.md delete mode 100644 .trae/documents/pr-create-from-body.solo.md delete mode 100644 .trae/jobs/README.md delete mode 100644 .trae/jobs/auto-flow.md delete mode 100644 .trae/jobs/auto-test.md delete mode 100644 .trae/jobs/changelog-rush-smart.md delete mode 100644 .trae/jobs/commit-smart.md delete mode 100644 .trae/jobs/create-branch.md delete mode 100644 .trae/jobs/pr-body-generate.md delete mode 100644 .trae/jobs/pr-create-from-body.md 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 <project> -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/github-gh-local.md b/.trae/documents/github-gh-local.md deleted file mode 100644 index d2f58abb93..0000000000 --- a/.trae/documents/github-gh-local.md +++ /dev/null @@ -1,96 +0,0 @@ -# GitHub CLI（gh）使用说明（创建 PR） - -- 作用：指导在 macOS 上安装与登录 `gh`，并用于创建 PR；与 `GITHUB_TOKEN` 文档保持一致的权限与注意事项 - -## 安装与更新（macOS） - -- 安装：`brew install gh` -- 更新：`brew upgrade gh` -- 验证：`gh --version`（建议使用较新版本以支持 `--body-file`） - -## 登录与授权 - -- 交互登录：`gh auth login` - - 选择 `GitHub.com` - - 选择协议：推荐 `HTTPS`（SSH 仅用于 git 操作） - - 选择登录方式：`Login with a web browser` 或 `Paste an authentication token` - - 完成浏览器授权后返回终端，`gh` 会在本地安全存储凭据 -- 组织 SSO：若目标仓库在组织下且开启 SSO，需为 `gh` 的凭据完成 SSO 授权，否则会出现 403 -- 状态查看：`gh auth status`（显示当前登录主机与权限） -- 登出与切换：`gh auth logout`（可指定主机 `-h github.com`）后重新登录 - -## 本地凭据存储 - -- `gh` 会将 OAuth/PAT 凭据安全存储在 macOS Keychain 中 -- 无需手动设置环境变量；与 `GITHUB_TOKEN` 互为备选方案（Job 默认优先 REST，再回退 `gh`） - -## 在 Job 中的使用 - -- `./.trae/jobs/pr-create-from-body.md` - - `mode: auto`：默认优先 REST（读取 `GITHUB_TOKEN`），其次使用 `gh` - - 正文仅从文件读取：`bodyFile` 或默认 `./.trae/output/pr.body.local.md` - - `gh` 创建命令示例： - - `gh pr create --base <base> --head <head> --title "<title>" --body-file <path> --label <label1> --label <label2> --draft` - - 成功输出 `pr_url`；失败输出错误信息，不展示 compare URL - -## 注意事项（与 Token 文档同步） - -- 最小权限原则：`gh` 登录时仅授权必要范围；组织仓库需完成 SSO 授权 -- 不要将凭据写入仓库或日志；避免在聊天中粘贴敏感信息 -- 定期检查与轮换凭据；遇到 401/403 优先排查授权与 SSO 状态 -- 仓库识别：`gh` 默认从当前目录的 git 远程推断目标仓库（确保 `origin` 指向 GitHub 仓库） - -## 常见问题排查 - -- 命令不可用：`gh --version` 检查是否已安装；`brew reinstall gh` -- 未登录或失效：`gh auth status`；如需重登：`gh auth logout && gh auth login` -- 403 权限不足：检查组织 SSO 授权、仓库可见性与权限范围 -- `--body-file` 不生效：升级 `gh` 到较新版本；或退化为读取文件内容并传入 `--body` -- 仓库识别失败：`gh repo view` 测试当前目录是否已关联 GitHub 仓库；必要时在仓库根目录执行命令 - -## 快速命令示例（macOS） - -- 安装与版本： - - `brew install gh && gh --version` -- 登录（浏览器方式）： - - `gh auth login` -- 查看状态： - - `gh auth status` -- 创建 PR（从文件正文）： - - `gh pr create --base develop --head chore/feature-xyz --title "feat(xyz): add auto layout" --body-file ./.trae/output/pr.body.local.md` - -## 安装与使用（Windows） - -### 安装与更新（Windows） - -- 通过 `winget` 安装：`winget install GitHub.cli` -- 或通过 `chocolatey` 安装：`choco install gh` -- 或到官方发布页下载 MSI 安装包：`https://github.com/cli/cli/releases` -- 验证：`gh --version` - -### 登录与授权（Windows） - -- 执行：`gh auth login` - - 选择 `GitHub.com` - - 选择协议：推荐 `HTTPS` - - 选择登录方式：`Login with a web browser` 或 `Paste an authentication token` -- 组织 SSO：若目标仓库在组织下且开启 SSO，需完成 SSO 授权 -- 查看状态：`gh auth status` -- 退出/切换：`gh auth logout -h github.com` - -### 本地凭据存储（Windows） - -- `gh` 默认使用 Windows Credential Manager 安全存储凭据 -- 无需设置环境变量；作为 `GITHUB_TOKEN` 的备选方案 - -### 在 Job 中的使用（Windows） - -- 同 macOS，`mode: auto` 优先 REST（读取 `GITHUB_TOKEN`），其次 `gh` -- 从文件正文创建： - - `gh pr create --base develop --head <branch> --title "<title>" --body-file ./.trae/output/pr.body.local.md` - -### 常见问题排查（Windows） - -- `gh` 未找到：确认已安装并检查 PATH；`winget list GitHub.cli` 或 `choco upgrade gh` -- 403：检查组织 SSO 授权与仓库权限 -- `--body-file` 不生效：升级 `gh` 到较新版本；退化为 `--body` 读取文件内容 diff --git a/.trae/documents/github-token-local.md b/.trae/documents/github-token-local.md deleted file mode 100644 index f9ab69f6f6..0000000000 --- a/.trae/documents/github-token-local.md +++ /dev/null @@ -1,199 +0,0 @@ -# GitHub Token 使用说明（REST 创建 PR） - -- 作用：指导如何获取并在本地配置 `GITHUB_TOKEN`，用于通过 REST API 创建 PR（仓库 Job 在 `mode: auto` 时优先使用 REST）。 - -## 获取 Token（网页端） - -- 登录 GitHub → 右上角头像 → `Settings` -- 左侧导航底部 → `Developer settings` → `Personal access tokens` -- 建议使用 Fine-grained token（推荐）或 Classic token（简化）： - - Fine-grained（推荐）： - - 选择仓库：`VisActor/VChart`（或你需要的目标仓库） - - Permissions（最小权限）： - - 在 `Repository permissions` 列表中勾选： - - `Pull requests` → `Read and write` - - `Contents` → `Read` - - `Metadata` → `Read` - - 若看不到以上权限项，请参考下文“Fine-grained 权限项不可见的排查” - - 设置过期时间（建议 30–90 天）与备注（如：`trae-pr-rest`），点击生成并复制 Token - - Classic（简化）： - - 公有仓库：勾选 `public_repo` - - 私有仓库：勾选 `repo` - - 设置过期时间与备注，生成并复制 Token - -### Classic token 权限最小集合（结合组织仓库场景） - -- 公有仓库（个人仓库）：`public_repo` -- 公有仓库（组织仓库）：`public_repo` + `read:org` - - 若组织开启 SSO：必须在组织的 `Tokens` 页面为该 Token 完成 SSO 授权 - -#### 如何查看组织是否开启了 SSO - -- 组织主页右上角 → `Settings` → `Security` → 查看 `SAML Single Sign-On` 是否为 `Enabled` -- 在 `Organization` → `People` 页面，成员列表顶部若显示 `SAML SSO is enforced`/`Requires SSO` 提示，说明已启用 -- 在 `Settings` → `Developer settings` → `Personal access tokens` 中，已创建的 Token 条目旁若出现 `Enable SSO`/`Configure SSO`/`SSO authorization required` 提示，通常该组织启用了 SSO - -#### 如何为 Token 进行 SSO 授权 - -- 路径一（Token 页面）： - - 进入 `Settings` → `Developer settings` → `Personal access tokens` - - 找到需使用的 Token，点击 `Enable SSO` 或 `Configure SSO` - - 在弹出的授权面板中勾选目标组织（如：`VisActor`），点击 `Authorize` - - 详细步骤（Fine-grained，推荐）： - 1. 登录 GitHub → 右上角头像 → `Settings` - 2. 左侧 `Developer settings` → `Personal access tokens` → `Fine-grained tokens` - 3. 点击 `Generate new token` - 4. `Token name` 与 `Expiration`（建议 30–90 天） - 5. `Resource owner` 选择目标组织（如 `VisActor`） - 6. `Repository access` 选择 `Only select repositories`，勾选 `VChart` - 7. `Repository permissions` 勾选： - - `Pull requests` → `Read and write` - - `Contents` → `Read` - - `Metadata` → `Read` - 8. 点击生成并复制 `github_pat_...` - 9. 在生成完成页，点击 `Configure SSO`（若可见），选择组织并 `Authorize` - -> 注意：Fine‑grained token 通常不会显示 `Configure SSO` 按钮。这是正常行为，因为 Fine‑grained 已在创建阶段绑定了“资源归属（组织）”与“仓库范围”。如果后续 API 访问仍出现 403，请按下方步骤排查。 - -#### Fine‑grained 生成后未出现 “Configure SSO” 的处理（详细） - -- 验证令牌类型与绑定： - - 令牌前缀应为 `github_pat_...`（Fine‑grained），而非 `ghp_...`（Classic） - - 创建时 `Resource owner` 必须选择目标组织（如 `VisActor`） - - `Repository access` 必须选择 `Only select repositories` 并勾选 `VChart` - - `Repository permissions` 勾选：`Pull requests: Read and write`、`Contents: Read`、`Metadata: Read` -- 组织策略检查： - - 让组织管理员在 `Organization → Settings → Policies → Personal access tokens` 确认允许成员使用 Fine‑grained PAT 访问仓库；部分组织需 Owner 审批后方可生效 - - 确认你是组织成员并已完成 SAML SSO 登录（IdP 中被分配到 GitHub 应用） -- 接口级验证： - - 列表 PR 接口：`curl -s -o /dev/null -D - -H "Authorization: Bearer $GITHUB_TOKEN" "https://api.github.com/repos/VisActor/VChart/pulls?per_page=1" | head -n 1` 期望 `HTTP/2 200` - - 若返回 403 且提示禁止 Classic，说明当前使用的并非 Fine‑grained 或未生效；重新导出 `github_pat_...` - - 若返回 403 `Resource not accessible by personal access token`，通常为仓库未被选择或权限未勾选；重新检查 `Repository access/permissions` -- 无需额外 SSO 按钮： - - Fine‑grained 场景下，一般不需要在 Token 列表页额外执行 `Configure SSO`；只需确保组织成员身份、完成组织 SSO 登录，以及令牌绑定到组织与仓库并具备所需权限 - 10. 在终端设置环境变量：`export GITHUB_TOKEN="github_pat_..."` → `source ~/.zshrc` - 11. 验证： - - `curl -s -o /dev/null -D - -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/repos/VisActor/VChart/pulls?per_page=1 | head -n 1` 期待 `HTTP/2 200` - - 若为 `403` 且提示禁止 Classic，则说明未正确使用 Fine-grained 或未完成组织授权 -- 路径二（组织页面）： - - 进入目标组织主页 → `Settings` → `Security` → `SAML Single Sign-On` - - 在 `Authorized credentials`/`Tokens` 区域选择你的 Token，点击授权 - - 详细步骤（Classic，若组织允许）： - 1. 确认组织策略未禁止 Classic PAT；若禁止将出现 403 并提示使用 Fine-grained - 2. 在 `Personal access tokens (classic)` 中创建包含 `repo`、`read:org` 的 Token（`ghp_...`） - 3. 返回 Token 列表，若条目旁出现 `Enable SSO`/`Configure SSO`，点击并为组织授权 - 4. 若按钮不可见，使用以下方式触发授权链接： - - `curl -s -D - -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/orgs/<组织名> | grep -i "X-GitHub-SSO"` - - 从响应头复制 `url=https://github.com/orgs/<组织名>/sso?...`，在浏览器打开并完成授权 - 5. 验证接口同上；若依旧 403，说明组织策略禁止 Classic 或 SSO 未完成 -- CLI 辅助（可选）： - - 使用 `gh` 进行授权刷新：`gh auth refresh -h github.com -s read:org -s repo -s workflow` - - 浏览器会弹出 SSO 授权流程，完成后本地凭据具备组织访问权限 - - 详细步骤（CLI）： - 1. 本机安装并登录 GitHub CLI：`gh auth login` - 2. 触发组织权限刷新：`gh auth refresh -h github.com -s read:org -s repo -s workflow` - 3. 浏览器弹出 SSO 页，选择目标组织并确认授权；完成后返回终端成功提示 - 4. 若希望优先使用本机 CLI 凭据而非环境变量 Token，执行命令时加前缀：`env -u GITHUB_TOKEN` - 5. 示例：`env -u GITHUB_TOKEN gh pr create --base develop --head <branch> --title "<title>" --body-file ./.trae/output/pr.body.local.md` - -#### 看不到 “Enable SSO/Configure SSO” 按钮时的处理 - -- 先确认前置条件： - - 你是目标组织成员；组织已启用并强制 SAML SSO（见上文“如何查看组织是否开启了 SSO”） - - 该 Token 为 Classic token（前缀通常为 `ghp_...`），且作用域包含会访问组织资源的权限（如：`repo`、`read:org`）。仅 `public_repo` 往往不会显示授权入口 -- 使用接口触发授权链接： - - 运行：`curl -s -D - -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/orgs/<组织名> | head -n 20` - - 若组织启用 SSO，响应头会包含 `X-GitHub-SSO: required; url=https://github.com/orgs/<组织名>/sso?authorization_request=...` - - 复制该 `url` 在浏览器打开，按页面提示为当前 Token 完成 SSO 授权 -- 使用 CLI 触发授权： - - `gh auth refresh -h github.com -s read:org -s repo` 后跟随浏览器流程为组织授权 -- 常见原因与修复： - - 组织未启用或未强制 SSO → 按组织设置页确认；未启用时不会出现授权入口 - - 不是组织成员 → 先加入组织，或让管理员邀请 - - Token 作用域不足（仅 `public_repo`）→ 重新生成包含 `repo` 与 `read:org` 的 Classic token，并完成 SSO 授权 - - 已授权过该 Token → 授权入口不再显示，可在组织 SSO 的 `Authorized credentials/Tokens` 区查看 -- 私有仓库（个人/组织）：`repo` - - 若为组织仓库：额外需要 `read:org`，并完成 SSO 授权（如启用） -- 使用 GitHub CLI（gh）进行 PR/工作流相关操作：建议额外授予 `workflow` - -说明：在组织仓库中，仅有 `public_repo` 往往无法通过 REST 或 gh 创建 PR，常见报错为权限不足（Missing scopes: `repo`, `read:org`）。为确保最小可用，请按上面矩阵配置。 -- 若目标仓库在组织（Org）下且开启 SSO，请在 Org 的 `Tokens` 页面对该 Token 进行 SSO 授权，否则 REST 会返回 403。 - -> 组织仓库最小权限提示：公有仓库至少需要 `public_repo + read:org`；私有仓库需要 `repo + read:org`；若使用 gh 并涉及工作流，建议加上 `workflow`。 - -### Fine-grained 权限项不可见的排查 - -1. 选择资源归属：在创建 Fine-grained token 时，`Resource owner` 需选择目标组织（如 `VisActor`），而非个人账户；否则无法选择组织仓库与权限项 -2. 仓库访问范围：在 `Repository access` 选择 `Only select repositories` 并勾选 `VChart`；选择 `All repositories` 在部分组织策略下会隐藏或限制可用权限 -3. 组织策略限制：组织可能限制 Fine-grained token 的可用权限或需要 Owner 审批；若权限列表不出现或出现“需要审批”提示，请联系组织管理员在 `Organization → Settings → Policies → Personal access tokens` 开启并允许仓库访问 -4. 成员与 SSO：需为组织成员且完成 SSO 绑定；非成员或未完成 SSO 时，权限项可能不可用或后续调用被 403 拒绝 -5. 页面刷新与账号切换：确保使用目标 GitHub 账号登录；切换后刷新页面并重新选择组织与仓库 - -验证：创建完成后在终端执行 `curl -s -o /dev/null -D - -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/repos/VisActor/VChart/pulls?per_page=1 | head -n 1`，期待 `HTTP/2 200`。若为 403 且信息提示使用 Fine-grained，则说明当前 Token 未具备所需仓库权限或未完成组织授权。 - -## 在本地存储与加载（macOS） - -- 临时（当前终端会话）： - - `export GITHUB_TOKEN="<你的 Token>"` -- 永久（所有新终端）： - - 编辑 `~/.zshrc`，追加一行： - - `export GITHUB_TOKEN="<你的 Token>"` - - 使其生效： - - `source ~/.zshrc` -- 验证： - - `echo $GITHUB_TOKEN` 应有值（不应为空） - - `curl -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user` 返回 200/用户信息即正常 - -## 在本地存储与加载（Windows） - -- 临时（当前 PowerShell 会话）： - - `$env:GITHUB_TOKEN = "<你的 Token>"` -- 永久（用户环境变量）： - - `setx GITHUB_TOKEN "<你的 Token>"` - - 注意：`setx` 对当前会话不生效，需重启终端或重新登录 -- PowerShell 配置文件（可选）： - - 将以下命令加入 `$PROFILE`： - - `[Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "<你的 Token>", "User")` -- Git Bash（可选）： - - 在 `~/.bashrc` 中追加：`export GITHUB_TOKEN="<你的 Token>"` -- 验证： - - `echo $Env:GITHUB_TOKEN` 应有值 - - `curl -H "Authorization: Bearer $Env:GITHUB_TOKEN" https://api.github.com/user` 返回 200/用户信息即正常 - - 或使用 PowerShell： - - `Invoke-WebRequest -Headers @{ Authorization = "Bearer $Env:GITHUB_TOKEN" } https://api.github.com/user` - -## 在 Job 中的使用 - -- `./.trae/jobs/pr-create-from-body.md`： - - `mode: auto` 默认优先 REST（读取 `GITHUB_TOKEN`），其次 `gh` CLI - - 正文仅从文件读取：`bodyFile` 或默认 `./.trae/output/pr.body.local.md` - - 成功输出 `pr_url`；失败输出错误信息，不展示 compare URL - -## 注意事项 - -- 切勿将 Token 写入仓库文件、提交记录或日志；不要粘贴到聊天或截图 -- 仅授予最小权限：优先使用 Fine-grained 并限定到具体仓库与必要权限 -- 设置合理过期时间并定期轮换；过期后需重新生成并替换本地配置 -- 组织仓库需完成 SSO 授权；否则会出现 403（权限不足） -- 新开终端需确保 `~/.zshrc` 已被加载（`source ~/.zshrc`） - -## 常见问题排查 - -- 401 未授权：检查 `GITHUB_TOKEN` 是否为空、是否过期 -- 403 权限不足： - - 组织仓库缺少 `read:org` 或未完成 SSO 授权 - - Classic token 缺少必要作用域：公有仓库缺 `public_repo`；私有/组织仓库缺 `repo` - - Fine-grained token 权限不足：确认 `Pull requests: Read and write`、`Contents: Read`、`Metadata: Read` -- REST 错误：查看 Job 输出中的错误信息；必要时用 `curl` 测试接口是否返回正常用户/仓库信息 - -## 快速命令示例（macOS） - -- 设置环境变量（一次性）： - - `export GITHUB_TOKEN="ghp_xxx..."` -- 永久配置： - - `echo 'export GITHUB_TOKEN="ghp_xxx..."' >> ~/.zshrc && source ~/.zshrc` -- 验证： - - `curl -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user` diff --git a/.trae/documents/pr-body-generate.solo.md b/.trae/documents/pr-body-generate.solo.md deleted file mode 100644 index 6fb8322f1e..0000000000 --- a/.trae/documents/pr-body-generate.solo.md +++ /dev/null @@ -1,36 +0,0 @@ -# PR 正文生成 Job（Solo 使用说明） - -- 入口文件：`./.trae/jobs/pr-body-generate.md` -- 作用：依据仓库 PR 模版生成完整正文（`pr.body`），输出预览与本地文件，等待人工修订 - -## 参数 -- `lang`：`zh|en`，默认 `zh` -- `title`：可选；用于生成 `generated_title` -- `head`：可选；未提供时自动推导当前分支仅用于展示 -- `labels`：可选标签数组（用于正文元信息展示） -- `rushChangesDir`：默认 `common/changes` -- `localBodyFile`：是否写入本地正文文件（默认 `true`） -- `openEditor`：是否生成后自动在编辑器中打开正文文件（默认 `false`） -- `message`：可选；用于摘要与“背景&方案”的素材 - -## 前置 -- 推荐先完成本地变更与自测；该 Job 不进行提交或推送，仅生成正文。 - -## 使用（Solo） -- 在聊天中发起：“执行 PR Body Job（.trae/jobs/pr-body-generate.md）”，可传： - - `title: '[Auto] feature-legend'` - - （可选）`head: chore/trae-feature-legend-20251222-1030` - - （可选）`localBodyFile: true` - - （可选）`openEditor: true` - - （可选）`message: 'Add legend auto layout and tests'` - -## 输出 - -- `generated_title`：建议标题 -- `generated_body_preview`：完整 Markdown 代码块正文（便于复制） -- `generated_body_file`：默认 `./.trae/output/pr.body.local.md`（纯 Markdown，无外层三引号，不追加任何“Generated by ...”类提示） - -## 人工检查 -- 在编辑器中打开并修订 `./.trae/output/pr.body.local.md` -- 确保以下栏目完整：勾选项、关联链接、背景&方案、Changelog、自测、Summary、Walkthrough -- 修订完成后，执行“创建 PR” Job（`./.trae/jobs/pr-create-from-body.md`） diff --git a/.trae/documents/pr-create-from-body.solo.md b/.trae/documents/pr-create-from-body.solo.md deleted file mode 100644 index ce69cb6de8..0000000000 --- a/.trae/documents/pr-create-from-body.solo.md +++ /dev/null @@ -1,42 +0,0 @@ -# 使用正文创建 PR Job（Solo 使用说明） - -- 入口文件：`./.trae/jobs/pr-create-from-body.md` -- 作用：读取经过人工确认的正文（仅本地文件），创建 GitHub PR（支持 REST/gh） - -## 参数 -- `base`：默认 `develop` -- `head`：可选；未提供时自动推导当前分支 -- `title`：必填；PR 标题 -- `lang`：`zh|en`，默认 `zh` -- `labels`：可选标签数组 -- `draft`：是否草稿，默认 `false` -- `useGhCli`：是否使用 `gh` 创建，默认 `true` -- `mode`：`auto|rest|gh`（默认 `auto`，优先 REST） -- `localBodyFile`：是否从默认路径读取正文（默认 `true`） -- `bodyFile`：正文文件路径（优先使用） -- `commitBeforeCreate`：创建前是否自动提交未提交变更（默认 `false`） -- `commitMessage`：自动提交的 commit 消息（默认空） -- `commitAllowEmpty`：是否允许空提交（默认 `false`） -- `pushAfterCommit`：提交后是否自动推送当前分支（默认 `true`） -- `commitMessageStrategy`：提交信息生成策略（`auto|topic|manual`，默认 `auto`） - -## 前置（登录/令牌） -- 优先方案：提供 `GITHUB_TOKEN`（参见 `./.trae/documents/github-token-local.md`） -- 备选方案：本机已登录 GitHub CLI（`gh`）（参见 `./.trae/documents/github-gh-local.md`） - -## 使用（Solo） -- 在聊天中发起：“执行 PR Create Job（.trae/jobs/pr-create-from-body.md）”，参数示例： - - `title: 'feat(legend): add auto layout'` - - `base: develop` - - （可选）`head: chore/trae-feature-legend-20251222-1030` - - `mode: auto` - - `localBodyFile: true` 或 `bodyFile: './.trae/output/pr.body.local.md'` - - （可选）`labels: ['feature', 'legend']` - - （可选）`draft: false` - - （可选）`commitBeforeCreate: true`、`commitMessageStrategy: auto` - -## 输出 -- `pr_url`：创建的 PR 链接（`rest/gh`） - -## 人工检查 -- 提交前确认 `title`、`head` 与正文是否与预期一致 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 5ae79968b5..0000000000 --- a/.trae/jobs/auto-flow.md +++ /dev/null @@ -1,108 +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: browser - commitAllowEmpty: false - pushAfterCommit: true - commitMessageStrategy: auto - flowStep: 1 - autoNext: false -required_parameters: [] -outputs: - - autotest_report - - rush_change_entries - - commit_message - - pushed_branch - - pr_url - - next_step_hint -success_criteria: - - flow_step_completed ---- - -# Auto Flow Job（单步执行：单测 → 变更日志 → 提交 → PR） - -## 参数检查 - -- 分支参数 `head` 可选：若未提供，将通过 `git rev-parse --abbrev-ref HEAD` 推导当前分支 -- 建议提供 `topic` 以优化 PR 标题；未提供时将回退为当前分支名 -- 原则：不覆盖子 Job 默认参数；仅透传用户显式提供的参数 - -## 模式说明 - -- 单步模式：本 Job 每次仅执行一个步骤，由 `parameters.flowStep` 指定（取值：`1|2|3|4|5`）。步骤完成后进入人工暂停，返回 `next_step_hint` 提示你在对话中输入“执行下一步”。 -- 串行模式：当 `parameters.autoNext == true` 时，从当前 `flowStep` 开始按既有步骤顺序自动推进至“完成”，不再返回 `next_step_hint`，而是直接继续下一步。 - -## 步骤 - -1. 差异驱动单测（flowStep=1） - -- 执行 Job：`.trae/jobs/auto-test.md` -- 传参：`sinceBranch={{baseBranch}}` -- 接收输出：`autotest_report=.trae/output/autotest.report.local.md` -- 人工检查点：打开临时报告，确认新增/更新测试与覆盖率是否合理；当 `autoNext==true` 时，在报告生成后自动继续执行下一步。 - -2. 生成 Rush 变更日志（flowStep=2） - -- 执行 Job：`.trae/jobs/changelog-rush-smart.md` -- 传参：`sinceBranch={{baseBranch}}`、`message={{message}}`、`bumpType={{bumpType}}`、`notCommit={{notCommit}}` -- 说明：仅透传用户显式提供的参数，未提供时不传，使用子 Job 默认值 -- 接收输出：`rush_change_entries`、`computed_bump_type`、`final_message` -- 人工检查点：检查 `common/changes/**` 条目与摘要是否合理；当 `autoNext==true` 时，在条目生成后自动继续执行下一步。 - -3. 智能提交（flowStep=3） - -- 执行 Job：`.trae/jobs/commit-smart.md` -- 传参： - - `head={{head || (git rev-parse --abbrev-ref HEAD)}}` - - `message={{message}}`（为空时使用步骤 2 的 `final_message`） -- 说明：除 `head` 与 `message` 外，其余参数不强制设置；未提供时使用子 Job 默认值 -- 接收输出：`commit_message`、`pushed_branch` -- 人工检查点：确认提交信息与推送分支是否正确；当 `autoNext==true` 时，在提交与推送完成后自动继续执行下一步。 - -4. 生成 PR 正文（flowStep=4） - -- 执行 Job：`.trae/jobs/pr-body-generate.md` -- 传参： - - `title='[Auto] {{topic || head}}'` - - `head={{head}}` - - `lang={{lang}}` - - `labels={{labels}}` - - `rushChangesDir=common/changes` - - `localBodyFile=true` -- 说明：仅透传上述必要编排参数，不改变子 Job 默认；未提供的可选项不透传 -- 接收输出：`generated_title`、`generated_body_preview`、`generated_body_file=.trae/output/pr.body.local.md` -- 人工检查点：打开并审阅本地正文文件；当 `autoNext==true` 时，在正文生成后自动继续执行下一步。 - -5. 创建 PR（flowStep=5） - -- 执行 Job：`.trae/jobs/pr-create-from-body.md` -- 传参： - - `base={{baseBranch}}` - - `head={{head}}` - - `title='[Auto] {{topic || head}}'` - - `lang={{lang}}` - - `labels={{labels}}` - - `mode=auto` - - `localBodyFile=true` - - `bodyFile='./.trae/output/pr.body.local.md'` -- 说明：默认优先使用 `GITHUB_TOKEN`（REST），其次 `gh`；不展示 compare URL -- 接收输出：`pr_url` -- 人工检查点：确认 PR 链接与页面内容；当 `autoNext==true` 时，在创建成功后进入“完成”阶段。 - -6. 完成 - -- 标记 `flow_step_completed`，返回本步骤对应输出与 `next_step_hint`；当 `autoNext==true` 时，返回本次串行执行的综合输出并结束。 diff --git a/.trae/jobs/auto-test.md b/.trae/jobs/auto-test.md deleted file mode 100644 index 35e4dc174d..0000000000 --- a/.trae/jobs/auto-test.md +++ /dev/null @@ -1,142 +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: false - dryRun: false - preview: false - stopOnError: true - focusChangedOnly: false - snapshotStrategy: combined - tempReportPath: .trae/output/autotest.report.local.md - includeWorkingTree: true - 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. 差异采集（含未提交内容，当 `includeWorkingTree==true`） - -- 运行 `git fetch --all --prune` -- 收集已提交差异：`git diff --name-status --diff-filter=AMR {{sinceBranch}}...HEAD` -- 收集工作树差异：`git status --porcelain` -- 行级差异： - - 已提交：`git diff --unified=0 {{sinceBranch}}...HEAD <file>` - - 暂存未提交：`git diff --cached --unified=0 -- <file>` - - 未暂存：`git diff --unified=0 -- <file>` - -2. 影响分析 - -- 识别导出符号、类型签名与逻辑分支；在包内搜索已有 `__tests__` 及缺口 - -3. 测试生成 - -- 在 `__tests__` 下创建或更新 `.test.ts` 文件；为每个 `describe/it` 添加函数级注释（JSDoc，说明目的、前置/输入、断言点） -- 策略： - - 纯函数/工具：正常/边界/异常分支 - - 主题 JSON：`toMatchSnapshot()` + 关键字段断言（颜色、字体、间距） - - 转换器：代表性输入，断言输出结构与关键键值；必要时增量快照 -- Mock/Spy：固定时间与随机数；隔离外部依赖（网络/FS） -- 自动化区块命名规则： - - `describe('autogen:<pkg>/<module>:<export>:<hash>')` - - `it('autogen:<case>:<hash>')` - -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:<reason>')` 与 `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`）形成“提交概览” - - 从提交中解析 `#<id>`，调用 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/commit-smart.md b/.trae/jobs/commit-smart.md deleted file mode 100644 index ade43ab4bf..0000000000 --- a/.trae/jobs/commit-smart.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -job: commit-smart -intent: git-commit-push -version: v1 -domain: git -runner: trae-solo -parameters: - head: '' - commitAllowEmpty: false - pushAfterCommit: true - commitMessageStrategy: auto - message: '' -required_parameters: [] -outputs: - - commit_message - - pushed_branch -success_criteria: - - commit_created_or_skipped ---- - -# Commit Job（智能提交与推送） - -## 步骤 - -1. 推导分支 - -- 若 `parameters.head` 为空：`git rev-parse --abbrev-ref HEAD` - -2. 工作树检查 - -- `git status --porcelain`；若无变更且 `commitAllowEmpty==false`，返回 `commit_created_or_skipped`（跳过） - -3. 生成提交信息（策略 `auto`） - -- 类型：按路径前缀判定（含 `docs/` → `docs`；含 `__tests__/`/`*.test.*` → `test`；否则 `chore|fix|feat` 依据 `common/changes/**` 的 `type`，缺省 `chore`） -- 作用域：`packages/<name>` 或顶层目录 -- 主题：若 `message` 非空用其首行，否则： - - 有 `common/changes/**`：取最新条目的 `comment` - - 否则：`sync changes before PR (N files)` - -4. 执行提交与推送 - -- `git add --all` -- `git commit {{#commitAllowEmpty}}--allow-empty{{/commitAllowEmpty}} -m "<auto message>"` -- 若 `pushAfterCommit==true`：`git push -u origin {{head}}` - -5. 输出 - -- `commit_message` 与 `pushed_branch` - -## 人工检查点 - -- 返回提交信息与结果，待确认后继续 PR 步骤。 - 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-body-generate.md b/.trae/jobs/pr-body-generate.md deleted file mode 100644 index f0163affec..0000000000 --- a/.trae/jobs/pr-body-generate.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -job: pr-body-generate -intent: github-pr-body -version: v1 -domain: github -runner: trae-solo -parameters: - lang: zh - title: '' - head: '' - labels: [] - rushChangesDir: common/changes - localBodyFile: true - openEditor: false -required_parameters: [] -inputs: - autotestReport: .trae/output/autotest.report.local.md -outputs: - - generated_title - - generated_body_preview - - generated_body_file -success_criteria: - - body_generated ---- - -# 生成 PR 正文（支持人工修订） - -## 参数检查 - -- 可选参数：`title`、`head`、`labels` -- 模板语言：`lang`（`zh|en`，默认 `zh`） -- 输出文件：当 `localBodyFile == true`，写入 `./.trae/output/pr.body.local.md` - -## 步骤 - -1. 解析上下文与选择模板 - -- 推导 `head`：`git rev-parse --abbrev-ref HEAD` -- 模板选择：`lang == zh` → `.github/PULL_REQUEST_TEMPLATE/pr_cn.md`；否则 → `.github/PULL_REQUEST_TEMPLATE.md` - -2. 自动填充内容 - -- 勾选项：`branchTypeChecks`（未提供则生成默认占位，如“新功能”、“Workflow”） -- 关联：`issue_links`、`related_pr_links`、`bugserver_ids`（未提供保留占位） -- 背景与方案：基于 `message` 首行摘要与变更上下文生成 -- Changelog：解析 `rushChangesDir`（默认 `common/changes`），填充 `changelog_en` 与 `changelog_zh` -- 自测项：生成默认勾选列表；若存在 `autotestReport`，合并摘要至 Walkthrough -- Summary 与 Walkthrough：包含分支、模板来源、测试摘要与生成信息 - -3. 输出与保存 - -- 生成标题建议：`generated_title = [Auto] {{title || (topic || head)}}` -- 输出完整 `generated_body_preview`（Markdown 代码块，便于复制） -- 当 `localBodyFile == true`：写入 `./.trae/output/pr.body.local.md`（纯 Markdown，无外层三引号）并输出 `generated_body_file` -- 不在文件中追加任何生成标记或提示文本（如“Generated by ...”）；写入内容即为 PR body 原文 -- 当 `openEditor == true`：在编辑器中打开正文文件以便人工修订 - -4. 人工检查点 - -- 请人工审阅并完善 `pr.body`，然后执行“创建 PR” Job（`pr-create-from-body`） diff --git a/.trae/jobs/pr-create-from-body.md b/.trae/jobs/pr-create-from-body.md deleted file mode 100644 index 8d009a3882..0000000000 --- a/.trae/jobs/pr-create-from-body.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -job: pr-create-from-body -intent: github-pr -version: v1 -domain: github -runner: trae-solo -parameters: - base: develop - head: '' - title: '' - lang: zh - labels: [] - draft: false - useGhCli: true - mode: gh - localBodyFile: true - bodyFile: '' - commitBeforeCreate: false - commitMessage: '' - commitAllowEmpty: false - pushAfterCommit: true - commitMessageStrategy: auto -required_parameters: - - title -inputs: - autotestReport: .trae/output/autotest.report.local.md -outputs: - - pr_url -success_criteria: - - pr_created ---- - -# 使用本地/提供的正文创建 PR - -## 参数检查 - -- 必填参数：`title` -- 正文来源仅支持文件：`bodyFile` → 默认本地 `./.trae/output/pr.body.local.md`（当 `localBodyFile==true`） - -## 步骤 - -1. 前置与正文确定 - -- 推导 `head`：`git rev-parse --abbrev-ref HEAD` -- 确认正文来源：读取 `bodyFile` 或默认文件；若均不可用或正文为空，则失败并提示先执行正文生成 Job -- 使用正文时按“原样传递”，不进行包裹、注释或追加任何提示文本 - -2. 可选自动提交与推送 - -- 检查工作树：`git status --porcelain` -- 当 `commitBeforeCreate == true` 且存在未提交变更：按 `commitMessageStrategy` 生成提交信息，执行提交；当 `pushAfterCommit == true` 推送当前分支 - -3. 创建 PR（模式） - -- `auto`：优先 `gh`（本机已安装并登录）；其次 `GITHUB_TOKEN` 的 REST；否则失败并提示令牌或 CLI 不可用 -- `gh`：`gh pr create --base {{base}} --title "{{title}}" --head {{head}} {{#labels}}--label {{labels}}{{/labels}} {{#draft}}--draft{{/draft}}`；正文优先 `--body-file {{bodyFile}}`，若不支持则读取文件内容传 `--body "..."` -- `rest`：`POST /repos/{owner}/{repo}/pulls`，body 使用正文文本 - - -4. 输出 - -- 成功：输出 `pr_url` -- 失败：输出错误信息，不展示 compare URL From 4f7ddadfc7bfa832adec49e1a3441af2850f815d Mon Sep 17 00:00:00 2001 From: "lixuefei.1313" <lixuef1313@163.com> Date: Thu, 8 Jan 2026 16:15:24 +0800 Subject: [PATCH 09/10] chore: optimaz skill --- .trae/skills/auto-flow/SKILL.md | 42 ++++++++++ .trae/skills/auto-flow/docs/USAGE.md | 47 ++++++++++-- .trae/skills/auto-test/SKILL.md | 55 +++++++++++++- .trae/skills/auto-test/docs/USAGE.md | 20 ++++- .trae/skills/changelog-rush-smart/SKILL.md | 12 +++ .../skills/changelog-rush-smart/docs/USAGE.md | 10 +++ .trae/skills/commit-smart/SKILL.md | 17 +++++ .trae/skills/commit-smart/docs/USAGE.md | 15 ++++ .trae/skills/pr-body-generate/SKILL.md | 40 +++++++++- .trae/skills/pr-body-generate/docs/GH_CLI.md | 4 +- .trae/skills/pr-body-generate/docs/USAGE.md | 30 +++++++- .trae/skills/pr-create-from-body/SKILL.md | 76 ++++++++++++++++++- .../skills/pr-create-from-body/docs/GH_CLI.md | 4 +- .../skills/pr-create-from-body/docs/USAGE.md | 43 +++++++++++ 14 files changed, 397 insertions(+), 18 deletions(-) diff --git a/.trae/skills/auto-flow/SKILL.md b/.trae/skills/auto-flow/SKILL.md index 3c19275e2e..ff8661260f 100755 --- a/.trae/skills/auto-flow/SKILL.md +++ b/.trae/skills/auto-flow/SKILL.md @@ -44,6 +44,7 @@ description: 'Orchestrates a complete, standardized workflow for preparing a pul 1. **差异驱动单测** - **执行**: `auto-test` 技能。 - **目的**: 为代码变更生成并运行单元测试。 + - **报告输出**: 默认总是将报告写入 `./.trae/output/autotest.report.local.md`（即 `auto-test` 的 `tempReportPath`），即便本次没有生成新的测试用例也会包含“无新增自动化测试 (No new tests generated)”等说明。 - **检查点**: Agent 会返回测试报告路径。**你需要检查报告中的测试覆盖率和结果，确认无误后指示 Agent 继续。** 2. **生成 Rush 变更日志** @@ -59,13 +60,54 @@ description: 'Orchestrates a complete, standardized workflow for preparing a pul 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 <your-branch> \ + -t "<your-title>" \ + -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": "<your-title>", + "head": "<your-branch>", + "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`）。上述命令仅作为认证异常时的应急方案。 + ## 何时使用 / 边界 - **使用时机**: diff --git a/.trae/skills/auto-flow/docs/USAGE.md b/.trae/skills/auto-flow/docs/USAGE.md index c4da10d50f..6fdeb0e7bf 100755 --- a/.trae/skills/auto-flow/docs/USAGE.md +++ b/.trae/skills/auto-flow/docs/USAGE.md @@ -11,8 +11,8 @@ 本技能是一个带有“门禁”的流水线，每一步完成后都会暂停，等待你的确认： -1. **自动测试**: 技能首先为你的代码变更生成并运行测试。 - * **你需要**: 检查测试报告，确认覆盖率和测试结果符合预期。 +1. **自动测试**: 技能首先为你的代码变更生成并运行测试，并将结果写入 `./.trae/output/autotest.report.local.md`（即使没有新增测试也会包含“无新增自动化测试 (No new tests generated)” 说明）。 + * **你需要**: 打开该报告，检查覆盖率和测试结果是否符合预期。 2. **生成变更日志**: 接着，它会为你的提交创建 `changelog` 文件。 * **你需要**: 检查 `common/changes/` 目录下生成的文件内容是否准确。 @@ -20,11 +20,11 @@ 3. **智能提交**: 然后，所有变更会被打包成一个规范的 Git 提交并推送。 * **你需要**: 确认自动生成的提交信息是正确的。 -4. **生成 PR 正文**: 技能会自动填充 PR 模板。 +4. **生成 PR 正文**: 技能会自动填充 PR 模板，从 `./.trae/output/autotest.report.local.md` 和 `common/changes` 中汇总信息，并将正文写入 `./.trae/output/pr.body.local.md`。 * **你需要**: 审阅生成的 PR 正文，可选择在本地修改 `.md` 文件。 5. **创建 PR**: 最后，使用准备好的正文创建 PR。 - * **你需要**: 访问返回的 PR 链接，做最终确认。 + * **你需要**: 访问返回的 PR 链接，做最终确认；如失败，优先检查 `gh auth status`、`git remote -v` 与 `GITHUB_TOKEN` 配置是否正确。 ## 示例对话 @@ -48,6 +48,43 @@ ## 注意事项 -- **凭证**: 确保 `GITHUB_TOKEN` 或 `gh` CLI 已正确配置，否则最后一步会失败。 +- **凭证**: 确保 `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 <your-branch> \ + -t "<your-title>" \ + -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": "<your-title>", + "head": "<your-branch>", + "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 index b8bb2996b8..49a7d2532a 100755 --- a/.trae/skills/auto-test/SKILL.md +++ b/.trae/skills/auto-test/SKILL.md @@ -34,7 +34,7 @@ description: 'Automates unit testing for incremental code changes in the VChart - `snapshots`: 生成或更新的快照文件。 - `coverage_report`: 覆盖率报告摘要。 - `manual_nodes`: 提示需要人工介入的测试点。 - - `temp_markdown_report`: 本地生成的 Markdown 格式临时报告。 + - `temp_markdown_report`: 本地生成的 Markdown 格式临时报告，其路径通常与 `tempReportPath` 一致（默认 `./.trae/output/autotest.report.local.md`）。**无论本次是否实际生成了新的测试用例，此报告都会写入，用于解释执行结果。** - **成功标准**: - `tests_generated_for_changed_exports`: 已为所有变更的导出项生成测试。 - `compile_without_errors`: 生成的测试代码编译无误。 @@ -52,7 +52,58 @@ description: 'Automates unit testing for incremental code changes in the VChart - 根据 `project` 参数，运行 `rush run test` 和 `rush run test-cov` 命令。 - 收集测试结果和覆盖率数据。 5. **报告生成**: - - 将所有变更、测试生成情况、运行结果、覆盖率变化及潜在风险点汇总成一份报告，并保存到 `{{tempReportPath}}`。 + - 将所有变更、测试生成情况、运行结果、覆盖率变化及潜在风险点汇总成一份报告，并保存到 `{{tempReportPath}}`（默认 `./.trae/output/autotest.report.local.md`）。 + - 报告结构至少包含：变更摘要、新增/更新测试列表、运行结果、覆盖率摘要（整体与关键文件）、覆盖率变化，以及风险与改进建议等板块。 + - **当本次执行没有生成任何新的自动化测试时，报告中必须包含一个明确的“无新增自动化测试 (No new tests generated)”小节，说明原因（例如仅文档变更、仅样式调整或变更被过滤等）以及当前测试覆盖情况。** + +## 命令示例（本地等价操作） + +如果需要在不依赖技能的情况下手动完成一次最小化的测试与覆盖率检查，可以在 VChart 仓库根目录执行： + +```bash +# 1. 运行单元测试 +rush run -p <project> -s test + +# 2. 运行覆盖率 +rush run -p <project> -s test-cov + +# 3. 将结果整理成临时报告（与 Skill 输出路径保持一致） +mkdir -p ./.trae/output +cat > ./.trae/output/autotest.report.local.md << 'EOF' +# Auto Test Report + +## Summary +- Project: <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`，观察报告中覆盖率摘要与“风险与建议”板块是否有所改善。 ## 何时使用 / 边界 diff --git a/.trae/skills/auto-test/docs/USAGE.md b/.trae/skills/auto-test/docs/USAGE.md index cb2d7bc0e3..41dafb53eb 100755 --- a/.trae/skills/auto-test/docs/USAGE.md +++ b/.trae/skills/auto-test/docs/USAGE.md @@ -31,6 +31,24 @@ ## 注意事项 -- 此技能专注于单元测试，不能完全替代集成测试或端到端测试。 +- **此技能专注于单元测试，不能完全替代集成测试或端到端测试。** - 自动生成的测试可能需要人工干预，特别是在涉及复杂模拟(Mock)或特定业务逻辑的场景中。 - 执行前请确保 `rush` 依赖已正确安装。 +- 每次执行都会在 `tempReportPath`（默认 `./.trae/output/autotest.report.local.md`）写入一份临时报告；**即使没有生成新的测试用例，也会包含“无新增自动化测试 (No new tests generated)”说明小节，解释原因与执行结果。** + +## 命令示例（本地运行） + +```bash +# 在 VChart 仓库根目录，针对某个 Rush 项目运行测试与覆盖率 +rush run -p <project> -s test +rush run -p <project> -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 index a5a7a5a4a6..f195fed15f 100755 --- a/.trae/skills/changelog-rush-smart/SKILL.md +++ b/.trae/skills/changelog-rush-smart/SKILL.md @@ -46,6 +46,17 @@ description: 'Generates standardized changelog entries for a Rush-based monorepo - Agent 会执行 `rush change` 命令，使用上一步确定的 `bumpType` 和消息，为每个受影响的包生成对应的变更文件。 5. **（可选）提交变更**: 如果 `notCommit` 未设置为 `true`，Agent 会将新生成的变更文件添加到 Git 暂存区并创建一个提交。 +## 命令示例（本地等价操作） + +在 VChart 仓库根目录，你可以用 `rush change --bulk` 近似完成此技能的核心步骤： + +```bash +# 基于 develop...HEAD 的变更，为所有受影响的包批量生成变更条目 +rush change --bulk +``` + +在运行前，建议先检查 `common/changes/**` 中是否已经存在覆盖当前提交集的条目；若已有合适的记录，可以跳过本次执行，避免重复生成。 + ## 何时使用 / 边界 - **使用时机**: @@ -54,3 +65,4 @@ description: 'Generates standardized changelog entries for a Rush-based monorepo - **边界**: - 此技能只负责生成 `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 index 17b724bf85..6cd3fa15bb 100755 --- a/.trae/skills/changelog-rush-smart/docs/USAGE.md +++ b/.trae/skills/changelog-rush-smart/docs/USAGE.md @@ -28,8 +28,18 @@ - `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 index bd65815114..f632223fbe 100755 --- a/.trae/skills/commit-smart/SKILL.md +++ b/.trae/skills/commit-smart/SKILL.md @@ -48,6 +48,23 @@ description: 'Creates a well-formed, intelligent Git commit for all pending chan - 然后使用生成的提交信息执行 `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` 清理暂存区。 + ## 何时使用 / 边界 - **使用时机**: diff --git a/.trae/skills/commit-smart/docs/USAGE.md b/.trae/skills/commit-smart/docs/USAGE.md index d55a1bc8e8..1f53c0ed95 100755 --- a/.trae/skills/commit-smart/docs/USAGE.md +++ b/.trae/skills/commit-smart/docs/USAGE.md @@ -31,3 +31,18 @@ - **危险区域**: 此技能会使用 `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/pr-body-generate/SKILL.md b/.trae/skills/pr-body-generate/SKILL.md index 6dacbc3b91..1a40402ccd 100755 --- a/.trae/skills/pr-body-generate/SKILL.md +++ b/.trae/skills/pr-body-generate/SKILL.md @@ -37,16 +37,50 @@ description: 'Generates a well-formed Pull Request body for the VChart project b ## 执行步骤 -1. **选择模板**: 根据 `lang` 参数，Agent 会选择对应的 PR 模板文件（例如 `.github/PULL_REQUEST_TEMPLATE/pr_cn.md`）。 +1. **选择模板**: 根据 `lang` 参数，Agent 会选择对应的 PR 模板文件（例如中文：`.github/PULL_REQUEST_TEMPLATE/pr_cn.md`，英文：`.github/PULL_REQUEST_TEMPLATE.md`）。 2. **填充内容**: Agent 会自动执行以下填充操作： - **Changelog**: 解析 `{{rushChangesDir}}` 目录下的变更条目，并填充到正文的 Changelog 部分。 - - **自测项**: 如果 `autotestReport` 文件存在，会将其中的测试摘要信息填充到自测/走查部分。 + - **自测项**: 如果 `autotestReport` 文件存在（默认路径为 `./.trae/output/autotest.report.local.md`），会将其中的测试摘要信息（包括“无新增自动化测试”说明）填充到自测/走查部分；若文件不存在，则在正文中保留空白或占位说明，提示尚未提供自动化测试报告。 - **背景与方案**: 基于 `message` 参数（如果提供）和提交历史，生成简要的背景与方案描述。 + - **缺失数据的占位处理**: 当未找到 `{{rushChangesDir}}` 下的 changelog 或未提供 `autotestReport` 时，正文仍会生成对应的小节，并使用“暂无 changelog”或“尚未提供自动化测试报告”等最小占位文案，确保结构完整而不会报错。 - **元信息**: 填充分支、标签等信息。 3. **输出与保存**: - Agent 会生成一个建议的 PR 标题。 - 将完整的 PR 正文以 Markdown 预览形式展示。 - - 如果 `localBodyFile` 为 `true`，会将纯净的 Markdown 正文内容保存到 `.trae/output/pr.body.local.md` 文件中，以便后续步骤使用或人工修改。 + - 当 `localBodyFile` 为 `true`（默认行为）时，**无论是否存在 changelog 或自动化测试报告，都会**将纯净的 Markdown 正文内容保存到 `.trae/output/pr.body.local.md` 文件中，作为后续创建 PR 的唯一来源。缺失的信息会以清晰的占位或“暂无数据”文案体现，而不是让文件缺失。 +4. **验证 (Validation)**: + - 生成完成后，请打开 `.trae/output/pr.body.local.md`，检查至少以下几点： + - 标题、背景与方案是否准确概括本次变更。 + - 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` 文件。 ## 何时使用 / 边界 diff --git a/.trae/skills/pr-body-generate/docs/GH_CLI.md b/.trae/skills/pr-body-generate/docs/GH_CLI.md index b231442426..e2bd4c6c93 100755 --- a/.trae/skills/pr-body-generate/docs/GH_CLI.md +++ b/.trae/skills/pr-body-generate/docs/GH_CLI.md @@ -1,6 +1,6 @@ # GitHub CLI (gh) 核心指南 -GitHub CLI (`gh`) 是 `pr-create-from-body` 技能的备选执行器。当 `GITHUB_TOKEN` 未设置时，技能会尝试使用 `gh` 来创建 Pull Request。 +GitHub CLI (`gh`) 是与 GitHub 交互（尤其是创建 Pull Request）的首选执行器。在 `mode: auto` 下，`pr-create-from-body` 等技能会优先使用 `gh` 来创建 PR；只有在 `gh` 不可用时才回退到使用 `GITHUB_TOKEN` 的 REST API。 ## 安装与登录 @@ -22,7 +22,7 @@ GitHub CLI (`gh`) 是 `pr-create-from-body` 技能的备选执行器。当 `GITH ## 使用 -`pr-create-from-body` 技能在 `mode: auto` 时，会优先检查 `GITHUB_TOKEN`。如果未找到，则会调用本机的 `gh` 命令来创建 PR。 +`pr-create-from-body` 技能在 `mode: auto` 时，会优先使用本机已登录的 `gh` 命令来创建 PR；只有在 `gh` 未安装或未登录时，才会回退到使用 `GITHUB_TOKEN` 的 REST API。 **示例命令 (由技能在内部执行):** ```bash diff --git a/.trae/skills/pr-body-generate/docs/USAGE.md b/.trae/skills/pr-body-generate/docs/USAGE.md index 5a8a7c4094..05b1c236e6 100755 --- a/.trae/skills/pr-body-generate/docs/USAGE.md +++ b/.trae/skills/pr-body-generate/docs/USAGE.md @@ -32,5 +32,31 @@ ## 注意事项 - **仅生成不创建**: 此技能只负责生成 PR 正文的 `.md` 文件，**不会** 在 GitHub 上创建 PR。创建操作由 `pr-create-from-body` 技能完成。 -- **依赖前序产出**: 生成的正文内容的完整性依赖于之前步骤的产出，例如 `common/changes` 目录下的 `changelog` 文件和 `auto-test` 生成的测试报告。 -- **人工审查**: 自动生成的内容是草稿，强烈建议在执行下一步前，打开本地生成的 `.md` 文件进行审查和必要的修改。 +- **依赖前序产出**: 正文内容的丰富程度依赖于之前步骤的产出，例如 `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 index 067639a402..11ecaf1b0b 100755 --- a/.trae/skills/pr-create-from-body/SKILL.md +++ b/.trae/skills/pr-create-from-body/SKILL.md @@ -45,10 +45,84 @@ description: 'Creates a GitHub Pull Request for the VChart project using a local 3. **创建 PR**: - **gh 模式**: Agent 会使用 `gh pr create` 命令，并通过 `--body-file` 参数直接传入正文文件。 - **rest 模式**: Agent 会读取 `bodyFile` 的内容，然后通过调用 GitHub REST API (`POST /repos/{owner}/{repo}/pulls`) 来创建 PR。 - - **auto 模式**: 自动选择可用的最佳方式。 + - **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 <your-branch> \ + -t "<your-title>" \ + -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": "<your-title>", + "head": "<your-branch>", + "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 状态码与提示内容），并根据提示进一步排查或联系仓库维护者。 + ## 何时使用 / 边界 - **使用时机**: diff --git a/.trae/skills/pr-create-from-body/docs/GH_CLI.md b/.trae/skills/pr-create-from-body/docs/GH_CLI.md index b231442426..e2bd4c6c93 100755 --- a/.trae/skills/pr-create-from-body/docs/GH_CLI.md +++ b/.trae/skills/pr-create-from-body/docs/GH_CLI.md @@ -1,6 +1,6 @@ # GitHub CLI (gh) 核心指南 -GitHub CLI (`gh`) 是 `pr-create-from-body` 技能的备选执行器。当 `GITHUB_TOKEN` 未设置时，技能会尝试使用 `gh` 来创建 Pull Request。 +GitHub CLI (`gh`) 是与 GitHub 交互（尤其是创建 Pull Request）的首选执行器。在 `mode: auto` 下，`pr-create-from-body` 等技能会优先使用 `gh` 来创建 PR；只有在 `gh` 不可用时才回退到使用 `GITHUB_TOKEN` 的 REST API。 ## 安装与登录 @@ -22,7 +22,7 @@ GitHub CLI (`gh`) 是 `pr-create-from-body` 技能的备选执行器。当 `GITH ## 使用 -`pr-create-from-body` 技能在 `mode: auto` 时，会优先检查 `GITHUB_TOKEN`。如果未找到，则会调用本机的 `gh` 命令来创建 PR。 +`pr-create-from-body` 技能在 `mode: auto` 时，会优先使用本机已登录的 `gh` 命令来创建 PR；只有在 `gh` 未安装或未登录时，才会回退到使用 `GITHUB_TOKEN` 的 REST API。 **示例命令 (由技能在内部执行):** ```bash diff --git a/.trae/skills/pr-create-from-body/docs/USAGE.md b/.trae/skills/pr-create-from-body/docs/USAGE.md index 6acb1c330e..160c3eddae 100755 --- a/.trae/skills/pr-create-from-body/docs/USAGE.md +++ b/.trae/skills/pr-create-from-body/docs/USAGE.md @@ -35,3 +35,46 @@ - **凭证**: 执行前，必须确保 `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 <your-branch> \ + -t "<your-title>" \ + -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": "<your-title>", + "head": "<your-branch>", + "base": "develop", + "body": "从 .trae/output/pr.body.local.md 复制正文内容到此处" + }' +``` + +> 提示：在技能中使用 `mode: auto` 时，会优先走“路径一”（`gh` 创建 PR），当 `gh` 不可用时自动回退到“路径二”（REST + `GITHUB_TOKEN`）。 From 65b7261684213f621c2caa710e3d2f16877a7009 Mon Sep 17 00:00:00 2001 From: "lixuefei.1313" <lixuef1313@163.com> Date: Thu, 8 Jan 2026 16:35:03 +0800 Subject: [PATCH 10/10] feat: optimiz pr body skill --- .trae/skills/pr-body-generate/SKILL.md | 94 +++++++++++++++++++------- 1 file changed, 68 insertions(+), 26 deletions(-) diff --git a/.trae/skills/pr-body-generate/SKILL.md b/.trae/skills/pr-body-generate/SKILL.md index 1a40402ccd..ff44a9a4a4 100755 --- a/.trae/skills/pr-body-generate/SKILL.md +++ b/.trae/skills/pr-body-generate/SKILL.md @@ -16,44 +16,86 @@ description: 'Generates a well-formed Pull Request body for the VChart project b ## 输入参数 -| 参数 | 类型 | 是否必填 | 默认值 | 描述 | -| ---------------- | ------- | -------- | ----------------------------- | -------------------------------------------------------------- | -| `lang` | string | 否 | `zh` | PR 模板的语言 (`zh` 或 `en`)。 | -| `title` | string | 否 | (空) | 用于生成建议 PR 标题的素材。 | -| `head` | string | 否 | (空) | PR 的源分支名。如果为空，将自动推导当前分支。 | -| `labels` | array | 否 | `[]` | 附加到 PR 的标签，会体现在正文的元信息中。 | -| `rushChangesDir` | string | 否 | `common/changes` | Rush 变更日志条目所在的目录。 | -| `localBodyFile` | boolean | 否 | `true` | 是否将生成的正文保存到本地文件。 | +| 参数 | 类型 | 是否必填 | 默认值 | 描述 | +| ---------------- | ------- | -------- | --------------------------------------- | -------------------------------------------------------------- | +| `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`）。 + - `generated_title`: 推荐的 PR 标题。 + - `generated_body_preview`: 生成的完整 PR 正文的 Markdown 预览。 + - `generated_body_file`: 本地保存 PR 正文的文件路径（默认为 `.trae/output/pr.body.local.md`）。 - **成功标准**: - - `body_generated`: PR 正文已成功生成并按需保存到本地文件。 + - `body_generated`: PR 正文已成功生成并按需保存到本地文件。 ## 执行步骤 -1. **选择模板**: 根据 `lang` 参数，Agent 会选择对应的 PR 模板文件（例如中文：`.github/PULL_REQUEST_TEMPLATE/pr_cn.md`，英文：`.github/PULL_REQUEST_TEMPLATE.md`）。 -2. **填充内容**: Agent 会自动执行以下填充操作： +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”或“尚未提供自动化测试报告”等最小占位文案，确保结构完整而不会报错。 - - **元信息**: 填充分支、标签等信息。 -3. **输出与保存**: + - **元信息**: 如需提供分支、标签等信息，放入“背景&解决方案”或相应模板章节的正文中，不新增“提交与后续”等额外章节。 +4. **输出与保存**: - Agent 会生成一个建议的 PR 标题。 - 将完整的 PR 正文以 Markdown 预览形式展示。 - - 当 `localBodyFile` 为 `true`（默认行为）时，**无论是否存在 changelog 或自动化测试报告，都会**将纯净的 Markdown 正文内容保存到 `.trae/output/pr.body.local.md` 文件中，作为后续创建 PR 的唯一来源。缺失的信息会以清晰的占位或“暂无数据”文案体现，而不是让文件缺失。 -4. **验证 (Validation)**: + - 当 `localBodyFile` 为 `true`（默认行为）时，将模板原文复制并在既有章节内补充内容，保存到 `.trae/output/pr.body.local.md`。输出不包含任何模板外的额外段落（例如“提交与后续”）。 +5. **验证 (Validation)**: - 生成完成后，请打开 `.trae/output/pr.body.local.md`，检查至少以下几点： - - 标题、背景与方案是否准确概括本次变更。 - - Changelog 小节是否与 `common/changes` 中的内容一致；如没有 changelog，正文中是否有明确的“暂无 changelog”说明。 - - 自测/走查小节是否正确引用了 auto-test 报告；当没有新增测试时，应能看到“无新增自动化测试 (No new tests generated)” 等说明。 - - Summary / Walkthrough 等收尾小节是否存在，整体结构是否完整。 + - 标题、背景与方案是否准确概括本次变更。 + - “这个分支是.../This is a ...”是否已正确勾选，且与分支名/提交类型一致。 + - Changelog 小节是否与 `common/changes` 中的内容一致；如没有 changelog，正文中是否有明确的“暂无 changelog”说明。 + - 自测/走查小节是否正确引用了 auto-test 报告；当没有新增测试时，应能看到“无新增自动化测试 (No new tests generated)” 等说明。 + - Summary / Walkthrough 等收尾小节是否存在，整体结构是否完整。 - 如发现缺失或需要补充的信息，可直接编辑该 Markdown 文件后再执行 `pr-create-from-body`。 ## 命令示例（本地等价操作） @@ -85,8 +127,8 @@ ${EDITOR:-vim} ./.trae/output/pr.body.local.md ## 何时使用 / 边界 - **使用时机**: - - 在提交代码并生成变更日志之后，创建 PR 之前，用于准备 PR 的描述内容。 - - 作为 `auto-flow` 工作流的一部分，在 `commit-smart` 步骤之后自动调用。 + - 在提交代码并生成变更日志之后，创建 PR 之前，用于准备 PR 的描述内容。 + - 作为 `auto-flow` 工作流的一部分，在 `commit-smart` 步骤之后自动调用。 - **边界**: - - 此技能只生成 PR 正文，不会创建 PR。创建 PR 是 `pr-create-from-body` 技能的职责。 - - 生成内容的丰富程度依赖于前序步骤的产出（如 `changelog` 和 `auto-test` 报告）。 + - 此技能只生成 PR 正文，不会创建 PR。创建 PR 是 `pr-create-from-body` 技能的职责。 + - 生成内容的丰富程度依赖于前序步骤的产出（如 `changelog` 和 `auto-test` 报告）。