jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-09-28 05:13:27 +00:00
Code Issues Packages Projects Releases Wiki Activity
681 Commits 5 Branches 27 Tags
116dc413f0f5dd730c435f90aca0ffd600a04890
Commit Graph

9 Commits

Author SHA1 Message Date
JianFeeeee
7e1169bcda feat(kernel): 内置工具注册进 ToolAPI 面（方案 B，补真机实跑发现的架构缺口） 
真机实跑实证（独立实例 /tmp/seqtest，未触碰生产）：
  seq_run 报「工具 knowledge_list 不存在或未注册」，
  而**同一轮模型直接调 knowledge_list 是成功的**。

根因：`memory_*` / `knowledge_*` / `doc_*` / `person_*` 这 20+ 个是
**内核内置**工具，在 core.executeToolCallInner 里按**前缀分派**，
由 buildToolDefs 直接生成 schema，**从不进 StageHost / IOManager**
⇒ ToolAPI（只有插件工具 + IO 设备工具）既查不到也调不了。
后果：序列只能编排插件/设备工具，无法编排记忆/知识/文档/人物
——恰恰是最常用的能力。

方案 B 的实现：
· internal/sdk: 新增 BuiltinProvider（Defs/Exec）与 SetBuiltinProvider。
  用**晚绑定注入**而非让 toolImpl 依赖 core，理由：ToolAPI 是**全局单例**
  却需要 per-agent 数据（驻留子是轻量内核，memory 为 nil；内置工具可见性
  由 `if a.memory != nil` 等门控）。sdk 不能依赖 core（方向反了）。
· internal/sdk/tool_impl.go: ToolDefByName / ExecuteTool 补查内置工具。
  ⚠️ ExecuteTool 只在「io 确实没有该工具」时才转内置；io 的**执行失败**
  必须如实上抛 —— 否则会把「设备离线」误报成「工具不存在」，让调用方
  按 missing 策略跳过（与 P3 修过的父 io 吞错误同一族陷阱）。
  内置工具**默认不声明 ParallelSafe**（含 SQLite 写与召回）。
· internal/agent/core/builtin_toolapi.go: Agent 侧 provider。
  ★ Defs **复用 buildToolDefs 的同一批生成逻辑**（筛出不在
  StageHost/IOManager 中的那些），保证"模型看得到什么"与"插件看得到什么"
  门控完全一致 —— 避免两套语义。
  Exec 复用 executeToolCall 完整路径（授权闸 + 异常处理）。
· cmd/homed/bootstrap.go: agent 构造后注入。

★ 不会让模型看到重复工具（已核实）：模型侧走 buildToolDefs
（a.io / a.stageHost **直调**），ToolAPI 只经 PluginSDK.Tool() 暴露给插件
—— 两条不重叠的路径。

判据（builtin_toolapi_test.go，6 条）：
· 内置工具能从 ToolAPI 查到
· ★ 查到 ≠ 调得通：必须真的能执行
· 门控语义保持：未接 memory/knowledge 时不得声称有那些工具
· ★ 接了 knowledge 时必须可见（这正是要补的缺口）
· ToolAPI 上"不存在"必须是类型化 not-found（供 seq 的 missing 策略用）
· 内置工具默认不声明并发安全

真机复验（同一隔离实例，新二进制）：
  序列 "smoke2" 执行完毕（1/1 组）— 工具 1 个
  变量槽: summary = cangjie/central-repo/agreement/...
⇒ knowledge_list 成功执行并回填具名槽。上一次的「不存在或未注册」已消除。

已知局限（记入待定）：ToolAPI 单例而内置工具面是 per-agent，
多 agent 下看到的是"最近一个注入者"的面。本次不解决。
 2026-09-27 13:40:22 +08:00
