From 7ddf82877eae6a5135c7060a631b746b4f14c9d2 Mon Sep 17 00:00:00 2001 From: GeWuYou <95328647+GeWuYou@users.noreply.github.com> Date: Mon, 13 Apr 2026 23:00:29 +0800 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E7=AB=99=E7=82=B9=E9=85=8D=E7=BD=AE=E5=92=8C=E5=BC=80?= =?UTF-8?q?=E5=8F=91=E7=8E=AF=E5=A2=83=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 配置 GitHub Pages 部署工作流，添加 Configure GitHub Pages 步骤 - 集成 demodrive-ai/llms-txt-action 生成 LLM 可读索引文件 - 添加 sitemap.xml 生成和 LLM 产物验证机制 - 创建完整的 VitePress 中文文档配置文件 - 添加开发环境能力清单和 AI 使用约定 - 配置多语言导航和侧边栏结构 - 设置搜索、页脚和社会链接等 UI 组件 --- .github/workflows/publish-docs.yml | 25 +++++++++++++++++- docs/.vitepress/config.mts | 7 +++++ .../contributor/development-environment.md | 26 +++++++++++++++++++ 3 files changed, 57 insertions(+), 1 deletion(-) diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index 9f6c1ca2..feda2bf6 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -50,6 +50,10 @@ jobs: - name: Checkout uses: actions/checkout@v6 + # 按 GitHub Pages 官方流程初始化部署元数据。 + - name: Configure GitHub Pages + uses: actions/configure-pages@v5 + # 安装 Bun 运行时 - name: Setup Bun uses: oven-sh/setup-bun@v2 @@ -70,7 +74,26 @@ jobs: - name: Make docs LLM ready uses: demodrive-ai/llms-txt-action@v1 with: - docs_dir: docs/.vitepress/dist + docs_dir: docs/.vitepress/dist + sitemap_path: sitemap.xml + skip_llms_txt: 'false' + skip_llms_full_txt: 'false' + skip_md_files: 'false' + + # 在上传前校验 LLM 索引产物，避免部署出“步骤成功但文件缺失”的 Pages 站点。 + - name: Verify LLM artifacts + run: | + test -f docs/.vitepress/dist/sitemap.xml + test -f docs/.vitepress/dist/llms.txt + test -f docs/.vitepress/dist/llms-full.txt + + md_count="$(find docs/.vitepress/dist -type f -name '*.md' | wc -l)" + if [ "$md_count" -eq 0 ]; then + echo "Expected llms-txt-action to generate page-level markdown files, but none were found." + exit 1 + fi + + echo "Generated $md_count markdown files for LLM ingestion." # 上传构建产物作为 Pages 部署工件 - name: Upload Pages Artifact diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index b27b9445..3b93e141 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -76,6 +76,13 @@ export default defineConfig({ ], /** GitHub Pages / 子路径部署 */ base: '/GFramework/', + /** + * 为 GitHub Pages 产物生成稳定的绝对 URL。 + * llms-txt-action 依赖 sitemap.xml 发现站点页面，因此 hostname 需要与最终 Pages 地址对齐。 + */ + sitemap: { + hostname: 'https://gewuyou.github.io/GFramework/' + }, vite: { plugins: [safeGenericEscapePlugin()], build: { diff --git a/docs/zh-CN/contributor/development-environment.md b/docs/zh-CN/contributor/development-environment.md index 99962af3..6ef058ac 100644 --- a/docs/zh-CN/contributor/development-environment.md +++ b/docs/zh-CN/contributor/development-environment.md @@ -86,6 +86,32 @@ bash scripts/collect-dev-environment.sh --write python3 scripts/generate-ai-environment.py ``` +## 文档站 LLM 索引接入说明 + +### 访问路径 + +LLM 索引文件与文档站一起部署在 GitHub Pages，遵循 `docs/.vitepress/config.mts` 里 `base: '/GFramework/'` 的路径规则。部署之后可以直接访问 +`https://gewuyou.github.io/GFramework/llms.txt` 和 `https://gewuyou.github.io/GFramework/llms-full.txt`。这些文件最终会被写入 ` +docs/.vitepress/dist/`，但生成动作发生在 `publish-docs` workflow 的 `demodrive-ai/llms-txt-action` 步骤，而不是单独执行 ` +bun run build` 时直接产出。 + +### 生成时机与依赖 + +`demodrive-ai/llms-txt-action` 负责把文档站打包后的页面转换成 LLM 索引，它的 `docs_dir` 已指定为 `docs/.vitepress/dist` +，并通过 `sitemap.xml` 解析页面 URL。只能在 `bun run build` 之后（即 VitePress 将页面输出到 `dist` 并生成 `sitemap.xml` +）执行；如果没有 sitemap，action 会得不到页面列表，生成的 `llms.txt` 就会不完整。 + +### 验证流程 + +1. 本地执行 `bun run build`，确认 `docs/.vitepress/dist/sitemap.xml` 已生成，并检查其中的 URL 是否与 GitHub Pages + 地址一致。添加或删除文档页面后必须重新运行一次全量构建。 +2. 在 Pull Request 或发布前查看 `publish-docs` workflow 日志，确认 `Verify LLM artifacts` 步骤通过，并检查 + `docs/.vitepress/dist/llms.txt`、`docs/.vitepress/dist/llms-full.txt` 已作为 Pages artifact 上传。 +3. 部署完成后通过 GitHub Pages 打开 `https://gewuyou.github.io/GFramework/llms.txt` + 和 `https://gewuyou.github.io/GFramework/llms-full.txt`，确认可访问且内容覆盖最新页面。 +4. 如果后续需要对 LLM 索引行为做变更，优先思考是否影响 `sitemap` 结构或 `docs_dir` 路径；失效通常表现为 `llms` + 文件缺失、内容为空，或链接仍指向旧页面。 + ## 维护规则 - 目标不是记录“这台机器装了什么”，而是记录“GFramework 开发和 AI 协作实际该用什么”。 From 12022d661a82e470b370a2dc218f34314c1b038b Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Mon, 13 Apr 2026 15:12:33 +0000 Subject: [PATCH 2/2] fix: apply CodeRabbit auto-fixes Fixed 1 file(s) based on 2 unresolved review comments. Co-authored-by: CodeRabbit --- docs/zh-CN/contributor/development-environment.md | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/docs/zh-CN/contributor/development-environment.md b/docs/zh-CN/contributor/development-environment.md index 6ef058ac..69f77bc6 100644 --- a/docs/zh-CN/contributor/development-environment.md +++ b/docs/zh-CN/contributor/development-environment.md @@ -90,16 +90,11 @@ python3 scripts/generate-ai-environment.py ### 访问路径 -LLM 索引文件与文档站一起部署在 GitHub Pages，遵循 `docs/.vitepress/config.mts` 里 `base: '/GFramework/'` 的路径规则。部署之后可以直接访问 -`https://gewuyou.github.io/GFramework/llms.txt` 和 `https://gewuyou.github.io/GFramework/llms-full.txt`。这些文件最终会被写入 ` -docs/.vitepress/dist/`，但生成动作发生在 `publish-docs` workflow 的 `demodrive-ai/llms-txt-action` 步骤，而不是单独执行 ` -bun run build` 时直接产出。 +LLM 索引文件与文档站一起部署在 GitHub Pages，遵循 `docs/.vitepress/config.mts` 里 `base: '/GFramework/'` 的路径规则。部署之后可以直接访问 `https://gewuyou.github.io/GFramework/llms.txt` 和 `https://gewuyou.github.io/GFramework/llms-full.txt`。这些文件最终会被写入 `docs/.vitepress/dist/`，但生成动作发生在 `publish-docs` workflow 的 `demodrive-ai/llms-txt-action` 步骤，而不是单独执行 `bun run build` 时直接产出。 ### 生成时机与依赖 -`demodrive-ai/llms-txt-action` 负责把文档站打包后的页面转换成 LLM 索引，它的 `docs_dir` 已指定为 `docs/.vitepress/dist` -，并通过 `sitemap.xml` 解析页面 URL。只能在 `bun run build` 之后（即 VitePress 将页面输出到 `dist` 并生成 `sitemap.xml` -）执行；如果没有 sitemap，action 会得不到页面列表，生成的 `llms.txt` 就会不完整。 +`demodrive-ai/llms-txt-action` 负责把文档站打包后的页面转换成 LLM 索引，它的 `docs_dir` 已指定为 `docs/.vitepress/dist`，并通过 `sitemap.xml` 解析页面 URL。只能在 `bun run build` 之后（即 VitePress 将页面输出到 `dist` 并生成 `sitemap.xml`）执行；如果没有 sitemap，action 会得不到页面列表，生成的 `llms.txt` 就会不完整。 ### 验证流程 @@ -119,4 +114,4 @@ bun run build` 时直接产出。 - 当前仓库构建、测试、文档或验证直接依赖它 - AI 在当前仓库中会高频使用，且能明显提升效率 - 新贡献者配置当前仓库开发环境时确实需要知道它 -- 不满足上述条件的工具，不写入文档，也不写入 `.ai/environment/tools.raw.yaml` / `.ai/environment/tools.ai.yaml`。 +- 不满足上述条件的工具，不写入文档，也不写入 `.ai/environment/tools.raw.yaml` / `.ai/environment/tools.ai.yaml`。 \ No newline at end of file