mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-11-05 16:57:32 +00:00
cc0eb51286
## 起因（生产故障）
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 防腐判据（部分已随本次落地）
102 lines
3.7 KiB
Go
102 lines
3.7 KiB
Go
package kstate
|
||
|
||
// 内核统一挂载点：本进程唯一的公共数据持有者 + 它的存取入口。
|
||
//
|
||
// ## 用户设计（本包存在的理由）
|
||
//
|
||
// > 内核通过一个结构体收集全部包级共享变量，其他模块通过这个结构体访问数据，
|
||
// > 各个模块的公共数据也统一注册到内核这个公共结构体中。
|
||
//
|
||
// > 结构体成员初始置 nil 加读取前检查不就好了
|
||
//
|
||
// > 所有共享数据统一挂载一个 kernel 提供的挂载点上暴露。
|
||
//
|
||
// ## 为什么本包必须与装配引擎分开（2026-11-04 拆分）
|
||
//
|
||
// 拆分前 `KernelState` 与装配引擎同居 `internal/kernelboot`。数据结构要认识
|
||
// 各业务类型（`*security.Runtime`、`*plugin.Registry`、`*agentCore.StageHost`…），
|
||
// 于是 `kernelboot` 被迫依赖 **19 个业务包**：
|
||
//
|
||
// kernelboot ──▶ agent/core
|
||
// ──▶ plugin
|
||
// ──▶ security
|
||
// ──▶ memory / knowledge / text / coldcontext / …
|
||
//
|
||
// 而装配引擎本身（kernelboot.go / scheduler.go / funcmodule.go）
|
||
// **一行业务代码都不需要** —— 依赖全在数据结构这一个文件里。
|
||
//
|
||
// 后果是所有被依赖的包都无法反向引用 kernelboot，于是它们各自造通道：
|
||
//
|
||
// core → Agent 字段（靠每种 agent 构造点记得传）
|
||
// plugin → 12 个 SetXxx
|
||
// sdk → SDKConfig 传参
|
||
// security → 包级单例 Global() / RuntimeGlobal() / ConfigCodec()
|
||
//
|
||
// 四条通道都指向同一个根因。把数据结构搬出来（本包），环就断了：
|
||
//
|
||
// kstate ← 纯数据，谁都能 import（它就是挂载点本身）
|
||
// kernelboot ← 装配引擎，零业务包
|
||
//
|
||
// ## 并发约定
|
||
//
|
||
// 状态结构体上的字段**不加锁**（用户设计）：同层模块并行 Init 时各自只写
|
||
// **自己那一个字段**，字段互不相同 ⇒ 无数据竞争。读方直接读字段 + 判 nil。
|
||
//
|
||
// 但**挂载点本身**要加锁：它是全部调用方共同读的单一变量，而装配期写入
|
||
// 与运行期读取必然跨 goroutine（`Mount` 在启动时一次，`Get` 在热路径）。
|
||
|
||
import "sync"
|
||
|
||
var (
|
||
mountMu sync.RWMutex
|
||
mount *State
|
||
)
|
||
|
||
// Mount 装入本进程的挂载点。**装配期调用一次**（由 kernelboot 的 Run 完成）。
|
||
//
|
||
// 重复调用会覆盖：便于测试与热重启路径（后装的生效）。
|
||
func Mount(s *State) {
|
||
mountMu.Lock()
|
||
mount = s
|
||
mountMu.Unlock()
|
||
}
|
||
|
||
// Get 取挂载点。未装配时返回 **nil**（不 panic）。
|
||
//
|
||
// ★ 为什么返回 nil 而不是空结构体：调用点散布在内核热路径上，未装配
|
||
// （单元测试、独立工具如 memgc）时必须**零成本跳过**。所有调用方写成：
|
||
//
|
||
// if ks := kstate.Get(); ks != nil && ks.Xxx != nil { … }
|
||
//
|
||
// 返回空结构体看似更"安全"，实则让"未装配"与"装配了但字段为 nil"两种
|
||
// 完全不同的情况混为一谈 —— 前者是环境问题，后者是装配缺陷。
|
||
func Get() *State {
|
||
mountMu.RLock()
|
||
defer mountMu.RUnlock()
|
||
return mount
|
||
}
|
||
|
||
// MountForTest 装入一个测试用挂载点，返回**恢复函数**。
|
||
//
|
||
// 测试里必须这样写：
|
||
//
|
||
// restore := kstate.MountForTest(fake)
|
||
// t.Cleanup(restore)
|
||
//
|
||
// 为什么不直接用 Mount：并行测试（`t.Parallel()`）会互相覆盖全局挂载点，
|
||
// 表现为随机红——而随机红是判据可信度的头号杀手（本仓已有教训：
|
||
// 判据在 -race 下才暴露竞态）。恢复函数让每个测试回到"进入前的状态"
|
||
// 而不是"nil"，嵌套/串行测试也正确。
|
||
func MountForTest(s *State) (restore func()) {
|
||
mountMu.Lock()
|
||
prev := mount
|
||
mount = s
|
||
mountMu.Unlock()
|
||
|
||
return func() {
|
||
mountMu.Lock()
|
||
mount = prev
|
||
mountMu.Unlock()
|
||
}
|
||
}
|