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
996 Commits 5 Branches 29 Tags
eb1deab5dd8a09b19742948eff58a815ae3c0375
Commit Graph

4 Commits

Author SHA1 Message Date
JianFeeeee
eb1deab5dd feat(agent): rtchild 实时子 agent + 四类 agent 独立模型源 + 残余任务四态 
## rtchild（R1–R13）

第三种、**独立**的子 agent 类型，面向语音/视频通话：内核只要文本流，
不定音频（TTS/播放由插件负责）。

- R1  CapRT 能力位 + AgentConfig.IsRealtime；AssignRealtime 两侧校验
- R2  rtSlot 单槽覆盖（latest-wins，从不排队）
- R3  独立 ctx + rtLoop + SpawnRTChild/StopRTChild
- R4  ChatStream 逐块 → outputch(rt).Execute(text)
- R5  打断 = 原地截断，不重试
- R6  工具执行期不可打断（suppressedCancels 让守卫可观测）
- R7  普通上下文 + 窗口裁剪（旧内容不进模型，**原文保留**）
- R9  CloseRTChild → L4 信号 + rt_transcript 按需分页取
- R10 notify_parent（L4，注册一次，停即注销）
- R11 闲置零 token
- R13 rt_children 管理工具（父专属）

刻意**不做** rtPage/anchor/degraded_resets（过设计，已裁定）；
不用四级中断阶梯（preemptCooldown+同级不抢占会让 ~75% 的 rt 打断
静默退化为排队）。

## 四类 agent 各自可配模型源

core.agent.llm.{main,resident,rt,child}_provider，语义是**优先不是独占**：
该源排到候选链最前，其余源仍作回退。硬锁定会让"首选源抖一下"变成
"这个 agent 彻底不工作"，而多源回退链正是本仓为此建立的机制。
名字写错 ⇒ 回退默认源 + 记日志（不静默）。子 agent 未配置时继承父的。

★ 顺带修掉一个真缺陷：spawn.go 原来直接 a.provider.Chat()，
**普通子 agent 完全绕过 provider 回退链** —— 它是唯一绕过的地方：
默认源抖一次整条子任务就"执行失败"，而主 agent 同刻能自动换源。

## 驻留子残余任务四态 + 通道三态

残余任务：keep / takeover（接手，keep 的明确别名）/ stash（暂存到各自
原通道）/ drop。stash 必须**逐条按各自 OutputChannel 归位** —— 一个子
可能同时收 qq 和 webui，混存会让"接回 qq 的人"拿到本该给 webui 的活。

通道：release（零值，向后兼容）/ suspend（挂起，暂存保留）/ takeover
（接回父并立即释放暂存）。原来是无条件 release，于是只有两种坏结局：
通道一直没人分配（消息无人处理且无提示），或刚好被别的 agent 抢到。

一次定完不留窗口：FinishResidentWith → DestroyResidentWith →
teardownResidentWith。任一环退回不带 disp 的旧函数，disp 就被丢掉、
通道被无条件释放 —— 而 stash 的暂存正挂在那条通道上（实际踩过）。

## 修复"手写字段白名单"丢值（7 处）

同一类缺陷：不传整个结构体，而是手写一份"允许通过的字段清单"。
危险在于**写漏了不报错** —— 字段静默归零，故障出现在很远的地方。

- corehandler.go outputRegister: ChannelDef{NoMemory,Cleaner} → 整体传
- pubSdkInjectOpts: 逐字段摊平丢 ScenePolicy/SecurityProfile → 收整个 injectParams
- injectParams/injectMediaParams: 结构本身缺字段 → 补齐 + asInjectParams()
- 配套反射判据 TestSegment_RoundTripEveryField（取代手写断言，
  原判据漏了 Phase/LLMText/FinalText/ToolCalls/ExtraKeyMediaBlocks/ExtraBag）

## 压缩偏离设计

CompressResident 原为截断，与设计（LLM 摘要替换）不符。改走
PlanCompaction → summarizeForCompaction（用子自己的 provider）→
ApplyCompaction，失败回退 TrimKeepRecent。顺带修 ApplyCompaction 的
锁重入 panic 与双重解锁。

并修一处真实生产数据竞争：ctxFullSignaled 由父 goroutine 写、
子调度 goroutine 读，加 ctxFullMu。

## 判据

新增约 70 条。全部验证过能变红（变异测试），包括：
- TestSegment_RoundTripEveryField 的防腐蚀：fullStageContext 反射断言
  每个字段非零，否则新字段永远不会被覆盖（"假绿"）
- TestPreferredProvider_PutsSourceFirstAndKeepsFallbacks 成对断言
  "在首位且回退仍在"—— 只断言前者的话，硬锁定也会绿

## 判据自身的坑（两次偶发红，都不是产品缺陷）

1. SpawnResident 末尾 Start()，子会在两次 enqueue 之间取走一条
   → "暂存 0 条"。修法：cancel + waitSchedulerStopped。
   （offload_test.go 早有记录，我没先读就重踩了一遍）
2. TaskPrompt 异步投递，可能在清空队列之后才到 → "多 1 条"。
   靠探针打印内容才认出是 TaskPrompt。修法：本文件用 spawnQuietResident。

