agentic_huge_data_base / wiki
页面 jcode · 8.2 安全系统与通知·DeepWiki 中文全文译文
DeepWiki 中文译文 / jcode / 8.2

8.2 · 安全系统与通知（Safety System and Notifications）

代理式研究运行时 · 本章是 jcode DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目jcode 章节8.2 状态全文译文 模块接口与服务契约、测试、发布与运维、界面与交互、记忆与上下文
项目要点页2.5 参考项目 项目章节目录jcode DeepWiki 原始章节Safety System and Notifications 上一章8.1 下一章9
源码线索
  • src/ambient.rs
  • src/ambient_runner.rs
  • src/channel.rs
  • src/id.rs
  • src/notifications.rs
  • src/safety.rs
  • src/server/client_api.rs
  • src/server/client_disconnect_cleanup.rs
  • src/tool/ambient.rs
  • src/tui/app/remote/reconnect.rs
模块标签
  • 接口与服务契约
  • 测试、发布与运维
  • 界面与交互
  • 记忆与上下文
  • 配置治理

中文译文

安全系统与通知（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/1jehuang/jcode/8.2-safety-system-and-notifications
翻译时间：2026-05-27T08:45:24.985Z
翻译模型：deepseek-chat
原文字符数：8801
项目：jcode (jcode)

---

安全系统与通知

相关源文件

以下文件为本维基页面的生成提供了上下文：

  • src/ambient.rs
  • src/ambient_runner.rs
  • src/channel.rs
  • src/id.rs
  • src/notifications.rs
  • src/safety.rs
  • src/server/client_api.rs
  • src/server/client_disconnect_cleanup.rs
  • src/tool/ambient.rs
  • src/tui/app/remote/reconnect.rs
  • tests/e2e/ambient.rs
  • tests/e2e/binary_integration.rs
  • tests/e2e/burst_spawn.rs
  • tests/e2e/main.rs
  • tests/e2e/provider_behavior.rs
  • tests/e2e/safety.rs
  • tests/e2e/session_flow.rs
  • tests/e2e/test_support/mod.rs
  • tests/e2e/transport.rs

jcode 安全系统提供了一个健壮的框架，用于对代理行为进行分类、管理人工参与的权限控制以及分发多通道通知。该系统确保代理可以自主执行常规任务，同时敏感或破坏性操作仍处于用户控制之下，即使代理在后台环境模式下运行也是如此。

行为分类与等级

系统将每个工具执行或代理行为划分为 ActionTier 枚举中定义的两个等级之一 src/safety.rs:13-18。

等级描述示例
AutoAllowed非破坏性、只读或低风险行为，代理无需明确确认即可执行。read、ls、grep、codesearch、memory、todo src/safety.rs:110-121
RequiresPermission修改文件系统、执行代码或涉及外部副作用的行为。write、shell_execute、delete_file、git_commit

SafetySystem::classify 函数 src/safety.rs:156-163 通过将行为名称与硬编码的 AUTO_ALLOWED 白名单进行匹配来执行此映射 src/safety.rs:110-122。

来源
  • src/safety.rs:13-18
  • src/safety.rs:110-122
  • src/safety.rs:156-163

权限生命周期

当某个行为需要权限时，SafetySystem 会启动一个正式的请求生命周期。该过程弥合了异步代理运行时与用户可用性之间的差距。在后台模式下，ensure_ambient_session 守卫 src/tool/ambient.rs:93-102 确保需要权限的工具仅对已注册的后台会话可用 src/tool/ambient.rs:73-91。

数据流：从请求到决策
  1. 请求发起：代理运行时调用 SafetySystem::request_permission src/safety.rs:166-178，并提供 PermissionRequest src/safety.rs:32-43。
  2. 持久化：请求被添加到由 Mutex 保护的队列中，并立即持久化到磁盘（通常为 ~/.jcode/safety/queue.json）src/safety.rs:170-173。
  3. 通知：NotificationDispatcher 通过所有已配置的通道发送告警 src/safety.rs:175-176。
  4. 决策：用户通过 TUI、专用 CLI 命令或交互式回复（电子邮件、ntfy 等）批准或拒绝请求。
  5. 完成：决策记录在 Decision 结构体中 src/safety.rs:55-62，请求从队列移至历史日志，代理解除阻塞。
权限状态机

下图展示了权限请求在系统中的状态转换过程。

权限请求生命周期