JianFeeeee
994f198bc5 fix(security): 设备授权闸下沉到 ToolAPI 路径（D4，堵住绕过） 
问题：设备类工具的授权闸只存在于 core.executeToolCallInner
（toolcall.go:151-152），即**「agent 收到模型 tool_call」那条路径**。
而 ToolAPI.ExecuteTool 是**另一条**独立执行入口，不经那道闸
⇒ 凡是走 ToolAPI 的调用都能绕过 AllowedOutputs。

实测范围**不止序列**：cli 插件的 /terminal 直接经 ToolAPI 调 agentcli 的
终端工具（cli/plugin.go:1038 的注释自陈"SDK 的 ToolAPI 已允许跨插件调用
工具"）。任何插件拿 ToolAPI 都能指挥未授权的设备。

改动：
· internal/sdk/tool.go: ToolAPI 新增 CanUse(toolName, args) bool。
  **纯新增方法**，零值实现返回 true ⇒ 未实现者（存量插件、测试替身）
  行为不变。
· internal/sdk/tool_impl.go: 实现 CanUse。判据只有一条——设备类工具按
  `device/<id>` 查授权；非设备工具不受影响（闸的作用域必须窄，否则会把
  所有工具锁死）。
  授权查询走**可注入**的晚绑定闭包：toolImpl 在 internal/sdk，而
  IsOutputAllowed 是 core.*Agent 的方法，sdk 不能依赖 core。
· internal/plugin/registry.go: 新增 SetDeviceAuthQuery。
· cmd/homed/bootstrap.go: 在 newMainAgent 末尾注入。⚠️ 必须在 agent
  构造**之后**——判据要用 agent 自己的 allowedOutputs，而 registry 早于
  agent 构造，故 registry 存的是晚绑定闭包。

判据（toolapi_auth_test.go，7 条），核心是**两条路径必须一致**：
· 收窄授权时 ToolAPI 路径同样被拦
· 已授权设备放行（防闸过严杀掉正常能力）
· 非设备工具不受影响
· 枚举类工具不受影响（与内核 TestDeviceToolAuth_EnumerationNotGated 同语义）
· 未配置白名单 = 完整授权
· ★ TestCanUseAgreesWithInnerPath：4 组用例逐例比对内核路径与 ToolAPI
  路径的结论 —— 判定不同本身就是漏洞
· ★ TestCanUseMatchesInnerFailOpenOnMissingDeviceID：把现状
  （缺 device_id 时**放行**）钉住。⚠️ 这是 fail-open，是既有的可疑设计
  （core 的 TestDeviceToolAuth_* 依赖它），本次不擅自改语义；判据写明
  "若要改成 fail-closed，必须两处同时改"。

过程中三次自伤：
1. 一度在 core 写了个 toolAPIRef —— **只实现部分方法的替身**是过度设计，
   且两份实现必然漂移。改为判据直接用 sdk.NewTool(stageHost, iom)，
   与插件侧走**同一个**实现。
2. 判据里又写了 `var _ = agentIO.DeviceOutput` 这种压 unused import 的
   占位 hack（第二次犯这个），并重造了 strings.Contains。都已去掉。
3. 注入点一开始找错了位置（以为 newStageAndRegistry 能拿到 agent，
   实际 pluginReg 是 main() 的局部变量）。核实 newMainAgent 的签名后
   确认它同时持有 agent 与 pluginReg，注入点落在那里。

变异验证：让 CanUse 恒返回 true（还原成原缺口）⇒ 两条判据 FAIL，
其中一条直指「内核路径=false 而 ToolAPI 路径=true —— 两条路径判定不一致」。

回归：go build ./... 通过；go test ./internal/... 全绿。
 2026-09-27 13:15:22 +08:00
JianFeeeee
81cd8231d7 feat(kb-migrate): 存量知识库目录名迁移工具 + 启动期只报告 
背景：旧版 Add 整串 sanitize 名字、逐段 sanitize 建目录，留下 tech/_go_/note、
Tech/Upper、a/b with space 这类「知识名与盘上目录不一致」的目录。修复后
normalizeName 要求二者逐字一致，故需一次性改名。

