Merge pull request #318 from Websoft9/feat/docs-cicd-bmad-standardization

feat: docs/cicd/bmad standardization

Author: chendelin1982

.github/workflows/app_from_contentful.yml

@@ -1,3 +1,7 @@
+# 从 Contentful CMS 自动生成 App 应用的元数据文档（_include/）和 App 文档骨架。
+# 触发方式：管理员手动触发（workflow_dispatch），需要仓库 Write 权限 + CONTENTFUL_ACCESS_TOKEN。
+# 注意：该 workflow 生成的 _include/ 文件不应手工修改，属于自动管理内容。
+
 name: Generate Apps header and appdocs files
 
 on:
@@ -8,14 +12,15 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
       with:
         fetch-depth: 0
 
     - name: Set up Python
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v5
       with:
         python-version: '3.x'
+        cache: 'pip'
 
     - name: Install dependencies
       run: |
@@ -26,9 +31,9 @@ jobs:
       env:
         CONTENTFUL_ACCESS_TOKEN: ${{ secrets.CONTENTFUL_GRAPHQLTOKEN }}
       run: |
-        python builds/gen_md_from_contenful.py template/meta/zh_head.jinja2  versioned_docs/version-2.0/apps/_include --override
-        python builds/gen_md_from_contenful.py template/meta/en_head.jinja2 i18n/en/docusaurus-plugin-content-docs/version-2.0/apps/_include --override
-        python builds/gen_md_from_contenful.py template/meta/zh_app.jinja2  versioned_docs/version-2.0/apps --ignore-list template/meta/skip_file.json
+        python builds/gen_md_from_contenful.py template/meta/zh_head.jinja2 versioned_docs/version-2.0/apps/_include
+        python builds/gen_md_from_contenful.py template/meta/en_head.jinja2 i18n/en/docusaurus-plugin-content-docs/version-2.0/apps/_include
+        python builds/gen_md_from_contenful.py template/meta/zh_app.jinja2 versioned_docs/version-2.0/apps --ignore-list template/meta/skip_file.json
         python builds/gen_md_from_contenful.py template/meta/en_app.jinja2 i18n/en/docusaurus-plugin-content-docs/version-2.0/apps --ignore-list template/meta/skip_file.json
         
     - name: Commit and push changes

.github/workflows/build_doc.yml

@@ -1,15 +1,28 @@
-# This workflow is triggered on pushes and pull requests to any branch.
-# The job name includes the branch name dynamically.
+# 文档构建与部署工作流
+# - dev 分支：只构建，不部署（用于验证 PR 不破坏构建）
+# - main 分支：构建 + 部署到 Cloudflare Pages（生产环境）
 
 name: Docs Build and Upload to Cloudflare
 
-on: 
+on:
   workflow_dispatch:
   push:
     branches:
       - dev
       - main
-    paths: 
+    paths:
+      - 'docs/**'
+      - 'versioned_docs/**'
+      - 'i18n/**'
+      - 'src/**'
+      - 'static/**'
+      - '**.js'
+      - '.github/workflows/**'
+      - '!docs/_list'
+  pull_request:
+    branches:
+      - dev
+    paths:
       - 'docs/**'
       - 'versioned_docs/**'
       - 'i18n/**'
@@ -18,57 +31,65 @@ on:
       - '**.js'
       - '!docs/_list'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     name: Build on branch ${{ github.ref_name }}
     runs-on: ubuntu-latest
-    #if: false # stop steps
     steps:
-    - uses: actions/checkout@master
+    - uses: actions/checkout@v4
+
     - uses: actions/setup-node@v4
       with:
-        node-version: 20        
+        node-version: 20
+
+    - name: Cache yarn dependencies
+      uses: actions/cache@v4
+      with:
+        path: node_modules
+        key: ${{ runner.os }}-yarn-${{ hashFiles('**/package.json') }}
+        restore-keys: |
+          ${{ runner.os }}-yarn-
+
     - name: Docusaurus build
       run: |
         yarn install
         yarn run build
       env:
         CI: true
