DeerFlow 授权身份链路实战:从 Gateway 防伪到 Guardrail 的可信 Principal 传播机制
DeerFlow 授权身份链路实战从 Gateway 防伪到 Guardrail 的可信 Principal 传播机制【免费下载链接】deer-flowAn open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of tasks that could take minutes to hours.项目地址: https://gitcode.com/GitHub_Trending/de/deer-flowDeerFlow 的 Phase 1A-1 阶段要解决一个具体问题让谁在执行工具这一身份信息从 Gateway 认证状态一路可信地传播到执行时刻的 Guardrail 授权判断中并在链路上清除一切客户端伪造的身份字段。读完本文你能完整掌握 DeerFlow 可信授权身份链的设计契约、Gateway 防伪边界的实现细节、Principal builder 的统一构造规则以及 subagent 身份继承与 Guardrail adapter 的落点——这套链路正是 Phase 1A-1 实施计划所固定的端到端方案。1. 目标链路一次请求中的身份生命周期本 PR 完成一条可信、可测试的授权身份链路覆盖从 Gateway 到 Guardrail 的全部关键节点Gateway 认证状态 → 清除客户端伪造字段 → 服务端注入 is_internal → lead runtime context → task_tool 捕获 → SubagentExecutor 复制 → subagent runtime context → GuardrailRequest → GuardrailAuthorizationAdapter → build_principal_from_context() → Principal这条链路的设计意图是身份的唯一权威来源是服务端认证状态request.state而不是客户端请求体。客户端可以在body.config[context]、body.config[configurable]或顶层body.context中伪造任何字段但只有经过 Gateway 清理与重新盖章restamp后的值才会进入下游。合并后的兼容性承诺有三条authorization.enabled: false时工具集合和工具执行决策不变runtime context 新增服务端身份字段是有意的可观察变化现有 adapter 异常传播语义保持不变。2. 固定安全契约2.1 Principal7 个字段的显式构造Principal是授权判定中执行者的数据结构定义在 provider.py 中dataclass class Principal: user_id: str | None None role: str | None None oauth_provider: str | None None oauth_id: str | None None channel_user_id: str | None None is_internal: bool False attributes: dict[str, Any] field(default_factorydict)build_principal_from_context()必须显式构造全部 7 个字段user_id/role/oauth_provider/oauth_id/channel_user_id/is_internal/attributes规则如下user_role为None或空字符串时使用default_role未知但非空的角色原样保留不能回退到默认角色避免把admin之外的合法自定义角色误降级is_internal只有原值严格等于True时才为True1、true均不合法authz_attributes为None或缺失时解析为{}非空authz_attributes必须实现Mapping否则抛TypeErrorattributes 每次都复制为新字典不共享可变引用builder 是纯函数不读全局 config、不缓存、不修改输入。2.2 Gateway 可信边界服务端拥有字段is_internal、authz_attributes和channel_user_id是服务端拥有server-owned字段安全规则为必须从config[context]和config[configurable]清除客户端值is_internal只能由request.state.auth_source AUTH_SOURCE_INTERNAL产生channel_user_id只能来自内部认证 IM 调用方的顶层body.context普通 session 请求和body.config两个 section 中的值必须删除必须使用直接赋值runtime_context[is_internal] ...不能使用setdefault否则客户端伪造值会抢先存活必须在user_id is None等所有 early return之前写入保证任何请求路径都拿到定义明确的is_internal。从当前源码看Phase 1A-1 落地后 services.py 中的服务端拥有键集合已扩展为_SERVER_OWNED_RUNTIME_CONTEXT_KEYSuser_id对非 internal 调用方同样是服务端拥有的客户端伪造值会被清除后仅从request.state.user重新盖章清理与注入逻辑集中在inject_authenticated_user_context()函数顶部# --- Server-owned authorization and sandbox lifecycle identity fields --- runtime_context config.setdefault(context, {}) if not isinstance(runtime_context, dict): raise TypeError(run context must be a mapping) for key in _SERVER_OWNED_RUNTIME_CONTEXT_KEYS: runtime_context.pop(key, None) configurable config.get(configurable) if isinstance(configurable, dict): for key in _SERVER_OWNED_RUNTIME_CONTEXT_KEYS: configurable.pop(key, None) auth_source getattr(getattr(request, state, None), auth_source, None) # 外部调用方的 user_id 也是服务端拥有字段先清除再重新盖章 user getattr(getattr(request, state, None), user, None) if auth_source ! AUTH_SOURCE_INTERNAL and getattr(user, system_role, None) ! INTERNAL_SYSTEM_ROLE: runtime_context.pop(user_id, None) if isinstance(configurable, dict): configurable.pop(user_id, None) runtime_context[is_internal] auth_source AUTH_SOURCE_INTERNAL if auth_source AUTH_SOURCE_INTERNAL and request_context is not None: channel_user_id request_context.get(channel_user_id) if channel_user_id is not None: runtime_context[channel_user_id] channel_user_id对应实施记录在 实施笔记中追加 Phase 1A-1 决策日志internal 来自服务端 auth source、Gateway 清除服务端拥有字段、adapter 复用唯一 builder 等。2.3 传递语义subagent 必须无差别继承Subagent 必须继承 parent context 的is_internal和合法 attributesis_internalFalse也必须显式写回不能按 truthy 条件省略省略会导致下游无法区分未设置和明确外部attributes 在 task 捕获、executor 构造和 context 写回时均使用副本非 Mapping attributes 在所有进程内消费边界统一抛TypeError——不能某些层抛错、另一些层静默变成{}Guardrail adapter 必须复用 Principal builder不能维护第二套默认角色或 attributes 解析逻辑。3. Principal builder唯一的身份构造入口实现位于 principal.py核心是一个共享的规范化函数加一个纯函数 builderdef normalize_authz_attributes(raw: Any) - dict[str, Any]: Validate and copy authz_attributes into a fresh dict. if raw is None: return {} if isinstance(raw, Mapping): return dict(raw) raise TypeError(fauthz_attributes must be a Mapping, got {type(raw).__name__}) def build_principal_from_context( context: Mapping[str, Any], *, default_role: str, ) - Principal: resolved_role context.get(user_role) if resolved_role is None or resolved_role : resolved_role default_role return Principal( user_idcontext.get(user_id), roleresolved_role, oauth_providercontext.get(oauth_provider), oauth_idcontext.get(oauth_id), channel_user_idcontext.get(channel_user_id), is_internalcontext.get(is_internal) is True, attributesnormalize_authz_attributes(context.get(authz_attributes)), )两个实现细节值得注意normalize_authz_attributes被抽成共享函数。计划文档中 builder、task_tool、executor、middleware 四层各写一段相同的 Mapping 校验分支落地时收敛为单一规范化点——所有进程内消费边界middleware.py、executor.py、task_tool.py都 import 它从代码结构上保证了非 Mapping 一律TypeError的契约不会被某一层遗漏。is_internalcontext.get(is_internal) is True用is而非真值判断把1、true等伪造形态一律视为外部调用方。行为测试集中在 test_authorization_principal.py覆盖空 context、部分 context、全 7 字段映射None//缺失 role 回退default_role未知非空 role 原样保留True/False/1/true/None的严格布尔行为attributes 缺失或None得到{}Mapping 被复制修改输入不影响 Principal非 Mapping 抛TypeError且错误信息包含实际类型名oauth 与 channel identity 正确映射。4. Gateway 防伪测试驱动的可信边界计划文档要求 Gateway 防伪测试复用真实的配置装配顺序而不能只测孤立函数build_run_config → merge_run_context_overrides → strip_internal_context_keys非 internal 请求 → inject_authenticated_user_context测试必须分别覆盖三个伪造入口且断言新增覆盖逻辑是唯一通过原因不能用本来就被body.context白名单过滤的空路径body.config[context]伪造is_internalTruebody.config[configurable]伪造is_internalTrue两个入口分别伪造authz_attributes。断言要点普通/session 请求最终context.is_internal is False且configurable.is_internal被删除两个 section 中的authz_attributes都被删除internal 请求最终is True但客户端伪造的 attributes 同样被删除userNone、auth source 缺失或 session 时仍写入FalseuserNoneauth_sourceinternal时仍写入True非 Mapping runtime context 显式抛TypeError而不静默跳过。相关测试位于 test_gateway_services.py。5. 身份跨进程内边界的复制task_tool 与 SubagentExecutor身份进入 lead agent 的 runtime context 后第一次跨边界传播发生在task_tool派生子代理时。task_tool.py 中的 parent identity capture 块现在无条件携带两个新字段# Propagate authorization identity: is_internal (strict bool) and # authz_attributes (validated Mapping, copied). is_internal parent_context.get(is_internal) is True authz_attributes normalize_authz_attributes(parent_context.get(authz_attributes)) # ... 无条件加入 executor_kwargs随后 SubagentExecutor 在构造参数中接收这两个字段构造时严格校验并复制context 写回时无条件执行包括False# 构造时 self.is_internal is_internal self.authz_attributes normalize_authz_attributes(authz_attributes) # context write-back无条件含 False context[is_internal] self.is_internal context[authz_attributes] dict(self.authz_attributes)测试方面test_task_tool_core_logic.py 覆盖 parentis_internalTrue/False显式传递、Mapping 复制、捕获后修改 parent 不影响 executor kwargs、非 Mapping 抛TypeErrortest_subagent_executor.py 覆盖构造参数写回、构造与写回两次复制的隔离性、以及 executor 直接收到非 Mapping attributes 时的TypeError。6. Guardrail 层GuardrailRequest 扩展与 adapter 复用执行时刻的身份最终收敛到 Guardrail 中间件。provider.py 中GuardrailRequest新增的三个字段全部带默认值保证向后兼容channel_user_id: str | None None is_internal: bool False authz_attributes: dict[str, Any] field(default_factorydict)middleware.py 在构造 request 前用普通分支完成 attributes 校验并做严格布尔映射channel_user_idcontext.get(channel_user_id), is_internalcontext.get(is_internal) is True, authz_attributesnormalize_authz_attributes(context.get(authz_attributes)),而 GuardrailAuthorizationAdapter 的职责是把AuthorizationProvider适配为GuardrailProvider从而复用现有GuardrailMiddleware的执行期拦截不新增中间件类。关键约束在_to_authz()中体现principal build_principal_from_context( { user_id: gr.user_id, user_role: gr.user_role, oauth_provider: gr.oauth_provider, oauth_id: gr.oauth_id, channel_user_id: gr.channel_user_id, is_internal: gr.is_internal, authz_attributes: gr.authz_attributes, }, default_roleself._default_role, )构造函数增加default_role: str user并保存Phase 1B 自动装配 adapter 时必须显式传入AuthorizationConfig.default_role不得手工构造 Principal必须走 builder保证 Layer 1工具装配与 Layer 2执行期 adapter共享同一套 role/attributes 语义不捕获 provider 异常、不实现fail_closed——异常继续向上传播由GuardrailMiddleware基于其fail_closed参数统一处理避免两层逻辑分叉同步evaluate()与异步aevaluate()通过同一条_to_authz()路径产生语义一致的完整 Principal。相应地provider.py 中Principal的生命周期说明也被更新为adapter 每次请求实时构建不缓存过期身份替代此前每个 run 只构建一次的描述。adapter 与 middleware 的测试分别落在 test_authorization_provider.py 和 test_guardrail_middleware.py新字段默认值向后兼容、middleware 的非 MappingTypeError、adapter 同步/异步一致、7 字段完整映射、role 缺失应用default_role、未知非空 role 不回退、provider 异常穿过 adapter。7. TDD 实施顺序与文件边界整个链路按先失败测试、后实现的 10 个 Step 推进builder 测试 → builder 实现 → Gateway 防伪测试 → Gateway 实现 → task_tool 捕获测试 → 捕获实现 → executor 写回测试 → 写回实现 → guardrail/adapter 测试 → 扩展GuardrailRequest与 adapter最后追加实施记录。计划刻意把 22 个文件5 新增 17 修改放进单个 PR原因是它固定的是一条跨 Gateway、lead、subagent 和 guardrail 的端到端身份链继续拆分会产生可合并但身份链不完整的中间状态。明确不修改与不实现的范围同样重要它界定了 Phase 1A-1 的承诺authorization_config.py、config.example.yaml、lead agent 与 client 均不动RBAC provider 与 factoryPhase 1A-2、Layer 1 工具过滤与 deferred catalog 防提升Phase 1B、Layer 2 自动接线Phase 1B、route/model/skill/sandbox/MCP server 授权、RBAC 配置示例与config_version变更全部延期。8. 验证与验收门槛提交前按 TDD 步骤逐段运行目标测试再跑边界与 lint 检查cd backend uv run pytest tests/test_authorization_principal.py -q uv run pytest tests/test_gateway_services.py -q uv run pytest tests/test_task_tool_core_logic.py -q uv run pytest tests/test_subagent_executor.py -q uv run pytest tests/test_authorization_provider.py -q uv run pytest tests/test_guardrail_middleware.py -q uv run pytest tests/test_channel_user_id_env.py -q uv run pytest tests/test_harness_boundary.py -q uv run ruff check packages/harness/deerflow/authz packages/harness/deerflow/guardrails \ packages/harness/deerflow/tools/builtins/task_tool.py \ packages/harness/deerflow/subagents/executor.py app/gateway/services.py \ tests/test_authorization_principal.py make test make lint make format验收门槛本质上是一组破坏性测试——每一项都要求删除某段实现后对应测试必须失败以此证明测试真正锚定了安全契约删除is_internal服务端直接赋值后Gateway 防伪测试失败删除configurable清理后对应伪造测试失败普通请求不能通过body.context或body.config注入channel_user_idinternal 请求只接受顶层body.context的值删除任意一段 task/executor identity wiring 后subagent 测试失败builder、task、executor、middleware 对 attributes 非 Mapping 的行为一致userNone的 internal 与 non-internal 分支都被固定authorization.enabled: false时工具集合与执行决策不变没有 Layer 1、Layer 2、RBAC 或 client 额外改动混入。9. 小结DeerFlow Phase 1A-1 的核心贡献是一条有测试锚点的身份不变量链服务端认证状态是唯一权威来源Gateway 在 early return 之前清除并重新盖章服务端拥有字段is_internal与authz_attributes在 task_tool、executor、middleware 每一跳都显式复制且严格校验最终由唯一 builder 收敛为Principal供授权判定。这套单点规范化 无条件写回 每层失败测试的组合为后续 Phase 1A-2 的 RBAC provider 与 Phase 1B 的 Layer 1/Layer 2 接线奠定了可信任的身份基础——理解这条链路也就理解了 DeerFlow 细粒度授权体系中执行者是谁这个问题的完整答案。【免费下载链接】deer-flowAn open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of tasks that could take minutes to hours.项目地址: https://gitcode.com/GitHub_Trending/de/deer-flow创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

