fix: 会商席位与总控角色隔离,编排能力只归总控

This commit is contained in:
董宏凯 committed 2026-08-30 20:02:09 +08:00
1 parent ff80cc110d
commit 3384f2e51c
10 files changed
+488 -125

No files matched your search

@@ -40,7 +40,74 @@ logger = logging.getLogger(__name__)
WRITING_SETUP_MAX_ROUNDS = 8
REPORT_STRUCTURE_SETUP_MAX_ROUNDS = 8
_ES_QUERY_ROUTING_OPEN_TAG = '<skill_routing skill="es_query">'
_ES_QUERY_ROUTING_OPEN_TAG = '<skill_routing skill="es_query">'
_SKILLS_BLOCKED_BY_EXCLUDED_TOOL: dict[str, frozenset[str]] = {
# 内置 tool 与历史 custom skill 目录存在两种拼写;禁用编排工具时两者都必须从系统提示和
# runtime skill allowlist 中消失,防止误配的席位仍看到「加载编排技能」。
"agent_orchestration": frozenset({"agent_orchestration", "agent-orchestration"}),
}
_ROUNDTABLE_COORDINATOR_AGENT_ID = "roundtable-coordinator"
_NON_COORDINATOR_ORCHESTRATION_BOUNDARY = """
<orchestration_capability_boundary>
你不是多智能体圆桌总控,因此没有编排、派活或调度其它智能体的权限。
不得加载、读取、检索或调用 agent_orchestration / agent-orchestration,
不得声称准备使用编排技能;请直接完成当前问答或你的本职任务。
</orchestration_capability_boundary>
""".strip()
def _enforce_coordinator_only_tool_exclusions(
agent_id: str | None,
excluded_tools: list[str] | None,
) -> list[str] | None:
"""Make orchestration unavailable to every agent except the fixed roundtable coordinator."""
if agent_id == _ROUNDTABLE_COORDINATOR_AGENT_ID:
return excluded_tools
effective = list(excluded_tools or [])
if "agent_orchestration" not in effective:
effective.append("agent_orchestration")
return effective
def _append_orchestration_capability_boundary(system_prompt: str, agent_id: str | None) -> str:
"""Reinforce the physical tool/skill gate in every non-coordinator system prompt."""
if agent_id == _ROUNDTABLE_COORDINATOR_AGENT_ID:
return system_prompt
return f"{system_prompt}\n\n{_NON_COORDINATOR_ORCHESTRATION_BOUNDARY}"
def _filter_available_skills_for_excluded_tools(
available_skills: list[str] | None,
excluded_tools: list[str] | None,
) -> list[str] | None:
"""让工具级禁用同步收紧 skill allowlist,必要时把「全部」展开为安全列表。"""
if not excluded_tools:
return available_skills
excluded = {name.strip().lower() for name in excluded_tools if name}
blocked = {
skill_name
for tool_name, skill_names in _SKILLS_BLOCKED_BY_EXCLUDED_TOOL.items()
if tool_name in excluded
for skill_name in skill_names
}
if not blocked:
return available_skills
if available_skills is None:
# ``None`` 原本表示「全部启用技能可见」,无法表达「除了总控专属技能之外的全部」。
# 此时显式展开存储中的启用技能;扫描失败则 fail closed,避免角色隔离失效。
try:
from deerflow.skills.storage import get_or_new_skill_storage
available_skills = [
skill.name for skill in get_or_new_skill_storage().load_skills(enabled_only=True)
]
except Exception: # noqa: BLE001
logger.warning("Failed to expand skills while applying excluded-tool boundary", exc_info=True)
available_skills = []
return [name for name in available_skills if name.strip().lower() not in blocked]
def _log_es_query_routing_registration(
@@ -535,8 +602,11 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
if not is_writing_mode_report_path(writing_artifact_path):
writing_artifact_path = None
agent_id = validate_agent_id(cfg.get("agent_id") or cfg.get("agent_name"))
requested_excluded_tools = cfg.get("excluded_tools") or None
agent_id = validate_agent_id(cfg.get("agent_id") or cfg.get("agent_name"))
requested_excluded_tools = _enforce_coordinator_only_tool_exclusions(
agent_id,
cfg.get("excluded_tools") or None,
)
try:
agent_config = load_agent_config(agent_id) if not is_bootstrap and not is_writing_setup and not is_report_structure_setup else None
@@ -585,10 +655,14 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
from deerflow.agents.deep_research.retrieval import merge_collector_skill_allowlist, runtime_extra_skills
runtime_available_skills = merge_collector_skill_allowlist(
agent_id, runtime_available_skills, runtime_extra_skills(cfg)
)
prompt_available_skills = set(runtime_available_skills) if runtime_available_skills is not None else None
runtime_available_skills = merge_collector_skill_allowlist(
agent_id, runtime_available_skills, runtime_extra_skills(cfg)
)
runtime_available_skills = _filter_available_skills_for_excluded_tools(
runtime_available_skills,
requested_excluded_tools,
)
prompt_available_skills = set(runtime_available_skills) if runtime_available_skills is not None else None
config["metadata"].update(
{
@@ -669,13 +743,14 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
# Special bootstrap agent with minimal prompt for initial custom agent creation flow
return create_agent(
model=create_chat_model(name=model_name, thinking_enabled=thinking_enabled, force_disable_thinking=thinking_force_disabled, app_config=resolved_app_config),
tools=get_available_tools(
model_name=model_name,
subagent_enabled=subagent_enabled,
is_scheduled_run=cfg.get("is_scheduled_run", False),
excluded_tools=requested_excluded_tools,
app_config=resolved_app_config,
)
tools=get_available_tools(
model_name=model_name,
subagent_enabled=subagent_enabled,
is_scheduled_run=cfg.get("is_scheduled_run", False),
excluded_tools=requested_excluded_tools,
allow_agent_orchestration=agent_id == _ROUNDTABLE_COORDINATOR_AGENT_ID,
app_config=resolved_app_config,
)
+ [setup_agent],
middleware=_build_middlewares(config, model_name=model_name, app_config=resolved_app_config),
system_prompt=apply_prompt_template(
@@ -698,11 +773,12 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
default_tools = get_available_tools(
model_name=model_name,
groups=agent_config.tool_groups if agent_config else None,
subagent_enabled=subagent_enabled,
is_scheduled_run=cfg.get("is_scheduled_run", False),
excluded_tools=requested_excluded_tools,
app_config=resolved_app_config,
)
subagent_enabled=subagent_enabled,
is_scheduled_run=cfg.get("is_scheduled_run", False),
excluded_tools=requested_excluded_tools,
allow_agent_orchestration=agent_id == _ROUNDTABLE_COORDINATOR_AGENT_ID,
app_config=resolved_app_config,
)
if agent_id == FORCED_RESEARCH_AGENT_ID:
default_tools = filter_forced_research_tools(default_tools)
if is_notebook_mode:
@@ -744,8 +820,8 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
writing_mode=writing_mode,
writing_artifact_path=writing_artifact_path,
)
else:
system_prompt = apply_prompt_template(
else:
system_prompt = apply_prompt_template(
subagent_enabled=subagent_enabled,
max_concurrent_subagents=max_concurrent_subagents,
agent_id=agent_id,
@@ -758,10 +834,12 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
rag_mode_enabled=rag_mode_enabled,
is_notebook_mode=is_notebook_mode,
notebook_source_ids=notebook_source_ids,
is_scheduled_run=bool(cfg.get("is_scheduled_run", False)),
)
_log_es_query_routing_registration(
is_scheduled_run=bool(cfg.get("is_scheduled_run", False)),
)
system_prompt = _append_orchestration_capability_boundary(system_prompt, agent_id)
_log_es_query_routing_registration(
system_prompt=system_prompt,
app_config=resolved_app_config,
agent_id=agent_id,
@@ -1474,7 +1474,7 @@ def grep_tool(
@tool("read_file", parse_docstring=True)
def read_file_tool(
def read_file_tool(
runtime: ToolRuntime[ContextT, ThreadState],
description: str,
path: str,
@@ -1488,12 +1488,21 @@ def read_file_tool(
path: The **absolute** path to the file to read.
start_line: Optional starting line number (1-indexed, inclusive). Use with end_line to read a specific range.
end_line: Optional ending line number (1-indexed, inclusive). Use with start_line to read a specific range.
"""
try:
sandbox = ensure_sandbox_initialized(runtime)
ensure_thread_directories_exist(runtime)
requested_path = path
if is_local_sandbox(runtime):
"""
try:
requested_path = path
if _is_skills_path(requested_path):
from deerflow.tools.builtins.skill_tools import (
_resolve_active_agent_id,
is_coordinator_only_skill_path,
)
if is_coordinator_only_skill_path(requested_path) and _resolve_active_agent_id(runtime) != "roundtable-coordinator":
# Match skill_view's non-leaking behavior: ordinary agents must not discover whether it exists.
return f"Error: File not found: {requested_path}"
sandbox = ensure_sandbox_initialized(runtime)
ensure_thread_directories_exist(runtime)
if is_local_sandbox(runtime):
thread_data = get_thread_data(runtime)
validate_local_tool_path(path, thread_data, read_only=True)
if _is_skills_path(path):
@@ -9,6 +9,21 @@ from langchain.tools import ToolRuntime, tool
logger = logging.getLogger(__name__)
_ROUNDTABLE_COORDINATOR_AGENT_ID = "roundtable-coordinator"
COORDINATOR_ONLY_SKILL_NAMES = frozenset({"agent_orchestration", "agent-orchestration"})
def can_access_coordinator_only_skill(agent_id: str | None, skill_name: str) -> bool:
"""Return whether this runtime identity may discover/read a reserved orchestration skill."""
normalized = (skill_name or "").strip().lower()
return normalized not in COORDINATOR_ONLY_SKILL_NAMES or agent_id == _ROUNDTABLE_COORDINATOR_AGENT_ID
def is_coordinator_only_skill_path(path: str) -> bool:
"""Recognize reserved skill directories in virtual/container paths."""
parts = {part.strip().lower() for part in (path or "").replace("\\", "/").split("/") if part}
return bool(parts & COORDINATOR_ONLY_SKILL_NAMES)
def _resolve_active_agent_id(runtime: ToolRuntime | None) -> str | None:
"""Extract the agent_id under which the current tool call is running.
@@ -22,12 +37,13 @@ def _resolve_active_agent_id(runtime: ToolRuntime | None) -> str | None:
return None
try:
if getattr(runtime, "context", None):
ctx_id = runtime.context.get("agent_id")
ctx_id = runtime.context.get("agent_id") or runtime.context.get("agent_name")
if ctx_id:
return str(ctx_id)
cfg = getattr(runtime, "config", None)
if isinstance(cfg, dict):
cid = cfg.get("configurable", {}).get("agent_id")
configurable = cfg.get("configurable", {})
cid = configurable.get("agent_id") or configurable.get("agent_name")
if cid:
return str(cid)
except Exception:
@@ -61,7 +77,11 @@ def _load_agent_skill_whitelist(agent_id: str | None, extra_skills: list[str] |
cfg = load_agent_config(agent_id)
if cfg is None:
return None
allowed = set(cfg.skills or [])
allowed = {
name
for name in (cfg.skills or [])
if can_access_coordinator_only_skill(agent_id, name)
}
except Exception:
logger.debug("Failed to load agent config for skill_list filter", exc_info=True)
return None
@@ -137,6 +157,9 @@ def skill_view_impl(name: str, agent_id: str | None, extra_skills: list[str] | N
guessing skill names. Replies "not found" rather than "forbidden" to
avoid leaking which skills exist.
"""
if not can_access_coordinator_only_skill(agent_id, name):
return f"Skill '{name}' not found."
from deerflow.skills.storage import get_or_new_skill_storage
from deerflow.skills.usage import bump_view
@@ -151,6 +174,7 @@ def skill_view_impl(name: str, agent_id: str | None, extra_skills: list[str] | N
elif storage.public_skill_exists(name):
skill_file = storage.get_skills_root_path()
from pathlib import Path
from deerflow.skills.types import SKILL_MD_FILE
path = Path(skill_file) / "public" / name / SKILL_MD_FILE
@@ -241,6 +265,8 @@ def search_skills_impl(query: str, agent_id: str | None, top_n: int = 5, extra_s
base_path = _resolve_skills_container_base_path()
scored: list[tuple[int, dict]] = []
for skill in skills:
if not can_access_coordinator_only_skill(agent_id, skill.name):
continue
entry = usage.get(skill.name, {})
if allowed is not None:
if skill.name not in allowed:
@@ -331,6 +357,8 @@ def skill_list_impl(agent_id: str | None, extra_skills: list[str] | None = None)
usage = all_entries()
result = []
for skill in skills:
if not can_access_coordinator_only_skill(agent_id, skill.name):
continue
entry = usage.get(skill.name, {})
if allowed is not None:
# 自定义 agent:严格按 config.yaml 的 skills 白名单过滤。
@@ -16,11 +16,10 @@ BROWSER_ACT_TOOL_USE = "deerflow.tools.builtins.browser_act_tool:browser_act_too
BROWSER_CONTEXT_TOOL_USES = {BROWSER_CONTEXT_TOOL_USE, BROWSER_ACT_TOOL_USE}
BROWSER_CONTEXT_TOOL_NAMES = {"browser_fetch_page", "browser_act"}
BUILTIN_TOOLS = [
present_file_tool,
ask_clarification_tool,
agent_orchestration_tool,
]
BUILTIN_TOOLS = [
present_file_tool,
ask_clarification_tool,
]
SUBAGENT_TOOLS = [
task_tool,
@@ -39,24 +38,36 @@ def _is_host_bash_tool(tool: object) -> bool:
return False
def _is_browser_context_tool(tool: object) -> bool:
def _is_browser_context_tool(tool: object) -> bool:
"""Return True if the tool config represents the browser extension bridge."""
use = getattr(tool, "use", None)
name = getattr(tool, "name", None)
return use in BROWSER_CONTEXT_TOOL_USES or name in BROWSER_CONTEXT_TOOL_NAMES
return use in BROWSER_CONTEXT_TOOL_USES or name in BROWSER_CONTEXT_TOOL_NAMES
def _enforce_agent_orchestration_scope(
tools: list[BaseTool],
*,
allow_agent_orchestration: bool,
) -> list[BaseTool]:
"""Fail closed: only an explicitly authorized coordinator may receive orchestration."""
if allow_agent_orchestration:
return tools
return [tool for tool in tools if tool.name != "agent_orchestration"]
def get_available_tools(
def get_available_tools(
groups: list[str] | None = None,
include_mcp: bool = True,
model_name: str | None = None,
subagent_enabled: bool = False,
is_scheduled_run: bool = False,
excluded_tools: list[str] | None = None,
*,
app_config: AppConfig | None = None,
) -> list[BaseTool]:
excluded_tools: list[str] | None = None,
*,
allow_agent_orchestration: bool = False,
app_config: AppConfig | None = None,
) -> list[BaseTool]:
"""Get all available tools from config.
Note: MCP tools should be initialized at application startup using
@@ -67,9 +78,11 @@ def get_available_tools(
include_mcp: Whether to include tools from MCP servers (default: True).
model_name: Optional model name to determine if vision tools should be included.
subagent_enabled: Whether to include subagent tools (task, task_status).
excluded_tools: Optional list of tool names to exclude from the result
(applied AFTER all other resolution). Takes precedence over
``app_config.excluded_tools``.
excluded_tools: Optional list of tool names to exclude from the result
(applied AFTER all other resolution). Takes precedence over
``app_config.excluded_tools``.
allow_agent_orchestration: Explicit coordinator-only capability gate. Defaults to
``False`` so ordinary agents and all indirect callers fail closed.
Returns:
List of available tools.
@@ -114,8 +127,10 @@ def get_available_tools(
loaded_tools = [t for _, t in loaded_tools_raw]
# Conditionally add tools based on config
builtin_tools = BUILTIN_TOOLS.copy()
# Conditionally add tools based on config
builtin_tools = BUILTIN_TOOLS.copy()
if allow_agent_orchestration:
builtin_tools.append(agent_orchestration_tool)
if not is_scheduled_run:
builtin_tools.append(scheduled_task_tool)
@@ -292,4 +307,8 @@ def get_available_tools(
)
unique_tools = filtered_tools
return unique_tools
# Defense in depth: a config/MCP tool with the reserved name must not bypass the builtin gate.
return _enforce_agent_orchestration_scope(
unique_tools,
allow_agent_orchestration=allow_agent_orchestration,
)