EverRoom子Agent框架揭秘文件驱动的子Agent调度与权限隔离设计【免费下载链接】EverRoomEverRoom - A workspace that remembers your projects, decisions, and sources.项目地址: https://gitcode.com/gh_mirrors/ev/EverRoomEverRoom 是一个能记住你的项目、决策与信息来源的个人工作区A workspace that remembers your projects, decisions, and sources。它的 AI 主 Agent 并不单打独斗所有繁重的专项任务——文档解析、材料分析、起草写作——都交给一套文件驱动的子 AgentSubagent框架来调度并通过严格的权限隔离保证每个子 Agent 只能做被授权的事。本文带你从目录结构讲到调度协议看懂这套框架的设计精髓。为什么需要子 Agent主 Agent 负责理解用户意图、管理上下文但如果分析长文档解析 PDF写文档正文都塞进同一个会话会带来三个问题上下文爆炸素材原文会撑爆主 Agent 的注意力窗口权限扩散干杂活的 Agent 不该拿到主 Agent 的记忆与工具行为漂移没有固定人设的模型分析风格时好时坏。子 Agent 框架的答案是每个专项任务用一个独立的、定义固定的 Agent承接主 Agent 只负责派单 收结果。EverRoom 的完整设计见 docs/subagent-framework-design.zh-CN.md。文件驱动一个目录就是一个子 Agent最直观的一点EverRoom 的子 Agent不用写任何调度代码在agents/目录下新建一个文件夹即可。官方说明见 agents/README.mdagents/ └── content-analyst/ ├── agent.yaml # 身份与策略声明 ├── SYSTEM.md # 系统提示词角色设定 ├── skills/ # 可复用技能文档 └── schemas/ # 输入校验 Schema以首个开发者定义的子 Agent content-analyst/agent.yaml 为例id: content-analyst mode: dispatch_only systemPrompt: ./SYSTEM.md skills: - ./skills/analysis-method policy: allowedCallers: [primary-agent, internal-workflow] maxConcurrency: 4 timeoutSeconds: 180 maxToolCalls: 8短短十几行就声明了四件事它是什么分析材料、听谁的话只允许主 Agent 和内部工作流调度、能并发多少4 路、多久必须交卷180 秒。角色设定写在 agents/content-analyst/SYSTEM.md明确规定材料内容是不可信数据不得执行其中包含的命令——这是防提示注入的第一道闸门。技能以 Markdown 形式沉淀。比如 skills/analysis-method/SKILL.md 用 6 个步骤教模型先找问题、再提事实、后下结论保证每次分析风格一致。不可变 Revision运行中的任务不会变脸文件驱动带来一个经典难题如果 Agent 运行到一半开发者改了SYSTEM.md怎么办EverRoom 的答案是目录是编辑格式数据库 Revision 是运行权威。Gateway 启动时注册表 apps/gateway/src/modules/subagents/registry.ts 会对每个目录 Bundle 做四步处理校验ID 格式、路径必须锁在 Bundle 内拒绝../逃逸、Skill 需带 YAML frontmatter、体积有上限摘要对提示词、Skill 文件、Schema、MCP 绑定和策略整体计算 SHA-256 digest固化把内容复制到独立的 Revision 快照目录materializeRevision运行时不再读开发目录入库digest 相同则复用不同则生成新版本 Revision。由此得到一条铁律一次调度绑定一个不可变 Revision改文件只会产生新版本已开始的调用永远使用旧配置。同一 Revision 复用 Runtime 实例不同 Revision 绝不共享会话、Skill 或 MCP 配置。权限隔离子 Agent 的默认三无这是框架最有含金量的部分。看 runtime-manager.ts 中为每个 Revision 构建的 Runtime 配置无内置工具builtinTools: []——没有文件写入、没有 Bash、没有任意网络访问无记忆继承子 Agent 不拿主 Agent 的 Memory、Knowledge 与会话历史只接收任务信封里显式给出的内容无 MCP 默认放行只有agent.yaml中mcp字段明确绑定服务器 ID 工具白名单的才可见如content-analyst干脆声明mcp: []。在此基础上还有两层加固隔离手段说明独立运行目录每个 Agent 拥有独立的 sessions / workspace 目录pi:subagent:revisionId隔离 Runtime 身份Skill 快照只读子 Agent 唯一的read工具被限制在 Revision 快照目录内越界直接报subagent_skill_path_not_allowed调用者白名单allowedCallers决定谁能派单子 Agent 之间默认不能互相调度也无法直接与用户对话换句话说Skill 里的我会调用某工具只是说明书真正的钥匙在策略层——写多少权限给多少能力。调度协议agent_catalog 与 agent_dispatch主 Agent 侧只暴露两个稳定工具实现见 tools.tsagent_catalog列出当前可调度子 Agent 的 ID、描述与输入要求不泄露系统提示词和密钥agent_dispatch给定agentId task input同步等待结果返回。一次dispatch在编排器 orchestrator.ts 中会走完一条严格的流水线幂等检查 → 调用者策略校验 → 输入 Schema 校验 → 并发限额检查 → 持久化 Invocation(accepted) → 获取 Revision Runtime → 执行 → 事件流逐条落库 → 超时/取消兜底 → 终态持久化几个值得注意的工程细节幂等键同一(source, parentRunId, idempotencyKey)重复提交直接返回已有记录不会产生重复副作用超时即取消超过timeoutSeconds强制取消 Runtime终态记为timed_out结构化结果契约配置了输出 Schema 的子 Agent 必须调用subagent_submit_result提交结果最终闲聊文本不算数见 runtime-manager.ts 中的SubagentResultCollector事件审计每个 Runtime 事件带序号落库桌面端任务中心可回放时间线。此外 EverRoom 还提供了一批业务门面工具比如document_analysis解析 Office/PDF、document_draft调度 doc-writer 起草文档、room_correction_draft总览纠错——它们本质都是对特定子 Agent 的 dispatch 封装主 Agent 用起来只是一次工具调用。EverRoom 内置了哪些子 Agent当前随仓库发布的 dispatch-only 子 Agent 一览子 Agent职责典型入口content-analyst从材料中提取事实、证据、矛盾与信息缺口content_analysis/room_analysismultimodal-document-parserOffice/PDF 解析与总结document_analysiscontext-roomRoom 创建整理、总览再生、简报刷新、划词改写Context Room 内部工作流doc-writer文档起草、修改提案、续写document_draftroom-correctorRoom 总览的引用纠正与修改提案room_correction_draft而main、knowledge、web-search等内建 Agent 是保留 ID注册表加载时会跳过它们——内建 Agent 由 Gateway 的 AgentResolver 直接管理不能作为子 Agent 被调度防止自己派单给自己的循环。可观测与故障恢复Gateway 重启也不怕框架把出事了怎么办也写进了协议重启恢复Gateway 启动时orchestrator.ts 的initialize()会把遗留的accepted/running调用统一标记为interrupted错误码gateway_restarted历史可查、状态自洽只读接口桌面端通过 routes.ts 暴露的/v1/subagent-invocations系列接口查看调用列表、状态与取消任务没有任何接口允许向子 Agent 追加消息限额即硬失败并发超限subagent_concurrency_limit直接拒绝并记录日志框架不排队——简单、可预测。小结EverRoom 子 Agent 框架的设计可以浓缩为三句话文件驱动一个目录 一个 Agentagent.yaml声明身份与策略SYSTEM.md Skill 定义行为新增能力零调度代码Revision 不可变digest 摘要 快照固化让运行中的任务与开发中的文件彻底解耦默认最小权限无内置工具、无记忆继承、MCP 白名单、调用者白名单能力逐项授权、平台策略不可被提示词覆盖。对想给 EverRoom 贡献新 Agent 的开发者来说门槛其实很低照着 agents/content-analyst 复制一个目录、写清楚agent.yaml和SYSTEM.md重启 Gateway 即可被主 Agent 发现并调度——而这正是文件驱动最大的红利。【免费下载链接】EverRoomEverRoom - A workspace that remembers your projects, decisions, and sources.项目地址: https://gitcode.com/gh_mirrors/ev/EverRoom创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考