- 迁移逻辑放在 internal/knowledge/migrate_names.go（PlanMigration/
  ApplyMigration），CLI 与 homed 启动**共用同一份实现**，避免口径漂移。
- 三条硬约束：
  1. 默认只报告（-apply 才真改名）—— 批量 os.Rename 不可逆。
  2. 检出目标名冲突（两条迁到同一目标 / 目标已存在）则**整批拒绝**，
     不做部分迁移：半迁移状态比不迁移更难收拾。
  3. 逐条失败不中断，最后统一报告；执行前重查冲突（计划生成与执行之间
     可能有人改过盘上状态），并校验目标不越出知识根。
- homed 启动在 initKnowledgeStore **之前**调 initKnowledgeMigration：改名后
  扫盘一次到位，避免先以旧名建索引再改名造成内存键与盘上目录短暂不一致。
  defaultApply=false ⇒ 启动只扫描+报告+打印可执行命令行，不替人决定。
  单次改名上限 200 条，防失控目录规模拖住启动。

实测：报告模式零改动；冲突场景整批拒绝且盘上原封不动；迁移后 Store
正确载入 4 条并可按规范名逐条删除。
 2026-09-26 14:20:19 +08:00
JianFeeeee
69446a2649 feat(scheduler): 主 agent 忙时把积压任务自动转投给驻留子 
问题（2026-09-19 线上实测）：主 agent 被长任务占住时（现场：12 分 8 秒、69 次
工具调用），后来到达的消息全部以 level insufficient 排进中断队列干等 —— 同级
中断不能抢占同级运行任务（canPreempt），只能等前一个跑完。而内核本有驻留子
（独立 agent + 独立调度器）可并行干活。

行为（用户 2026-09-19 明确要求）：
- 触发：运行任务持续 > offload_busy_after(5m) 且积压 >= offload_min_pending(3)
- 拉起/复用「转投专用」驻留子，把积压的纯排队输入转投过去
- 在原队列位置留下说明「[系统] N 条积压任务已转投给驻留子 agent X 处理…」

通道配置（按用户口径，与人工创建的子刻意不同）：
- 不配 inputch（内核的干活 agent，不接收插件用户输入）
- 持有全部输出通道（结果要能发回 qq/webui 等正确通道）

三个设计要点（都是实测撞出来的，写进代码注释与设计文档 §7.1）：
1. 检查必须在**独立 goroutine**：schedulerLoop 同步执行任务，放它里面在
   「正忙」期间根本回不到循环顶部 ⇒ 永不触发（我第一版就写错了，测试才发现）。
2. 只转投 TaskQueued 纯排队输入：中断任务带级别语义、self 任务与父的记忆面绑定。
3. 转投失败/关闭时必须把任务**放回队列前端**：吞一条输入比多处理一条更糟。

这是设计 §7「决策在父的模型手里」的**刻意例外**（父正忙、物理上无法决策，
而积压任务本来就是空的），已在文档中显式记录，且默认关闭、由部署方显式打开。

测试 11 条：只取排队输入 / 不足量不取 / 放回不丢任务 / 说明自解释 / 默认关闭 /
空闲不触发 / 端到端转投 / 上限不增殖 / 独立 goroutine 确实会触发。
 2026-09-19 16:59:47 +08:00
JianFeeeee
e70d2171ee refactor(terminal): 内核开终端/命令历史权威视图，WebUI 与 CLI 都改接内核 
按「内核开，两个插件接」重构终端与命令历史的数据归属。

背景：此前 WebUI 与 CLI 各订 EventToolCall/EventTerminalOutput 攅一份状态，
同一件事两份推导，还各自踩过同一个坑——工具 result 是 Go 的 map 文本
（map[cols:80 ... id:term_2 ...]），断言成 map[string]interface{} 永远失败，
terminal_create 的 id 回填不生效，/terminals 因此恒空（WebUI 也一样）。
实测确认：WebUI 自己的 /api/v1/terminals 与 /api/v1/cmd/history 同样是空的。