go build/vet/gofmt 干净；go test ./... -count=1 -race = 62 包 ok / 0 FAIL / 0 RACE
 2026-10-30 17:00:47 +08:00
JianFeeeee
3f834794c5 refactor: SDK module 路径统一改为 hologramagentsdk（59 文件 + go.mod） 
## 为什么必须做

SDK 仓（独立仓库）已把 module 从 `github.com/JianFeeeee/homeagentsdk`
改名为 `hologramagentsdk`。主仓通过 `replace` 直接引用它的**物理目录**：

    replace github.com/JianFeeeee/homeagentsdk => ./third_party/homeagent-sdk

一旦 SDK 侧改成新 module 名，主仓立刻炸：

    go: ./third_party/homeagent-sdk@ used for two different module paths
        (github.com/JianFeeeee/hologramagentsdk and github.com/JianFeeeee/homeagentsdk)

Go **不允许**同一目录被两个 module 路径 replace。所以不能"新旧并存"，
只能把主仓 59 个文件的 import 全部改到新名，并删掉旧 replace。

## 一个被证伪的前提

我最初按"third_party/homeagent-sdk 是独立仓库，不能在此仓修改其源码"
来处理，并因此判断两个仓的改动可以隔离。实际上主仓是靠 `replace` 指向
该目录的物理副本 —— **两个仓的改动不可能真正隔离**：SDK 侧改 module 名，
主仓必然跟着改 import。

这个前提应该在做任何改动之前用 `go list -m` 验证，而不是假设。

## 连带修掉两处

| 缺陷 | 性质 |
|---|---|
| `TestLuaSDKMockSingleSource` 失败 | SDK 的 `sdk/lua/sdk.lua` 变了，主仓内嵌副本未同步（跑 `scripts/sync-lua-sdk.sh` 修复） |
| `sdkModuleNames` 分散两处 | 已在 SDK 仓合并为单一数据源（见 SDK 仓 725732b） |

第一条是**副本一致性判据抓到的**，不是我自己发现的 —— 这类判据的价值在此：
两个仓必然有副本，靠人记住"改了 A 要同步 B"是做不到的。

## 验证

- `go build ./...` / `go vet ./...` 干净
- `go test ./... -count=1`：**58 包 0 失败**
- `internal/plugin`（Lua SDK 副本一致性）+ `internal/sdk` 全绿
- 主仓 `third_party/homeagent-sdk/` 与 SDK 仓 `main` 无差异
 2026-10-23 15:51:02 +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
6b47d185ac feat(plugin): entry 双通道分派 + 共享内存 stage 数据面（Part 1 + Part 4 核心） 
Part 1 加载分派骨架（迁移可逐插件推进、随时回退的前提）:
- dynamic.go: 新增 binEntry/skillEntry 常量 + entryKind 枚举 + classifyEntry/detectEntryKind
  manifest entry 优先级最高（改回 plugin.so 即回退 cabi）；无 manifest 时按目录探测，.bin 优先
- registry.go: tryDynamic 按 entry 分派 proc/cabi 双通道；
  entry 声明 .bin 但二进制缺失时报明确错误，不静默回退（否则'已迁移插件跑回旧通道'极难排查）
- registry.go: pluginEntryHash 候选顺序与 detectEntryKind 对齐（.bin 优先），
  否则增量重载会用错文件算 hash
- dynamic_proc_{unix,windows}.go: tryLoadProc 桩位（权限/类型校验已实现，进程管理属 Part 2）

Part 4 共享内存数据面（迁移评估 §3.3/§3.4/§3.7，最关键一环）:
- proc/shm.go: 段布局（Header + ShmStageCtx 描述符数组 + append-only arena）
  相对偏移设计——各进程 mmap 到不同虚拟地址仍能正确解引用
  arena 用尽显式报错而非静默截断（§4.4 风险登记）；Compact() 回收 append-only 垃圾
- proc/shmcodec.go: StageContext 16 字段跨进程编解码
  字段级描述符消除 lost update：只改 FinalText 的插件不触碰 ToolResults 描述符
  WriteDirty 只写脏字段——只读插件零写入，不可能覆盖他人改写
  Snapshot 存序列化字符串（切片共享底层数组的坑，C ABI 侧修 11.3 时已踩过）
  Extra 4 键提升为具名字段；Response 用标志位表达 nil vs 空串
- proc/lock.go: 锁仲裁回归内核（§3.7 已裁定，零 cgo）
  ForceRelease 实现实验 9 的崩溃自愈——排除 robust pthread_mutex 必要性
  重复加锁显式拒绝（否则死锁 30s）；等待超时有补偿 goroutine 防锁泄漏

验证:
- proc 包 16 项测试全绿（含 -race）：全字段往返/只读零写回/原地改切片识别/
  现网 sanitizer+weather 场景/5插件×40轮并发零丢失/arena 耗尽报错/压实不破坏字段/
  锁互斥·串扰拒绝·崩溃自愈·临界区串行化
- entry 分派 9 项测试全绿；go build ./... exit 0；接口冻结 git diff sdk/ 为空
 2026-09-02 10:41:18 +08:00