AtomCodeReverseEngineer

Appearance

AtomCode 深度盲区分析 #12 — 权限系统、日志系统、终端回退机制 ​

持续分析循环 — 2026-06-24 14:32 发现权限系统、日志系统、终端回退机制等未文档化子系统

1. 权限决策系统 ​

源文件: crates/atomcode-daemon/src/permission_bridge.rs

1.1 权限决策请求 ​

rust
struct PermissionDecisionRequest {
    // 3 个字段
    call_id:        String,     // 工具调用 ID
    decision:       Decision,   // 决策 (allow/deny/always_allow/allow_persist)
    // 还有 1 个额外字段
}

enum Decision {
    Allow,          // 允许一次
    Deny,           // 拒绝
    AlwaysAllow,    // 总是允许（per 工具）
    AllowPersist,   // 允许持久化（per 工具+路径组合）
}

1.2 权限决策生命周期 ​

用户输入
  → 工具被调用
  → 安全检查
    ├── 正常操作 → 执行工具
    └── 敏感操作 → PermissionRequest 事件
                    → WebUI/TUI 显示审批对话框
                      ├── "Deny"         → 拒绝，记录
                      ├── "Approve"      → 允许一次
                      ├── "Always allow" → 永远信任此工具
                      └── "Always allow this tool" (持久化) → 写入 config

1.3 MCP 工具特殊处理 ​

javascript
// WebUI 中 MCP 工具的"总是允许"按钮单独处理
if (e.tool_name.startsWith("mcp__")) {
    // 显示 "Always allow" 按钮（仅有 allow_persist 按钮）
}

1.4 dangerously_skip_permissions ​

特殊 CLI 参数 --dangerously-skip-permissions 可完全跳过权限检查：

rust
// CLI 参数解析
"--dangerously-skip-permissions"
// 在 daemon 模式下禁用所有安全提示

1.5 WebUI 权限对话框本地化 ​

javascript
"perm.title":         "Tool approval request",
"perm.args":          "Arguments",
"perm.deny":          "Deny",
"perm.approve":       "Approve",
"perm.alwaysAllow":   "Always allow",
"perm.allowPersist":  "Always allow this tool",

1.6 权限桥接 ​

Daemon 通过 permission_bridge 模块将 TUI/CLI 的权限决策桥接到 WebUI：

rust
// permission_bridge.rs 主要职责:
// 1. 接收 WebUI 的 PermissionDecisionRequest
// 2. 转发到 agent 系统的权限检查模块
// 3. 返回决策结果

2. 终端回退机制（之前分析不完整） ​

2.1 通知回退策略 ​

Strategy: terminal-native notifications first (kitty / WezTerm / iTerm2),
while some OS fallbacks may still notify even if AtomCode is focused.

完整通知回退链：

  1. Kitty 协议 (终端内通知: \x1b]777;notify;...)
  2. WezTerm 协议 (通过 WEZTERM_PANE 检测)
  3. iTerm2 协议 (通过 TERM_PROGRAM 检测)
  4. notify-send (Linux 桌面)
  5. osascript (macOS 原生)
  6. terminal-notifier (macOS 备用)

2.2 background_only 策略 ​

SubAgentConfig 的 background_only 字段说明：

`background_only` is best-effort: focus-aware terminal protocols honor it,
while some OS fallbacks may still notify even if AtomCode is focused.

2.3 终端聚焦检测 ​

工具链：

  • Kitty 检测: KITTY_WINDOW_ID
  • WezTerm 检测: WEZTERM_PANE
  • Ghostty 检测: ghostty 环境变量
  • tmux 检测: TMUX 环境变量
  • iTerm2 检测: TERM_PROGRAM=iTerm.app
  • Apple Terminal 检测: TERM_PROGRAM=Apple_Terminal

2.4 系统特定路径 ​

macOS Pgyer 安装残留路径证实

