jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-01 06:47:29 +00:00
Code Issues Packages Projects Releases Wiki Activity
858 Commits 5 Branches 29 Tags
4e70b8d5d8a38cf6c7927c275ca50ee1fd7d5fcb
Commit Graph

11 Commits

Author SHA1 Message Date
root
f33ee3e396 docs: 把「业务语义归插件、联动走事件总线」补进 OVERVIEW 与 PLUGIN_DEV 
上一提交只在 ARCHITECTURE 里记了终端归属。本次把这条**通用原则**补到另外两份
文档，避免只读 OVERVIEW / 插件开发指南的人仍旧按旧直觉写代码。

## OVERVIEW（中英）

设计要点新增一条「业务语义留在插件层」：内核不定义业务对象（终端、命令历史、
设备状态、媒体库都是插件域）。以终端为例说明：PTY/生命周期/输出缓冲归
agentcli，WebUI/CLI 订阅总线自攒视图，内核只提供事件总线与注册面 —— 新增一类
能力不需要改内核，也不会在核心里堆出第二套业务真相。

## PLUGIN_DEV（中英）

PluginSDK 章节新增「与其它插件联动 — 走事件总线，不要依赖内核内部组件」：
- 代码示例：订阅 terminal_output + tool_call 自己攒视图
- 两条稳定事件表（谁发布、用途）
- ★ 外部插件只能订阅、不能发布（Publish 属 withheld 能力），所以「能力所有者
  需要广播状态」的插件必须内置（agentcli 即此例）
- 指向 internal/pluginview 作为参考实现，并写明「视图不是权威、晚启动会缺早期
  事件」

一个准确性修正：公开 SDK **没有** EventTerminalOutput 常量（属内核内部事件
类型），所以示例里外部插件用 sdk.EventType("terminal_output") 字符串订阅，
并注明内置插件可用 internal sdk 常量 —— 避免文档给出编不过的示例。

验证：四份文档代码围栏配对（74/74、0/0）；仅文档改动，无代码影响。
 2026-10-20 09:41:07 +08:00
root
2aab90c508 fix(plugins): 内置清单终审 15 → 13 —— kbtree/multimodal 翻案加回 
## 翻案依据（逐方法对照公开 SDK，非方法名 grep）

初判把 kbtree/multimodal 归入"只用公开 SDK"，错了。两边的
s.Knowledge() / s.LLM() **同名但接口面不同**：

- kbtree 需要 KnowledgeAPI.Subtree/CategoryCounts/SearchIn/Categories
  与 KnowledgeTreeView/KnowledgeCategoryCount 类型 —— 公开 KnowledgeAPI
  只有 Search/Add/List，树视图类型公开面根本没有
- multimodal 需要 LLMAPI.Chat + LLMMessage/LLMContentBlock ——
  公开 LLMAPI 只有 ListSources/SetSource/CurrentSource，没有 Chat

外置它们 = OCR/看图/转写、知识树浏览静默失效。

## 最终内置 13 个

  cli webui agentcli healthcheck pluginmgr seq remotedevice
  clawhubadapter kbtree multimodal cfgmgr skillmgr seemedia

外置 5 个（SDK 仓 example/ 已提供工程并已部署验证）：
  cmd localuse mcp（本轮）+ ai_image files（此前）+ timer（更早）

## 文档同步（中英 6 份）

数量 11 → 13；判定标准小节补「终审翻案」与教训：
**判外置与否必须逐方法对照公开接口，同名方法不等于同面。**

验证：go build/vet/test 全绿；生产实例已部署新内核 + 新插件包，
四个按需插件经 plugin_start 拉起、工具全部注册（cmd_run /
local_screensee / mcp_* / files_edit_line 实核）。
 2026-10-19 22:09:09 +08:00
root
835688c94a refactor(plugins): 按「内置插件判定标准」收敛内置清单 16 → 11 
## 判定标准（写进 all.go 与 ARCHITECTURE）

**只有必须使用内部 SDK 能力（公开 SDK 没有的接口面）的插件，才留在
编译期内置清单**；其余一律外置为 .hmap 插件，独立编译、独立发版。

依据是 internal/plugin/proc/capability.go 的 withheldCapabilities：
内部 SDK 的 TerminalAPI/TrackerAPI/StatusAPI/SupervisorAPI/AdapterAPI/
SelftestAPI/ToolAPI/Publish 等能力面，外部插件在类型层就不存在。
需要它们的插件外置后功能会**静默消失**（不报错），必须内置；
只要公开能力的插件，留在内核里是白付重编成本。

