[Feature] Agent 节点工具调用策略：按命令前缀/路径声明 allow·deny·ask 规则，高危操作拦截或转人工审批

未关闭
  • 哪里不对？
#301 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
15/100
Issue 类型
功能
描述清晰度
基本清楚
活跃度
活跃
技术栈
go
领域
backend, security

调研方向

This is design work spanning several subsystems, so read the referenced files first: internal/runtime/hooks.go (materializeAgentHooks), internal/domain/agent.go (AgentHook), internal/engine/node_outcome.go (waiting_approval), and the provider files for Claude Code, CodeBuddy and Codex. Agree on the policy model and the three-level merge order with a maintainer before coding. Done means the acceptance checklist in the issue passes, starting with the check endpoint and policy unit tests.

由索引模型根据 Issue 内容生成。

描述

背景与借鉴来源

无人值守的 Agent 节点在沙箱里执行 shell 和文件写入。沙箱能隔离宿主，但挡不住在工作区和已授权的远端上做的高危操作：git push --force、删分支、rm -rf 仓库目录、改 CI 配置或 migrations/、kubectl/terraform apply、curl … | sh 等。主流 Agent 都在「全放开」和「每步都问」之间加了一层声明式工具调用策略：

  • openai/codex（https://github.com/openai/codex ，约 135k★，当天仍有提交）：codex-rs/execpolicy 用 prefix_rule(pattern=[...], decision=allow|prompt|forbidden, justification=...) 按命令前缀判定；forbidden 时把 justification（如「请用 jj 代替 git」）回给模型；规则自带 match/not_match 样例，加载时当单测校验。
  • google-gemini/gemini-cli（https://github.com/google-gemini/gemini-cli ，约 109k★，当天仍有提交）：Policy Engine 用 TOML 规则（toolName、commandPrefix/参数匹配、decision = allow|deny|ask_user、priority），用户级、管理员级多层合并，优先级高的规则生效。
  • OpenHands/software-agent-sdk（https://github.com/OpenHands/software-agent-sdk ，OpenHands 约 93k★，SDK 当天仍有提交）：security/confirmation_policy.py 提供 AlwaysConfirm/NeverConfirm/ConfirmRisky(threshold)，按动作风险等级决定是否要人工确认。
  • anthropics/claude-code（约 155k★）：permissions.allow/deny/ask 支持 Bash(git push:*)、Edit(./migrations/**) 这种细粒度规则，PreToolUse hook 可返回 permissionDecision: deny。

LoopForge 现状与不足

  1. 所有执行器都强制全放开：
    • internal/runtime/provider_claude.go 的 Prepare 固定改成 --permission-mode bypassPermissions；
    • internal/runtime/provider_codebuddy.go 的 isolateCodeBuddyFlagsWithSource 固定加 -y 和 bypassPermissions；
    • internal/runtime/provider_codex.go 在 docker/bwrap 下改成 --sandbox danger-full-access。
      这对无人值守是必要的，但结果是 SOP 节点里任何命令都不会被拦下，平台也没有统一的地方补拦截。
  2. 只能靠每个 Agent 自己写 hook 脚本：domain.AgentHook（internal/domain/agent.go）+ internal/runtime/hooks.go 的 materializeAgentHooks 支持 PreToolUse 脚本，但要每个角色手写 shell/python、不同 CLI 的输入输出格式各不相同、没有平台/项目级统一配置、没法审计「拦了什么」。Main Bot 的 PreToolUse 拦截（internal/httpapi/assistant_provider.go、assistant_engine_cli.go）只用于助手会话，不覆盖 SOP 节点。
  3. 没有「需要人工确认」这条路：引擎已有 waiting_approval（internal/engine/node_outcome.go）和干预点 HumanInterventionPoint，但干预点只能挂在 before_execution/after_execution/before_publish 阶段，不能「执行到某条高危命令时」暂停等人批。
  4. 现有相关 issue 都不覆盖这块：#226 管沙箱出网域名，#227 管推送前密钥扫描，#258 管停滞/打转，#223 管 Token 预算。

建议方案

  1. 策略模型（internal/domain 新增 ToolPolicy，归 CatalogRepo 管理）：规则字段
    tool（shell/edit/write/mcp:<server>/<tool>）、commandPrefix（按 token 前缀，支持备选）、pathGlob（文件类工具）、decision（allow/deny/ask）、priority、justification、examples.match/notMatch。
    作用域：平台默认 → 项目 → Agent 角色，按优先级合并；平台可标记某些 deny 规则为「不可被下层覆盖」。
  2. 内置默认规则集（可关）：git push --force*/git push * :branch、rm -rf / 及工作区根、curl|wget … | sh、改 .github/workflows/**、.gitlab-ci.yml、migrations/** 等给出 deny 或 ask 建议值。
  3. 统一执行点：在 materializeAgentHooks 阶段为每个节点自动注入一个平台 PreToolUse 守卫（复用 Main Bot 守卫的做法），守卫读物化后的策略 JSON 做判定，按 Claude Code / CodeBuddy / Codex 各自的 hook 协议返回结果；不支持 hook 的执行器（opencode、cursor 等）在节点详情里标「策略未生效」，项目可配置「要求策略生效，否则拒绝运行」。
  4. 三种结果的处理：
    • deny：拒绝该调用，把 justification 作为拒绝原因回给模型，让它换做法；
    • ask：拒绝本次调用并结束当前轮，节点进入 waiting_approval，审批卡片展示命令、工作目录、命中规则；批准后通过 resume 会话放行该命令（一次性 allow token），拒绝则把原因作为反馈继续；
    • allow：放行。
  5. 审计：每次命中写 policy.decision 事件（规则 ID、工具、命令摘要、结果），节点详情和运营分析里可查「被拦/被审批」的次数。
  6. 策略测试：保存策略时校验 examples；提供 POST /api/tool-policies/check 输入命令返回命中结果，便于配置前试跑。

验收标准

  • 可以在平台、项目、Agent 三级配置策略，合并顺序和「不可覆盖」标记有单测覆盖；保存时 examples.match/notMatch 不符会报错。
  • Claude Code、CodeBuddy、Codex 三种执行器下，节点执行 git push --force origin main 时被拦截，模型能收到 justification，事件里有 policy.decision=deny。
  • ask 规则命中时节点进入 waiting_approval，审批卡片能看到命令和命中的规则；批准后该命令得以执行、节点继续；拒绝后原因作为反馈回到 Agent。
  • 不支持 hook 的执行器在节点详情显示「策略未生效」；开启「要求策略生效」时这类节点启动即失败并给出明确提示。
  • 未配置任何策略、且关闭内置默认规则时，现有节点行为和测试结果不变。
  • check 接口对给定命令返回命中的规则和最终结果。
主要语言
Go
星标
141
派生
28
平均合并
1 天 15 小时
30 天内合并 PR
113

环境准备

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

Tencent/LoopForge 的其他 Issue

查看 Tencent/LoopForge 的全部 Issue

相似的 Issue

更多 Go Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。