初始化提交

backend/app/application/tool_runtime/builtins.py

@@ -0,0 +1,174 @@
+"""内置工具集合。覆盖 L0–L3 风险等级，供编排闭环、司命分级演示与前端调用。
+
+文件类工具（read_file / list_dir / write_file）使用沙箱 base 下的持久子目录
+``workspace``，并通过 ``isolated_workspace=True`` 由 runtime 改写为按角色隔离的
+``workspace/<character_id>``，使同一角色跨会话/跨 run 文件互通、不同角色互不可见
+（workdir 相对 base，受沙箱路径逃逸保护）。多用户上线后隔离主体将切换为真实用户标识。
+
+执行路径：
+- 沙箱路径（datetime/read_file/list_dir/write_file/shell）：``build_request`` 产出 ExecRequest，
+  由 SandboxClient 执行。参数默认用环境变量传参（避免命令注入）；write_file 的 content 因可能
+  很大（单个 env 受 MAX_ARG_STRLEN≈128KB 限制）改经 stdin 写入——既无大小上限，又不经 shell 解释。
+  shell 保留直接拼接——本就是任意命令，且经沙箱隔离。
+- 直接执行路径（fetch_url）：``executor`` 直接发起 HTTP 调用（见 ``web_tools.py``），
+  不走沙箱；http_client 与密钥由 runtime 注入。
+"""
+
+from __future__ import annotations
+
+from app.application.tool_runtime.web_tools import _fetch_url_executor
+from app.core.config import settings
+from app.integrations.sandbox.models import ExecRequest
+from app.modules.safety.governor import PermissionPolicy
+from app.modules.tool_runtime.definition import ToolInput, ToolSpec
+
+# 沙箱 base 下的持久工作子目录（文件类工具共享，由 runtime 按角色隔离为 workspace/<character_id>）
+_WORKSPACE = "workspace"
+
+
+def _need_str(input: ToolInput, key: str) -> str:
+    value = input.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"工具需要非空字符串 '{key}' 输入")
+    return value
+
+
+def _datetime_request(_input: ToolInput) -> ExecRequest:
+    return ExecRequest(argv=["sh", "-c", "date '+%Y-%m-%d %H:%M:%S %Z'"])
+
+
+def _as_positive_int(value: object, *, default: int) -> int:
+    """把 offset/limit 容错解析为 >=1 的整数；非数字或缺省返回 default。"""
+    try:
+        n = int(value)  # str/int/float 均可；bool(True)=1 由 >=1 兜底
+    except (TypeError, ValueError):
+        return default
+    return n if n >= 1 else default
+
+
+def _read_file_request(input: ToolInput) -> ExecRequest:
+    path = _need_str(input, "path")
+    # 行分页（offset 起始行 1-based / limit 行数）：大文件可分段读取，避免整体 cat 后被回显
+    # 截断、模型拿不到完整内容而反复试错。offset/limit 经 int() 规整为纯数字后拼入 sed 地址
+    # （数字无注入风险），行范围用单引号包裹（末行 $ 字面、不经 shell 展开），PATH_ARG 仍走 env。
+    # 缺省 offset/limit 时读全部（行为不变）。
+    # 使用绝对路径（/bin/sed, /bin/cat）：避免 env_clear 后 PATH 失效。
+    start = _as_positive_int(input.get("offset"), default=1)
+    row_limit = _as_positive_int(input.get("limit"), default=0)
+    if start > 1 or row_limit > 0:
+        range_expr = f"{start},{start + row_limit - 1}" if row_limit > 0 else f"{start},$"
+        return ExecRequest(
+            argv=["sh", "-c", f"sed -n '{range_expr}p' \"$PATH_ARG\""],
+            env={"PATH_ARG": path},
+            workdir=_WORKSPACE,
+        )
+    return ExecRequest(
+        argv=["sh", "-c", 'cat -- "$PATH_ARG"'],
+        env={"PATH_ARG": path},
+        workdir=_WORKSPACE,
+    )
+
+
+def _list_dir_request(input: ToolInput) -> ExecRequest:
+    path = input.get("path", ".")
+    return ExecRequest(
+        argv=["sh", "-c", 'ls -la -- "$PATH_ARG"'],
+        env={"PATH_ARG": str(path)},
+        workdir=_WORKSPACE,
+    )
+
+
+def _write_file_request(input: ToolInput) -> ExecRequest:
+    path = _need_str(input, "path")
+    content = input.get("content", "")
+    # content 经 stdin 写入（cat > file），不经环境变量：单个 env 受 MAX_ARG_STRLEN≈128KB
+    # 限制，大文档经 env 会让 execve 返回 E2BIG、沙箱 ok=False，模型反复重试直到截断；
+    # stdin 既无大小上限、又完全不经过 shell 解释（比 env/argv 更安全，内容里的 `$`、
+    # 反引号、`%` 等都原样落盘）。PATH_ARG 仍用 env（短、需拼进重定向目标）。
+    return ExecRequest(
+        argv=["sh", "-c", 'cat > "$PATH_ARG"'],
+        env={"PATH_ARG": path},
+        stdin=str(content),
+        workdir=_WORKSPACE,
+    )
+
+
+def _shell_request(input: ToolInput) -> ExecRequest:
+    command = _need_str(input, "command")
+    raw_timeout = input.get("timeout_ms")
+    timeout_ms = (
+        int(raw_timeout)
+        if isinstance(raw_timeout, int | float)
+        else settings.sandbox_default_timeout_ms
+    )
+    stdin = input.get("stdin")
+    return ExecRequest(
+        argv=["sh", "-c", command],
+        stdin=stdin if isinstance(stdin, str) else None,
+        timeout_ms=timeout_ms,
+    )
+
+
+DATETIME = ToolSpec(
+    name="datetime",
+    description="获取当前时间（只读，L0）。",
+    risk_level="L0",
+    permission_policy=PermissionPolicy.allow,
+    build_request=_datetime_request,
+    side_effect=False,
+)
+READ_FILE = ToolSpec(
+    name="read_file",
+    description="读取 workspace 内文件（只读，L1）。",
+    risk_level="L1",
+    permission_policy=PermissionPolicy.allow,
+    build_request=_read_file_request,
+    side_effect=False,
+    isolated_workspace=True,
+)
+LIST_DIR = ToolSpec(
+    name="list_dir",
+    description="列出 workspace 内目录（只读，L1）。",
+    risk_level="L1",
+    permission_policy=PermissionPolicy.allow,
+    build_request=_list_dir_request,
+    side_effect=False,
+    isolated_workspace=True,
+)
+WRITE_FILE = ToolSpec(
+    name="write_file",
+    description="写入 workspace 内文件（有副作用，L2 需确认）。",
+    risk_level="L2",
+    permission_policy=PermissionPolicy.ask,
+    build_request=_write_file_request,
+    side_effect=True,
+    isolated_workspace=True,
+)
+SHELL = ToolSpec(
+    name="shell",
+    description="在沙箱中执行任意 shell 命令（高风险，L3 需确认）。",
+    risk_level="L3",
+    permission_policy=PermissionPolicy.always_ask,
+    build_request=_shell_request,
+    side_effect=True,
+    # 与文件类工具统一默认工作目录（workspace/<角色>）：否则 shell 跑在沙箱根目录，cat/ls
+    # 看不到 read_file/write_file 产生的文件，模型会反复试不同路径直到循环截断。shell 本是
+    # 任意命令，cd 仍可改目录（沙箱路径逃逸保护另兜底），这里只统一默认起点。
+    isolated_workspace=True,
+)
+FETCH_URL = ToolSpec(
+    name="fetch_url",
+    description="抓取指定 URL 的网页正文（转 markdown）。",
+    risk_level="L2",
+    permission_policy=PermissionPolicy.ask,
+    side_effect=True,
+    audit_required=True,
+    executor=_fetch_url_executor,
+)
+
+
+def builtin_specs() -> dict[str, ToolSpec]:
+    """返回内置工具规格字典。"""
+    return {
+        spec.name: spec for spec in [DATETIME, READ_FILE, LIST_DIR, WRITE_FILE, SHELL, FETCH_URL]
+    }