refactor(mcp_env): 改进 before_launch 钩子处理逻辑

.claude/skills/rock-docs/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: rock-docs
+description: 为 ROCK 项目管理 Docusaurus 文档版本。支持添加新版本文档、添加 Release Note、管理中英文 i18n 文档。当用户说"添加文档版本"、"发布新版本文档"、"添加 release note"、"rock-docs"或需要操作 docs/ 目录下的版本化文档时使用。
+---
+
+# ROCK Docs
+
+管理 ROCK 项目的 Docusaurus 版本化文档。
+
+## 项目背景
+
+- Docusaurus 3.9.x，部署于 `https://alibaba.github.io/ROCK/`
+- 语言：英文（默认）+ 中文（zh-Hans）
+- `includeCurrentVersion: false`，所有发布内容来自 `versioned_docs/`
+- `versions.json` 驱动版本注册，`convertVersionsArrayToObject()` 自动生成配置
+- 侧边栏：顶层手动 + 内层 `autogenerated`
+- Release Notes 通过 `reverseReleaseNoteSidebars()` 自动倒序排列
+
+## 需要操作的 6 个位置
+
+| # | 操作 | 路径 |
+|---|------|------|
+| 1 | 创建英文文档目录 | `docs/versioned_docs/version-{NEW}/` |
+| 2 | 创建版本侧边栏 | `docs/versioned_sidebars/version-{NEW}-sidebars.json` |
+| 3 | 更新版本列表 | `docs/versions.json` |
+| 4 | 更新最新版本指向 | `docs/docusaurus.config.js` 中的 `lastVersion` |
+| 5 | 创建中文文档目录 | `docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{NEW}/` |
+| 6 | 创建中文侧边栏翻译 | `docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{NEW}.json` |
+
+## 标准目录结构
+
+```
+version-X.Y.x/
+├── Getting Started/
+├── User Guides/
+├── References/
+│   ├── api.md
+│   └── Python SDK References/
+├── Release Notes/
+│   ├── index.md
+│   └── vX.Y.Z.md
+└── overview.md
+```
+
+## 执行流程
+
+### Phase 0：版本冲突检测
+
+1. 读取 `docs/versions.json` 获取已有版本列表
+2. 从用户输入的版本号推断文档版本号（如 `1.4.5` → `1.4.x`）
+3. 如果文档版本已存在，**跳转至「仅添加 Release Note」流程**
+
+#### 仅添加 Release Note 流程
+
+**Step A**：创建英文 Release Note
+- 路径：`docs/versioned_docs/version-{EXISTING}/Release Notes/v{VERSION}.md`
+- 使用下方英文模板
+
+**Step B**：创建中文 Release Note
+- 路径：`docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{EXISTING}/Release Notes/v{VERSION}.md`
+- 使用下方中文模板
+
+**Step C**：更新 Release Notes 索引
+
+在英文和中文 `Release Notes/index.md` 的标题行下方第一行插入：
+```markdown
+* [release v{VERSION}](v{VERSION}.md)
+```
+
+完成后跳转至 Phase 5 验证。
+
+---
+
+如果文档版本不存在，继续执行完整流程。
+
+### Phase 1：收集信息
+
+1. **新版本号**：如 `1.4.x`
+2. **基础版本**：从哪个版本复制？默认取 `versions.json` 第一项
+3. **Release Note**：是否创建？版本号是什么？
+4. **是否修改 `lastVersion`**：必须明确告知用户影响后再确认：
+
+   > ⚠️ 修改 `lastVersion` 会改变文档站点默认展示版本。当前为 `{当前 lastVersion}`，修改后为 `{NEW}`。是否确认？
+
+   **不要默认选「是」，等用户明确确认。**
+
+具体版本号（如 `1.4.0`）自动推断为文档版本号（`1.4.x`）。
+
+### Phase 2：创建英文文档
+
+#### Step 1：复制英文文档目录
+
+```bash
+cp -r docs/versioned_docs/version-{BASE}/ docs/versioned_docs/version-{NEW}/
+```
+
+#### Step 1.5：清理旧版本 Release Notes（仅主版本号变更时）
+
+当主版本号（major.minor）不同时（如 `1.4.x` → `1.5.x`）：
+
+1. 删除 `docs/versioned_docs/version-{NEW}/Release Notes/` 下除 `index.md` 外的所有 `v*.md`
+2. 重写 `index.md`：
+
+```markdown
+---
+sidebar_position: 1
+---
+# Release Notes
+```
+
+#### Step 2：复制版本侧边栏
+
+```bash
+cp docs/versioned_sidebars/version-{BASE}-sidebars.json docs/versioned_sidebars/version-{NEW}-sidebars.json
+```
+
+#### Step 3：创建 Release Note（如果需要）
+
+**英文模板** `docs/versioned_docs/version-{NEW}/Release Notes/v{VERSION}.md`：
+```markdown
+# v{VERSION}
+
+## Release Date
+{Mon DD, YYYY}
+
+---
+
+TODO
+```
+
+**中文模板** `docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{NEW}/Release Notes/v{VERSION}.md`：
+```markdown
+# v{VERSION}
+
+## 发布日期
+{YYYY} 年 {M} 月 {D} 日
+
+---
+
+TODO
+```
+
+#### Step 3.5：更新 Release Notes 索引
+
+在英文 `docs/versioned_docs/version-{NEW}/Release Notes/index.md` 标题行下方第一行插入：
+```markdown
+* [release v{VERSION}](v{VERSION}.md)
+```
+
+### Phase 3：创建中文文档
+
+#### Step 4：复制中文文档目录
+
+```bash
+cp -r docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{BASE}/ docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{NEW}/
+```
+
+#### Step 4.5：清理中文旧版本 Release Notes（仅主版本号变更时）
+
+与 Step 1.5 同理：
+1. 删除 `docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{NEW}/Release Notes/` 下除 `index.md` 外的所有 `v*.md`
+2. 重写 `index.md`（中文版标题为 `# 版本说明`）：
+
+```markdown
+---
+sidebar_position: 1
+---
+# 版本说明
+```
+
+#### Step 5：创建中文侧边栏翻译 JSON
+
+```bash
+cp docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{BASE}.json docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{NEW}.json
+```
+
+修改新 JSON 文件中的 `version.label`：
+
+```json
+{
+  "version.label": {
+    "message": "{NEW}",
+    "description": "The label for version {NEW}"
+  }
+}
+```
+
+### Phase 4：更新配置
+
+#### Step 6：更新 versions.json
+
+在 `docs/versions.json` 数组开头插入 `{NEW}`。
+
+#### Step 7：更新 docusaurus.config.js（仅用户明确确认后）
+
+修改 `docs/docusaurus.config.js` 中的 `lastVersion` 从 `{BASE}` 为 `{NEW}`。用户选择不修改则跳过。
+
+### Phase 5：验证
+
+**Step 8：构建验证**
+```bash
+cd docs && npm run build
+```
+构建成功后启动预览：
+```bash
+cd docs && npm run serve
+```
+> `npm run serve` 基于构建产物启动，支持中英文切换验证。`npm run start` 仅加载默认语言，无法验证中文。
+
+**Step 9：手动检查清单**
+
+```
+✅ 文档验证清单：
+
+英文版本检查：
+   □ 版本下拉菜单中是否显示新版本
+   □ 默认展示版本是否符合预期
+   □ 英文文档页面是否正常渲染
+   □ Release Notes 是否按版本号倒序排列
+   □ 侧边栏导航是否完整
+
+中文版本检查（右上角语言切换）：
+   □ 中文文档页面是否正常显示
+   □ 侧边栏分类名称是否正确翻译
+   □ Release Notes 内容是否与英文版本对应
+
+后续工作：
+   □ 更新新版本英文文档中的具体内容
+   □ 更新中文文档翻译内容
+   □ 如有 Release Note，补充具体发布内容
+```
+
+## 注意事项
+
+- `docs/rock/` 是未发布版本源码，`includeCurrentVersion: false` 不会发布
+- `HiddenSidebars` 中的文件会从侧边栏隐藏，但仍可通过直接链接访问
+- 详细 i18n 配置、侧边栏管理、翻译流程参见 [references/i18n-guide.md](references/i18n-guide.md)

