mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-11-05 16:57:32 +00:00
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 防腐判据（部分已随本次落地）
This commit is contained in:
JianFeeeee
@ -12,6 +12,7 @@ package pluginhost
|
||||
// ④ 关键顺序：failback 白名单必须在插件拉起前生效
|
||||
|
||||
import (
|
||||
"github.com/JianFeeeee/HologramAgent/internal/kstate"
|
||||
"go/ast"
|
||||
"go/parser"
|
||||
"go/token"
|
||||
@ -311,8 +312,8 @@ func TestCatalogConcurrentRead(t *testing.T) {
|
||||
// ⇒ 判据：把 typed-nil 传给 Scheduler 前必须已被拦截。
|
||||
// 这里直接验证**拦截逻辑本身**（不依赖 produciton 装配）。
|
||||
func TestNilSyncBusDoesNotPanic(t *testing.T) {
|
||||
var nb *kernelboot.SyncBus // typed-nil
|
||||
var iface kernelboot.SyncState = nb
|
||||
var nb *kstate.SyncBus // typed-nil
|
||||
var iface kstate.SyncState = nb
|
||||
if iface == nil {
|
||||
t.Skip("接口就是 nil（不会有陷阱）—— 与本判据的前提不符")
|
||||
}
|
||||
@ -378,7 +379,7 @@ func TestUndeclaredPluginsWaitForKernelComplete(t *testing.T) {
|
||||
t.Fatalf("两个自动启动插件都应进调度器（含**未声明**的），实际 %d 个", len(specs))
|
||||
}
|
||||
|
||||
bus := kernelboot.NewSyncBus()
|
||||
bus := kstate.NewSyncBus()
|
||||
bus.MarkDeclared([]string{"config", "agent"})
|
||||
bus.MarkReady("config")
|
||||
|
||||
|
||||
@ -2,6 +2,8 @@ package pluginhost
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"github.com/JianFeeeee/HologramAgent/internal/kstate"
|
||||
sdk "github.com/JianFeeeee/HologramAgent/internal/sdk"
|
||||
"log"
|
||||
"os"
|
||||
"path/filepath"
|
||||
@ -44,7 +46,7 @@ func (Module) Requires() []string {
|
||||
|
||||
func (Module) Provides() []string { return []string{FacPlugins} }
|
||||
|
||||
func (Module) Init(ks *kernelboot.KernelState) error {
|
||||
func (Module) Init(ks *kstate.State) error {
|
||||
// ── 前置检查（用户要求："nil 加读取前检查"）──
|
||||
if ks.PluginRegistry == nil || ks.StageHost == nil {
|
||||
return fmt.Errorf("plugin-host：ks.PluginRegistry/StageHost 为 nil —— " +
|
||||
@ -111,8 +113,8 @@ func (Module) Init(ks *kernelboot.KernelState) error {
|
||||
//
|
||||
// 这样声明的插件仍在依赖就绪时尽早启动（本步的核心收益不变），
|
||||
// 而未声明的**恢复原行为**（等内核完全初始化）。
|
||||
var bus kernelboot.SyncState
|
||||
var busConcrete *kernelboot.SyncBus // 保留具体类型以便订阅 OnUpdate
|
||||
var bus kstate.SyncState
|
||||
var busConcrete *kstate.SyncBus // 保留具体类型以便订阅 OnUpdate
|
||||
if ks.SyncBus != nil {
|
||||
bus = ks.SyncBus
|
||||
busConcrete = ks.SyncBus
|
||||
@ -122,7 +124,7 @@ func (Module) Init(ks *kernelboot.KernelState) error {
|
||||
// 所以这里必须显式判 `!= nil` 再赋给接口变量。
|
||||
log.Printf("[pluginhost] warning: SyncBus is nil -- non-production assembly path, " +
|
||||
"退化为立即加载（依赖未就绪的插件在 Start 时自行处理）")
|
||||
fallback := kernelboot.NewSyncBus()
|
||||
fallback := kstate.NewSyncBus()
|
||||
fallback.MarkKernelComplete()
|
||||
bus = fallback
|
||||
busConcrete = fallback
|
||||
@ -172,7 +174,7 @@ func (Module) Init(ks *kernelboot.KernelState) error {
|
||||
// 不在 catalog 里，只有 LoadSkipping 的工厂分支能加载它们）。
|
||||
skip := buildSkipSet(catalog, groups)
|
||||
var loadOnce sync.Once
|
||||
loadRest := func(st kernelboot.SyncState) {
|
||||
loadRest := func(st kstate.SyncState) {
|
||||
if !st.KernelComplete() {
|
||||
return
|
||||
}
|
||||
@ -296,7 +298,7 @@ func buildSkipSet(c *PluginCatalog, g formGroups) map[string]bool {
|
||||
// ★ 这里**刻意不做** SetStatusProvider —— 它依赖 agent，
|
||||
// 由 agent 模块**后补注入**（见其注释）。这不是遗漏，是有意的分层：
|
||||
// 让插件加载不必等 agent 那 35 秒。
|
||||
func injectBaseDeps(ks *kernelboot.KernelState) {
|
||||
func injectBaseDeps(ks *kstate.State) {
|
||||
reg := ks.PluginRegistry
|
||||
reg.SetLuaVM(ks.LuaVM)
|
||||
reg.SetBaseAPIKey(ks.BaseAPIKey)
|
||||
@ -305,7 +307,17 @@ func injectBaseDeps(ks *kernelboot.KernelState) {
|
||||
}
|
||||
reg.SetTracker(ks.Tracker)
|
||||
reg.SetConfig(ks.Cfg)
|
||||
reg.SetStageHost(ks.StageHost)
|
||||
// StageHost 在挂载点里存 any（kstate 不依赖 agent/core，否则成环）。
|
||||
// 断言成 sdk.ToolSource（plugin 真正需要的只读工具视图）。
|
||||
//
|
||||
// 断言失败时**不静默跳过**：SetStageHost 不设的后果是插件加载后
|
||||
// 工具表为空，而那与"插件没注册工具"无法区分。所以这里响亮记录。
|
||||
// （Init 里已检查过 StageHost != nil，此处失败是类型不合约，属装配缺陷。）
|
||||
if ts, ok := ks.StageHost.(sdk.ToolSource); ok && ts != nil {
|
||||
reg.SetStageHost(ts)
|
||||
} else {
|
||||
log.Printf("[plugin-host] WARNING: ks.StageHost 未实现 sdk.ToolSource —— 插件工具将不可见")
|
||||
}
|
||||
|
||||
if ks.Memory != nil {
|
||||
reg.SetIndexer(ks.Memory.Indexer)
|
||||
@ -350,7 +362,7 @@ func classify(c *PluginCatalog) formGroups {
|
||||
}
|
||||
|
||||
// loadOne 加载单个插件（走既有 LoadOneDir 路径，不绕过任何机制）。
|
||||
func loadOne(ks *kernelboot.KernelState, dir, name string) (bool, error) {
|
||||
func loadOne(ks *kstate.State, dir, name string) (bool, error) {
|
||||
if err := ks.PluginRegistry.LoadOneDir(filepath.Join(dir, name), name); err != nil {
|
||||
return false, err
|
||||
}
|
||||
@ -358,7 +370,7 @@ func loadOne(ks *kernelboot.KernelState, dir, name string) (bool, error) {
|
||||
}
|
||||
|
||||
// planCatalog 取元数据缓存（类型断言集中一处，便于排查"缓存没建起来"）。
|
||||
func planCatalog(ks *kernelboot.KernelState) *PluginCatalog {
|
||||
func planCatalog(ks *kstate.State) *PluginCatalog {
|
||||
c, _ := ks.PluginCatalog.(*PluginCatalog)
|
||||
return c
|
||||
}
|
||||
@ -368,7 +380,7 @@ func planCatalog(ks *kernelboot.KernelState) *PluginCatalog {
|
||||
// 失败只记日志、不阻断：系统本身仍可正常接受输入，只是依赖本事件的
|
||||
// 订阅者（如 seq 的开机序列）不会自动执行。**必须可见** ——
|
||||
// 静默失败会让"为什么开机序列没跑"完全无从查起。
|
||||
func publishToolsReady(ks *kernelboot.KernelState) {
|
||||
func publishToolsReady(ks *kstate.State) {
|
||||
if ks == nil || ks.EventBus == nil {
|
||||
log.Printf("[pluginhost] tools_ready NOT published: EventBus is nil " +
|
||||
"(subscribers such as seq boot sequences will not run)")
|
||||
|
||||
@ -14,7 +14,7 @@ import (
|
||||
"testing"
|
||||
|
||||
"github.com/JianFeeeee/HologramAgent/internal/events"
|
||||
"github.com/JianFeeeee/HologramAgent/internal/kernelboot"
|
||||
"github.com/JianFeeeee/HologramAgent/internal/kstate"
|
||||
)
|
||||
|
||||
// 没有 EventBus 时必须**响亮报错而不是静默返回** ——
|
||||
@ -26,7 +26,7 @@ func TestPublishToolsReadyWithoutBusDoesNotPanic(t *testing.T) {
|
||||
}
|
||||
}()
|
||||
publishToolsReady(nil)
|
||||
publishToolsReady(&kernelboot.KernelState{})
|
||||
publishToolsReady(&kstate.State{})
|
||||
}
|
||||
|
||||
// 有 EventBus 时必须真的发布一条 tools_ready，且带 plugin_count。
|
||||
@ -35,7 +35,7 @@ func TestPublishToolsReadyPublishes(t *testing.T) {
|
||||
var got []*events.Event
|
||||
bus.Subscribe(events.EventToolsReady, func(e *events.Event) { got = append(got, e) })
|
||||
|
||||
ks := &kernelboot.KernelState{EventBus: bus}
|
||||
ks := &kstate.State{EventBus: bus}
|
||||
publishToolsReady(ks)
|
||||
|
||||
if len(got) != 1 {
|
||||
|
||||
Reference in New Issue
Block a user