-        
-    - name: Debug
-      run: ls
 
     - name: Create apidocs directory and add files
+      continue-on-error: true
       run: |
         mkdir -p build/apidocs
         cd build/apidocs
         wget -O redoc.standalone.js https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js
         wget -O README.md https://websoft9.github.io/websoft9/apphub/apidocs/README.md
         wget -O index.html https://websoft9.github.io/websoft9/apphub/apidocs/index.html
         docker run -d --name apphub -p 8080:8080 websoft9dev/apphub:latest
-          sleep 5
-          max_attempts=10
-          url="http://localhost:8080/openapi.json"
-          for attempt in $(seq 1 $max_attempts); do
-            echo "Attempt #$attempt to download $url..."
-            if wget -O openapi.json "$url"; then
-              echo "Successfully downloaded $url"
-              break
-            else
-              echo "Failed to download $url. Waiting for 5 seconds before retry..."
-              sleep 5
-            fi
-          done
+        sleep 5
+        max_attempts=10
+        url="http://localhost:8080/openapi.json"
+        for attempt in $(seq 1 $max_attempts); do
+          echo "Attempt #$attempt to download $url..."
+          if wget -O openapi.json "$url"; then
+            echo "Successfully downloaded $url"
+            break
+          else
+            echo "Failed to download $url. Waiting for 5 seconds before retry..."
+            sleep 5
+          fi
+        done
 
     - name: Publish to Cloudflare Pages
+      if: github.ref == 'refs/heads/main'
       uses: cloudflare/pages-action@v1
       with:
         apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
         accountId: eb79f13320db531d8cf1f3720966b695
         projectName: doc-websoft9-com
         directory: build
-        # Optional: Enable this if you want to have GitHub Deployments triggered
         gitHubToken: ${{ secrets.GITHUB_TOKEN }}
-        # Optional: Switch what branch you are publishing to.
-        # By default this will be the branch which triggered this workflow
-        # branch: dev

.github/workflows/check.yml

@@ -1,30 +1,45 @@
-# ProxyCheck: Read dockerhub proxy URL from docs/reference/_include/dockerhub-proxy.md and test the network speed
-# Spellcheck
+# 文档质量检查工作流
+# - push 到 dev 分支时触发
+# - 向 dev 分支提 PR 时触发（作为合并前的强制质量门）
+# 功能：使用 lychee 检查文档中的 broken links，结果输出为 artifact
 
 name: Check Action
 
-on: 
+on:
   workflow_dispatch:
   push:
     branches:
       - dev
-      
+  pull_request:
+    branches:
+      - dev
+
 jobs:
+  broken-links:
+    name: Broken Links Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check broken links
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --verbose
+            --no-progress
+            --exclude-path node_modules
+            --exclude-path build
+            versioned_docs/
+            i18n/
+          fail: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-  # Spellcheck:
-  #   name: Spellcheck
-  #   runs-on: ubuntu-latest
-  #   steps:
-  #   - uses: actions/checkout@v3
-  #   - uses: rojopolis/spellcheck-github-actions@0.41.0
-  #     name: Spellcheck
-  #     with:
-  #       source_files: i18n/en/docusaurus-plugin-content-docs/current/**/*.md
-  #       task_name: Markdown
-  #       output_file: spellcheck-output.txt
+      - name: Upload lychee results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: lychee-report
+          path: lychee/out.md
+          retention-days: 7
 
-  #   - uses: actions/upload-artifact@v3
-  #     if: '!cancelled()' # Do not upload artifact if job was cancelled
-  #     with:
-  #       name: Spellcheck Output
-  #       path: spellcheck-output.txt

.github/workflows/json2md.yml

@@ -1,28 +1,34 @@
+# 从制品文件生成 App 应用目录列表 Markdown。
+# 触发方式：手动触发 或 repository_dispatch（事件名: applist_dev_event）。
+# repository_dispatch 由 Websoft9 主仓库 release 时自动触发。
+
 name: Generate Apps list for docs
 
 on:
   workflow_dispatch:
   repository_dispatch:
     types: [applist_dev_event]