.claude/skills/rock-docs/references/i18n-guide.md

@@ -0,0 +1,70 @@
+# Docusaurus i18n 与侧边栏管理参考
+
+## 扩展参考
+
+- 官方 i18n 教程：https://docusaurus.io/docs/i18n/tutorial
+
+## 侧边栏配置
+
+本项目采用 **"顶层手动 + 内层自动"** 的混合模式：
+
+- **顶层分类**（Getting Started、User Guides、References、Release Notes）在侧边栏配置中**手动定义**
+- **内层文档**通过 `autogenerated` 从目录中**自动生成**，新文件放入对应目录即可自动出现在侧边栏
+
+### 添加新的顶层侧边栏分类
+
+需要手动修改以下文件：
+
+1. **主侧边栏配置**：`docs/sidebars.js` — 添加新的顶层 category
+2. **各版本侧边栏**：`docs/versioned_sidebars/version-{VERSION}-sidebars.json` — 添加对应的 category 配置
+3. **中文翻译 JSON**：`docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{VERSION}.json` — 添加 `sidebar.tutorialSidebar.category.{CategoryName}` 条目
+
+顶层分类配置格式示例（`version-1.4.x-sidebars.json`）：
+
+```json
+{
+  "type": "category",
+  "label": "New Category",
+  "items": [
+    {
+      "type": "autogenerated",
+      "dirName": "New Category"
+    }
+  ]
+}
+```
+
+在 `versioned_docs/version-{VERSION}/` 和对应 i18n 目录下创建同名文件夹，内层文档会自动生成侧边栏条目。
+
+**在已有分类下添加新文档**，无需修改侧边栏配置，直接将 md 文件放入对应目录即可。
+
+## 翻译文件结构
+
+翻译文件存储在 `docs/i18n/zh-Hans/` 目录下：
+
+| 文件/目录 | 用途 |
+|---------|------|
+| `docusaurus-plugin-content-docs/version-{V}.json` | 侧边栏分类名称和版本标签翻译 |
+| `docusaurus-plugin-content-docs/version-{V}/` | 各版本文档内容中文翻译 |
+| `docusaurus-theme-classic/navbar.json` | 导航栏文本翻译 |
+| `docusaurus-theme-classic/footer.json` | 页脚文本翻译 |
+| `code.json` | React 代码中的文本标签翻译 |
+
+### 提取翻译 key
+
+```bash
+cd docs && npm run write-translations -- --locale zh-Hans
+```
+
+该命令自动扫描项目代码和配置，生成需要翻译的 JSON 文件。生成后编辑对应 JSON 文件填入中文翻译。
+
+## 翻译文档内容
+
+文档内容翻译通过在 i18n 目录下创建对应的 markdown 文件实现。文件路径必须与英文原文完全对应：
+
+```
+英文原文：docs/versioned_docs/version-1.4.x/User Guides/example.md
+中文翻译：docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.4.x/User Guides/example.md
+```
+
+如果中文目录下不存在对应文件，Docusaurus 会回退到英文原文展示。

