mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-11-06 09:17:31 +00:00
118 lines
5.4 KiB
Go
118 lines
5.4 KiB
Go
package sdk
|
||
|
||
// SecurityAPI 是插件**声明**自身安全策略的接口。
|
||
//
|
||
// ## 为什么需要它（用户裁定 2026-10-26，2026-10-29 补齐实现）
|
||
//
|
||
// > 插件可以声明自身安全限制策略，并在插件自身 inputch 触发时携带参数
|
||
// > 选择其中一种 —— 正好对应 QQ 插件内部 owner 与非 owner 的差别对待。
|
||
//
|
||
// > 这是可选参数，不声明安全策略则使用内核默认安全策略。
|
||
//
|
||
// ## 分工：插件只声明，内核只执行
|
||
//
|
||
// 插件：DeclareProfile / DeclareProfiles （只声明，不判定）
|
||
// 内核：CheckTool / CheckToolFor / ActivateProfile （只执行，不信任插件）
|
||
//
|
||
// ★ 为什么判定必须在内核：插件崩溃或被重载时，声明不能跟着消失
|
||
// （否则"挂掉插件"就是绕过策略的手段）；而且判定要与全局基线、主体策略
|
||
// 走同一条链 —— 分散到各插件就是"被约束者自己决定约束"，
|
||
// 本仓已有实测教训（QQ 的 beforeToolcall 自己判身份/白名单/硬私有，
|
||
// 结果每个插件各写一套、拒绝语义散落、插件崩了策略就没了）。
|
||
//
|
||
// ## 声明 vs 全局基线：两层，职责不重叠
|
||
//
|
||
// ① 全局基线（部署方配置 core.security.*）：不受插件影响，防"插件自己放水"
|
||
// ② 档位（本接口）：单次请求的**收窄**
|
||
//
|
||
// 档位**只能收窄**：内核的判定顺序是「全局 deny → 档位 deny → 主体 deny
|
||
// → 全局 allow → 档位 allow」，全局黑名单永远先判，档位绕不过去。
|
||
//
|
||
// ## 缺省语义（重要）
|
||
//
|
||
// 不声明 / 不传 = 不使用档位，一切判定沿用内核默认策略
|
||
//
|
||
// 也就是说这是**可选**能力：不用的插件行为与之前完全一致。
|
||
// 而一旦传了**未声明**的档位名，内核会**报错**而不是静默回落 ——
|
||
// 拼错档位名却默默用默认策略是安全事故的经典形态。
|
||
//
|
||
// ## 典型用法（QQ 插件）
|
||
//
|
||
// // Start 阶段：声明两个档位（只声明，不判定）
|
||
// s.Security().DeclareProfiles([]SecurityProfile{
|
||
// {Name: "qq.owner", Owner: "qq", AllowTools: []string{"*"}},
|
||
// {Name: "qq.guest", Owner: "qq",
|
||
// DenyTools: []string{"cmd_*", "files_write"},
|
||
// SensitiveWords: []string{"内部代号"}},
|
||
// })
|
||
//
|
||
// // 注入阶段：按发送者身份选择档位
|
||
// s.InjectTextOpts(source, channel, text, sdk.InjectOptions{
|
||
// SecurityProfile: "qq.guest",
|
||
// })
|
||
//
|
||
// ## 名字约束
|
||
//
|
||
// 档位名必须是 `<owner>.<档位>`，其中 owner 等于插件名。这条在内核侧
|
||
// 强制（否则插件 A 能声明 `qq.owner` 并夺走插件 B 的档位语义）。
|
||
type SecurityAPI interface {
|
||
// DeclareProfile 声明一个命名档位。同名重复声明会覆盖（同一 owner
|
||
// 只能覆盖自己的档位，不能覆盖别人的）。
|
||
//
|
||
// 返回 error 的情形：
|
||
// · 名字不符合 `<owner>.<档位>` 形式
|
||
// · owner 与本插件名不一致（试图声明别人的档位）
|
||
// · 安全模块未启用（此时没有可声明的策略容器）
|
||
DeclareProfile(p SecurityProfile) error
|
||
|
||
// DeclareProfiles 批量声明（任一失败即整体失败，便于早失败）。
|
||
//
|
||
// 为什么提供批量版：QQ 这类插件有 3~4 个档位，逐个判断 error 会让
|
||
// Start 里堆满重复代码；而"声明到一半失败"是更难排查的状态。
|
||
DeclareProfiles(ps []SecurityProfile) error
|
||
}
|
||
|
||
// SecurityProfile 是一个**命名安全档位**的声明。
|
||
//
|
||
// 与 ToolPolicy 类配置的区别：档位是**运行时可选**的（按 inputch 输入
|
||
// 携带的参数选择），不是全局生效的。
|
||
type SecurityProfile struct {
|
||
// Name 是档位名，必须形如 `<owner>.<档位>`（如 "qq.guest"）。
|
||
Name string
|
||
// Owner 是声明者（插件名）。与 Name 的前缀必须一致。
|
||
Owner string
|
||
|
||
// AllowTools / DenyTools 是本档位下的工具白/黑名单（支持尾部 `*` 前缀）。
|
||
//
|
||
// 语义（与全局策略一致，且**只能收窄**）：
|
||
// · DenyTools 命中 ⇒ 拒绝（且它叠加在全局黑名单之上，不能反向放行）
|
||
// · AllowTools 非空且未命中 ⇒ 拒绝
|
||
// · 两者都空 ⇒ 本档位不额外限制
|
||
AllowTools []string
|
||
DenyTools []string
|
||
|
||
// SensitiveWords 是本档位额外追加的敏感词（在全局敏感词之上追加）。
|
||
//
|
||
// 用途：某些词只在特定身份下才敏感（如非所有者对话时不该看到内部代号）。
|
||
SensitiveWords []string
|
||
|
||
// ToolSensitiveWords 是**按工具**追加的敏感词（在 SensitiveWords 之上再追加）。
|
||
//
|
||
// key = 工具名模式，支持尾部 `*`（与 AllowTools/DenyTools 同一套匹配规则）
|
||
// value = 该工具额外追加的词
|
||
//
|
||
// 用途：不同工具带回来的外部内容风险不同 —— `web_fetch` 拿的是网页正文
|
||
// （间接提示词注入的主入口），而 `qq_get_message` 拿的是聊天记录。
|
||
// 插件最清楚自己每个工具的内容形态，所以词表由插件按工具声明。
|
||
//
|
||
// ★ 语义是**追加不是覆盖**：整轮 SensitiveWords 仍然生效。
|
||
// 当前处置是 B 档（标记+警示，不阻断），多标一条只是多一句警示，
|
||
// 漏标则是安全缺口 —— 所以取宽不取窄。
|
||
//
|
||
// ToolSensitiveWords: map[string][]string{
|
||
// "web_fetch": {"内部代号", "机密"},
|
||
// "qq_get_*": {"客户名单"},
|
||
// }
|
||
ToolSensitiveWords map[string][]string
|
||
}
|