mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-10-01 06:43:18 +00:00
82e8d9dbac
`ParallelSafe` / `Serial` / `stream_index` 三个新能力此前**零文档**： README 提到 `Serial` 的那处是 UART 串口，与并发声明无关。插件作者只能 读源码注释才能知道这些字段存在及其优先级。 ## docs/guide/parallel-tool-declaration.md - 保守 opt-in 的理由：存量插件不改一行就得串行，不会被升级意外并发 - 声明 `ParallelSafe` 的三个条件（线程安全 / 不争抢资源 / 顺序无关） - `Serial` 存在的意义：让"我确认过**必须**串行"与"我没想过"可区分 - **`Serial` 胜出**，不允许被 `ParallelSafe` 或默认值覆盖 - 声明字段放在 `ToolDef` 末尾，遵循既有 `NoMemory` 风格 - 压测效果 N=2/4/8 → 1.41×/2.22×/3.88×，并附"必须同时统计实际执行数" 的理由（旧适配器耗时更短但实际处理 0 个工具） ## docs/guide/stream-tool-call-index.md 面向写 Lua 适配器的人： - 上游 `index` 字段的用途：分桶累积 `id`/`name`/`arguments` - **键名是 `stream_index` 不是 `index`** —— 写错会被 Go 解码器静默丢弃 - 不透传的实际后果：name 互相覆盖、args 碎片混拼、工具被当空参数调用 - 顺带记两个易踩点：不能按 name 过滤分片；扁平结构的协议族同样要带 - 自检命令；并注明 `gemini.lua` 不涉及（协议是 `functionCall`） ## 其它 - `mkdocs.yml` nav 登记两篇 —— 之前它们会被 mkdocs 明确警告 "not included in the nav configuration"，等于在站点里不可达 - 重跑 `tools/apidoc/build.sh` 同步 `docs/api/*`、`llms.txt`（生成物） 核实过的事实，避免臆造： - 内置工具声明是**核心仓**的 `toolDefOptions`/`parallelOpts()` （`internal/agent/core/tooldefs.go`），不是 `sdk.BuiltinToolDef` —— 初稿写错 - `gemini.lua` 对 `functionCall|tool_calls` 匹配数为 0，确认无流式实现 - `server/kimicode/anthropic/ollama` 四个适配器确有 `stream_index`（2~5 处） - 跨仓相对链接不可解析，故改为纯文本路径指路 `docs/api/tools.md` 属生成物（首行注明"请勿手改"），其 `ToolDef` 签名被截断、 不展示字段 —— 这是生成器既有行为，本次 diff 只是行号漂移，未改它。
138 lines
4.3 KiB
YAML
138 lines
4.3 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
|
||
- 工具并发声明（ParallelSafe/Serial）: guide/parallel-tool-declaration.md
|
||
- 流式多 tool_call（适配器透传 index）: guide/stream-tool-call-index.md
|
||
- 场景记忆（按场合召回）: guide/scene-memory.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
|