.github/scripts/get-CI-result.sh

@@ -9,6 +9,8 @@ fi
 COMMIT_ID=$1
 SECURITY=$2
 REPOSITORY=$3
+PIPELINE_ID="42305"
+PROJECT_ID="3567319"
 
 # 设置最大等待时间
 MAX_WAIT_TIME=7200
@@ -19,7 +21,7 @@ while true; do
 
     response=$(curl -s  -H "Content-Type: application/json" \
                         -H "Authorization: Basic ${SECURITY}" \
-                        -d "{\"type\": \"RETRIEVE-TASK-STATUS\", \"repositoryUrl\": \"${REPOSITORY}\", \"commitId\": \"${COMMIT_ID}\"}" "http://get-tasend-back-twkvcdsbpj.cn-hangzhou.fcapp.run")
+                        -d "{\"type\": \"RETRIEVE-TASK-STATUS\", \"aone\": { \"projectId\": \"${PROJECT_ID}\", \"pipelineId\": \"${PIPELINE_ID}\"}, \"repositoryUrl\": \"${REPOSITORY}\",\"commitId\": \"${COMMIT_ID}\"}" "http://get-tasend-back-twkvcdsbpj.cn-hangzhou.fcapp.run")
     echo "Response: $response"
 
     # 检查curl是否成功