相关新闻

霞鹜文楷免费商用安装与配置完整指南:3 分钟选对字重装好字体

霞鹜文楷免费商用安装与配置完整指南:3 分钟选对字重装好字体

霞鹜文楷免费商用安装与配置完整指南:3 分钟选对字重装好字体 【免费下载链接】LxgwWenKai An open-source Chinese font derived from Fontworks Klee One. 一款开源中文字体,基于 FONTWORKS 出品字体 Klee One 衍生。 项目地址: https://gitcode.co…

2026/11/16 21:00:07 阅读更多 →
STM32F103与W5500硬件TCP/IP栈实现工业级UDP通信实战

STM32F103与W5500硬件TCP/IP栈实现工业级UDP通信实战

简介:本资源是一套面向物联网嵌入式开发者的STM32以太网实战代码工程,聚焦UDP通信场景,适用于STM32F103系列单片机初学者及项目开发者快速掌握W5500模块联网开发全流程。资源完整覆盖DHCP自动获取IP、UDP Socket创建、客户端连接监听与连接管…

2026/11/16 21:00:07 阅读更多 →
Mac 菜单栏如何整理清爽?免费开源菜单栏管理工具 Ice 实战指南

Mac 菜单栏如何整理清爽?免费开源菜单栏管理工具 Ice 实战指南

