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
2026-11-04 11:23:05 +08:00
parent 387ae945df
commit cc0eb51286
63 changed files with 1734 additions and 494 deletions

101
internal/kstate/mount.go Normal file
View File

@ -0,0 +1,101 @@
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()
}
}