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

View File

@ -0,0 +1,123 @@
package kstate
import (
"fmt"
"log"
)
// 内核生命周期:**伪关机(Quiesce)** 与 **唤醒(Resume)**。
//
// ## 为什么需要它(用户 2026-10-17 要求)
//
// 数据目录迁移时**绝不能有模块在写数据**:distiller 每 10 分钟写一次
// memory/graph.db,text memory 滚动写 memory/text,tracker 在 overlay 里写,
// 40 个插件各写自己的 plugin_data。迁移 21G 数据要几分钟,期间任何写入
// 都会造成"迁移到一半的数据"或迁移后新旧不一致。
//
// 用户原话:
//
// 「迁移模块要先让 core 暂停其他模块运行(伪关机)完成迁移后再唤醒」
//
// ## 为什么不能用现成的 CloseAll
//
// `CloseAll` 是**一次性**的:它执行完就把 `Closers` 清空(切片置 nil),
// 且各模块的 Init 有副作用(建库、播种、迁移扫描),**不能简单重跑**。
// 用它做伪关机 = 关掉就再也起不来,等于要求重启进程 —— 那就不是"伪"关机了。
//
// ## 本文件的做法
//
// 分两级,都**可逆**:
//
// Quiesce() → 让所有"活动写者"停下来,但**保留连接/句柄**
// Resume() → 把停下来的重新启动
//
// 参与方式:模块在 Init 里通过 `AddQuiescer(name, pause, resume)` 登记。
// 与 CloseAll 一样**逆序**唤醒(LIFO)——后启动的先恢复,保证依赖顺序。
//
// ## ★ 关键约束(写进类型里)
//
// 1. pause 必须**幂等**且**不关闭文件/DB 句柄**(关了就无法 resume)
// 2. pause 必须**阻塞到确实不再写**(否则迁移仍有竞态)
// 3. resume 失败必须**可见**(返回错误),不能静默"半醒"
// 4. 只有**持有写句柄**的模块才需要登记 —— 纯读模块不必(如 config)
type Quiescer struct {
// Name 用于日志与诊断(哪个模块停不下来,一眼看到)。
Name string
// Pause 停下活动写入并**等到确实停了**才返回。
Pause func() error
// Resume 恢复写入。失败必须返回错误(不能假装成功)。
Resume func() error
}
// AddQuiescer 登记一个可暂停/恢复的写者(在模块 Init 里调用)。
func (s *State) AddQuiescer(name string, pause, resume func() error) {
if pause == nil {
return
}
s.quiesceMu.Lock()
s.Quiescers = append(s.Quiescers, Quiescer{Name: name, Pause: pause, Resume: resume})
s.quiesceMu.Unlock()
}
// Quiesce 伪关机:**逆序**暂停全部已登记的写者。
//
// 返回成功暂停的清单 —— Resume 只唤醒这些(没有的不要"凭空唤醒")。
// 任何一个 Pause 失败都会**停止继续暂停**并返回错误:宁可只关一半
// 让调用方放弃迁移,也不要"看起来关了但仍有写者在跑"。
func (s *State) Quiesce() ([]string, error) {
s.quiesceMu.Lock()
qs := make([]Quiescer, len(s.Quiescers))
copy(qs, s.Quiescers)
s.quiesceMu.Unlock()
// 逆序暂停:后启动的先停(与启动顺序相反,先停"消费者"再停"生产者")
var paused []string
for i := len(qs) - 1; i >= 0; i-- {
q := qs[i]
if err := q.Pause(); err != nil {
// 已暂停的按**反序**回滚(把它唤醒回去),别留半关状态
for j := len(paused) - 1; j >= 0; j-- {
if r := s.resumeOne(qs, paused[j]); r != nil {
log.Printf("[quiesce] rollback wake %s failed: %v", paused[j], r)
}
}
return nil, fmt.Errorf("暂停 %s 失败(已回滚 %d 个): %w", q.Name, len(paused), err)
}
paused = append(paused, q.Name)
log.Printf("[quiesce] paused: %s", q.Name)
}
return paused, nil
}
// Resume 唤醒:按**暂停的逆序**(即原启动顺序)恢复。
func (s *State) Resume(paused []string) error {
s.quiesceMu.Lock()
qs := make([]Quiescer, len(s.Quiescers))
copy(qs, s.Quiescers)
s.quiesceMu.Unlock()
var firstErr error
for i := len(paused) - 1; i >= 0; i-- {
if err := s.resumeOne(qs, paused[i]); err != nil {
log.Printf("[quiesce] wake %s failed: %v", paused[i], err)
if firstErr == nil {
firstErr = fmt.Errorf("唤醒 %s: %w", paused[i], err)
}
} else {
log.Printf("[quiesce] woken: %s", paused[i])
}
}
return firstErr
}
func (s *State) resumeOne(qs []Quiescer, name string) error {
for _, q := range qs {
if q.Name == name {
if q.Resume == nil {
return nil
}
return q.Resume()
}
}
return fmt.Errorf("未登记的写者: %s", name)
}