Mac 菜单栏如何整理清爽?免费开源菜单栏管理工具 Ice 实战指南 【免费下载链接】Ice Powerful menu bar manager for macOS 项目地址: https://gitcode.com/GitHub_Trending/ice/Ice 抬头一看,电池百分比被刘海挡住了一半?带刘海的 Ma…

2026/10/24 14:08:46 阅读更多 →

最新新闻

Electron桌面应用开发实战:从环境搭建到打包发布全流程

Electron桌面应用开发实战:从环境搭建到打包发布全流程

做前端这些年,我大部分时间都在跟浏览器标签页打交道,直到第一次把桌面应用跑起来,才发现原来自己一直被限制在地址栏和刷新按钮围起来的框框里。Electron这个词,最开始是在某段时间频繁出现在同事的讨论里,一个用HTML…

2026/11/16 8:22:12 阅读更多 →
滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

简介:亚太天能T109滑盖智能锁产品说明书是一份PDF格式的官方技术文档,主要面向智能锁安装人员、终端用户及售后维护者,帮助快速掌握产品安装、配置与常见故障处理。全包仅1个PDF文件,大小4.37MB,内容结构清晰&#xff…

2026/11/16 6:41:34 阅读更多 →
PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

上个月我在调试一台高速AGV的驱动系统,整车要求空载跑到8m/s,电机转速已经拉到额定点,驱动器的输出电压也顶到了母线电压极限附近。再往上踩速度指令,转速纹丝不动,三相电流反而开始震荡。那会儿我的第一反应就是&…