-    
+
 jobs:
   build:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
 
       - name: Setup Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
           python-version: "3.x"
+          cache: 'pip'
 
       - name: Install unzip utility
         run: sudo apt-get install unzip
 
       - name: Download and unzip JSON files
         run: |
-          curl -L -o media-latest.zip https://artifact.websoft9.com/release/websoft9/plugin/media/media-latest.zip
+          curl -L --retry 3 --retry-delay 5 --retry-connrefused --fail \
+            -o media-latest.zip https://artifact.websoft9.com/release/websoft9/plugin/media/media-latest.zip
           unzip media-latest.zip "media/json/product_zh.json" "media/json/product_en.json" "media/json/catalog_zh.json" "media/json/catalog_en.json" -d ./extracted
 
       - name: Generate Markdown for app catalog README.mdx(zh)
@@ -53,3 +59,4 @@ jobs:
         uses: stefanzweifel/git-auto-commit-action@v4
         with:
           commit_message: Update Product Catalog Markdown
+

.github/workflows/update.yml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Install dependencies
         run: |

.lycheeignore

@@ -0,0 +1,19 @@
+# lychee broken-links 检查排除规则
+# 以下 pattern 匹配的链接将不被检查
+
+# 本地开发地址
+localhost
+127.0.0.1
+
+# CDN 图片域名（外网请求不稳定，大量图片链接）
+libs.websoft9.com
+
+# Algolia 搜索相关（动态 URL 中出现的 appId 和 indexName）
+NA4GDUSQ4H
+support-websoft9
+
+# 内部支持站点
+support.websoft9.com
+
+# 文档模板占位链接
+example.com

CHANGELOG.md

@@ -1,2 +1,37 @@
-# 开发日志
+# Changelog
+
+本文件记录本项目的所有重要变更，遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/) 规范。
+
+版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+---
+
+## [Unreleased]
+
+### Added
+
+- 新增 `CONTRIBUTING.md` 贡献指南（由 `developer.md` 重命名并全面重写），包含分支策略、PR 规范、i18n 说明、文档原则和常见问题
+- 新增 `DEVELOPMENT.md` 开发手册，包含环境配置、本地开发命令、模板系统说明、CI/CD 工作流说明、BMAD Quick Flow 使用指南和 App 文档创建标准流程
+- 新增 `template/docs/zh/app.md` Quick Flow 专用 App 文档 Prompt 模板
+- 新增 `.lycheeignore` broken-links 检查排除规则文件
+
+### Changed
+
+- `README.md` 全面重写：新增 CI badge、Tech Stack badge、快速开始、项目结构和文档链接
+- `docs/readme.md` 更新为 next 版本说明
+- `build_doc.yml`：升级 `checkout@master` → `@v4`，新增 yarn cache、concurrency 控制，删除调试步骤，修复 Docker 缩进，区分 dev/main 分支部署行为，apidocs 步骤设为 `continue-on-error: true`，新增 `pull_request` 触发（PR 构建质量门）
+- `check.yml`：全量重写，恢复 broken-links 检查（`lychee-action@v2`），新增 PR 触发
+- `app_from_contentful.yml`：升级 `checkout@v2` → `@v4`、`setup-python@v2` → `@v5`，新增 pip cache，移除 `--override` 参数
+- `json2md.yml`：升级 `checkout@v2` → `@v4`、`setup-python@v2` → `@v5`，新增 pip cache，curl 新增重试参数
+- `update.yml`：升级 `checkout@v2` → `@v4`
+
+### Removed
+
+- 删除 `Notes.md`（内容已迁移至 `CONTRIBUTING.md`）
+- 删除 `add_apps.md`（纯占位文件）
+
+---
+
+<!-- 版本链接占位 -->
+[Unreleased]: https://github.com/Websoft9/doc.websoft9.com/compare/HEAD...HEAD