mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-09-26 12:23:18 +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 正确。
135 lines
4.1 KiB
YAML
135 lines
4.1 KiB
YAML
# HomeAgent 插件 SDK 文档站配置。
|
||
#
|
||
# 设计取舍：
|
||
# - 每页顶部都放「版本 + 编辑链接」，因为 SDK 与内核的协议版本会错配，
|
||
# 读者必须先能确认自己看的是哪一版。
|
||
# - 中文检索依赖 jieba（已装）；英文走内置分词。两者都不要额外服务。
|
||
# - docs/api/*.md 是**生成物**（tools/apidoc/gensite），页首会写明，防止手改。
|
||
|
||
site_name: HomeAgent 插件 SDK
|
||
site_description: 用 Go 或 Lua 为 HomeAgent 编写插件 —— API 参考与开发指南
|
||
site_url: https://sdk.homeagent.jianfgit.xyz/
|
||
copyright: MIT 许可 · JianFeeeee
|
||
|
||
# 主题覆盖目录：只覆盖 footer.html（补备案号，见该文件里的说明）。
|
||
docs_dir: docs
|
||
site_dir: site_build
|
||
|
||
theme:
|
||
name: material
|
||
language: zh
|
||
# custom_dir 必须写在 theme 下（顶层会被判为未知配置）。
|
||
custom_dir: overrides
|
||
# 品牌图标：与主站 introduce 同一份 logo（曾用 Material 默认，不是我们的）。
|
||
logo: assets/logo-mark.svg
|
||
favicon: assets/logo.svg
|
||
features:
|
||
- navigation.instant
|
||
- navigation.instant.progress
|
||
- navigation.tracking
|
||
- navigation.tabs
|
||
- navigation.sections
|
||
- navigation.indexes
|
||
- navigation.top
|
||
- toc.follow
|
||
- search.suggest
|
||
- search.highlight
|
||
- search.share
|
||
- content.code.copy
|
||
- content.code.annotate
|
||
- content.action.edit
|
||
palette:
|
||
- media: "(prefers-color-scheme: light)"
|
||
scheme: default
|
||
primary: indigo
|
||
accent: indigo
|
||
toggle:
|
||
icon: material/weather-night
|
||
name: 切换到深色
|
||
- media: "(prefers-color-scheme: dark)"
|
||
scheme: slate
|
||
primary: indigo
|
||
accent: indigo
|
||
toggle:
|
||
icon: material/weather-sunny
|
||
name: 切换到浅色
|
||
icon:
|
||
repo: fontawesome/brands/git-alt
|
||
|
||
plugins:
|
||
- search:
|
||
lang:
|
||
- zh
|
||
- en
|
||
separator: '[\s\u200b\-]'
|
||
# 中文按词切（jieba），否则整句变一个 token，检索不到。
|
||
jieba_dict: null
|
||
|
||
markdown_extensions:
|
||
- admonition
|
||
- attr_list
|
||
- def_list
|
||
- footnotes
|
||
- md_in_html
|
||
- tables
|
||
- toc:
|
||
permalink: true
|
||
toc_depth: 3
|
||
- pymdownx.details
|
||
# Material 的图标语法 :material-xxx: / :octicons-xxx: 依赖这个扩展。
|
||
# 没开时它们会**原样显示为文本**（实测首页四个卡片全花了）。
|
||
- pymdownx.emoji:
|
||
emoji_index: !!python/name:material.extensions.emoji.twemoji
|
||
emoji_generator: !!python/name:material.extensions.emoji.to_svg
|
||
- pymdownx.highlight:
|
||
anchor_linenums: true
|
||
- pymdownx.inlinehilite
|
||
- pymdownx.snippets
|
||
- pymdownx.superfences
|
||
- pymdownx.tabbed:
|
||
alternate_style: true
|
||
|
||
extra:
|
||
generator: false
|
||
social:
|
||
- icon: fontawesome/solid/code
|
||
link: https://gitcode.com/JianFeeeee/homeagent-sdk
|
||
name: SDK 源码
|
||
# 自定义检索端点在 docs/javascripts/api-search.js 里注册，
|
||
# 索引文件由 gensite 产出：docs/assets/api-index.json
|
||
|
||
nav:
|
||
- 首页: index.md
|
||
- 快速开始:
|
||
- 环境与工具链: guide/getting-started.md
|
||
- 第一个 Go 插件: guide/first-plugin.md
|
||
- 第一个 Lua 插件: guide/first-lua-plugin.md
|
||
- API 参考:
|
||
- api/index.md
|
||
- 工具（Tools）: api/tools.md
|
||
- 阶段钩子（Stages）: api/stages.md
|
||
- 记忆（Memory）: api/memory.md
|
||
- 输入/输出通道: api/channels.md
|
||
- 配置（Settings）: api/settings.md
|
||
- 生命周期（Lifecycle）: api/lifecycle.md
|
||
- 事件（Events）: api/events.md
|
||
- LLM 调用: api/llm.md
|
||
- 常量与枚举: api/constants.md
|
||
- 桥接装配点: api/bridge.md
|
||
- 其他类型: api/misc.md
|
||
- 仅内置插件可用: api/builtin-only.md
|
||
- 指南:
|
||
- 能力边界（哪些 API 外部可用）: guide/capability-boundary.md
|
||
- 打包与发布: guide/packaging.md
|
||
- 多平台构建: guide/multi-platform.md
|
||
- 受限 SDK 与安全: guide/security.md
|
||
- 示例插件:
|
||
- 总览: examples/index.md
|
||
- 版本与兼容: versions.md
|
||
|
||
extra_css:
|
||
- stylesheets/extra.css
|
||
|
||
extra_javascript:
|
||
- javascripts/api-search.js
|