2026/11/16 8:22:12 阅读更多 →
C++核心知识点:从内存管理到STL的实战指南

C++核心知识点:从内存管理到STL的实战指南

C 这门语言我前前后后折腾了十几年,用它写过嵌入式驱动、做过游戏服务端,也搭过基础组件库。每次看到新人一头扎进"C 核心知识点"这个搜索词,我其实挺感慨的——这门语言的难点从来不是语法多,而是知识点之间的耦合太深…

2026/11/16 8:22:12 阅读更多 →
T109滑盖智能锁怎么装?安装调试与故障排查全攻略

T109滑盖智能锁怎么装?安装调试与故障排查全攻略

简介:亚太天能T109滑盖智能锁产品说明书以PDF格式发布,适合智能锁用户、安装人员与售后维修人员阅读。内容围绕T109系列指纹密码刷卡锁展开,先介绍前面板、后面板、锁体、机械钥匙、电池盒盖等部件名称与功能,再给出完整安装步骤&…

2026/11/16 7:30:18 阅读更多 →
LLM知识降熵:从信息垄断到理解权下放

LLM知识降熵:从信息垄断到理解权下放

你有没有过这种经历:翻开源码注释、论文摘要或者一份专业报告,每个字都认识,连在一起却像天书。想找人聊聊,身边要么没人懂,要么懂的懒得跟你解释。后来我试着把同一段内容丢给一个大语言模型,几秒钟之后&a…

2026/11/16 8:22:12 阅读更多 →

日新闻

周新闻

月新闻