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

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

代理式研究运行时 · 聚焦本章的模块关系、源码依据与实现要点。

项目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

安全系统与通知

相关源文件

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

  • 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，请求从队列移至历史日志，代理解除阻塞。
权限状态机

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

权限请求生命周期

jcode · 权限状态机 · 图 1
jcode · 权限状态机 · 图 1

来源： 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 进行分发。

安全与通知架构

jcode · 系统集成 · 图 2
jcode · 系统集成 · 图 2
关键函数
  • 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