## 内置 11 个（all.go 单一权威清单）

  cli webui       TerminalAPI/Tracker/Status/Supervisor/Adapter
  agentcli        EventPublish（终端输出走 Publish，公开 SDK 无此方法）
  healthcheck     SelftestAPI
  pluginmgr       failback 恢复链必需
  seq             ToolAPI
  remotedevice    RegisterChannel
  clawhubadapter  InjectInputSync
  cfgmgr skillmgr seemedia（保留）

## 外置 8 个（源码保留，.hmap 由 SDK 仓 example/ 提供）

  timer（此前）ai_image files cmd kbtree localuse mcp multimodal

## 同步修正

- kbtree 归位：它一直是编译期内置插件，却长期被 main.go 单独导入，
  游离在 all.go 清单之外（文档盘点因此数错）。现移入 all.go，
  main.go 不再单独导入任何插件，并加注释禁止该做法。
- integration_test：外置插件的 7 个用例（cmd_run/terminal_*）加
  requireExternalTool 跳过保护——用例保留（行为判据仍有价值），
  在纯内置装配下 Skip，不造假失败。
- 全部文档同步 11 个的清单与判定标准（中英四份 + 两份 README）。

## 已核实不做的事

- 保留的 11 个内置插件无一在代码里硬依赖被外置的插件：
  cli 对 terminal_* 是 ExecuteTool 按名动态调用（运行时依赖）；
  healthcheck/seq 只在白名单与示例文本里出现；webui 只订阅事件。
- kernelmod/（内核模块）与 plugins/（插件）严格区分：
  kernelmod/multimodal 是内核装配模块，与外置的 multimodal 插件无关。

验证：go build ./... 全绿；go test ./internal/plugins/... 全绿；
webui 新增 5 条命令历史渲染回归判据（TestCmdHistory*）全绿。
 2026-10-19 21:13:23 +08:00
root
515cf2deb1 docs: 按源码全面校正（插件数/内置 timer/RPC 数/工具数/失效行号） 
逐条对着源码核过，修掉 5 类与实现不符的陈述（中英四份文档同步）：

1. **内置插件数 20 → 17**
   `internal/plugins/all.go` 的空白导入实际是 17 个。旧文档还列了 `timer`
   （已外置）与 `data`/`kbtree`（根本不是内置插件，前者只有 skills 目录，
   后者未进 all.go）。清单按 all.go 重写。
   涉及：README、README_EN（含「许可」章节的 AGPL 覆盖范围）、OVERVIEW 中英、
   ARCHITECTURE 中英的加载方式表。

2. **删除所有把 timer 当内置插件的表述**
   ARCHITECTURE 中英目录树里的 `internal/plugins/timer/` 行、
   PLUGIN_DEV 内置插件示例表的 Timer 行（该行还与同页下方「timer 已移出内置插件」
   的说明自相矛盾）。示例表改用 healthcheck（真实存在、30m 定时自检）。

3. **子进程 RPC 方法数 55 → 82**
   权威清单是 `internal/plugin/proc/protocol.go` 的 Method 常量，
   实际 82 个（settings 16 / plugin 9 / io 8 / secrets 7 …）。
   v1.1.1「51 → 55」作为历史叙述保留，但补注说明 82 才是当前值，
   避免读者把 55 当现值。

4. **qq 示例工具数 20 → 24**
   按 `example/qq/plugin.go` 的 `Name: tp + "..."` 实数。

5. **修掉整张失效的「文件:行号」引用表**
   原文写 `context.go:155` / `document.go:206` / `indexer.go:96+111`，
   但 memory 重组后 `context.go` 已迁到 `agent/core/`，行号全部错位。
   改为**函数名锚点**（`RelevanceContext.Prune`、`Store.Query`、
   `Indexer.vectorSearchEntities`），并改正 `distill.go` 的算法描述：
   文档写 Bigram Jaccard，源码是**加权** Jaccard（`scene_emerge.go` 有明确注释），
   阈值 `sim > 0.75` 在 `distill.go`。

同时补 Provider 接口漏项：实际有 4 个方法（Name / Chat / ChatStream /
MaxContextTokens），文档只写了前 3 个。

验证：`go build ./...` 通过；文档内相对链接 0 坏链；
引用的 22 个 .go 路径逐个 stat 存在（`internal/memory/media/` 两处是
「已删除机制」的历史叙述，指向不存在路径是正确语义，保持不变）。
 2026-10-19 20:49:43 +08:00
JianFeeeee
6d38a164eb chore(module): Go module 路径随托管地迁移 gitcode → github 
## 背景