graph TD
    subgraph "代理运行时 (src/agent.rs)"
        A["工具执行"] --> B{"SafetySystem::classify()"}
        B -- "AutoAllowed" --> C["执行工具"]
        B -- "RequiresPermission" --> D["SafetySystem::request_permission()"]
    end

    subgraph "SafetySystem (src/safety.rs)"
        D --> E["添加到队列"]
        E --> F["SafetySystem::persist_queue()"]
        F --> G["NotificationDispatcher::dispatch_permission_request()"]
    end

    subgraph "通知通道 (src/notifications.rs)"
        G --> H["send_ntfy()"]
        G --> I["send_desktop()"]
        G --> J["jcode_notify_email::send_email()"]
    end

    J -- "回复：批准" --> K["jcode_notify_email::poll_imap_once()"]
    K --> L["SafetySystem::record_decision()"]
    L --> M["更新 history.json"]
    M --> N["通过 PermissionResult 解除代理阻塞"]
来源
  • src/safety.rs:32-62
  • src/safety.rs:166-178
  • src/notifications.rs:105-130
  • src/tool/ambient.rs:73-102

通知分发器与通道

NotificationDispatcher src/notifications.rs:50-54 负责发送即忘式的告警投递。它会区分"安全"正文（用于公共/第三方通道）和"详细"正文（用于私有通道）。

通道与配置
通道方法安全级别用途
ntfy.shHTTP PUT/POST公共（已消毒）通过 ntfy 应用向移动设备推送通知 src/notifications.rs:174-184。
桌面notify-send / DBus私有用户在其机器前时发出的本地系统告警 src/notifications.rs:187-197。
电子邮件SMTP（通过 lettre）私有详细日志和交互式批准按钮 src/notifications.rs:201-215。

分发器使用 Priority 级别 src/notifications.rs:21-28 来调整投递的紧急程度（例如，对于关键安全问题使用 Urgent）。

交互式电子邮件系统（jcode-notify-邮件）

jcode-notify-email crate 提供了用于生成和解析电子邮件的专用逻辑。它使用 lettre 进行发送，使用 imap 接收回复。

  • HTML 生成：build_permission_email_html src/notifications.rs:120-120 创建包含 mailto: 链接的电子邮件。这些链接会在主题行中预填充 [jcode-perm:req_ID] 标签。
  • IMAP 轮询：poll_imap_once src/notifications.rs:15-17 在收件箱中搜索包含权限 ID 的未读邮件。
  • 回复解析：parse_permission_reply src/notifications.rs:15-17 使用简单的关键词检测（例如"approve"、"yes"、"deny"）从电子邮件正文中提取用户的意图。
来源
  • src/notifications.rs:21-54
  • src/notifications.rs:174-215
  • src/notifications.rs:15-17

系统集成

安全系统深度集成到 AmbientRunner 中。当后台周期完成时，系统会生成一个 AmbientTranscript src/safety.rs:87-104，汇总所有已执行的行为，然后通过 dispatch_cycle_summary src/notifications.rs:82-103 进行分发。

安全与通知架构

classDiagram
    class SafetySystem {
        -Mutex~Vec~PermissionRequest~~ queue
        -Mutex~Vec~Decision~~ history
        -NotificationDispatcher notifier
        +classify(action) ActionTier
        +request_permission(request) PermissionResult
        +expire_dead_session_requests(via)
    }

    class NotificationDispatcher {
        -reqwest::Client client
        -SafetyConfig config
        -ChannelRegistry channels
        +dispatch_cycle_summary(transcript)
        +dispatch_permission_request(action, description, request_id)
    }

    class jcode_notify_email {
        <<crate>>
        +send_email(request)
        +poll_imap_once()
        +build_permission_email_html()
    }

    class AmbientRunner {
        <<src/ambient_runner.rs>>
        +run_cycle()
    }

    SafetySystem --> NotificationDispatcher : 使用
    NotificationDispatcher --> jcode_notify_email : 使用
    SafetySystem ..> PermissionRequest : 管理
    SafetySystem ..> Decision : 记录
    AmbientRunner --> SafetySystem : 检查权限
关键函数
  • SafetySystem::new()：初始化系统，并通过 queue_path 和 history_path 从磁盘加载持久化数据 src/safety.rs:136-154。
  • SafetySystem::expire_dead_session_requests()：如果发起请求的代理会话不再活跃，则清理待处理的请求 src/safety.rs:183-217。
  • NotificationDispatcher::dispatch_cycle_summary()：在后台运行后发送已修改记忆和压缩操作的摘要 src/notifications.rs:82-103。
  • register_ambient_session()：将会话标记为符合后台安全工作流条件 src/tool/ambient.rs:73-77。
来源
  • src/safety.rs:87-104
  • src/safety.rs:136-154
  • src/safety.rs:183-217
  • src/notifications.rs:82-103
  • src/tool/ambient.rs:73-77