ModelRouter/docs/design-plugin-kernel-api.md

插件可调用内核动作（R4-c）设计

用户决策（2026-10-11）：全开（13 个内核动作全部可调）+ 设置页可配权限 + Go 侧 deadline 兜底。

1. 要解决的问题

用户原话："现在这个接口不全，可以多给一些接口让 lua 调用内核。"

现状（__llmsproxy_adapters）是我手写的三个闭包（install/update/remove）， 只能管适配器。内核还有 13 个公开动作（Reload / ResetHealth / AddSource / RemoveSource / SaveAutoRules / key 增删改 / 列表读取…），插件一个都调不到。

而"自动孵化 / 自愈 / 联动"这类插件能力（例如：探测到上游全挂 → 触发重探 + 清冷却；发现额度变化 → 重排 AUTO 链）恰恰需要它们。

2. 关键认识：Go 调用可以超时，Lua 死循环不能

这决定了整个设计，也是用户提"阻塞 + Go 兜底"的原因：

形态	能否中断	处置方式
Lua 里 while true do end	不能（LuaJIT 限制，已实测三次）	只能停用插件
Lua 里 __llmsproxy_kernel.call("reload")	能	Go 侧 select + deadline，超时把错误返回给 Lua

因为 Lua 只是在等 Go 的返回值，不占用 Lua 栈的执行。所以给每次内核调用加 Go 侧 deadline 是可行的、干净的 —— 不需要"Lua 投递请求、Go 队列执行"：那样 还要定义"超时后队列里积压的命令怎么办"，而 deadline 直接返回 (nil, err)， 语义闭合。

3. 依赖方向

internal/lua 不能 import internal/core（方向是 core → lua）。 按既有先例（SetOutboundHosts）注入一个接口，由 core 实现：

// internal/lua/kernel_api.go
type KernelAction struct {
    Name        string   // "reload" / "reset_health" / ...
    Title       string   // 设置页展示用
    Description string
    Danger      string   // ""=只读, "write"=改配置, "danger"=破坏性
    Params      []string // 参数名（设置页/文档用）
}

type KernelAPI interface {
    // Actions 列出可调用动作（设置页据此渲染权限开关）
    Actions() []KernelAction
    // Invoke 执行一个动作，args 为已解码参数。**必须**尊重 ctx 的 deadline。
    Invoke(ctx context.Context, name string, args map[string]any) (any, error)
}

core 侧实现 Invoke 时用现有的 Core 方法，本身不持 p.mu，因此不会与 插件锁成环（已核实：所有 ps.mu → p.mu 都是先释放 ps.mu）。

4. 权限模型

复用 visibilityOverrides 的同一套持久化机制（.access.json）， 但用独立的键空间：kernel:<plugin> → 逗号分隔的动作名或 *。

• 默认拒绝：插件不显式获得授权时，call 返回 (nil, "not permitted")。 理由：全开是"能力存在"，不是"默认授予"。一个插件能删密钥这件事必须由 运维在设置页点过确认。
• danger 类必须显式逐个授权，不接受 *。这一条是防止运维图省事写 通配符，把"删密钥"和"读状态"等同起来。
• 插件可以在自己源码里声明它想要的动作（plugin.kernel = {...}）， 设置页把它显示为"申请"，运维批准后才生效。声明不等于授权。

5. 动作清单（13 个 + 适配器 3 个）

动作	危险级	对应 Core 方法	超时
status	只读	读 AutoSlotStates/Registry	2s
list_sources	只读	Sources()	2s
list_models	只读	Registry().ModelList()	2s
list_adapters	只读	ListAdapters()	2s
adapter_owner	只读	AdapterOwnerOf	2s
reload	write	Reload()	30s
reset_health	write	ResetHealth()	5s
probe_all	write	Registry().ProbeAll(ctx)	60s
save_auto_rules	write	SaveAutoRules()	10s
save_key_auto	write	SaveKeyAuto()	10s
add_source	write	AddSource()	30s
remove_source	danger	RemoveSource()	30s
create_key	write	CreateKey()	10s
update_key	write	UpdateKey()	10s
delete_key	danger	DeleteKey()	10s
install_adapter	write	UploadAdapter()	10s
remove_adapter	danger	RemoveAdapter()	30s
set_plugin_enabled	danger	SetEnabled()	5s

绝不开放：ListKeys() / FindKey() —— 返回明文密钥。给插件读密钥等于 把网关的凭据面交给第三方 Lua。要用 key 相关动作就只用带掩码的形态。

6. Lua 调用面

-- 探测：拿到可用动作与自己的授权情况
local acts = __llmsproxy_kernel.actions()
-- 调用：统一入口，返回 (result, err)
local ok, err = __llmsproxy_kernel.call("reset_health", {})
local st, err = __llmsproxy_kernel.call("status", {})

统一入口（而不是每个动作一个全局函数）的理由：动作集合将来会变，而 __llmsproxy_kernel 的签名不变 —— 否则每加一个动作就要动 bootPluginState，而那里正是历史上出过 cgo 崩溃的地方。

7. 实施顺序

1. internal/lua/kernel_api.go：接口 + 动作元数据 + 权限检查 + deadline 包装
2. internal/lua/plugin_kernel_bridge.go：Lua 绑定（actions / call）
3. internal/core/kernel_actions.go：实现 KernelAPI（core 侧）
4. 权限持久化：复用 .access.json，新键空间
5. 设置页：插件行加"内核动作"列 + 授权编辑
6. 测试：Go 侧全动作、Lua 侧调用、权限拒绝、deadline 生效、危险动作需显式授权