mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-10-02 15:14:37 +00:00
255d6479ad
三件事，都是「站点上线后看出来的」问题。 ## ① 图标用的是 Material 默认，不是我们的 站上 favicon 是 mkdocs-material 自带的那张（`assets/images/favicon.png`）， 与主站 introduce 不一致。改为引入主站同一份 logo： - `docs/assets/logo.svg` —— 原样（浅色底，适合 favicon） - `docs/assets/logo-mark.svg` —— 去掉底色矩形（否则在靛蓝页头上是个白方块） `theme.favicon` / `theme.logo` 分别指向它们。实测子页面路径也正确 （mkdocs 生成 `../../assets/logo.svg`，不是错误的相对路径）。 ## ② 缺备案号 `introduce` 底部有 ICP + 公安备案，文档站没有。Material 的 footer 只渲染 `config.copyright` 一个字符串，塞不进「两条带链接的备案」——所以覆盖了 `overrides/partials/footer.html`（`theme.custom_dir`），并顺带把许可也写进底部， 读者在任何一页都能看到，不必翻到首页。 ## ③ 没有给 agent 的入口 站点是给人看的（HTML + 主题 + JS 搜索），但越来越多读者是 agent。让它们爬 HTML 既浪费 token（样板占大头）又容易漏内容。 新增 `tools/apidoc/gensite/agent.go`，随构建产出： | 路径 | 内容 | |---|---| | `/llms.txt` | 站点目录：每页一行，带 URL 与一句话说明（4.3KB）| | `/llms-full.txt` | 全部文档正文拼成一份，可一次读完（115KB）| | `/<page>.md` | 每个页面的 Markdown 原文，含生成的 API 页（text/markdown）| 沿用 llms.txt 社区约定：`llms.txt` 读目录、`llms-full.txt` 一次读全。 **一个必须处理的坑**：mkdocs 只把 `.md` **渲染**成 HTML，不会把 Markdown 放进产物目录 —— 那样 `llms.txt` 里的链接会全部 404。所以 `build.sh` 增加了 第 4 步 `copy_agent_files`，在构建后把 23 个 Markdown 复制进 `site_build/`。 `docs/llms-full.txt` 已 gitignore：它是派生件，改任何一页都会整份重写， 进版本库只产生噪声（`llms.txt` 索引小且稳定，仍提交）。 验证：`mkdocs build --strict` 零告警；favicon/logo 可取（200，naturalWidth=400）； 三页底部均含两个备案号；4 个 agent 入口均可访问且 content-type 正确。
63 lines
2.3 KiB
Bash
Executable File
63 lines
2.3 KiB
Bash
Executable File
#!/usr/bin/env bash
|
||
# 生成并构建插件 SDK 文档站。
|
||
#
|
||
# 四步：
|
||
# 1. apidoc —— 从 sdk/*.go 提取公开 API 面（签名/注释/分层）→ JSON
|
||
# 2. gensite —— 把 JSON 渲染成 docs/api/*.md + 检索索引 + llms.txt
|
||
# 3. mkdocs —— 构建静态站
|
||
# 4. copy_agent —— 把 Markdown 源搬进站点产物（mkdocs 只渲染 .md，不复制）
|
||
#
|
||
# 为什么要脚本而不是手敲：API 参考是**生成物**，必须与源码同步，
|
||
# 否则文档会悄悄过时（这是文档站最常见的死法）。
|
||
#
|
||
# 用法：
|
||
# tools/apidoc/build.sh # 生成 + 构建
|
||
# tools/apidoc/build.sh serve # 生成 + 本地预览（热重载）
|
||
set -euo pipefail
|
||
|
||
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
|
||
cd "$ROOT"
|
||
|
||
TMP_API="${TMPDIR:-/tmp}/homeagent-sdk-api.json"
|
||
SITE=site_build
|
||
|
||
# copy_agent_files 把 docs/ 下的 Markdown 原样复制进站点产物。
|
||
#
|
||
# 为什么必须复制：mkdocs 只把 .md **渲染**成 HTML，不会把它们放进产物目录。
|
||
# 但 agent 需要 Markdown 原文（省 token、不含主题样板），所以 llms.txt 里
|
||
# 指的 /api/tools.md 必须真实可访问。llms.txt 与 llms-full.txt 由 gensite 生成。
|
||
copy_agent_files() {
|
||
local n=0 rel dir
|
||
while IFS= read -r -d '' f; do
|
||
rel="${f#docs/}"
|
||
[ "${rel##*/}" = "README.md" ] && continue
|
||
dir="$(dirname "$rel")"
|
||
[ "$dir" != "." ] && mkdir -p "$SITE/$dir"
|
||
cp "$f" "$SITE/$rel"
|
||
n=$((n + 1))
|
||
done < <(find docs -name '*.md' -print0)
|
||
echo " 复制 $n 个 Markdown 到 $SITE/（供 agent 直读）"
|
||
}
|
||
|
||
echo "=== 1/4 提取 API 面 ==="
|
||
go run ./tools/apidoc -pkgdir ./sdk -out "$TMP_API"
|
||
|
||
echo "=== 2/4 渲染文档页、检索索引与 agent 入口 ==="
|
||
go run ./tools/apidoc/gensite -api "$TMP_API" -out ./docs -examples ./example
|
||
|
||
echo "=== 3/4 构建静态站 ==="
|
||
if [ "${1:-}" = "serve" ]; then
|
||
# 预览模式也要能取到 .md（agent 入口），故先构建一次再起服务。
|
||
mkdocs build --strict >/dev/null
|
||
copy_agent_files
|
||
exec mkdocs serve
|
||
fi
|
||
mkdocs build --strict
|
||
|
||
echo "=== 4/4 供 agent 直读的 Markdown ==="
|
||
copy_agent_files
|
||
|
||
echo
|
||
echo "完成。产物在 $SITE/，本地预览：tools/apidoc/build.sh serve"
|
||
echo "agent 入口：$SITE/llms.txt（目录）、$SITE/llms-full.txt（全文）"
|