Merge pull request #215 from GeWuYou/docs/vitepress-site-config

docs: 添加文档站点配置和开发环境说明

.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

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: {

docs/zh-CN/contributor/development-environment.md

@@ -86,6 +86,27 @@ 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 协作实际该用什么”。
@@ -93,4 +114,4 @@ python3 scripts/generate-ai-environment.py
     - 当前仓库构建、测试、文档或验证直接依赖它
     - AI 在当前仓库中会高频使用，且能明显提升效率
     - 新贡献者配置当前仓库开发环境时确实需要知道它
-- 不满足上述条件的工具，不写入文档，也不写入 `.ai/environment/tools.raw.yaml` / `.ai/environment/tools.ai.yaml`。
+- 不满足上述条件的工具，不写入文档，也不写入 `.ai/environment/tools.raw.yaml` / `.ai/environment/tools.ai.yaml`。