代码提交

This commit is contained in:
董宏凯 committed 2026-08-24 20:47:31 +08:00
1 parent 007ed5a7de
commit babc5e95c6
21 files changed
+1170 -145

No files matched your search

@@ -0,0 +1,382 @@
"""Hard runtime policy for the built-in forced-research responder.
The ordinary custom-agent skill allowlist only makes skills visible to the
model; it does not guarantee that a model will use one before answering. This
middleware turns that behavioural preference into a per-user-turn runtime
contract:
* before a successful information-gathering tool result exists, every model
call is made with ``tool_choice=required``;
* a provider that ignores ``tool_choice`` and emits text is sent back to the
model node (with the premature text hidden);
* after a bounded number of failed attempts the model may only report the
collection failure instead of looping forever;
* ``write_file`` / ``str_replace`` are restricted to temporary ``.py`` files
under ``/mnt/user-data/workspace`` and ``bash`` may only execute Python
scripts. Markdown/document deliverables and ``present_files`` are denied.
The policy is mounted only for :data:`FORCED_RESEARCH_AGENT_ID`.
"""
from __future__ import annotations
import json
import re
from collections.abc import Awaitable, Callable
from copy import deepcopy
from pathlib import PurePosixPath
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware, hook_config
from langchain.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse
from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
from langgraph.prebuilt.tool_node import ToolCallRequest
from langgraph.runtime import Runtime
from langgraph.types import Command
FORCED_RESEARCH_AGENT_ID = "forced-research-responder"
_WORKSPACE_PREFIX = "/mnt/user-data/workspace"
_MAX_COLLECTION_ATTEMPTS = 8
# These tools prepare/discover capabilities but do not themselves return the
# information requested by the user. Unknown tools (not in this set) are
# intentionally accepted so configured MCP/skill-specific retrieval tools work.
_NON_EVIDENCE_TOOLS = {
"agent_orchestration",
"ask_clarification",
"bash",
"glob",
"grep",
"ls",
"memory",
"present_files",
"read_file",
"scheduled_task",
"search_skills",
"skill_list",
"skill_manage",
"skill_view",
"str_replace",
"task",
"tool_search",
"write_file",
"write_todos",
}
_TOOLS_REMOVED_FROM_FORCED_RESEARCH = {
"agent_orchestration",
"ask_clarification",
"memory",
"present_files",
"scheduled_task",
"skill_manage",
"task",
}
_FAILED_RESULT_MARKERS = (
"error:",
"no results found",
"no result found",
"success\": false",
"success': false",
"未找到",
"没有找到",
"检索失败",
"查询失败",
)
_FORCE_COLLECTION_TEXT = """<forced_research_gate>
【运行时强制】本轮尚未取得任何有效的信息采集结果,禁止直接回答用户。
请先分析用户意图,拆分检索方向和具体检索词,然后立即调用已配置技能所需的工具、检索工具、知识库工具或技能 Python 脚本。
读取 SKILL.md、搜索技能、编写临时 Python 脚本都只是准备步骤,不能替代实际信息采集。
至少取得一次有效工具结果后,才能按照用户指定的格式直接在聊天中回答。
</forced_research_gate>"""
_COLLECTION_FAILED_TEXT = """<forced_research_gate>
【运行时强制】本轮已经多次尝试调用工具,但仍未取得有效的信息采集结果。
现在不要继续循环,也不得凭模型记忆补写事实。请直接用用户要求的格式如实说明本轮检索失败、已经尝试的方向以及仍缺少的信息。
禁止生成或呈现任何文件。
</forced_research_gate>"""
def filter_forced_research_tools(tools: list[Any]) -> list[Any]:
"""Remove unrelated/write-capable built-ins while retaining skill tools.
``write_file`` and ``str_replace`` stay available because the policy below
narrows them to temporary Python source files. ``bash`` stays available so
script-backed skills can execute their own or those temporary scripts.
"""
return [tool for tool in tools if getattr(tool, "name", "") not in _TOOLS_REMOVED_FROM_FORCED_RESEARCH]
def _normalize_args(raw: object) -> dict[str, Any]:
if isinstance(raw, dict):
return raw
if isinstance(raw, str):
try:
parsed = json.loads(raw)
except (TypeError, ValueError, json.JSONDecodeError):
return {}
return parsed if isinstance(parsed, dict) else {}
return {}
def _tool_field(tool_call: object, key: str, default: Any = None) -> Any:
if isinstance(tool_call, dict):
return tool_call.get(key, default)
getter = getattr(tool_call, "get", None)
if callable(getter):
return getter(key, default)
return getattr(tool_call, key, default)
def _normalized_container_path(value: object) -> str:
text = str(value or "").strip().replace("\\", "/")
if not text:
return ""
try:
return str(PurePosixPath(text))
except Exception: # noqa: BLE001 - invalid model-provided path is denied
return ""
def _is_workspace_python_path(value: object) -> bool:
path = _normalized_container_path(value)
return path.startswith(f"{_WORKSPACE_PREFIX}/") and path.lower().endswith(".py")
_PYTHON_EXECUTABLE_RE = re.compile(r"(?:^|[\s;&|])(?:python(?:3(?:\.\d+)?)?|py)(?:\.exe)?(?:\s|$)", re.IGNORECASE)
_PYTHON_FILE_RE = re.compile(r"(?:^|[\s\"'])([^\s\"']+\.py)(?=$|[\s\"'])", re.IGNORECASE)
_SHELL_WRITE_RE = re.compile(r"(?:>|\b(?:tee|touch|cp|mv|rm|del|erase|out-file|set-content|add-content)\b)", re.IGNORECASE)
_FORBIDDEN_DELIVERABLE_RE = re.compile(r"(?:/mnt/user-data/outputs|\.(?:md|markdown|docx?|pdf|xlsx?|pptx?|html?)(?:\s|$|[\"']))", re.IGNORECASE)
def _validate_python_command(command: object) -> str | None:
text = str(command or "").strip()
if not text:
return "bash 仅允许执行技能所需的 Python 脚本,command 不能为空。"
if _FORBIDDEN_DELIVERABLE_RE.search(text):
return "禁止通过 bash 创建、修改或处理 Markdown/文档交付物及 outputs 目录。"
if _SHELL_WRITE_RE.search(text):
return "bash 仅允许执行 Python 脚本,禁止使用 shell 重定向或文件管理命令。"
if not _PYTHON_EXECUTABLE_RE.search(text) or not _PYTHON_FILE_RE.search(text):
return "bash 仅允许执行 .py 脚本(例如 cd <技能目录> && python scripts/search.py ...)。"
return None
def validate_forced_research_tool_call(tool_call: object) -> str | None:
"""Return a rejection reason, or ``None`` when the call is permitted."""
name = str(_tool_field(tool_call, "name", "") or "")
args = _normalize_args(_tool_field(tool_call, "args", {}))
if name == "present_files":
return "本智能体只在聊天中输出,禁止呈现沙箱文件。"
if name in {"write_file", "str_replace"}:
if not _is_workspace_python_path(args.get("path")):
return "只允许在 /mnt/user-data/workspace/ 下创建或修改临时 .py 文件。"
if name == "bash":
return _validate_python_command(args.get("command"))
return None
def _is_visible_human(message: Any) -> bool:
if not isinstance(message, HumanMessage):
return False
kwargs = getattr(message, "additional_kwargs", None) or {}
if kwargs.get("hide_from_ui"):
return False
return getattr(message, "name", None) != "forced_research_gate"
def _turn_start(messages: list[Any]) -> int:
for index in range(len(messages) - 1, -1, -1):
if _is_visible_human(messages[index]):
return index
return 0
def _call_map(messages: list[Any], start: int) -> dict[str, tuple[str, dict[str, Any]]]:
calls: dict[str, tuple[str, dict[str, Any]]] = {}
for message in messages[start:]:
if not isinstance(message, AIMessage):
continue
for call in message.tool_calls or []:
call_id = str(_tool_field(call, "id", "") or "")
if call_id:
calls[call_id] = (
str(_tool_field(call, "name", "") or ""),
_normalize_args(_tool_field(call, "args", {})),
)
return calls
def _tool_result_succeeded(message: ToolMessage) -> bool:
status = str(getattr(message, "status", "") or "").lower()
if status == "error":
return False
content = str(getattr(message, "content", "") or "").strip()
if not content:
return False
lowered = content.lower()
return not any(marker in lowered for marker in _FAILED_RESULT_MARKERS)
def _is_information_result(name: str, args: dict[str, Any], message: ToolMessage) -> bool:
if name in _NON_EVIDENCE_TOOLS:
if name == "read_file":
path = str(args.get("path") or "").replace("\\", "/").lower()
if path.endswith("/skill.md") or path.endswith(".py"):
return False
elif name == "bash":
# bash is evidence only when it actually executed a Python skill
# script; policy validation has already rejected other commands.
if _validate_python_command(args.get("command")) is not None:
return False
else:
return False
return _tool_result_succeeded(message)
def _turn_collection_state(messages: list[Any]) -> tuple[bool, int]:
start = _turn_start(messages)
calls = _call_map(messages, start)
attempts = 0
for message in messages[start:]:
if not isinstance(message, ToolMessage):
continue
call_id = str(getattr(message, "tool_call_id", "") or "")
call = calls.get(call_id)
if call is None:
continue
attempts += 1
if _is_information_result(call[0], call[1], message):
return True, attempts
return False, attempts
def _hidden_reminder(text: str) -> HumanMessage:
return HumanMessage(
name="forced_research_gate",
content=text,
additional_kwargs={"hide_from_ui": True, "lc_source": "forced_research_gate"},
)
class ForcedResearchMiddleware(AgentMiddleware[AgentState]):
"""Require information collection and enforce temporary-Python-only IO."""
state_schema = AgentState
def _patch_model_request(self, request: ModelRequest) -> ModelRequest:
messages = list(request.messages or [])
collected, attempts = _turn_collection_state(messages)
if collected:
return request
if attempts >= _MAX_COLLECTION_ATTEMPTS:
return request.override(messages=[*messages, _hidden_reminder(_COLLECTION_FAILED_TEXT)])
return request.override(
messages=[*messages, _hidden_reminder(_FORCE_COLLECTION_TEXT)],
tool_choice="required",
)
def _prevent_premature_exit(self, state: AgentState) -> dict[str, Any] | None:
messages = list(state.get("messages") or [])
if not messages:
return None
last = messages[-1]
if not isinstance(last, AIMessage) or last.tool_calls:
return None
collected, attempts = _turn_collection_state(messages)
if collected or attempts >= _MAX_COLLECTION_ATTEMPTS:
return None
# Some OpenAI-compatible gateways ignore ``tool_choice=required``.
# Hide/blank that premature answer and explicitly jump back to model.
additional_kwargs = dict(last.additional_kwargs or {})
additional_kwargs["hide_from_ui"] = True
additional_kwargs["lc_source"] = "forced_research_suppressed_answer"
response_metadata = deepcopy(last.response_metadata or {})
if response_metadata.get("finish_reason") == "stop":
response_metadata["finish_reason"] = "tool_calls"
suppressed = last.model_copy(
update={
"content": "",
"additional_kwargs": additional_kwargs,
"response_metadata": response_metadata,
}
)
return {
"jump_to": "model",
"messages": [suppressed, _hidden_reminder(_FORCE_COLLECTION_TEXT)],
}
def _reject_tool_call(self, request: ToolCallRequest) -> ToolMessage | None:
tool_call = getattr(request, "tool_call", None) or {}
reason = validate_forced_research_tool_call(tool_call)
if reason is None:
return None
return ToolMessage(
content=f"Error: {reason}",
tool_call_id=str(_tool_field(tool_call, "id", "") or ""),
name=str(_tool_field(tool_call, "name", "") or ""),
status="error",
)
@override
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
return handler(self._patch_model_request(request))
@override
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
return await handler(self._patch_model_request(request))
@hook_config(can_jump_to=["model"])
@override
def after_model(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | None:
return self._prevent_premature_exit(state)
@hook_config(can_jump_to=["model"])
@override
async def aafter_model(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | None:
return self._prevent_premature_exit(state)
@override
def wrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
rejected = self._reject_tool_call(request)
if rejected is not None:
return rejected
return handler(request)
@override
async def awrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
) -> ToolMessage | Command:
rejected = self._reject_tool_call(request)
if rejected is not None:
return rejected
return await handler(request)
__all__ = [
"FORCED_RESEARCH_AGENT_ID",
"ForcedResearchMiddleware",
"filter_forced_research_tools",
"validate_forced_research_tool_call",
]