deer-flow/docs/superpowers/specs/2026-06-19-guardrail-request-attribution-design.md

GuardrailRequest 运行时用户上下文与归因字段补充

概述

为 GuardrailRequest 补充可选的运行时用户上下文和工具调用归因字段，使可插拔 GuardrailProvider 能访问 DeerFlow 已认证用户、外部身份映射、run/thread/tool-call 定位信息。

本设计不新增治理系统、不定义统一 policy schema，也不改变默认 allow/deny 行为。它只把 DeerFlow 运行时已经掌握的上下文传给 provider。

背景

DeerFlow 已通过 GuardrailMiddleware + 可插拔 GuardrailProvider 实现工具调用前授权。当前 GuardrailDecision 已能表达 allow/deny、原因、policy_id 和 metadata；缺口在 GuardrailRequest 侧：provider 只能看到 tool_name 和 tool_input，无法可靠知道“谁发起了这次工具调用”以及“这次调用属于哪个 run/tool_call”。

源码中 DeerFlow 已有用户身份模型：

• users.id：DeerFlow 内部稳定用户 ID。
• users.system_role：admin / user。
• users.oauth_provider、users.oauth_id：未来 OAuth/SSO 外部身份映射字段，local user 下可为空。

这些字段当前已存在于认证后的 request.state.user，但 run-time middleware/tool 阶段只能通过 runtime.context 访问上下文。因此应在 Gateway 构建 run config 时注入 server-authenticated user context，再由 GuardrailMiddleware 消费。

改动范围

• app/gateway/services.py：inject_authenticated_user_context() 注入更多 authenticated user context。
• guardrails/provider.py：GuardrailRequest 新增 optional 字段。
• guardrails/middleware.py：从 ToolCallRequest.runtime.context 读取字段。
• tests/test_setup_agent_e2e_user_isolation.py：验证 Gateway 注入到 runtime context。
• tests/test_guardrail_middleware.py：验证 runtime context 进入 GuardrailRequest。
• backend/docs/GUARDRAILS.md：更新 custom provider 示例。

设计

GuardrailRequest 字段

@dataclass
class GuardrailRequest:
    tool_name: str
    tool_input: dict[str, Any]
    agent_id: str | None = None
    thread_id: str | None = None
    is_subagent: bool = False
    timestamp: str = ""

    user_id: str | None = None
    user_role: str | None = None
    oauth_provider: str | None = None
    oauth_id: str | None = None
    run_id: str | None = None
    tool_call_id: str | None = None

所有新增字段均为 optional，缺失时保持 None。GuardrailDecision 不变。

字段来源

字段	来源	说明
user_id	request.state.user.id → runtime.context["user_id"]	DeerFlow 内部稳定用户 ID
user_role	request.state.user.system_role → runtime.context["user_role"]	可用于简单 role-based policy
oauth_provider	request.state.user.oauth_provider → runtime.context["oauth_provider"]	OAuth/SSO 外部 provider，local user 可为空
oauth_id	request.state.user.oauth_id → runtime.context["oauth_id"]	外部 provider subject/user id，local user 可为空
run_id	_build_runtime_context() 写入 runtime.context["run_id"]	run 级审计归因
thread_id	_build_runtime_context() 写入 runtime.context["thread_id"]	修正已有字段未填充问题
tool_call_id	request.tool_call.get("id")	单次 tool call 定位

Gateway 注入只信任服务端认证态 request.state.user。客户端 body.context 里的 user_id/user_role/oauth_* 不应覆盖 authenticated user。

收益

稳定审计归因

user_id/run_id/thread_id/tool_call_id 让 provider 或外部审计系统能回答：

• 哪个 DeerFlow 用户触发了 tool call？
• 哪个 run 里发生了 deny？
• 同一轮中多次同名工具调用时，具体是哪一次？

可读的本地策略示例

user_id 是 UUID，不适合直接写人工 policy。user_role 可以支持简单示例：

field: role_tool_key
operator: eq
value: admin:bash

provider 可派生：

role_tool_key = f"{request.user_role or ''}:{request.tool_name}"

外部身份映射

oauth_provider/oauth_id 保留了未来接 OAuth/SSO/IAM 时的外部 subject 信息。当前 OAuth 路由仍是 placeholder，local user 下这些字段通常为 None，但字段 optional，不影响现有部署。

兼容性

• 所有新增字段 optional。
• 现有 provider 不读取新字段时行为不变。
• GuardrailDecision 不变。
• 未认证或无 runtime context 时字段为 None。
• local user 没有 OAuth 信息时 oauth_provider/oauth_id 为 None。
• agent_id 语义不变，仍保持现有 passport/agent hint 含义。

测试

新增或扩展以下测试：

测试	覆盖
TestConfigAssembly::test_authenticated_user_context_includes_role_and_oauth_identity	Gateway 将 user_id/user_role/oauth_provider/oauth_id 注入 runtime context
TestConfigAssembly::test_client_supplied_user_id_is_overridden	客户端伪造 identity context 不覆盖服务端认证态
TestGuardrailRequestAttribution::test_authenticated_user_context_present	runtime.context 中用户上下文进入 GuardrailRequest
TestGuardrailRequestAttribution::test_all_attribution_fields_present	用户上下文 + run/tool_call 归因字段同时传递
缺失 runtime/context 测试	字段保持 None，向后兼容

验证命令：

cd backend
PYTHONPATH=. uv run pytest \
  tests/test_guardrail_middleware.py::TestGuardrailRequestAttribution \
  tests/test_setup_agent_e2e_user_isolation.py::TestConfigAssembly -v

未涉及

• 不新增 central governance subsystem。
• 不新增 DeerFlow 内置 policy schema。
• 不修改 MCP 配置机制。
• 不修改 OAuth/SSO 实现状态。
• 不让 GuardrailMiddleware 直接依赖 FastAPI request、DB 或 auth repository。