内核开（权威唯一真相）：
- internal/agent/core/terminal_registry.go：TerminalRegistry 归并两类事件——
  EventToolCall（terminal_create/close、cmd_run，id/command 从 args 或 Go map
  文本回填）与 EventTerminalOutput（agentcli 生命周期 + 输出，含 64KB 缓冲上限、
  100 条命令历史、50 个终端上限）。
- internal/sdk/terminal.go：新增 TerminalAPI（ListTerminals/CmdHistory）与
  TerminalStatus/CmdExecStatus DTO。**不塞进 KernelStatus**：那是全量快照，
  前端每 3 秒轮询 /kernel，背上每终端最多 64KB 输出会让轮询成本爆炸；
  终端输出是按需拉取的明细，另开接口。
- Agent 订阅自己的事件总线（subscribeTerminalRegistry），且**只根 agent 建**
  （驻留子共用同一总线，每个子都建会 N+1 份重复记账）。
- SDKConfig/Registry/bootstrap 接线：pluginReg.SetTerminalAPI(agent)。

生产者补全（agentcli）：终端无输出时 ticker 不发事件，内核就无从知道终端
存在。新增 emitTermState，在 handleCreate/handleClose/readLoop 退出（超时/
进程结束/读取错误/stopCh）显式上报 running 状态，并给输出事件补 command 字段。
handleClose 改为接收 *sdk.PluginSDK 以便上报。

两个插件接（消费方）：
- WebUI：删掉本地 termStates/cmdHistory/subscribeTerminalStream/handleToolEvent
  及不再使用的 getStr；/terminals 与 /cmd/history 直接读 s.Terminal()。
- CLI：删掉上一轮刚加的 subscribeToolEvents 与 cliTermState/cliCmdExec；
  /terminals 与 /cmd/history 直接读 s.Terminal()。两条路（local/remote）都通。

测试：新增 terminal_registry_test.go，锁死 Go map 文本解析（旧缺陷根因）、
生命周期、CLI 直调路径（无 EventToolCall 仅凭 output 事件建条目）、历史与
终端数量上限。全量 go test ./internal/... ./cmd/... 通过。
 2026-09-17 18:56:15 +08:00
JianFeeeee
6afe361804 fix(memory): 记忆层启动接线/并发/落盘一致性整备 
按设计方案整顿记忆系统，收敛一批"单测照不出、只在长跑生产里暴露"的缺陷：

- 启动接线：initMemoryStack 残留 `defer distiller.Stop()`，规则蒸馏
  10min 心跳启动即死。改为由调用点 cleanup 停机，并补 Stopped() 探针 +
  TestInitMemoryStackKeepsDistillerRunning / TestStartKeepsLoopRunningUntilStop。
- L0 相关性上下文：SetDenseSpace 注入稠密空间时回填已有事件的稠密向量，
  否则旧事件走稀疏余弦、新事件走稠密余弦，同一次 Prune 里两种尺度混排。
- 文档检索：QueryScored 访问计数从读锁内写移出（-race 竞争），更新后置脏，
  优雅关停可落盘、FindColdDocs 冷度判据跨重启不再失真。
- 蒸馏管线：只 flush 未落盘记录（persisted 标记）、蒸馏成功后从 raw 文件
  删除对应行、原子写文件，修重启重复蒸馏导致 mention_count 膨胀。
- 图库：全量 Recall 加实体上限（内部整备路径，防大图整表进内存）；
  ClearSentenceID 补写锁；Commit/upsertEntity 计数语义注释澄清。
- 索引器：recalled 去重集加 FIFO 上限，防长跑进程自动注入越来越沉默。
- 文档/媒体注释修正；README 记忆层流程对齐跨模态召回。

