mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-11-05 16:57:32 +00:00
67be11464784d4df2b1f2bc5916cb3b3f6832ab4
5 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
| cc0eb51286 |
refactor(kernel): 统一挂载点 kstate + 插件声明式系统提示词段
## 起因（生产故障）
A2A 分诊助手（驻留子）把 terminal_create 当一次性命令执行器：
terminal_create(command='cd /usr/lib/node_modules/@deepseek-ai && ls -d */ | head -60 && …')
→ read /dev/ptmx: input/output error
→ 再开 term_7、term_8、term_9 …
链路拆开四层：
① cmd 插件 auto_start=false ⇒ 工具表里没有 cmd_run
② 需要 cmd-tools skill 说明"先 plugin_start cmd"
③ 但 skill 索引没进那个 agent 的提示词
④ 因为 skillIndex 只是根 agent 的字段、由 bootstrap 手工接线
④ 才是总根。而它之所以必须手工接线：agent/core 读不到内核的共享数据。
## 环的精确形状（实测，非推测）
kernelboot 因为持有 KernelState 而依赖 19 个业务包：
kernelboot ──▶ agent/core ──▶ …
──▶ plugin
──▶ security
──▶ memory / knowledge / text / coldcontext / …
而 kernelboot.go / scheduler.go / funcmodule.go / syncbus.go / lifecycle.go
**一行业务代码都不需要** —— 依赖全在 kernelstate.go 这一个数据文件里。
后果是四个底层包各自造通道：
core → Agent 字段（每种 agent 构造点都要记得传）
plugin → 12 个 SetXxx
sdk → SDKConfig 传参
security → 包级单例 Global() / RuntimeGlobal() / ConfigCodec()
四条通道是同一个根因的四个表现。
## 本次做的事
### 1. 抽出 internal/kstate（断环）
kernelstate.go / syncbus.go / lifecycle.go 搬出 kernelboot：
internal/kstate 纯数据 + 唯一挂载点（叶子，谁都能 import）
internal/kernelboot 装配引擎，零业务包
挂载点 API：Mount / Get（nil 安全）/ MountForTest（返回 restore，并行测试隔离）。
验证：core 现在能 import kstate（此前 import cycle not allowed）。
### 2. StageHost / Agent 字段存 any
它们是 core 自己的类型（core 是环的一极，这是真环）。按用户裁定的方向：
> 是其他包在kstate挂共享内容啊
存 any，消费方断言回具体类型 —— 与本仓既有的 PluginCatalog /
PluginScheduler / UpdateCapabilities 同型。
★ 其余字段保持**具体类型**，没有一律改 any。判据是"它会不会反向依赖
agent/core"：实测 plugin / security / sdk 都不依赖 core，所以它们作为
具体类型不构成环，而类型化字段让"拼错/取错类型"是编译错误（本结构体的
设计原则）。
### 3. 插件声明式系统提示词段
SDK 新增 SystemPromptAPI（见 submodule 提交）。内核侧：
kstate.State.PromptSections *promptsec.Registry ← 唯一事实来源
Agent.renderSystemPrompt() 每轮重建时读它
skillmgr 从"实现 SkillIndexProvider 让内核来问"改为"声明自己的段"：
DeclarePromptSection{Section:"skillmgr.skills", Order:100, Volatile:true}
并挂到全部变更点（启动全扫后、移交事件后、load/unload/create/install/
enable/disable 后、Stop 时撤销）。
### 4. 内核自身的提示词段也走同一管理器
按用户裁定「把现在内核所有 systemprompt 的相关注入都接入到这个统一的
systemprompt 管理器上」，把 buildSystemPrompt 里硬拼的十几块
（人格卡/任务提示词/记忆说明/输出规则/工具目录…）改为声明式：
kernelSections() 当轮计算 → 与插件段按 Order 合并渲染。
顺序由 Order 常量决定，改结构变成调常量而不是挪代码块。
## 判据（均经变异验证）
TestCoreCanImportKstate 真编译探针；环重现则红（实测）
TestKstateDoesNotDependOnCore 静态版，指向具体字段
TestKstateIsLeaf kstate 不得反依赖上层
TestRTChildSeesPromptSections 子 agent 能看到插件段
TestResidentSeesPromptSections 生产实际中招的那一类；变异后红（实测）
TestRootAgentSeesPromptSections 确认没改坏根路径
TestNoPromptSectionsMount 未装配时不 panic、不凭空出现段
TestDeclareTwiceRendersOnce ★ 回应"会不会多份"：声明 5 次渲染 1 份
TestSectionRemovalTakesEffect Stop 后段消失
TestRuntimeUpdateVisibleToExistingAgent 同一实例下一轮看到新内容
TestSectionOrderIsRespected Order 生效且稳定
## 验证
go build ./... PASS
go vet ./... PASS
gofmt -l internal/ cmd/ pkg/ 干净
go test ./... -count=1 63 包全过，0 FAIL
干净检出（git worktree） build + 4 包测试全绿
## 未做（见 kernelplan.md）
T3 security 三单例收敛（含 Store 复用 Codec 的惰性迁移）
T5 plugin Setter 收敛
T6 防腐判据（部分已随本次落地）
|
|||
| f9ee58a914 |
merge: pr31 — update 回滚安全（原子写 + 回读校验），解 19 处冲突
pr31 与 main 是**双向分叉**，不是单向落后。`ba281a8` 已把它的多数工作
在 main 上重新实现（dataDir 守卫、gc.go、dataDir 解析），但两边各自又
往前走了，所以 6 个文件 19 处冲突要逐条判。
## 合进来的（main 缺）
- **标记原子写**：main 是 `os.WriteFile` 直接覆写，掉电留半截标记；
改为 `写 .tmp → fsync → close → rename → fsync 目录`
- **H4**：`publishResult` 里 `if errMsg != "" { _ = errMsg }` 把失败原因
丢了，订阅方只看到 ok=false。现在 error 字段恒定存在
- **回读校验补最低可用性**：main 对无 digest 的旧 marker 只比"内容与备份
一致"，而**零字节备份内容也一致** ⇒ 判成回滚成功、不清 marker 的时机
也错过了。补"非空 + 带可执行位"，刻意**不**要求 `--version`
（老内核没这个 flag，那正是 PR #31 的回归）
- `kernel_apply_test.go`（836 行，含 B2c `TestMarkPendingUpgrade_PreservesOldMarkerOnFailure`）
## 保留 main 的（pr31 在这几处是旧版或更差）
- **回滚校验用 digest**（`verifyRestored`）而不是 `--version`：
pr31 要求回滚后能读版本，而 1.3.x 及以前没有 `--version`，
而它们恰恰是最常见的回滚目标 ⇒ 从旧版升级失败后永久回滚不了
- **`restoreDepGraph` 三态**：原来有+备份有→还原、原来有+备份无→不算成功、
原来无→删掉新装的。pr31 只处理第一种，会导致「旧 homed + 新 depgraph」
的崩溃循环
- **marker 在还原完整后才清**：pr31 在还原前就清，还原失败即失去第二次自愈
- **CLI 不重启服务**：pr31 仍带 `restartUnit`，会杀掉整个 cgroup 连带 guard
- **`resolveDataDir`**：pr31 的 `upgradeDataDir` 是它的子集，多扫几个候选前缀
## 冲突处理中的三处重复声明
两边各加了同名函数，自动合并把它们都留下了：
- `readBinVersionStrict` —— 删 pr31 的（main 在 77 行有）
- `kernelDataDirMu/kernelDataDir/SetKernelDataDir/KernelDataDir` —— 删 kernel.go
里那份（main 在 install.go）
- `newPkgRoot` —— pr31 的重命名 `newPkgRootFromBin`，两套测试各自可用
- rollback.go 里 `verifyRestored` 与 `readBinVersionStrict` 两段校验并存 —— 删后者
顺带修掉删除时误伤的 `ShortSum` 注释，并删掉 pr31 引入但无人调用的
`DataDirEnv`（main 明确不再拿 env 当 dataDir 来源）。
## 验证
go build ./... ✓
go vet ./... ✓
go test ./... -count=1 62 ok / 0 fail
go test -race ./internal/update/ ... ✓
gofmt -l 干净
|
|||
| ba281a855a |
feat(update): 差分 OTA + 安装形态分派 + 事件总线统一受安全监控
三条主线，由 e2e 实测驱动。 ## 一、差分 OTA（internal/update/delta.go） 实测：改一行逻辑，88MB 的二进制逐字节只差 80 字节，而 OTA 一直下整包。 用 rsync 族的滚动哈希块匹配（4KB 粒度），不是 bsdiff —— 后者需 17×N 峰值内存（88MB → 1.5GB），而升级恰可能发生在内存紧张时。 真实二进制实测：88,036,728 字节 → 补丁 77,316 字节（0.088%）。 三道闸：应用前验旧文件 sha256（错基线会静默产出垃圾）、应用后验结果 sha256、COPY/LITERAL 越界防护。任何失败**退回整包**，不向上抛 —— 差分是优化，不是可用性前提。 接入：Source.Resolve 优先试 delta；CheckRelease 按 -from-<commit8>.delta 匹配（不猜基线）；CLI 新增 -make-delta；打包脚本 build_delta（需 PREVIOUS_HOMED），delta 进 SHA256SUMS。 ## 二、安装形态分派（internal/update/install.go + channel.go） 内核对「能不能自己升级」此前只有一个答案：直接替换二进制。而 deb/rpm 形态下那样做会让 dpkg/rpm 数据库与实际内容不一致（下次 apt upgrade 覆盖回旧版，或 dpkg 拒绝后续升级）。 新增探测：deb/rpm/tar/container/source 五类形态 + 变体（full/server/ client/toolchain）+ 目录写权限。判据全部来自可观测系统事实（dpkg 的 info 目录、容器标记文件），不做路径推断。 三端统一走 PlanUpgrade 分派；形态闸门放在**下载 880MB 之前**。 ## 三、事件总线统一受安全监控（internal/events + security） 用户指正：「eventbus 上所有事件都要接受安全模块的监控」。 此前 EventPolicy 只被 internal/sdk/events.go 调用，而那是四条路径中的 一条。s.Publish / s.Subscribe / s.EventBus() 拿的是裸 *events.Bus， 任何插件都能绕过策略发任意事件（含伪造内核事件）。 现在闸门在 Bus.Publish/Subscribe 本体上（Guard 接口注入，避免 events ↔ security 成环），四条路径全部覆盖。sdk.EventBus() 改返回带身份的 BusHandle。内核身份免授权，但载荷照样过凭据闸门。 白名单按主体收窄：agent_output/stage/terminal_output 只允许承载者 （webui/cli/agentcli）发布 —— 它们是内核向外的输出面，谁都能发就等于 能伪造 agent 说的话。 ## e2e 暴露并修掉的三个真实回归 [bus] subscribe denied: pluginmgr type=update_request [bus] subscribe denied: skillmgr type=skill_detected 前两个让升级请求静默丢失、职责链交接断掉。内部协作事件必须可订阅 （安全边界在发布侧，订阅只是「听得到」）。 ## 顺带的止血修复 - 回滚判据从 `--version` 改为 digest：旧内核（1.3.x 及以前）没有该 flag，而它恰是最常见的回滚目标 —— 原逻辑让「从旧版升级失败」永久 无法回滚。 - CopyFile 补 fsync（替换 homed 本体时掉电会留半截文件）。 - restore 完整还原才清 marker（原先先清再还原，还原失败就失去第二次 自愈机会）。 - 回滚时移除升级中新增的 depgraph（否则「旧 homed + 新 depgraph」 会因 digest 不匹配崩溃循环）。 - homed-upgrade 不再硬编码 systemctl restart（丢 guard 状态、unit 名 漂移）；改用内核已有的 restartCh → exit 42 语义。 - homed-upgrade 不再用 CGO_ENABLED=0 编却依赖 go-sqlite3（stub 下 静默失效，该路径从未工作过）；改用 internal/config。 - 服务单元补 User=hologramagent + 三条安装路径补建用户（此前发行物里 完全没有落实降权）。 - rpm 的 fpm 调用补 --after-install（此前 rpm 装完根本不建用户）。 ## 判据 新增 30 条：差分 8（往返/压缩比/错基线/截断/篡改/边界）、通道 8、 执行器 6、事件闸门 8、按主体授权 8。全仓 go test ./... 0 失败。 |
|||
| 1319d6619c |
fix(update): dataDir 取内核权威源 + 回滚可信校验 + marker 原子写
承上一个 commit（回退 85fd38b）。本 commit 是 R2 主体：B0/B1/B2 三项修复，
以及为 P1–P4 补齐的**行为级**判据。
━━━ B0 · dataDir 不再推导，取内核真实 -data ━━━
`internal/update/kernel.go`
· 删除 ResolveDataDir（env → `<exe>/data` 兜底）。
· 新增 SetKernelDataDir / KernelDataDir：值由内核适配层在启动时
用 ks.DataDir 注入。进程内调用方（pluginmgr / webui）直接取，
不做任何推导；取不到返回**空串**。
· DataDirEnv 保留但降级为诊断参考（不再是合法来源）。
`internal/kernelmod/update/mod.go`
· Init 里 upd.SetKernelDataDir(ks.DataDir)；为空时打响亮告警
（不阻断启动 —— 第 0 层职责是回滚判定，不是参数校验）。
`internal/plugins/pluginmgr/kernel_update.go`、`internal/plugins/webui/kernel_update.go`
· kernelDataDir / dataDirOf 都改为 return update.KernelDataDir()。
`cmd/homed-upgrade/main.go`
· upgradeDataDir(explicit)：① `-data <dir>`；② config.db 的
core.daemon.data_dir（只读连接 + PRAGMA query_only=1，不建表不迁移）。
· 两者都拿不到 ⇒ 返回空串 ⇒ `-apply` 在动手之前就 fail 并说明怎么修。
→ 这样 P1 的空值守卫重新变成**活的**：拿不到真实 dataDir 就真的会拦。
━━━ B1 · 回滚可信：回读校验是唯一判据（判据 B1）━━━
`internal/update/rollback.go` — RollbackIfUnconfirmed
· rollback.go:315 `rb, verr := readBinVersionStrict(binPath)`
替换后**必须**回读成功且 rb.Version == rec.FromVer，否则
rolled=false + error + **不清 marker**（下次启动再试，并让人看到日志）。
CopyFile 返回 nil 只代表字节搬完了，不代表搬过去的东西能执行。
· rollback.go:254 确认分支同样改用 readBinVersionStrict。
这里曾经用 ReadBinVersion —— 它含 InferVersionFromRunning 回退，
已实测：binPath 是不可执行残文件、marker.ToVer 恰好等于本机 waiter
版本时，会从 waiter **借到**版本号 ⇒ confirmed=true ⇒ 清 marker、
不回滚 ⇒ 机器带着跑不起来的二进制继续启动且失去自愈机会。
该缺陷环境相关（CI 没装 homed/waiter 会绿），故判据不能依赖本机环境。
· 备份缺失 / 回读失败 / 版本不符 / depgraph 回滚失败 —— 四种情形
一律不清 marker。
· 新增 readBinVersionStrict（kernel.go）：只认「这个文件自己能报出版本」，
无任何回退；ReadBinVersion 改为其包装器（保留探测用回退），
注释写明它**不能**用作回滚校验。
━━━ B2 · marker 原子 + 损坏不卡启动（判据 B2）━━━
`internal/update/rollback.go` — MarkPendingUpgrade
· 旧实现 os.WriteFile 直接覆写（O_TRUNC），掉电留半截 JSON。
· 现改为：写 <path>.tmp → fsync(文件) → rename(原子) → fsync(目录)。
目录 fsync 失败仅告警（容器/tmpfs 下 EINVAL 不该阻断升级）。
rollback.go:112 `if err := f.Sync(); err != nil {` 即这条链路的第一道闸。
· RollbackIfUnconfirmed 遇到解析不了的 marker：quarantineMarker 改名
留存（不删，保留现场）+ 告警 + return false,"","",nil
⇒ 当作「无待确认升级」继续启动。把内核卡在启动阶段是最差选择：
能执行到这行已证明当前二进制可执行。
`internal/kernelmod/update/mod.go`
· 补注释钉住语义：rerr != nil 必须中止启动；但 marker **损坏**不算
失败（已由 RollbackIfUnconfirmed 吞掉并改名留存）。
━━━ 判据补齐（行为级，修掉 M6 真空洞）━━━
`internal/update/kernel_apply_test.go`
· P1 TestApplyRefusesEmptyDataDir 加强：切到 t.TempDir() 并拍快照，
断言拒绝升级时**根本没写任何文件**（旧用例只查「目标二进制没变」，
把守卫挪到预检之后依旧绿 —— 因为 filepath.Join("", prefix) 会把
备份目录建到 CWD）。
· P3 新增 TestApplyPrunesOldBackups：预置 5 个历史备份后跑真实 Apply，
断言旧的被 GC。★ 这是补 M6 的真空洞 —— 旧的变异脚本只跑
`-run TestPruneOldBackups`（只证明函数能跑，3 毫秒），把 Apply 里
那一行 PruneOldBackups(dataDir) 删掉它照样绿；新脚本必须同时跑
TestApplyPrunesOldBackups，删掉调用后立刻报红。
「函数能跑」≠「Apply 真的调了它」。
· B1 新增 TestRollback_RefusesCorruptBackup（零字节/坏备份 ⇒ 必须
回滚失败且不清 marker）、TestRollback_RefusesVersionMismatch
（备份版本 ≠ FromVer ⇒ 同样失败）、
TestRollback_ConfirmedBranchIgnoresInferredVersion 与
TestConfirmedBranch_StrictProbeBitesOnUnparseable（确认分支不得
使用推断值；用可注入的 inferHomedPath/inferWaiterPath 造出
「能借到版本」的场景，不依赖本机是否装了 homed/waiter）。
· B2 新增 TestMarkPendingUpgrade_IsAtomic、
TestRollback_CorruptMarkerDoesNotBlockBoot。
`internal/update/rollback_test.go`
· TestRollback_RestoresBackup / TestRollback_RollsBackWhenRunningOldVersion
的备份从纯字节 "OLD-GOOD" 改为**真正可执行**的假二进制（1.4.0），
并按版本而非按字节断言。旧的写法只能测「字节搬对了」，测不到
「搬过去的东西能跑」—— 而后者才是回滚能救机器的前提。
`internal/update/kernel.go`
· inferHomedPath / inferWaiterPath 提为包级变量（生产默认值不变），
唯一目的是让「确认分支不得使用推断值」这条判据可稳定复现。
━━━ 判据锚点自检（grep -F 命中数均为 1，行号已核对）━━━
P1 kernel.go:348 if dataDir == "" {
P2 kernel.go:370 backup := filepath.Join(dataDir, BackupDirPrefix+ts)
P3 kernel.go:449 PruneOldBackups(dataDir)
P4 kernel.go:445 publishResult(bus, "kernel", "", true, …)
P4 events.go:69 "error": errMsg,
B1 rollback.go:254 if cur, cerr := readBinVersionStrict(binPath); cerr == nil {
B1 rollback.go:315 rb, verr := readBinVersionStrict(binPath)
B2 rollback.go:112 if err := f.Sync(); err != nil {
验证：go build ./... 通过；go test ./internal/update/ 通过。
|
|||
| d17e261b76 |
feat(update): update 注册为内核标准模块（第 0 层）+ 启动失败自动回滚
## 为什么必须是第 0 层（用户口径） update 肩负「启动失败回滚上一次升级」的职责，该职责必须**早于所有模块**。 若排在后面：升级后新内核在 memory/llm 阶段崩了，而回滚还没跑 ⇒ 机器进 崩溃循环，只能靠 guard 的 failback（受限启动）兜底。failback 是最后手段， 不该承担"换错二进制"这种**已知可回滚**的故障。 ⇒ Requires() 为空 ⇒ 依赖图天然把它放 Layers[0]。 ## 两段式升级确认（rollback.go） 升级成功 ──→ 写 pending 标记（"这个版本尚未被确认能启动"） ↓ 重启 → 内核启动 → update 模块（第 0 层）读标记 ↓ ┌────────────┴────────────┐ 标记还在 标记已不在 （上次升级没能活到清除） （上次升级已确认成功） ↓ ↓ 回滚到备份版本 正常继续 + 清标记 清除时机：模块跑完自检后立刻清。只依赖"进程活着且执行到第 0 层"， 不依赖其他模块 ⇒ 不会误判。 **为什么不用 TTL / 重启次数**：那是 guard 已有的 failback，但判据是 "崩了几次"，不是"这次升级该不该撤销"。用重启次数会在"新版本偶发崩溃"时 误回滚 —— 而那种情况该修的是崩溃，不是回退版本。 ## 分层（与仓库其他模块同一惯例） internal/update/ 业务实现（三端共用：CLI/WebAPI/agent 工具） internal/kernelmod/update/ 适配层（读 ks → 调业务包 → 写回 ks） 参照 supervisor 模块：实现在 internal/supervisor，模块里只做装配。 分开的理由：internal/update 被三端调用，它们都没有 KernelState。 ## 标记写入时机（一个真实的顺序坑） MarkPendingUpgrade 在**替换二进制之前**调用。反过来（替换后才写）会在 "替换成功但没来得及写标记就崩了"时丢标记 ⇒ 下次启动不知道该回滚。 且写标记失败 ⇒ **放弃本次升级**（未替换任何文件）：没有标记就没有回滚 能力，而不带回滚的升级等于赌运气。 ## 回滚失败必须响亮 备份不存在时返回 error，调用方（模块 Init）必须中止启动 —— 继续装配等于 用一个已知起不来的版本。错误文案带备份路径与标记路径（删标记即可放弃回滚）， 人能照着修。 ## 判据 internal/update/rollback_test.go 10 条，2 条经变异验证： · TestRollback_RestoresBackup —— 二进制+depgraph 同批回滚、标记清除、 坏版本留档 homed-broken-*、版本轨迹记录 变异：回滚后不清标记 ⇒ 红 · TestRollback_MissingBackupIsLoud —— 备份缺失时报错且可执行 变异：静默返回 nil ⇒ 红 · TestPendingMarker_AbsentIsNotError —— 无标记返回 (nil,nil) 而非 error （否则每次启动都走"回滚失败"分支 ⇒ 内核永远起不来） · TestPendingMarker_CorruptIsActionable —— 标记损坏时提示可删 · TestStateSummary_* —— 回滚信息进 healthcheck；nil 安全 ## 顺带修正的既有判据 · runtime_dep_test.go：L0 设施集合从 2 个变 3 个（新增 kernel.version）， 改为断言**集合**而非顺序（注册表本就是乱序的） · facilities.go：新增 FacVersion，并登记为 internalOnlyFacilities （它是启动时序事实，不是插件契约 —— facilities_sync_test 的守卫正确拦住了 "把内部标记泄漏成对外契约"） 三个 DoUpgrade 调用点补 dataDir 参数（标记落点必须与内核 --data 一致）。 |
