diff --git a/.cursor/commands/speckit.changelog.md b/.cursor/commands/speckit.changelog.md new file mode 100755 index 0000000000..528928dae0 --- /dev/null +++ b/.cursor/commands/speckit.changelog.md @@ -0,0 +1,35 @@ +--- +description: 'Generate Rush changes entries for VChart monorepo based on commits since base branch; infer bump type; aggregate messages.' +handoffs: + - label: 'Commit Changes' + agent: 'speckit.commit' + prompt: 'Create a clean Conventional Commits commit and push if desired' + send: true +--- + +## User Input + +```text +$ARGUMENTS +``` + +## Outline + +1. **Read Inputs**: + - `sinceBranch` (default: `develop`): The base branch for collecting commits. + - `bumpType` (default: `auto`): Explicit bump type (`patch`, `minor`, `major`). If `auto`, infer from commit messages. + - `message` (optional): A custom message to use for the changelog entry. + +2. **Gather Context**: + - Collect commits and file changes between `sinceBranch` and `HEAD`. + - If `bumpType` is `auto`, analyze commit messages (`feat`, `fix`, `BREAKING CHANGE`) to determine the appropriate version bump. + +3. **Execute Rush Change**: + - The agent will run `rush change`, providing the determined bump type and an aggregated message. + - The message is constructed from the `message` input or summarized from commit history (and enriched with issue titles if `githubToken` is present). + - This action generates changelog files under `common/changes/`. + +4. **Report Outputs**: + - List the paths of the generated changelog files. + - Confirm the final message used. + - Verify that the generated message complies with Conventional Commits (`commitlint`) standards. diff --git a/.cursor/commands/speckit.commit.md b/.cursor/commands/speckit.commit.md new file mode 100755 index 0000000000..8cef4d8460 --- /dev/null +++ b/.cursor/commands/speckit.commit.md @@ -0,0 +1,35 @@ +--- +description: "Create an intelligent commit (Conventional Commits) bundling workspace changes; optionally push to origin." +handoffs: + - label: "Generate PR Body" + agent: "speckit.prgenerate" + prompt: "Generate a PR body from templates and artifacts" + send: true +--- + +## User Input + +```text +$ARGUMENTS +``` + +## Outline + +1. **Pre-flight Checks**: + * Verify the current branch and check if the working tree is dirty. + * If `commitAllowEmpty=false` (default) and there are no changes, the process will be skipped. + +2. **Generate Commit Message**: + * **Priority 1**: Use the `message` argument if provided. + * **Priority 2**: If no message is provided, extract the subject from the latest entry in `common/changes/`. + * **Priority 3**: If neither is available, generate a generic subject like `chore: sync changes (N files)`. + * The commit type and scope are inferred from file paths and changelog entries. + +3. **Execute Git Actions**: + * The agent will run `git add --all` to stage all changes. + * It will then execute `git commit` with the generated message. + * If `pushAfterCommit=true` (default), it will push the commit to the remote origin. + +4. **Report Outputs**: + * `commit_message`: The full commit message used. + * `pushed_branch`: The name of the branch that was pushed (if applicable). diff --git a/.cursor/commands/speckit.implement.md b/.cursor/commands/speckit.implement.md index 41da7b931c..e28c32d44e 100644 --- a/.cursor/commands/speckit.implement.md +++ b/.cursor/commands/speckit.implement.md @@ -1,5 +1,10 @@ --- description: Execute the implementation plan by processing and executing all tasks defined in tasks.md +handoffs: + - label: Generate Changelog + agent: speckit.changelog + prompt: Generate Rush changes entries from current work + send: true --- ## User Input diff --git a/.cursor/commands/speckit.prcreate.md b/.cursor/commands/speckit.prcreate.md new file mode 100755 index 0000000000..aa367a6194 --- /dev/null +++ b/.cursor/commands/speckit.prcreate.md @@ -0,0 +1,36 @@ +--- +description: 'Create a GitHub Pull Request using local body file via gh CLI (browser auth).' +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Outline + +1. **Check Inputs**: + - **Title**: The Pull Request title (Required). + - **Head Branch**: Source branch (defaults to current branch: `git branch --show-current`). + - **Base Branch**: Target branch (defaults to `develop`). + - **Body File**: Path to PR body content (defaults to `.trae/output/pr.body.local.md`). + +2. **Verify Environment**: + - Check if `gh` CLI is installed: `gh --version`. + - Check authentication status: `gh auth status`. + - **Note**: Explicitly ignore `GITHUB_TOKEN` env var to force browser-based auth if needed. + +3. **Execute PR Creation**: + - Construct and run the `gh pr create` command: + ```bash + gh pr create --title "" --body-file "<BODY_FILE>" --base "<BASE>" --head "<HEAD>" --web + ``` + - Note: The `--web` flag is optional but recommended if the user wants to review in browser before final submission, otherwise remove it to create directly. Based on user preference or default to direct creation if not specified. + +4. **Report Output**: + - Capture the command output. + - Display the URL of the newly created Pull Request. + - Verify the URL is valid. diff --git a/.cursor/commands/speckit.prgenerate.md b/.cursor/commands/speckit.prgenerate.md new file mode 100755 index 0000000000..eeb10ab13a --- /dev/null +++ b/.cursor/commands/speckit.prgenerate.md @@ -0,0 +1,51 @@ +--- +description: 'Generate a well-formed PR body using repo template and local artifacts (changelog, auto-test report). Save to .trae/output/pr.body.local.md by default.' +handoffs: + - label: 'Create Pull Request' + agent: 'speckit.prcreate' + prompt: 'Create the GitHub Pull Request using the generated body' + send: true +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Outline + +1. **Determine Template and Context**: + - **Select Template**: + - Check user input for language preference (English or Chinese). + - If Chinese, use template at: `.github/PULL_REQUEST_TEMPLATE/pr_cn.md` + - If English or unspecified, use template at: `.github/PULL_REQUEST_TEMPLATE.md` + - **Infer Context**: + - Get current branch name using `git branch --show-current`. + - Get recent commit messages using `git log -5 --pretty=format:"%s"`. + - Infer PR type (feat, fix, docs, etc.) to verify the checklist items. + +2. **Populate Body Sections**: + - **Changelog**: + - Check `common/changes` directory for change files. + - If files exist, parse them to summarize changes for the `Changelog` section. + - If no files, mark as "N/A" or leave empty. + - **Self-test Summary**: + - Read report from `.trae/output/autotest.report.local.md`. + - If file exists, append summary to the body. + - If missing, add a placeholder indicating no automated test report. + - **Background/Solution**: + - Synthesize a description from commit messages and user input. + - Fill in the "Background and solution" section of the template. + +3. **Generate and Save**: + - **Generate Title**: Create a concise PR title following Conventional Commits (e.g., `feat: add new chart type`). + - **Preview**: Display the generated title and body content to the user for review. + - **Save**: Write the final content to `.trae/output/pr.body.local.md`. + - **Verify**: Check if the file `.trae/output/pr.body.local.md` was created successfully. + +4. **Validation Checklist**: + - Confirm the output file exists. + - Ask user to review the generated body in `.trae/output/pr.body.local.md`. diff --git a/.trae/skills/auto-flow/SKILL.md b/.trae/skills/auto-flow/SKILL.md deleted file mode 100755 index f0b6f71a05..0000000000 --- a/.trae/skills/auto-flow/SKILL.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -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 的有效工作区中执行（已安装 Node、pnpm 与 Rush）。 -- **凭证**: 需要本机已安装并登录的 GitHub CLI (`gh`)，用于最终创建 PR。你可以通过 `gh auth status` 验证登录状态。 -- **仓库状态**: 确保当前目录映射到 GitHub 上的 `VisActor/VChart` 仓库（`git remote -v` 与 `gh repo view` 均正常）。 -- **分支推送**: 开发分支需已推送到远程，否则无法创建 PR（`git push -u origin <branch>`）。 - -## 输入参数 - -本技能的流程是固定的，不通过参数选择执行步骤。它会按顺序执行所有五个步骤。 - -| 参数 | 类型 | 是否必填 | 默认值 | 描述 | -| ------------- | ------- | -------- | ------------ | -------------------------------------------------------------------- | -| `baseBranch` | string | 否 | `develop` | 整个流程所围绕的基准分支，用于差异计算和 PR 目标。 | -| `topic` | string | 否 | (空) | 用于优化 PR 标题的可选主题。 | -| `message` | string | 否 | (空) | 用于 `changelog` 和 `commit` 的自定义消息。 | -| `bumpType` | string | 否 | `auto` | Rush 变更日志的版本升级类型。 | -| `head` | string | 否 | (空) | 当前开发分支。如果为空，将自动推导。 | -| `labels` | array | 否 | `[changelog, test]` | 附加到最终 PR 的标签。 | - -## 输出与成功标准 - -- **主要输出**: - - `autotest_report`: 单元测试报告文件路径。 - - `rush_change_entries`: 生成的 Rush 变更条目列表。 - - `commit_message`: 创建的提交信息。 - - `pr_url`: 最终创建的 Pull Request 链接。 -- **成功标准**: - - `flow_step_completed`: 流程中的每一步或整个流程已成功完成。 - -## 执行步骤 - -本技能按固定顺序依次执行以下子技能，并在每一步之间设置人工检查点： - -1. **差异驱动单测** - - **执行**: `auto-test` 技能。 - - **目的**: 为代码变更生成并运行单元测试。 - - **报告输出**: 默认总是将报告写入 `./.trae/output/autotest.report.local.md`（即 `auto-test` 的 `tempReportPath`），即便本次没有生成新的测试用例也会包含“无新增自动化测试 (No new tests generated)”等说明。 - - **检查点**: Agent 会返回测试报告路径。**你需要检查报告中的测试覆盖率和结果，确认无误后指示 Agent 继续。** - -2. **生成 Rush 变更日志** - - **执行**: `changelog-rush-smart` 技能。 - - **目的**: 根据提交历史创建 `common/changes/**` 下的变更条目。 - - **检查点**: Agent 会提示已生成变更条目。**你需要检查这些文件的内容是否准确反映了你的变更，然后指示 Agent 继续。** - -3. **智能提交** - - **执行**: `commit-smart` 技能。 - - **目的**: 将所有变更（代码、测试、changelog 文件）创建一个符合规范的 Git 提交并推送到远程。 - - **检查点**: Agent 会返回生成的提交信息和推送结果。**你需要确认提交信息是正确的，然后指示 Agent 继续。** - -4. **生成 PR 正文** - - **执行**: `pr-body-generate` 技能。 - - **目的**: 自动填充 PR 模板，生成包含所有上下文信息的 PR 正文。 - - **输入输出约定**: 默认会从 `./.trae/output/autotest.report.local.md` 读取 auto-test 生成的报告摘要，并将生成的正文写入 `./.trae/output/pr.body.local.md`。即使缺少 changelog 或自动化测试报告，也会生成一个结构完整的最小正文，并在相应小节中标注“暂无 changelog”或“尚未提供自动化测试报告”等说明。 - - **检查点**: Agent 会返回生成的 PR 正文预览和本地文件路径。**你应审阅正文内容，确保其完整和准确（可在此步之后手动修改文件），然后指示 Agent 继续。** - -5. **创建 PR** - - **执行**: `pr-create-from-body` 技能。 - - **目的**: 使用上一步生成的正文文件，在 GitHub 上创建 Pull Request。 - - **执行方式**: 技能使用已登录的 `gh` CLI 创建 PR（gh-only）。确保分支已推送、标题与正文文件路径正确。 - - **检查点**: Agent 会返回最终的 PR 链接。**你需要访问链接确认 PR 是否按预期创建。** - -## 故障排查（分步） - -- **Step 1: auto-test** - - 常见问题：依赖未安装、测试命令失败、覆盖率采集异常 - - 处理建议：在仓库根目录执行 `rush install`，针对项目执行 `rush run -p <project> -s test` 与 `test-cov`；检查 `./.trae/output/autotest.report.local.md` - -- **Step 2: changelog-rush-smart** - - 常见问题：`rush change` 未生成条目、重复条目 - - 处理建议：确认 `develop...HEAD` 的变更存在；已有覆盖当前提交的条目时无需重复生成 - -- **Step 3: commit-smart** - - 常见问题：误提交 `.trae/skills` 等环境目录、远程不存在 - - 处理建议：执行前 `git status` 检查；必要时 `git restore --staged .trae/skills`；确保远程分支存在并可推送 - -- **Step 4: pr-body-generate** - - 常见问题：模板选择错误、正文未包含必要信息 - - 处理建议：确认语言模板（中文/英文）；检查 `Changelog` 与 `自测` 小节；必要时手动编辑 `.trae/output/pr.body.local.md` - -- **Step 5: pr-create-from-body** - - 常见问题：`gh` 未登录、分支未推送、SSO 授权缺失 - - 处理建议：`gh auth status`、`git remote -v`、`gh repo view`；确保 `git push -u origin <branch>`；参考 `docs/GH_CLI.md` 的详细安装与使用指南 - -## Quick Actions（PR 创建失败时的人工兜底） - -```bash -# 1) 登录 gh（如尚未登录） -gh auth login - -# 2) 使用本地正文文件创建 PR（仓库根目录） -gh pr create \ - -B develop \ - -H <your-branch> \ - -t "<your-title>" \ - -F ./.trae/output/pr.body.local.md \ - --label changelog \ - --label test -``` - -## 何时使用 / 边界 - -- **使用时机**: - - 当你完成一个功能或修复，准备发起一个完整的、高质量的 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 deleted file mode 100755 index 8d2811783e..0000000000 --- a/.trae/skills/auto-flow/docs/USAGE.md +++ /dev/null @@ -1,72 +0,0 @@ -# 使用说明：auto-flow - -本技能将创建 Pull Request 的所有准备工作（测试、变更日志、提交、生成正文、创建 PR）串联成一个标准化的五步流程。 - -## 何时使用 - -- **发布准备**: 当你完成一个功能或修复，准备发起一个完整的、高质量的 Pull Request 时，使用此技能可以确保所有检查项都已完成。 -- **标准化贡献**: 团队成员可以使用此流程来确保所有贡献都遵循相同的质量标准。 - -## 流程与人工检查点 - -本技能是一个带有“门禁”的流水线，每一步完成后都会暂停，等待你的确认： - -1. **自动测试**: 技能首先为你的代码变更生成并运行测试，并将结果写入 `./.trae/output/autotest.report.local.md`（即使没有新增测试也会包含“无新增自动化测试 (No new tests generated)” 说明）。 - * **你需要**: 打开该报告，检查覆盖率和测试结果是否符合预期。 - -2. **生成变更日志**: 接着，它会为你的提交创建 `changelog` 文件。 - * **你需要**: 检查 `common/changes/` 目录下生成的文件内容是否准确。 - -3. **智能提交**: 然后，所有变更会被打包成一个规范的 Git 提交并推送。 - * **你需要**: 确认自动生成的提交信息是正确的。 - -4. **生成 PR 正文**: 技能会自动填充 PR 模板，从 `./.trae/output/autotest.report.local.md` 和 `common/changes` 中汇总信息，并将正文写入 `./.trae/output/pr.body.local.md`。 - * **你需要**: 审阅生成的 PR 正文，可选择在本地修改 `.md` 文件。 - -5. **创建 PR**: 最后，使用准备好的正文创建 PR。 - * **你需要**: 访问返回的 PR 链接，做最终确认；如失败，优先检查 `gh auth status`、`git remote -v` 与分支是否已推送。 - -## 示例对话 - -> **你**: “启动 `auto-flow` 流程，为我的新功能做发布准备。” -> -> **Agent**: (执行第一步) “第一步：测试已完成，报告位于 `.../autotest.report.local.md`。请检查后告诉我是否继续。” -> -> **你**: (检查后) “继续。” -> -> **Agent**: (执行第二步) “第二步：变更日志已生成。请检查 `common/changes/` 目录。确认无误后，请告诉我是否继续。” -> -> **你**: “继续。” -> -> *... (Agent 会继续执行后续步骤，并在每一步后请求确认)* - -## 关键参数 - -- `baseBranch`: PR 的目标分支，默认为 `develop`。 -- `topic`: 用于生成 PR 标题，建议提供。 -- `message`: 用于 `changelog` 和 `commit` 的自定义消息。 - -## 注意事项 - -- **凭证**: 确保 `gh` CLI 已安装并通过 `gh auth status` 登录成功（本流程的 PR 创建为 gh-only，不再回退 REST）。 -- **顺序固定**: 本技能的五个步骤是固定的，不能跳过或重排。 -- **失败中断**: 流程中任何一步失败都会导致整个流程中断。 - -## 故障排查与 Quick Actions（PR 创建失败时） - -当流程执行到第 5 步“创建 PR”时，如因权限或认证问题失败，可在终端直接使用 `gh pr create` 完成创建： - -### 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 -``` -> 提示：如仍失败，检查 `gh auth status`、`gh repo view`、`git remote -v` 与 `git push -u origin <branch>` 是否正常；详见 [GH_CLI.md](file:///Users/bytedance/Documents/GitHub/VChart/.trae/skills/pr-create-from-body/docs/GH_CLI.md) 的常见问题与处理。 diff --git a/.trae/skills/auto-test/SKILL.md b/.trae/skills/auto-test/SKILL.md deleted file mode 100755 index 49a7d2532a..0000000000 --- a/.trae/skills/auto-test/SKILL.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -name: auto-test -description: 'Automates unit testing for incremental code changes in the VChart project. Use this skill to automatically generate and run tests for your modifications against a base branch (default: develop). It identifies changes, creates/updates Jest test cases and snapshots, and provides a coverage report. This skill requires a functional Rush and Git environment.' ---- - -# 差异驱动的单元测试 (auto-test) - -## 概述 - -本技能用于对 `VChart` 项目中指定基准分支与当前 `HEAD` 之间的代码差异，自动生成、更新和执行单元测试。它能够处理已提交和未提交的变更，并生成一份详细的测试报告。 - -## 前置条件 - -- **环境**: 必须在配置了 Rush 和 Git 的有效工作区中执行。 -- **GitHub 凭证 (可选)**: 某些高级功能可能需要有效的 `GITHUB_TOKEN` 或已登录的 `gh` CLI。 - -## 输入参数 - -| 参数 | 类型 | 默认值 | 描述 | -| -------------------- | ------- | --------------------------------- | ---------------------------------------------------------- | -| `sinceBranch` | string | `develop` | 用于差异计算的基准分支。 | -| `project` | string | `auto` | 要测试的 Rush 项目，`auto` 表示自动识别变更所属的项目。 | -| `mode` | string | `full` | 测试模式。 | -| `noSnapshot` | boolean | `false` | 是否跳过快照测试。 | -| `reportFormat` | string | `md` | 生成报告的格式 (`md` 或 `json`)。 | -| `tempReportPath` | string | `.trae/output/autotest.report.local.md` | 临时报告的输出路径。 | -| `replaceAutogen` | boolean | `false` | 是否允许替换已有的 `autogen:` 测试块。 | -| `includeWorkingTree` | boolean | `true` | 是否包含工作树（未提交的）的变更。 | - -## 输出与成功标准 - -- **主要输出**: - - `test_files`: 生成或更新的测试文件列表。 - - `snapshots`: 生成或更新的快照文件。 - - `coverage_report`: 覆盖率报告摘要。 - - `manual_nodes`: 提示需要人工介入的测试点。 - - `temp_markdown_report`: 本地生成的 Markdown 格式临时报告，其路径通常与 `tempReportPath` 一致（默认 `./.trae/output/autotest.report.local.md`）。**无论本次是否实际生成了新的测试用例，此报告都会写入，用于解释执行结果。** -- **成功标准**: - - `tests_generated_for_changed_exports`: 已为所有变更的导出项生成测试。 - - `compile_without_errors`: 生成的测试代码编译无误。 - - `coverage_increase_or_maintained`: 代码覆盖率持平或有所提升。 - -## 执行步骤 - -1. **差异采集**: Agent 会使用 `git diff` 和 `git status` 命令，识别出从 `{{sinceBranch}}` 到当前 `HEAD` 的所有已提交和未提交的文件与代码行级变更。 -2. **影响分析**: 分析变更内容，识别出哪些导出函数、类型或逻辑分支受到了影响，并检查 `__tests__` 目录下是否存在对应的测试缺口。 -3. **测试生成**: - - 在受影响模块的 `__tests__` 目录下创建或更新测试文件 (`*.test.ts`)。 - - 为纯函数、UI 组件、工具函数等生成不同策略的测试用例，并附带说明性注释。 - - 对不确定的 Mock 或断言，会生成带 `test.skip` 和 `MANUAL_REQUIRED` 标记的占位符。 -4. **执行与覆盖率分析**: - - 根据 `project` 参数，运行 `rush run test` 和 `rush run test-cov` 命令。 - - 收集测试结果和覆盖率数据。 -5. **报告生成**: - - 将所有变更、测试生成情况、运行结果、覆盖率变化及潜在风险点汇总成一份报告，并保存到 `{{tempReportPath}}`（默认 `./.trae/output/autotest.report.local.md`）。 - - 报告结构至少包含：变更摘要、新增/更新测试列表、运行结果、覆盖率摘要（整体与关键文件）、覆盖率变化，以及风险与改进建议等板块。 - - **当本次执行没有生成任何新的自动化测试时，报告中必须包含一个明确的“无新增自动化测试 (No new tests generated)”小节，说明原因（例如仅文档变更、仅样式调整或变更被过滤等）以及当前测试覆盖情况。** - -## 命令示例（本地等价操作） - -如果需要在不依赖技能的情况下手动完成一次最小化的测试与覆盖率检查，可以在 VChart 仓库根目录执行： - -```bash -# 1. 运行单元测试 -rush run -p <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`，观察报告中覆盖率摘要与“风险与建议”板块是否有所改善。 - -## 何时使用 / 边界 - -- **使用时机**: - - 在完成一部分代码开发后，需要快速验证变更的正确性并补充单元测试时。 - - 在准备提交代码前，确保所有改动都被测试覆盖。 - - 作为持续集成流程的一部分，用于自动化回归测试。 -- **边界**: - - 此技能专注于单元测试，无法替代集成测试或端到端测试。 - - 对于复杂的业务逻辑或需要精细 Mock 的场景，生成的测试用例可能需要人工调整。 diff --git a/.trae/skills/auto-test/docs/USAGE.md b/.trae/skills/auto-test/docs/USAGE.md deleted file mode 100755 index 1dbada67f1..0000000000 --- a/.trae/skills/auto-test/docs/USAGE.md +++ /dev/null @@ -1,61 +0,0 @@ -# 使用说明：auto-test - -本技能根据代码增量自动生成单元测试，确保变更得到充分验证。 - -## 何时使用 - -- **编码后**: 开发了新功能或修复了缺陷后，运行此技能可快速为你的变更生成测试用例。 -- **提交前**: 在 `git commit` 之前，使用此技能确保所有改动都已被测试覆盖，满足合入标准。 -- **CI/CD**: 可作为自动化流水线的一环，对每次提交进行回归测试。 - -## 示例对话 - -**场景一：对所有变更运行测试** - -> **你**: “帮我运行 `auto-test`，检查下我最近的改动。” -> -> **Agent**: (执行技能) “测试已完成，报告位于 `./.trae/output/autotest.report.local.md`。新增测试 `X` 个，覆盖率提升 `Y%`。请查阅报告确认。” - -**场景二：仅测试特定包** - -> **你**: “为 `@visactor/vchart` 项目执行 `auto-test`。” -> -> **Agent**: (将测试范围限定在指定包内执行) “已完成对 `@visactor/vchart` 的测试。报告已生成。” - -## 关键参数 - -- `sinceBranch`: 定义进行比较的基准分支，默认为 `develop`。 -- `project`: 指定要测试的 Rush 项目。`auto` 会自动识别变更影响的包；你也可以明确指定，如 `'@visactor/vchart'`。 -- `reportFormat`: 输出报告的格式，支持 `md` (默认) 和 `json`。 -- `tempReportPath`: 测试报告的本地输出路径，默认为 `./.trae/output/autotest.report.local.md`。 - -## 注意事项 - -- **此技能专注于单元测试，不能完全替代集成测试或端到端测试。** -- 自动生成的测试可能需要人工干预，特别是在涉及复杂模拟(Mock)或特定业务逻辑的场景中。 -- 执行前请确保 `rush` 依赖已正确安装。 -- 每次执行都会在 `tempReportPath`（默认 `./.trae/output/autotest.report.local.md`）写入一份临时报告；**即使没有生成新的测试用例，也会包含“无新增自动化测试 (No new tests generated)”说明小节，解释原因与执行结果。** - -## 故障排查 - -- **依赖缺失**: 在根目录执行 `rush install`；必要时运行 `pnpm -v` 确认 pnpm 可用 -- **测试执行失败**: 针对项目执行 `rush run -p <project> -s test`；查看错误日志并在 `__tests__` 中补充/修复用例 -- **覆盖率报告为空**: 确认测试命令包含覆盖率脚本（如 `test-cov`）；手动执行 `rush run -p <project> -s test-cov` -- **报告未写出**: 检查输出目录存在 `mkdir -p ./.trae/output`；确认 `tempReportPath` 配置正确 - -## 命令示例（本地运行） - -```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 deleted file mode 100755 index f195fed15f..0000000000 --- a/.trae/skills/changelog-rush-smart/SKILL.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -name: changelog-rush-smart -description: 'Generates standardized changelog entries for a Rush-based monorepo like VChart. Use this skill to create changelog files based on Git commits since a base branch (default: develop). It intelligently determines the version bump type, aggregates commit messages, and can enrich them with linked GitHub issue titles if a GITHUB_TOKEN is provided.' ---- - -# 智能 Rush 变更日志 (changelog-rush-smart) - -## 概述 - -本技能依据自 `develop` 分支以来的 Git 提交历史，为 `VChart` 项目自动生成符合 Rush 规范的变更日志条目。它能智能地推断版本变更类型（major/minor/patch），并聚合提交信息来创建消息内容。 - -## 前置条件 - -- **Rush 环境**: 项目依赖 `rush` 已正确安装。 -- **GitHub Token (可选)**: 若想自动拉取并聚合关联 Issue 的标题，需在环境中配置 `GITHUB_TOKEN`。 - -## 输入参数 - -| 参数 | 类型 | 是否必填 | 默认值 | 描述 | -| ------------- | ------ | -------- | --------- | ---------------------------------------------------------- | -| `sinceBranch` | string | 否 | `develop` | 用于差异计算的基准分支。 | -| `bumpType` | string | 否 | `auto` | 版本变更类型 (`auto`, `major`, `minor`, `patch`)。`auto` 会根据提交信息自动推断。 | -| `message` | string | 否 | (空) | 手动指定的变更摘要。如果为空，将根据提交记录自动生成。 | -| `notCommit` | boolean| 否 | `true` | 是否在生成变更条目后自动执行 `git commit`。 | -| `githubToken` | string | 否 | (空) | 用于访问 GitHub API 以获取 Issue 标题的个人访问令牌。 | - -## 输出与成功标准 - -- **主要输出**: - - `rush_change_entries`: 生成的 Rush 变更条目文件路径列表（位于 `common/changes/**`）。 - - `computed_bump_type`: 最终采纳的版本变更类型。 - - `final_message`: 用于生成变更条目的最终消息文本。 -- **成功标准**: - - `rush_changes_generated`: 变更条目已成功生成。 - - `commitlint_passed`: 生成的消息摘要符合 `commitlint` 规范。 - -## 执行步骤 - -1. **采集差异与提交**: Agent 会收集从 `{{sinceBranch}}` 到 `HEAD` 的文件变更和提交记录。 -2. **判定版本变更类型 (`bumpType`)**: - - Agent 会分析提交信息中的关键字（如 `BREAKING CHANGE`, `feat`, `fix` 等）来自动判断版本变更级别。 - - 如果用户显式提供了 `bumpType` 参数，则优先使用用户指定的值。 -3. **构建变更消息**: - - 如果 `message` 参数为空，Agent 会智能地从提交历史中提取关键信息，并（在有 `githubToken` 的情况下）拉取关联 Issue 的标题，共同构成一条内容丰富的变更消息。 -4. **生成 Rush 变更条目**: - - Agent 会执行 `rush change` 命令，使用上一步确定的 `bumpType` 和消息，为每个受影响的包生成对应的变更文件。 -5. **（可选）提交变更**: 如果 `notCommit` 未设置为 `true`，Agent 会将新生成的变更文件添加到 Git 暂存区并创建一个提交。 - -## 命令示例（本地等价操作） - -在 VChart 仓库根目录，你可以用 `rush change --bulk` 近似完成此技能的核心步骤： - -```bash -# 基于 develop...HEAD 的变更，为所有受影响的包批量生成变更条目 -rush change --bulk -``` - -在运行前，建议先检查 `common/changes/**` 中是否已经存在覆盖当前提交集的条目；若已有合适的记录，可以跳过本次执行，避免重复生成。 - -## 何时使用 / 边界 - -- **使用时机**: - - 在完成一个或多个功能的开发、即将发起 Pull Request 之前，用于生成标准的 `changelog` 条目。 - - 当你需要遵循 `VChart` 项目的版本发布流程，为你的变更创建记录时。 -- **边界**: - - 此技能只负责生成 `common/changes/**` 下的变更文件，它本身不执行版本发布 (`rush publish`)。 - - 自动生成的消息质量依赖于良好、规范的 Git 提交历史。 - - 如果 `common/changes/**` 中已经存在覆盖当前提交集的条目，可以只复核既有文件，无需强行生成新的变更记录，以避免重复。 diff --git a/.trae/skills/changelog-rush-smart/docs/USAGE.md b/.trae/skills/changelog-rush-smart/docs/USAGE.md deleted file mode 100755 index ccd1c46a14..0000000000 --- a/.trae/skills/changelog-rush-smart/docs/USAGE.md +++ /dev/null @@ -1,52 +0,0 @@ -# 使用说明：changelog-rush-smart - -本技能用于根据 Git 提交记录为 Rush monorepo 项目智能生成变更日志。 - -## 何时使用 - -- **PR 前**: 在发起 Pull Request 之前，使用此技能为你的变更生成标准的 `changelog` 条目。 -- **发布准备**: 作为 `auto-flow` 编排的一部分，在 `auto-test` 之后自动执行，确保版本历史的完整性。 - -## 示例对话 - -**场景一: 自动生成** - -> **你**: “请为我最近的提交生成 changelog。” -> -> **Agent**: (执行技能) “变更日志已生成。`bumpType` 被自动判断为 `patch`。文件已创建于 `common/changes/` 目录。” - -**场景二: 手动指定类型和消息** - -> **你**: “执行 `changelog-rush-smart`，`bumpType` 设为 `minor`，并使用消息 '新增图表系列，支持交互式图例'。” -> -> **Agent**: (使用指定参数执行) “好的，已使用 `minor` 类型和你的自定义消息生成了变更日志。” - -## 关键参数 - -- `sinceBranch`: 定义比较的基准分支，默认为 `develop`。 -- `bumpType`: 版本变更类型，可以是 `auto`, `major`, `minor`, `patch`。`auto` 会基于提交信息自动推断。 -- `message`: 手动指定的变更摘要。如果留空，将根据提交记录自动生成。 -- `githubToken`: （可选）提供 GitHub 个人访问令牌，以便自动拉取并聚合关联 Issue 的标题。 - -## 命令示例 - -```bash -# 在 VChart 仓库根目录，基于 develop...HEAD 的变更批量生成 changelog 条目 -rush change --bulk -``` - -在交互过程中选择合适的变更类型（major/minor/patch）并填写简明的 message，生成的文件会位于 `common/changes/**`。 - -## 注意事项 - -- 自动生成的消息质量高度依赖于规范、清晰的 Git 提交历史。 -- 本技能仅生成 `common/changes/**` 下的文件，不执行 `rush version` 或 `rush publish`。 -- 如果需要自动关联 Issue 标题，请确保 `GITHUB_TOKEN` 已在环境中正确配置。 -- 如果 `common/changes/**` 中已经存在覆盖当前提交的条目（例如之前已经为某次修复创建过记录），可以只复核这些文件，不必重复生成新的条目。 - -## 故障排查 - -- **未生成条目**: 检查 `develop...HEAD` 是否存在差异；确认当前仓库根目录执行命令 -- **类型判断不准确**: 显式提供 `bumpType`；保证提交信息遵循 Conventional Commits（如 `feat:`、`fix:`、`docs:`） -- **重复记录**: 检查现有 `common/changes/**` 是否已覆盖当前提交；避免重复生成 -- **关联 Issue 标题失败**: 验证 `GITHUB_TOKEN` 权限并在终端导出环境变量；尝试使用 Fine-grained Token 授权到组织资源 diff --git a/.trae/skills/commit-smart/SKILL.md b/.trae/skills/commit-smart/SKILL.md deleted file mode 100755 index f632223fbe..0000000000 --- a/.trae/skills/commit-smart/SKILL.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -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}}` 将提交推送到远程仓库。 - -## 安全命令示例（避免提交环境文档） - -为了避免将 `.trae/skills` 等环境/文档目录意外提交到远程，可以在使用本技能前或之后配合以下命令： - -```bash -# 查看当前暂存内容 -git status - -# 如果发现 .trae/skills 被错误地加入暂存区，可以将其移除： -git restore --staged .trae/skills - -# 如需手动提交时缩小范围，可使用路径前缀而不是 add --all： -git add packages/vchart src tests -``` - -> 提示：`commit-smart` 在内部会使用 `git add --all` 聚合变更，执行前请先用 `git status` 确认没有不希望提交的目录（如 `.trae/skills`），必要时可先执行 `git restore --staged .trae/skills` 清理暂存区。 - -## 何时使用 / 边界 - -- **使用时机**: - - 在执行了 `auto-test` 和 `changelog-rush-smart` 之后，需要将所有自动生成的文件和你的代码变更一起提交时。 - - 在准备发起 Pull Request 之前的最后一步，用于创建一个干净、规范的提交。 -- **边界**: - - 此技能会提交工作区中 **所有** 的变更，请在执行前确认没有不想被提交的文件。 - - 它不会处理 Git 冲突，执行前请确保分支是干净的。 diff --git a/.trae/skills/commit-smart/docs/USAGE.md b/.trae/skills/commit-smart/docs/USAGE.md deleted file mode 100755 index fc838478de..0000000000 --- a/.trae/skills/commit-smart/docs/USAGE.md +++ /dev/null @@ -1,55 +0,0 @@ -# 使用说明：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` 忽略的变更添加到提交中。请在执行前仔细检查你的工作区，确保没有不想提交的临时文件或改动。 -- 执行前请确保当前分支没有合并冲突，且远程分支已存在。 - -## 故障排查 - -- **误加环境文件**: 执行 `git status` 检查并 `git restore --staged .trae/skills` 取消暂存 -- **提交信息不规范**: 确保提交信息遵循 Conventional Commits；必要时通过 `message` 指定主题 -- **无法推送**: 确认当前分支存在于远程或执行 `git push -u origin <branch>` 建立跟踪 -- **空提交被跳过**: 如需空提交，设置 `commitAllowEmpty: true`；否则将安全跳过 - -## 安全命令示例 - -```bash -# 提交前检查暂存状态 -git status - -# 如发现 .trae/skills 被加入暂存区，撤销暂存： -git restore --staged .trae/skills - -# 需要更精细控制时，可以只对代码目录执行 add： -git add packages/vchart src tests -``` - -> 建议在调用 `commit-smart` 前先清理暂存区中不需要的文件（尤其是 `.trae/skills` 等环境文档），以免被自动提交。 diff --git a/.trae/skills/create-branch/SKILL.md b/.trae/skills/create-branch/SKILL.md deleted file mode 100755 index a37811936d..0000000000 --- a/.trae/skills/create-branch/SKILL.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -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 deleted file mode 100755 index 99c3c9eebc..0000000000 --- a/.trae/skills/create-branch/docs/USAGE.md +++ /dev/null @@ -1,41 +0,0 @@ -# 使用说明：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` 操作可能会覆盖未提交的改动。 -- 本技能只负责创建和切换分支，不处理任何代码的提交或合并。 - -## 命名规范与推送建议 - -- 推荐前缀：`feat/`、`fix/`、`docs/`、`perf/`、`refactor/`、`chore/trae-<topic>-<YYYYMMDD-HHmm>` -- 建议在创建后立即推送以建立远程跟踪关系： - ```bash - git push -u origin <new-branch> - ``` -- 如需调整远程地址或默认分支，使用： - ```bash - git remote -v - git remote set-url origin https://github.com/VisActor/VChart.git - ``` diff --git a/.trae/skills/pr-body-generate/SKILL.md b/.trae/skills/pr-body-generate/SKILL.md deleted file mode 100755 index ff44a9a4a4..0000000000 --- a/.trae/skills/pr-body-generate/SKILL.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -name: pr-body-generate -description: 'Generates a well-formed Pull Request body for the VChart project based on its template. Use this skill to automatically populate the PR body with details like linked issues, changelog entries, self-test checklists, and a code walkthrough. The output is saved to a local file for review and modification before creating the PR.' ---- - -# 生成 PR 正文 (pr-body-generate) - -## 概述 - -本技能用于根据 `VChart` 仓库中预设的 Pull Request 模板，自动生成一份内容丰富、格式规范的 PR 正文。它能够智能地聚合来自 Rush 变更日志、测试报告和 Git 提交历史的信息。 - -## 前置条件 - -- **Git 环境**: 一个配置好的 Git 环境。 -- **本地变更**: 建议在本地已有代码变更和 `common/changes` 变更条目的情况下运行，以生成最完整的 PR 正文。 - -## 输入参数 - -| 参数 | 类型 | 是否必填 | 默认值 | 描述 | -| ---------------- | ------- | -------- | --------------------------------------- | -------------------------------------------------------------- | -| `lang` | string | 否 | `zh` | PR 模板的语言 (`zh` 或 `en`)。 | -| `title` | string | 否 | (空) | 用于生成建议 PR 标题的素材。 | -| `head` | string | 否 | (空) | PR 的源分支名。如果为空，将自动推导当前分支。 | -| `labels` | array | 否 | `[]` | 附加到 PR 的标签，会体现在正文的元信息中。 | -| `rushChangesDir` | string | 否 | `common/changes` | Rush 变更日志条目所在的目录。 | -| `localBodyFile` | boolean | 否 | `true` | 是否将生成的正文保存到本地文件。 | -| `autotestReport` | string | 否 | `.trae/output/autotest.report.local.md` | `auto-test` 技能生成的临时报告路径，其内容会被摘要进 PR 正文。 | -| `autoCheckType` | boolean | 否 | `true` | 是否自动勾选模板中的“分支类型/This is a ...”。 | -| `typeOverride` | string | 否 | (空) | 手动覆盖类型（如 `Workflow`、`New feature` 等），优先级最高。 | - -## 输出与成功标准 - -- **主要输出**: - - `generated_title`: 推荐的 PR 标题。 - - `generated_body_preview`: 生成的完整 PR 正文的 Markdown 预览。 - - `generated_body_file`: 本地保存 PR 正文的文件路径（默认为 `.trae/output/pr.body.local.md`）。 -- **成功标准**: - - `body_generated`: PR 正文已成功生成并按需保存到本地文件。 - -## 执行步骤 - -1. **选择模板（严格遵循）**: 根据 `lang` 参数，精确选择对应的 PR 模板文件（中文：`.github/PULL_REQUEST_TEMPLATE/pr_cn.md`，英文：`.github/PULL_REQUEST_TEMPLATE.md`），并严格保留其章节结构与标题，不新增任何自定义章节或尾注。 -2. **任务类型自动识别与勾选（This is a ... / 这个分支是...）**: - - 勾选策略优先级（从高到低）： - 1. `typeOverride` 显式指定 - 2. 分支名前缀（例如 `feat/`、`fix/`、`chore/auto-flow-...`） - 3. 最近一次提交的 Conventional Commits 类型（如 `feat:`、`fix:`） - 4. 分支名关键词（如 `docs`、`demo`、`perf`、`refactor`、`style`、`test`、`merge`、`release`、`types`、`deps`、`bundle`） - 5. 标签 `labels` 的类型暗示（如包含 `workflow`、`documentation`） - - 英文模板 `.github/PULL_REQUEST_TEMPLATE.md` 的映射： - - `feat` → New feature - - `fix` → Bug fix - - `types`/`typings` → TypeScript definition update - - `bundle`/`size`/`chore(bundle)` → Bundle size optimization - - `perf` → Performance optimization - - `enhance`/`improve` → Enhancement feature - - `refactor` → Refactoring - - `deps`/`chore(deps)` → Update dependency - - `style` → Code style optimization - - `test` → Test Case - - `merge`/`branch-merge` → Branch merge - - `release` → Release - - `docs`/`site` → Site / documentation update - - `demo` → Demo update - - `chore/auto-flow*`、`workflow`、`ci` → Workflow - - 未匹配 → Other (about what?) - - 中文模板 `.github/PULL_REQUEST_TEMPLATE/pr_cn.md` 的映射与上面对应（如 `feat` → 新功能、`fix` → Bug fix、`docs` → 网站/文档更新、`chore/auto-flow*`/`workflow`/`ci` → Workflow 等）。 - - 仅勾选一个“主类型”，避免多选造成歧义；若同时匹配多个类型，选择优先级更高者。 - - 示例： - - `chore/auto-flow-experience` → 勾选 Workflow - - `feat/heatmap-color-scale` → 勾选 New feature / 新功能 - - `fix/tooltip-crash` → 勾选 Bug fix - - `docs/site-nav` → 勾选 Site / documentation update - - `refactor/scale` → 勾选 Refactoring - - `perf/heatmap` → 勾选 Performance optimization - - `test/heatmap` → 勾选 Test Case - - `style/eslint` → 勾选 Code style optimization - - `merge/develop` → 勾选 Branch merge - - `release/vX.Y.Z` → 勾选 Release - - `types/vchart` → 勾选 TypeScript definition update - - `chore(deps): bump lodash` → 勾选 Update dependency -3. **填充内容（仅在模板章节内）**: 仅在模板既有章节下补充内容： - - **Changelog**: 解析 `{{rushChangesDir}}` 目录下的变更条目，并填充到正文的 Changelog 部分。 - - **自测项**: 如果 `autotestReport` 文件存在（默认路径为 `./.trae/output/autotest.report.local.md`），会将其中的测试摘要信息（包括“无新增自动化测试”说明）填充到自测/走查部分；若文件不存在，则在正文中保留空白或占位说明，提示尚未提供自动化测试报告。 - - **背景与方案**: 基于 `message` 参数（如果提供）和提交历史，生成简要的背景与方案描述。 - - **缺失数据的占位处理**: 当未找到 `{{rushChangesDir}}` 下的 changelog 或未提供 `autotestReport` 时，正文仍会生成对应的小节，并使用“暂无 changelog”或“尚未提供自动化测试报告”等最小占位文案，确保结构完整而不会报错。 - - **元信息**: 如需提供分支、标签等信息，放入“背景&解决方案”或相应模板章节的正文中，不新增“提交与后续”等额外章节。 -4. **输出与保存**: - - Agent 会生成一个建议的 PR 标题。 - - 将完整的 PR 正文以 Markdown 预览形式展示。 - - 当 `localBodyFile` 为 `true`（默认行为）时，将模板原文复制并在既有章节内补充内容，保存到 `.trae/output/pr.body.local.md`。输出不包含任何模板外的额外段落（例如“提交与后续”）。 -5. **验证 (Validation)**: - - 生成完成后，请打开 `.trae/output/pr.body.local.md`，检查至少以下几点： - - 标题、背景与方案是否准确概括本次变更。 - - “这个分支是.../This is a ...”是否已正确勾选，且与分支名/提交类型一致。 - - Changelog 小节是否与 `common/changes` 中的内容一致；如没有 changelog，正文中是否有明确的“暂无 changelog”说明。 - - 自测/走查小节是否正确引用了 auto-test 报告；当没有新增测试时，应能看到“无新增自动化测试 (No new tests generated)” 等说明。 - - Summary / Walkthrough 等收尾小节是否存在，整体结构是否完整。 - - 如发现缺失或需要补充的信息，可直接编辑该 Markdown 文件后再执行 `pr-create-from-body`。 - -## 命令示例（本地等价操作） - -如果希望在不依赖技能的情况下，用命令行完成一个最小可用的 PR 正文生成流程，可以在 VChart 仓库根目录参考以下步骤： - -```bash -# 1. 确定当前分支（head） -head="$(git rev-parse --abbrev-ref HEAD)" - -# 2. 选择 PR 模板文件 -# 中文模板： -template=".github/PULL_REQUEST_TEMPLATE/pr_cn.md" -# 英文模板： -# template=".github/PULL_REQUEST_TEMPLATE.md" - -# 3. 确保输出目录存在 -mkdir -p ./.trae/output - -# 4. 将模板内容写入本地临时 PR 正文文件 -cp "$template" ./.trae/output/pr.body.local.md - -# 5. 在编辑器中打开并补充变更摘要、自测结果与覆盖率信息 -${EDITOR:-vim} ./.trae/output/pr.body.local.md -``` - -> 说明：`pr-body-generate` 在内部会在此基础上自动整合 `common/changes` 与 `./.trae/output/autotest.report.local.md` 中的信息，但无论数据是否齐全，都会按照 `localBodyFile: true` 的默认行为写出 `.trae/output/pr.body.local.md` 文件。 - -## 何时使用 / 边界 - -- **使用时机**: - - 在提交代码并生成变更日志之后，创建 PR 之前，用于准备 PR 的描述内容。 - - 作为 `auto-flow` 工作流的一部分，在 `commit-smart` 步骤之后自动调用。 -- **边界**: - - 此技能只生成 PR 正文，不会创建 PR。创建 PR 是 `pr-create-from-body` 技能的职责。 - - 生成内容的丰富程度依赖于前序步骤的产出（如 `changelog` 和 `auto-test` 报告）。 diff --git a/.trae/skills/pr-body-generate/docs/GH_CLI.md b/.trae/skills/pr-body-generate/docs/GH_CLI.md deleted file mode 100755 index e2bd4c6c93..0000000000 --- a/.trae/skills/pr-body-generate/docs/GH_CLI.md +++ /dev/null @@ -1,41 +0,0 @@ -# GitHub CLI (gh) 核心指南 - -GitHub CLI (`gh`) 是与 GitHub 交互（尤其是创建 Pull Request）的首选执行器。在 `mode: auto` 下，`pr-create-from-body` 等技能会优先使用 `gh` 来创建 PR；只有在 `gh` 不可用时才回退到使用 `GITHUB_TOKEN` 的 REST API。 - -## 安装与登录 - -1. **安装**: - * **macOS**: `brew install gh` - * **Windows**: `winget install GitHub.cli` 或 `choco install gh` - -2. **登录**: - * 在终端运行 `gh auth login`。 - * 按照交互式提示操作：选择 `GitHub.com` -> `HTTPS` -> `Login with a web browser`。 - * 浏览器将打开一个页面要求授权。授权后，`gh` 会在本地安全地存储你的凭证。 - -3. **验证**: - * 运行 `gh auth status` 检查你的登录状态和权限。 - -## SSO (单点登录) - -如果目标仓库所属的组织强制使用 SSO，`gh` 在首次访问该组织资源时会自动触发浏览器进行 SSO 授权。只需按提示操作即可。 - -## 使用 - -`pr-create-from-body` 技能在 `mode: auto` 时，会优先使用本机已登录的 `gh` 命令来创建 PR；只有在 `gh` 未安装或未登录时，才会回退到使用 `GITHUB_TOKEN` 的 REST API。 - -**示例命令 (由技能在内部执行):** -```bash -gh pr create \ - --base develop \ - --head your-feature-branch \ - --title "feat: Your great feature" \ - --body-file ./.trae/output/pr.body.local.md -``` - -## 常见问题 - -- **`gh` 命令未找到**: 确保 `gh` 已安装并且其路径已添加到系统的 `PATH` 环境变量中。 -- **403 Forbidden**: - - **权限不足**: 你的 GitHub 账户可能没有对该仓库的写权限。 - - **SSO 问题**: 运行 `gh auth status` 并检查是否已为目标组织授权。如果没有，尝试访问该组织的任一仓库页面，`gh` 可能会自动提示你重新授权。 diff --git a/.trae/skills/pr-body-generate/docs/GITHUB_TOKEN.md b/.trae/skills/pr-body-generate/docs/GITHUB_TOKEN.md deleted file mode 100755 index 0bf6974720..0000000000 --- a/.trae/skills/pr-body-generate/docs/GITHUB_TOKEN.md +++ /dev/null @@ -1,31 +0,0 @@ -# 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 deleted file mode 100755 index efd90de1ba..0000000000 --- a/.trae/skills/pr-body-generate/docs/USAGE.md +++ /dev/null @@ -1,69 +0,0 @@ -# 使用说明：pr-body-generate - -本技能用于自动生成一份内容丰富、格式规范的 Pull Request 正文。 - -## 何时使用 - -- **创建 PR 前**: 在代码提交和 `changelog` 生成之后，使用此技能可以一键生成 PR 的完整描述，节省手动填写模板的时间。 -- **作为流程的一部分**: 在 `auto-flow` 编排中，此技能是创建 PR 之前的关键准备步骤。 - -## 示例对话 - -**场景一: 自动生成正文** - -> **你**: “我已提交了代码和 changelog，现在请帮我生成 PR 正文。” -> -> **Agent**: (执行技能) “PR 正文已生成并保存到 `./.trae/output/pr.body.local.md`。建议标题为 '[Auto] feat: your feature summary'。请审阅内容，然后执行 `pr-create-from-body` 来创建 PR。” - -**场景二: 生成时指定标题和标签** - -> **你**: "执行 `pr-body-generate`，标题是 'feat(vis-component): 新增 Tooltip 组件'，标签是 'feature', 'component'。" -> -> **Agent**: (执行技能) “好的，已生成 PR 正文，其中包含了你指定的标签信息，并为你推荐了标题。” - -## 关键参数 - -- `lang`: PR 模板的语言，支持 `zh` (默认) 和 `en`。 -- `title`: 用于生成建议 PR 标题的素材。 -- `rushChangesDir`: Rush 变更日志条目的目录，默认为 `common/changes`。 -- `localBodyFile`: 是否将生成的正文保存到本地文件，默认为 `true`。 -- `autotestReport`: `auto-test` 技能的报告路径，其内容会被摘要进 PR 正文。 - -## 注意事项 - -- **仅生成不创建**: 此技能只负责生成 PR 正文的 `.md` 文件，**不会** 在 GitHub 上创建 PR。创建操作由 `pr-create-from-body` 技能完成。 -- **依赖前序产出**: 正文内容的丰富程度依赖于之前步骤的产出，例如 `common/changes` 目录下的 `changelog` 文件，以及 `auto-test` 在 `./.trae/output/autotest.report.local.md` 写入的测试报告。若这些信息缺失，技能仍会生成一个结构完整但内容较为精简的正文，并在相应小节中标注“暂无 changelog”或“尚未提供自动化测试报告”等提示。 -- **人工审查与验证**: 自动生成的内容是草稿，强烈建议在执行下一步前打开 `./.trae/output/pr.body.local.md`，至少检查：标题是否准确、Changelog 是否匹配实际变更、自测小节是否正确引用 auto-test 报告（或在无新增测试时包含“无新增自动化测试 (No new tests generated)” 说明）、总体结构是否完整。如有需要可直接编辑该文件后再执行 `pr-create-from-body`。 - -## 进阶用法与排查 - -- **自动勾选分支类型**: 若设置 `autoCheckType: true`（默认），技能会依据分支前缀/最近提交类型/标签来判断“这个分支是...”，如 `feat/`→新功能、`docs/`→网站/文档更新、`chore/auto-flow-...`→Workflow 等 -- **缺失数据占位**: 当缺少 `changelog` 或 `autotestReport` 时，生成文档会在相应小节插入占位说明，避免结构破坏 -- **模板语言选择错误**: 请确保 `lang` 与团队评审习惯一致；中文模板路径为 `.github/PULL_REQUEST_TEMPLATE/pr_cn.md`，英文模板为 `.github/PULL_REQUEST_TEMPLATE.md` -- **正文未覆盖关键信息**: 在保存到 `./.trae/output/pr.body.local.md` 后可直接编辑补充：关联 issue、背景与方案、风险与兼容性、验证说明等 - -## 命令示例（本地等价操作） - -在 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 deleted file mode 100755 index 4fcb3fea69..0000000000 --- a/.trae/skills/pr-create-from-body/SKILL.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -name: pr-create-from-body -description: 'Creates a GitHub Pull Request for the VChart project using a local markdown file as its body. This skill exclusively uses a logged-in `gh` CLI environment to operate.' ---- - -# 从本地文件创建 PR (pr-create-from-body) - -## 概述 - -本技能用于读取一个本地 Markdown 文件作为 Pull Request 的正文，并在 GitHub 上创建该 PR。它是 `pr-body-generate` 技能的后续步骤，负责将准备好的内容发布出去。此技能仅支持通过 GitHub CLI (`gh`) 创建 PR。 - -## 前置条件 - -- **GitHub CLI**: 必须已安装并登录 `gh` CLI，且能访问目标仓库。此技能在执行 `gh` 时会显式忽略环境中的 `GITHUB_TOKEN`，仅使用本地凭证（浏览器 OAuth/Keychain）进行认证。 -- **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 文件的路径。 | -| `draft` | boolean | 否 | `false` | 是否将 PR 创建为草稿（Draft）状态。 | -| `labels` | array | 否 | `[]` | 要附加到 PR 的标签列表。 | - -## 输出与成功标准 - -- **主要输出** (`pr_url`): 成功创建的 Pull Request 的 URL。 -- **成功标准** (`pr_created`): Pull Request 已在 GitHub 上成功创建。 - -## 执行步骤 - -1. **参数与环境检查**: - - Agent 会检查 `title` 是否已提供。 - - 确认 `head` 分支，如果未提供则自动检测当前分支。 - - 检查 `bodyFile` 指定的文件是否存在且内容不为空。 - - 检查 `gh` CLI 是否已安装并已登录，且当前目录映射到正确的 GitHub 仓库。 - - 若当前会话存在 `GITHUB_TOKEN`，在后续调用中将通过清理该变量来避免其参与认证。 - -2. **（可选）提交变更**: 如果 `commitBeforeCreate` 设置为 `true` 且有未提交的变更，Agent 会先执行一次智能提交（类似于 `commit-smart` 技能）。 - -3. **创建 PR**: - - 使用 `gh pr create` 命令，并通过 `--body-file` 参数直接传入正文文件；按需设置 `--base`、`--head`、`--title`、`--draft`、`--label` 等参数。 - - 为确保仅使用 gh 本地凭证，调用时显式清除环境变量：`env -u GITHUB_TOKEN gh pr create ...`。 - -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 -``` - -> 说明：`pr-create-from-body` 在内部执行与上述命令等价的 `gh pr create`。 - -## 错误处理与排查 - -当创建 PR 失败时，可以按以下顺序排查： - -1. **检查 gh 安装与登录状态** - - 运行 `gh --version` 确认命令可用。 - - 运行 `gh auth status` 确认已登录 `github.com`，并具备访问 `VisActor/VChart` 的权限。 - - 如提示正在使用 `GITHUB_TOKEN`，请执行 `env -u GITHUB_TOKEN gh auth login` 完成浏览器登录以建立本地凭证。 - -2. **确认仓库远程指向正确** - - 在仓库根目录执行 `git remote -v`，确认 `origin` 指向 GitHub 上的 `VisActor/VChart`。 - - 执行 `gh repo view` 验证 `gh` 能识别当前目录对应的仓库。 - -3. **处理组织 SSO 授权问题** - - 如果组织启用了 SSO，按 `gh auth status` 提示完成 SSO 授权，或在浏览器中重新授权访问 `VisActor` 组织。 - -若以上步骤均正常但仍报错，建议记录错误信息（HTTP 状态码与提示内容），并根据提示进一步排查或联系仓库维护者。 - -## 何时使用 / 边界 - -- **使用时机**: - - 在使用 `pr-body-generate` 生成并（可选地）人工审查了 PR 正文之后，作为发布的最后一步。 - - 当你有一个准备好的 Markdown 文件，并希望用它作为 PR 的描述来快速创建 PR 时。 -- **边界**: - - 此技能强依赖于一个已存在的、内容完备的本地正文文件。 - - 它不会修改 PR 正文内容，只是“按原样”上传。 - - 创建 PR 前，请确保你的 `head` 分支已经包含了所有需要合并的提交，并已推送到远程仓库。 diff --git a/.trae/skills/pr-create-from-body/docs/GH_CLI.md b/.trae/skills/pr-create-from-body/docs/GH_CLI.md deleted file mode 100755 index cb9b6f6b40..0000000000 --- a/.trae/skills/pr-create-from-body/docs/GH_CLI.md +++ /dev/null @@ -1,71 +0,0 @@ -# GitHub CLI (gh) 核心指南 - -GitHub CLI (`gh`) 是与 GitHub 交互（尤其是创建 Pull Request）的唯一支持方式。`pr-create-from-body` 技能仅通过 `gh` 来创建 PR。 - -## 安装与登录 - -1. **安装**: - - - **macOS**: `brew install gh` - - **Windows**: `winget install GitHub.cli` 或 `choco install gh` - - **Linux (Debian/Ubuntu)**: `sudo apt update && sudo apt install gh` - - **Linux (RHEL/CentOS/Fedora)**: `sudo dnf install gh` 或 `sudo yum install gh` - - 安装后可用 `which gh` 或 `gh --version` 验证是否在 `PATH` 中 - -2. **登录**: - - - 在终端运行：`gh auth login` - - 交互式选择：`GitHub.com` → `HTTPS` → `Login with a web browser` - - 浏览器授权完成后，本地凭证自动保存（支持 2FA） - - 验证登录状态：`gh auth status`，必要时刷新权限：`gh auth refresh -h github.com -s repo` - -3. **验证**: - - 运行 `gh auth status` 检查登录状态与授权范围 - - 运行 `gh repo view` 确认当前目录识别为 GitHub 仓库（需在仓库根目录） - - 运行 `git remote -v` 检查 `origin` 是否指向 `VisActor/VChart` - -## SSO (单点登录) - -如果目标仓库所属的组织强制使用 SSO，`gh` 在首次访问该组织资源时会自动触发浏览器进行 SSO 授权。只需按提示操作即可。 - -## 使用 - -`pr-create-from-body` 技能会使用本机已登录的 `gh` 命令来创建 PR。使用前请确保： - -- 当前分支已推送到远程：`git push -u origin <your-branch>` -- 仓库可被识别：`gh repo view` 在项目根目录能正常输出项目信息 -- 若会话存在 `GITHUB_TOKEN`，为避免走 Token 认证并导致 401，请使用本地凭证方式：`env -u GITHUB_TOKEN gh auth login`，并在创建 PR 时同样清除该变量。 - -**示例命令 (由技能在内部执行):** - -```bash -env -u GITHUB_TOKEN gh pr create \ - --base develop \ - --head your-feature-branch \ - --title "feat: Your great feature" \ - --body-file ./.trae/output/pr.body.local.md -``` - -**常用参数扩展:** - -- `--draft` 将 PR 设为草稿 -- `--label <name>` 可多次添加标签 -- `--assignee <user>` 指定受理人 -- `--reviewer <user>` 指定评审人，可多次 -- `--fill` 自动从提交历史生成标题与正文（本技能通常使用 `--body-file`） -- `-B`/`--base` 指定目标分支；`-H`/`--head` 指定源分支 - -## 常见问题 - -- **`gh` 命令未找到**: 确保 `gh` 已安装并且其路径已添加到系统的 `PATH` 环境变量中。 -- **403 Forbidden**: - - **权限不足**: 你的 GitHub 账户可能没有对该仓库的写权限。 - - **SSO 问题**: 运行 `gh auth status` 并检查是否已为目标组织授权。如果没有，尝试访问该组织的任一仓库页面，`gh` 可能会自动提示你重新授权。 -- **404 Not Found / 仓库不可识别**: - - 当前目录不是 Git 仓库，或 `origin` 未指向 `VisActor/VChart`；在根目录运行 `git remote -v` 与 `gh repo view` -- **422 Validation Failed**: - - 相同的 `head`→`base` 已存在打开的 PR；可访问仓库 PR 页面确认并更新现有 PR -- **网络/代理问题**: - - 企业网络下需设置 `HTTPS_PROXY` 或 `HTTP_PROXY` 环境变量；确保浏览器能完成 OAuth -- **分支未推送**: - - 执行 `git push -u origin <your-branch>` 后重试 `gh pr create` diff --git a/.trae/skills/pr-create-from-body/docs/USAGE.md b/.trae/skills/pr-create-from-body/docs/USAGE.md deleted file mode 100755 index dc3dc1f47c..0000000000 --- a/.trae/skills/pr-create-from-body/docs/USAGE.md +++ /dev/null @@ -1,65 +0,0 @@ -# 使用说明：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`。 -- `draft`: 是否将 PR 创建为草稿状态，默认为 `false`。 - -## 注意事项 - -- **凭证**: 执行前，必须确保 `gh` CLI 已安装并登录。请参阅本技能目录下的 `docs/GH_CLI.md`。 -- **分支推送**: 在创建 PR 之前，请务必确保你的本地分支 (`head`) 已经推送到 GitHub 远程仓库，否则 GitHub 无法找到该分支。 -- **正文文件**: 确认 `bodyFile` 指向的文件存在且内容正确。 -- **常见失败的排查清单**： - - 使用 `gh auth status` 检查 CLI 登录状态以及是否已为目标组织完成 SSO 授权； - - 在仓库根目录运行 `git remote -v` 与 `gh repo view`，确认当前目录映射到 GitHub 上的 `VisActor/VChart` 仓库； - - 确认分支已推送（`git push -u origin <your-branch>`），并确保不存在重复的 `head→base` 打开 PR - - 若环境中存在 `GITHUB_TOKEN` 导致使用 Token 认证，请改用本地凭证：`env -u GITHUB_TOKEN gh auth login` 后重试 - -## Quick Actions（一键命令示例） - -### gh CLI - -在 VChart 仓库根目录执行： - -```bash -# 登录（如尚未登录） -gh auth login - -# 使用本地正文文件创建 PR -env -u GITHUB_TOKEN gh pr create \ - -B develop \ - -H <your-branch> \ - -t "<your-title>" \ - -F ./.trae/output/pr.body.local.md \ - --label changelog \ - --label test - # 可选：更多参数 - # --draft - # --assignee your-username - # --reviewer reviewer-1 --reviewer reviewer-2 -```