feat(io): InjectOptions.Payload 业务字段扩展,透传到本轮 stage

## 为什么需要

QQ 的「对方正在输入中」必须只在**自己引起的** before_output 里发,且要
知道发给谁。但两条路都断了:

	on_input 的 stageCtx  是局部变量(stageCtxFromInput),runStage 完就丢
	before_output 的 stageCtx 是内核**新建**的(emitResponse)
	⇒ 两者**不共享 Extra**

## 第一版是错的(用户指出)

我先加了 `InjectOptions.Meta` —— 那是把同一件事做了两遍。用户直接问:
「为什么又额外定义了 injectMeta,而不是包含在 inputch 的请求体中?」

查证后的真实边界:`InputEvent.Payload` **本就是通道送入内核的请求体**,
身份信息本该在那里。但 `IOInjector` 接口全是
`(source, channel, text, opts)`,插件无法给 payload 加字段 —— 所以
payload 需要一个**扩展口**,而不是一个平行的新概念。

改名为 `Payload` 还有一个实际好处:所有注入路径(HTTP/CLI/ACP)共用
同一套机制,不是注入专属。

## 内核怎么处理

	注入点 opts.Payload
	  → 与真 payload 合并(**内核保留键不可覆盖**)
	  → emitResponse 把非保留键原样透传到 stageCtx.Extra

保留键清单 `reservedPayloadKeys` 覆盖注入路径自身写入的键
(no_memory/context_policy/recall_policy/scene_policy/cleaner_name/
priority/type/content)与内核读取的语义键。允许覆盖意味着插件能伪造
"这条不记记忆"或"这条要立即打断"——那是权限提升,不是便利。

拦截方式是**跳过**而非拒绝整次注入:插件可能只想带一个业务字段,
因顺手多写一个保留键就让整条注入失败,代价太大。

## 判据(4 条,变异 2/2 咬)

 · 插件字段原样进 payload
 · 保留键不可覆盖(逐个验证 11 个键)
 · 空 Payload 不改变旧行为
 · 保留字清单必须覆盖注入路径自己写入的键(否则新键=新提权面)

## 附带修掉的编译破坏

`internal/plugin/lua_surface_test.go` 用 `z != sdk.InjectOptions{}` 比较
零值 —— 结构体含 map 就**不可比较**,加了 Payload 后直接编译失败。
改为逐字段验证。
This commit is contained in:
JianFeeeee
2026-10-18 17:40:07 +08:00
parent 40de84facc
commit 70f7bea4b9
5 changed files with 218 additions and 0 deletions

View File

@ -150,6 +150,36 @@ type InjectOptions struct {
// 排队注入(InjectText*/InjectInputSync)没有级别:它们本就是“不需及时处理”
// 的那一类,可被任何中断打断。
Priority string
// Payload 是本次注入要额外并入事件 payload 的字段(**不透明**)。
//
// ## 为什么需要它(2026-10-18)
//
// QQ 插件的「对方正在输入中」必须只在**自己引起的** before_output 里发,
// 而且要知道发给谁。但两条路都断了:
//
// · `on_input` 的 stageCtx 是局部变量(runStage 完就丢)
// · `before_output` 的 stageCtx 是内核**新建**的(emitResponse)
// ⇒ 两者**不共享 Extra**,插件拿不到“这轮是谁引起的”
//
// ## 为什么挂在 InjectOptions 而不是新造一个 Meta 字段
//
// 第一版我加了 `InjectOptions.Meta` —— 错的。它把同一件事做了两遍:
// `InputEvent.Payload` **本来就是通道送入内核的请求体**,身份信息本该
// 就在那里。但 `IOInjector` 接口全是 `(source, channel, text, opts)`,
// 插件无法直接给 payload 加字段 —— 所以 payload 需要一个扩展口,
// 而不是一个平行的新概念。
//
// 叫 Payload 而不是 Meta 还有一个好处:经内核实测确认,
// 它能让 HTTP/CLI/ACP 等**所有注入路径**共用同一套机制。
//
// ## 内核怎么处理
//
// 与真 payload 合并(同名键以本字段为准,但**内核保留字不允许覆盖**,
// 否则插件能伪造 `context_policy`/`content` 等内核语义),
// 然后在 emitResponse 里把**非内核保留键**原样透传到 `stageCtx.Extra`。
// 内核不解释其中任何业务字段。
Payload map[string]interface{}
}
// 中断优先级取值。