mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-11-05 16:57:32 +00:00
81a0f5f598
## 一、插件声明层（用户裁定）
> 「敏感词策略也应该是插件声明啊，每个插件声明自己轮次以及自己工具的
> 敏感词策略」
SecurityProfile 新增两个字段：
ToolSensitiveWords map[string][]string // key=工具名模式(尾 *)，value=词表
DetectInjection bool // 开启内核内置注入迹象识别
语义是**追加不覆盖**：整轮 SensitiveWords 仍然生效。
取宽不取窄的理由：当前处置是 B 档（标记+警示，不阻断），
多标一条只是多一句警示，漏标则是安全缺口。
## 二、修掉我自己造的「莲藕式分层」
前一版把 *security.Round 从 runInputTask 一路搬到工具链
（prepareInputTask(evt, round) → TaskFrame.SecRound →
executeToolCallOutcomeWithRound），并在 rtchild 里另补一条。
那是把**分层策略实现成跨层传参**：每多一条工具执行路径就要求调用方
多传一次句柄。profileActivator 的设计注释早就写明了正路：
> 工具调用发生在 LLM 决定之后，此时插件已不在调用栈上。
> 唯一可靠的传递方式是**内核在输入进来时记住**，在该轮的工具判定里使用。
改为 security 自取：
Runtime.ScanContentForAgent(agentID, isChild, ins, text)
→ ForAgent(agentID, isChild) // per-agent 视图，天然不串档
→ EffectiveProfile() // session > longtime
→ 合并 全局词表 + 档位词表 + 工具词表 + DetectInjection
core 只递交**事实**（我是谁 / 哪个工具 / 什么文本），不认识 Round。
与 CheckToolForAgent 同一套身份推断，不引入第二个入口语义。
TaskFrame.SecRound / executeToolCallOutcomeWithRound 全部撤除。
## 三、目录名统一
third_party/homeagent-sdk → third_party/hologramagentsdk
module 与远端仓早已是 hologramagentsdk，只剩物理目录是遗留名。
同步改了 go.mod replace、构建/打包/部署脚本、5 处测试里的分段路径。
注意：这里改的是**主仓 vendored 的 SDK 源码路径**，example/ 由 SDK
独立仓自己跟踪，主仓不涉及。
## 判据
TestToolSensitiveWordsAppendOnlyForThatTool 词表只对目标工具生效 + 追加语义
TestToolSensitiveWordsUseAgentScope security 按 agent scope 自取生效
（变异验证：删掉 ForAgent 查询 → 红）
## 验证
go build ./... → 0
go vet ./... → 0
go test ./... -count=1 -race → 62 ok / 0 FAIL / 0 DATA RACE
gofmt -l internal/ → 干净
130 lines
6.0 KiB
Go
130 lines
6.0 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
|
||
|
||
// DetectInjection 开启内核内置的**提示词注入迹象**识别。
|
||
//
|
||
// 与 ToolSensitiveWords 的分工：词表是插件给的**数据**（它知道自己的
|
||
// 哪些词敏感），注入迹象是内核内置的**形态**规则（ignore previous /
|
||
// 角色劫持 / 索要系统提示 / 伪造更高优先级）。
|
||
//
|
||
// ★ 默认 false：注入识别会命中"扮演""你现在是"这类正常对话词，
|
||
// 默认开启会让常识对话充满误报 —— 由插件按自己的内容形态显式声明。
|
||
//
|
||
// ★ 当前处置是 B 档：命中只**标记并警示**，不阻断。
|
||
DetectInjection bool
|
||
}
|