.github/workflows/CI-request-trigger.yml

@@ -0,0 +1,51 @@
+# This is a basic workflow to help you get started with Actions
+
+name: CI Request Trigger
+
+# Controls when the workflow will run
+on:
+  pull_request:
+    branches: [ "master" ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  # This workflow contains a single job called "build"
+  build:
+    # The type of runner that the job will run on
+    runs-on: ubuntu-latest
+    # work on CI script dir
+    defaults:
+      run:
+        working-directory: .github/scripts
+    # Steps represent a sequence of tasks that will be executed as part of the job
+    steps:
+      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      - uses: actions/checkout@v4
+
+      # Runs trigger CI
+      - name: Make the script files executable
+        run: chmod +x trigger-CI.sh get-CI-result.sh
+      - name: trigger a CI
+        run: |
+          echo "=== Task started at: $(date '+%Y-%m-%d %H:%M:%S') ==="
+          COMMIT_ID=$([ "${{ github.event_name }}" == "pull_request" ] && echo "${{ github.event.pull_request.head.sha }}" || echo "${{ github.sha }}")
+          echo "Using Commit ID: $COMMIT_ID"
+          echo "$GITHUB_REF"
+          PR_ID=$(echo "$GITHUB_REF" | sed 's@refs/pull/\([0-9]\+\)/.*@\1@')
+          echo "PR ID is $PR_ID"
+          ./trigger-CI.sh "$COMMIT_ID" "${{ secrets.CI_SECRET }}" "${{ github.event.pull_request.head.repo.clone_url }}" "$PR_ID"
+
+      # Runs get CI result
+      - name: Get CI result
+        run: |
+          echo "=== Task started at: $(date '+%Y-%m-%d %H:%M:%S') ==="
+          COMMIT_ID=$([ "${{ github.event_name }}" == "pull_request" ] && echo "${{ github.event.pull_request.head.sha }}" || echo "${{ github.sha }}")
+          echo "Using Commit ID: $COMMIT_ID"
+          ./get-CI-result.sh "$COMMIT_ID" "${{ secrets.CI_SECRET }}" "${{ github.repository }}"

.github/workflows/deploy.yml

@@ -38,6 +38,7 @@ jobs:
             ${{ runner.os }}-node-
 
       - run: npm install
+      - run: npm install webpack@5.105.4 --no-save
       - run: npm run build
 
       - name: Deploy

.github/workflows/python-ci.yml

@@ -55,8 +55,9 @@ jobs:
         echo "🔐 Running admin tests..."
         uv run pytest -n auto -m "need_admin" --reruns 1
 
+    # Only run after merge into master / release/v1.0 (push event), not on PRs. See #1039
     - name: Run tests need admin and network
-      if: success()
+      if: success() && github.event_name == 'push'
       run: |
         echo "🔐 Running admin and network tests..."
         uv run pytest -n auto -m "need_admin_and_network" --reruns 1