|
|
4e70b8d5d8
|
refactor(module): 核心仓 Go module 路径改为 github.com/JianFeeeee/HologramAgent
批 1，不含 SDK 仓与目录改名。
- go.mod 第 1 行 module 路径
- 366 个 .go 文件的完整前缀 github.com/JianFeeeee/HomeAgent 机械替换
（857 处，仅完整前缀；展示名/注释里的 HomeAgent 字样留给批 5）
- 未改：third_party 目录名、SDK 自身 go.mod module、go.mod replace 目标、
homed/waiter 可执行名、.hmap 后缀
|
2026-10-21 12:17:19 +08:00 |
|
|
|
70f7bea4b9
|
feat(io): InjectOptions.Payload 业务字段扩展，透传到本轮 stage
## 为什么需要
QQ 的「对方正在输入中」必须只在**自己引起的** before_output 里发，且要
知道发给谁。但两条路都断了：
on_input 的 stageCtx 是局部变量（stageCtxFromInput），runStage 完就丢
before_output 的 stageCtx 是内核**新建**的（emitResponse）
⇒ 两者**不共享 Extra**
## 第一版是错的（用户指出）
我先加了 `InjectOptions.Meta` —— 那是把同一件事做了两遍。用户直接问：
「为什么又额外定义了 injectMeta，而不是包含在 inputch 的请求体中？」
查证后的真实边界：`InputEvent.Payload` **本就是通道送入内核的请求体**，
身份信息本该在那里。但 `IOInjector` 接口全是
`(source, channel, text, opts)`，插件无法给 payload 加字段 —— 所以
payload 需要一个**扩展口**，而不是一个平行的新概念。
改名为 `Payload` 还有一个实际好处：所有注入路径（HTTP/CLI/ACP）共用
同一套机制，不是注入专属。
## 内核怎么处理
注入点 opts.Payload
→ 与真 payload 合并（**内核保留键不可覆盖**）
→ emitResponse 把非保留键原样透传到 stageCtx.Extra
保留键清单 `reservedPayloadKeys` 覆盖注入路径自身写入的键
（no_memory/context_policy/recall_policy/scene_policy/cleaner_name/
priority/type/content）与内核读取的语义键。允许覆盖意味着插件能伪造
"这条不记记忆"或"这条要立即打断"——那是权限提升，不是便利。
拦截方式是**跳过**而非拒绝整次注入：插件可能只想带一个业务字段，
因顺手多写一个保留键就让整条注入失败，代价太大。
## 判据（4 条，变异 2/2 咬）
· 插件字段原样进 payload
· 保留键不可覆盖（逐个验证 11 个键）
· 空 Payload 不改变旧行为
· 保留字清单必须覆盖注入路径自己写入的键（否则新键=新提权面）
## 附带修掉的编译破坏
`internal/plugin/lua_surface_test.go` 用 `z != sdk.InjectOptions{}` 比较
零值 —— 结构体含 map 就**不可比较**，加了 Payload 后直接编译失败。
改为逐字段验证。
|
2026-10-18 17:40:07 +08:00 |
|
|
|
9b2c74bc49
|
refactor(config): 默认值单一来源 —— ConfigDef.Default，不再各调用点重复硬编码
## 起因（用户质疑）
我把 offload 的触发阈值从 5 分钟改成 1 分钟时，同一个默认值散落在四处：
defaultOffloadBusyAfter = 5 * time.Minute （agent/core 常量）
set("core.agent.offload_busy_after", "5m") （seedDBValues 播种）
reg(ConfigDef{... Default: "5m" ...}) （seedCoreDefs 定义）
GetDuration("...", 5*time.Minute) （kernelmod 读取点）
用户问：「为什么不是单一从配置读取，而是硬编码在源码中？」
答：这不是合理的分层，是重复。同一份默认值四处字面量，改一处漏两处
就是**静默的行为漂移** —— 不报错，只是某些路径用 5m、另一些用 1m。
## 改动
**① 默认值的唯一来源 = ConfigDef.Default**
GetInt/GetDuration/GetBool/GetString 新增 defDefault()：
DB 里查不到行时，从已注册的 ConfigDef.Default 取，而不是用调用方传的字面量。
调用点现在写 GetDuration(key, 0) —— 那个 0 只是「连 ConfigDef 都没注册」
时的兜底，正常路径永远用不到。
**② 删掉 seedDBValues 里 54 行重复的 set()，改由 reg() 落库**
reg() 原本只 `r.defs[k]=&d`（只登记不落库），默认值另由 set() 写一遍。
现在 reg() = registerDefLocked（登记 + 落库）。
为此抽出 registerDefLocked：SeedDefaults 已持 r.mu，直接调 RegisterDef
会自死锁（sync.Mutex 不可重入）。
**③ 8 个键必须「只登记、不播种」，新增 regMeta()**
core.agent.system_prompt 播种会把版本号冻死在 DB 里
core.defaults.llm_endpoints 空默认值
core.memory.multimodal_space.options.* provider 私有选项
第一版没有区分，一改就红了两条既有判据：
TestSeedDefaultsDoesNotSeedSystemPrompt
TestSeedDefaultsDoesNotInjectIntoLegacyInstall
后者尤其重要：老安装升级被注入新默认值 = 静默加载 1.8GB 向量模型。
**④ seeded 集合：回退只对「本次真播种过」的键生效**
这是修 ③ 过程中暴露的更根本的问题。GetXxx 无条件回退到
ConfigDef.Default 会让**老安装**读到新版本的默认值 —— 即使 DB 里
根本没有那一行。加了 seeded map 区分：
全新安装 → 键已播种 → 回退 ConfigDef.Default（正常）
老安装 → 新键没播种 → 返回零值（不注入）
## 顺带修的
offload_busy_after 的 Type 从 "string" 改成 "duration" —— 它本来就是时长，
用 string 时 WebUI 只能给文本框，拿不到时长控件。
## 判据
沿用既有判据，不新增。新写的 offload_threshold_test.go 已删除 ——
它断言「四处默认值必须一致」，方向是**鼓励重复**，与本次目标相反。
|
2026-10-18 10:16:53 +08:00 |
|
|
|
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 |
|
|
|
b4d6fcde5d
|
feat(resident): 分诊助手定位 + 残余任务由父显式决定
用户澄清（重要定性）：这不是「内核替父决定」，而是**及时反馈** ——
主 agent 忙时不该让用户干等十几分钟。子 agent 是**分诊助手**：
简单的直接处理并回复，需要主 agent 的立刻回「忙碌中，请稍候」、不勉强作答。
三处补齐：
1. 分诊助手的职责提示词（之前完全没给 ⇒ 子不知道自己为什么存在）：
两条路（直接办 / 报忙碌）、拿不准时报忙碌、必须 output_send 到原通道。
2. 驻留子继承父的 SystemPrompt（之前没传 ⇒ 子只用一句兜底文案，
拿不到「异步通道必须显式 output_send，否则回复被静默丢弃」这条铁律。
webui 这类同步通道能回是因为走 ResponseCh，掩盖了这个缺陷）。
3. 残余任务由父显式决定（用户要求）：reclaim/destroy 时子手头未处理的消息
不再由内核悄悄处置 —— 内核只负责列清楚，父用 residual=keep/drop 决定。
之前 pendingEvents 只收带 ResponseCh 的，异步（qq）残余任务完全不在内，
被销毁时静默消失、用户零反馈且日志无痕。
配套：
- scheduler.takeAllPendingEvents：取走全部未执行事件（不筛通道）
- ApplyResidual(keep|drop)：keep 转回父队列（保留 ResponseCh），
drop 逐条记日志 + 给同步调用方补终态（否则 cli/a2a 永久挂起）
- 状态面暴露 offload_owned，让父分清「我建的子」与「内核临时拉的助手」
- 工具 schema 加 residual 参数并说明 drop 的代价
这也是用户观察到的「机制很自然」的落点：分诊助手就在同一张登记表里，
父能 inspect/send/compress/reclaim/destroy，控制面 6 动作按 id 生效不区分来源。
测试 +7（残余 keep 转回且保留 ResponseCh / drop 通知同步调用方 /
空残余如实报告 / 分诊提示词 / 继承 SystemPrompt），
其中 drop 那条已实测「对着静默丢弃的旧实现会失败」。全套绿。
|
2026-09-19 17:43:16 +08:00 |
|
|
|
4f36379d1b
|
fix(offload): 转投必须保留 ResponseCh，否则同步调用方永久挂起
线上实测第二个 bug：转投生效、子也正常处理（日志各 ~3s），但 webui 的 HTTP
请求一直挂着不返回，最终 504。
根因：第一版用 InjectInputTo 转发，它会**重建** InputEvent ⇒ ResponseCh 被丢掉。
而 cli / a2a / webui 这类**同步**调用方正阻塞等这个 channel。
仓库反复警告过同一件事（Agent.Stop 的注释：「带 ResponseCh 的同步注入方
（cli / clawhubadapter 均无超时）会永久挂起」）。
修法：改走既有的跨 agent 投递原语 DeliverRouted —— 它推**原事件**，保留
ResponseCh/RequestID，只往 payload 里补转投标注。
回归测试 TestForwardKeepsResponseCh 断言**最强的那条性质**：真的等同步回执回来。
（不用「读子的 InputChan」来断言：SpawnResident 会启动子自己的调度循环，
它会与测试抢同一个 channel，那样写出来的测试是 flaky 的 —— 我第一版就是这样，
实测挂死过一次。）
已实测该测试对着错误实现会失败（10s 超时）、修后通过。
|
2026-09-19 17:16:24 +08:00 |
|
|
|
62c178eea4
|
fix(offload): 积压可能全堵在 io 输入 channel，不在就绪队列
线上实测发现上一版**永不触发**：主 agent 跑着 6×45s 的长任务、我连发 4 条消息，
scheduler 始终显示 queue=0、residents=0，转投一次都没发生。
根因：schedulerLoop 是**同步执行**任务的，所以「正忙」期间它根本回不到循环顶部
去调 pumpInbox —— 后到的输入全堆在 io.inputCh（容量 256）里，压根没进 sched.queue。
而 takeQueuedInputs 只看 s.queue ⇒ 恒取不到东西。
★ 仓库里早记过同一个坑：armStop 的注释写着「pending 是还没被 pumpInbox 搬进队列
的那一段……只数 s.queue 会得到 0（实测），配额随之失效」。我重犯了它。
修法：转投前先 drainInboxToQueue() 把 channel 里的输入搬进队列。
与 pumpInbox 的区别是**不要求 hasRoom** —— pumpInbox 满时会停下保留背压，
而转投场景恰恰是「队列空、输入堵在 channel」（调度器回不到 pumpInbox）。
队列上限仍由 enqueue 把关，放不下的给同步调用方 skipped 终态（不丢、不阻塞）。
回归测试 TestOffloadSeesInputsStuckInChannel 精确复现该现场状态：
已实测它对着修复前的逻辑**会失败**（期望 3 实际 0），修后通过 —— 是真回归测试。
|
2026-09-19 17:05:38 +08:00 |
|
|
|
4be40c316b
|
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 |
|