仓库早已迁移到 GitHub（`github.com/JianFeeeee/HomeAgent`，CI/CD 都在那边跑），
gitcode 保留为**国内只读镜像**（`ci.yml` 的 sync-gitcode-main 快进推送）。
但 go.mod 的 module 路径一直是 `gitcode.com/JianFeeeee/...` —— 既与权威源
不符，`meta.SourceURL`（AGPL §13 的源码提供入口）也指向镜像而非实际运行的代码。

## 关键区分（这是本次改动安全的前提）

两个 module 是**不同**的，影响面差一个数量级：

| module | 谁依赖 | 改它的后果 |
|---|---|---|
| `.../HomeAgent`（主仓） | **只有主仓自己** | 内部重构，零外部影响 |
| `.../homeagent-sdk`（SDK 仓） | 主仓 49 文件 + 所有外部插件 | 需重编插件 |

★ 实测确认：**插件不 import 主仓 module**（`strings qq/plugin.bin | grep HomeAgent` = 0），
只依赖 SDK 仓。而插件与内核的边界是 **RPC 方法名字符串**
（`plugin.init` / `tool.invoke`…，见 proc/protocol.go），**与 Go module 名无关**。
⇒ module 改名**不改变任何 wire 协议**，现网已装的插件照常运行。

SDK 的 GitHub 仓名是 `homeagentsdk`（无连字符），module 路径必须与之精确匹配，
否则 `go get` 会因路径不符失败，故取 `github.com/JianFeeeee/homeagentsdk`。

## 改动

- `go.mod` / `go.sum`：两个 module 路径 + require/replace
- 277 个 Go 文件 + Makefile + 打包脚本的 import 与 ldflags 路径
- SDK 仓 `meta.CoreModule`、`tools/hmapdev` 的 module 声明与工程模板
- 对外文档/链接的仓库地址（README、PLUGIN_DEV、OVERVIEW 等）

## 明确**保留** gitcode 的地方（镜像机制，不能动）

- `GITCODE_TOKEN`、`GC_URL="…@gitcode.com"`（CI 同步 job）
- `gitcode.com/api/v5/...`（release 附件上传）
- git remote `gitcode`（镜像拉取/推送）
- `docs/zh/ci-cd-runbook.md`（整篇讲镜像运维）

## 验证

- `go build ./...` / `go vet ./...` 绿
- `go test ./... -count=1` → 48 包 ok / 0 FAIL
- hmapdev 工具链编译通过（`third_party/homeagent-sdk/tools/hmapdev`）
- 全仓残留检查：module 形态的 `gitcode.com/JianFeeeee` = 0
- 镜像机制抽验：GC_URL / @gitcode / api/v5 / remote 均完好

## 顺带修正

`hmapdev/templates.go` 的注释此前写「gitcode 的模块不在 proxy.golang.org 上」——
module 已迁 GitHub，该论断不再成立。改为如实说明**为何仍默认 replace 到本机 SDK**：
离线可构建、避免版本漂移、内网可用。理由与托管地无关，故 replace 保留。
 2026-10-08 10:40:17 +08:00
JianFeeeee
a9e0489e57 docs: 修正「项目概览/架构」把已删除机制写成现行机制（中英四份） 
## 问题

assets/docs/{zh,en}/OVERVIEW.md 的媒体记忆段仍在描述 v1.2.0 **已整体拆除**的机制，
且两份文档的第一读者入口（README「文档」区、site/index.html 的「项目概览」链接）
都指向它。docs/git-branching.md §七.7 的反例表里恰好列着这一条，说明这是
「文档当事实后反向误导」的复发项。

同时修掉同一批里其余过期的结构性断言（均为逐条回源码核实后改）。

## 改动（四份文件，7 处）

OVERVIEW.md（zh/en 对称）：
- 媒体记忆段：「引用计数 GC + 描述文本才是持久语义记忆 + [<mime> <digest>] 标记」
  → 「一等记忆块：块自带向量与指纹直接检索；无独立 GC / 无引用计数 / 无 keep-set；
    删除块即删内容」，并显式注明旧机制已在 v1.2.0 拆除
  - 依据：internal/memory/block.go（"不携带 Layer、Owner 或 RefCount"）、
    ARCHITECTURE.md 自身的「不再有描述式索引」段、
    graphmedia_test.go:24「描述文本、marker 反解…全部已废弃」、
    inputunify_test.go:226「不往文本里贴 marker」
- LLM Provider 段：「三种实现 OpenAIProvider/OllamaProvider/LuaAdaptedProvider」
  → 「唯一实现 LuaAdaptedProvider」
  - 依据：internal/agent/api/provider.go 只有 LuaAdaptedProvider 一个实现类型