/Applications/PgyVisitor_download.app/Library/LaunchDaemons/com.oray.pgy.plist
Library/Logs/PgyVisitor
ip=/Applications/PgyVisitor_download.app/Library/LaunchDaemons/com.oray.pgy.plist

3. 子代理完整生命周期 ​

此前覆盖不完整的领域

3.1 SubAgentConfig 完整配置 ​

toml
[sub_agent]
initial_turns =      # 初始回合数（默认值）
max_turns =          # 最大回合数
max_concurrent =     # 最大并发子代理数
min_duration_secs =  # 最小运行时长
background_only =    # 是否仅后台运行（参考上方说明）

3.2 9 种子代理终止条件 ​

源自 SUBAGENT_SYSTEM_ANALYSIS.md：

#终止条件说明
1MaxTurns达到最大回合数
2Timeout超时（默认 5 分钟）
3SkillComplete技能执行完成
4UserInterrupt用户中断
5ErrorLimit错误达到上限
6ToolError工具调用错误
7SessionEnded会话结束
8BackgroundOnly后台模式限制
9MinDuration最小运行时长未达到

3.3 子代理调度 ​

rust
// subtask_driver 模块
// 1. 接收子代理创建请求
// 2. 检查 max_concurrent 限制
// 3. 排队等待可用槽位
// 4. 驱动子代理回合循环
// 5. 收集结果或错误
// 6. 返回主代理合并

4. PermissionDecision 错误类型 ​

not_found           → 未找到指定资源
open_atomcode       → 打开 AtomCode 相关路径
dangerously_skip_permissions → 跳过权限检查
network_error       → 网络错误
server_error        → 服务器错误
invalid_args        → 无效参数

4.1 错误类型分类 ​

rust
enum PermissionError {
    NetworkError,               // 网络不可达
    ServerError,                // 服务端错误
    InvalidArgs,                // 参数校验失败
    NotFound,                   // 资源未找到
    OpenAtomCode,               // 内部路径访问
    DangerouslySkipPermissions, // 跳过权限（CLI 参数）
    InputTokens,                // 输入 Token 限制
    OutputTokens,               // 输出 Token 限制
    CachedTokens,               // 缓存 Token 统计
    HadError,                   // 出现错误
    ContextWindow,              // 上下文窗口超限
    SystemTokens,               // 系统 Token 统计
    ToolDefTokens,              // 工具定义 Token
    ToolResultTokens,           // 工具结果 Token
    RateLimited,                // 被限流
    StreamInterrupted,          // 流中断
    StreamTimeout,              // 流超时
    Timeout,                    // 超时
    IoError,                    // IO 错误
    HttpError,                  // HTTP 错误
    QuotaExhausted,             // 配额耗尽
    DeniedByUser,               // 用户拒绝
    BlockedByHook,              // 钩子阻止
    LoopDetected,               // 循环检测
    SkillNotFound,              // 技能未找到
    SkillDisabled,              // 技能已禁用
    SkillEmptyTemplate,         // 技能模板为空
}

总结 ​

#盲区此前覆盖本次新增
1权限决策系统 (allow/deny/always_allow/allow_persist)部分✅ 完整 4 级决策 + MCP 特殊处理
2PermissionDecisionRequest 3 字段无✅
3dangerously_skip_permissions CLI 参数无✅ daemon 模式禁用所有安全检查
4通知回退链 (终端 → 桌面 → macOS)部分✅ 完整回退链 + 聚焦检测
5background_only 策略解释无✅ best-effort 注解
6子代理完整 9 种终止条件部分✅ 全部列出
7PermissionError 类型系统无✅ 25+ 错误变体
8macOS Pgyer 安装残留证据无✅ plist 路径证实

文档总计: 54 份 | 以发现的 Rust 结构体: 110+

本报告由持续分析循环生成 — 第 12 轮盲区挖掘

基于 VitePress 构建 · AtomCode v4.25.3 逆向工程分析文档