This commit is contained in:
许海洋 committed 2026-05-20 17:43:50 +08:00
commit e2d61f4cfb
476 files changed
+103681 -9379

No files matched your search

@@ -1,5 +1,5 @@
from .clarification_tool import ask_clarification_tool
from .fast_chat_tool import fast_chat_tool, fast_llm_answer
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
@@ -10,6 +10,7 @@ __all__ = [
"setup_agent",
"present_file_tool",
"ask_clarification_tool",
"memory_tool",
"scheduled_task_tool",
"view_image_tool",
"task_tool",
@@ -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",
]
@@ -0,0 +1,159 @@
"""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 or 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"]
@@ -66,6 +66,21 @@ async def _to_thread(func, /, *args, **kwargs):
return await asyncio.to_thread(func, *args, **kwargs)
async def _bump_patch_best_effort(name: str) -> None:
"""记一次技能维护活动(patch / edit)。
刷新 ``.usage.json`` 的 ``patch_count`` 与 ``last_patched_at``,让 curator 的
年龄流转把"Agent 正在主动维护的技能"算作活跃,而不是误判为闲置后归档。
best-effort:埋点失败只记 DEBUG 日志,绝不影响技能写入主流程。
"""
try:
from deerflow.skills.usage import bump_patch
await _to_thread(bump_patch, name)
except Exception:
logger.debug("Failed to bump patch count for %r", name, exc_info=True)
async def _ensure_skill_db_registered(store: SkillStore, name: str, user_id: str) -> None:
"""Idempotently record an agent-created skill's ownership in the DB.
@@ -229,6 +244,7 @@ async def _skill_manage_impl(
name,
_history_record(action="edit", file_path=SKILL_MD_FILE, prev_content=prev_content, new_content=content, thread_id=thread_id, scanner=scan),
)
await _bump_patch_best_effort(name)
await refresh_skills_system_prompt_cache_async()
return f"Updated custom skill '{name}'."
@@ -253,6 +269,7 @@ async def _skill_manage_impl(
name,
_history_record(action="patch", file_path=SKILL_MD_FILE, prev_content=prev_content, new_content=new_content, thread_id=thread_id, scanner=scan),
)
await _bump_patch_best_effort(name)
await refresh_skills_system_prompt_cache_async()
return f"Patched custom skill '{name}' ({replacement_count} replacement(s) applied, {occurrences} match(es) found)."
@@ -6,7 +6,7 @@ from deerflow.config import get_app_config
from deerflow.config.app_config import AppConfig
from deerflow.reflection import resolve_variable
from deerflow.sandbox.security import is_host_bash_allowed
from deerflow.tools.builtins import ask_clarification_tool, fast_chat_tool, fast_llm_answer, present_file_tool, scheduled_task_tool, task_tool, view_image_tool
from deerflow.tools.builtins import ask_clarification_tool, memory_tool, present_file_tool, scheduled_task_tool, task_tool, view_image_tool
from deerflow.tools.builtins.tool_search import reset_deferred_registry
logger = logging.getLogger(__name__)
@@ -86,6 +86,25 @@ def get_available_tools(
builtin_tools = BUILTIN_TOOLS.copy()
if not is_scheduled_run:
builtin_tools.append(scheduled_task_tool)
# Memory V2:记忆与 builtin provider 都启用时,暴露 memory 工具给 LLM 主动写入
memory_config = getattr(config, "memory", None)
if memory_config is not None and getattr(memory_config, "enabled", False):
builtin_config = getattr(memory_config, "builtin", None)
if builtin_config is not None and getattr(builtin_config, "enabled", False):
builtin_tools.append(memory_tool)
logger.info("Including memory tool (Memory V2 builtin provider enabled)")
# Hindsight 在 tools / hybrid 模式下,额外暴露 3 个 Hindsight 工具
if getattr(memory_config, "provider", "builtin") == "hindsight":
hindsight_config = getattr(memory_config, "hindsight", None)
memory_mode = getattr(hindsight_config, "memory_mode", "context") if hindsight_config else "context"
if memory_mode in ("tools", "hybrid"):
from deerflow.tools.builtins.hindsight_tools import HINDSIGHT_TOOLS
builtin_tools.extend(HINDSIGHT_TOOLS)
logger.info("Including Hindsight tools (memory_mode=%s)", memory_mode)
skill_evolution_config = getattr(config, "skill_evolution", None)
# skill_list / skill_view 是只读工具(发现、查看技能),与"自我进化"写能力无关,
# 始终提供给 agent。
from deerflow.tools.builtins.skill_tools import skill_list_tool, skill_view_tool