# 权限系统 (Permission System) Agent 权限系统采用**多层纵深防御**架构，从工具级 trait 约束到运行时的 Hook 拦截、路径沙箱、命令黑名单，形成 7 层安全防线。 --- ## 整体架构 ```mermaid graph TD subgraph L1["第一层：工具 Trait 约束"] IB["InterruptBehavior
(Cancel vs Block)"] CS["is_concurrency_safe
(并行安全声明)"] CP["check_permissions
(自定义 PermissionRule)"] SA["causes_sibling_abort
(兄弟中断)"] end subgraph L2["第二层：PermissionChecker 规则引擎"] Rules["有序规则链
Deny → Allow → Ask → Default Allow"] WC["通配符 '*' 全匹配"] end subgraph L3["第三层：Hook 管道"] PreH["PreToolUse
Continue | Block | MutateInput | PermissionRequired"] PostH["PostToolUse
Continue | MutateOutput"] Builtins["3 内置 Hook
Cancellation | Metrics | AuditLog"] end subgraph L4["第四层：文件系统沙箱"] PS["路径沙箱
library_dir / skills_dir / cwd"] PT["穿越防护
拒绝 .. 和 ~"] end subgraph L5["第五层：Bash 命令安全"] Blacklist["黑名单 21 条
交互式/破坏性命令"] Timeout["超时控制 60s (max 120s)"] OutputLimit["输出截断 4000 字符"] end subgraph L6["第六层：子代理隔离"] SilentCtx["Silent 上下文
禁止 ask_user"] FreshMsg["全新消息上下文
不污染父代理"] InheritPerm["继承 PermissionChecker
+ HookRegistry"] end subgraph L7["第七层：运行时安全约束"] MaxSteps["max_steps 上限"] DupDetect["同质调用检测"] TokenBudget["Token 预算 diminishing returns"] Cancel["用户取消 (cancelled_runs)"] end AgentRuntime["AgentRuntime::run_turn()"] --> L1 L1 --> L2 L2 --> L3 L3 --> L4 L4 --> L5 L5 --> L6 L6 --> L7 ``` --- ## 第一层：工具级 Trait 约束 每个工具通过覆写 `AgentTool` trait 的 4 个安全方法声明自身行为边界。 定义位置：`src/agent/tools/mod.rs:179` ### 方法说明 | 方法 | 默认值 | 作用 | |---|---|---| | `interrupt_behavior()` | `Cancel` | 用户取消时的响应：`Cancel` 立即停止（只读工具），`Block` 等待完成（有副作用的写入工具） | | `is_concurrency_safe(args)` | `false` | 是否可与其他工具并行执行。保守默认，只读工具须显式覆写为 `true` | | `check_permissions(args)` | 空 `Vec` | 返回 `PermissionRule` 列表，由 PermissionChecker 运行时逐条匹配 | | `causes_sibling_abort()` | `false` | 该工具失败时是否中止兄弟并行执行（下载/解析类工具可设为 `true`） | ### 工具安全分类表 #### 只读并发安全工具 | 工具 | 域 | `is_concurrency_safe` | `interrupt_behavior` | |---|---|---|---| | `search_papers` | astro/search | `true` | `Cancel` | | `get_paper_metadata` | astro/search | `true` | `Cancel` | | `get_paper_content` | astro/paper | `true` | `Cancel` | | `rag_search` | astro/rag | `true` | `Cancel` | | `query_target` | astro/target | `true` | `Cancel` | | `read_file` | filesystem | `true` | `Cancel` | | `grep_files` | filesystem | `true` | `Cancel` | | `glob_files` | filesystem | `true` | `Cancel` | | `load_skill` | skill | `true` | `Cancel` | #### 写入/IO 串行安全工具 | 工具 | 域 | `is_concurrency_safe` | `interrupt_behavior` | |---|---|---|---| | `download_paper` | astro/paper | `false` | `Cancel` | | `parse_paper` | astro/paper | `false` | `Cancel` | | `file_write` | filesystem | `false` | `Cancel` | | `file_edit` | filesystem | `false` | `Cancel` | | `save_note` | astro/note | `false` | `Cancel` | | `save_memory` | memory | `false` | **`Block`** | | `run_bash` | filesystem | `false` | **`Block`** | | `ask_user` | ask_user | `false` | **`Block`** | | `todo_write` | todo | `false` | `Cancel` | | `compress_context` | compress | `false` | `Cancel` | | `subagent` | subagent | `false` | **`Block`** | > **设计原理**：`Block` 工具在用户取消时忽略中断信号，确保写操作完整提交后才停止。`save_memory` 和 `run_bash` 涉及文件系统修改，`ask_user` 依赖 oneshot 通道生命周期，`subagent` 开启了完整的子代理 ReAct 循环，中断可能导致数据不一致。 --- ## 第二层：PermissionChecker 规则引擎 参考 Claude Code 的 PermissionChecker 设计，提供可编程的权限规则链。 定义位置：`src/agent/runtime/permission.rs` ### 权限判定规则 ``` ┌────────────────────────────────────────────────────────────┐ │ 规则匹配优先级 (first-match-wins) │ │ │ │ 1. Deny { tool_name, reason } — 不可覆盖的拒绝 │ │ 2. Allow { tool_name } — 显式允许 │ │ 3. Ask { tool_name, message } — 需要用户确认 │ │ 4. (default) — 无匹配 → Allow │ │ │ │ 通配符 "*" 匹配所有工具名 │ └────────────────────────────────────────────────────────────┘ ``` ### PermissionChecker API ```rust // src/agent/runtime/permission.rs pub struct PermissionChecker { rules: Vec, // 有序规则列表，先添加的优先级更高 } impl PermissionChecker { pub fn new() -> Self; // 空检查器 = 默认允许所有 pub fn add_rule(&mut self, rule: PermissionRule); // 添加规则 pub fn check(&self, tool_name: &str) -> PermissionResult; // 检查单个工具 pub fn is_denied(&self, tool_name: &str) -> bool; // 快捷 deny 检查 fn matches(pattern: &str, tool_name: &str) -> bool { pattern == "*" || pattern == tool_name // 通配符或精确匹配 } } pub enum PermissionResult { Denied { reason: String }, Allowed, AskUser { message: String }, } ``` ### 使用示例 ```rust // 创建受限检查器：只允许只读操作 let mut checker = PermissionChecker::new(); checker.add_rule(PermissionRule::Deny { tool_name: "run_bash".into(), reason: "此会话中禁止执行命令".into(), }); checker.add_rule(PermissionRule::Deny { tool_name: "download_paper".into(), reason: "禁止下载".into(), }); checker.add_rule(PermissionRule::Ask { tool_name: "file_write".into(), message: "是否允许写入文件？".into(), }); // 默认 Allow — 其余工具正常执行 assert!(checker.check("search_papers").is_allowed()); assert!(checker.check("run_bash").is_denied()); ``` ### 当前集成状态 ```mermaid graph LR subgraph "AgentConfig::from_env_optional()" PC0["解析 AGENT_PERMISSIONS_* 环境变量
构造 PermissionChecker::from_config()"] end subgraph "AgentRuntime::run_turn()" PC1["permission_checker: PermissionChecker
(Deny → Ask → Allow 规则链 + 4种模式)"] end subgraph "SubAgentRunner" PC2["permission_checker: Arc<PermissionChecker>"] PC2 -->|"check(tool_name, Some(&args))"| SubExec["三态检查
Deny→注入错误 | Ask→自动拒绝 | Allow→执行"] end subgraph "execute_parallel() Phase 2.5" PC3["permission_checker: Option<&PermissionChecker>"] PC3 -->|"check() + apply_mode() + 工具级叠加"| DenyCheck["━━ 三态处理 ━━
Deny → 注入错误跳过执行
AskUser → SSE PermissionRequest + oneshot 等待(120s超时)
Allowed → 正常进入执行队列"] end PC0 -.->|"构建"| PC1 PC1 -.->|"传递给"| PC2 PC1 -.->|"传递给"| PC3 style PC3 fill:#ccffcc,stroke:#00aa00 ``` > **✅ 完整已实现**：`executor::execute_parallel()` 在 Phase 2.5（PreToolUse hooks 之后、工具执行之前）执行完整的权限检查管道： > 1. `PermissionChecker::check(tool_name, tool_args)` — 规则链匹配 + 内容级匹配 > 2. `PermissionChecker::apply_mode()` — 模式变换（Bypass/DontAsk/AcceptEdits） > 3. Hook `PermissionRequired` 升级 — hook 请求的权限确认为 AskUser > 4. 工具级 `check_permissions()` 叠加 — 工具自定义规则在 Allow 时升级为 Ask > 5. 最终三态分流：Deny → 注入错误 / AskUser → oneshot 交互(120s 超时) / Allowed → 正常执行 --- ## 第三层：Hook 管道 Hook 系统提供了可编程的事件拦截点，参考 Claude Code 的 PreToolUse/PostToolUse/Stop hooks 设计。 定义位置：`src/agent/hooks.rs` ### PreToolUse 动作类型 ```mermaid graph TD PreToolUse["PreToolUse hook"] PreToolUse --> Continue["Continue
正常执行"] PreToolUse --> Block["Block { reason }
阻止执行，第一个 Block 短路整个链"] PreToolUse --> Mutate["MutateInput { updated_args, additional_context }
修改参数 + 注入附加上下文"] PreToolUse --> PermReq["PermissionRequired { permission, tool_name }
请求权限决策（Phase 2 待完善）"] ``` ### PostToolUse 动作类型 ```mermaid graph TD PostToolUse["PostToolUse hook"] PostToolUse --> Continue2["Continue
保持输出不变"] PostToolUse --> MutateOut["MutateOutput { updated_content }
修改工具输出（如脱敏）"] ``` ### Hook 链执行逻辑 (`run_pre_tool_use`) ```rust // 遍历所有已注册 hook for hook in &self.hooks { let action = hook.pre_tool_use(ctx).await; match action { Block { reason } => { // 第一个 Block 立即短路返回，不执行后续 hook return PreToolUseResult { action, ... }; } MutateInput { updated_args, additional_context } => { // 累积 additional_context（多 hook 拼接） // 更新 final_args（最后一个 MutateInput 的修改生效） } PermissionRequired { .. } => { // 记录日志，但暂不阻塞（Phase 2 完善） } Continue => {} // 继续下一个 hook } } ``` ### 3 个内置 Hook ```mermaid classDiagram class CancellationHook { -cancelled_runs: Arc~Mutex~HashSet~String~~ +pre_tool_use() → Block | Continue +on_session_stop() → 清理取消状态 } class MetricsHook { -data: Arc~Mutex~MetricsData~ +on_session_start() → 关联 session_id +post_tool_use() → 累计工具调用/错误计数 +on_step_complete() → 每 3 步输出摘要日志 +on_session_stop() → 输出终止原因 +snapshot() → 返回可查询的指标快照 } class AuditLogHook { -db: SqlitePool +post_tool_use() → fire-and-forget 写入 agent_audit_log +on_session_stop() → 写入 SESSION_STOP 标记 } class AgentHook { <> +name() &str +on_session_start() +pre_tool_use() +post_tool_use() +on_step_complete() +on_session_stop() +on_subagent_start() +on_subagent_stop() +on_pre_compact() +on_post_compact() } AgentHook <|-- CancellationHook AgentHook <|-- MetricsHook AgentHook <|-- AuditLogHook ``` ### 审计日志 (`agent_audit_log` 表) `AuditLogHook` 在每次工具执行后通过 fire-and-forget（`tokio::spawn`）写入审计记录： | 字段 | 说明 | |---|---| | `session_id` | 会话 ID | | `step` | ReAct 步数 | | `tool_name` | 工具名称 | | `status` | `"OK"` 或 `"FAIL"` | | `elapsed_ms` | 执行耗时（毫秒） | | `output_preview` | 输出内容前 200 字符 | | `agent_name` | 代理身份（`"lead"` 或子代理名） | 会话终止时写入一条 `tool_name = 'session'`、`status = 'SESSION_STOP'` 的汇总记录。 --- ## 第四层：文件系统路径沙箱 所有文件操作工具（`read_file`、`file_write`、`file_edit`、`glob_files`、`grep_files`、`run_bash` 的 `working_dir` 参数）共享的路径安全检查。 定义位置：`src/agent/tools/filesystem/security.rs` ### 允许的根目录 ```rust let allowed_roots = [ config.library_dir.canonicalize(), // 论文库目录 config.skills_dir.canonicalize(), // Agent Skills 目录 std::env::current_dir(), // 项目根目录 ]; ``` ### 安全检查函数 ```mermaid flowchart TD Input["用户提供的路径字符串"] --> PT{"has_path_traversal()
包含 .. 或 ~ ？"} PT -->|是| Reject1["❌ 拒绝"] PT -->|否| Resolve["resolve_path()
绝对路径直接用，相对路径基于 cwd 拼接"] Resolve --> Canon["canonicalize()
消除符号链接"] Canon -->|失败| TryParent["尝试对父目录 canonicalize"] TryParent -->|失败| Reject2["❌ 拒绝：无法解析"] Canon -->|成功| Check{"is_path_allowed()
在 allowed_roots 内？"} TryParent -->|成功| Check Check -->|是| Allow["✅ 允许"] Check -->|否| Reject3["❌ 拒绝：无权访问"] ``` ### 防护能力 | 攻击类型 | 防护方式 | |---|---| | 路径穿越 (`../../../etc/passwd`) | `has_path_traversal()` 拒绝含 `..` 的路径 | | 家目录访问 (`~/`) | `has_path_traversal()` 拒绝含 `~` 的路径 | | 符号链接逃逸 | `canonicalize()` 解析符号链接到真实路径后再检查 | | 绝对路径越界 | `resolve_path()` 解析后再 `is_path_allowed()` | ### 覆盖的工具 | 工具 | 受保护的参数 | |---|---| | `read_file` | `file_path` | | `file_write` | `file_path` | | `file_edit` | `file_path` | | `glob_files` | `pattern` (解析后) | | `grep_files` | `path` | | `run_bash` | `working_dir` | --- ## 第五层：Bash 命令安全校验 `run_bash` 工具在路径沙箱之上叠加了命令级安全校验。 定义位置：`src/agent/tools/filesystem/bash.rs` ### 校验流程 ```mermaid flowchart TD Cmd["command 参数"] --> Trim["trim() 去空格"] Trim --> Empty{"空命令 / bash / bash -c？"} Empty -->|是| Reject1["❌ 拒绝"] Empty -->|否| Lower["to_lowercase()"] Lower --> Blacklist{"黑名单子串匹配
（21 条模式）"} Blacklist -->|命中| Reject2["❌ 拒绝：不允许执行 'X' 类命令"] Blacklist -->|未命中| Execute["✅ 执行"] ``` ### 黑名单（精确首词匹配，已修复子串误伤问题） 校验流程： ```mermaid flowchart TD Cmd["command 参数"] --> Trim["trim() 去空格"] Trim --> Empty{"空命令 / bash / bash -c？"} Empty -->|是| Reject1["❌ 拒绝"] Empty -->|否| Bypass{"命令替换绕过？
$() 或反引号开头的首词"} Bypass -->|是| Reject2["❌ 拒绝"] Bypass -->|否| Extract["extract_first_command_word()
提取首个命令单词"] Extract --> Whitelist{"SAFE_COMMANDS 白名单？
（35 个安全命令）"} Whitelist -->|是| Allow["✅ 直接允许"] Whitelist -->|否| Blacklist{"DANGEROUS_COMMANDS 黑名单？
（33 个精确匹配）"} Blacklist -->|是| Reject3["❌ 拒绝"] Blacklist -->|否| ArgCheck{"DANGEROUS_ARG_PATTERNS？
（5 个危险参数子串）"} ArgCheck -->|命中| Reject4["❌ 拒绝"] ArgCheck -->|未命中| Allow2["✅ 默认允许
（路径沙箱 + 超时兜底）"] ``` **精确匹配 vs 子串匹配（修复前/后对比）**： | 命令 | 修复前（子串） | 修复后（首词精确） | |---|---|---| | `grep "ssh_config" *.rs` | ❌ 误拦（含子串 `ssh `） | ✅ 允许（首词 `grep` 在白名单） | | `echo "use sudo carefully"` | ❌ 误拦（含子串 `sudo `） | ✅ 允许（首词 `echo` 在白名单） | | `cat /usr/share/vim/vimrc` | ❌ 误拦（含子串 `vim `） | ✅ 允许（首词 `cat` 在白名单） | | `python script.py` | ✅ 允许 | ✅ 允许（不在黑名单，默认允许） | | `vim file.txt` | ✅ 拒绝 | ✅ 拒绝（首词 `vim` 在黑名单） | | `$(echo sud; echo o) /etc/passwd` | ✅ 允许（绕过！） | ❌ 拒绝（检测到命令替换绕过） | ### 安全白名单（已启用） ```rust const SAFE_COMMANDS: &[&str] = &[ "ls", "cat", "head", "tail", "find", "grep", "wc", "echo", "pwd", "sort", "uniq", "cut", "tr", "awk", "sed", "jq", "diff", "file", "stat", "du", "df", "env", "printenv", "which", "basename", "dirname", "realpath", "readlink", "xargs", "tee", "date", "sleep", "true", "false", ]; ``` 白名单内的命令**优先放行**，不经过黑名单检查。非白名单命令经过黑名单精确匹配和危险参数二次检查后默认允许。 ### 其他约束 | 约束 | 值 | 说明 | |---|---|---| | 超时 | 默认 60s，最大 120s | `AGENT_TOOL_TIMEOUT_SECS` 环境变量 | | 输出截断 | 4000 字符 | `truncate_content()` | | 工作目录 | library_dir / skills_dir / cwd | 受路径沙箱约束 | ### 已知局限 1. ~~**黑名单子串匹配**~~ — ✅ 已修复：改用首词精确匹配，`grep "ssh_config"` 不再误拦 2. **未限制网络访问** — `curl`、`wget` 不在黑名单中 3. **未限制进程数** — fork bomb（如 `:(){ :\|:& };:`）未被检测 4. **管道/重定向完整放行** — `<`、`>`、`|` 不做限制 5. ~~**`$()` 命令替换**~~ — ✅ 已修复：检测首词位置 `$()` 和反引号绕过 6. ~~**白名单未被使用**~~ — ✅ 已修复：`SAFE_COMMANDS` 已集成到 `validate_bash_command()` 中，白名单命令优先放行 --- ## 第六层：子代理隔离 子代理通过 `SubAgentRunner` 创建上下文隔离的执行环境，参考 Claude Code Subagents 设计。 定义位置：`src/agent/subagent.rs`、`src/agent/tools/subagent.rs` ### 隔离维度对比 | 维度 | 父代理 | 子代理 | |---|---|---| | 消息上下文 | 完整历史 + 所有中间工具调用 | **全新 messages**：仅 `[system_prompt, user_prompt]` | | 工具注册表 | 完整 `ToolRegistry`（19+ 工具） | 完整 `ToolRegistry`（共享同一个引用） | | 工具上下文 | `ToolContext::new()` | `ToolContext::silent()` — **`silent = true`** | | Hook 管道 | 完整 `HookRegistry` | 继承父代理的 `HookRegistry` | | PermissionChecker | 自己的实例 | 继承父代理的 `PermissionChecker` | | 上下文压缩 | 多层压缩（micro/auto/manual） | 独立的自动压缩 | | 死循环检测 | `DuplicateDetector` per turn | 独立的 `(last_call, consecutive_count)` | ### Silent 模式 ```rust // src/agent/tools/mod.rs:114 pub fn silent(app_state: Arc) -> Self { ToolContext { app_state, session_id: String::new(), silent: true, // ← 关键标志 read_file_state: ..., sse_tx: None, // ← 无 SSE 通道 enable_thinking: false, } } ``` **Silent 模式效果**： - `ask_user` 工具检测到 `ctx.silent == true` 时**直接返回错误** - 阻止子代理绕过父代理向终端用户提问 - 无 SSE 通道 → 子代理的工具调用进度不会单独推送到前端 ### 子代理内部权限流程 ```mermaid sequenceDiagram participant SA as SubAgentRunner participant Hook as HookRegistry participant PC as PermissionChecker participant Tool as AgentTool SA->>Hook: PreToolUseContext { tool_name, args } Hook-->>SA: PreToolUseResult { action, final_args } alt action = Block SA-->>SA: 注入错误 tool_result，跳过执行 else action = Continue / MutateInput SA->>PC: is_denied(tool_name) alt 被拒绝 SA-->>SA: 注入错误 tool_result，跳过执行 else 允许 SA->>Tool: execute(final_args, silent_ctx) Tool-->>SA: ToolOutput SA->>Hook: PostToolUse hooks → 可能修改输出 end end ``` > **⚠️ 当前局限**：子代理使用**完整的父代理 ToolRegistry**，不支持按子任务需求裁剪工具列表（如"仅搜索"模式只给只读工具）。未来可引入 `ToolRegistry::restrict()` 方法实现最小权限原则。 --- ## 第七层：运行时安全约束 ReAct 循环中的多层终止条件，防止无限循环和资源耗尽。 定义位置：`src/agent/runtime/mod.rs:442` ### 终止条件矩阵 | 条件 | 触发阈值 | 行为 | |---|---|---| | **最大步数** | `step > max_steps` (默认 8) | 强制 LLM 生成最终答案（不带工具调用），注入提醒消息 | | **同质调用** | 连续 3 次相同 `(tool_name, args)` | 注入错误 tool_result，跳过本轮该工具 | | **Token diminishing returns** | 连续多步无新增信息 | 强制结束，注入"请基于已收集信息直接回答" | | **用户取消** | `cancelled_runs` 含当前 `session_id` | 循环开始和工具执行中双重检查，发送 Error SSE 事件 | | **压缩熔断** | `CompactionCircuitBreaker` 连续失败 | 跳过自动压缩，避免无限压缩循环 | | **Token 硬限制** | `token_hard_limit` (默认 40000) | `TokenBudget` 触发强制动作 | ### 用户取消的双重检查 ```mermaid sequenceDiagram participant User as 用户 participant API as API 层 participant State as cancelled_runs participant Loop as ReAct 循环 participant Exec as 工具执行 User->>API: POST /api/chat/cancel API->>State: insert(session_id) Note over Loop: 每步迭代开始 Loop->>State: contains(session_id)? State-->>Loop: true → break 循环 Note over Exec: 工具执行中 (每 250ms) loop 取消轮询 Exec->>State: contains(session_id)? State-->>Exec: true → interrupt end Note over Exec: InterruptBehavior 判断 alt interrupt_behavior = Cancel Exec-->>Exec: 立即停止，返回 "执行已被用户取消" else interrupt_behavior = Block Exec-->>Exec: 忽略中断信号，等待完成 end ``` - 主循环在**每步开始**检查取消标志 - 工具执行器以 **250ms 间隔**轮询取消状态 - `Block` 工具（`run_bash`、`save_memory`、`ask_user`、`subagent`）忽略取消信号直到自然完成 ### 取消状态生命周期 1. 用户通过 API 端点设置 `cancelled_runs.insert(session_id)` 2. `CancellationHook::pre_tool_use()` 检测到 → 返回 `Block` 3. ReAct 循环入口检测到 → `break` 跳出 4. 工具执行检测到 + `InterruptBehavior::Cancel` → 立即返回 5. `CancellationHook::on_session_stop()` → 清理 `cancelled_runs.remove(session_id)` --- ## 配套安全机制 ### Background Task 安全 位置：`src/agent/tools/background.rs`、`src/agent/background.rs` - `bg_task_run` 用于在后台执行慢速操作（下载、解析） - 后台任务通过 `BgNotificationQueue` 注入结果，不直接访问 Agent 上下文 - 结果注入在下一次 LLM 调用前以 user 消息形式推送 ### 工具输出持久化 位置：`src/agent/tools/persist.rs` - 大型工具结果（超过 `max_tool_output_chars`）写入磁盘，消息中只包含 stub - 写入路径：`{library_dir}/tool-results/{tool_call_id}.txt` - 通过调用外部工具读取完整结果，避免上下文污染 ### Token 预算管理 位置：`src/agent/runtime/token_budget.rs` ``` 软限制 (token_soft_limit, 默认 32000) ↓ 触发渐进式 nudging 提醒 → 建议 LLM 总结/给出答案 ↓ 硬限制 (token_hard_limit, 默认 40000) ↓ 触发强制动作 → 上下文压缩或强制结束 ↓ Diminishing Returns 检测 ↓ 连续无新增信息 → 强制结束 + 直接回答 ``` --- ## 权限检查全链路 一次完整的工具调用穿越全部 7 层防线： ``` 工具调用请求 │ ├─ [L7] 循环入口：步数 / 取消 / diminishing returns 检查 │ ├─ [L7] validate_and_prepare()：死循环检测 + 参数解析 │ ├─ [L3] PreToolUse hooks： │ ├── CancellationHook → 检查 cancelled_runs │ ├── 自定义 Hook → Block? MutateInput? │ └── 返回 final_args + additional_context │ ├─ [L2] PermissionChecker.check() ← ✅ 在 Phase 2.5 调用（PreToolUse hooks 之后、执行之前） │ ├── Deny → 注入错误 result，跳过执行，不进入队列 │ ├── AskUser → 暂视为允许（Phase 2 确认交互待完善） │ └── Allowed → 正常进入执行队列 │ ├─ [L1] 分区器 (ToolPartitioner)： │ └── is_concurrency_safe() 判断 → 并行 or 串行批次 │ ├─ 工具执行 (每工具独立 Future)： │ │ │ ├─ [L1] InterruptBehavior 判断 → Cancel 可中断 / Block 不可中断 │ │ │ ├─ [L4] 路径沙箱 (read_file / file_write / file_edit / glob / grep / bash) │ │ │ ├─ [L5] Bash 黑名单 (run_bash): │ │ ├── validate_bash_command() → 空命令 / 黑名单 │ │ ├── 工作目录路径沙箱检查 │ │ └── 超时控制 (60s default / 120s max) │ │ │ ├─ [L6] ask_user Silent 模式检查 → 子代理中直接返回错误 │ │ │ └─ 超时控制 (AGENT_TOOL_TIMEOUT_SECS, default 120s) │ └─ [L3] PostToolUse hooks： ├── 输出截断 + 大结果持久化 ├── MetricsHook → 累计指标 ├── AuditLogHook → fire-and-forget 审计日志 └── MutateOutput → 输出修改 ``` --- ## Claude Code 权限系统对比分析 > 对比基准：Claude Code (`/home/fmq/program/claudecode/src/utils/permissions/`) > 分析日期：2026-06-17 ### 架构差异总览 | 维度 | AstroResearch (当前) | Claude Code (参考) | 差距 | |------|---------------------|-------------------|------| | 规则引擎 | ✅ PermissionChecker (完成) | ✅ hasPermissionsToUseTool 多步流水线 | 相当 | | 规则匹配粒度 | ✅ 内容级 `Tool(content*)` 前缀/后缀/包含 | ✅ 前缀/通配/内容级 / 正则 | 小 | | AskUser 交互流 | ✅ SSE → PermissionRequestCard → Allow/Deny/Always Allow | ✅ 完整 SSE → Dialog → 决策 | 相当 | | 权限模式 | ✅ Default/AcceptEdits/Bypass/DontAsk | ✅ 6种模式 (含 plan/auto) | 小 | | 规则持久化 | ✅ 环境变量加载 + `PermissionChecker::from_config()` | ✅ settings.json 多层加载 (8级来源优先级) | 小 | | 规则来源追踪 | ✅ `PermissionRuleSource` 枚举 (Env/Session) | ✅ cliArg > command > session > userSettings > ... | 小 | | Bash 权限分类器 | ✅ SAFE_COMMANDS 白名单 + `check_permissions()` 集成 | ✅ AST解析 + AI分类器 + 异步推测 | 中等 | | 拒绝追踪/熔断 | ✅ `DenialTracker` 连续/累计计数 + ReAct 循环熔断 | ✅ 连续/总计拒绝计数 + 自动终止 | 相当 | | 权限 Hook 集成 | ✅ PreToolUseAction::PermissionRequired 完整流程 | ✅ 完整 PermissionRequest hook + 多路径决议 | 相当 | | 规则遮蔽检测 | ✅ `detect_shadowed_rules()` deny/ask 双重检查 | ✅ `shadowedRuleDetection` deny/ask 遮蔽检测 | 相当 | | Auto Mode (AI 分类) | ❌ 无 | ✅ YOLO classifier + 快速路径 + 安全工具白名单 | **远期** | | 权限解释器 | ✅ 启发式 `explain_permission()` (Bash 风险等级 + 路径检测) | ✅ Haiku 生成风险解释 | 中等 | | 会话内规则更新 | ✅ `POST/PUT /api/chat/sessions/:id/permissions/*` | ✅ `/permissions` 命令 + API | 小 | | 子代理权限继承 | ✅ 完整 `check()` 三态检查 | ✅ 完整继承父级权限上下文 | 相当 | | 附加目录沙箱 | ✅ `AGENT_ADDITIONAL_DIRS` + `is_path_allowed()` 扩展 | ✅ `additionalDirectories` 可配置 | 相当 | ### Claude Code 权限流水线 (参考架构) ``` hasPermissionsToUseTool(toolName, input, context): Step 1a: 工具级 deny 规则检查 → deny → 返回 deny Step 1b: 工具级 ask 规则检查 → ask → 返回 ask (sandbox 例外) Step 1c: 工具自定义 checkPermissions() → 内容级规则匹配 Step 1d: 工具实现返回 deny → deny → 返回 deny Step 1e: requiresUserInteraction? → ask → 强制 ask (bypass 免疫) Step 1f: 内容级 ask 规则 → ask → 强制 ask (bypass 免疫) Step 1g: 安全检查 (敏感路径等) → ask → 强制 ask (bypass 免疫) Step 2a: bypassPermissions 模式? → allow → 返回 allow Step 2b: 工具级 allow 规则 → allow → 返回 allow Step 3: 剩余 passthrough → ask → 返回 ask 外层模式变换: dontAsk 模式: ask → deny auto 模式: acceptEdits 快速路径 → 安全工具白名单 → AI分类器 headless: hooks 先运行 → 无 hook 决定 → auto-deny ``` ### 关键设计决策对比 **1. 规则格式** Claude Code 使用 `ToolName(content)` 格式支持内容级规则： ``` Bash → 匹配所有 bash 命令 Bash(npm install) → 匹配精确命令 Bash(npm *) → 前缀通配 Bash(rm:*) → 旧版前缀（已废弃） Read(.env) → 文件模式 mcp__server__tool → MCP 工具级 mcp__server → MCP 服务级 Agent(Explore) → 代理类型级 ``` AstroResearch 已实现相同格式： ``` "*" → 通配所有工具 "tool_name" → 精确工具名匹配 "tool_name(content*)" → 前缀通配（如 "run_bash(rm *)" 匹配 "rm -rf /"） "tool_name(*suffix)" → 后缀通配（如 "read_file(*.env)" 匹配 ".env"） "tool_name(exact)" → 包含匹配（子串命中） "*(content)" → 工具通配 + 内容匹配（如 "*(sudo)" 匹配任意工具的 sudo 命令） ``` 从 args 中自动提取 `command`/`file_path`/`path`/`pattern`/`url` 字段进行内容匹配。 **2. 权限模式** Claude Code 的 6 种模式通过 Shift+Tab 循环切换： - `default` — 标准逐项确认 - `acceptEdits` — 工作目录内文件编辑自动通过 - `bypassPermissions` — 跳过所有 Ask（deny/ask 规则仍生效；安全检查 bypass 免疫） - `dontAsk` — 所有 Ask 转 Deny - `plan` — 计划模式 - `auto` — AI 自动分类（内部使用） AstroResearch 已实现 4 种模式（通过 `AGENT_PERMISSION_MODE` 环境变量或 API 切换）： - `default` — 标准规则链，Ask 触发用户交互 - `acceptEdits` — 工作目录内文件编辑自动通过（路径检查由 executor 完成） - `bypassPermissions` — 跳过所有 Ask（Deny 规则仍生效） - `dontAsk` — 所有 Ask 转为 Deny `PermissionChecker::from_config()` 从 `AgentConfig` 加载环境变量规则并构造完整检查器。 **3. 多路径权限决议** Claude Code 的 AskUser 决议支持多个并行路径，任一先返回即生效（`claim()` 模式）： - 本地 UI 对话框 - Bridge 响应（CCR 远程） - Channel 响应（Telegram 等） - PermissionRequest hooks（后台异步运行） - Bash 分类器（后台推测性异步分类） AstroResearch 已实现完整的 AskUser 交互流： - `PermissionChecker::check()` 返回 `AskUser` 时，executor 发送 `AgentStreamEvent::PermissionRequest` SSE 事件 - 通过 `oneshot` 通道创建 `PendingPermission`，存入 `AppState::pending_permissions` - 等待用户通过前端 `PermissionRequestCard` 组件响应（Allow / Deny / Always Allow），120s 超时自动拒绝 - 单一路径决议（oneshot），不支持多路径 claim 模式 --- ## 优化路线图 ### ✅ P0 — 已全部完成 #### P0-1: 规则加载与持久化 ✅ `AgentConfig::from_env_optional()` 从环境变量加载规则（`AGENT_PERMISSIONS_DENY`/`ALLOW`/`ASK`），`PermissionChecker::from_config()` 按 Deny → Ask → Allow 优先级顺序构造规则链。 **实现位置**: `src/agent/runtime/mod.rs:113-117`, `src/agent/runtime/permission.rs:268-290` #### P0-2: 完成 AskUser 权限交互流 ✅ executor Phase 2.5 中完整的 AskUser 处理： - `AgentStreamEvent::PermissionRequest` SSE 事件 → 前端 `PermissionRequestCard` 组件 - `oneshot` 通道 + `AppState::pending_permissions` 存储 - 120s 超时自动拒绝，支持 Allow / Deny / Always Allow 决策 **实现位置**: `src/agent/runtime/executor.rs:282-422`, `src/api/agent.rs`, `dashboard/src/features/agent/PermissionRequestCard.tsx` #### P0-3: 内容级权限匹配 ✅ `PermissionChecker::matches()` 支持 `"tool_name(content_pattern)"` 格式，前缀通配（`prefix*`）、后缀通配（`*suffix`）、包含匹配，自动从 args 提取 `command`/`file_path`/`path`/`pattern`/`url` 字段。 **实现位置**: `src/agent/runtime/permission.rs:183-255` ### ✅ P1 — 已全部完成 #### P1-1: 权限模式系统 ✅ `PermissionMode` 枚举实现 4 种模式（Default/AcceptEdits/Bypass/DontAsk），通过 `AGENT_PERMISSION_MODE` 环境变量或 API 切换。`PermissionChecker::apply_mode()` 在 executor Phase 2.5 中对检查结果进行模式变换（Bypass 将 Ask→Allowed，DontAsk 将 Ask→Denied）。 **实现位置**: `src/agent/runtime/permission.rs:39-60, 139-177` #### P1-2: Bash 权限接入 PermissionChecker ✅ `RunBashTool::check_permissions()` 调用 `bash_needs_permission()` —— 安全白名单中的命令返回空规则（自动允许），非白名单命令返回 `Ask` 规则。executor Phase 2.5 中与 PermissionChecker 结果叠加。 **实现位置**: `src/agent/tools/filesystem/bash.rs:58-73, 362-365` #### P1-3: 权限 Hook 集成 ✅ `PreToolUseAction::PermissionRequired` 在 executor 中被检测：若 hook 返回 `PermissionRequired` 且 PermissionChecker 返回 `Allowed`，则升级为 `AskUser` 触发用户交互。已修复 Continue 覆盖 meaningful action 的 bug。 **实现位置**: `src/agent/hooks.rs:378-384`, `src/agent/runtime/executor.rs:221-230` #### P1-4: 子代理完整权限继承 ✅ `SubAgentRunner` 使用 `check(tool_name, Some(&final_args))` 进行三态检查：Deny → 注入错误跳过执行，AskUser → 自动拒绝（子代理不应打断用户），Allowed → 正常执行。 **实现位置**: `src/agent/subagent.rs` ### ✅ P2-1、P2-2 — 已实现 #### P2-1: 拒绝追踪与熔断 ✅ `DenialTracker` 追踪连续拒绝和总拒绝数，阈值触发 ReAct 循环终止。 配置：`AGENT_DENIAL_MAX_CONSECUTIVE` (默认 3) / `AGENT_DENIAL_MAX_TOTAL` (默认 20)。 **实现位置**: `src/agent/runtime/denial_tracker.rs`, `src/agent/runtime/mod.rs` #### P2-2: 会话内规则更新 API ✅ `POST /api/chat/sessions/:id/permissions/rules` — add/remove 规则 `PUT /api/chat/sessions/:id/permissions/mode` — 切换权限模式 通过 `AppState::session_permission_checker` (`Arc>`) 实现跨 turn 共享。 **实现位置**: `src/api/permissions.rs`, `src/agent/runtime/executor.rs` Phase 2.5 ### 🟡 P2-3~P2-5 — 远期增强（按需实现） #### P2-3: 规则遮蔽检测 ✅ `PermissionChecker::detect_shadowed_rules()` 检测 Deny/Ask 遮蔽 Allow 的情况，输出 `ShadowedRule` 列表（含 reason + fix 建议），在 AgentRuntime 初始化时通过 `warn!` 日志输出。 **实现位置**: `src/agent/runtime/permission.rs` #### P2-4: 权限解释器 ✅ 启发式 `explain_permission()` 函数，根据工具名和参数生成 `{risk_level, explanation, reasoning, risk}` 结构。Bash 命令通过关键词检测风险等级（HIGH/MEDIUM/LOW），文件操作检测系统路径。结果随 `PermissionRequest` SSE 事件推送到前端。 **实现位置**: `src/agent/runtime/permission_explainer.rs`, `src/agent/runtime/mod.rs` `AgentStreamEvent::PermissionRequest.explanation` #### P2-5: Auto Mode (AI 权限分类器) ❌ 使用 LLM 自动评估工具调用的风险： - 快速路径：`AcceptEdits` 模式自动允许工作目录内的文件编辑 - 安全工具白名单：`read_file`、`grep_files`、`search_papers` 等只读操作自动允许 - AI 分类：对不确定的操作调用快速模型判断安全性 - 失败封闭：分类器不可用时拒绝所有非白名单操作（安全优先） **工作量**: 3-5天 #### P2-4: 权限解释器 在执行前用 LLM 生成人类可读的风险描述： ``` "该命令将执行 npm install，可能修改 node_modules/ 目录并下载外部依赖包。" ``` **工作量**: 1天 #### P2-5: 子代理最小权限 (ToolRegistry::restrict) ```rust impl ToolRegistry { pub fn restrict(&self, allowed_tools: &[&str]) -> Self { // 创建仅包含指定工具的受限注册表 } } ``` **工作量**: 0.5天 --- ## 实现路线图 ``` 已完成 (Phase 1): P0-1 规则加载 + P0-2 AskUser 交互流 + P0-3 内容级匹配 已完成 (Phase 2): P1-1 权限模式 + P1-2 Bash 集成 + P1-3 Hook 集成 + P1-4 子代理继承 已完成 (Phase 3): P2-1 拒绝追踪熔断 + P2-2 会话内规则更新 + P2-3 规则遮蔽检测 + P2-4 权限解释器 + 附加目录沙箱 + 规则来源追踪 远期规划 (按需): P2-5 Auto Mode (AI 分类器) + P2-6 权限解释器 LLM 升级 + 子代理最小权限 + 文件写入大小限制 ``` --- ## 待完善项 | 优先级 | 项目 | 当前状态 | 建议 | |---|---|---|---| | ~~**HIGH**~~ | ~~PermissionChecker 集成到主执行路径~~ | ✅ **已完成** | — | | ~~**HIGH**~~ | ~~Bash 黑名单改为命令解析~~ | ✅ **已完成** | — | | ~~**P0**~~ | ~~规则加载与持久化~~ | ✅ **已完成**：`AgentConfig` 新增 `permission_deny_rules` / `permission_allow_rules` / `permission_ask_rules` / `permission_mode` 字段，通过 `AGENT_PERMISSIONS_*` 环境变量加载 | — | | ~~**P0**~~ | ~~AskUser 权限交互流~~ | ✅ **已完成**：executor Phase 2.5 AskUser 分支重写为完整 oneshot → SSE → 120s 超时流程。前端 `PermissionRequestCard` 组件提供 Allow / Deny / Always Allow | — | | ~~**P0**~~ | ~~内容级权限匹配~~ | ✅ **已完成**：`check(tool_name, tool_args)` 签名，`matches()` 支持 `"tool(content*)"` 格式（前缀/后缀/包含），自动提取 args 字段 | — | | ~~**P1**~~ | ~~权限模式系统~~ | ✅ **已完成**：`PermissionMode` (Default/AcceptEdits/Bypass/DontAsk)，`apply_mode()` 方法，`AGENT_PERMISSION_MODE` 配置 | — | | ~~**P1**~~ | ~~Bash 权限集成~~ | ✅ **已完成**：`RunBashTool::check_permissions()` 调用 `bash_needs_permission()`（安全命令自动允许），executor 合并工具级检查 | — | | ~~**P1**~~ | ~~权限 Hook 集成~~ | ✅ **已完成**：`PreToolUseResult::is_permission_required()`，修复 Continue 覆盖 bug，executor 触发 AskUser | — | | ~~**P1**~~ | ~~子代理完整权限继承~~ | ✅ **已完成**：`is_denied()` → `check(tool_name, Some(&final_args))`，子代理中 AskUser 自动拒绝 | — | | ~~**MEDIUM**~~ | ~~拒绝追踪与熔断~~ | ✅ **已完成** | `DenialTracker`：连续/总计拒绝计数，阈值触发 ReAct 循环终止 | | ~~**MEDIUM**~~ | ~~会话内规则更新 API~~ | ✅ **已完成** | `POST/PUT /api/chat/sessions/:id/permissions/*` 动态 add/remove/mode | | ~~**MEDIUM**~~ | ~~权限解释器~~ | ✅ **已完成** | 启发式 `explain_permission()`，Bash 风险等级 + 路径检测，随 SSE PermissionRequest 推送前端 | | **MEDIUM** | Auto Mode (AI 分类器) | 未实现 | LLM 评估风险，快速路径 + 安全工具白名单 | | **LOW** | 子代理最小权限 | 继承全部父工具 | `ToolRegistry::restrict()` | | **LOW** | 文件写入大小限制 | 无上限 | 添加 `max_file_size` 参数 | | **LOW** | 网络访问控制 | `curl`/`wget` 未限制 | Bash 黑名单扩展 | | **LOW** | 用户权限 profiles | 不支持 | YAML/TOML 权限配置 |