验证：go build ./...、go vet、go test -race
./internal/memory/... ./internal/agent/core/... ./cmd/homed/... 全绿。
 2026-09-15 06:32:36 +08:00
HomeAgent Agent
4cbfdc970c perf(webui)+feat(config): 聊天记录写盘节流 + 配置库空闲页回收 
两条都是我上一封里点出、你说继续的问题。

① 聊天记录：每条消息都整段重写 → 节流合并写
   原来 persistChatLocked 每次变更就整段重写记录文件，而一轮对话会触发多次
   （用户消息、每个工具事件、收尾消息）。200 条上限下文件可达数 MB，单轮就能
   放大出几十 MB 写。文件里还留着一个 chatSaveThrottle=3s 常量——声明了但从未
   被使用（疑似上次 revert 的遗留），等于节流从来没生效。
   现在：persistChatLocked 只置脏 + 唤醒写盘协程；chatPersistLoop 去抖
   chatSaveThrottle(3s)、并以 chatSaveMaxDelay(10s) 兜底（持续输出也不会无限拖延）；
   写盘前把快照拷出来，**不持 chatMu 做文件 IO**；写失败重新标脏下轮重试。
   插件 Stop 里调 Handler.Close()：停协程 + 强制落最后一次（幂等），否则丢最后一轮。

   实测（临时实例，连发 3 条消息）：3s 窗口内记录文件**尚未创建**（节流生效）；
   SIGTERM 后文件出现且 6 条（3 用户 + 3 助手，无 LLM key 故为错误回复）全在
   ——关停落盘没丢。

② config.db：SQLite 的 DELETE 不缩文件 → 空闲页够多时 VACUUM
   新增 ConfigRegistry.MaybeCompact(minFreeBytes, minRatio)：空闲页 >= 1MB 且
   占页数 >= 25% 才做一次 VACUUM，避免每次启动都重写整库。库里是 WAL 模式，
   VACUUM 之后必须再 wal_checkpoint(TRUNCATE)，否则主库文件看着没变小。
   调用点放在插件加载**之后**（大值的搬走/删除发生在插件 Start 里，之前调没意义）。

   实测（一个刚被搬走 5MB 聊天记录的实例）：
     freelist 1288 页 × 4096B；启动日志「配置库已压缩: 5394432 -> 118784 字节」
     config.db 5,394,432 → 118,784 字节；记录文件 5,279,491 字节完好未动。

测试：TestChatPersistenceIsThrottled（节流窗口内不写盘 + Close 必落盘 + Close 幂等）、
TestMaybeCompactReclaimsFreePages（删大值后文件确实变小 + 数据完好 + 阈值不达标时不白做功）。
 2026-09-14 07:14:55 +08:00
HomeAgent Agent
0beb389223 fix(webui): 设置接口不再吐内部数据；--webui 覆盖生效；端口占用不再静默成功 
三处实测确认的缺陷：

① 设置接口整块吐出聊天记录
   plugin.webui.chathistory 是 webui 自己持久化的整段聊天记录（生产实例
   实测 5,176,016 字节），躺在插件配置表里被设置接口当普通配置项整块返回，
   前端还会把它渲染成一个巨大的文本框。
   修复：GET 跳过该键（按插件+键精确判定），PUT 直接 400，避免误改。

② CLI --webui 与 webui.listen_addr 一直是死配置
   内核原本在插件加载前写 settings["addr"]，但那时 config_<name> 表还没建
   （表只在插件注册 def 时创建），PluginSettings.Set 的 INSERT 失败，而错误被
   "_ =" 忽略了；随后插件 Start 里 RegisterDef 才建表并写入默认 :8080。
   实测：传 "-webui 127.0.0.1:18099" 仍然监听 :8080。
   修复：覆盖值改由插件自己接收（webui.SetListenOverride，loadPlugins 前调用），
   优先级 CLI > webui.listen_addr（非默认值才算显式配置）> settings["addr"]。
   实测修复后："-webui 127.0.0.1:18099" 正确监听 18099，与生产的 :8080 并存。