- 适配器：「内置 8 个」→「内置 10 个」并补全名单（+kimicode/server）
  - 依据：ls internal/lua/adapters/*.lua = 10；README.md 同一处早已写「10 个」，
    两份文档此前自相矛盾
- 「支持 8 个 LLM 源自动降级」→「多源自动降级」
  - 依据：源数量由部署配置，默认 seed 仅 deepseek 一个
    （registry.go defaultSources 唯一条目）

ARCHITECTURE.md（zh/en 对称）：
- 代码结构树 internal/skill/（**该目录不存在**）→ 移入 plugins/skillmgr/
  - 依据：internal/plugins/skillmgr/ 存在，internal/skill/ 不存在（README 亦写 plugins/skillmgr）
- dynamic.go 描述「.so 动态加载器」→「加载通道分派（proc/lua/skill）；.so 仅剩给明确报错」
  - 依据：dynamic.go 的 tryDynamic 实际只分派 proc 与 lua，.so 命中只为给出「请用新版
    hmapdev 重编」的明确错误（legacyCABIEntries 注释）
- 配置系统「8 个 LLM 源的 seeds」→「含 1 个 LLM 源 seed，其余源由部署时添加」
- 适配器数 8 → 10
- Provider 分层图（仅 en 侧滞后）：删掉不存在的 OpenAIProvider/OllamaProvider
  - 依据：zh 侧同一图早已写作「LuaAdaptedProvider (唯一实现)」，en 侧未跟上

## 验证

- 全量残留扫描：OpenAIProvider / OllamaProvider / 引用计数 GC /
  Reference-counted GC / 8 个 LLM / 8 LLM / internal/skill / .so 动态加载
  → 在 assets/docs/ 与两份 README 中均为 **0 命中**（改前分别为 3/2/2/1/2/1/2/2）
- 每条新断言逐条回源码核实（adapters=10、provider struct=1、skillmgr 存在、
  internal/skill 不存在、defaultSources=1、无 marker 写入代码）
- 纯文档改动：不涉及 .go，不改变构建产物（assets/docs 未被 //go:embed 打包，
  仅被 site/index.html 以 GitHub 链接形式引用）
- 未新增版本号字面量，符合 §七.7 的「模型或用户会当作事实的文本不得写死版本号」

## 分支归属

按 docs/git-branching.md §七.7：面向使用者的开发者文档先落 release 线、
再 cherry-pick 合入 main（不 merge）。本次提交在 release/v1.3.x。
 2026-10-08 07:55:28 +08:00
JianFeeeee
3cb4686727 docs: 同步仓库文档到 v1.1.1，补媒体记忆与接口扩展规则 
五处文档此前停在 v1.0.0，而 v1.1.0/v1.1.1 都已发布并在现网运行。
本轮补齐三层记忆的媒体架构、模型工具的媒体参数、通信面 method 数，
以及冻结解除后的替代约束。

## 中英双语 OVERVIEW.md

三层记忆段只写了 Context/Document/Graph 三层，而 v1.1.0 起图片/音频是
三层里的一类节点。补上媒体记忆的架构概要：CAS + 引用计数 GC + 标记格式
（描述文本才是持久语义记忆，blob 是可淘汰的缓存）+ 插件边界贯通。

## 中英双语 ARCHITECTURE.md

- 「记忆工具」表补 `memory_commit`/`doc_commit` 的 `media_digests` 与
  `sentence_text`（后者从未暴露给模型，而它是媒体绑定链的必经环节）
- 「三层记忆」段新增媒体记忆子节：CAS 设计表（寻址/完整性/写入原子性/引用/GC）、
  标记格式、可选性（`enabled=false` 时整条链路静默退化）
- 「三个通信面」从 51 改为 55 个 method，新增四个 media method 的说明
- 「SDK 四通道」代码示例补媒体注入三方法 + 与 SetToolBlocks 的区别

## plugin-interface-matrix.md

- 状态从「完成 v2」改「完成 v3」，v3 记录 v1.1.1 的接口扩展
- §二 A3 DocMemoryAPI 补 InsertWithMedia
- §二 A4 补三个媒体注入方法 + 为何不能搭 SetToolBlocks 的车
- §二 A5 补 MediaAttachment 类型 + Triple/Doc/TextEvent 的扩展字段
- §六「新获得的能力」补 SetToolBlocks 已落地、媒体入记忆、插件主动发起
  带媒体的对话
- §七 冻结检查点补第 5 条（冻结已解除，取代它的是 §九）
- 新增 §九「v1.1.x 的接口扩展规则」：冻结解除后的三条硬约束
  （只增不减签名不改 / 新增方法方向 / 模板接线六处失败链）+ 验证方式
  （存量插件 17/17、旧产物 4/4 建链、模板断言、压测 -race）

## 为何分立两笔 commit

前一笔（SDK 仓 README + 内核 README）改的是给**插件开发者**看的文本，
本笔改的是给**架构师与维护者**看的技术文档。受众与改动层次不同，
放在同一个 commit 会让追溯时看不出"文档在哪一层跟上了代码"。
 2026-09-06 15:07:14 +08:00
JianFeeeee
d043fed5ce docs: 文档与发布脚本同步到 v1.0.0 子进程架构 
README/架构文档仍在描述 C ABI 动态库加载，与 v1.0.0 实际实现不符。
新用户按文档走会去做 -buildmode=c-shared，产物新内核根本不加载。

README.md / README_EN.md：
- 设计要点补子进程架构段（三面通信、崩溃自愈、真热重载）
- 代码结构 plugin/ 描述：.so 动态加载器 → 子进程加载器
- 项目状态补 v1.0.0 条目（6 类缺陷 + 实测数字），v0.9.0 标注 ABI 已退场
- 新增「下载」章节：三变体对照 + 各平台包格式 + macOS 限制

assets/docs/{zh,en}/ARCHITECTURE.md：
- 四种加载方式表：外部 .so/C ABI → 外部子进程/握手+stdio JSON-RPC
- 加载流程改写为 exec.Command → 继承 fd → 握手 → init → start
- 内置 vs 外部对照表 7 行更新
- 新增「子进程插件的三个通信面」小节，含每个面的选择理由

assets/docs/{zh,en}/OVERVIEW.md：插件系统段落改写

deploy/ 发布脚本三处回归（v0.7.2 的 7f08f3c 把 package/ 移到
deploy/packaging/ 使目录深度 1→2，但没改相对路径，此后两个版本
的发布都没有二进制资产）：
- build.sh：.syso 按目标平台 hide/restore（trap 兜底），恢复
  windows 目标的 CXX，arm64 刻意不带 CXX
- installer.nsi：5 处 ..\build → ..\..\build，PRODUCT_VERSION 可注入
  （原先硬编码 0.8.0）
- homeagent.spec：server 变体补装 waiter（control-server 声明了 CLI 却没装）

deploy/scripts/upload_assets.py：release 资产上传（两步签名 URL → OBS
PUT）。放 deploy/scripts/ 而非 scripts/，因为后者在 .gitignore 里。
支持 GITCODE_REPO/ASSET_DIR 环境变量以复用于 SDK 仓。
 2026-09-03 19:26:17 +08:00
JianFeeeee
74d30915ea docs: correct plugindev toolchain usage, Lua execution model, and stale plugin examples 
- 工具链：修正 bundle 默认开启（plugindev build 默认多平台合集）、补充 --no-bundle/debug/--target/--outdir/--sdk-path/--replace 用法、Lua 打包内容、安装端点语义
- 新增「执行模型」节：Lua 插件为被动回调模型，无常驻服务能力
- OVERVIEW/ARCHITECTURE：示例列表与 Lua 加载描述修正（internal/plugin gopher-lua，非 internal/lua VM；无热加载）
 2026-07-31 12:59:06 +08:00
JianFeeeee
53a00793d3 docs: 修复记忆分层引用错误 + 补充内置/外部插件说明 + 同步中英文文档 2026-07-28 21:56:53 +08:00
JianFeeeee
7f08f3ca09 v0.7.2: 根目录清理 + Agent 心跳重构 + 内嵌 ONNX 模型 
- 根目录清理: branding/docs/knowledge -> assets/, package/tools/deploy -> deploy/
- meta.go: Version 0.7.2, SDKCompatibleVersion 语义改为最高兼容
- Makefile: 版本回退 0.7.2
- registry.go: 系统提示词改用 meta.Version 格式化
- Agent 心跳: reorgGraph 拆分为三个独立循环(archive/merge/review)，各自可配间隔
- GraphDB: 新增 sentences 表 + 关系句子溯源 + ClearSentenceID + CleanupOrphanedSentences
- Knowledge: 支持词嵌入向量化器
- NLP 四阶段流水线: Parse -> Extract -> Verify -> Fuse + SentenceRef
- 移除远程 HTTP 解析器(remote_parser.go)
- 新增内嵌 ONNX 模型(vocab + dep_parser.onnx):
  +build onnxruntime: 全量 ONNX Runtime 推理
  !build onnxruntime: 内嵌词表规则式降级解析器
- config: core.agent.onnx_model_path 替代 dep_parser_url
 2026-07-28 09:56:26 +08:00