143 lines
6.0 KiB
Markdown
143 lines
6.0 KiB
Markdown
---
|
||
title: Tool Runtime Policy
|
||
created: 2026-04-21
|
||
updated: 2026-05-02
|
||
type: concept
|
||
tags: [tool, runtime, agent, backend, config]
|
||
sources: [packages/backend/src/modules/netaclaw/tools/manifest.ts, packages/backend/src/modules/netaclaw/tools/runtime_policy.ts, packages/backend/src/modules/netaclaw/tools/presentation.ts, packages/backend/src/modules/netaclaw/service/tool_resolver.ts, packages/backend/src/modules/netaclaw/subagent/process_protocol.ts, packages/frontend/src/modules/agent/tools/runtime-policy.ts]
|
||
---
|
||
|
||
# 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 方法拆成独立权限。
|
||
|
||
## 三层模型
|
||
|
||
```text
|
||
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`、`custom`
|
||
- `executionMode`: `parallel` 或 `sequential`
|
||
- `supportedInWorker`
|
||
- `workerRoutingHint`: `local`、`main-process-proxy`、`disabled`
|
||
- `requiresShell`
|
||
- `requiresWrite`
|
||
- `requiresSkillScope`
|
||
|
||
这些字段是子 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-local`
|
||
- `main-process-proxy`
|
||
- `disabled`
|
||
|
||
## 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` 强制覆盖：
|
||
|
||
- `auto`
|
||
- `force-local`
|
||
- `force-main-process-proxy`
|
||
- `force-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。
|
||
|
||
## 相关页面
|
||
|
||
- [[tool-governance]]
|
||
- [[tool-system]]
|
||
- [[tool-operations]]
|
||
- [[subagent-session]]
|
||
- [[agent-runtime]]
|
||
- [[frontend-architecture]]
|