Alpha — 实验阶段。 行为、配置键与退回提示可能随时变化,尚未稳定,暂不建议在生产或个人关键流程上依赖。欢迎测试与反馈。
Hermes pre_tool_call 插件。执行 terminal 前检查命令是否带有审计摘要:
- 不会进入 Hermes 审批/密码流程的命令:直接放行。
- 会进入审批/密码流程且摘要完整:放行,不改写命令。
- 会进入审批/密码流程但摘要缺失或不完整:退回该次调用(
action: block,命令未执行),提示模型补齐摘要后,在同一轮里原样重发同一条命令。
execute_code 同样受管:先检查脚本级摘要(code 开头的三行 Python 注释),通过后再逐个检查 terminal() 的命令级摘要。详见「execute_code 覆盖」。
默认模式是 strict。插件不会代写摘要,摘要必须由当时的模型自己写。
摘要必须是命令开头连续的 # 注释行(遇到第一个非注释行即停止),固定三行:
# 【新改动|回滚|只读】用途=一句话说明这条命令要做什么
# 写入=写到哪里:文件/目录/服务/远端主机;只读则写 无
# 失败影响=失败时会怎样,一句话
规则:
- 第一行必须以
#开头,并带【新改动】、【回滚】、【只读】三选一标签。 - 第二、三行也必须以
#开头。 - 三个键名容错:
用途=/用途:/用途:;写入=/写入:/写入:;失败影响=/失败影响:/失败影响:,也接受失败=。 - 摘要行之后必须紧跟原命令本身,插件不会修改、移动或重新拼接命令。
- 摘要只用于审批卡片展示,不参与执行。
完整示例:
# 【回滚】用途=清理临时目录
# 写入=/tmp/cng
# 失败影响=不可恢复
rm -rf /tmp/x
- 第一次调用会进入审批但缺少摘要,插件返回
block,命令不会执行。 - 审批卡片显示命中项、缺少项(
label/用途/写入/失败影响)和三行格式示例。 - 模型按格式补写摘要,在同一轮里原样重发同一条命令(命令本身不要改)。
- 摘要完整后插件放行;后续命令照常执行。
退回提示固定为:
这条命令缺少审计摘要,已退回(未执行)。命中形态:recursive delete
缺:label、用途、写入、失败影响
请补成三行注释后,原样重发同一条命令(命令本身不要改):
# 【新改动|回滚|只读】用途=做什么
# 写入=写到哪(只读写 无)
# 失败影响=失败会怎样
示例:
# 【新改动】用途=重启示例服务加载新版插件
# 写入=launchctl gui/<uid> 域
# 失败影响=服务短暂中断,随后自动重连
execute_code 在子代理/injected 上下文里会走整脚本审批,审批卡片把整段 code 渲染成:
execute_code <<'PY'
<code 原文>
PY
这段 execute_code <<'PY' ... PY 包装文本由 Hermes 生成,模型无法在里面加注释,所以摘要只能写在 code 开头的 Python 注释里。execute_code 因此是两层检查,按顺序执行。
每次 execute_code 的 code 最前面必须是一段连续的三行 Python 注释(遇到第一个非注释行即停止,空行也会截断):
# 【只读】用途=查看 /tmp 下的大文件
# 写入=无
# 失败影响=无
from hermes_tools import terminal
print(terminal("du -sh /tmp/* | sort -h | tail"))-
即使脚本里一个
terminal()都没有(例如纯print(1)),也要求这三行。 -
缺失或不完整时直接退回,不执行脚本。退回提示:
execute_code 脚本缺少审计摘要,已退回(未执行)。缺:label、用途、写入、失败影响 请在 code 最前面写三行 Python 注释后重发(代码本身不要改): # 【新改动|回滚|只读】用途=这段脚本要做什么 # 写入=写到哪(只读写 无) # 失败影响=失败会怎样 注意:这三行必须是 code 的第一段内容(Python 注释),不是 shell 命令里的注释。 -
日志:
command-note-guard: blocked execute_code script missing=<missing>,只记录缺失项,不记录 code 正文。 -
lenient模式只要求code的第一个非空行以#开头。 -
annotate模式不改code,只记一条日志后放行。
脚本级摘要通过后,插件再对 code 做静态分析,取出其中每个 terminal(...) 调用的 command,套用同一套审批判据与三行摘要规则。命令级摘要必须写在 command 字符串开头,脚本级摘要不能替代它。
覆盖范围:
- 直接字符串字面量:
terminal("rm -rf /tmp/x")。 command=关键字:terminal(command="kill 123")。- 同一函数体或模块级、调用之前最近一次
ast.Constant(str)赋值:cmd = "rm -rf /tmp/x"; terminal(cmd)。只回溯一层,不做控制流分析。 - f-string 的静态部分:
terminal(f"rm -rf {p}")按rm -rf {}近似文本判断审批命中项与摘要。 - 函数别名与属性调用:
from hermes_tools import terminal as t之后的t(...),以及hermes_tools.terminal(...)。
不覆盖(静态取不到 command 时直接放行,不会代写摘要):
- 动态拼接、函数返回值、下标、
join等非字面量或非单层Name的 command。 - 通过
subprocess、os.system等自行调起的命令。 - 多层变量传递:
a = "rm ..."; b = a; terminal(b)。
两层都齐全的完整示例:
# 【只读】用途=查看目录内容
# 写入=无
# 失败影响=无
from hermes_tools import terminal
terminal(
"# 【只读】用途=查看目录\n"
"# 写入=无\n"
"# 失败影响=无\n"
"ls -la"
)多个 terminal() 调用都不合格时,退回提示只报第一个,并给出不合格总数。
注意:这要求每一次
execute_code都写脚本级摘要,没有「脚本很安全就免写」的例外。这是用户已知并接受的成本,换取审批卡片上始终能看到脚本用途、写入点与失败影响。
环境变量在插件导入时读取一次,修改后需重载 Hermes。
# 默认(都不设):strict,会进入审批就要求三行摘要,缺失即退回
unset COMMAND_NOTE_GUARD COMMAND_NOTE_GUARD_DRY
# 完全关闭:不注册、不生效;0 / false 等价
export COMMAND_NOTE_GUARD=off
# 宽松:会进入审批的 terminal 命令、以及 execute_code 脚本,都只要求首行是 #,不检查三键
export COMMAND_NOTE_GUARD=lenient
# 旧行为回退:不拦截,terminal 命令自动补一行摘要后放行;execute_code 只记日志、不改 code
export COMMAND_NOTE_GUARD=annotate
# 灰测:只 logger.info 记录缺少项,不改命令、不拦截
export COMMAND_NOTE_GUARD_DRY=1COMMAND_NOTE_GUARD_DRY=1 优先级最高:只记录、不改、不拦。
# 【自动补注】recursive delete | 对象:/tmp/x | 后果:recursive delete
rm -rf /tmp/x
- 摘要固定为单行,≤140 字符。
- 原命令逐字保留在第二行,缩进、换行都不变。
- 首行(第一个非空行)已经是
#注释时不补注。 - 摘要只用于审批卡片展示,不参与执行;命令照常运行。
- 日志只记录命中项,不记录命令正文或对象内容。
插件不再维护自己的风险形态清单。判据只有一个问题:这条命令会不会进入 Hermes 的审批/密码流程。
命中检测直接调用 Hermes 源码里的两个纯函数(延迟 import,避免插件加载期失败):
from tools.approval_detection import (
detect_dangerous_command,
detect_hardline_command,
)detect_hardline_command(command)返回(True, description):追加hardline:<description>。这是 Hermes 的硬拦截底线,--yolo也不能绕过。detect_dangerous_command(command)返回(True, key, description):追加description or key。这与terminal_tool的审批守卫使用同一张DANGEROUS_PATTERNS表。- 非注释行里出现
\bsudo\b:追加sudo。sudo会单独触发密码框,不包含在上面两个函数里。
也就是说,这里的命中集合与 Hermes 审批守卫同源;Hermes 不要求审批的命令,本插件也不要求摘要。
旧版按自建形态表判断,会对一些实际不进入审批的命令要求摘要。以下命令现在不再要求摘要:
scp/rsync:分类器不 flag(除非同时命中真正的危险模式);旧清单的remote-copy命中已不再要求摘要。chmod/chown的普通权限修改(例如chmod 700 ~/x.sh):只有777/666/ other-writable、递归 chown root 等危险写法才命中;旧清单的permissions命中已不再要求摘要。launchctl print等只读子命令:分类器不 flag,因此不要求摘要(旧清单本来也只匹配操作类子命令)。普通服务的launchctl bootout gui/501/local.foo则从旧清单的launchd命中变为不要求摘要;分类器只对ai.hermes/hermes网关标签的stop/kickstart/bootout/unload/kill/disable/remove报审批。- 普通重定向到非敏感目标(例如
echo hi > /dev/null 2>&1):不命中(旧清单也排除了/dev/null与2>&1);> /etc/...等敏感路径仍会命中。 - 普通
kill -9 <pid>:分类器只 flagkill -9 -1、pkill -9等宽范围终止;旧清单的kill-process命中已不再要求摘要。
反过来,旧清单未覆盖但 Hermes 会审批的命令(例如 SQL DELETE 无 WHERE、git reset --hard、敏感路径写入等)现在也会要求摘要。python3 -c 'print(1)' 也仍会命中 script execution via -e/-c flag,因为分类器本身就会 flag 内联脚本。
同一命令可能命中多个项,日志与退回提示会列出全部命中项。
- 退回:
command-note-guard: blocked <hits> missing=<missing>,只记录命中项和缺失项,不记录命令正文。 - execute_code 脚本级退回:
command-note-guard: blocked execute_code script missing=<missing>,不记录 code 正文。 - execute_code 命令级退回:
command-note-guard: blocked execute_code #<n> <hits> missing=<missing>。 - annotate:
command-note-guard: annotated <hits>;execute_code 为command-note-guard: execute_code annotate pass ...。 - 灰测:
command-note-guard: dry-run missing=<missing> hits=<hits>。 - 关闭:
command-note-guard: disabled by COMMAND_NOTE_GUARD。
execute_code只做静态分析:动态拼接、函数返回值、下标、join、多层变量传递等取不到字面量的 command 会直接放行。例如cmd = "rm " + "-rf /tmp/x"。- 通过
subprocess、os.system等自行调起的命令不在terminal的审批路径上,插件也看不到。 - 插件跑在 host 隔离模式、无法 import
tools.approval_detection时,启用一份五条兜底规则(fallback:recursive-delete、fallback:sql-drop、fallback:inline-script、fallback:heredoc、fallback:sudo),仍要求摘要,只记一次 warning。此时覆盖率明显低于正常路径,其余命令会放行。 - 判据与 Hermes 审批守卫同源:Hermes 分类器不 flag 的命令,本插件也不会要求摘要;这不是「命令一定安全」的保证。
- 两层摘要都只认开头连续的
#行;摘要与代码之间插入空行,或把摘要写到后面,都会被判为缺失。脚本级摘要必须是code的第一段内容,命令级摘要必须是 command 字符串的第一段内容。 - 插件内部异常一律放行;任何解析失败都不会阻止命令执行。