mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-10-15 12:15:11 +00:00
b6a6168e65
SDK 仓已迁到 GitHub 作为权威源，go module 路径同步： `gitcode.com/JianFeeeee/homeagent-sdk` → `github.com/JianFeeeee/homeagentsdk` ## 范围 74 个文件：71 个 Go 源码 + go.mod/go.sum + hmapdev 模板 + CI 与打包脚本。 主仓（HomeAgent）侧对应改动是 6d38a164。本仓这些文件当时**不在工作树上** （见下），所以那次的批量替换扫不到它们——这里是补偿。 ## 为何这批文件当时不在工作树上（事故与恢复） 10-08 07:58 主仓做 checkout/cherry-pick 序列时，把本仓工作树的 20 个文件 误清理了（`example/*/plugin.go` + `plg.json`，10 个示例）。 根因是**结构误判**：本仓是「一目录两仓库」结构下主仓 `third_party/` 里的 **独立 git 仓库**，而主仓 .gitignore 忽略了 `example/`，于是它在主仓 `git status` 里不可见 —— 看着像「不受跟踪的构建产物」，实际是本仓受跟踪的源码。 已全部恢复（`git checkout -- <D 文件>`，只恢复删除、不动迁移改动）， 20 个文件与 HEAD 逐字节一致。 **破坏的连锁后果**：恢复出来的 `plugin.go` 仍写着旧 module 路径， 因为迁移时它们已不在工作树上。所以这次补偿是必须的，不是可选优化。 ## 保留 gitcode 引用 以下位置的 `gitcode` **有意保留**，不要"顺手清掉"： - README.md / docs 里「二进制实际分发地址目前是 gitcode」的说明 - mkdocs.yml 的 gitcode 镜像链接（国内直连更快） - `tools/hmapdev/templates.go` 里「SDK 已从 gitcode 迁到 GitHub」的注释 gitcode 仍是**只读镜像**（源码同步；release 附件暂时仍在那边）。 ## 验证 - 本仓根 module：`go build ./...` + `go test ./...` 全通过 - 全部 20 个 example：`go vet` 通过（补偿前 10 个因旧 module 路径失败） - example/qq：`go test` 通过，且能从源码 build 出可用 plugin 产物
sanitizer · 文本清洗
不注册任何工具，只挂三个阶段钩子，在 Agent 全链路上洗掉两类污染：
- 坏字节：坏 UTF-8、
U+FFFD（替换符）、ANSI 转义序列 - 思维泄漏：LLM 输出里残留的工具调用标记
为什么需要它
坏字节会被 LLM 复读。一次工具返回乱码（比如源码里带 ANSI 颜色码、或二进制片段被当文本读出来）， 这些字节会进上下文，之后模型每次生成都可能把它抄一遍 —— 越滚越脏。 在每个入口洗掉，比事后清理便宜得多。
思维泄漏则是另一种：模型有时把 <tool_call>...</tool_call> 这类内部标记直接写进正文，
用户就看到一堆不该出现的 XML。
挂载的三个阶段
| 阶段 | 处理对象 | 作用 |
|---|---|---|
on_input |
ctx.RawMessage |
洗用户输入，脏字节不进后续链路 |
after_toolcall |
ctx.ToolResults |
洗工具结果，坏字节不进 LLM 上下文 |
post_action |
ctx.LLMText |
洗模型输出：先清思维泄漏，再清乱码 |
每次有改动都打一行日志（cleaned N bytes），便于确认它真的在工作而不是静默失败。
识别哪些泄漏形态
按正则匹配多种标记写法，覆盖不同模型家族的习惯：
<tool_call>…</tool_call>、<invoke>…</invoke>、<tool>…</tool><function>…</function>- 上述标记包在
xml /json 代码块里的形态 - 中文括号变体：
【tool_call】…【/tool_call】
实现要点
- 依赖 ABI v2 的 stage 写回能力：插件对
StageContext的修改会同步回内核。 在 v1 上改了不生效。 - 读写
StageContext时按约定加ctx.Lock()。
构建
go build -buildmode=plugin -o sanitizer.so .
或经 hmapdev build 打包为 .hmap。