初始化
This commit is contained in:
1 parent
34474bd5fc
commit
b638b541d0
3008 files changed
+837699
No files matched your search
@@ -0,0 +1,23 @@
|
||||
from .agent_orchestration_tool import agent_orchestration_tool
|
||||
from .clarification_tool import ask_clarification_tool
|
||||
from .memory_tool import memory_tool
|
||||
from .present_file_tool import present_file_tool
|
||||
from .scheduled_task_tool import scheduled_task_tool
|
||||
from .setup_agent_tool import setup_agent
|
||||
from .setup_report_structure_tool import setup_report_structure
|
||||
from .setup_writing_tool import setup_writing
|
||||
from .task_tool import task_tool
|
||||
from .view_image_tool import view_image_tool
|
||||
|
||||
__all__ = [
|
||||
"setup_agent",
|
||||
"setup_report_structure",
|
||||
"setup_writing",
|
||||
"present_file_tool",
|
||||
"ask_clarification_tool",
|
||||
"agent_orchestration_tool",
|
||||
"memory_tool",
|
||||
"scheduled_task_tool",
|
||||
"view_image_tool",
|
||||
"task_tool",
|
||||
]
|
||||
+46
@@ -0,0 +1,46 @@
|
||||
"""Placeholder tool that lets the roundtable leader agent dispatch sub-agents.
|
||||
|
||||
Background
|
||||
----------
|
||||
The multi-agent ``/api/multi-agent/run/stream`` endpoint (``app.gateway.routers.multi_agent``)
|
||||
drives a *leader* agent whose only job is to delegate work to seat-specific sub-agents.
|
||||
Its SOUL.md tells the model to "use the agent_orchestration skill, passing agent_name
|
||||
and task". With no real tool registered under that name, the model used to emit
|
||||
``{"name": "agent_orchestration", "args": {"agent_name": ..., "task": ...}}`` calls
|
||||
that the runtime rejected with "agent_orchestration is not a valid tool", driving it
|
||||
into an unproductive retry loop (a single leader call could exceed 10 000 SSE frames).
|
||||
|
||||
This module exposes a no-op tool with the exact signature the leader naturally
|
||||
emits. The actual dispatch is handled by ``SkillStopMiddleware`` which intercepts
|
||||
the call, halts the run, and lets ``multi_agent.py`` parse the AIMessage's
|
||||
``tool_calls`` to extract ``(agent_name, task)`` pairs for the frontend.
|
||||
"""
|
||||
|
||||
from langchain.tools import tool
|
||||
|
||||
|
||||
@tool("agent_orchestration", parse_docstring=True)
|
||||
def agent_orchestration_tool(agent_name: str, task: str) -> str:
|
||||
"""Delegate a task to a named sub-agent in the multi-agent roundtable.
|
||||
|
||||
Use this tool ONLY when you are the roundtable coordinator and need to
|
||||
dispatch work to one of the configured seat agents. Each call delegates
|
||||
ONE task to ONE agent. Emit multiple calls in the same turn to dispatch
|
||||
several seats in a single round of the discussion.
|
||||
|
||||
The call is intercepted by the runtime — you do not get a real result
|
||||
back synchronously. The orchestrator will collect every dispatched
|
||||
``(agent_name, task)`` pair, run the corresponding sub-agents, then
|
||||
re-prompt you with a synthesis instruction once they finish.
|
||||
|
||||
Args:
|
||||
agent_name: Name of the sub-agent to dispatch. MUST exactly match one of
|
||||
the names listed in your SOUL prompt's ``可调度智能体`` section.
|
||||
task: The instruction to hand to that sub-agent. Be specific — the
|
||||
sub-agent only sees this string (plus its own SOUL prompt), not the
|
||||
broader conversation context.
|
||||
"""
|
||||
# Real handling is in SkillStopMiddleware + the multi_agent router. This
|
||||
# body only runs as a fallback if the middleware is not configured; it
|
||||
# returns a placeholder so the model does not see a "not a valid tool" error.
|
||||
return f"dispatched:{agent_name}"
|
||||
+225
@@ -0,0 +1,225 @@
|
||||
"""Interactive browser action tool backed by the user's Chrome extension.
|
||||
|
||||
Unlike ``browser_fetch_page`` (a one-shot read), this tool drives an
|
||||
*observe -> act* loop on a live page the extension keeps open:
|
||||
|
||||
1. The model calls ``browser_act`` with an action (navigate/click/type/...).
|
||||
2. The extension performs the action on the session tab, then re-scans the page
|
||||
and returns an *observation*: the final URL/title, an indexed list of
|
||||
interactive elements, and the visible page text.
|
||||
3. The model reads the observation, picks the next element by its index, and
|
||||
calls ``browser_act`` again with the same ``session_id``.
|
||||
|
||||
The element ``index`` values are only valid for the most recent observation of a
|
||||
session; always act on indices from the latest result.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
from urllib.parse import urlparse
|
||||
from uuid import uuid4
|
||||
|
||||
from langchain.tools import tool
|
||||
|
||||
from deerflow.browser_context.tasks import create_browser_task, wait_for_browser_task_result
|
||||
from deerflow.config import get_app_config
|
||||
from deerflow.config.browser_context_config import BrowserContextConfig
|
||||
from deerflow.runtime.user_context import get_effective_user_id
|
||||
|
||||
_ACTIONS = {"navigate", "click", "type", "scroll", "wait", "extract", "observe", "close"}
|
||||
_NEEDS_INDEX = {"click", "type"}
|
||||
|
||||
|
||||
def _settings() -> BrowserContextConfig:
|
||||
value = getattr(get_app_config(), "browser_context", None)
|
||||
if isinstance(value, BrowserContextConfig):
|
||||
return value
|
||||
if isinstance(value, dict):
|
||||
return BrowserContextConfig.model_validate(value)
|
||||
return BrowserContextConfig()
|
||||
|
||||
|
||||
def _validate_url(raw_url: str) -> str | None:
|
||||
url = (raw_url or "").strip()
|
||||
parsed = urlparse(url)
|
||||
if parsed.scheme not in {"http", "https"} or not parsed.netloc:
|
||||
return None
|
||||
return url
|
||||
|
||||
|
||||
def _format_elements(elements: list[dict[str, Any]] | None) -> str:
|
||||
if not elements:
|
||||
return "(no interactive elements detected)"
|
||||
lines: list[str] = []
|
||||
for el in elements:
|
||||
idx = el.get("index")
|
||||
tag = str(el.get("tag") or "?")
|
||||
el_type = str(el.get("type") or "").strip()
|
||||
label = str(el.get("label") or "").strip().replace("\n", " ")
|
||||
if len(label) > 120:
|
||||
label = label[:120] + "…"
|
||||
descriptor = f"{tag}" + (f"[{el_type}]" if el_type else "")
|
||||
extra = ""
|
||||
if el.get("value"):
|
||||
value = str(el["value"]).strip().replace("\n", " ")
|
||||
extra = f' value="{value[:60]}"'
|
||||
lines.append(f"[{idx}] {descriptor} \"{label}\"{extra}".rstrip())
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def _format_observation(action: str, observation: dict[str, Any] | None, session_id: str, settings: BrowserContextConfig) -> str:
|
||||
observation = observation or {}
|
||||
status = str(observation.get("action_status") or "ok")
|
||||
message = str(observation.get("message") or "").strip()
|
||||
url = str(observation.get("url") or "").strip() or "(unknown)"
|
||||
title = str(observation.get("title") or "").strip() or "(untitled)"
|
||||
elements = observation.get("elements") if isinstance(observation.get("elements"), list) else []
|
||||
text = str(observation.get("text") or "").strip()
|
||||
text_limit = max(500, int(settings.observation_text_max_chars))
|
||||
text_truncated = len(text) > text_limit
|
||||
if text_truncated:
|
||||
text = text[:text_limit]
|
||||
|
||||
parts = [
|
||||
f"Browser session: {session_id}",
|
||||
f"Last action: {action} -> {status}",
|
||||
]
|
||||
if message:
|
||||
parts.append(f"Note: {message}")
|
||||
parts.extend(
|
||||
[
|
||||
f"URL: {url}",
|
||||
f"Title: {title}",
|
||||
"",
|
||||
"Interactive elements (use the [index] with click/type):",
|
||||
_format_elements(elements),
|
||||
"",
|
||||
"Page text:",
|
||||
text or "(empty page text)",
|
||||
]
|
||||
)
|
||||
if text_truncated:
|
||||
parts.append("\n[Page text truncated by browser_context.observation_text_max_chars]")
|
||||
parts.append(
|
||||
"\nNext step: call browser_act again with this session_id and the index of the element to act on. "
|
||||
"When the task is finished, call browser_act with action=\"close\" to release the tab."
|
||||
)
|
||||
return "\n".join(parts)
|
||||
|
||||
|
||||
@tool("browser_act", parse_docstring=True)
|
||||
async def browser_act_tool(
|
||||
action: str,
|
||||
session_id: str = "",
|
||||
url: str = "",
|
||||
index: int = -1,
|
||||
text: str = "",
|
||||
submit: bool = False,
|
||||
wait_for: str = "",
|
||||
wait_seconds: int = 0,
|
||||
) -> str:
|
||||
"""Drive an interactive observe/act loop on a page in the user's Chrome browser.
|
||||
|
||||
Use this to operate a real web page on the user's behalf — log in, fill forms,
|
||||
click through navigation, and read pages that need the user's session or local
|
||||
network. Start every task with ``action="navigate"`` and a URL to open a tab
|
||||
and get the first observation, then keep calling this tool with the same
|
||||
``session_id``, choosing elements by the ``index`` shown in the observation.
|
||||
Call ``action="close"`` when done to free the tab.
|
||||
|
||||
Args:
|
||||
action: One of navigate, click, type, scroll, wait, extract, observe, close.
|
||||
session_id: Session id from a previous observation. Leave empty to start a new session (requires navigate + url).
|
||||
url: Target http(s) URL. Required for navigate (and to start a new session).
|
||||
index: Index of the interactive element to act on, taken from the latest observation. Required for click and type.
|
||||
text: Text to enter for the type action.
|
||||
submit: For type, press Enter / submit the form after typing.
|
||||
wait_for: For wait, a CSS selector to wait for before observing.
|
||||
wait_seconds: Optional extra seconds to wait for this step's result. Zero uses the configured default.
|
||||
"""
|
||||
|
||||
settings = _settings()
|
||||
if not settings.enabled:
|
||||
return "browser_act is disabled by config.yaml: browser_context.enabled is false."
|
||||
if not settings.actions_enabled:
|
||||
return "browser_act is disabled by config.yaml: browser_context.actions_enabled is false."
|
||||
|
||||
action = (action or "").strip().lower()
|
||||
if action not in _ACTIONS:
|
||||
return f"browser_act: unknown action {action!r}. Use one of: {', '.join(sorted(_ACTIONS))}."
|
||||
|
||||
session_id = (session_id or "").strip()
|
||||
safe_url = _validate_url(url) if url else None
|
||||
|
||||
if action == "navigate" and safe_url is None:
|
||||
return "browser_act navigate requires an exact http(s) URL, for example https://example.com/page."
|
||||
|
||||
if not session_id:
|
||||
if action != "navigate":
|
||||
return "browser_act: no session_id yet. Start with action=\"navigate\" and a url to open the page first."
|
||||
session_id = uuid4().hex
|
||||
|
||||
if action in _NEEDS_INDEX and index < 0:
|
||||
return f"browser_act {action} requires a non-negative element index from the latest observation."
|
||||
if action == "type" and not text:
|
||||
return "browser_act type requires the text to enter."
|
||||
|
||||
action_payload: dict[str, Any] = {"type": action}
|
||||
if safe_url is not None:
|
||||
action_payload["url"] = safe_url
|
||||
if index >= 0:
|
||||
action_payload["index"] = int(index)
|
||||
if text:
|
||||
action_payload["text"] = text
|
||||
if submit:
|
||||
action_payload["submit"] = True
|
||||
if wait_for.strip():
|
||||
action_payload["wait_for"] = wait_for.strip()[:300]
|
||||
|
||||
configured_timeout = max(5, int(settings.action_result_timeout_seconds))
|
||||
requested_timeout = int(wait_seconds or configured_timeout)
|
||||
timeout = min(max(5, requested_timeout), configured_timeout)
|
||||
user_id = get_effective_user_id()
|
||||
|
||||
task = create_browser_task(
|
||||
user_id=user_id,
|
||||
url=safe_url or "",
|
||||
instruction="",
|
||||
kind="act",
|
||||
session_id=session_id,
|
||||
action=action_payload,
|
||||
timeout_seconds=timeout + int(settings.task_lease_seconds),
|
||||
max_content_chars=settings.max_content_chars,
|
||||
metadata={"source": "browser_act_tool"},
|
||||
)
|
||||
|
||||
completed = await wait_for_browser_task_result(
|
||||
task_id=task["id"],
|
||||
user_id=user_id,
|
||||
timeout_seconds=timeout,
|
||||
poll_interval_seconds=settings.task_poll_interval_seconds,
|
||||
)
|
||||
if completed is None:
|
||||
return f"Browser task {task['id']} was not found after it was created."
|
||||
|
||||
status = completed.get("status")
|
||||
if status == "error":
|
||||
return f"browser_act session {session_id}: step failed: {completed.get('error') or 'unknown error'}"
|
||||
if status == "expired":
|
||||
return (
|
||||
f"browser_act session {session_id}: the Chrome extension did not respond in time. "
|
||||
"Check that Deer Web Clipper is installed, the same user is logged in, and task polling is enabled."
|
||||
)
|
||||
if status != "done":
|
||||
return (
|
||||
f"browser_act session {session_id}: step is still {status or 'pending'} after {timeout} seconds. "
|
||||
"Keep the Deer Web Clipper extension running with task polling enabled, then try again."
|
||||
)
|
||||
|
||||
if action == "close":
|
||||
return f"browser_act session {session_id}: tab closed."
|
||||
|
||||
result = completed.get("result") or {}
|
||||
observation = result.get("observation") if isinstance(result.get("observation"), dict) else None
|
||||
return _format_observation(action, observation, session_id, settings)
|
||||
+117
@@ -0,0 +1,117 @@
|
||||
"""Browser extension backed page fetch tool."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from urllib.parse import urlparse
|
||||
|
||||
from langchain.tools import tool
|
||||
|
||||
from deerflow.browser_context.tasks import create_browser_task, wait_for_browser_task_result
|
||||
from deerflow.config import get_app_config
|
||||
from deerflow.config.browser_context_config import BrowserContextConfig
|
||||
from deerflow.runtime.user_context import get_effective_user_id
|
||||
|
||||
|
||||
def _settings() -> BrowserContextConfig:
|
||||
value = getattr(get_app_config(), "browser_context", None)
|
||||
if isinstance(value, BrowserContextConfig):
|
||||
return value
|
||||
if isinstance(value, dict):
|
||||
return BrowserContextConfig.model_validate(value)
|
||||
return BrowserContextConfig()
|
||||
|
||||
|
||||
def _validate_url(raw_url: str) -> str | None:
|
||||
url = (raw_url or "").strip()
|
||||
parsed = urlparse(url)
|
||||
if parsed.scheme not in {"http", "https"} or not parsed.netloc:
|
||||
return None
|
||||
return url
|
||||
|
||||
|
||||
@tool("browser_fetch_page", parse_docstring=True)
|
||||
async def browser_fetch_page_tool(url: str, question: str = "", wait_seconds: int = 0) -> str:
|
||||
"""Ask the user's paired Chrome extension to fetch a page and return visible page text.
|
||||
|
||||
Use this when the user explicitly asks to use the browser extension or asks
|
||||
for data from a page that may require their browser session, login state, or
|
||||
local network access. The URL must be an exact http(s) URL provided by the
|
||||
user. If the user did not provide a URL, ask for the URL instead of guessing.
|
||||
|
||||
Args:
|
||||
url: Exact http(s) URL to open in the user's Chrome browser.
|
||||
question: Optional instruction describing what data the user wants from the page.
|
||||
wait_seconds: Optional seconds to wait for the extension result. Zero uses the configured default.
|
||||
"""
|
||||
|
||||
settings = _settings()
|
||||
if not settings.enabled:
|
||||
return "browser_fetch_page is disabled by config.yaml: browser_context.enabled is false."
|
||||
|
||||
safe_url = _validate_url(url)
|
||||
if safe_url is None:
|
||||
return "browser_fetch_page requires an exact http(s) URL, for example https://example.com/page."
|
||||
|
||||
configured_timeout = max(5, int(settings.task_result_timeout_seconds))
|
||||
requested_timeout = int(wait_seconds or configured_timeout)
|
||||
timeout = min(max(5, requested_timeout), configured_timeout)
|
||||
user_id = get_effective_user_id()
|
||||
|
||||
task = create_browser_task(
|
||||
user_id=user_id,
|
||||
url=safe_url,
|
||||
instruction=(question or "").strip(),
|
||||
timeout_seconds=timeout + int(settings.task_lease_seconds),
|
||||
max_content_chars=settings.max_content_chars,
|
||||
metadata={"source": "browser_fetch_page_tool"},
|
||||
)
|
||||
|
||||
completed = await wait_for_browser_task_result(
|
||||
task_id=task["id"],
|
||||
user_id=user_id,
|
||||
timeout_seconds=timeout,
|
||||
poll_interval_seconds=settings.task_poll_interval_seconds,
|
||||
)
|
||||
if completed is None:
|
||||
return f"Browser task {task['id']} was not found after it was created."
|
||||
|
||||
status = completed.get("status")
|
||||
if status == "error":
|
||||
return f"Browser task {task['id']} failed: {completed.get('error') or 'unknown error'}"
|
||||
if status == "expired":
|
||||
return (
|
||||
f"Browser task {task['id']} expired before the Chrome extension returned a result. "
|
||||
"Check that Deer Web Clipper is installed, configured with the same access token, and task polling is enabled."
|
||||
)
|
||||
if status != "done":
|
||||
return (
|
||||
f"Browser task {task['id']} is still {status or 'pending'} after {timeout} seconds. "
|
||||
"Keep the Deer Web Clipper extension running with task polling enabled, then try again."
|
||||
)
|
||||
|
||||
result = completed.get("result") or {}
|
||||
content = str(result.get("content") or "").strip()
|
||||
tool_limit = max(1_000, int(settings.tool_result_max_chars))
|
||||
tool_truncated = len(content) > tool_limit
|
||||
if tool_truncated:
|
||||
content = content[:tool_limit]
|
||||
|
||||
notes: list[str] = []
|
||||
if result.get("truncated"):
|
||||
notes.append("The browser capture was truncated by browser_context.max_content_chars.")
|
||||
if tool_truncated:
|
||||
notes.append("The tool response was truncated by browser_context.tool_result_max_chars.")
|
||||
|
||||
parts = [
|
||||
"Browser page fetched through the user's Chrome extension.",
|
||||
f"Task ID: {task['id']}",
|
||||
f"Title: {result.get('title') or '(untitled)'}",
|
||||
f"URL: {result.get('url') or safe_url}",
|
||||
]
|
||||
if question:
|
||||
parts.extend(["", "Requested extraction:", question.strip()])
|
||||
if notes:
|
||||
parts.extend(["", "Notes:", "\n".join(f"- {note}" for note in notes)])
|
||||
parts.extend(["", "Page content:", content or "(empty page text)"])
|
||||
return "\n".join(parts)
|
||||
|
||||
+78
@@ -0,0 +1,78 @@
|
||||
from typing import Literal
|
||||
|
||||
from langchain.tools import tool
|
||||
|
||||
|
||||
# ClarificationMiddleware owns the stop behaviour: it returns a Command that
|
||||
# writes the ToolMessage and explicitly routes to END. ``return_direct=True``
|
||||
# makes the prebuilt tool node short-circuit before that Command update is
|
||||
# checkpointed in some LangGraph versions, leaving an assistant tool call
|
||||
# without its matching ToolMessage. The next user reply then fails provider
|
||||
# validation with "tool_calls must be followed by tool messages".
|
||||
@tool("ask_clarification", parse_docstring=True, return_direct=False)
|
||||
def ask_clarification_tool(
|
||||
question: str,
|
||||
clarification_type: Literal[
|
||||
"missing_info",
|
||||
"ambiguous_requirement",
|
||||
"approach_choice",
|
||||
"risk_confirmation",
|
||||
"suggestion",
|
||||
],
|
||||
context: str | None = None,
|
||||
options: list[str] | None = None,
|
||||
allow_multiple: bool | None = None,
|
||||
) -> str:
|
||||
"""Ask the user for clarification when you need more information to proceed.
|
||||
|
||||
Use this tool when you encounter situations where you cannot proceed without user input:
|
||||
|
||||
- **Missing information**: Required details not provided (e.g., file paths, URLs, specific requirements)
|
||||
- **Ambiguous requirements**: Multiple valid interpretations exist
|
||||
- **Approach choices**: Several valid approaches exist and you need user preference
|
||||
- **Risky operations**: Destructive actions that need explicit confirmation (e.g., deleting files, modifying production)
|
||||
- **Suggestions**: You have a recommendation but want user approval before proceeding
|
||||
|
||||
The execution will be interrupted and the question will be presented to the user.
|
||||
Wait for the user's response before continuing.
|
||||
|
||||
When to use ask_clarification:
|
||||
- You need information that wasn't provided in the user's request
|
||||
- The requirement can be interpreted in multiple ways
|
||||
- Multiple valid implementation approaches exist
|
||||
- You're about to perform a potentially dangerous operation
|
||||
- You have a recommendation but need user approval
|
||||
|
||||
Batching multiple independent questions:
|
||||
- **You CAN and SHOULD call ask_clarification multiple times in the same turn** when the user's
|
||||
request leaves several **independent** aspects unclear (e.g. project type AND tech stack AND
|
||||
deployment target). Emit one tool call per aspect — do NOT cram several unrelated questions
|
||||
into one `question` string.
|
||||
- The frontend automatically groups all clarification cards in one turn into a single submission,
|
||||
so the user answers them together in one reply. You will then receive one combined user message
|
||||
addressing every question in order.
|
||||
- When the questions DEPEND on each other (the second only makes sense after the first is answered),
|
||||
ask only the first one and wait for the reply before asking the next.
|
||||
|
||||
Best practices:
|
||||
- One question per ask_clarification call — keep each `question` focused on a single decision.
|
||||
- Be specific and clear in your question.
|
||||
- Provide `options` (with concise labels) whenever there is a discrete set of reasonable choices.
|
||||
- By default the UI is **single-select** (click an option to send). Pass `allow_multiple=True`
|
||||
only when the user may legitimately pick several options together (e.g. multiple constraints).
|
||||
- Don't make assumptions when clarification is needed.
|
||||
- For risky operations, ALWAYS ask for confirmation.
|
||||
- After calling this tool (or several in one turn), execution will be interrupted automatically.
|
||||
|
||||
Args:
|
||||
question: The clarification question to ask the user. Focused on a single decision; be specific and clear.
|
||||
clarification_type: The type of clarification needed (missing_info, ambiguous_requirement, approach_choice, risk_confirmation, suggestion).
|
||||
context: Optional context explaining why clarification is needed. Helps the user understand the situation.
|
||||
options: Optional list of choices. Present clear options for the user to choose from.
|
||||
allow_multiple: When True, the UI allows multi-select plus a submit button. When False or
|
||||
omitted, the UI is single-select and sends immediately on click (default).
|
||||
"""
|
||||
# This is a placeholder implementation
|
||||
# The actual logic is handled by ClarificationMiddleware which intercepts this tool call
|
||||
# and interrupts execution to present the question to the user
|
||||
return "Clarification request processed by middleware"
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
"""ask_clarification 工具参数的共享解析(Harness + Gateway)。
|
||||
|
||||
圆桌 Step 1(``intent.py``)与 Step 2 总控(``multi_agent.py``)在 SSE 终态帧里
|
||||
都会带上 ``allow_multiple``,供前端 ``resolveAllowMultiple`` 决定选项卡片是
|
||||
「点击即发送(单选)」还是「多选 + 发送按钮」。
|
||||
|
||||
约定(与前端 ``roundtable-planning/lib/clarification.ts`` 一致):
|
||||
- 模型**未传** ``allow_multiple`` 或传 ``null`` → **False**(单选);
|
||||
- 仅当模型显式传 ``true`` 时才多选;
|
||||
- 不再根据 ``clarification_type`` 推断多选(旧逻辑已移除)。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
|
||||
def coerce_bool(value: object | None, *, default: bool) -> bool:
|
||||
"""把 LLM tool args 里可能出现的 bool/数字/字符串统一成 bool。"""
|
||||
if value is None:
|
||||
return default
|
||||
if isinstance(value, bool):
|
||||
return value
|
||||
if isinstance(value, (int, float)):
|
||||
return bool(value)
|
||||
if isinstance(value, str):
|
||||
lowered = value.strip().lower()
|
||||
if lowered in ("true", "1", "yes", "y", "on"):
|
||||
return True
|
||||
if lowered in ("false", "0", "no", "n", "off"):
|
||||
return False
|
||||
return bool(value)
|
||||
|
||||
|
||||
def resolve_allow_multiple(args: dict) -> bool:
|
||||
"""是否允许多选。仅 ``args["allow_multiple"]`` 显式为真时返回 True。"""
|
||||
if "allow_multiple" in args and args["allow_multiple"] is not None:
|
||||
return coerce_bool(args["allow_multiple"], default=False)
|
||||
return False
|
||||
+573
@@ -0,0 +1,573 @@
|
||||
"""写作模式的内联深度研究报告工具。
|
||||
|
||||
聊天输入框「写作模式」首轮(尚无 report.md 产物)在**交付时刻**(模型认为
|
||||
对话已经聊得差不多、该出报告了)调用本工具:优先把**对话中已经产生的**
|
||||
工具结果收割成研究资料池,内联运行 DeepResearchEngine(basic runner),按
|
||||
「通用分析结构」大纲撰写 ``report.md``,直接写进**当前聊天线程**的沙箱
|
||||
``outputs/`` 目录——前端画布 / 编辑 / 下载 / 续写全部沿用既有 artifacts 通道。
|
||||
除「写 md」这一动作换成管线外,agent 的对话 / 检索 / 澄清行为一切照旧。
|
||||
|
||||
资料来源(收割池先按**当前主题**做词面相关度强过滤——旧课题的检索
|
||||
结果不进报告):
|
||||
|
||||
- 一律用对话里已经产生的资料写(哪怕为空——basic runner 有领域知识兜底),
|
||||
**不再**因条数不足打断用户,也**不再**在管线内部补检索。
|
||||
需要检索时由 lead agent 用对话工具先搜,再调用本工具写文件。
|
||||
|
||||
报告管线继承聊天里选择的模型与思考开关(``context.model_name`` /
|
||||
``thinking_enabled`` / ``thinking_force_disabled``,经 run config 白名单透
|
||||
传),与「除写 md 外其他行为保持原样」一致;缺省回落系统默认模型。
|
||||
|
||||
与 job 执行器(``app/gateway/deep_research_job_executor.py``)的差异:
|
||||
|
||||
- 不建会话 / 任务 / 事件库行——生命周期就是本次聊天 run;
|
||||
- 产物写入器定向到聊天线程(执行器定向到会话的隐藏 ``dr_`` 线程);
|
||||
- 事件不落库,经 LangGraph 的 ``get_stream_writer()`` custom 通道直达前端
|
||||
``onCustomEvent``(与子智能体 ``task_running`` 事件同一通道),帧统一带
|
||||
``{"type": "deep_research_report", ...}`` 前缀。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import re
|
||||
from typing import Annotated, Any
|
||||
|
||||
from langchain.tools import InjectedToolCallId, ToolRuntime, tool
|
||||
from langchain_core.messages import HumanMessage, ToolMessage
|
||||
from langgraph.types import Command
|
||||
from langgraph.typing import ContextT
|
||||
|
||||
from deerflow.agents.deep_research.adapters.artifacts import ThreadOutputsArtifactWriter
|
||||
from deerflow.agents.deep_research.adapters.context import DeerFlowContextCompressor
|
||||
from deerflow.agents.deep_research.adapters.image import build_image_provider
|
||||
from deerflow.agents.deep_research.adapters.llm import DeerFlowCompletionBackend
|
||||
from deerflow.agents.deep_research.collection.thread_harvester import (
|
||||
StaticHarvestMaterialProvider,
|
||||
harvest_messages_materials,
|
||||
)
|
||||
from deerflow.agents.deep_research.config import DeepResearchConfig
|
||||
from deerflow.agents.deep_research.engine import DeepResearchEngine
|
||||
from deerflow.agents.deep_research.events import DeepResearchEvent, EventType, ResearchPhase
|
||||
from deerflow.agents.deep_research.types import AdapterBundle, DeepResearchRequest, ResearchMaterial
|
||||
from deerflow.agents.thread_state import ThreadState
|
||||
from deerflow.persistence.report_structures.defaults import GENERAL_OUTLINE
|
||||
from deerflow.runtime.thread_paths import resolve_path_user_id
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# 收割池低于该条数视为「资料偏少」,仅记日志,不再打断用户。
|
||||
_MIN_HARVESTED_MATERIALS = 3
|
||||
|
||||
# 引擎事件中值得转发到聊天的子集(model_usage / heartbeat / job_* 只对持久
|
||||
# 任务管道有意义,聊天内是噪音)。
|
||||
_FORWARDABLE_EVENTS: frozenset[str] = frozenset(
|
||||
{
|
||||
"phase_changed",
|
||||
"plan_created",
|
||||
"queries_planned",
|
||||
"query_started",
|
||||
"query_completed",
|
||||
"source_added",
|
||||
"sources_curated",
|
||||
"context_compressed",
|
||||
"report_reset",
|
||||
"report_chunk",
|
||||
"report_completed",
|
||||
"summary_completed",
|
||||
"artifact_created",
|
||||
"warning",
|
||||
"error",
|
||||
}
|
||||
)
|
||||
|
||||
# live-only 帧类型(不落库的 token 级增量,ReportChunkEmitter.publish_live)。
|
||||
_FORWARDABLE_LIVE_EVENTS: frozenset[str] = frozenset({"report_delta", "report_thinking"})
|
||||
|
||||
REPORT_VIRTUAL_PATH = "/mnt/user-data/outputs/report.md"
|
||||
|
||||
|
||||
def is_writing_mode_report_path(path: str | None) -> bool:
|
||||
"""Only ``report.md`` counts as the writing-mode deliverable for follow-up edits.
|
||||
|
||||
Leftover notes / skill Markdown must not skip the first-report pipeline.
|
||||
"""
|
||||
if not path or not isinstance(path, str):
|
||||
return False
|
||||
normalized = path.replace("\\", "/").split("?", 1)[0].split("#", 1)[0].rstrip("/")
|
||||
return normalized.lower().endswith("/report.md") or normalized.lower() == "report.md"
|
||||
|
||||
|
||||
class StreamWriterEventSink:
|
||||
"""把引擎事件经 LangGraph custom 通道转发到聊天前端。
|
||||
|
||||
满足 :class:`~deerflow.agents.deep_research.events.EventSink` 协议(结构
|
||||
类型)。不持久化——``seq`` 恒为 0,聊天内没有 ``?after`` 重放需求;转发
|
||||
失败只记日志,绝不影响研究执行。
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
writer: Any,
|
||||
*,
|
||||
session_id: str,
|
||||
job_id: str,
|
||||
) -> None:
|
||||
self._writer = writer
|
||||
self._session_id = session_id
|
||||
self._job_id = job_id
|
||||
|
||||
async def emit(
|
||||
self,
|
||||
type: EventType, # noqa: A002 — 与协议参数名保持一致
|
||||
*,
|
||||
phase: ResearchPhase = "initializing",
|
||||
payload: dict[str, Any] | None = None,
|
||||
) -> DeepResearchEvent:
|
||||
event = DeepResearchEvent(
|
||||
seq=0,
|
||||
session_id=self._session_id,
|
||||
job_id=self._job_id,
|
||||
type=type,
|
||||
phase=phase,
|
||||
payload=payload or {},
|
||||
)
|
||||
if type in _FORWARDABLE_EVENTS:
|
||||
self._forward(event.to_sse_dict())
|
||||
return event
|
||||
|
||||
async def publish_live(
|
||||
self,
|
||||
type: str, # noqa: A002
|
||||
*,
|
||||
phase: ResearchPhase = "initializing",
|
||||
payload: dict[str, Any] | None = None,
|
||||
) -> None:
|
||||
if type not in _FORWARDABLE_LIVE_EVENTS:
|
||||
return
|
||||
self._forward(
|
||||
{
|
||||
"seq": 0,
|
||||
"sessionId": self._session_id,
|
||||
"jobId": self._job_id,
|
||||
"type": type,
|
||||
"phase": phase,
|
||||
"payload": payload or {},
|
||||
"live": True,
|
||||
}
|
||||
)
|
||||
|
||||
def _forward(self, frame: dict[str, Any]) -> None:
|
||||
if self._writer is None:
|
||||
return
|
||||
try:
|
||||
self._writer({"type": "deep_research_report", "event": frame})
|
||||
except Exception: # noqa: BLE001 - 进度转发绝不影响研究本体
|
||||
logger.debug("deep_research_report: custom stream frame dropped", exc_info=True)
|
||||
|
||||
|
||||
# 写作模式常在「不用搜索 / 对话资料很少」时开写。工作台默认的「材料不足就
|
||||
# 写明资料不足」会把报告写成元分析;这里强制用领域知识补全正文。
|
||||
_KNOWLEDGE_WRITE_INSTRUCTION = (
|
||||
"对话材料很少或用户要求直接开写时:必须基于模型自身的领域知识写成完整、有实质内容的研究报告"
|
||||
"(含架构说明;用户要求流程图时用 Mermaid)。禁止把「材料不足/未提供文献/现有材料高度浓缩」"
|
||||
"写成报告主线或用其填充多个章节。参考文献可标为基于公开领域知识,不要用「材料未提供」占整节。"
|
||||
)
|
||||
|
||||
|
||||
def build_writing_research_config(
|
||||
*,
|
||||
focus: str | None = None,
|
||||
thinking_enabled: bool = False,
|
||||
model_name: str | None = None,
|
||||
) -> DeepResearchConfig:
|
||||
"""组装聊天写作模式的研究配置:basic + 通用分析结构 + adaptive。
|
||||
|
||||
与深度研究工作台确认卡的默认值一致(``ReportConfigCard.DEFAULT_ADVANCED_OPTIONS``)。
|
||||
``model_name`` / ``thinking_enabled`` 继承自聊天 run 的模型选择——同一模型
|
||||
覆盖 fast/smart/strategic 三个角色,使报告管线与对话用同一个模型和思考
|
||||
开关(缺省回落系统默认模型)。
|
||||
"""
|
||||
parts: list[str] = []
|
||||
if focus and focus.strip():
|
||||
parts.append(focus.strip())
|
||||
parts.append(_KNOWLEDGE_WRITE_INSTRUCTION)
|
||||
return DeepResearchConfig(
|
||||
mode="basic",
|
||||
collection_mode="legacy",
|
||||
custom_outline=GENERAL_OUTLINE,
|
||||
structure_mode="adaptive",
|
||||
generate_images=False,
|
||||
thinking_enabled=thinking_enabled,
|
||||
fast_model=model_name,
|
||||
smart_model=model_name,
|
||||
strategic_model=model_name,
|
||||
report_instruction="\n".join(parts),
|
||||
).clamp()
|
||||
|
||||
|
||||
def _resolve_chat_model(context: dict[str, Any] | None) -> tuple[str | None, bool, bool]:
|
||||
"""从 run 上下文解析聊天选择的模型与思考开关(P2:管线继承聊天模型)。
|
||||
|
||||
Returns ``(model_name, thinking_enabled, force_disable_thinking)``。模型名
|
||||
对不上 config.yaml 时回落 ``None``(系统默认);模型不支持思考时关思考,
|
||||
语义与 lead agent 的解析一致(``_make_lead_agent``)。
|
||||
"""
|
||||
cfg = context or {}
|
||||
name = cfg.get("model_name") or cfg.get("model") or None
|
||||
thinking = bool(cfg.get("thinking_enabled", True))
|
||||
force_disable = bool(cfg.get("thinking_force_disabled", False))
|
||||
name = str(name).strip() if isinstance(name, str) else None
|
||||
if not name:
|
||||
return None, thinking, force_disable
|
||||
try:
|
||||
from deerflow.config.app_config import get_app_config
|
||||
|
||||
model_config = get_app_config().get_model_config(name)
|
||||
except Exception: # noqa: BLE001 - 配置不可用时交由 create_chat_model 自行兜底
|
||||
logger.warning("[deep_research_report] app config unavailable; passing model through: %s", name)
|
||||
return name, thinking, force_disable
|
||||
if model_config is None:
|
||||
logger.warning("[deep_research_report] chat model '%s' not in app config; using system default", name)
|
||||
return None, thinking, force_disable
|
||||
if thinking and not model_config.supports_thinking:
|
||||
thinking = False
|
||||
return name, thinking, force_disable
|
||||
|
||||
|
||||
# ── 当前主题相关度强过滤(P1:旧课题资料不得凑门槛、不得入报告) ────────────
|
||||
|
||||
# 主题切词:ASCII 词(≥2 字符)+ CJK 连续段的全部 bigram;≥4 字的整段额外
|
||||
# 作为强词(命中标题即认定相关)。
|
||||
_ASCII_WORD_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]+")
|
||||
_CJK_RUN_RE = re.compile(r"[\u4e00-\u9fff]+")
|
||||
_STRONG_TERM_MIN_CHARS = 4
|
||||
# 词面命中判定:标题 ≥2 个不同词,或正文 ≥4 个不同词,或 标题≥1 且正文≥2,
|
||||
# 或强词(整段主题短语)出现在标题。
|
||||
_TITLE_MIN_HITS = 2
|
||||
_CONTENT_MIN_HITS = 4
|
||||
# 正文只扫前若干字符——相关度信号在开头最密,长文省 CPU。
|
||||
_CONTENT_SCAN_CHARS = 4000
|
||||
|
||||
|
||||
def _topic_terms(topic: str) -> tuple[frozenset[str], frozenset[str]]:
|
||||
"""切出 ``(强词, 弱词)``:强词=主题整段短语,弱词=bigram + ASCII 词。"""
|
||||
weak: set[str] = set()
|
||||
strong: set[str] = set()
|
||||
for word in _ASCII_WORD_RE.findall(topic):
|
||||
weak.add(word.lower())
|
||||
for run in _CJK_RUN_RE.findall(topic):
|
||||
if len(run) >= _STRONG_TERM_MIN_CHARS:
|
||||
strong.add(run)
|
||||
for i in range(len(run) - 1):
|
||||
weak.add(run[i : i + 2])
|
||||
return frozenset(strong), frozenset(weak)
|
||||
|
||||
|
||||
def _is_topic_relevant(material: ResearchMaterial, strong: frozenset[str], weak: frozenset[str]) -> bool:
|
||||
title = (material.title or "").lower()
|
||||
content = (material.raw_content or "")[:_CONTENT_SCAN_CHARS].lower()
|
||||
title_hits = sum(1 for term in weak if term in title)
|
||||
content_hits = sum(1 for term in weak if term in content)
|
||||
if any(term in title for term in strong):
|
||||
return True
|
||||
if title_hits >= _TITLE_MIN_HITS:
|
||||
return True
|
||||
if content_hits >= _CONTENT_MIN_HITS:
|
||||
return True
|
||||
if title_hits >= 1 and content_hits >= 2:
|
||||
return True
|
||||
# 短主题兜底:切出的词 ≤2 个时(如「课题」「AI」),命中任意一词即相关。
|
||||
return len(weak) <= 2 and (title_hits + content_hits) >= 1
|
||||
|
||||
|
||||
def _filter_relevant_materials(
|
||||
materials: list[ResearchMaterial],
|
||||
*,
|
||||
topic: str,
|
||||
anchor_index: int | None = None,
|
||||
) -> tuple[list[ResearchMaterial], int]:
|
||||
"""按当前主题过滤收割池;返回 ``(相关池, 被剔除条数)``。
|
||||
|
||||
两条保留通道(满足其一即入池):
|
||||
|
||||
1. **位置**:材料来自课题请求消息(``anchor_index``)之后的工具消息——
|
||||
那是模型为本课题检索的,与词面/语言无关,一律保留。线上实测中文课题
|
||||
+ 英文检索结果会被纯词面匹配整批误杀(35 条只留 4 条)。
|
||||
2. **词面**:材料词面命中课题(强词/标题/正文规则)——兜住课题切换前
|
||||
的旧检索里仍与当前课题相关的部分。
|
||||
|
||||
``anchor_index`` 之前的旧课题检索(词面不命中)继续被剔除(P1:旧课题
|
||||
资料不得凑门槛、不得入报告)。``anchor_index=None`` 或负数(对话里找不
|
||||
到课题请求消息,如纯工具消息的旧调用方)退化为纯词面过滤。
|
||||
"""
|
||||
strong, weak = _topic_terms(topic)
|
||||
if not strong and not weak:
|
||||
return list(materials), 0
|
||||
positional = anchor_index is not None and anchor_index >= 0
|
||||
relevant: list[ResearchMaterial] = []
|
||||
for material in materials:
|
||||
message_index = material.metadata.get("message_index")
|
||||
if positional and isinstance(message_index, int) and message_index > anchor_index:
|
||||
relevant.append(material)
|
||||
continue
|
||||
if _is_topic_relevant(material, strong, weak):
|
||||
relevant.append(material)
|
||||
return relevant, len(materials) - len(relevant)
|
||||
|
||||
|
||||
def _anchor_visible_human(message: Any) -> bool:
|
||||
if not isinstance(message, HumanMessage):
|
||||
return False
|
||||
kwargs = getattr(message, "additional_kwargs", None) or {}
|
||||
return not kwargs.get("hide_from_ui")
|
||||
|
||||
|
||||
def _anchor_is_clarification_result(message: Any) -> bool:
|
||||
return isinstance(message, ToolMessage) and str(getattr(message, "name", "") or "") == "ask_clarification"
|
||||
|
||||
|
||||
def _anchor_message_text(message: Any) -> str:
|
||||
content = getattr(message, "content", "")
|
||||
if isinstance(content, list):
|
||||
parts: list[str] = []
|
||||
for part in content:
|
||||
if isinstance(part, str):
|
||||
parts.append(part)
|
||||
elif isinstance(part, dict) and isinstance(part.get("text"), str):
|
||||
parts.append(part["text"])
|
||||
return " ".join(parts).strip()
|
||||
return str(content or "").strip()
|
||||
|
||||
|
||||
def topic_anchor_index(messages: list[Any], *, topic: str = "") -> int:
|
||||
"""课题请求消息在对话中的位置(写作模式首报轮的资料过滤锚点)。
|
||||
|
||||
规则与 ``writing_mode_report_middleware.extract_report_topic`` 一致:取
|
||||
最新的可见人类消息、跳过对 ``ask_clarification`` 的直接回答(紧跟澄清
|
||||
ToolMessage 的人类消息不是新课题)。传入 ``topic`` 时优先返回与其文本
|
||||
前缀一致的消息位置(模型原样复述课题的常见情形)。找不到返回 -1。
|
||||
"""
|
||||
normalized_topic = " ".join(str(topic or "").split())
|
||||
prefix = normalized_topic[:80]
|
||||
fallback = -1
|
||||
for index in range(len(messages) - 1, -1, -1):
|
||||
message = messages[index]
|
||||
if not _anchor_visible_human(message):
|
||||
continue
|
||||
if index > 0 and _anchor_is_clarification_result(messages[index - 1]):
|
||||
continue
|
||||
text = " ".join(_anchor_message_text(message).split())
|
||||
if not text:
|
||||
continue
|
||||
if prefix and text.startswith(prefix):
|
||||
return index
|
||||
if fallback < 0:
|
||||
fallback = index
|
||||
return fallback
|
||||
|
||||
|
||||
def _safe_stream_writer() -> Any:
|
||||
"""获取当前 run 的 custom 事件写入器;非流式上下文返回 None。"""
|
||||
try:
|
||||
from langgraph.config import get_stream_writer
|
||||
|
||||
return get_stream_writer()
|
||||
except Exception: # noqa: BLE001 - 非流式运行(测试/后台)没有 writer
|
||||
return None
|
||||
|
||||
|
||||
@tool("deep_research_report", parse_docstring=True)
|
||||
async def deep_research_report_tool(
|
||||
runtime: ToolRuntime[ContextT, ThreadState],
|
||||
tool_call_id: Annotated[str, InjectedToolCallId],
|
||||
topic: str,
|
||||
focus: str | None = None,
|
||||
retrieve: bool | None = None,
|
||||
) -> Command:
|
||||
"""Run the deep-research report pipeline on the conversation's materials and produce report.md as the writing-mode deliverable.
|
||||
|
||||
Call this AT DELIVERY TIME — when the conversation has gathered enough substance
|
||||
and the user expects the report file now (they asked to start writing, or you have
|
||||
finished discussing and the report is the natural next step). Before that, work
|
||||
exactly as usual (chat, search, clarify); do NOT call this tool early.
|
||||
|
||||
The tool harvests the materials already produced in this conversation (search /
|
||||
knowledge / skill / file tool results) and writes a full research report
|
||||
(general-analysis structure, numbered reference section) to
|
||||
/mnt/user-data/outputs/report.md in this thread. The file is presented
|
||||
automatically; do NOT write the report body yourself with write_file.
|
||||
|
||||
If the harvested pool is thin (or little of it matches the current topic), the
|
||||
tool still starts the writing pipeline immediately with whatever relevant
|
||||
materials exist — do NOT ask the user whether to search for more, and do NOT
|
||||
call ask_clarification for that reason. Search in the conversation first with
|
||||
your normal tools; this tool only writes the file.
|
||||
|
||||
Args:
|
||||
topic: The research topic / thesis to investigate. Copy the user's subject faithfully;
|
||||
do not paraphrase it into something narrower unless the user asked for that scope.
|
||||
focus: Optional extra write-time requirements from the user (length, tone, must-cover
|
||||
points, language preferences). Omit when the user gave none.
|
||||
retrieve: Ignored. Kept for older callers; the writing-mode pipeline never
|
||||
searches. False / omitted / True all write from conversation materials only.
|
||||
tool_call_id: Injected tool call id.
|
||||
"""
|
||||
# 与 present_file_tool 相同的解析顺序:runtime.context → runtime.config。
|
||||
thread_id = runtime.context.get("thread_id") if runtime.context else None
|
||||
if not thread_id:
|
||||
thread_id = ((getattr(runtime, "config", None) or {}).get("configurable") or {}).get("thread_id")
|
||||
thread_id = str(thread_id) if thread_id else ""
|
||||
if not thread_id:
|
||||
return Command(
|
||||
update={
|
||||
"messages": [
|
||||
ToolMessage(
|
||||
content="Error: deep_research_report could not resolve the current thread id.",
|
||||
tool_call_id=tool_call_id,
|
||||
name="deep_research_report",
|
||||
)
|
||||
]
|
||||
}
|
||||
)
|
||||
|
||||
query = topic.strip()
|
||||
state = getattr(runtime, "state", None) or {}
|
||||
conversation_messages = state.get("messages") or []
|
||||
harvested, _agent_summary = harvest_messages_materials(conversation_messages, query=query)
|
||||
# 课题请求之后的检索结果整批保留(那是模型为本课题检索的);只有课题
|
||||
# 切换前的旧检索才按词面强过滤(旧课题资料不得凑门槛、不得入报告)。
|
||||
anchor_index = topic_anchor_index(conversation_messages, topic=query)
|
||||
materials, dropped_count = _filter_relevant_materials(harvested, topic=query, anchor_index=anchor_index)
|
||||
harvested_count = len(materials)
|
||||
logger.info(
|
||||
"[deep_research_report] thread=%s harvested %d materials from conversation (topic-relevant %d, off-topic dropped %d, anchor_index=%d)",
|
||||
thread_id,
|
||||
len(harvested),
|
||||
harvested_count,
|
||||
dropped_count,
|
||||
anchor_index,
|
||||
)
|
||||
|
||||
if harvested_count < _MIN_HARVESTED_MATERIALS:
|
||||
logger.info(
|
||||
"[deep_research_report] thread=%s thin materials (%d < %d); writing immediately",
|
||||
thread_id,
|
||||
harvested_count,
|
||||
_MIN_HARVESTED_MATERIALS,
|
||||
)
|
||||
|
||||
if retrieve is True:
|
||||
logger.info(
|
||||
"[deep_research_report] thread=%s ignoring retrieve=true; writing-mode pipeline writes from conversation materials only",
|
||||
thread_id,
|
||||
)
|
||||
materials_provider: Any = StaticHarvestMaterialProvider(materials)
|
||||
material_source = "对话资料"
|
||||
|
||||
user_id = resolve_path_user_id(str(thread_id))
|
||||
session_id = f"chat-{thread_id}"
|
||||
writer = _safe_stream_writer()
|
||||
events = StreamWriterEventSink(writer, session_id=session_id, job_id=tool_call_id)
|
||||
|
||||
# P2:报告管线继承聊天选择的模型与思考开关,缺省回落系统默认模型。
|
||||
model_name, thinking_enabled, force_disable_thinking = _resolve_chat_model(runtime.context)
|
||||
research_config = build_writing_research_config(
|
||||
focus=focus,
|
||||
thinking_enabled=thinking_enabled,
|
||||
model_name=model_name,
|
||||
)
|
||||
llm_backend = DeerFlowCompletionBackend(
|
||||
research_config,
|
||||
event_sink=events,
|
||||
force_disable_thinking=force_disable_thinking,
|
||||
)
|
||||
bundle = AdapterBundle(
|
||||
llm=llm_backend,
|
||||
materials=materials_provider,
|
||||
context=DeerFlowContextCompressor(llm=llm_backend),
|
||||
artifacts=ThreadOutputsArtifactWriter(str(thread_id), user_id=user_id or None),
|
||||
events=events,
|
||||
images=build_image_provider(),
|
||||
)
|
||||
request = DeepResearchRequest(
|
||||
session_id=session_id,
|
||||
user_id=user_id,
|
||||
query=query,
|
||||
config=research_config,
|
||||
request_id=tool_call_id,
|
||||
)
|
||||
|
||||
logger.info(
|
||||
"[deep_research_report] thread=%s starting inline research (topic=%.80r, source=%s, harvested=%d)",
|
||||
thread_id,
|
||||
topic,
|
||||
material_source,
|
||||
harvested_count,
|
||||
)
|
||||
result = None
|
||||
error_message: str | None = None
|
||||
try:
|
||||
result = await DeepResearchEngine().run(request, adapters=bundle)
|
||||
except Exception as exc: # noqa: BLE001 - 工具错误以 ToolMessage 回给模型自纠
|
||||
logger.exception("[deep_research_report] thread=%s research failed", thread_id)
|
||||
error_message = f"深度研究报告生成失败:{exc}"
|
||||
|
||||
# 终态帧:无论成败都发,前端据此收尾进度条 / 停止流式预览。
|
||||
if writer is not None:
|
||||
try:
|
||||
writer(
|
||||
{
|
||||
"type": "deep_research_report",
|
||||
"event": {
|
||||
"type": "tool_finished",
|
||||
"sessionId": session_id,
|
||||
"jobId": tool_call_id,
|
||||
"phase": "done" if result is not None else "error",
|
||||
"payload": {
|
||||
"status": "success" if result is not None else "error",
|
||||
**({"error": error_message} if error_message else {}),
|
||||
},
|
||||
},
|
||||
}
|
||||
)
|
||||
except Exception: # noqa: BLE001
|
||||
logger.debug("[deep_research_report] tool_finished frame dropped", exc_info=True)
|
||||
|
||||
if result is None:
|
||||
return Command(
|
||||
update={
|
||||
"messages": [
|
||||
ToolMessage(
|
||||
content=f"Error: {error_message}. 收集资料或模型调用可能暂时不可用,可建议用户稍后重试。",
|
||||
tool_call_id=tool_call_id,
|
||||
name="deep_research_report",
|
||||
)
|
||||
]
|
||||
}
|
||||
)
|
||||
|
||||
source_count = len(result.source_ids or [])
|
||||
summary = f"研究报告已完成:基于 {source_count} 条资料({material_source})按「通用分析结构」撰写,已写入 {REPORT_VIRTUAL_PATH} 并展示给用户。请用 2-3 句话向用户简要总结报告的核心结论,不要复述全文。"
|
||||
logger.info(
|
||||
"[deep_research_report] thread=%s completed (sources=%d, report_chars=%d)",
|
||||
thread_id,
|
||||
source_count,
|
||||
len(result.report_markdown or ""),
|
||||
)
|
||||
return Command(
|
||||
update={
|
||||
"artifacts": [REPORT_VIRTUAL_PATH],
|
||||
"messages": [ToolMessage(content=summary, tool_call_id=tool_call_id, name="deep_research_report")],
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
__all__ = [
|
||||
"REPORT_VIRTUAL_PATH",
|
||||
"StreamWriterEventSink",
|
||||
"build_writing_research_config",
|
||||
"deep_research_report_tool",
|
||||
"is_writing_mode_report_path",
|
||||
"topic_anchor_index",
|
||||
]
|
||||
+155
@@ -0,0 +1,155 @@
|
||||
"""Memory V2 - Hindsight 的 3 个 LangChain 工具。
|
||||
|
||||
仅当 ``config.memory.hindsight.memory_mode`` 为 ``tools`` 或 ``hybrid`` 时,
|
||||
这些工具才会被 ``get_available_tools`` 加入工具集 (``context`` 模式不暴露)。
|
||||
|
||||
- hindsight_recall 多策略检索 (语义 + 实体图谱),查双 bank
|
||||
- hindsight_reflect 跨记忆综合 (LLM 推理)
|
||||
- hindsight_retain 主动存储一条记忆到全局 user bank
|
||||
|
||||
与 builtin 的 ``memory`` 工具一样,这些工具从 :class:`ToolRuntime` 与请求上下文
|
||||
解析 user_id / agent_id,按生效配置懒建一个 :class:`HindsightProvider` 后调用。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import logging
|
||||
|
||||
from langchain.tools import ToolRuntime, tool
|
||||
from langgraph.config import get_config
|
||||
from langgraph.typing import ContextT
|
||||
|
||||
from deerflow.agents.thread_state import ThreadState
|
||||
from deerflow.config.memory_config import get_effective_memory_config
|
||||
from deerflow.runtime.user_context import get_effective_user_id
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def _resolve_agent_id(runtime: ToolRuntime[ContextT, ThreadState]) -> str:
|
||||
"""从 runtime context / RunnableConfig 解析 agent_id,缺省 ``"default"``。"""
|
||||
agent_id = runtime.context.get("agent_id") if runtime.context else None
|
||||
if agent_id:
|
||||
return str(agent_id)
|
||||
runtime_config = getattr(runtime, "config", None) or {}
|
||||
agent_id = runtime_config.get("configurable", {}).get("agent_id")
|
||||
if agent_id:
|
||||
return str(agent_id)
|
||||
try:
|
||||
agent_id = get_config().get("configurable", {}).get("agent_id")
|
||||
except RuntimeError:
|
||||
agent_id = None
|
||||
return str(agent_id) if agent_id else "default"
|
||||
|
||||
|
||||
def _build_provider(runtime: ToolRuntime[ContextT, ThreadState]):
|
||||
"""按生效配置懒建并初始化一个 HindsightProvider;不可用时返回 ``None``。"""
|
||||
from deerflow.agents.memory.providers.hindsight import HindsightProvider
|
||||
|
||||
user_id = get_effective_user_id()
|
||||
config = get_effective_memory_config(user_id)
|
||||
if not config.enabled or config.provider != "hindsight":
|
||||
return None
|
||||
provider = HindsightProvider(config.hindsight)
|
||||
if not provider.is_available():
|
||||
return None
|
||||
thread_id = runtime.context.get("thread_id") if runtime.context else None
|
||||
provider.initialize(
|
||||
user_id=user_id,
|
||||
agent_id=_resolve_agent_id(runtime),
|
||||
thread_id=thread_id or "",
|
||||
base_dir="",
|
||||
)
|
||||
return provider
|
||||
|
||||
|
||||
@tool("hindsight_recall", parse_docstring=True)
|
||||
def hindsight_recall_tool(
|
||||
runtime: ToolRuntime[ContextT, ThreadState],
|
||||
query: str,
|
||||
) -> str:
|
||||
"""检索 Hindsight 长期记忆,查找与 query 相关的历史信息。
|
||||
|
||||
用于回答关于用户、过往会话、之前讨论过的内容的问题。会同时检索全局用户
|
||||
记忆和当前 agent 的工作记忆。
|
||||
|
||||
Args:
|
||||
query: 检索查询,描述你想找回什么信息。
|
||||
"""
|
||||
provider = _build_provider(runtime)
|
||||
if provider is None:
|
||||
return json.dumps({"success": False, "error": "Hindsight 记忆不可用。"}, ensure_ascii=False)
|
||||
try:
|
||||
results = provider.recall(query)
|
||||
except Exception as exc: # noqa: BLE001
|
||||
logger.warning("hindsight_recall 失败:%s", exc)
|
||||
return json.dumps({"success": False, "error": f"检索失败:{exc}"}, ensure_ascii=False)
|
||||
if not results:
|
||||
return json.dumps({"success": True, "result": "没有找到相关记忆。"}, ensure_ascii=False)
|
||||
lines = "\n".join(f"{i}. {text}" for i, text in enumerate(results, 1))
|
||||
return json.dumps({"success": True, "result": lines}, ensure_ascii=False)
|
||||
|
||||
|
||||
@tool("hindsight_reflect", parse_docstring=True)
|
||||
def hindsight_reflect_tool(
|
||||
runtime: ToolRuntime[ContextT, ThreadState],
|
||||
query: str,
|
||||
) -> str:
|
||||
"""对 Hindsight 记忆做跨记忆综合推理,得到一段综合性回答。
|
||||
|
||||
与 hindsight_recall 返回原始记忆片段不同,reflect 会让 LLM 综合多条记忆
|
||||
给出推理结论。适合需要归纳、总结、跨记忆关联的问题。
|
||||
|
||||
Args:
|
||||
query: 你希望综合分析的问题。
|
||||
"""
|
||||
provider = _build_provider(runtime)
|
||||
if provider is None:
|
||||
return json.dumps({"success": False, "error": "Hindsight 记忆不可用。"}, ensure_ascii=False)
|
||||
try:
|
||||
text = provider.reflect(query)
|
||||
except Exception as exc: # noqa: BLE001
|
||||
logger.warning("hindsight_reflect 失败:%s", exc)
|
||||
return json.dumps({"success": False, "error": f"综合失败:{exc}"}, ensure_ascii=False)
|
||||
return json.dumps(
|
||||
{"success": True, "result": text or "没有找到相关记忆。"}, ensure_ascii=False
|
||||
)
|
||||
|
||||
|
||||
@tool("hindsight_retain", parse_docstring=True)
|
||||
def hindsight_retain_tool(
|
||||
runtime: ToolRuntime[ContextT, ThreadState],
|
||||
content: str,
|
||||
) -> str:
|
||||
"""主动把一条信息存入 Hindsight 的全局用户记忆库。
|
||||
|
||||
用于记录跨会话、跨 agent 仍有价值的用户事实。Hindsight 会自动做实体抽取
|
||||
和知识图谱关联。
|
||||
|
||||
Args:
|
||||
content: 要存储的记忆内容。
|
||||
"""
|
||||
if not content or not content.strip():
|
||||
return json.dumps({"success": False, "error": "content 不能为空。"}, ensure_ascii=False)
|
||||
provider = _build_provider(runtime)
|
||||
if provider is None:
|
||||
return json.dumps({"success": False, "error": "Hindsight 记忆不可用。"}, ensure_ascii=False)
|
||||
try:
|
||||
provider.retain_to_user_bank(content.strip())
|
||||
except Exception as exc: # noqa: BLE001
|
||||
logger.warning("hindsight_retain 失败:%s", exc)
|
||||
return json.dumps({"success": False, "error": f"存储失败:{exc}"}, ensure_ascii=False)
|
||||
return json.dumps({"success": True, "result": "记忆已存储。"}, ensure_ascii=False)
|
||||
|
||||
|
||||
#: 三个 Hindsight 工具,供 get_available_tools 在 tools/hybrid 模式下加入。
|
||||
HINDSIGHT_TOOLS = [hindsight_recall_tool, hindsight_reflect_tool, hindsight_retain_tool]
|
||||
|
||||
|
||||
__all__ = [
|
||||
"hindsight_recall_tool",
|
||||
"hindsight_reflect_tool",
|
||||
"hindsight_retain_tool",
|
||||
"HINDSIGHT_TOOLS",
|
||||
]
|
||||
+257
@@ -0,0 +1,257 @@
|
||||
"""Built-in tool for invoking external ACP-compatible agents."""
|
||||
|
||||
import logging
|
||||
import os
|
||||
import shutil
|
||||
from typing import Annotated, Any
|
||||
|
||||
from langchain_core.runnables import RunnableConfig
|
||||
from langchain_core.tools import BaseTool, InjectedToolArg, StructuredTool
|
||||
from pydantic import BaseModel, Field
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class _InvokeACPAgentInput(BaseModel):
|
||||
agent: str = Field(description="Name of the ACP agent to invoke")
|
||||
prompt: str = Field(description="The concise task prompt to send to the agent")
|
||||
|
||||
|
||||
def _get_work_dir(thread_id: str | None) -> str:
|
||||
"""Get the per-thread ACP workspace directory.
|
||||
|
||||
Each thread gets an isolated workspace under
|
||||
``{base_dir}/threads/{thread_id}/acp-workspace/`` so that concurrent
|
||||
sessions cannot read or overwrite each other's ACP agent outputs.
|
||||
|
||||
Falls back to the legacy global ``{base_dir}/acp-workspace/`` when
|
||||
``thread_id`` is not available (e.g. embedded / direct invocation).
|
||||
|
||||
The directory is created automatically if it does not exist.
|
||||
|
||||
Returns:
|
||||
An absolute physical filesystem path to use as the working directory.
|
||||
"""
|
||||
from deerflow.config.paths import get_paths
|
||||
from deerflow.runtime.user_context import get_effective_user_id
|
||||
|
||||
paths = get_paths()
|
||||
if thread_id:
|
||||
try:
|
||||
work_dir = paths.acp_workspace_dir(thread_id, user_id=get_effective_user_id())
|
||||
except ValueError:
|
||||
logger.warning("Invalid thread_id %r for ACP workspace, falling back to global", thread_id)
|
||||
work_dir = paths.base_dir / "acp-workspace"
|
||||
else:
|
||||
work_dir = paths.base_dir / "acp-workspace"
|
||||
|
||||
work_dir.mkdir(parents=True, exist_ok=True)
|
||||
logger.info("ACP agent work_dir: %s", work_dir)
|
||||
return str(work_dir)
|
||||
|
||||
|
||||
def _build_mcp_servers() -> dict[str, dict[str, Any]]:
|
||||
"""Build ACP ``mcpServers`` config from DeerFlow's enabled MCP servers."""
|
||||
from deerflow.config.extensions_config import ExtensionsConfig
|
||||
from deerflow.mcp.client import build_servers_config
|
||||
|
||||
return build_servers_config(ExtensionsConfig.from_file())
|
||||
|
||||
|
||||
def _build_acp_mcp_servers() -> list[dict[str, Any]]:
|
||||
"""Build ACP ``mcpServers`` payload for ``new_session``.
|
||||
|
||||
The ACP client expects a list of server objects, while DeerFlow's MCP helper
|
||||
returns a name -> config mapping for the LangChain MCP adapter. This helper
|
||||
converts the enabled servers into the ACP wire format.
|
||||
"""
|
||||
from deerflow.config.extensions_config import ExtensionsConfig
|
||||
|
||||
extensions_config = ExtensionsConfig.from_file()
|
||||
enabled_servers = extensions_config.get_enabled_mcp_servers()
|
||||
|
||||
mcp_servers: list[dict[str, Any]] = []
|
||||
for name, server_config in enabled_servers.items():
|
||||
transport_type = server_config.type or "stdio"
|
||||
payload: dict[str, Any] = {"name": name, "type": transport_type}
|
||||
|
||||
if transport_type == "stdio":
|
||||
if not server_config.command:
|
||||
raise ValueError(f"MCP server '{name}' with stdio transport requires 'command' field")
|
||||
payload["command"] = server_config.command
|
||||
payload["args"] = server_config.args
|
||||
payload["env"] = [{"name": key, "value": value} for key, value in server_config.env.items()]
|
||||
elif transport_type in ("http", "sse"):
|
||||
if not server_config.url:
|
||||
raise ValueError(f"MCP server '{name}' with {transport_type} transport requires 'url' field")
|
||||
payload["url"] = server_config.url
|
||||
payload["headers"] = [{"name": key, "value": value} for key, value in server_config.headers.items()]
|
||||
else:
|
||||
raise ValueError(f"MCP server '{name}' has unsupported transport type: {transport_type}")
|
||||
|
||||
mcp_servers.append(payload)
|
||||
|
||||
return mcp_servers
|
||||
|
||||
|
||||
def _build_permission_response(options: list[Any], *, auto_approve: bool) -> Any:
|
||||
"""Build an ACP permission response.
|
||||
|
||||
When ``auto_approve`` is True, selects the first ``allow_once`` (preferred)
|
||||
or ``allow_always`` option. When False (the default), always cancels —
|
||||
permission requests must be handled by the ACP agent's own policy or the
|
||||
agent must be configured to operate without requesting permissions.
|
||||
"""
|
||||
from acp import RequestPermissionResponse
|
||||
from acp.schema import AllowedOutcome, DeniedOutcome
|
||||
|
||||
if auto_approve:
|
||||
for preferred_kind in ("allow_once", "allow_always"):
|
||||
for option in options:
|
||||
if getattr(option, "kind", None) != preferred_kind:
|
||||
continue
|
||||
|
||||
option_id = getattr(option, "option_id", None)
|
||||
if option_id is None:
|
||||
option_id = getattr(option, "optionId", None)
|
||||
if option_id is None:
|
||||
continue
|
||||
|
||||
return RequestPermissionResponse(
|
||||
outcome=AllowedOutcome(outcome="selected", optionId=option_id),
|
||||
)
|
||||
|
||||
return RequestPermissionResponse(outcome=DeniedOutcome(outcome="cancelled"))
|
||||
|
||||
|
||||
def _format_invocation_error(agent: str, cmd: str, exc: Exception) -> str:
|
||||
"""Return a user-facing ACP invocation error with actionable remediation."""
|
||||
if not isinstance(exc, FileNotFoundError):
|
||||
return f"Error invoking ACP agent '{agent}': {exc}"
|
||||
|
||||
message = f"Error invoking ACP agent '{agent}': Command '{cmd}' was not found on PATH."
|
||||
if cmd == "codex-acp" and shutil.which("codex"):
|
||||
return f"{message} The installed `codex` CLI does not speak ACP directly. Install a Codex ACP adapter (for example `npx @zed-industries/codex-acp`) or update `acp_agents.codex.command` and `args` in config.yaml."
|
||||
|
||||
return f"{message} Install the agent binary or update `acp_agents.{agent}.command` in config.yaml."
|
||||
|
||||
|
||||
def build_invoke_acp_agent_tool(agents: dict) -> BaseTool:
|
||||
"""Create the ``invoke_acp_agent`` tool with a description generated from configured agents.
|
||||
|
||||
The tool description includes the list of available agents so that the LLM
|
||||
knows which agents it can invoke without requiring hardcoded names.
|
||||
|
||||
Args:
|
||||
agents: Mapping of agent name -> ``ACPAgentConfig``.
|
||||
|
||||
Returns:
|
||||
A LangChain ``BaseTool`` ready to be included in the tool list.
|
||||
"""
|
||||
agent_lines = "\n".join(f"- {name}: {cfg.description}" for name, cfg in agents.items())
|
||||
description = (
|
||||
"Invoke an external ACP-compatible agent and return its final response.\n\n"
|
||||
"Available agents:\n"
|
||||
f"{agent_lines}\n\n"
|
||||
"IMPORTANT: ACP agents operate in their own independent workspace. "
|
||||
"Do NOT include /mnt/user-data paths in the prompt. "
|
||||
"Give the agent a self-contained task description — it will produce results in its own workspace. "
|
||||
"After the agent completes, its output files are accessible at /mnt/acp-workspace/ (read-only)."
|
||||
)
|
||||
|
||||
# Capture agents in closure so the function can reference it
|
||||
_agents = dict(agents)
|
||||
|
||||
async def _invoke(agent: str, prompt: str, config: Annotated[RunnableConfig, InjectedToolArg] = None) -> str:
|
||||
logger.info("Invoking ACP agent %s (prompt length: %d)", agent, len(prompt))
|
||||
logger.debug("Invoking ACP agent %s with prompt: %.200s%s", agent, prompt, "..." if len(prompt) > 200 else "")
|
||||
if agent not in _agents:
|
||||
available = ", ".join(_agents.keys())
|
||||
return f"Error: Unknown agent '{agent}'. Available: {available}"
|
||||
|
||||
agent_config = _agents[agent]
|
||||
thread_id: str | None = ((config or {}).get("configurable") or {}).get("thread_id")
|
||||
|
||||
try:
|
||||
from acp import PROTOCOL_VERSION, Client, text_block
|
||||
from acp.schema import ClientCapabilities, Implementation
|
||||
except ImportError:
|
||||
return "Error: agent-client-protocol package is not installed. Run `uv sync` to install project dependencies."
|
||||
|
||||
class _CollectingClient(Client):
|
||||
"""Minimal ACP Client that collects streamed text from session updates."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self._chunks: list[str] = []
|
||||
|
||||
@property
|
||||
def collected_text(self) -> str:
|
||||
return "".join(self._chunks)
|
||||
|
||||
async def session_update(self, session_id: str, update, **kwargs) -> None: # type: ignore[override]
|
||||
try:
|
||||
from acp.schema import TextContentBlock
|
||||
|
||||
if hasattr(update, "content") and isinstance(update.content, TextContentBlock):
|
||||
self._chunks.append(update.content.text)
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
async def request_permission(self, options, session_id: str, tool_call, **kwargs): # type: ignore[override]
|
||||
response = _build_permission_response(options, auto_approve=agent_config.auto_approve_permissions)
|
||||
outcome = response.outcome.outcome
|
||||
if outcome == "selected":
|
||||
logger.info("ACP permission auto-approved for tool call %s in session %s", tool_call.tool_call_id, session_id)
|
||||
else:
|
||||
logger.warning("ACP permission denied for tool call %s in session %s (set auto_approve_permissions: true in config.yaml to enable)", tool_call.tool_call_id, session_id)
|
||||
return response
|
||||
|
||||
client = _CollectingClient()
|
||||
cmd = agent_config.command
|
||||
args = agent_config.args or []
|
||||
physical_cwd = _get_work_dir(thread_id)
|
||||
try:
|
||||
mcp_servers = _build_acp_mcp_servers()
|
||||
except ValueError as exc:
|
||||
logger.warning(
|
||||
"Invalid MCP server configuration for ACP agent '%s'; continuing without MCP servers: %s",
|
||||
agent,
|
||||
exc,
|
||||
)
|
||||
mcp_servers = []
|
||||
agent_env: dict[str, str] | None = None
|
||||
if agent_config.env:
|
||||
agent_env = {k: (os.environ.get(v[1:], "") if v.startswith("$") else v) for k, v in agent_config.env.items()}
|
||||
|
||||
try:
|
||||
from acp import spawn_agent_process
|
||||
|
||||
async with spawn_agent_process(client, cmd, *args, env=agent_env, cwd=physical_cwd) as (conn, proc):
|
||||
logger.info("Spawning ACP agent '%s' with command '%s' and args %s in cwd %s", agent, cmd, args, physical_cwd)
|
||||
await conn.initialize(
|
||||
protocol_version=PROTOCOL_VERSION,
|
||||
client_capabilities=ClientCapabilities(),
|
||||
client_info=Implementation(name="deerflow", title="DeerFlow", version="0.1.0"),
|
||||
)
|
||||
session_kwargs: dict[str, Any] = {"cwd": physical_cwd, "mcp_servers": mcp_servers}
|
||||
if agent_config.model:
|
||||
session_kwargs["model"] = agent_config.model
|
||||
session = await conn.new_session(**session_kwargs)
|
||||
await conn.prompt(
|
||||
session_id=session.session_id,
|
||||
prompt=[text_block(prompt)],
|
||||
)
|
||||
result = client.collected_text
|
||||
logger.info("ACP agent '%s' returned %s", agent, result[:1000])
|
||||
logger.info("ACP agent '%s' returned %d characters", agent, len(result))
|
||||
return result or "(no response)"
|
||||
except Exception as e:
|
||||
logger.error("ACP agent '%s' invocation failed: %s", agent, e)
|
||||
return _format_invocation_error(agent, cmd, e)
|
||||
|
||||
return StructuredTool.from_function(
|
||||
name="invoke_acp_agent",
|
||||
description=description,
|
||||
coroutine=_invoke,
|
||||
args_schema=_InvokeACPAgentInput,
|
||||
)
|
||||
+134
@@ -0,0 +1,134 @@
|
||||
"""Authorized read-only WeKnora retrieval for cmzs Q&A."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import re
|
||||
from collections.abc import Mapping
|
||||
from typing import Any
|
||||
|
||||
from langchain.tools import ToolRuntime, tool
|
||||
from langgraph.typing import ContextT
|
||||
|
||||
from deerflow.agents.thread_state import ThreadState
|
||||
from deerflow.config import get_app_config
|
||||
from deerflow.config.agents_config import load_agent_config
|
||||
from deerflow.integrations.weknora.local_index.runtime import get_local_wiki_retrieval_service
|
||||
from deerflow.integrations.weknora.local_index.search import WikiIndexError
|
||||
from deerflow.integrations.weknora.runtime import get_llmwiki_store, get_resolved_llmwiki_runtime
|
||||
from deerflow.runtime.user_context import get_current_user, get_effective_user_id
|
||||
|
||||
_CONVERSATION_DEPOSIT_NAME = "对话沉淀"
|
||||
_CONVERSATION_DEPOSIT_OWNER_USER_ID = "system"
|
||||
_LEGACY_BRAND_PATTERN = re.compile(r"deer[\s_-]*flow", re.IGNORECASE)
|
||||
|
||||
|
||||
def _is_conversation_deposit_mapping(row: Mapping[str, Any]) -> bool:
|
||||
return str(row.get("owner_user_id") or "") == _CONVERSATION_DEPOSIT_OWNER_USER_ID and str(row.get("name") or "").strip() == _CONVERSATION_DEPOSIT_NAME
|
||||
|
||||
|
||||
def _sanitize_conversation_deposit_value(value: Any) -> Any:
|
||||
if isinstance(value, str):
|
||||
return _LEGACY_BRAND_PATTERN.sub("cmzs", value)
|
||||
if isinstance(value, dict):
|
||||
return {key: _sanitize_conversation_deposit_value(item) for key, item in value.items()}
|
||||
if isinstance(value, list):
|
||||
return [_sanitize_conversation_deposit_value(item) for item in value]
|
||||
if isinstance(value, tuple):
|
||||
return tuple(_sanitize_conversation_deposit_value(item) for item in value)
|
||||
return value
|
||||
|
||||
|
||||
def selected_knowledge_base_ids(context: Mapping[str, Any] | None) -> list[str] | None:
|
||||
"""Read the conversation selection; ``None`` means legacy/no selection key."""
|
||||
|
||||
if not context or "llmwiki_knowledge_base_ids" not in context:
|
||||
return None
|
||||
raw = context.get("llmwiki_knowledge_base_ids")
|
||||
if not isinstance(raw, list):
|
||||
return []
|
||||
return list(dict.fromkeys(str(item).strip() for item in raw if str(item).strip()))[:100]
|
||||
|
||||
|
||||
def _agent_allowed_ids(context: Mapping[str, Any] | None) -> list[str] | None:
|
||||
agent_id = str((context or {}).get("agent_id") or "").strip()
|
||||
if not agent_id or agent_id in {"default", "lead_agent"}:
|
||||
return None
|
||||
try:
|
||||
config = load_agent_config(agent_id)
|
||||
except (FileNotFoundError, ValueError):
|
||||
return []
|
||||
return list(config.llmwiki_knowledge_base_ids or []) if config else []
|
||||
|
||||
|
||||
@tool("llmwiki_search", parse_docstring=True)
|
||||
async def llmwiki_search_tool(
|
||||
query: str,
|
||||
runtime: ToolRuntime[ContextT, ThreadState],
|
||||
) -> str:
|
||||
"""Search the LLMWiki knowledge selected for this conversation.
|
||||
|
||||
Use this tool only when the current conversation explicitly selected one
|
||||
or more LLMWiki knowledge bases. It only retrieves passages; it cannot
|
||||
upload, edit, delete, publish or change permissions.
|
||||
|
||||
Args:
|
||||
query: Focused natural-language retrieval query.
|
||||
"""
|
||||
|
||||
local_config = get_app_config().llmwiki.local_wiki_index
|
||||
resolved = get_resolved_llmwiki_runtime()
|
||||
if not (local_config.enabled and local_config.internal_search_enabled) and not resolved.weknora_enabled:
|
||||
return "LLMWiki retrieval is unavailable because no retrieval provider is enabled."
|
||||
|
||||
store = get_llmwiki_store()
|
||||
user_id = get_effective_user_id()
|
||||
is_admin = getattr(get_current_user(), "system_role", None) == "admin"
|
||||
context = runtime.context if runtime.context else {}
|
||||
selected_ids = selected_knowledge_base_ids(context)
|
||||
allowed_ids = _agent_allowed_ids(context)
|
||||
if selected_ids is None:
|
||||
return "No LLMWiki knowledge base is selected for this conversation."
|
||||
elif allowed_ids is not None and not set(selected_ids).issubset(set(allowed_ids)):
|
||||
return "The conversation requested knowledge outside this agent's configured LLMWiki scope."
|
||||
|
||||
if selected_ids == []:
|
||||
return "No LLMWiki knowledge base is selected for this conversation."
|
||||
rows = []
|
||||
for mapping_id in selected_ids:
|
||||
row = await store.get_authorized(
|
||||
mapping_id,
|
||||
user_id,
|
||||
write=False,
|
||||
is_admin=is_admin,
|
||||
)
|
||||
if row is None:
|
||||
return f"Knowledge base {mapping_id!r} is not available to the current user."
|
||||
rows.append(row)
|
||||
if not rows:
|
||||
return "No authorized LLMWiki knowledge bases are available."
|
||||
|
||||
try:
|
||||
payload = await get_local_wiki_retrieval_service().search(query.strip(), rows)
|
||||
except (RuntimeError, WikiIndexError) as exc:
|
||||
code = exc.code if isinstance(exc, WikiIndexError) else "WIKI_RETRIEVAL_UNAVAILABLE"
|
||||
return f"LLMWiki Wiki-only retrieval failed ({code}); retrieval is unavailable, not empty."
|
||||
mapping_by_id = {str(row["id"]): row for row in rows}
|
||||
results = []
|
||||
for item in payload["results"]:
|
||||
mapping = mapping_by_id.get(str(item.get("knowledge_base_id") or ""))
|
||||
visible = _sanitize_conversation_deposit_value(item) if mapping and _is_conversation_deposit_mapping(mapping) else item
|
||||
results.append(visible)
|
||||
return json.dumps(
|
||||
{
|
||||
"query": query,
|
||||
"selection": [row["id"] for row in rows],
|
||||
"knowledge_base_count": len(rows),
|
||||
"mode": payload.get("mode") or "wiki_api",
|
||||
"results": results,
|
||||
"partial": payload.get("partial", False),
|
||||
"warnings": payload.get("warnings", []),
|
||||
"fallback_knowledge_base_ids": payload.get("fallback_knowledge_base_ids", []),
|
||||
},
|
||||
ensure_ascii=False,
|
||||
)
|
||||
+171
@@ -0,0 +1,171 @@
|
||||
"""Memory V2 - LLM 主动调用的 ``memory`` 工具。
|
||||
|
||||
让 LLM 在对话过程中主动把跨会话仍有用的信息记到持久化记忆里 ——
|
||||
对应 Hermes 的 ``memory`` 工具,是双轨写入里的 "主动" 一轨。
|
||||
|
||||
工具写入直达 :class:`BuiltinFileProvider`:
|
||||
- ``target="user"`` -> ``USER.md`` (用户画像,跨 agent 共享)
|
||||
- ``target="memory"`` -> ``MEMORY.md`` (agent 私有工作笔记)
|
||||
|
||||
agent_id / user_id 在工具调用时从 :class:`ToolRuntime` 与请求上下文解析。
|
||||
P2 期会在写入后追加 Hindsight 镜像 (``on_memory_write`` 钩子)。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import logging
|
||||
from typing import Literal
|
||||
|
||||
from langchain.tools import ToolRuntime, tool
|
||||
from langgraph.config import get_config
|
||||
from langgraph.typing import ContextT
|
||||
|
||||
from deerflow.agents.memory.providers.builtin import BuiltinFileProvider
|
||||
from deerflow.agents.thread_state import ThreadState
|
||||
from deerflow.config.memory_config import get_effective_memory_config
|
||||
from deerflow.config.paths import get_paths
|
||||
from deerflow.runtime.user_context import get_effective_user_id
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def _resolve_agent_id(runtime: ToolRuntime[ContextT, ThreadState]) -> str:
|
||||
"""从 runtime context / RunnableConfig 解析当前 agent_id,缺省为 ``"default"``。"""
|
||||
agent_id = runtime.context.get("agent_id") if runtime.context else None
|
||||
if agent_id:
|
||||
return str(agent_id)
|
||||
runtime_config = getattr(runtime, "config", None) or {}
|
||||
agent_id = runtime_config.get("configurable", {}).get("agent_id")
|
||||
if agent_id:
|
||||
return str(agent_id)
|
||||
try:
|
||||
agent_id = get_config().get("configurable", {}).get("agent_id")
|
||||
except RuntimeError:
|
||||
agent_id = None
|
||||
return str(agent_id) if agent_id else "default"
|
||||
|
||||
|
||||
@tool("memory", parse_docstring=True)
|
||||
def memory_tool(
|
||||
runtime: ToolRuntime[ContextT, ThreadState],
|
||||
action: Literal["add", "replace", "remove"],
|
||||
target: Literal["memory", "user"],
|
||||
content: str | None = None,
|
||||
old_text: str | None = None,
|
||||
) -> str:
|
||||
"""把跨会话仍有用的信息记到持久化记忆里。
|
||||
|
||||
记忆会被注入到后续对话的系统提示词中,所以请保持简洁、只记真正还会用到的事实。
|
||||
|
||||
什么时候应该记 (主动判断,不必等用户开口):
|
||||
- 用户纠正你,或者说 "记住这件事" / "下次别这样"
|
||||
- 用户透露偏好、习惯、个人信息 (姓名、角色、时区、代码风格)
|
||||
- 你发现了环境/项目/工具相关、之后还会复用的稳定事实
|
||||
|
||||
两类 target —— 拿不准时优先选 memory:
|
||||
- memory:当前 agent 的私有记忆 (agent 隔离)。**默认选这个。**
|
||||
只要用户是在对当前这个 agent 说话 —— 例如 "你以后……"、"和我说话时……"、
|
||||
针对本助手的语气/开场白/回复风格/处理方式,以及环境事实、约定、踩过的坑 —— 一律记到 memory,
|
||||
这样只影响当前 agent。
|
||||
- user:用户画像 (跨所有 agent 共享)。仅当信息是**跨所有 agent 都通用**的客观身份事实时才用 ——
|
||||
姓名、角色、时区、惯用语言。除非用户明确说 "所有助手都……",否则不要把沟通风格/偏好记到 user。
|
||||
|
||||
不要记:一次性任务进度、可以重新查到的信息、临时 TODO 状态。
|
||||
|
||||
Args:
|
||||
action: 操作类型。add 新增条目;replace 替换 (用 old_text 定位);remove 删除 (用 old_text 定位)。
|
||||
target: 记忆类别。默认用 memory (当前 agent 私有);只有跨所有 agent 通用的用户身份事实才用 user。
|
||||
content: 条目内容。action 为 add 或 replace 时必填。
|
||||
old_text: 短唯一子串,用于定位要替换或删除的条目。action 为 replace 或 remove 时必填。
|
||||
"""
|
||||
user_id = get_effective_user_id()
|
||||
config = get_effective_memory_config(user_id)
|
||||
|
||||
if not config.enabled:
|
||||
return json.dumps(
|
||||
{"success": False, "error": "记忆功能未启用,可能在配置中被关闭。"},
|
||||
ensure_ascii=False,
|
||||
)
|
||||
|
||||
if getattr(config, "version", "v2") == "v1":
|
||||
return json.dumps(
|
||||
{"success": False, "error": "当前使用 V1 记忆模式,记忆由系统自动提取,不支持手动写入。"},
|
||||
ensure_ascii=False,
|
||||
)
|
||||
|
||||
if not config.builtin.enabled:
|
||||
return json.dumps(
|
||||
{"success": False, "error": "记忆功能未启用,可能在配置中被关闭。"},
|
||||
ensure_ascii=False,
|
||||
)
|
||||
|
||||
if target not in ("memory", "user"):
|
||||
return json.dumps(
|
||||
{"success": False, "error": f"非法 target '{target}',只能是 'memory' 或 'user'。"},
|
||||
ensure_ascii=False,
|
||||
)
|
||||
|
||||
agent_id = _resolve_agent_id(runtime)
|
||||
provider = BuiltinFileProvider(
|
||||
memory_char_limit=config.builtin.memory_char_limit,
|
||||
user_char_limit=config.builtin.user_char_limit,
|
||||
deduplicate_on_load=config.builtin.deduplicate_on_load,
|
||||
security=config.security,
|
||||
)
|
||||
try:
|
||||
provider.initialize(
|
||||
user_id=user_id,
|
||||
agent_id=agent_id,
|
||||
base_dir=str(get_paths().base_dir),
|
||||
)
|
||||
except Exception as exc: # noqa: BLE001 - 初始化失败要返回给 LLM 而非崩溃
|
||||
logger.warning("memory 工具初始化 BuiltinFileProvider 失败:%s", exc)
|
||||
return json.dumps(
|
||||
{"success": False, "error": f"记忆初始化失败:{exc}"}, ensure_ascii=False
|
||||
)
|
||||
|
||||
if action == "add":
|
||||
if not content:
|
||||
result = {"success": False, "error": "action=add 需要提供 content。"}
|
||||
else:
|
||||
result = provider.add(target, content)
|
||||
elif action == "replace":
|
||||
if not old_text:
|
||||
result = {"success": False, "error": "action=replace 需要提供 old_text。"}
|
||||
elif not content:
|
||||
result = {"success": False, "error": "action=replace 需要提供 content。"}
|
||||
else:
|
||||
result = provider.replace(target, old_text, content)
|
||||
elif action == "remove":
|
||||
if not old_text:
|
||||
result = {"success": False, "error": "action=remove 需要提供 old_text。"}
|
||||
else:
|
||||
result = provider.remove(target, old_text)
|
||||
else:
|
||||
result = {"success": False, "error": f"未知 action '{action}',只能是 add / replace / remove。"}
|
||||
|
||||
# 写入成功后镜像到外部 provider (Hindsight)。失败不影响 builtin 写入结果。
|
||||
if result.get("success") and action in ("add", "replace") and content:
|
||||
_mirror_to_external(config, user_id, agent_id, thread_id="", action=action, target=target, content=content)
|
||||
|
||||
return json.dumps(result, ensure_ascii=False)
|
||||
|
||||
|
||||
def _mirror_to_external(config, user_id: str, agent_id: str, *, thread_id: str, action: str, target: str, content: str) -> None:
|
||||
"""把一次 builtin 记忆写入镜像到外部 provider (P2: Hindsight)。"""
|
||||
if config.provider != "hindsight":
|
||||
return
|
||||
try:
|
||||
from deerflow.agents.memory.providers.hindsight import HindsightProvider
|
||||
|
||||
provider = HindsightProvider(config.hindsight)
|
||||
if not provider.is_available():
|
||||
return
|
||||
provider.initialize(user_id=user_id, agent_id=agent_id, thread_id=thread_id, base_dir="")
|
||||
provider.on_memory_write(action, target, content, metadata={"user_id": user_id, "agent_id": agent_id})
|
||||
except Exception as exc: # noqa: BLE001 - 镜像失败不影响 builtin 写入
|
||||
logger.debug("memory 工具镜像到 Hindsight 失败:%s", exc)
|
||||
|
||||
|
||||
__all__ = ["memory_tool"]
|
||||
+71
@@ -0,0 +1,71 @@
|
||||
"""空间 RAG 检索工具。
|
||||
|
||||
从 LangGraph configurable 中读取 notebook_search_space_id / notebook_source_ids /
|
||||
notebook_token,调用外部检索接口返回相关文本块,供 LLM 在空间模式下引用回答。
|
||||
|
||||
API base URL 通过环境变量 DEER_FLOW_NOTEBOOK_API_BASE 配置。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import os
|
||||
|
||||
import httpx
|
||||
from langchain.tools import tool
|
||||
from langgraph.config import get_config
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
_SEARCH_PATH = "/api/v1/source/mentioned-documents/search"
|
||||
|
||||
|
||||
def _notebook_api_base() -> str:
|
||||
return (os.getenv("DEER_FLOW_NOTEBOOK_API_BASE") or "").rstrip("/")
|
||||
|
||||
|
||||
@tool("search_notebook_sources", parse_docstring=True)
|
||||
def notebook_search_tool(query: str, top_k: int = 10) -> str:
|
||||
"""Search the notebook's knowledge sources to find relevant content.
|
||||
|
||||
Call this tool for EVERY user question. After retrieving results, cite
|
||||
sources inline using [[cite:<document_id>]] markers immediately after
|
||||
each claim, e.g. "违约金为0.5%[[cite:101]]".
|
||||
|
||||
Args:
|
||||
query: The user's question or a refined search query.
|
||||
top_k: Number of top chunks to retrieve (default 10).
|
||||
"""
|
||||
base = _notebook_api_base()
|
||||
if not base:
|
||||
return "Notebook API base URL not configured (DEER_FLOW_NOTEBOOK_API_BASE)."
|
||||
|
||||
cfg = get_config().get("configurable", {})
|
||||
search_space_id: int | None = cfg.get("notebook_search_space_id")
|
||||
source_ids: list[int] = cfg.get("notebook_source_ids") or []
|
||||
token: str = cfg.get("notebook_token") or ""
|
||||
|
||||
if not search_space_id:
|
||||
return "No notebook search space configured."
|
||||
|
||||
logger.info("notebook_search_tool query=%r source_ids=%s search_space_id=%s", query, source_ids, search_space_id)
|
||||
|
||||
try:
|
||||
resp = httpx.post(
|
||||
f"{base}{_SEARCH_PATH}",
|
||||
headers={"Authorization": f"Bearer {token}"},
|
||||
json={
|
||||
"query": query,
|
||||
"source_ids": source_ids,
|
||||
"search_space_id": search_space_id,
|
||||
"top_k": top_k,
|
||||
},
|
||||
timeout=30,
|
||||
)
|
||||
resp.raise_for_status()
|
||||
data = resp.json()
|
||||
content = data.get("content") if isinstance(data, dict) else None
|
||||
return content if content else "No relevant content found."
|
||||
except Exception as e:
|
||||
logger.warning("notebook_search_tool failed: %s", e)
|
||||
return f"Search failed: {e}"
|
||||
+322
@@ -0,0 +1,322 @@
|
||||
"""Thread-safe page-report template preparation and static quality checks."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import re
|
||||
from collections.abc import Iterable
|
||||
from pathlib import Path
|
||||
|
||||
from langchain.tools import ToolRuntime, tool
|
||||
from langgraph.typing import ContextT
|
||||
|
||||
from deerflow.agents.thread_state import ThreadState
|
||||
from deerflow.config.paths import VIRTUAL_PATH_PREFIX, get_paths
|
||||
from deerflow.page_reports.templates import (
|
||||
choose_template,
|
||||
get_template_profile,
|
||||
list_template_profiles,
|
||||
resolve_template_file,
|
||||
)
|
||||
from deerflow.runtime.thread_paths import resolve_path_user_id
|
||||
|
||||
_MAX_HTML_BYTES = 4 * 1024 * 1024
|
||||
# Allow human-readable Chinese filenames while still rejecting path separators,
|
||||
# Windows-reserved filename characters, and control characters.
|
||||
_SAFE_OUTPUT_NAME = re.compile(r'^[^<>:"/\\|?*\x00-\x1f]+\.html$', re.IGNORECASE)
|
||||
_FONT_SIZE_RE = re.compile(r"font-size\s*:\s*([0-9]+(?:\.[0-9]+)?)px", re.IGNORECASE)
|
||||
_MIN_TEXT_FONT_SIZE = 16.0
|
||||
|
||||
|
||||
def _thread_id(runtime: ToolRuntime[ContextT, ThreadState]) -> str:
|
||||
context = runtime.context or {}
|
||||
thread_id = context.get("thread_id")
|
||||
if not thread_id:
|
||||
thread_id = (getattr(runtime, "config", {}) or {}).get("configurable", {}).get("thread_id")
|
||||
if not thread_id:
|
||||
raise ValueError("当前会话缺少 thread_id,无法准备页面模板。")
|
||||
return str(thread_id)
|
||||
|
||||
|
||||
def _virtual_path(path: Path, *, thread_id: str, user_id: str | None) -> str:
|
||||
root = get_paths().sandbox_user_data_dir(thread_id, user_id=user_id).resolve()
|
||||
relative = path.resolve().relative_to(root)
|
||||
return f"{VIRTUAL_PATH_PREFIX}/{relative.as_posix()}"
|
||||
|
||||
|
||||
def _thread_directories(runtime: ToolRuntime[ContextT, ThreadState]) -> tuple[str, str | None, Path, Path]:
|
||||
thread_id = _thread_id(runtime)
|
||||
user_id = resolve_path_user_id(thread_id)
|
||||
paths = get_paths()
|
||||
workspace = paths.sandbox_work_dir(thread_id, user_id=user_id)
|
||||
outputs = paths.sandbox_outputs_dir(thread_id, user_id=user_id)
|
||||
workspace.mkdir(parents=True, exist_ok=True)
|
||||
outputs.mkdir(parents=True, exist_ok=True)
|
||||
return thread_id, user_id, workspace, outputs
|
||||
|
||||
|
||||
def _safe_output_filename(output_name: str) -> str:
|
||||
raw = (output_name or "report-page.html").strip()
|
||||
if not raw.lower().endswith(".html"):
|
||||
raw += ".html"
|
||||
if Path(raw).name != raw or not _SAFE_OUTPUT_NAME.fullmatch(raw):
|
||||
raise ValueError("output_name 必须是单个安全的 .html 文件名,不能包含路径或 Windows 非法字符。")
|
||||
return raw
|
||||
|
||||
|
||||
def _apply_minimum_font_size(html: str) -> str:
|
||||
"""Normalize editable template copies to the report designer's font floor.
|
||||
|
||||
The library includes some legacy dashboard skeletons with compact labels.
|
||||
They are useful layout starting points, but the designer contract requires
|
||||
that visible text is at least 16px. Normalize the *per-thread copy* here
|
||||
so a weaker model does not have to remember a large CSS-only cleanup before
|
||||
it can work on the actual report content. The immutable source template is
|
||||
never changed, and ``validate`` remains the final guard if later edits add
|
||||
a smaller declaration.
|
||||
"""
|
||||
|
||||
def replace(match: re.Match[str]) -> str:
|
||||
size = float(match.group(1))
|
||||
if size >= _MIN_TEXT_FONT_SIZE:
|
||||
return match.group(0)
|
||||
return f"font-size: {_MIN_TEXT_FONT_SIZE:g}px"
|
||||
|
||||
return _FONT_SIZE_RE.sub(replace, html)
|
||||
|
||||
|
||||
def _edit_contract(template_id: str) -> dict[str, object]:
|
||||
profile = get_template_profile(template_id)
|
||||
chart_driven = "reportData" in profile.data_entry
|
||||
return {
|
||||
"data_entry": profile.data_entry,
|
||||
"edit_order": [
|
||||
"先把用户材料整理为文字摘要、指标、表格行、图表数据和待办事项。",
|
||||
"只编辑工作区的副本;禁止改动模板源文件。",
|
||||
"若存在 reportData,先改该对象中的图表数组,再替换标题、段落、卡片和表格文案。",
|
||||
"根据材料删掉无数据的卡片或整页;不要为了凑页数保留空白面板。",
|
||||
"将最终 HTML 写入 outputs 后调用 validate;通过后用 present_files 交付。",
|
||||
],
|
||||
"must_keep": (
|
||||
["reportData 的字段名和图表渲染函数", "页面切换及 prefers-reduced-motion 逻辑"]
|
||||
if chart_driven
|
||||
else ["已有布局类名", "移动端 / reduced-motion 样式"]
|
||||
),
|
||||
"illustrative_data_rule": "没有可核验数值但用户明确要求图表时,可画示意图;页面必须在图例或数据口径处标注“示意数据 / 待补充数据”,不得伪装为事实。",
|
||||
}
|
||||
|
||||
|
||||
def _prepare(
|
||||
runtime: ToolRuntime[ContextT, ThreadState],
|
||||
*,
|
||||
theme: str,
|
||||
content_density: str,
|
||||
required_features: list[str],
|
||||
preferred_page_count: int | None,
|
||||
selection_key: str,
|
||||
exclude_template_ids: list[str],
|
||||
template_id: str | None,
|
||||
output_name: str,
|
||||
page_brief: str,
|
||||
) -> str:
|
||||
profile = (
|
||||
get_template_profile(template_id)
|
||||
if (template_id or "").strip()
|
||||
else choose_template(
|
||||
theme=theme,
|
||||
content_density=content_density,
|
||||
required_features=required_features,
|
||||
preferred_page_count=preferred_page_count,
|
||||
selection_key=selection_key,
|
||||
exclude_template_ids=exclude_template_ids,
|
||||
)
|
||||
)
|
||||
source = resolve_template_file(profile.id)
|
||||
thread_id, user_id, workspace, outputs = _thread_directories(runtime)
|
||||
filename = _safe_output_filename(output_name)
|
||||
working_copy = workspace / f"{Path(filename).stem}--{profile.id}.html"
|
||||
brief_path = workspace / f"{Path(filename).stem}--page-brief.json"
|
||||
# Copy first, then normalize only the editable thread-local copy. This
|
||||
# preserves the bundled assets exactly as supplied while giving every run a
|
||||
# usable 16px-or-larger starting point.
|
||||
working_copy.write_text(_apply_minimum_font_size(source.read_text(encoding="utf-8")), encoding="utf-8")
|
||||
brief = {
|
||||
"template": profile.to_dict(),
|
||||
"requested_theme": theme or "auto",
|
||||
"requested_content_density": content_density or "balanced",
|
||||
"required_features": required_features,
|
||||
"recommended_final_output": _virtual_path(outputs / filename, thread_id=thread_id, user_id=user_id),
|
||||
"working_copy": _virtual_path(working_copy, thread_id=thread_id, user_id=user_id),
|
||||
"user_material_brief": (page_brief or "").strip(),
|
||||
"edit_contract": _edit_contract(profile.id),
|
||||
"font_rule": "所有可见文字最小字号为 16px;生成后必须通过 validate 校验。",
|
||||
}
|
||||
brief_path.write_text(json.dumps(brief, ensure_ascii=False, indent=2), encoding="utf-8")
|
||||
return json.dumps(
|
||||
{
|
||||
"ok": True,
|
||||
"template": profile.to_dict(),
|
||||
"working_copy": _virtual_path(working_copy, thread_id=thread_id, user_id=user_id),
|
||||
"brief_path": _virtual_path(brief_path, thread_id=thread_id, user_id=user_id),
|
||||
"final_output": brief["recommended_final_output"],
|
||||
"next_step": "读取 brief_path 和 working_copy,改完后写入 final_output,再调用 action=validate。",
|
||||
},
|
||||
ensure_ascii=False,
|
||||
)
|
||||
|
||||
|
||||
def _resolve_current_thread_file(
|
||||
runtime: ToolRuntime[ContextT, ThreadState],
|
||||
virtual_path: str,
|
||||
) -> tuple[Path, str, str | None]:
|
||||
thread_id, user_id, workspace, outputs = _thread_directories(runtime)
|
||||
normalized = (virtual_path or "").strip()
|
||||
if not normalized.startswith(f"{VIRTUAL_PATH_PREFIX}/"):
|
||||
raise ValueError(f"file_path 必须位于 {VIRTUAL_PATH_PREFIX}/workspace 或 {VIRTUAL_PATH_PREFIX}/outputs。")
|
||||
actual = get_paths().resolve_virtual_path(thread_id, normalized, user_id=user_id)
|
||||
permitted_roots: Iterable[Path] = (workspace.resolve(), outputs.resolve())
|
||||
if not any(actual.is_relative_to(root) for root in permitted_roots):
|
||||
raise ValueError("file_path 只能指向当前会话的 workspace 或 outputs 目录。")
|
||||
if not actual.is_file():
|
||||
raise ValueError(f"待校验 HTML 不存在:{virtual_path}")
|
||||
return actual, thread_id, user_id
|
||||
|
||||
|
||||
def _count_textual_content(html: str) -> int:
|
||||
plain = re.sub(r"<script[\s\S]*?</script>|<style[\s\S]*?</style>|<[^>]+>", " ", html, flags=re.IGNORECASE)
|
||||
return len(re.sub(r"\s+", "", plain))
|
||||
|
||||
|
||||
def _quality_report(html: str, *, data_mode: str, expected_features: set[str]) -> dict[str, object]:
|
||||
lowered = html.lower()
|
||||
errors: list[str] = []
|
||||
warnings: list[str] = []
|
||||
if "<!doctype html" not in lowered or "</html>" not in lowered:
|
||||
errors.append("HTML 不完整:需要 <!doctype html> 和 </html>。")
|
||||
if "<body" not in lowered or "</body>" not in lowered:
|
||||
errors.append("HTML 缺少完整 body 结构。")
|
||||
if "<title" not in lowered:
|
||||
errors.append("页面缺少 title。")
|
||||
if _count_textual_content(html) < 500:
|
||||
warnings.append("有效文字内容偏少;本类页面应以结论、要点、说明和行动项为主体。")
|
||||
chart_markers = {"line": "svg", "bar": "bar", "pie": "pie", "radar": "radar", "scatter": "scatter", "gantt": "gantt"}
|
||||
for feature in expected_features:
|
||||
marker = chart_markers.get(feature)
|
||||
if marker and marker not in lowered:
|
||||
warnings.append(f"未检测到请求的 {feature} 图表结构,请确认是否应删去该要求或补充图表。")
|
||||
font_sizes = [float(value) for value in _FONT_SIZE_RE.findall(html)]
|
||||
too_small = sorted({value for value in font_sizes if value < 16})
|
||||
if too_small:
|
||||
errors.append("发现小于 16px 的字号:" + "、".join(f"{value:g}px" for value in too_small[:8]) + "。")
|
||||
if (data_mode or "provided").strip().lower() in {"illustrative", "mixed"} and not any(
|
||||
mark in html for mark in ("示意数据", "待补充数据", "模拟数据")
|
||||
):
|
||||
errors.append("示意图表没有标注“示意数据 / 待补充数据”,可能被误认为事实。")
|
||||
if "reportdata" in lowered and "const reportdata" not in lowered:
|
||||
warnings.append("检测到 reportData 引用但未检测到 const reportData 定义,请检查图表脚本。")
|
||||
return {
|
||||
"ok": not errors,
|
||||
"errors": errors,
|
||||
"warnings": warnings,
|
||||
"metrics": {
|
||||
"bytes": len(html.encode("utf-8")),
|
||||
"text_characters": _count_textual_content(html),
|
||||
"page_sections": len(re.findall(r"class=[\"'][^\"']*(?:report-page|page)[^\"']*[\"']", html, flags=re.IGNORECASE)),
|
||||
"has_script": "<script" in lowered,
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
def _validate(
|
||||
runtime: ToolRuntime[ContextT, ThreadState],
|
||||
*,
|
||||
file_path: str,
|
||||
data_mode: str,
|
||||
expected_features: list[str],
|
||||
) -> str:
|
||||
actual, thread_id, user_id = _resolve_current_thread_file(runtime, file_path)
|
||||
if actual.stat().st_size > _MAX_HTML_BYTES:
|
||||
raise ValueError(f"HTML 超过 {_MAX_HTML_BYTES // 1024 // 1024}MB,拒绝读取。")
|
||||
html = actual.read_text(encoding="utf-8")
|
||||
report = _quality_report(
|
||||
html,
|
||||
data_mode=data_mode,
|
||||
expected_features={item.strip().lower() for item in expected_features if item.strip()},
|
||||
)
|
||||
report_path = actual.with_name(f"{actual.stem}.quality.json")
|
||||
report_path.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
|
||||
report["quality_report"] = _virtual_path(report_path, thread_id=thread_id, user_id=user_id)
|
||||
report["file_path"] = _virtual_path(actual, thread_id=thread_id, user_id=user_id)
|
||||
return json.dumps(report, ensure_ascii=False)
|
||||
|
||||
|
||||
@tool("page_report_template", parse_docstring=True)
|
||||
def page_report_template_tool(
|
||||
runtime: ToolRuntime[ContextT, ThreadState],
|
||||
action: str,
|
||||
theme: str = "auto",
|
||||
content_density: str = "balanced",
|
||||
required_features: list[str] | None = None,
|
||||
preferred_page_count: int | None = None,
|
||||
selection_key: str = "",
|
||||
exclude_template_ids: list[str] | None = None,
|
||||
template_id: str | None = None,
|
||||
output_name: str = "report-page.html",
|
||||
page_brief: str = "",
|
||||
file_path: str = "",
|
||||
data_mode: str = "provided",
|
||||
) -> str:
|
||||
"""Select, copy, and quality-check reusable HTML report-page templates.
|
||||
|
||||
Use this tool instead of editing a source template in place.
|
||||
|
||||
Args:
|
||||
action: One of ``catalog``, ``prepare``, or ``validate``. ``catalog`` lists
|
||||
profiles; ``prepare`` selects/copies a source into this thread's
|
||||
workspace and writes an editing brief; ``validate`` checks an edited
|
||||
HTML file and writes a JSON quality report next to it.
|
||||
theme: ``dark`` or ``light``. Use the UI-provided presentation theme when
|
||||
available; ``auto`` lets the selector use all profiles.
|
||||
content_density: ``text-heavy``, ``balanced``, or ``data-heavy``.
|
||||
required_features: Needed components such as ``line``, ``pie``,
|
||||
``radar``, ``scatter``, ``gantt``, ``table``, ``text-panels``.
|
||||
preferred_page_count: Preferred number of report pages. The agent may
|
||||
remove unused skeleton pages after preparation.
|
||||
selection_key: Stable request/thread-derived text used to vary equally
|
||||
good template choices.
|
||||
exclude_template_ids: Recently-used template ids to avoid where possible.
|
||||
template_id: Optional explicit catalog id. Omit to select automatically.
|
||||
output_name: Final safe HTML filename, e.g. ``经营月报.html``.
|
||||
page_brief: Concise summary of supplied materials and desired output.
|
||||
file_path: For ``validate`` only: current-thread HTML under workspace or
|
||||
outputs.
|
||||
data_mode: ``provided`` for factual data, ``illustrative`` when charts
|
||||
are intentionally demonstrative, or ``mixed``.
|
||||
"""
|
||||
normalized_action = (action or "").strip().lower()
|
||||
if normalized_action == "catalog":
|
||||
return json.dumps({"templates": [profile.to_dict() for profile in list_template_profiles()]}, ensure_ascii=False)
|
||||
if normalized_action == "prepare":
|
||||
return _prepare(
|
||||
runtime,
|
||||
theme=theme,
|
||||
content_density=content_density,
|
||||
required_features=required_features or [],
|
||||
preferred_page_count=preferred_page_count,
|
||||
selection_key=selection_key,
|
||||
exclude_template_ids=exclude_template_ids or [],
|
||||
template_id=template_id,
|
||||
output_name=output_name,
|
||||
page_brief=page_brief,
|
||||
)
|
||||
if normalized_action == "validate":
|
||||
return _validate(
|
||||
runtime,
|
||||
file_path=file_path,
|
||||
data_mode=data_mode,
|
||||
expected_features=required_features or [],
|
||||
)
|
||||
raise ValueError("action 仅支持 catalog、prepare、validate。")
|
||||
|
||||
|
||||
__all__ = ["page_report_template_tool"]
|
||||
+194
@@ -0,0 +1,194 @@
|
||||
import logging
|
||||
from pathlib import Path
|
||||
from typing import Annotated
|
||||
|
||||
from langchain.tools import InjectedToolCallId, ToolRuntime, tool
|
||||
from langchain_core.messages import ToolMessage
|
||||
from langgraph.config import get_config
|
||||
from langgraph.types import Command
|
||||
from langgraph.typing import ContextT
|
||||
|
||||
from deerflow.agents.thread_state import ThreadState
|
||||
from deerflow.config.paths import VIRTUAL_PATH_PREFIX, get_paths
|
||||
from deerflow.runtime.thread_paths import resolve_path_user_id
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
OUTPUTS_VIRTUAL_PREFIX = f"{VIRTUAL_PATH_PREFIX}/outputs"
|
||||
|
||||
# Maximum sibling filenames to list when reporting "file not found", to keep the
|
||||
# tool message bounded — a chatty agent can fill up its outputs/ directory and
|
||||
# we'd otherwise blow past the model's context window with the listing.
|
||||
_MAX_AVAILABLE_FILE_HINTS = 25
|
||||
|
||||
|
||||
def _get_thread_id(runtime: ToolRuntime[ContextT, ThreadState]) -> str | None:
|
||||
"""Resolve the current thread id from runtime context or RunnableConfig."""
|
||||
thread_id = runtime.context.get("thread_id") if runtime.context else None
|
||||
if thread_id:
|
||||
return thread_id
|
||||
|
||||
runtime_config = getattr(runtime, "config", None) or {}
|
||||
thread_id = runtime_config.get("configurable", {}).get("thread_id")
|
||||
if thread_id:
|
||||
return thread_id
|
||||
|
||||
try:
|
||||
return get_config().get("configurable", {}).get("thread_id")
|
||||
except RuntimeError:
|
||||
return None
|
||||
|
||||
|
||||
def _list_available_outputs(outputs_dir: Path) -> list[str]:
|
||||
"""Return up to ``_MAX_AVAILABLE_FILE_HINTS`` files under ``outputs_dir``.
|
||||
|
||||
Used to build a "did you mean ..." hint when the model presents a file that
|
||||
does not exist — a typo or a hallucinated filename was the most common
|
||||
cause of "file not found" reports in production. Returns an empty list if
|
||||
the directory itself does not exist or cannot be walked.
|
||||
"""
|
||||
if not outputs_dir.exists() or not outputs_dir.is_dir():
|
||||
return []
|
||||
try:
|
||||
files: list[str] = []
|
||||
for entry in sorted(outputs_dir.rglob("*"), key=lambda p: p.as_posix()):
|
||||
if not entry.is_file():
|
||||
continue
|
||||
try:
|
||||
rel = entry.relative_to(outputs_dir)
|
||||
except ValueError:
|
||||
continue
|
||||
files.append(rel.as_posix())
|
||||
if len(files) >= _MAX_AVAILABLE_FILE_HINTS:
|
||||
break
|
||||
return files
|
||||
except OSError as exc:
|
||||
logger.debug("Failed to enumerate %s: %s", outputs_dir, exc)
|
||||
return []
|
||||
|
||||
|
||||
def _normalize_presented_filepath(
|
||||
runtime: ToolRuntime[ContextT, ThreadState],
|
||||
filepath: str,
|
||||
) -> str:
|
||||
"""Normalize a presented file path to the `/mnt/user-data/outputs/*` contract.
|
||||
|
||||
Accepts either:
|
||||
- A virtual sandbox path such as `/mnt/user-data/outputs/report.md`
|
||||
- A host-side thread outputs path such as
|
||||
`/app/backend/.deer-flow/threads/<thread>/user-data/outputs/report.md`
|
||||
|
||||
Returns:
|
||||
The normalized virtual path.
|
||||
|
||||
Raises:
|
||||
ValueError: If runtime metadata is missing, the path is outside the
|
||||
current thread's outputs directory, or no file actually exists at
|
||||
the resolved location. The error message lists existing files in
|
||||
``outputs/`` so the agent can self-correct on its next turn
|
||||
instead of leaving the user with a blank 404 in the UI.
|
||||
"""
|
||||
if runtime.state is None:
|
||||
raise ValueError("Thread runtime state is not available")
|
||||
|
||||
thread_id = _get_thread_id(runtime)
|
||||
if not thread_id:
|
||||
raise ValueError("Thread ID is not available in runtime context or runtime config")
|
||||
|
||||
thread_data = runtime.state.get("thread_data") or {}
|
||||
outputs_path = thread_data.get("outputs_path")
|
||||
if not outputs_path:
|
||||
raise ValueError("Thread outputs path is not available in runtime state")
|
||||
|
||||
outputs_dir = Path(outputs_path).resolve()
|
||||
stripped = filepath.lstrip("/")
|
||||
virtual_prefix = VIRTUAL_PATH_PREFIX.lstrip("/")
|
||||
|
||||
if stripped == virtual_prefix or stripped.startswith(virtual_prefix + "/"):
|
||||
try:
|
||||
actual_path = get_paths().resolve_virtual_path(thread_id, filepath, user_id=resolve_path_user_id(thread_id))
|
||||
except TypeError:
|
||||
actual_path = get_paths().resolve_virtual_path(thread_id, filepath)
|
||||
else:
|
||||
actual_path = Path(filepath).expanduser().resolve()
|
||||
|
||||
try:
|
||||
relative_path = actual_path.relative_to(outputs_dir)
|
||||
except ValueError as exc:
|
||||
raise ValueError(f"Only files in {OUTPUTS_VIRTUAL_PREFIX} can be presented: {filepath}") from exc
|
||||
|
||||
# Existence + file-type check: the previous version trusted the agent
|
||||
# blindly, so any typo or "I'll create it next turn" path produced a UI
|
||||
# 404. Surfacing the failure here lets the model retry within the same
|
||||
# turn and unblocks downstream `present_files` consumers.
|
||||
if not actual_path.exists():
|
||||
available = _list_available_outputs(outputs_dir)
|
||||
if available:
|
||||
hint = "; available files: " + ", ".join(available)
|
||||
if len(available) >= _MAX_AVAILABLE_FILE_HINTS:
|
||||
hint += f", ... (showing first {_MAX_AVAILABLE_FILE_HINTS})"
|
||||
else:
|
||||
hint = "; outputs/ is empty — write the file first"
|
||||
raise ValueError(f"File does not exist: {filepath}{hint}")
|
||||
|
||||
if not actual_path.is_file():
|
||||
raise ValueError(f"Path is not a regular file: {filepath}")
|
||||
|
||||
return f"{OUTPUTS_VIRTUAL_PREFIX}/{relative_path.as_posix()}"
|
||||
|
||||
|
||||
@tool("present_files", parse_docstring=True)
|
||||
def present_file_tool(
|
||||
runtime: ToolRuntime[ContextT, ThreadState],
|
||||
filepaths: list[str],
|
||||
tool_call_id: Annotated[str, InjectedToolCallId],
|
||||
) -> Command:
|
||||
"""Make files visible to the user for viewing and rendering in the client interface.
|
||||
|
||||
When to use the present_files tool:
|
||||
|
||||
- Making any file available for the user to view, download, or interact with
|
||||
- Presenting multiple related files at once
|
||||
- After creating files that should be presented to the user
|
||||
|
||||
When NOT to use the present_files tool:
|
||||
- When you only need to read file contents for your own processing
|
||||
- For temporary or intermediate files not meant for user viewing
|
||||
|
||||
Notes:
|
||||
- You should call this tool after creating files and moving them to the `/mnt/user-data/outputs` directory.
|
||||
- This tool can be safely called in parallel with other tools. State updates are handled by a reducer to prevent conflicts.
|
||||
|
||||
Args:
|
||||
filepaths: List of absolute file paths to present to the user. **Only** files in `/mnt/user-data/outputs` can be presented.
|
||||
"""
|
||||
# Per-file try/except so a single typo doesn't drop every other artefact
|
||||
# the agent intended to present in the same turn — that pattern caused a
|
||||
# lot of confusing "where did the file go?" reports in production.
|
||||
normalized_paths: list[str] = []
|
||||
failures: list[str] = []
|
||||
for filepath in filepaths:
|
||||
try:
|
||||
normalized_paths.append(_normalize_presented_filepath(runtime, filepath))
|
||||
except ValueError as exc:
|
||||
failures.append(str(exc))
|
||||
|
||||
if not normalized_paths:
|
||||
# Nothing succeeded: the agent must self-correct, so surface a
|
||||
# tool-error message rather than silently writing an empty artifacts
|
||||
# list (which the lead agent treats as "successfully presented").
|
||||
message = "Error: " + " | ".join(failures) if failures else "Error: no files were presented"
|
||||
return Command(update={"messages": [ToolMessage(message, tool_call_id=tool_call_id)]})
|
||||
|
||||
if failures:
|
||||
message = "Successfully presented files: " + ", ".join(normalized_paths) + " | Skipped: " + " | ".join(failures)
|
||||
else:
|
||||
message = "Successfully presented files"
|
||||
|
||||
# The merge_artifacts reducer will handle merging and deduplication
|
||||
return Command(
|
||||
update={
|
||||
"artifacts": normalized_paths,
|
||||
"messages": [ToolMessage(message, tool_call_id=tool_call_id)],
|
||||
},
|
||||
)
|
||||
+82
@@ -0,0 +1,82 @@
|
||||
"""read_peer_delivery —— 圆桌席位「按需读取前序席位**完整交付**」的只读工具。
|
||||
|
||||
背景:圆桌每个席位是独立 thread(独立 sandbox),彼此隔离。默认情况下,一个席位只能
|
||||
从跨席位广播里看到前序席位的**截断摘要**(≤1500 字)。当席位识别到自己需要某个前序
|
||||
席位的**全文**时,调用本工具按席位名取回完整交付。
|
||||
|
||||
数据来源:全文由**网关层**(``app.gateway``)在发起本席位 run 时,注入到
|
||||
``runtime.context["roundtable_peer_deliveries"]`` —— 一个
|
||||
``[{"name": <席位显示名>, "content": <完整交付正文>}, ...]`` 列表。本工具**只读该上下文
|
||||
dict**,不跨 thread、不碰 sandbox、不发网络请求,因此完全在 ``deerflow.*`` 内(不违反
|
||||
harness→app 导入防火墙)。非圆桌场景下该上下文为空,工具返回「无」。
|
||||
|
||||
「传摘要按需传全文」:完整交付**只在席位真正调用本工具时**才进入它的 LLM 上下文,平时
|
||||
只有摘要,既省 token 又满足「需要时能拿全文」。详见
|
||||
``frontend-web/docs/roundtable-dag-orchestration.md`` §12.9。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
|
||||
from langchain.tools import ToolRuntime, tool
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
_CTX_KEY = "roundtable_peer_deliveries"
|
||||
|
||||
|
||||
def _peer_deliveries(runtime: ToolRuntime | None) -> list[dict]:
|
||||
"""从 runtime.context 取出网关注入的前序席位完整交付列表(缺失/非法时返回 [])。"""
|
||||
if runtime is None:
|
||||
return []
|
||||
ctx = getattr(runtime, "context", None)
|
||||
if not ctx:
|
||||
return []
|
||||
try:
|
||||
peers = ctx.get(_CTX_KEY)
|
||||
except Exception:
|
||||
return []
|
||||
if not isinstance(peers, list):
|
||||
return []
|
||||
return [p for p in peers if isinstance(p, dict)]
|
||||
|
||||
|
||||
@tool("read_peer_delivery", parse_docstring=True)
|
||||
def read_peer_delivery_tool(runtime: ToolRuntime, seat_name: str = "") -> str:
|
||||
"""Read another roundtable seat's FULL deliverable on demand.
|
||||
|
||||
In a multi-agent roundtable you (a seat) normally only see **truncated
|
||||
summaries** of earlier seats' deliverables. When you decide you genuinely
|
||||
need the **complete text** of a specific earlier seat (e.g. to build on its
|
||||
detailed data/conclusions), call this tool with that seat's name to fetch
|
||||
its full deliverable. Prefer the summaries you already have; only call this
|
||||
when the summary is insufficient.
|
||||
|
||||
Args:
|
||||
seat_name: The earlier seat's display name (the Chinese name shown in
|
||||
the summaries, e.g. "情报收集"). Leave empty to list which peers'
|
||||
full deliverables are available to read.
|
||||
"""
|
||||
peers = _peer_deliveries(runtime)
|
||||
if not peers:
|
||||
return "(当前没有可读取的前序席位完整交付。请直接基于你已有的上下文与摘要完成交付。)"
|
||||
|
||||
names = [str(p.get("name") or "") for p in peers if p.get("name")]
|
||||
query = (seat_name or "").strip()
|
||||
if not query:
|
||||
return (
|
||||
"可读取**完整交付**的前序席位:" + "、".join(names) + "。\n"
|
||||
"需要哪个席位的全文,就再次调用 read_peer_delivery 并把它的名称传给 seat_name。"
|
||||
)
|
||||
|
||||
ql = query.lower()
|
||||
# 精确匹配(忽略大小写)优先,其次子串互含(容忍模型给「情报收集席位」这类带后缀的名)。
|
||||
for p in peers:
|
||||
if str(p.get("name") or "").lower() == ql:
|
||||
return str(p.get("content") or "(该席位交付为空。)")
|
||||
for p in peers:
|
||||
nm = str(p.get("name") or "")
|
||||
if nm and (ql in nm.lower() or nm.lower() in ql):
|
||||
return str(p.get("content") or "(该席位交付为空。)")
|
||||
return f"未找到名为「{query}」的前序席位。可读取的有:" + "、".join(names) + "。"
|
||||
+149
@@ -0,0 +1,149 @@
|
||||
"""Tool for managing user scheduled agent tasks."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from typing import Any, Literal
|
||||
|
||||
from langchain.tools import ToolRuntime, tool
|
||||
from langgraph.typing import ContextT
|
||||
|
||||
from deerflow.agents.thread_state import ThreadState
|
||||
from deerflow.runtime.scheduler import get_scheduled_task_service
|
||||
from deerflow.runtime.user_context import get_current_user
|
||||
|
||||
|
||||
def _runtime_context(runtime: ToolRuntime[ContextT, ThreadState]) -> dict[str, Any]:
|
||||
context = getattr(runtime, "context", None)
|
||||
merged = dict(context or {}) if isinstance(context, dict) else {}
|
||||
config = getattr(runtime, "config", None)
|
||||
if isinstance(config, dict):
|
||||
configurable = config.get("configurable")
|
||||
if isinstance(configurable, dict):
|
||||
for key, value in configurable.items():
|
||||
merged.setdefault(key, value)
|
||||
return merged
|
||||
|
||||
|
||||
@tool("scheduled_task", parse_docstring=True)
|
||||
async def scheduled_task_tool(
|
||||
runtime: ToolRuntime[ContextT, ThreadState],
|
||||
action: Literal["create", "list", "update", "delete", "pause", "resume", "trigger"],
|
||||
name: str | None = None,
|
||||
schedule: str | None = None,
|
||||
prompt: str | None = None,
|
||||
task_id: str | None = None,
|
||||
timezone: str | None = None,
|
||||
enabled: bool | None = None,
|
||||
execution_agent_name: str | None = None,
|
||||
) -> str:
|
||||
"""Create, list, update, delete, pause, resume, or trigger scheduled tasks.
|
||||
|
||||
Use this tool whenever the user asks to run something later or repeatedly,
|
||||
such as daily reports, weekly inspections, reminders, audits, or recurring
|
||||
research. Tasks can be created from any chat or custom agent. The scheduled
|
||||
execution reuses the current custom agent by default, including its skills
|
||||
and tool groups, but the final output is delivered to the user's dedicated
|
||||
scheduled-task conversation.
|
||||
|
||||
Args:
|
||||
action: Operation to perform: create, list, update, delete, pause, resume, or trigger.
|
||||
name: Human-friendly task name. Required for create.
|
||||
schedule: Natural language schedule or cron expression. Examples: "every day at 9am", "每天9点", "0 9 * * *".
|
||||
prompt: The instruction to run on schedule. Required for create.
|
||||
task_id: Existing task id for update, delete, pause, resume, or trigger.
|
||||
timezone: IANA timezone, e.g. "Asia/Shanghai". Defaults to UTC if omitted.
|
||||
enabled: Whether the task is enabled when updating.
|
||||
execution_agent_name: Optional custom agent name to run this task with. Defaults to the current agent.
|
||||
"""
|
||||
user = get_current_user()
|
||||
if user is None:
|
||||
return "Error: scheduled tasks require an authenticated user."
|
||||
|
||||
ctx = _runtime_context(runtime)
|
||||
if ctx.get("is_scheduled_run"):
|
||||
return "Error: scheduled task management is disabled while a scheduled task is running."
|
||||
|
||||
service = get_scheduled_task_service()
|
||||
user_id = str(user.id)
|
||||
current_agent = ctx.get("agent_name")
|
||||
if not isinstance(current_agent, str):
|
||||
current_agent = None
|
||||
|
||||
try:
|
||||
if action == "list":
|
||||
tasks = await service.list_tasks(user_id)
|
||||
return json.dumps({"tasks": tasks}, ensure_ascii=False, default=str)
|
||||
|
||||
if action == "create":
|
||||
if not prompt or not prompt.strip():
|
||||
return "Error: prompt is required when creating a scheduled task."
|
||||
if not schedule or not schedule.strip():
|
||||
return "Error: schedule is required when creating a scheduled task."
|
||||
execution_context = {
|
||||
key: value
|
||||
for key, value in ctx.items()
|
||||
if key
|
||||
in {
|
||||
"agent_name",
|
||||
"model_name",
|
||||
"mode",
|
||||
"thinking_enabled",
|
||||
"reasoning_effort",
|
||||
"is_plan_mode",
|
||||
"subagent_enabled",
|
||||
"max_concurrent_subagents",
|
||||
}
|
||||
}
|
||||
task = await service.create_task(
|
||||
user_id=user_id,
|
||||
name=(name or "Scheduled task").strip(),
|
||||
prompt=prompt,
|
||||
schedule=schedule,
|
||||
timezone=timezone,
|
||||
source_thread_id=ctx.get("thread_id") if isinstance(ctx.get("thread_id"), str) else None,
|
||||
source_agent_name=current_agent,
|
||||
execution_agent_name=execution_agent_name or current_agent,
|
||||
execution_context=execution_context,
|
||||
)
|
||||
return json.dumps({"created": True, "task": task}, ensure_ascii=False, default=str)
|
||||
|
||||
if not task_id:
|
||||
return f"Error: task_id is required for action={action}."
|
||||
|
||||
if action == "update":
|
||||
update: dict[str, Any] = {}
|
||||
if name is not None:
|
||||
update["name"] = name
|
||||
if prompt is not None:
|
||||
update["prompt"] = prompt
|
||||
if schedule is not None:
|
||||
update["schedule"] = schedule
|
||||
if timezone is not None:
|
||||
update["timezone"] = timezone
|
||||
if enabled is not None:
|
||||
update["enabled"] = enabled
|
||||
if execution_agent_name is not None:
|
||||
update["execution_agent_name"] = execution_agent_name
|
||||
task = await service.update_task(user_id, task_id, update)
|
||||
return json.dumps({"updated": task is not None, "task": task}, ensure_ascii=False, default=str)
|
||||
|
||||
if action == "delete":
|
||||
deleted = await service.delete_task(user_id, task_id)
|
||||
return json.dumps({"deleted": deleted}, ensure_ascii=False)
|
||||
|
||||
if action == "pause":
|
||||
task = await service.pause_task(user_id, task_id)
|
||||
return json.dumps({"paused": task is not None, "task": task}, ensure_ascii=False, default=str)
|
||||
|
||||
if action == "resume":
|
||||
task = await service.resume_task(user_id, task_id)
|
||||
return json.dumps({"resumed": task is not None, "task": task}, ensure_ascii=False, default=str)
|
||||
|
||||
if action == "trigger":
|
||||
task = await service.trigger_task(user_id, task_id)
|
||||
return json.dumps({"triggered": task is not None, "task": task}, ensure_ascii=False, default=str)
|
||||
except Exception as exc:
|
||||
return f"Error: failed to manage scheduled task: {exc}"
|
||||
|
||||
return f"Error: unsupported action={action}."
|
||||
+75
@@ -0,0 +1,75 @@
|
||||
import logging
|
||||
|
||||
import yaml
|
||||
from langchain_core.messages import ToolMessage
|
||||
from langchain_core.tools import tool
|
||||
from langgraph.prebuilt import ToolRuntime
|
||||
from langgraph.types import Command
|
||||
|
||||
from deerflow.config.agents_config import validate_agent_id
|
||||
from deerflow.config.paths import get_paths
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
@tool
|
||||
def setup_agent(
|
||||
soul: str,
|
||||
description: str,
|
||||
runtime: ToolRuntime,
|
||||
name: str | None = None,
|
||||
skills: list[str] | None = None,
|
||||
) -> Command:
|
||||
"""Setup the custom DeerFlow agent.
|
||||
|
||||
Args:
|
||||
soul: Full SOUL.md content defining the agent's personality and behavior.
|
||||
description: One-line description of what the agent does.
|
||||
name: Optional human-readable display name for the agent. If omitted,
|
||||
the agent's stable id is used as the display name.
|
||||
skills: Optional list of skill names this agent should use. None or empty means no skills. Maximum 5 skills allowed.
|
||||
"""
|
||||
|
||||
agent_name: str | None = (runtime.context.get("agent_id") or runtime.context.get("agent_name")) if runtime.context else None
|
||||
agent_dir = None
|
||||
is_new_dir = False
|
||||
|
||||
try:
|
||||
agent_name = validate_agent_id(agent_name)
|
||||
paths = get_paths()
|
||||
agent_dir = paths.agent_dir(agent_name) if agent_name else paths.base_dir
|
||||
is_new_dir = not agent_dir.exists()
|
||||
agent_dir.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
if agent_name:
|
||||
# If agent_name is provided, we are creating a custom agent in the agents/ directory
|
||||
display_name = (name or "").strip() or agent_name
|
||||
config_data: dict = {"id": agent_name, "name": display_name}
|
||||
if description:
|
||||
config_data["description"] = description
|
||||
if skills is not None:
|
||||
config_data["skills"] = skills[:5]
|
||||
|
||||
config_file = agent_dir / "config.yaml"
|
||||
with open(config_file, "w", encoding="utf-8") as f:
|
||||
yaml.dump(config_data, f, default_flow_style=False, allow_unicode=True)
|
||||
|
||||
soul_file = agent_dir / "SOUL.md"
|
||||
soul_file.write_text(soul, encoding="utf-8")
|
||||
|
||||
logger.info(f"[agent_creator] Created agent '{agent_name}' at {agent_dir}")
|
||||
return Command(
|
||||
update={
|
||||
"created_agent_name": agent_name,
|
||||
"messages": [ToolMessage(content=f"Agent '{agent_name}' created successfully!", tool_call_id=runtime.tool_call_id)],
|
||||
}
|
||||
)
|
||||
|
||||
except Exception as e:
|
||||
import shutil
|
||||
|
||||
if agent_name and is_new_dir and agent_dir is not None and agent_dir.exists():
|
||||
# Cleanup the custom agent directory only if it was newly created during this call
|
||||
shutil.rmtree(agent_dir)
|
||||
logger.error(f"[agent_creator] Failed to create agent '{agent_name}': {e}", exc_info=True)
|
||||
return Command(update={"messages": [ToolMessage(content=f"Error: {e}", tool_call_id=runtime.tool_call_id)]})
|
||||
+55
@@ -0,0 +1,55 @@
|
||||
"""报告结构「智能新增」用的提交工具。
|
||||
|
||||
与 ``setup_writing`` 同构:模型在几轮对话里问清用户想要的报告结构后,调用本工具把建议字段
|
||||
「提交」出来。实际总是被 ``SetupReportStructureApprovalMiddleware`` 在 ``after_model``
|
||||
拦截(不真正执行)——拦截后把字段打包进审批 ToolMessage,前端据此回填右侧表单。
|
||||
|
||||
函数体只是兜底:万一未被拦截,也只回一句确认、不落任何盘。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
|
||||
from langchain_core.messages import ToolMessage
|
||||
from langchain_core.tools import tool
|
||||
from langgraph.prebuilt import ToolRuntime
|
||||
from langgraph.types import Command
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
@tool
|
||||
def setup_report_structure(
|
||||
title: str,
|
||||
content: str,
|
||||
runtime: ToolRuntime,
|
||||
name: str | None = None,
|
||||
structure_mode: str | None = None,
|
||||
retrieval_directions: list[str] | None = None,
|
||||
retrieval_skills: list[str] | None = None,
|
||||
) -> Command:
|
||||
"""把与用户聊清的报告结构配置提交给前端表单(不直接入库)。
|
||||
|
||||
Args:
|
||||
title: 报告结构标题(必填,短、可展示,如「市场分析报告模板」)。
|
||||
content: **已与用户确认的报告大纲全文**,使用 Markdown 标题层级
|
||||
(`#` / `##` / `###`),只写结构与小节要点,不写正文。
|
||||
name: 一句话描述这套结构的适用场景(可选)。
|
||||
structure_mode: 结构约束。``fixed`` = 固定大纲(按章节逐一成文,不得改写/合并/省略);
|
||||
``adaptive`` = 弹性大纲(可按材料合并或省略无依据小节)。不确定时用 ``adaptive``。
|
||||
retrieval_directions: 检索方向列表(可选)。每项是一个拆词维度,例如「各品牌汽车销量」,
|
||||
**不是**直接拿去搜索的关键词。用户没提就留空。
|
||||
retrieval_skills: 检索来源技能 name 列表(可选,hyphen-case 文件夹 id)。
|
||||
只填用户明确点名、且出现在系统给定技能列表里的项;不确定就留空,交给用户在表单里选。
|
||||
"""
|
||||
logger.info("[setup_report_structure] proposed config submitted (intercepted by approval middleware)")
|
||||
return Command(
|
||||
update={
|
||||
"messages": [
|
||||
ToolMessage(
|
||||
content="报告结构已生成,请在对话里确认后应用到右侧表单,再点保存。",
|
||||
tool_call_id=runtime.tool_call_id,
|
||||
)
|
||||
]
|
||||
}
|
||||
)
|
||||
+59
@@ -0,0 +1,59 @@
|
||||
"""写作配置助手用的提交工具。
|
||||
|
||||
与 ``setup_agent`` 同构:模型在「写作配置 Q&A」里与用户聊清需求后,调用本工具把建议的
|
||||
写作配置「提交」出来。实际它总是被 ``SetupWritingApprovalMiddleware`` 在 ``after_model``
|
||||
拦截(不真正执行)——拦截后把建议字段打包进审批 ToolMessage,前端据此回填左侧写作表单。
|
||||
|
||||
因此本工具的函数体基本是兜底:万一未被拦截(如审批被预先放行),也只回一句确认、不落任何盘。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
|
||||
from langchain_core.messages import ToolMessage
|
||||
from langchain_core.tools import tool
|
||||
from langgraph.prebuilt import ToolRuntime
|
||||
from langgraph.types import Command
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
@tool
|
||||
def setup_writing(
|
||||
user_intent: str,
|
||||
runtime: ToolRuntime,
|
||||
article_type: str | None = None,
|
||||
word_count_target: int | None = None,
|
||||
target_audience: str | None = None,
|
||||
writing_mode: str | None = None,
|
||||
material_source: str | None = None,
|
||||
outline: str | None = None,
|
||||
article_type_detail: str | None = None,
|
||||
) -> Command:
|
||||
"""把与用户聊清的写作配置提交给前端表单(不直接开始写作)。
|
||||
|
||||
Args:
|
||||
user_intent: 用户的写作意图(精炼成一句话的写作目标)。
|
||||
article_type: 文章类型。优先填系统给定的合法类型 key;若已有类型都不贴切,可**自拟一个新的
|
||||
文章类型**——此时填一个简短的中文类型名(如「政策解读」「人物特写」),并在
|
||||
``article_type_detail`` 里说明该类型特征。不确定可留空。
|
||||
word_count_target: 目标字数(正整数)。
|
||||
target_audience: 目标读者(如「行业专家」「普通读者」)。
|
||||
writing_mode: 写作模式,'strict'(严格依据素材)或 'loose'(可结合通用知识)。
|
||||
material_source: 素材来源,'knowledge_base'(知识库)或 'skill'(技能检索)。
|
||||
outline: **已与用户确认的大纲全文**(保留其层级与标题)。本工具在用户确认大纲后调用,
|
||||
故通常应带上这份大纲;用户未提供/未确认大纲时才留空。
|
||||
article_type_detail: 仅当 ``article_type`` 是**新类型(不在已有列表里)**时填写:用一句话说明
|
||||
这个类型的写作侧重/特征(如「以政策原文为锚、逐条拆解影响并给出执行建议」)。命中已有类型时留空。
|
||||
"""
|
||||
logger.info("[setup_writing] proposed writing config submitted (intercepted by approval middleware)")
|
||||
return Command(
|
||||
update={
|
||||
"messages": [
|
||||
ToolMessage(
|
||||
content="写作配置已生成,请在右侧确认后应用到表单,或直接开始写作。",
|
||||
tool_call_id=runtime.tool_call_id,
|
||||
)
|
||||
]
|
||||
}
|
||||
)
|
||||
+390
@@ -0,0 +1,390 @@
|
||||
"""skill_view and skill_list — read-only tools for agent skill introspection."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import logging
|
||||
|
||||
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.
|
||||
|
||||
Custom agents pass their id via either the ``context`` dict or the
|
||||
``configurable`` section of the LangGraph runtime config. The default
|
||||
lead agent runs without an explicit agent_id — callers should treat
|
||||
a None return as "no per-agent skills filter applies".
|
||||
"""
|
||||
if runtime is None:
|
||||
return None
|
||||
try:
|
||||
if getattr(runtime, "context", None):
|
||||
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):
|
||||
configurable = cfg.get("configurable", {})
|
||||
cid = configurable.get("agent_id") or configurable.get("agent_name")
|
||||
if cid:
|
||||
return str(cid)
|
||||
except Exception:
|
||||
return None
|
||||
return None
|
||||
|
||||
|
||||
def _load_agent_skill_whitelist(agent_id: str | None, extra_skills: list[str] | None = None) -> set[str] | None:
|
||||
"""Return the explicit skill name set declared in an agent's config.yaml.
|
||||
|
||||
Semantics:
|
||||
- ``None`` returned → no agent_id, or the agent's on-disk config is
|
||||
missing entirely — caller should fall back to "all skills visible"
|
||||
(default lead agent behavior).
|
||||
- ``set()`` (empty) → custom agent with ``skills: []`` declared **or**
|
||||
with no ``skills`` key at all — visibility is intentionally empty.
|
||||
This mirrors the prompt layer (``agents_config.AgentConfig.skills``:
|
||||
``None``/``[]`` both mean "no skills" for custom agents), so an agent
|
||||
whose config omits ``skills`` can no longer enumerate every skill
|
||||
through this tool.
|
||||
- Non-empty set → only these names are visible to this agent.
|
||||
|
||||
``extra_skills`` only widens the **deep-research collector** allowlist
|
||||
for one run (report-structure 检索来源). Other agents ignore it.
|
||||
"""
|
||||
if not agent_id:
|
||||
return None
|
||||
try:
|
||||
from deerflow.config.agents_config import load_agent_config
|
||||
|
||||
cfg = load_agent_config(agent_id)
|
||||
if cfg is None:
|
||||
return None
|
||||
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
|
||||
|
||||
if extra_skills:
|
||||
from deerflow.agents.deep_research.retrieval import merge_collector_skill_allowlist
|
||||
|
||||
merged = merge_collector_skill_allowlist(agent_id, list(allowed), extra_skills)
|
||||
return set(merged or [])
|
||||
return allowed
|
||||
|
||||
|
||||
def _resolve_extra_skills(runtime: ToolRuntime | None) -> list[str]:
|
||||
"""Extra skill names from this run's context (collector 检索来源)."""
|
||||
if runtime is None:
|
||||
return []
|
||||
try:
|
||||
from deerflow.agents.deep_research.retrieval import runtime_extra_skills
|
||||
|
||||
if getattr(runtime, "context", None):
|
||||
extras = runtime_extra_skills(runtime.context)
|
||||
if extras:
|
||||
return extras
|
||||
cfg = getattr(runtime, "config", None)
|
||||
if isinstance(cfg, dict):
|
||||
return runtime_extra_skills(cfg.get("configurable", {}) or {})
|
||||
except Exception:
|
||||
return []
|
||||
return []
|
||||
|
||||
|
||||
def _resolve_effective_user_id() -> str | None:
|
||||
"""当前请求/线程绑定的用户 id;解析失败时返回 None。"""
|
||||
try:
|
||||
from deerflow.runtime.user_context import get_effective_user_id
|
||||
|
||||
return get_effective_user_id()
|
||||
except Exception:
|
||||
logger.debug("Failed to resolve effective user id for skill_list", exc_info=True)
|
||||
return None
|
||||
|
||||
|
||||
def _load_owned_skill_names(user_id: str | None) -> set[str] | None:
|
||||
"""返回 ``owner_user_id == user_id`` 的自定义技能名集合。
|
||||
|
||||
用于默认 lead agent 的可见性过滤:只算"用户自己拥有的"自定义技能,不含
|
||||
其他用户发布的。返回 ``None`` 表示 ``SkillStore`` 不可用(未配置数据库
|
||||
等)—— 调用方应降级为"放行全部自定义技能",避免离线无库部署下技能凭空
|
||||
消失。
|
||||
"""
|
||||
if not user_id:
|
||||
return None
|
||||
try:
|
||||
from deerflow.persistence.engine import get_session_factory, run_db_blocking
|
||||
from deerflow.persistence.skills import make_skill_store
|
||||
|
||||
factory = get_session_factory()
|
||||
if factory is None:
|
||||
return None
|
||||
store = make_skill_store(factory)
|
||||
records = run_db_blocking(store.list_visible(user_id))
|
||||
return {r["name"] for r in records if r.get("owner_user_id") == user_id}
|
||||
except Exception:
|
||||
logger.debug("Failed to load owned skill names for skill_list filter", exc_info=True)
|
||||
return None
|
||||
|
||||
|
||||
def skill_view_impl(name: str, agent_id: str | None, extra_skills: list[str] | None = None) -> str:
|
||||
"""Read a skill's SKILL.md, honoring the agent's config.yaml whitelist.
|
||||
|
||||
Custom agents may only read skills on their whitelist — same filter as
|
||||
``skill_list``, so a restricted agent cannot bypass its allowlist by
|
||||
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
|
||||
|
||||
allowed = _load_agent_skill_whitelist(agent_id, extra_skills)
|
||||
if allowed is not None and name not in allowed:
|
||||
return f"Skill '{name}' not found."
|
||||
|
||||
storage = get_or_new_skill_storage()
|
||||
try:
|
||||
if storage.custom_skill_exists(name):
|
||||
content = storage.read_custom_skill(name)
|
||||
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
|
||||
if not path.exists():
|
||||
return f"Skill '{name}' not found."
|
||||
content = path.read_text(encoding="utf-8")
|
||||
else:
|
||||
return f"Skill '{name}' not found."
|
||||
except Exception as e:
|
||||
logger.debug("skill_view failed for %r: %s", name, e)
|
||||
return f"Error reading skill '{name}': {e}"
|
||||
|
||||
try:
|
||||
bump_view(name)
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
return content
|
||||
|
||||
|
||||
@tool("skill_view")
|
||||
def skill_view_tool(name: str, runtime: ToolRuntime) -> str:
|
||||
"""Read the full SKILL.md content of a skill by name.
|
||||
|
||||
Args:
|
||||
name: The skill name (hyphen-case, e.g. 'my-skill').
|
||||
"""
|
||||
return skill_view_impl(name, _resolve_active_agent_id(runtime), _resolve_extra_skills(runtime))
|
||||
|
||||
|
||||
def _resolve_skills_container_base_path() -> str:
|
||||
"""容器内技能挂载根路径(用于回传 location,供 agent read_file)。"""
|
||||
try:
|
||||
from deerflow.config import get_app_config
|
||||
|
||||
return get_app_config().skills.container_path
|
||||
except Exception:
|
||||
return "/mnt/skills"
|
||||
|
||||
|
||||
def _score_skill(query_terms: list[str], haystack: str) -> int:
|
||||
"""对单个技能按关键词命中计分(纯关键词、离线、确定性)。"""
|
||||
score = 0
|
||||
for term in query_terms:
|
||||
if term and term in haystack:
|
||||
score += 1
|
||||
return score
|
||||
|
||||
|
||||
def search_skills_impl(query: str, agent_id: str | None, top_n: int = 5, extra_skills: list[str] | None = None) -> str:
|
||||
"""按关键词检索可用技能,返回 top-N 的 name/description/category/location。
|
||||
|
||||
与 ``skill_list`` 共享可见性过滤(自定义 agent 走白名单;默认 lead agent 只
|
||||
暴露未归档且内置或属于当前用户的技能),并只检索**已启用**的技能 —— 它是
|
||||
"技能压缩"开启后,agent 调出被压缩(非常驻)技能的主要入口。匹配字段为技能
|
||||
名与描述。
|
||||
"""
|
||||
import re
|
||||
|
||||
from deerflow.skills.storage import get_or_new_skill_storage
|
||||
from deerflow.skills.types import SkillCategory
|
||||
from deerflow.skills.usage import STATE_ARCHIVED, all_entries
|
||||
|
||||
query = (query or "").strip()
|
||||
if not query:
|
||||
return "search_skills: empty query. Provide a short keyword query describing the task."
|
||||
|
||||
terms = [t for t in re.findall(r"\w+", query.lower()) if t]
|
||||
# 整串也作为一个匹配项,兼顾中文等不被 \w+ 切分出有意义 token 的查询。
|
||||
whole = query.lower()
|
||||
if whole and whole not in terms:
|
||||
terms.append(whole)
|
||||
|
||||
allowed = _load_agent_skill_whitelist(agent_id, extra_skills)
|
||||
owned: set[str] | None = None
|
||||
if allowed is None:
|
||||
owned = _load_owned_skill_names(_resolve_effective_user_id())
|
||||
|
||||
try:
|
||||
top_n = max(1, min(int(top_n or 5), 50))
|
||||
except (TypeError, ValueError):
|
||||
top_n = 5
|
||||
|
||||
try:
|
||||
storage = get_or_new_skill_storage()
|
||||
skills = storage.load_skills(enabled_only=True)
|
||||
usage = all_entries()
|
||||
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:
|
||||
continue
|
||||
else:
|
||||
if entry.get("state") == STATE_ARCHIVED:
|
||||
continue
|
||||
if skill.category == SkillCategory.CUSTOM and owned is not None and skill.name not in owned:
|
||||
continue
|
||||
haystack = f"{skill.name} {skill.description}".lower()
|
||||
score = _score_skill(terms, haystack)
|
||||
if score <= 0:
|
||||
continue
|
||||
scored.append((
|
||||
score,
|
||||
{
|
||||
"name": skill.name,
|
||||
"description": skill.description,
|
||||
"category": skill.category.value if hasattr(skill.category, "value") else str(skill.category),
|
||||
"location": skill.get_container_file_path(base_path),
|
||||
},
|
||||
))
|
||||
scored.sort(key=lambda x: x[0], reverse=True)
|
||||
results = [item for _, item in scored[:top_n]]
|
||||
if not results:
|
||||
return f"No skills matched '{query}'. Try a broader keyword, or call skill_list to browse everything available."
|
||||
return json.dumps(results, ensure_ascii=False, indent=2)
|
||||
except Exception as e:
|
||||
logger.debug("search_skills failed: %s", e)
|
||||
return f"Error searching skills: {e}"
|
||||
|
||||
|
||||
@tool("search_skills")
|
||||
def search_skills_tool(query: str, runtime: ToolRuntime) -> str:
|
||||
"""Search available skills by keyword and return the best matches.
|
||||
|
||||
Use this to discover skills that are not already described in full in your
|
||||
system prompt. Returns a JSON array of matches, each with `name`,
|
||||
`description`, `category`, and `location` — then `read_file` the `location`
|
||||
of the most relevant match and follow its SKILL.md instructions.
|
||||
|
||||
Args:
|
||||
query: A short keyword query describing the task (e.g. 'pdf table extract').
|
||||
"""
|
||||
return search_skills_impl(query, _resolve_active_agent_id(runtime), extra_skills=_resolve_extra_skills(runtime))
|
||||
|
||||
|
||||
@tool("skill_list")
|
||||
def skill_list_tool(runtime: ToolRuntime) -> str:
|
||||
"""List skills available to this agent, with metadata and usage stats.
|
||||
Does NOT read SKILL.md content.
|
||||
|
||||
For a **custom agent**, the result is filtered to skills explicitly
|
||||
declared in the agent's ``.deer-flow/agents/{agent_id}/config.yaml``
|
||||
under the ``skills:`` field — the agent only sees what it was wired to
|
||||
use.
|
||||
|
||||
For the **default lead agent** (no agent_id in runtime), the result is
|
||||
filtered to non-archived skills that are either built-in (public) or
|
||||
owned by the current user. Other users' published custom skills and
|
||||
archived skills are excluded.
|
||||
|
||||
Returns a JSON array with fields: name, description, category, enabled,
|
||||
state, use_count, view_count, patch_count, last_activity_at, pinned,
|
||||
source.
|
||||
"""
|
||||
return skill_list_impl(_resolve_active_agent_id(runtime), _resolve_extra_skills(runtime))
|
||||
|
||||
|
||||
def skill_list_impl(agent_id: str | None, extra_skills: list[str] | None = None) -> str:
|
||||
"""List skills visible to ``agent_id`` (None = default lead agent)."""
|
||||
from deerflow.skills.storage import get_or_new_skill_storage
|
||||
from deerflow.skills.types import SkillCategory
|
||||
from deerflow.skills.usage import STATE_ARCHIVED, all_entries, latest_activity_at
|
||||
|
||||
allowed = _load_agent_skill_whitelist(agent_id, extra_skills)
|
||||
|
||||
# 默认 lead agent 没有 per-agent 白名单 —— 改为只暴露"未归档"且"内置或属于
|
||||
# 当前用户"的技能。owned 为 None 表示 SkillStore 不可用,降级放行全部自定义
|
||||
# 技能(见 _load_owned_skill_names)。
|
||||
owned: set[str] | None = None
|
||||
if allowed is None:
|
||||
owned = _load_owned_skill_names(_resolve_effective_user_id())
|
||||
|
||||
try:
|
||||
storage = get_or_new_skill_storage()
|
||||
skills = storage.load_skills(enabled_only=False)
|
||||
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 白名单过滤。
|
||||
if skill.name not in allowed:
|
||||
continue
|
||||
else:
|
||||
# 默认 agent:跳过已归档技能。
|
||||
if entry.get("state") == STATE_ARCHIVED:
|
||||
continue
|
||||
# 自定义技能仅当属于当前用户时可见;内置 public 技能始终可见。
|
||||
if skill.category == SkillCategory.CUSTOM and owned is not None and skill.name not in owned:
|
||||
continue
|
||||
result.append({
|
||||
"name": skill.name,
|
||||
"description": skill.description,
|
||||
"category": skill.category.value if hasattr(skill.category, "value") else str(skill.category),
|
||||
"enabled": skill.enabled,
|
||||
"state": entry.get("state", "active"),
|
||||
"use_count": entry.get("use_count", 0),
|
||||
"view_count": entry.get("view_count", 0),
|
||||
"patch_count": entry.get("patch_count", 0),
|
||||
"last_activity_at": latest_activity_at(skill.name),
|
||||
"pinned": entry.get("pinned", False),
|
||||
"source": entry.get("source", "upload"),
|
||||
})
|
||||
return json.dumps(result, ensure_ascii=False, indent=2)
|
||||
except Exception as e:
|
||||
logger.debug("skill_list failed: %s", e)
|
||||
return f"Error listing skills: {e}"
|
||||
+308
@@ -0,0 +1,308 @@
|
||||
"""Task tool for delegating work to subagents."""
|
||||
|
||||
import asyncio
|
||||
import logging
|
||||
import uuid
|
||||
from dataclasses import replace
|
||||
from typing import TYPE_CHECKING, Annotated, Any, cast
|
||||
|
||||
from langchain.tools import InjectedToolCallId, ToolRuntime, tool
|
||||
from langgraph.config import get_stream_writer
|
||||
from langgraph.typing import ContextT
|
||||
|
||||
from deerflow.agents.thread_state import ThreadState
|
||||
from deerflow.config import get_app_config
|
||||
from deerflow.sandbox.security import LOCAL_BASH_SUBAGENT_DISABLED_MESSAGE, is_host_bash_allowed
|
||||
from deerflow.subagents import SubagentExecutor, get_available_subagent_names, get_subagent_config
|
||||
from deerflow.subagents.config import resolve_subagent_model_name
|
||||
from deerflow.subagents.executor import (
|
||||
SubagentStatus,
|
||||
cleanup_background_task,
|
||||
get_background_task_result,
|
||||
request_cancel_background_task,
|
||||
)
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from deerflow.config.app_config import AppConfig
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def _get_runtime_app_config(runtime: Any) -> "AppConfig | None":
|
||||
context = getattr(runtime, "context", None)
|
||||
if isinstance(context, dict):
|
||||
app_config = context.get("app_config")
|
||||
if app_config is not None:
|
||||
return cast("AppConfig", app_config)
|
||||
return None
|
||||
|
||||
|
||||
def _merge_skill_allowlists(parent: list[str] | None, child: list[str] | None) -> list[str] | None:
|
||||
"""Return the effective subagent skill allowlist under the parent policy."""
|
||||
if parent is None:
|
||||
return child
|
||||
if child is None:
|
||||
return list(parent)
|
||||
|
||||
parent_set = set(parent)
|
||||
return [skill for skill in child if skill in parent_set]
|
||||
|
||||
|
||||
@tool("task", parse_docstring=True)
|
||||
async def task_tool(
|
||||
runtime: ToolRuntime[ContextT, ThreadState],
|
||||
description: str,
|
||||
prompt: str,
|
||||
subagent_type: str,
|
||||
tool_call_id: Annotated[str, InjectedToolCallId],
|
||||
max_turns: int | None = None,
|
||||
) -> str:
|
||||
"""Delegate a task to a specialized subagent that runs in its own context.
|
||||
|
||||
Subagents help you:
|
||||
- Preserve context by keeping exploration and implementation separate
|
||||
- Handle complex multi-step tasks autonomously
|
||||
- Execute commands or operations in isolated contexts
|
||||
|
||||
Built-in subagent types:
|
||||
- **general-purpose**: A capable agent for complex, multi-step tasks that require
|
||||
both exploration and action. Use when the task requires complex reasoning,
|
||||
multiple dependent steps, or would benefit from isolated context.
|
||||
- **bash**: Command execution specialist for running bash commands. This is only
|
||||
available when host bash is explicitly allowed or when using an isolated shell
|
||||
sandbox such as `AioSandboxProvider`.
|
||||
|
||||
Additional custom subagent types may be defined in config.yaml under
|
||||
`subagents.custom_agents`. Each custom type can have its own system prompt,
|
||||
tools, skills, model, and timeout configuration. If an unknown subagent_type
|
||||
is provided, the error message will list all available types.
|
||||
|
||||
When to use this tool:
|
||||
- Complex tasks requiring multiple steps or tools
|
||||
- Tasks that produce verbose output
|
||||
- When you want to isolate context from the main conversation
|
||||
- Parallel research or exploration tasks
|
||||
|
||||
When NOT to use this tool:
|
||||
- Simple, single-step operations (use tools directly)
|
||||
- Tasks requiring user interaction or clarification
|
||||
|
||||
Args:
|
||||
description: A short (3-5 word) description of the task for logging/display. ALWAYS PROVIDE THIS PARAMETER FIRST.
|
||||
prompt: The task description for the subagent. Be specific and clear about what needs to be done. ALWAYS PROVIDE THIS PARAMETER SECOND.
|
||||
subagent_type: The type of subagent to use. ALWAYS PROVIDE THIS PARAMETER THIRD.
|
||||
max_turns: Optional maximum number of agent turns. Defaults to subagent's configured max.
|
||||
"""
|
||||
runtime_app_config = _get_runtime_app_config(runtime)
|
||||
available_subagent_names = get_available_subagent_names(app_config=runtime_app_config) if runtime_app_config is not None else get_available_subagent_names()
|
||||
|
||||
# Get subagent configuration
|
||||
config = get_subagent_config(subagent_type, app_config=runtime_app_config) if runtime_app_config is not None else get_subagent_config(subagent_type)
|
||||
if config is None:
|
||||
available = ", ".join(available_subagent_names)
|
||||
return f"Error: Unknown subagent type '{subagent_type}'. Available: {available}"
|
||||
if subagent_type == "bash":
|
||||
host_bash_allowed = is_host_bash_allowed(runtime_app_config) if runtime_app_config is not None else is_host_bash_allowed()
|
||||
if not host_bash_allowed:
|
||||
return f"Error: {LOCAL_BASH_SUBAGENT_DISABLED_MESSAGE}"
|
||||
|
||||
# Build config overrides
|
||||
overrides: dict = {}
|
||||
|
||||
# Skills are loaded by SubagentExecutor per-session (aligned with Codex's pattern:
|
||||
# each subagent loads its own skills based on config, injected as conversation items).
|
||||
# No longer appended to system_prompt here.
|
||||
|
||||
if max_turns is not None:
|
||||
overrides["max_turns"] = max_turns
|
||||
|
||||
# Extract parent context from runtime
|
||||
sandbox_state = None
|
||||
thread_data = None
|
||||
thread_id = None
|
||||
parent_model = None
|
||||
trace_id = None
|
||||
metadata: dict = {}
|
||||
|
||||
if runtime is not None:
|
||||
sandbox_state = runtime.state.get("sandbox")
|
||||
thread_data = runtime.state.get("thread_data")
|
||||
thread_id = runtime.context.get("thread_id") if runtime.context else None
|
||||
if thread_id is None:
|
||||
thread_id = runtime.config.get("configurable", {}).get("thread_id")
|
||||
|
||||
# Try to get parent model from configurable
|
||||
metadata = runtime.config.get("metadata", {})
|
||||
parent_model = metadata.get("model_name")
|
||||
|
||||
# Get or generate trace_id for distributed tracing
|
||||
trace_id = metadata.get("trace_id") or str(uuid.uuid4())[:8]
|
||||
|
||||
parent_available_skills = metadata.get("available_skills")
|
||||
if parent_available_skills is not None:
|
||||
overrides["skills"] = _merge_skill_allowlists(list(parent_available_skills), config.skills)
|
||||
|
||||
if overrides:
|
||||
config = replace(config, **overrides)
|
||||
|
||||
# Get available tools (excluding task tool to prevent nesting)
|
||||
# Lazy import to avoid circular dependency
|
||||
from deerflow.tools import get_available_tools
|
||||
|
||||
# Inherit parent agent's tool_groups so subagents respect the same restrictions
|
||||
parent_tool_groups = metadata.get("tool_groups")
|
||||
resolved_app_config = runtime_app_config
|
||||
if config.model == "inherit" and parent_model is None and resolved_app_config is None:
|
||||
resolved_app_config = get_app_config()
|
||||
effective_model = resolve_subagent_model_name(config, parent_model, app_config=resolved_app_config)
|
||||
|
||||
# Subagents should not have subagent tools enabled (prevent recursive nesting)
|
||||
available_tools_kwargs = {
|
||||
"model_name": effective_model,
|
||||
"groups": parent_tool_groups,
|
||||
"subagent_enabled": False,
|
||||
}
|
||||
if resolved_app_config is not None:
|
||||
available_tools_kwargs["app_config"] = resolved_app_config
|
||||
tools = get_available_tools(**available_tools_kwargs)
|
||||
|
||||
# Create executor
|
||||
executor_kwargs = {
|
||||
"config": config,
|
||||
"tools": tools,
|
||||
"parent_model": parent_model,
|
||||
"sandbox_state": sandbox_state,
|
||||
"thread_data": thread_data,
|
||||
"thread_id": thread_id,
|
||||
"trace_id": trace_id,
|
||||
}
|
||||
if resolved_app_config is not None:
|
||||
executor_kwargs["app_config"] = resolved_app_config
|
||||
executor = SubagentExecutor(**executor_kwargs)
|
||||
|
||||
# Start background execution (always async to prevent blocking)
|
||||
# Use tool_call_id as task_id for better traceability
|
||||
task_id = executor.execute_async(prompt, task_id=tool_call_id)
|
||||
|
||||
# Poll for task completion in backend (removes need for LLM to poll)
|
||||
poll_count = 0
|
||||
last_status = None
|
||||
last_message_count = 0 # Track how many AI messages we've already sent
|
||||
# Polling timeout: execution timeout + 60s buffer, checked every 5s
|
||||
max_poll_count = (config.timeout_seconds + 60) // 5
|
||||
|
||||
logger.info(f"[trace={trace_id}] Started background task {task_id} (subagent={subagent_type}, timeout={config.timeout_seconds}s, polling_limit={max_poll_count} polls)")
|
||||
|
||||
writer = get_stream_writer()
|
||||
# Send Task Started message'
|
||||
writer({"type": "task_started", "task_id": task_id, "description": description})
|
||||
|
||||
try:
|
||||
while True:
|
||||
result = get_background_task_result(task_id)
|
||||
|
||||
if result is None:
|
||||
logger.error(f"[trace={trace_id}] Task {task_id} not found in background tasks")
|
||||
writer({"type": "task_failed", "task_id": task_id, "error": "Task disappeared from background tasks"})
|
||||
cleanup_background_task(task_id)
|
||||
return f"Error: Task {task_id} disappeared from background tasks"
|
||||
|
||||
# Log status changes for debugging
|
||||
if result.status != last_status:
|
||||
logger.info(f"[trace={trace_id}] Task {task_id} status: {result.status.value}")
|
||||
last_status = result.status
|
||||
|
||||
# Check for new AI messages and send task_running events
|
||||
ai_messages = result.ai_messages or []
|
||||
current_message_count = len(ai_messages)
|
||||
if current_message_count > last_message_count:
|
||||
# Send task_running event for each new message
|
||||
for i in range(last_message_count, current_message_count):
|
||||
message = ai_messages[i]
|
||||
writer(
|
||||
{
|
||||
"type": "task_running",
|
||||
"task_id": task_id,
|
||||
"message": message,
|
||||
"message_index": i + 1, # 1-based index for display
|
||||
"total_messages": current_message_count,
|
||||
}
|
||||
)
|
||||
logger.info(f"[trace={trace_id}] Task {task_id} sent message #{i + 1}/{current_message_count}")
|
||||
last_message_count = current_message_count
|
||||
|
||||
# Check if task completed, failed, or timed out
|
||||
if result.status == SubagentStatus.COMPLETED:
|
||||
writer({"type": "task_completed", "task_id": task_id, "result": result.result})
|
||||
logger.info(f"[trace={trace_id}] Task {task_id} completed after {poll_count} polls")
|
||||
cleanup_background_task(task_id)
|
||||
return f"Task Succeeded. Result: {result.result}"
|
||||
elif result.status == SubagentStatus.FAILED:
|
||||
writer({"type": "task_failed", "task_id": task_id, "error": result.error})
|
||||
logger.error(f"[trace={trace_id}] Task {task_id} failed: {result.error}")
|
||||
cleanup_background_task(task_id)
|
||||
return f"Task failed. Error: {result.error}"
|
||||
elif result.status == SubagentStatus.CANCELLED:
|
||||
writer({"type": "task_cancelled", "task_id": task_id, "error": result.error})
|
||||
logger.info(f"[trace={trace_id}] Task {task_id} cancelled: {result.error}")
|
||||
cleanup_background_task(task_id)
|
||||
return "Task cancelled by user."
|
||||
elif result.status == SubagentStatus.TIMED_OUT:
|
||||
writer({"type": "task_timed_out", "task_id": task_id, "error": result.error})
|
||||
logger.warning(f"[trace={trace_id}] Task {task_id} timed out: {result.error}")
|
||||
cleanup_background_task(task_id)
|
||||
return f"Task timed out. Error: {result.error}"
|
||||
|
||||
# Still running, wait before next poll
|
||||
await asyncio.sleep(5)
|
||||
poll_count += 1
|
||||
|
||||
# Polling timeout as a safety net (in case thread pool timeout doesn't work)
|
||||
# Set to execution timeout + 60s buffer, in 5s poll intervals
|
||||
# This catches edge cases where the background task gets stuck
|
||||
# Note: We don't call cleanup_background_task here because the task may
|
||||
# still be running in the background. The cleanup will happen when the
|
||||
# executor completes and sets a terminal status.
|
||||
if poll_count > max_poll_count:
|
||||
timeout_minutes = config.timeout_seconds // 60
|
||||
logger.error(f"[trace={trace_id}] Task {task_id} polling timed out after {poll_count} polls (should have been caught by thread pool timeout)")
|
||||
writer({"type": "task_timed_out", "task_id": task_id})
|
||||
return f"Task polling timed out after {timeout_minutes} minutes. This may indicate the background task is stuck. Status: {result.status.value}"
|
||||
except asyncio.CancelledError:
|
||||
# Signal the background subagent thread to stop cooperatively.
|
||||
# Without this, the thread (running in ThreadPoolExecutor with its
|
||||
# own event loop via asyncio.run) would continue executing even
|
||||
# after the parent task is cancelled.
|
||||
request_cancel_background_task(task_id)
|
||||
|
||||
async def cleanup_when_done() -> None:
|
||||
max_cleanup_polls = max_poll_count
|
||||
cleanup_poll_count = 0
|
||||
|
||||
while True:
|
||||
result = get_background_task_result(task_id)
|
||||
if result is None:
|
||||
return
|
||||
|
||||
if result.status in {SubagentStatus.COMPLETED, SubagentStatus.FAILED, SubagentStatus.CANCELLED, SubagentStatus.TIMED_OUT} or getattr(result, "completed_at", None) is not None:
|
||||
cleanup_background_task(task_id)
|
||||
return
|
||||
|
||||
if cleanup_poll_count > max_cleanup_polls:
|
||||
logger.warning(f"[trace={trace_id}] Deferred cleanup for task {task_id} timed out after {cleanup_poll_count} polls")
|
||||
return
|
||||
|
||||
await asyncio.sleep(5)
|
||||
cleanup_poll_count += 1
|
||||
|
||||
def log_cleanup_failure(cleanup_task: asyncio.Task[None]) -> None:
|
||||
if cleanup_task.cancelled():
|
||||
return
|
||||
|
||||
exc = cleanup_task.exception()
|
||||
if exc is not None:
|
||||
logger.error(f"[trace={trace_id}] Deferred cleanup failed for task {task_id}: {exc}")
|
||||
|
||||
logger.debug(f"[trace={trace_id}] Scheduling deferred cleanup for cancelled task {task_id}")
|
||||
asyncio.create_task(cleanup_when_done()).add_done_callback(log_cleanup_failure)
|
||||
raise
|
||||
+202
@@ -0,0 +1,202 @@
|
||||
"""Tool search — deferred tool discovery at runtime.
|
||||
|
||||
Contains:
|
||||
- DeferredToolRegistry: stores deferred tools and handles regex search
|
||||
- tool_search: the LangChain tool the agent calls to discover deferred tools
|
||||
|
||||
The agent sees deferred tool names in <available-deferred-tools> but cannot
|
||||
call them until it fetches their full schema via the tool_search tool.
|
||||
Source-agnostic: no mention of MCP or tool origin.
|
||||
"""
|
||||
|
||||
import contextvars
|
||||
import json
|
||||
import logging
|
||||
import re
|
||||
from dataclasses import dataclass
|
||||
|
||||
from langchain.tools import BaseTool
|
||||
from langchain_core.tools import tool
|
||||
from langchain_core.utils.function_calling import convert_to_openai_function
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
MAX_RESULTS = 5 # Max tools returned per search
|
||||
|
||||
|
||||
# ── Registry ──
|
||||
|
||||
|
||||
@dataclass
|
||||
class DeferredToolEntry:
|
||||
"""Lightweight metadata for a deferred tool (no full schema in context)."""
|
||||
|
||||
name: str
|
||||
description: str
|
||||
tool: BaseTool # Full tool object, returned only on search match
|
||||
|
||||
|
||||
class DeferredToolRegistry:
|
||||
"""Registry of deferred tools, searchable by regex pattern."""
|
||||
|
||||
def __init__(self):
|
||||
self._entries: list[DeferredToolEntry] = []
|
||||
|
||||
def register(self, tool: BaseTool) -> None:
|
||||
self._entries.append(
|
||||
DeferredToolEntry(
|
||||
name=tool.name,
|
||||
description=tool.description or "",
|
||||
tool=tool,
|
||||
)
|
||||
)
|
||||
|
||||
def promote(self, names: set[str]) -> None:
|
||||
"""Remove tools from the deferred registry so they pass through the filter.
|
||||
|
||||
Called after tool_search returns a tool's schema — the LLM now knows
|
||||
the full definition, so the DeferredToolFilterMiddleware should stop
|
||||
stripping it from bind_tools on subsequent calls.
|
||||
"""
|
||||
if not names:
|
||||
return
|
||||
before = len(self._entries)
|
||||
self._entries = [e for e in self._entries if e.name not in names]
|
||||
promoted = before - len(self._entries)
|
||||
if promoted:
|
||||
logger.debug(f"Promoted {promoted} tool(s) from deferred to active: {names}")
|
||||
|
||||
def search(self, query: str) -> list[BaseTool]:
|
||||
"""Search deferred tools by regex pattern against name + description.
|
||||
|
||||
Supports three query forms (aligned with Claude Code):
|
||||
- "select:name1,name2" — exact name match
|
||||
- "+keyword rest" — name must contain keyword, rank by rest
|
||||
- "keyword query" — regex match against name + description
|
||||
|
||||
Returns:
|
||||
List of matched BaseTool objects (up to MAX_RESULTS).
|
||||
"""
|
||||
if query.startswith("select:"):
|
||||
names = {n.strip() for n in query[7:].split(",")}
|
||||
return [e.tool for e in self._entries if e.name in names][:MAX_RESULTS]
|
||||
|
||||
if query.startswith("+"):
|
||||
parts = query[1:].split(None, 1)
|
||||
required = parts[0].lower()
|
||||
candidates = [e for e in self._entries if required in e.name.lower()]
|
||||
if len(parts) > 1:
|
||||
candidates.sort(
|
||||
key=lambda e: _regex_score(parts[1], e),
|
||||
reverse=True,
|
||||
)
|
||||
return [e.tool for e in candidates][:MAX_RESULTS]
|
||||
|
||||
# General regex search
|
||||
try:
|
||||
regex = re.compile(query, re.IGNORECASE)
|
||||
except re.error:
|
||||
regex = re.compile(re.escape(query), re.IGNORECASE)
|
||||
|
||||
scored = []
|
||||
for entry in self._entries:
|
||||
searchable = f"{entry.name} {entry.description}"
|
||||
if regex.search(searchable):
|
||||
score = 2 if regex.search(entry.name) else 1
|
||||
scored.append((score, entry))
|
||||
|
||||
scored.sort(key=lambda x: x[0], reverse=True)
|
||||
return [entry.tool for _, entry in scored][:MAX_RESULTS]
|
||||
|
||||
@property
|
||||
def entries(self) -> list[DeferredToolEntry]:
|
||||
return list(self._entries)
|
||||
|
||||
@property
|
||||
def deferred_names(self) -> set[str]:
|
||||
"""Names of tools that are still hidden from model binding."""
|
||||
return {entry.name for entry in self._entries}
|
||||
|
||||
def contains(self, name: str) -> bool:
|
||||
"""Return whether *name* is still deferred."""
|
||||
return any(entry.name == name for entry in self._entries)
|
||||
|
||||
def __len__(self) -> int:
|
||||
return len(self._entries)
|
||||
|
||||
|
||||
def _regex_score(pattern: str, entry: DeferredToolEntry) -> int:
|
||||
try:
|
||||
regex = re.compile(pattern, re.IGNORECASE)
|
||||
except re.error:
|
||||
regex = re.compile(re.escape(pattern), re.IGNORECASE)
|
||||
return len(regex.findall(f"{entry.name} {entry.description}"))
|
||||
|
||||
|
||||
# ── Per-request registry (ContextVar) ──
|
||||
#
|
||||
# Using a ContextVar instead of a module-level global prevents concurrent
|
||||
# requests from clobbering each other's registry. In asyncio-based LangGraph
|
||||
# each graph run executes in its own async context, so each request gets an
|
||||
# independent registry value. For synchronous tools run via
|
||||
# loop.run_in_executor, Python copies the current context to the worker thread,
|
||||
# so the ContextVar value is correctly inherited there too.
|
||||
|
||||
_registry_var: contextvars.ContextVar[DeferredToolRegistry | None] = contextvars.ContextVar("deferred_tool_registry", default=None)
|
||||
|
||||
|
||||
def get_deferred_registry() -> DeferredToolRegistry | None:
|
||||
return _registry_var.get()
|
||||
|
||||
|
||||
def set_deferred_registry(registry: DeferredToolRegistry) -> None:
|
||||
_registry_var.set(registry)
|
||||
|
||||
|
||||
def reset_deferred_registry() -> None:
|
||||
"""Reset the deferred registry for the current async context."""
|
||||
_registry_var.set(None)
|
||||
|
||||
|
||||
# ── Tool ──
|
||||
|
||||
|
||||
@tool
|
||||
def tool_search(query: str) -> str:
|
||||
"""Fetches full schema definitions for deferred tools so they can be called.
|
||||
|
||||
Deferred tools appear by name in <available-deferred-tools> in the system
|
||||
prompt. Until fetched, only the name is known — there is no parameter
|
||||
schema, so the tool cannot be invoked. This tool takes a query, matches
|
||||
it against the deferred tool list, and returns the matched tools' complete
|
||||
definitions. Once a tool's schema appears in that result, it is callable.
|
||||
|
||||
Query forms:
|
||||
- "select:Read,Edit,Grep" — fetch these exact tools by name
|
||||
- "notebook jupyter" — keyword search, up to max_results best matches
|
||||
- "+slack send" — require "slack" in the name, rank by remaining terms
|
||||
|
||||
Args:
|
||||
query: Query to find deferred tools. Use "select:<tool_name>" for
|
||||
direct selection, or keywords to search.
|
||||
|
||||
Returns:
|
||||
Matched tool definitions as JSON array.
|
||||
"""
|
||||
registry = get_deferred_registry()
|
||||
if not registry:
|
||||
return "No deferred tools available."
|
||||
|
||||
matched_tools = registry.search(query)
|
||||
if not matched_tools:
|
||||
return f"No tools found matching: {query}"
|
||||
|
||||
# Use LangChain's built-in serialization to produce OpenAI function format.
|
||||
# This is model-agnostic: all LLMs understand this standard schema.
|
||||
tool_defs = [convert_to_openai_function(t) for t in matched_tools[:MAX_RESULTS]]
|
||||
|
||||
# Promote matched tools so the DeferredToolFilterMiddleware stops filtering
|
||||
# them from bind_tools — the LLM now has the full schema and can invoke them.
|
||||
registry.promote({t.name for t in matched_tools[:MAX_RESULTS]})
|
||||
|
||||
return json.dumps(tool_defs, indent=2, ensure_ascii=False)
|
||||
+194
@@ -0,0 +1,194 @@
|
||||
import base64
|
||||
import mimetypes
|
||||
from pathlib import Path
|
||||
from typing import Annotated
|
||||
|
||||
from langchain.tools import InjectedToolCallId, ToolRuntime, tool
|
||||
from langchain_core.messages import ToolMessage
|
||||
from langgraph.types import Command
|
||||
from langgraph.typing import ContextT
|
||||
|
||||
from deerflow.agents.thread_state import ThreadDataState, ThreadState
|
||||
from deerflow.config.paths import VIRTUAL_PATH_PREFIX
|
||||
|
||||
_ALLOWED_IMAGE_VIRTUAL_ROOTS = (
|
||||
f"{VIRTUAL_PATH_PREFIX}/workspace",
|
||||
f"{VIRTUAL_PATH_PREFIX}/uploads",
|
||||
f"{VIRTUAL_PATH_PREFIX}/outputs",
|
||||
)
|
||||
_ALLOWED_IMAGE_VIRTUAL_ROOTS_TEXT = ", ".join(_ALLOWED_IMAGE_VIRTUAL_ROOTS)
|
||||
_MAX_IMAGE_BYTES = 20 * 1024 * 1024
|
||||
_EXTENSION_TO_MIME = {
|
||||
".jpg": "image/jpeg",
|
||||
".jpeg": "image/jpeg",
|
||||
".png": "image/png",
|
||||
".webp": "image/webp",
|
||||
}
|
||||
|
||||
|
||||
def _is_allowed_image_virtual_path(image_path: str) -> bool:
|
||||
return any(image_path == root or image_path.startswith(f"{root}/") for root in _ALLOWED_IMAGE_VIRTUAL_ROOTS)
|
||||
|
||||
|
||||
def _detect_image_mime(image_data: bytes) -> str | None:
|
||||
if image_data.startswith(b"\xff\xd8\xff"):
|
||||
return "image/jpeg"
|
||||
if image_data.startswith(b"\x89PNG\r\n\x1a\n"):
|
||||
return "image/png"
|
||||
if len(image_data) >= 12 and image_data.startswith(b"RIFF") and image_data[8:12] == b"WEBP":
|
||||
return "image/webp"
|
||||
return None
|
||||
|
||||
|
||||
def _sanitize_image_error(error: Exception, thread_data: ThreadDataState | None) -> str:
|
||||
from deerflow.sandbox.tools import mask_local_paths_in_output
|
||||
|
||||
return mask_local_paths_in_output(f"{type(error).__name__}: {error}", thread_data)
|
||||
|
||||
|
||||
@tool("view_image", parse_docstring=True)
|
||||
def view_image_tool(
|
||||
runtime: ToolRuntime[ContextT, ThreadState],
|
||||
image_path: str,
|
||||
tool_call_id: Annotated[str, InjectedToolCallId],
|
||||
question: str | None = None,
|
||||
) -> Command:
|
||||
"""Read and understand an image file.
|
||||
|
||||
This is the ONLY correct way to understand an image. The image is analyzed by
|
||||
the configured vision model and its description/answer is returned to you as
|
||||
the tool result. Treat that result as authoritative.
|
||||
|
||||
When to use the view_image tool:
|
||||
- Whenever you need to view, describe, or answer a question about an image file.
|
||||
|
||||
When NOT to use the view_image tool:
|
||||
- For non-image files (use present_files instead)
|
||||
- For multiple files at once (use present_files instead)
|
||||
|
||||
IMPORTANT — do NOT attempt to understand images any other way:
|
||||
- Never read, open, decode, or parse an image with read_file, grep, bash,
|
||||
python, PIL/Pillow, OpenCV, EXIF parsing, or byte/hex inspection. Those
|
||||
cannot interpret visual content and will only waste turns.
|
||||
- If `view_image` returns a weak or incomplete description, do not fall back
|
||||
to code. Either call `view_image` again with a more specific `question`,
|
||||
or tell the user the configured vision model could not extract more detail
|
||||
(the vision model may need to be changed in config).
|
||||
|
||||
Args:
|
||||
image_path: Absolute /mnt/user-data virtual path to the image file. Common formats supported: jpg, jpeg, png, webp.
|
||||
question: Optional specific question to ask about the image (e.g. "What is the total on this invoice?"). When omitted, a general detailed description is produced.
|
||||
"""
|
||||
from deerflow.sandbox.exceptions import SandboxRuntimeError
|
||||
from deerflow.sandbox.tools import (
|
||||
get_thread_data,
|
||||
resolve_and_validate_user_data_path,
|
||||
validate_local_tool_path,
|
||||
)
|
||||
|
||||
thread_data = get_thread_data(runtime)
|
||||
|
||||
if not _is_allowed_image_virtual_path(image_path):
|
||||
return Command(
|
||||
update={
|
||||
"messages": [
|
||||
ToolMessage(
|
||||
f"Error: Only image paths under {_ALLOWED_IMAGE_VIRTUAL_ROOTS_TEXT} are allowed",
|
||||
tool_call_id=tool_call_id,
|
||||
)
|
||||
]
|
||||
},
|
||||
)
|
||||
|
||||
try:
|
||||
validate_local_tool_path(image_path, thread_data, read_only=True)
|
||||
actual_path = resolve_and_validate_user_data_path(image_path, thread_data)
|
||||
except (PermissionError, SandboxRuntimeError) as e:
|
||||
return Command(
|
||||
update={"messages": [ToolMessage(f"Error: {str(e)}", tool_call_id=tool_call_id)]},
|
||||
)
|
||||
|
||||
path = Path(actual_path)
|
||||
|
||||
# Validate that the file exists
|
||||
if not path.exists():
|
||||
return Command(
|
||||
update={"messages": [ToolMessage(f"Error: Image file not found: {image_path}", tool_call_id=tool_call_id)]},
|
||||
)
|
||||
|
||||
# Validate that it's a file (not a directory)
|
||||
if not path.is_file():
|
||||
return Command(
|
||||
update={"messages": [ToolMessage(f"Error: Path is not a file: {image_path}", tool_call_id=tool_call_id)]},
|
||||
)
|
||||
|
||||
# Validate image extension
|
||||
expected_mime_type = _EXTENSION_TO_MIME.get(path.suffix.lower())
|
||||
if expected_mime_type is None:
|
||||
return Command(
|
||||
update={"messages": [ToolMessage(f"Error: Unsupported image format: {path.suffix}. Supported formats: {', '.join(_EXTENSION_TO_MIME)}", tool_call_id=tool_call_id)]},
|
||||
)
|
||||
|
||||
# Detect MIME type from file extension
|
||||
mime_type, _ = mimetypes.guess_type(actual_path)
|
||||
if mime_type is None:
|
||||
mime_type = expected_mime_type
|
||||
|
||||
try:
|
||||
image_size = path.stat().st_size
|
||||
except OSError as e:
|
||||
return Command(
|
||||
update={"messages": [ToolMessage(f"Error reading image metadata: {_sanitize_image_error(e, thread_data)}", tool_call_id=tool_call_id)]},
|
||||
)
|
||||
if image_size > _MAX_IMAGE_BYTES:
|
||||
return Command(
|
||||
update={"messages": [ToolMessage(f"Error: Image file is too large: {image_size} bytes. Maximum supported size is {_MAX_IMAGE_BYTES} bytes", tool_call_id=tool_call_id)]},
|
||||
)
|
||||
|
||||
# Read image file and convert to base64
|
||||
try:
|
||||
with open(actual_path, "rb") as f:
|
||||
image_data = f.read()
|
||||
except Exception as e:
|
||||
return Command(
|
||||
update={"messages": [ToolMessage(f"Error reading image file: {_sanitize_image_error(e, thread_data)}", tool_call_id=tool_call_id)]},
|
||||
)
|
||||
|
||||
detected_mime_type = _detect_image_mime(image_data)
|
||||
if detected_mime_type is None:
|
||||
return Command(
|
||||
update={"messages": [ToolMessage("Error: File contents do not match a supported image format", tool_call_id=tool_call_id)]},
|
||||
)
|
||||
if detected_mime_type != expected_mime_type:
|
||||
return Command(
|
||||
update={"messages": [ToolMessage(f"Error: Image contents are {detected_mime_type}, but file extension indicates {expected_mime_type}", tool_call_id=tool_call_id)]},
|
||||
)
|
||||
mime_type = detected_mime_type
|
||||
image_base64 = base64.b64encode(image_data).decode("utf-8")
|
||||
|
||||
# Delegated recognition: when a dedicated vision model is configured, send
|
||||
# the image to that model and return its description as the tool result, so
|
||||
# a text-only main chat model can still "see" the image.
|
||||
from deerflow.models.vision import is_delegated_vision, recognize_image
|
||||
|
||||
if is_delegated_vision():
|
||||
try:
|
||||
description = recognize_image(image_base64, mime_type, question=question)
|
||||
except Exception as e: # noqa: BLE001 - surface as a recoverable tool error
|
||||
return Command(
|
||||
update={"messages": [ToolMessage(f"Error recognizing image: {_sanitize_image_error(e, thread_data)}", tool_call_id=tool_call_id)]},
|
||||
)
|
||||
if not description:
|
||||
description = "The vision model returned an empty description."
|
||||
return Command(
|
||||
update={"messages": [ToolMessage(f"Image recognition result for {image_path}:\n\n{description}", tool_call_id=tool_call_id)]},
|
||||
)
|
||||
|
||||
# Native vision: store the image so ViewImageMiddleware injects it into the
|
||||
# (vision-capable) main model before the next LLM call.
|
||||
# The merge_viewed_images reducer will handle merging with existing images.
|
||||
new_viewed_images = {image_path: {"base64": image_base64, "mime_type": mime_type}}
|
||||
|
||||
return Command(
|
||||
update={"viewed_images": new_viewed_images, "messages": [ToolMessage("Successfully read image", tool_call_id=tool_call_id)]},
|
||||
)
|
||||
Reference in new issue
Block a user