periodic: merge to main as stable

.github/workflows/cpp-check.yml

@@ -0,0 +1,68 @@
+name: C++ Check
+
+on:
+  pull_request:
+    branches:
+      - main
+      - release/*
+    types:
+      - opened
+      - synchronize
+      - reopened
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  linux-build-test:
+    name: Linux build and tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build Docker image
+        run: |
+          docker build \
+            --platform linux/amd64 \
+            --build-arg QT_ARCH=linux_gcc_64 \
+            -f scripts/docker/Dockerfile.build \
+            -t cfdesktop-build \
+            .
+
+      - name: Configure, build, and test
+        run: |
+          docker run --rm \
+            --platform linux/amd64 \
+            -e QT_QPA_PLATFORM=offscreen \
+            -v "$PWD:/project" \
+            -w /project \
+            cfdesktop-build \
+            bash -lc "bash scripts/build_helpers/linux_develop_build.sh ci -c build_ci_config.ini && bash scripts/build_helpers/linux_run_tests.sh ci -c build_ci_config.ini"
+
+  docs-build:
+    name: VitePress docs build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.33.3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build docs
+        run: pnpm build

.github/workflows/deploy.yml

@@ -1,94 +1,61 @@
-# 工作流名称
-name: 自动部署 MkDocs
+name: Deploy VitePress
 
-# 触发条件：推送到 main 分支
 on:
   push:
     branches:
       - main
-
-  # 允许手动触发
   workflow_dispatch:
 
-# 设置权限
 permissions:
-  contents: write  # 允许推送到 gh-pages 分支
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
 
 jobs:
-  deploy:
+  build:
     runs-on: ubuntu-latest
-    
+
     steps:
-      # 1. 检出代码
-      - name: 检出仓库
+      - name: Checkout
         uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
         with:
-          fetch-depth: 0  # 获取完整历史，显示文章修改时间
-
-      # 2. 设置 Python
-      - name: 设置 Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-          # cache: 'pip'  # 缓存依赖，加速构建
-
-      # 3. 安装依赖
-      - name: 安装依赖
-        run: |
-          pip install mkdocs-material
-          pip install mkdocs-awesome-pages-plugin
-          pip install mkdocs-git-revision-date-localized-plugin
-
-      # 4. 安装 Doxygen
-      - name: 安装 Doxygen
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y doxygen
+          version: 10.33.3
 
-      # 5. 安装 doxybook2
-      - name: 安装 doxybook2
-        run: |
-          # 下载最新版本的 doxybook2
-          DOXYBOOK2_VERSION="1.5.0"
-          wget https://github.com/matusnovak/doxybook2/releases/download/v${DOXYBOOK2_VERSION}/doxybook2-linux-amd64-v${DOXYBOOK2_VERSION}.zip
-          unzip doxybook2-linux-amd64-v${DOXYBOOK2_VERSION}.zip
-          sudo mv bin/doxybook2 /usr/local/bin/
-          sudo chmod +x /usr/local/bin/doxybook2
-          doxybook2 --version
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
 
-      # 6. 生成 API 文档(Doxygen → Markdown)
-      - name: 生成 API 文档
-        run: |
-          doxygen Doxyfile
-          rm -rf document/api
-          mkdir -p document/api
-          doxybook2 --input ./xml \
-                    --output ./document/api \
-                    --config doxybook.json
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
 
-      # 6.5. 为自动生成的 API 文档配置导航
-      - name: 配置 API 导航
-        run: |
-          cat > document/api/.pages <<'EOF'
-          title: API 自动文档
-          icon: material/file-document
-          nav:
-            - 命名空间: Namespaces
-            - 类: Classes
-            - 文件: Files
-          EOF
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
 
-      # 6.6. 修复 doxybook2 生成的相对链接路径
-      - name: 修复 API 文档链接
-        run: python3 scripts/document/fix_doxybook_links.py
+      - name: Build docs
+        run: pnpm build
 
-      # 7. 构建网站
-      - name: 构建网站
-        run: mkdocs build --clean
-
-      # 8. 自动部署到 gh-pages 分支（这一步会自动触发 GitHub Pages）
-      - name: 部署到 GitHub Pages
-        uses: peaceiris/actions-gh-pages@v4
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}  # GitHub 自动提供的 token
-          publish_dir: ./site  # MkDocs 构建输出目录
+          path: site/.vitepress/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/docs-check.yml

@@ -0,0 +1,41 @@
+name: Docs Check
+
+on:
+  pull_request:
+    branches:
+      - develop
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - labeled
+
+permissions:
+  contents: read
+
+jobs:
+  vitepress:
+    name: VitePress build
+    if: contains(github.event.pull_request.labels.*.name, 'build-doc')
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.33.3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build docs
+        run: pnpm build

.gitignore

@@ -1,31 +1,38 @@
-# ignores
-.cache
-.claude
-
-# aqtinstall log
-aqtinstall.log
-# privates
-BLUEPRINT.md
-
-# native builds
-out/
-
-# Documents summons
-xml/
-site/
-document/api/
-
-# .vscode
-.vscode
-
-# third_party dependencies (downloaded during configuration)
-third_party/*/
-!third_party/.gitkeep
-
-__pycache__/
-
-# Python virtual environment
-.venv/
-
-# Docker build logs
-scripts/docker/logger/
+# ignores
+.cache
+.claude
+CLAUDE.md
+MEMORY.md
+
+# aqtinstall log
+aqtinstall.log
+# privates
+BLUEPRINT.md
+
+# native builds
+out/
+
+# Documents summons
+xml/
+document/api/
+
+# .vscode
+.vscode
+
+# third_party dependencies (downloaded during configuration)
+third_party/*/
+!third_party/.gitkeep
+
+__pycache__/
+
+# Python virtual environment
+.venv/
+
+# Docker build logs
+scripts/docker/logger/
+
+# Node/VitePress
+node_modules/
+site/.vitepress/cache/
+site/.vitepress/dist/
+site/.vitepress/.temp

AGENT.md

@@ -0,0 +1,51 @@
+# AGENT.md — Project Conventions for AI Agents
+
+## Build System
+
+- **Language**: C++23 / CMake (minimum 3.16), Qt 6
+- **Build directory**: `out/build_develop/`
+- **Configure**: `bash scripts/build_helpers/linux_configure.sh`
+- **Build (no re-configure)**: `bash scripts/build_helpers/linux_fast_develop_build.sh`
+- **Build (full clean + build + tests)**: `bash scripts/build_helpers/linux_develop_build.sh`
+
+## Doxygen Fix Workflow
+
+### 1. Read the spec
+
+Read `document/DOXYGEN_REQUEST.md` in full — it is the authoritative Doxygen style guide.
+
+### 2. Read the violations
+
+Read `FAILED_DOXYGEN.md` for the current list of violations, grouped by file.
+
+### 3. Read the linter
+
+Skim `scripts/doxygen/lint.py` to understand the exact checks (file header, function blocks, return tags, param directions, language rules, etc.).
+
+### 4. Fix by file
+
+For each flagged file, read the source, then:
+
+1. **File header** — add `/** @file ... */` at top if missing (see DOXYGEN_REQUEST.md Section 2).
+2. **Type comments** — add `/** @brief ... */` before any undocumented public enum/struct/class.
+3. **Function comments** — add a Doxygen block before each flagged function. Key rules:
+   - Every `@param` needs a direction: `[in]`, `[out]`, or `[in,out]`.
+   - Non-void functions **must** have `@return`. Void functions **must not**.
+   - Tags to always include: `@brief`, `@throws` (or `None`), `@note` (or `None`), `@warning` (or `None`), `@since` (`N/A`), `@ingroup` (`none`).
+4. **Style consistency** — use `/** */` block style or `///` line style consistently within a file.
+5. **Language** — third-person present tense only. No "will", "we", "I", "our", "my".
+
+### 5. Validate
+
+```bash
+python3 scripts/doxygen/lint.py
+```
+
+Iterate up to 3 passes if violations remain.
+
+## Key Constraints
+
+- Only edit Doxygen comments — never change code logic.
+- All comments in English.
+- Comment lines must be ≤ 100 characters.
+- When uncertain about behavior, use `@note FIXME: ...` rather than guessing.