From c7e5d2a446c97a6ecd2bd3825ec8dface551a66c Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Tue, 29 Sep 2026 20:43:27 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E8=A1=A5=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E7=AB=99=E5=85=A5=E5=8F=A3=EF=BC=8C=E5=B9=B6=E6=8A=8A=E3=80=8C?= =?UTF-8?q?SDK=20=E6=BA=90=E7=A0=81=E3=80=8D=E9=93=BE=E6=8E=A5=E8=BF=81?= =?UTF-8?q?=E5=88=B0=20GitHub?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SDK 仓此前**没有任何地方指向文档站** —— README 不写、GitHub 仓的 homepage 字段也是空的，于是从仓首页根本走不到 sdk.homeagent.jianfgit.xyz。 文档站本身一直在线（106 个文件的 mkdocs 产物），只是没人从仓里指过去。 本次补上： - README.md / README_EN.md 顶部加文档站入口（快速开始 / API 参考 / 能力边界 / llms.txt + llms-full.txt 的 agent 直读入口），并在末尾加「文档」章节 列出全部页面的直链。 - mkdocs.yml 的社交链接由 gitcode 改指 GitHub，并**新增** gitcode 镜像入口与 介绍站入口（国内直连 gitcode 更快，海外/权威源看 GitHub，两个都留）。 - docs/guide/getting-started.md 的 `git clone` 地址改为 GitHub 仓名 （homeagentsdk），并写明「release 附件暂时仍在 gitcode」这个事实。 ★ 刻意**不**改的东西：Go 模块路径 `gitcode.com/JianFeeeee/homeagent-sdk`。 改模块路径会让所有现有插件的 go.mod 全面失效，属于破坏性变更， 与「仓库托管位置迁移」是两件事。 关于 GitHub 侧没有 release 条目（因此不能写 releases/latest/download/...， 那会 404）：已在 README 里如实写明 —— 二进制目前只在 gitcode 的 release 附件里， GitHub 从下一个 SDK 版本（v1.4.0）起才会同步发布。 验证：两份 README 里 28 个 URL 全部实测 200；文档站重建（106 文件）并部署， 线上 `git clone` 已是 GitHub 地址、旧 gitcode clone 地址 0 次、 三个社交入口名称正确。 --- README.md | 36 ++++++++++++++++++++++++++++++++--- README_EN.md | 10 ++++++++++ docs/guide/getting-started.md | 12 +++++++++--- mkdocs.yml | 10 +++++++++- 4 files changed, 61 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index ed50194..70915f0 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,15 @@ HomeAgent 插件开发 SDK，用于构建与 HomeAgent 平台交互的智能插件。 +> 📖 **完整文档**： +> +> 快速开始 / API 参考 / 指南 / 示例插件都在那里，**本 README 只是速览**， +> 接口细节以文档站为准。直接进入：[快速开始](https://sdk.homeagent.jianfgit.xyz/guide/getting-started/) +> · [API 参考](https://sdk.homeagent.jianfgit.xyz/api/) · [能力边界](https://sdk.homeagent.jianfgit.xyz/guide/capability-boundary/) +> +> 面向 agent 的纯文本入口：[`llms.txt`](https://sdk.homeagent.jianfgit.xyz/llms.txt) +> （含全部 API 的 [`llms-full.txt`](https://sdk.homeagent.jianfgit.xyz/llms-full.txt)）。 + ## 版本与兼容性 当前：**SDK 1.3.0**（需内核 **1.3.0+**）。 @@ -337,15 +346,23 @@ func New(name string, sett SettingsAPI, regTool ToolRegistrar, regStage StageReg ## hmapdev 工具链 `hmapdev` 提供插件开发全流程支持，最终产出 `.hmap` 插件包（工具名即来自该包格式）。 -预编译二进制作为 **release 附件**分发（linux/darwin/windows × amd64/arm64），从 -[Releases](https://gitcode.com/JianFeeeee/homeagent-sdk/releases) 下载后加入 PATH 即可： +预编译二进制作为 **release 附件**分发（linux/darwin/windows × amd64/arm64）， +下载后加入 PATH 即可： + +> ⚠️ **二进制的实际分发地址目前是 gitcode**（两个仓的 release 附件不同步）： +> `hmapdev_linux_amd64` 等 5 个平台二进制 + `SHA256SUMS` 在 +> 。 +> GitHub 侧（）从 +> 下一个 SDK 版本（v1.4.0）起才会同步发布 —— 因为 SDK 仓**移仓后还没发过版**。 +> 源码与文档一律以 GitHub 为准，**只有二进制暂时还得到 gitcode 取**。 > 改名说明：工具链原名 `plugindev`，自 1.2.0 起更名 `hmapdev`。 > SDK 存储目录同时由 `~/.homeagent/plugindev/sdk` 迁到 `~/.homeagent/hmapdev/sdk` > （旧目录会被自动沿用，不会丢已装版本）。 ```bash -# 从 release 附件下载（以最新 SDK 发布 / linux amd64 为例） +# 从 release 附件下载（以 linux amd64 为例，<版本> 如 v1.3.0） +# 当前实际分发地址是 gitcode（见下方说明）： curl -Lo hmapdev https://gitcode.com/JianFeeeee/homeagent-sdk/releases/download/<版本>/hmapdev_linux_amd64 chmod +x hmapdev @@ -956,6 +973,19 @@ curl -X POST http://127.0.0.1:9876/plugins \ 或通过 WebUI 插件管理页面上传，也可手动将 `.hmap` 放入插件目录后重启平台。 +## 文档 + +- 文档站：**** +- 快速开始：[环境与工具链](https://sdk.homeagent.jianfgit.xyz/guide/getting-started/) · [第一个 Go 插件](https://sdk.homeagent.jianfgit.xyz/guide/first-plugin/) · [第一个 Lua 插件](https://sdk.homeagent.jianfgit.xyz/guide/first-lua-plugin/) +- API 参考：[总览](https://sdk.homeagent.jianfgit.xyz/api/) · [工具](https://sdk.homeagent.jianfgit.xyz/api/tools/) · [阶段钩子](https://sdk.homeagent.jianfgit.xyz/api/stages/) · [记忆](https://sdk.homeagent.jianfgit.xyz/api/memory/) · [输入/输出通道](https://sdk.homeagent.jianfgit.xyz/api/channels/) +- 指南：[能力边界（哪些 API 外部可用）](https://sdk.homeagent.jianfgit.xyz/guide/capability-boundary/) · [工具并发声明](https://sdk.homeagent.jianfgit.xyz/guide/parallel-tool-declaration/) · [流式多 tool_call](https://sdk.homeagent.jianfgit.xyz/guide/stream-tool-call-index/) · [场景记忆](https://sdk.homeagent.jianfgit.xyz/guide/scene-memory/) · [打包与发布](https://sdk.homeagent.jianfgit.xyz/guide/packaging/) +- 版本与兼容： +- 核心仓（内核 / 记忆 / 调度）： +- 介绍站： + +> 文档站为自托管（国内直连，不必挂代理）。构建与部署见核心仓的 +> `deploy-sdk-site.sh`（`--check` 只比对、`--rollback` 回滚）。 + ## 许可 SDK 以 **MIT** 发布，全文见 [LICENSE](LICENSE)。 diff --git a/README_EN.md b/README_EN.md index 32f9bd9..bd5e3d4 100644 --- a/README_EN.md +++ b/README_EN.md @@ -2,6 +2,16 @@ Plugin development SDK for building intelligent plugins that interact with the HomeAgent platform. +> 📖 **Full documentation**: +> +> Quick start / API reference / guides / example plugins all live there. **This README is a +> summary only** — the docs site is authoritative for interface details. +> Jump to: [Getting started](https://sdk.homeagent.jianfgit.xyz/guide/getting-started/) +> · [API reference](https://sdk.homeagent.jianfgit.xyz/api/) · [Capability boundary](https://sdk.homeagent.jianfgit.xyz/guide/capability-boundary/) +> +> Agent-friendly plain-text entry points: [`llms.txt`](https://sdk.homeagent.jianfgit.xyz/llms.txt) +> and [`llms-full.txt`](https://sdk.homeagent.jianfgit.xyz/llms-full.txt) (the whole docs in one file). + ## Version and Compatibility Current: **SDK 1.3.0** (requires kernel **1.3.0+**). diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index d2c27d7..a45f39a 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -13,13 +13,19 @@ 从源码构建： ```bash -git clone https://gitcode.com/JianFeeeee/homeagent-sdk -cd homeagent-sdk/tools/hmapdev +git clone https://github.com/JianFeeeee/homeagentsdk +cd homeagentsdk/tools/hmapdev go build -o hmapdev # 把 hmapdev 放进 PATH，或直接用 ./hmapdev ``` -也可以从 SDK 的 release 附件下载预编译二进制（`hmapdev_linux_amd64` 等）。 +也可以从 SDK 的 release 附件下载预编译二进制（`hmapdev_linux_amd64` 等， +共 5 个平台：linux/darwin/windows × amd64/arm64）。 + +> 仓已迁到 GitHub；gitcode 仅作国内镜像（源码同步，**release 附件暂时仍在那里**）： +> `https://gitcode.com/JianFeeeee/homeagent-sdk/releases`。 +> Go 模块路径仍是 `gitcode.com/JianFeeeee/homeagent-sdk` —— 这是有意保留的， +> 改模块路径会让现有插件的 `go.mod` 全面失效。 ## SDK 版本管理 diff --git a/mkdocs.yml b/mkdocs.yml index bff39eb..2061db8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -92,9 +92,17 @@ markdown_extensions: extra: generator: false social: + # 主仓已迁到 GitHub；gitcode 保留为国内镜像（源码同步）。 + # 两个链接都放，是因为国内直连 gitcode 更快，而海外/权威源看 GitHub。 - icon: fontawesome/solid/code + link: https://github.com/JianFeeeee/homeagentsdk + name: SDK 源码（GitHub） + - icon: fontawesome/solid/code-branch link: https://gitcode.com/JianFeeeee/homeagent-sdk - name: SDK 源码 + name: gitcode 镜像（国内） + - icon: fontawesome/solid/house + link: https://introduce.homeagent.jianfgit.xyz/ + name: HomeAgent 介绍站 # 自定义检索端点在 docs/javascripts/api-search.js 里注册， # 索引文件由 gensite 产出：docs/assets/api-index.json