Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

运行时内部机制

本页面是 Agents 部分其余内容的架构深度配套文档：介绍运行时如何强制执行每个代理的权限、限定内存范围以及归属日志。有关配置和运行代理，请从 Agents 开始；有关架构级别的字段参考，请参阅 Config；有关实时设置步骤，请参阅 Multi-agent setup。

权限模型

每个智能体的有效 SecurityPolicy 由 SecurityPolicy::for_agent(config, alias) 构建：

  1. 从智能体的风险配置文件（[risk_profiles.<profile>]）开始。
  2. 将边界设置为每个代理的工作区目录（<install>/agents/<alias>/workspace/）。
  3. 遍历 [agents.<alias>.workspace.access]：
    • Read（读取）→ 同级的工作区会进入只读白名单。
    • Write / ReadWrite → 同级的工作区进入读写允许列表。
  4. 如果 [agents.<alias>.workspace.unrestricted_filesystem] 为 true，请关闭 workspace_only。

只读白名单由 file_read（以及其他读取类工具）遵循；读写白名单则控制 file_write、file_edit、git_operations 以及 shell 工具涉及路径操作的调用。POSIX 设备文件（/dev/null、/dev/zero、/dev/random、/dev/urandom）始终可读，因此 shell 习惯用法无需为每个 agent 配置即可正常工作。

SubAgent 生成会强制执行子代理不能超越其父代理权限的规则。验证器的完整轴列表和预算共享行为记录在 委派 → 权限继承。

内存模型

每个智能体都有自己的 Arc<dyn Memory> 实例。该工厂（zeroclaw_memory::create_memory_for_agent）会根据后端类型进行分发：

  • SQLite / Postgres / Lucid：全局共享的安装级存储。agents 表将别名映射到 UUID，memories 表通过 agent_id 引用该 UUID。工厂将内部后端封装在 AgentScopedMemory 中，它会在每次存储时通过 store_with_agent 标记绑定智能体的 UUID，并在每次召回时通过 recall_for_agents 使用解析后的允许列表进行过滤。
  • Markdown：按 agent 划分目录。每个 agent 的 MarkdownMemory 写入 <install>/agents/<alias>/workspace/MEMORY.md 和 memory/YYYY-MM-DD.md。跨 agent 检索由 AgentScopedMarkdownMemory 组合而成，它持有绑定 agent 的 MarkdownMemory 以及一组 (alias, MarkdownMemory) 对等集合，并将各自结果合并，在每行加上 [<alias>] 归属前缀。
  • Qdrant：共享集合，按 payload 建立键。agent_id payload 字段用于标识各个 agent 的归属；recall_for_agents 会过量获取数据，并根据 payload 进行后置过滤。
  • None：空操作存根。包装器仍然存在，以保持运行时路径统一。

不支持跨后端的跨代理内存：配置加载时的架构校验器会拒绝指向不同后端的同级项的 read_memory_from 条目。

重命名和删除生命周期

请使用网关仪表盘的代理控制项或专用的 zeroclaw agents CLI 执行重命名和删除。在启用 gateway 和 agent-runtime 的标准构建中，这两个界面都会执行引用和所属状态的级联处理；直接在 TOML 中移除或重新设置 agents.<alias> 的键名，或通过通用配置设置器执行此操作，则不会进行级联处理。功能精简版 CLI 仍会更新配置引用，但会警告所属状态未进行级联处理，因此执行生命周期操作时，请使用同时启用这两项功能的构建版本。

两种操作都会先将配置更改持久化，然后再执行自有状态副作用。重命名会先重写配置引用，然后移动每个别名的默认工作区，并更新记忆、cron、ACP 和会话状态的指向。删除会先拒绝处理存在硬引用或活跃 ACP 会话的情况，然后移除配置条目和软引用，再尝试执行工作区归档、自有状态导出与清理，以及清除会话归属信息。

持久化后的副作用是尽力而为的，并会报告已暴露的失败，但归档文件写入失败可能只会出现在网关日志中。重命名警告表示需要重试同一个网关 API 重命名操作，以收敛旧别名下遗留的残留内容。删除后，在依赖归档进行恢复之前，请先验证归档内容和日志。不支持自动恢复。

有关当前的控制措施、阻塞项、归档布局和操作员检查，请参阅多智能体设置演练。

今天不支持

  1. 跨后端跨代理内存访问（例如 SQLite 代理读取 Postgres 代理的行）。
  2. 从 agent 删除存档中自动恢复。
  3. 每个 agent 的密钥命名空间隔离：存在一个工作区范围的 SecretStore。
  4. 用于跨代理作用域的 Lucid 线格式扩展。