6.0 KiB
| title | created | updated | type | tags | sources | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Tool Runtime Policy | 2026-04-21 | 2026-05-02 | concept |
|
|
Tool Runtime Policy
Tool Runtime Policy 是工具重构后新增的运行时策略层。它解决的问题是：工具不仅要知道“是否启用”，还要知道“在当前 Agent、当前子进程、当前 workspace/policy 下到底能不能执行，以及应该在哪里执行”。
它连接 tool-system、tool-governance、subagent-session 和 agent-runtime。
2026-05-02 后还要区分 tool-operations：Runtime Policy 决定工具在 worker 视角是本地、主进程代理还是禁用；Operations 决定某个已构建工具的文件系统、进程和搜索调用如何落地。当前实现仍保持工具粒度 route，不把每个 file/process 方法拆成独立权限。
三层模型
Tool Catalog / DB Governance
-> Tool Manifest
-> Runtime Policy Projection
1. Catalog / DB Governance
这一层负责工具是否存在、全局是否启用、Agent 是否覆盖、Prompt Hint 如何写入。详见 tool-governance。
2. Tool Manifest
tools/manifest.ts 将工具转成稳定画像：
kind:builtin、memory、skill、delegation、admin、customexecutionMode:parallel或sequentialsupportedInWorkerworkerRoutingHint:local、main-process-proxy、disabledrequiresShellrequiresWriterequiresSkillScope
这些字段是子 Agent worker 和前端诊断展示的共同语言。
3. Runtime Policy Projection
tools/runtime_policy.ts 根据 manifest、enabled tool names、disabled reasons、worker policy 推导最终状态：
| 状态 | 含义 |
|---|---|
worker-local |
子进程可以本地执行 |
main-process-proxied |
子进程请求父进程代理执行 |
disabled-in-worker |
当前 worker 策略下不能执行 |
not-selected |
没有被选入当前子 Agent 工具集 |
前端再映射为路由：
worker-localmain-process-proxydisabled
Worker Policy 自动推导
buildSubprocessWorkerPolicy 会从当前 session 和工具 manifest 推导 worker 策略：
workspaceRoots: 来自sessionCwd和额外 workspace roots，去重后传给 worker。allowShell: 只有工具确实需要 shell，且策略允许时才为 true。readonly: 如果没有写工具需求，默认只读；写工具需要显式允许。
这使子 Agent 不需要默认拥有完整宿主进程权限。
阻断原因
常见 blockedReason 包括：
| 原因 | 含义 |
|---|---|
workspace_root_required |
工具需要 workspace root，但当前 session 没有 cwd/root |
shell_disabled_by_policy |
bash 等 shell 工具被策略禁用 |
write_blocked_by_readonly_policy |
写入类工具被 readonly 策略阻止 |
requires_main_process_proxy |
工具需要主进程代理 |
unsupported_in_worker |
工具没有 worker 支持 |
not_selected_for_subagent |
未被选入子 Agent 工具集 |
这些原因应该在工具管理页、Agent 编辑页、子 Agent 批次详情里使用同一套中文展示。
当前内置路由
| 工具类别 | 工具 | 默认路由 |
|---|---|---|
| Worker 本地 | bash、read_file、list_dir、find_files、grep |
worker-local |
| 主进程代理 | write_file、edit、patch、read_skill、read_skill_file、skill_manage、execute_skill、memory_save、memory_recall |
main-process-proxy |
| 强顺序工具 | edit、patch、write_file、delegate_task、delegate_parallel、clarify、escalate |
sequential |
治理层可以通过 workerRoutingStrategy 强制覆盖：
autoforce-localforce-main-process-proxyforce-disabled
前端一致性要求
这次重构的目标之一是让三处页面一致：
- 工具管理页显示全局治理、核心工具、是否可关闭、运行时画像。
- Agent 编辑页显示当前 Agent 的局部启停、子 Agent 允许工具、有效 runtime profile。
- 对话页显示实际运行时的子 Agent 工具路由和 blocked reason。
这些页面不应各自重新推导规则，而应消费后端 runtimeDiagnostic / projection。
2026-04-23 动态路由与静态画像的区别
近期实现里，Tool Runtime Policy 需要同时解释两种结果：
manifest/effectiveRuntimeProfile：偏静态画像，描述工具理论上支持什么、通常需要什么权限。toolRuntimeRoutes：偏动态结果，描述在当前 session cwd、workspace roots、allowShell、readonly、selected tools 条件下，这次运行究竟走哪条路。
因此：
- 工具管理页更适合看“画像”和“全局风险”。
- Agent 编辑页更适合看“该 Agent 保存后会生效什么画像”。
- 对话页和子 Agent 批次更适合看“本次任务真正请求到的路由结果”。
如果出现“Agent 编辑页显示允许，但运行时还是 blocked”，优先检查动态 toolRuntimeRoutes，不要只盯着静态 manifest。
Operations 不是 Runtime Policy
tool-operations 新增后，容易混淆两条线：
toolRuntimeRoutes是“这个工具在本次策略下能不能进 worker / 是否代理”的决策结果。ToolOperations是“工具实例内部调用文件、搜索、进程时走哪个后端”的执行依赖。
例如 bash 可以被 Runtime Policy 判定为 worker-local，但其具体执行仍由注入的 ProcessOperations.exec() 完成；测试环境可以替换为 mock process operations，而不需要改 policy。