mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-09-23 10:28:06 +00:00
fix(site): 逐条对照源码修正描述（含两处真错误）
上一版有几处表述与源码不符。这轮把页面上每条可核验的说法都对着代码重新查一遍， 改掉 15 处，其中两处是**事实错误**而非措辞问题。 ## 事实错误 **① L4 的归属说反了（FAQ）** 原文让读者「用更高级别的中断（如 L4：内核与内核级插件）」插队，暗示插件能用 L4。 源码 `scheduler.go` 的 `clampPluginLevel` 把 **>L3 一律夹到 L3**，注释也写明 「L4 由内核独占（panic、内核事件 selfip）」。照原文写插件会静默拿到 L3。 改为：插件可声明 L1–L3，L4 是内核保留的「立即打断」。 **② 驻留子的父侧动作列错** 组件表写「父可查看/收发/压缩/回收」。"收"不存在 —— 源码的动作集是 `list | create | send | inspect | compress | reclaim | destroy`， 子持有状态面由**父 pull**（resident.go 开篇注释：父持登记表，子持 inputch 处理表， 父 pull 不打断子）。改成「查看/发送/压缩/回收/销毁，子是父拉取而非推送」。 ## 措辞不准确（12 处） - **Context 层**「最近若干条受保护」→ 源码 `pCount := 10` **写死十条**； 「预训练词向量 → 余弦相似度，TF-IDF 回退」→ 实为优先稠密向量余弦、 未配置时退到稀疏词向量（TF-IDF / fastText）；「自动下沉」→ 归档进 Document 层 - **PluginSDK「四通道」**→ 不是四个"通道"，是三面接口（工具/钩子/事件）+ 输出通道声明 - **管道「7 个阶段钩子」**→ 会被读成都在管道内。实际分布是进管道前 1（on_input）、 轮次中 4、收尾 2（before/after_output），两处都标明 - **sanitizer** 只写了"清工具调用残留"，漏了它更常做的是洗坏 UTF-8/U+FFFD/ANSI （而这类字节会被模型复读），且不注册工具只挂钩子 - **rss**「推送通知」→ 实际是按间隔轮询 + 中断注入；补上"订阅时记历史条目， 所以订一个源不会把旧文章全推一遍" - **memo** 补上可核验的机制：每 5 分钟检查未完成待办 - **ocr / bili** 补外部依赖（tesseract + chi_sim / yt-dlp）—— 不写清楚装完才发现缺 - **mc**「两阶段激活」原样照抄没解释；实为「想连着（意图）」与「确实连着（连接）」 两个状态分开，所以 bridge 被 kill -9 后能自动重登恢复会话 - **qq** 一句话太单薄，补 20 工具 + 权限模型要点（身份绑帧、取交集、前缀拒绝） - **a2a / music / weather** 分别补：两个方向与端点、只读无副作用、NoMemory 取舍 ## 顺带修掉两个我上一轮引入的 HTML 缺陷 用行替换时失手：Context 卡丢了一个 `</p>`、mc 卡多了一个 `</span>`。 这次写了栈式配对检查才发现（简单的计数对比看不出来）。 ## 验证 - 栈式标签配对：p/span/div/button/code/section/h2/h3/details/ul/ol/a/li **全部平衡** （修复前 p 差 1、span 差 -1） - 事实终检 10/10：内置插件 16（all.go 导入数）、LLM 适配器 9 且**逐个名字对上**、 Go 行 109241→109k、go.mod 1.25.0、L4 归属、resident 动作、Stage 分布、备案号 - 浏览器回归：深浅错误 0、JS 禁用 47/47 可见、reduce 动效停、390/768/1440 溢出 0、 滚到底未揭示元素 0 - mc 工具数：本写「12 个动作工具」，实测 `tp+"act"` 去重后 activate/deactivate/status 之外是 **11** 个，已改
This commit is contained in:
JianFeeeee
@ -1387,10 +1387,11 @@
|
||||
<div class="body">
|
||||
<h3><span class="mark">①</span> Context<span class="en">工作窗口</span></h3>
|
||||
<p>
|
||||
内存中的事件窗口。按与当前输入的相关性排序（预训练词向量 → 余弦相似度，
|
||||
TF-IDF 回退），最近若干条受保护。低分事件自动下沉。
|
||||
</p>
|
||||
</div>
|
||||
内存中的事件窗口。按与当前输入的相关性打分：优先比统一空间的稠密向量余弦，
|
||||
未配置时退到稀疏词向量（TF-IDF / fastText）。最近 10 条受保护，
|
||||
低分事件归档进 Document 层。
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="layer l-doc reveal">
|
||||
@ -1448,7 +1449,7 @@
|
||||
<div class="wrap">
|
||||
<h2 class="reveal rise">一条消息进来之后</h2>
|
||||
<p class="sub reveal rise" style="--d:90ms">
|
||||
输入先过调度器，再进处理管道。管道有 7 个阶段钩子，插件可改写或短路。
|
||||
输入先过调度器，再进处理管道。全程 7 个阶段钩子，插件可改写或短路。
|
||||
</p>
|
||||
|
||||
<div class="flow reveal rise">
|
||||
@ -1545,10 +1546,10 @@
|
||||
<h2 class="reveal" style="margin-top: 3rem">核心组件</h2>
|
||||
<div class="comp reveal rise">
|
||||
<div class="row"><code>homed</code><span>常驻内核进程：LLM 编排、记忆管理、输入调度、插件生命周期</span></div>
|
||||
<div class="row"><code>PluginSDK</code><span>四通道：注册工具 / 挂阶段钩子 / 订阅事件 / 声明输出通道</span></div>
|
||||
<div class="row"><code>PluginSDK</code><span>面向内核的接口：注册工具 / 挂阶段钩子 / 订阅事件 / 声明输出通道</span></div>
|
||||
<div class="row"><code>inputch</code><span>最基本的输入路由单位，可划给某个 agent（含驻留子）</span></div>
|
||||
<div class="row"><code>Stage</code><span>7 个处理阶段钩子，插件可改写或短路消息流</span></div>
|
||||
<div class="row"><code>resident</code><span>驻留子 agent：独立调度器 + temp 图记忆，父可查看/收发/压缩/回收</span></div>
|
||||
<div class="row"><code>Stage</code><span>7 个处理阶段钩子（进管道前 1 个、轮次中 4 个、收尾 2 个），插件可改写或短路</span></div>
|
||||
<div class="row"><code>resident</code><span>驻留子 agent：独立调度器 + temp 图记忆；父可查看/发送/压缩/回收/销毁，子是父拉取而非推送</span></div>
|
||||
<div class="row"><code>hmapdev</code><span>插件工具链：生成工程、构建 .hmap、安装</span></div>
|
||||
</div>
|
||||
|
||||
@ -1613,7 +1614,7 @@ echo <span class="s">"你好，记住我喜欢喝咖啡"</span> | ./build/waiter
|
||||
<p class="phint" id="phint">点上方任一插件查看用途</p>
|
||||
<div class="pcard" id="p-a2a">
|
||||
<div class="pcard-head"><code>a2a</code><span class="ver">v1.3.1</span></div>
|
||||
<p>Agent-to-Agent 协议通信插件，支持双向 A2A 通信：可查询其他 Agent 并回复其请求。提供 HTTP 服务端暴露本 Agent 能力。</p>
|
||||
<p>Agent 间通信。对外起 HTTP 服务暴露 /agent-card 与 /a2a（JSON-RPC）供他人发现与调用；对内提供工具去问别的 Agent。把监听地址设为空即只出站、不开端口。</p>
|
||||
<a class="psrc" href="https://gitcode.com/JianFeeeee/homeagent-sdk/blob/main/example/a2a" target="_blank" rel="noopener noreferrer" title="SDK example/a2a"><span class="psrc-r">SDK</span><span class="psrc-p">example/a2a</span><span class="psrc-out">↗</span></a>
|
||||
</div>
|
||||
<div class="pcard" id="p-acp">
|
||||
@ -1623,7 +1624,7 @@ echo <span class="s">"你好，记住我喜欢喝咖啡"</span> | ./build/waiter
|
||||
</div>
|
||||
<div class="pcard" id="p-bili">
|
||||
<div class="pcard-head"><code>bili</code><span class="ver">v1.2.0</span></div>
|
||||
<p>B站视频下载工具，基于 yt-dlp 引擎。支持查看视频清晰度列表、指定格式下载、可配置下载目录。</p>
|
||||
<p>B站视频下载。需系统装 yt-dlp。不指定格式时先返回可用清晰度列表，选定后再下载；输出目录有路径校验，拒绝写成系统目录。</p>
|
||||
<a class="psrc" href="https://gitcode.com/JianFeeeee/homeagent-sdk/blob/main/example/bili" target="_blank" rel="noopener noreferrer" title="SDK example/bili"><span class="psrc-r">SDK</span><span class="psrc-p">example/bili</span><span class="psrc-out">↗</span></a>
|
||||
</div>
|
||||
<div class="pcard" id="p-browser">
|
||||
@ -1654,22 +1655,22 @@ echo <span class="s">"你好，记住我喜欢喝咖啡"</span> | ./build/waiter
|
||||
</div>
|
||||
<div class="pcard" id="p-mc">
|
||||
<div class="pcard-head"><code>mc</code><span class="ver">v0.1.8</span></div>
|
||||
<p>把 mineflayer 虚拟 MC 客户端封装为 HomeAgent 的 chan:mc IO 通道（两阶段激活 + 动作工具）</p></span>
|
||||
<p>基于 mineflayer 的虚拟 MC 客户端，作为 chan:mc 通道接入。「激活」分两个状态：想连着（意图）与确实连着（连接），所以 bridge 进程被杀后能自动重登恢复会话，而不是要人再喊一次。带移动/挖掘/合成/攻击等 11 个动作工具。</p>
|
||||
<span class="psrc psrc-none" title="该插件源码在本地开发仓，尚无公开地址"><span class="psrc-p">本地开发仓（无公开地址）</span></span>
|
||||
</div>
|
||||
<div class="pcard" id="p-memo">
|
||||
<div class="pcard-head"><code>memo</code><span class="ver">v1.1.0</span></div>
|
||||
<p>待办与备忘录插件。待办（todo_add/todo_complete/todo_list）会主动提醒；备忘录（memo_create/memo_list/memo_delete）纯记事不提醒。</p>
|
||||
<p>待办与备忘录刻意分两类：待办每 5 分钟检查未完成数、有则注入提醒；备忘录纯记事不提醒。混成一类要么天天弹、要么被忘掉。</p>
|
||||
<a class="psrc" href="https://gitcode.com/JianFeeeee/homeagent-sdk/blob/main/example/memo" target="_blank" rel="noopener noreferrer" title="SDK example/memo"><span class="psrc-r">SDK</span><span class="psrc-p">example/memo</span><span class="psrc-out">↗</span></a>
|
||||
</div>
|
||||
<div class="pcard" id="p-music">
|
||||
<div class="pcard-head"><code>music</code><span class="ver">v0.1.0</span></div>
|
||||
<p>音乐搜索插件，支持搜索歌曲和查看歌词（基于网易云音乐）</p>
|
||||
<p>搜歌与查歌词（网易云公开接口）。只读：不下载音频、不落文件。两段式用法 —— 先搜到歌曲 ID，再按 ID 取词。</p>
|
||||
<a class="psrc" href="https://gitcode.com/JianFeeeee/homeagent-sdk/blob/main/example/music" target="_blank" rel="noopener noreferrer" title="SDK example/music"><span class="psrc-r">SDK</span><span class="psrc-p">example/music</span><span class="psrc-out">↗</span></a>
|
||||
</div>
|
||||
<div class="pcard" id="p-ocr">
|
||||
<div class="pcard-head"><code>ocr</code><span class="ver">v1.0.0</span></div>
|
||||
<p>图片文字识别工具，基于 Tesseract OCR 引擎。支持从 URL 或 base64 图片中提取文字内容。</p>
|
||||
<p>图片文字识别。需系统装 tesseract（中文另需 chi_sim 语言包）。支持 URL 或 base64 输入，临时文件识别后自动清理。</p>
|
||||
<a class="psrc" href="https://gitcode.com/JianFeeeee/homeagent-sdk/blob/main/example/ocr" target="_blank" rel="noopener noreferrer" title="SDK example/ocr"><span class="psrc-r">SDK</span><span class="psrc-p">example/ocr</span><span class="psrc-out">↗</span></a>
|
||||
</div>
|
||||
<div class="pcard" id="p-plugindev">
|
||||
@ -1679,7 +1680,7 @@ echo <span class="s">"你好，记住我喜欢喝咖啡"</span> | ./build/waiter
|
||||
</div>
|
||||
<div class="pcard" id="p-qq">
|
||||
<div class="pcard-head"><code>qq</code><span class="ver">v1.4.1</span></div>
|
||||
<p>QQ 消息收发插件，通过 NapCat 协议桥接</p>
|
||||
<p>经 NapCat 桥接 QQ：20 个工具覆盖消息、群/好友、文件传输。带权限模型 —— 身份绑在「帧」上而非插件全局（中断抢占恢复后不会丢身份），多来源合并取权限交集，敏感工具按前缀一律拒绝非所有者。</p>
|
||||
<a class="psrc" href="https://gitcode.com/JianFeeeee/homeagent-sdk/blob/main/example/qq" target="_blank" rel="noopener noreferrer" title="SDK example/qq"><span class="psrc-r">SDK</span><span class="psrc-p">example/qq</span><span class="psrc-out">↗</span></a>
|
||||
</div>
|
||||
<div class="pcard" id="p-recoverydiag">
|
||||
@ -1689,12 +1690,12 @@ echo <span class="s">"你好，记住我喜欢喝咖啡"</span> | ./build/waiter
|
||||
</div>
|
||||
<div class="pcard" id="p-rss">
|
||||
<div class="pcard-head"><code>rss</code><span class="ver">v1.1.0</span></div>
|
||||
<p>RSS/Atom 订阅监控插件，自动检测更新并推送通知</p>
|
||||
<p>RSS/Atom 订阅监控。按间隔轮询，发现新条目即以中断注入告知 agent；订阅时记下历史条目，所以订一个源不会把旧文章全推一遍。</p>
|
||||
<a class="psrc" href="https://gitcode.com/JianFeeeee/homeagent-sdk/blob/main/example/rss" target="_blank" rel="noopener noreferrer" title="SDK example/rss"><span class="psrc-r">SDK</span><span class="psrc-p">example/rss</span><span class="psrc-out">↗</span></a>
|
||||
</div>
|
||||
<div class="pcard" id="p-sanitizer">
|
||||
<div class="pcard-head"><code>sanitizer</code><span class="ver">v0.1.0</span></div>
|
||||
<p>清洗 LLM 输出中的工具调用残留（思维泄漏）</p>
|
||||
<p>在三个阶段清洗文本：坏 UTF-8 / U+FFFD / ANSI 转义（会被模型复读）与 LLM 输出里的工具调用残留。不注册工具，只挂钩子。</p>
|
||||
<a class="psrc" href="https://gitcode.com/JianFeeeee/homeagent-sdk/blob/main/example/sanitizer" target="_blank" rel="noopener noreferrer" title="SDK example/sanitizer"><span class="psrc-r">SDK</span><span class="psrc-p">example/sanitizer</span><span class="psrc-out">↗</span></a>
|
||||
</div>
|
||||
<div class="pcard" id="p-vanblog">
|
||||
@ -1709,7 +1710,7 @@ echo <span class="s">"你好，记住我喜欢喝咖啡"</span> | ./build/waiter
|
||||
</div>
|
||||
<div class="pcard" id="p-weather">
|
||||
<div class="pcard-head"><code>weather</code><span class="ver">v1.0.0</span></div>
|
||||
<p>天气查询插件（基于 wttr.in），支持实时天气和未来预报</p>
|
||||
<p>查实时天气与预报（wttr.in，无需 API Key）。可设默认城市；结果标记为不进记忆计算 —— 天气是易变数据，反复写进记忆只会挤占预算。</p>
|
||||
<a class="psrc" href="https://gitcode.com/JianFeeeee/homeagent-sdk/blob/main/example/weather" target="_blank" rel="noopener noreferrer" title="SDK example/weather"><span class="psrc-r">SDK</span><span class="psrc-p">example/weather</span><span class="psrc-out">↗</span></a>
|
||||
</div>
|
||||
</div>
|
||||
@ -1745,8 +1746,9 @@ echo <span class="s">"你好，记住我喜欢喝咖啡"</span> | ./build/waiter
|
||||
<summary>为什么消息会「排队」而不是立即处理？</summary>
|
||||
<p>
|
||||
因为同一时刻只应有一个任务在改上下文。同级抢占会让两边都做一半。
|
||||
需要立刻插队时用更高级别的中断（如 L4：内核与内核级插件），
|
||||
而不是让所有消息都变成抢占者。
|
||||
需要立刻插队时用更高级别的中断：插件可声明 L1–L3，L4 是内核保留的
|
||||
「立即打断」（panic、内核事件），外部插件声明 L4 会被夹到 L3。
|
||||
不该让所有消息都变成抢占者。
|
||||
</p>
|
||||
</details>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user