③ 端口被占时 webui 静默死亡
   Start 在后台 goroutine 里 ListenAndServe，先打印 "listening on" 再尝试绑定，
   失败只留一行日志，Start 永远返回 nil → 插件仍被当成加载成功。
   修复：net.Listen 同步做，失败即返回 error（交给加载器/守护），
   成功后才起 Serve，并打印真实绑定地址。
   A/B 实测（两个实例都撞生产的 :8080）：
     修复前："listening on :8080" + "server error: address already in use" + LOADED: webui
     修复后："[plugin] start webui: webui: 监听 :8080 失败: ..."，不再有 LOADED: webui

效果实测（同一实例，先注入 5,271,690 字节 chathistory）：
  GET /api/v1/settings   8,244,108 → 28,652 字节（约 1/288）
  meta 条数              5,208 → 105，幻影键 0 条
  设置页仍正常：?prefix=plugin.webui 返回 8 条 def；普通键 PUT 落库；
  校验：GET/PUT 内部键被拒；-webui 覆盖真实生效。

新增测试：TestSettingsNoCrossPluginLeak（跨插件泄漏/幻影键/chathistory 读写）、
TestListenOverrideAndBindFailure（覆盖生效 + 端口占用必须报错）、
TestResolveListenAddrPrecedence（优先级）。
 2026-09-14 06:54:16 +08:00
HomeAgent Agent
3edab0fe68 refactor(homed): main() 696 行按启动阶段拆成 25 个阶段函数 
main() 原本是一整条 696 行的启动脚本：日志、目录、记忆、配置、Lua、守护、
追踪、内核 API、文本记忆、LLM 源、文档/知识、人格、插件、Agent、ONNX、
IPC、心跳、关停全挤在一个函数里，变量跨 500 行互相引用。

现在 main() 只剩「顺序编排 + 就地交接」（**149 行**，低于 funlen 阈值 150）：
  opt           := parseFlags()
  logDir        := setupLogging(opt.dataDir)
  agentWorkDir  := ensureDataDirs(opt.dataDir)
  mem, closeMem := initMemoryStack(opt.dataDir)
  ...
共 25 个阶段调用，实现体在同包 bootstrap.go（一一对应）。

零漂移保证：
  * 阶段体逐字取自原 main，只做机械替换（`*dataDir`→参数、`memIdx`→`mem.indexer`）；
  * 原 main 的每个 defer 都换成一个在**同一位置**注册的 cleanup，
    LIFO 释放顺序不变；多资源阶段内部再按原注册顺序取反；
  * 语句级比对：原 main 的 525 条可执行语句全部有对应，无遗漏。
    仅 3 处为**有意**的结构改写（其余为同义替换）：
      1. initLuaVM / initTextMemory：「启动成功才 defer Stop」改为
         「失败返回 no-op cleanup，成功返回 Stop」——调用点语义不变；
      2. startIPCServer：同上（用 started 标志保证失败时不 Stop）；
      3. resolveBaseAPIKey：把三级兜底 API key 解析提成一个纯函数。
  * defaultPrompt 提为包级 const defaultSystemPrompt（不含版本号字面量）。

验证（A/B 实测，不是只跑编译）：
  * go build ./... / go vet ./cmd/homed/ / go test ./cmd/... ./internal/agent/... ./internal/plugin/... 全绿
  * 重构前后二进制各起一次（-data 临时目录，SIGTERM 收尾），日志集合**完全一致**：
    63 个注册工具、同名插件全部 loaded、kernel ready、插件逆序关停、'stopped'
    —— 差异仅为并发加载插件的打印顺序。

全仓非测试 Go 函数现状：≥300 行 **0 个**，≥200 行 9 个，≥150 行 16 个。
 2026-09-14 06:30:45 +08:00