diff --git a/.auto-flow/autotest_report.md b/.auto-flow/autotest_report.md new file mode 100644 index 0000000000..f121631602 --- /dev/null +++ b/.auto-flow/autotest_report.md @@ -0,0 +1,33 @@ +# Auto Test 报告 + +- 基线分支: develop +- 头部分支: 当前分支自动推导 +- 命令: rush test +- 结果: 通过（含警告） +- 用时: 约 31.64s + +## 摘要 +- @visactor/vchart: 37 套件、110 用例全部通过（有 Node MaxListeners 警告） +- @visactor/vchart-schema: 2 套件、3 用例全部通过 +- @visactor/vutils-extension: 1 套件、1 用例全部通过 + +## 关键信息摘录 + +``` +Test Suites: 37 passed, 37 total +Tests: 110 passed, 110 total +Snapshots: 0 total +Time: 18.84 s + +Test Suites: 2 passed, 2 total +Tests: 3 passed, 3 total +Snapshots: 0 total +Time: 6.178 s + +Test Suites: 1 passed, 1 total +Tests: 1 passed, 1 total +Snapshots: 0 total +Time: 3.493 s +``` + +生成时间: 2026-01-05 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 015eb762bf..5ae79968b5 100644 --- a/.trae/jobs/auto-flow.md +++ b/.trae/jobs/auto-flow.md @@ -15,81 +15,94 @@ parameters: bumpType: auto notCommit: true head: '' - mode: auto - commitBeforeFlow: true + mode: browser commitAllowEmpty: false pushAfterCommit: true commitMessageStrategy: auto - enforceCommit: true - commitRetry: 1 + flowStep: 1 + autoNext: false required_parameters: [] outputs: - autotest_report - rush_change_entries + - commit_message + - pushed_branch - pr_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 标题；未提供时将回退为当前分支名 +- 原则：不覆盖子 Job 默认参数；仅透传用户显式提供的参数 -## 步骤 - -1. 分支预检查 +## 模式说明 -- 运行 `git rev-parse --abbrev-ref HEAD` 获取当前分支作为 `head` -- 确认当前分支不是 `main`/`develop`，且工作树状态符合提交规范 -- 人工检查点：如不在开发分支，请先自行创建并切换到正确分支 +- 单步模式：本 Job 每次仅执行一个步骤，由 `parameters.flowStep` 指定（取值：`1|2|3|4|5`）。步骤完成后进入人工暂停，返回 `next_step_hint` 提示你在对话中输入“执行下一步”。 +- 串行模式：当 `parameters.autoNext == true` 时，从当前 `flowStep` 开始按既有步骤顺序自动推进至“完成”，不再返回 `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 "<auto_message>"` - - 若 `pushAfterCommit==true`：`git push -u origin {{head}}` - - 提交后校验（当 `enforceCommit==true`）： - - 运行 `git status --porcelain`，若非空则视为失败；进行最多 `commitRetry` 次重试（`git add --all && git commit -m '<auto_message>'`），仍失败则中止流程并提示处理 -- 若 `commitBeforeFlow==false` 且存在未提交变更：直接失败并提示先完成提交 +## 步骤 -2. 运行差异驱动单测 +1. 差异驱动单测（flowStep=1） - 执行 Job：`.trae/jobs/auto-test.md` -- 传参：`sinceBranch={{baseBranch}}`（其余沿用默认） +- 传参：`sinceBranch={{baseBranch}}` - 接收输出：`autotest_report=.trae/output/autotest.report.local.md` -- 人工检查点：打开临时报告，确认新增/更新测试与覆盖率 +- 人工检查点：打开临时报告，确认新增/更新测试与覆盖率是否合理；当 `autoNext==true` 时，在报告生成后自动继续执行下一步。 -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/**` 条目与摘要 +- 说明：仅透传用户显式提供的参数，未提供时不传，使用子 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` 时，在正文生成后自动继续执行下一步。 -4. 创建 PR +5. 创建 PR（flowStep=5） -- 执行 Job：`.trae/jobs/pr-create.md` +- 执行 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}}`（auto 优先 gh → token → 浏览器 URL） - - `commitBeforeCreate=false`（已在 1.1 阶段完成自动提交） + - `mode=auto` + - `localBodyFile=true` + - `bodyFile='./.trae/output/pr.body.local.md'` +- 说明：默认优先使用 `GITHUB_TOKEN`（REST），其次 `gh`；不展示 compare URL - 接收输出：`pr_url` -- 人工检查点：最终确认并提交 +- 人工检查点：确认 PR 链接与页面内容；当 `autoNext==true` 时，在创建成功后进入“完成”阶段。 -5. 完成 +6. 完成 -- 标记 `flow_completed`，返回 `autotest_report`、`rush_change_entries` 与 `pr_url` +- 标记 `flow_step_completed`，返回本步骤对应输出与 `next_step_hint`；当 `autoNext==true` 时，返回本次串行执行的综合输出并结束。 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 <file>` 获取行级差异 +- 收集已提交差异：`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. 影响分析 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/<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/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..8d009a3882 --- /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: 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 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，使用浏览器登录后手动创建 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` 指向的文件存在且内容正确。 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 diff --git a/common/changes/@visactor/vchart/fix-heatmap-label_2025-12-26-08-38.json b/common/changes/@visactor/vchart/fix-heatmap-label_2025-12-26-08-38.json new file mode 100644 index 0000000000..13ba46254f --- /dev/null +++ b/common/changes/@visactor/vchart/fix-heatmap-label_2025-12-26-08-38.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "comment": "fix: fix default lineWidth for heatmap label\n\n", + "type": "none", + "packageName": "@visactor/vchart" + } + ], + "packageName": "@visactor/vchart", + "email": "dingling112@gmail.com" +} \ No newline at end of file diff --git a/common/changes/@visactor/vchart/temp-test-skill_2026-01-05-08-22.json b/common/changes/@visactor/vchart/temp-test-skill_2026-01-05-08-22.json new file mode 100644 index 0000000000..d48f8a7b68 --- /dev/null +++ b/common/changes/@visactor/vchart/temp-test-skill_2026-01-05-08-22.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "comment": "chore(auto-flow): 自动生成变更", + "type": "none", + "packageName": "@visactor/vchart" + } + ], + "packageName": "@visactor/vchart", + "email": "lixuef1313@163.com" +} \ No newline at end of file diff --git a/packages/vchart/src/series/heatmap/heatmap.ts b/packages/vchart/src/series/heatmap/heatmap.ts index 3ad2f3d783..7467526fb9 100644 --- a/packages/vchart/src/series/heatmap/heatmap.ts +++ b/packages/vchart/src/series/heatmap/heatmap.ts @@ -73,7 +73,7 @@ export class HeatmapSeries<T extends IHeatmapSeriesSpec = IHeatmapSeriesSpec> ex return; } this.setMarkStyle(textMark, { - fill: this.getColorAttribute(), + fill: this._spec.cell?.style?.fill ?? this.getColorAttribute(), text: (datum: Datum) => { return datum[this.getMeasureField()[0]]; } diff --git a/packages/vchart/src/theme/builtin/common/series/heatmap.ts b/packages/vchart/src/theme/builtin/common/series/heatmap.ts index 6697536abf..460e324640 100644 --- a/packages/vchart/src/theme/builtin/common/series/heatmap.ts +++ b/packages/vchart/src/theme/builtin/common/series/heatmap.ts @@ -9,5 +9,10 @@ export const heatmap: IHeatmapSeriesTheme = { }, cellBackground: { visible: false + }, + label: { + style: { + lineWidth: 2 + } } };