steven_li
5ba5c7e4c1
集成新的Beaver后端服务到应用实例中，替换原有的nanobot实现。 主要变更包括： - 在Dockerfile和环境配置中添加Beaver相关路径和配置变量 - 更新工作目录结构从.nanobot到.beaver - 实现Beaver引擎加载器，支持配置文件加载和工具组装 - 添加内置工具如ListDirectoryTool、ReadFileTool、SearchFilesTool - 更新消息处理流程，支持通道适配器和网关模式 - 重构技能系统，支持显式工具提示和嵌入式检索 - 改进错误处理和生命周期管理 此变更使应用实例能够使用统一的Beaver后端进行AI代理运行时管理。
443 lines
14 KiB
Python
443 lines
14 KiB
Python
"""Workspace-scoped read-only filesystem tools.
|
|
|
|
这些工具是 Beaver 第一批真实本地工具，只做只读能力：
|
|
- list_directory
|
|
- read_file
|
|
- search_files
|
|
|
|
安全边界先保持非常明确：所有用户传入路径都必须解析到当前
|
|
`ToolContext.workspace` 内部。即使 workspace 里有指向外部的符号链接，
|
|
读取时也会因为真实路径越界而被拒绝。
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from dataclasses import dataclass, field
|
|
import json
|
|
from pathlib import Path
|
|
from typing import Any, Iterable
|
|
|
|
|
|
MAX_LIST_ENTRIES = 1_000
|
|
MAX_READ_LINES = 1_000
|
|
MAX_READ_CHARS = 120_000
|
|
MAX_SEARCH_RESULTS = 200
|
|
MAX_SEARCH_FILE_BYTES = 2_000_000
|
|
MAX_SEARCH_FILES = 5_000
|
|
SKIP_DIR_NAMES = {
|
|
".git",
|
|
".hg",
|
|
".svn",
|
|
".venv",
|
|
"venv",
|
|
"__pycache__",
|
|
".pytest_cache",
|
|
".mypy_cache",
|
|
".ruff_cache",
|
|
"node_modules",
|
|
"dist",
|
|
"build",
|
|
}
|
|
|
|
|
|
LIST_DIRECTORY_PARAMETERS: dict[str, Any] = {
|
|
"type": "object",
|
|
"properties": {
|
|
"path": {
|
|
"type": "string",
|
|
"default": ".",
|
|
"description": "Directory path relative to the current workspace. Absolute paths are allowed only if they stay inside the workspace.",
|
|
},
|
|
"recursive": {
|
|
"type": "boolean",
|
|
"default": False,
|
|
"description": "Whether to recursively list child entries. Symlink directories are not followed.",
|
|
},
|
|
"max_entries": {
|
|
"type": "integer",
|
|
"default": 200,
|
|
"minimum": 1,
|
|
"maximum": MAX_LIST_ENTRIES,
|
|
"description": "Maximum number of entries to return.",
|
|
},
|
|
},
|
|
"required": [],
|
|
}
|
|
|
|
READ_FILE_PARAMETERS: dict[str, Any] = {
|
|
"type": "object",
|
|
"properties": {
|
|
"path": {
|
|
"type": "string",
|
|
"description": "File path relative to the current workspace. Absolute paths are allowed only if they stay inside the workspace.",
|
|
},
|
|
"start_line": {
|
|
"type": "integer",
|
|
"default": 1,
|
|
"minimum": 1,
|
|
"description": "1-based line number to start reading from.",
|
|
},
|
|
"max_lines": {
|
|
"type": "integer",
|
|
"default": 200,
|
|
"minimum": 1,
|
|
"maximum": MAX_READ_LINES,
|
|
"description": "Maximum number of lines to read.",
|
|
},
|
|
},
|
|
"required": ["path"],
|
|
}
|
|
|
|
SEARCH_FILES_PARAMETERS: dict[str, Any] = {
|
|
"type": "object",
|
|
"properties": {
|
|
"query": {
|
|
"type": "string",
|
|
"description": "Plain text query to search in file paths and UTF-8 text files.",
|
|
},
|
|
"path": {
|
|
"type": "string",
|
|
"default": ".",
|
|
"description": "Directory or file path relative to the current workspace.",
|
|
},
|
|
"max_results": {
|
|
"type": "integer",
|
|
"default": 50,
|
|
"minimum": 1,
|
|
"maximum": MAX_SEARCH_RESULTS,
|
|
"description": "Maximum number of matches to return.",
|
|
},
|
|
"case_sensitive": {
|
|
"type": "boolean",
|
|
"default": False,
|
|
"description": "Whether search should be case-sensitive.",
|
|
},
|
|
},
|
|
"required": ["query"],
|
|
}
|
|
|
|
|
|
class WorkspacePathError(ValueError):
|
|
"""Raised when a requested path escapes the configured workspace."""
|
|
|
|
|
|
def _json_result(success: bool, **payload: Any) -> str:
|
|
return json.dumps({"success": success, **payload}, ensure_ascii=False, indent=2)
|
|
|
|
|
|
def _clamp_int(value: Any, *, default: int, minimum: int, maximum: int) -> int:
|
|
try:
|
|
parsed = int(value)
|
|
except (TypeError, ValueError):
|
|
parsed = default
|
|
return max(minimum, min(parsed, maximum))
|
|
|
|
|
|
def _workspace_root(workspace: str | None) -> Path:
|
|
if not workspace:
|
|
raise WorkspacePathError("workspace is not configured for filesystem tools")
|
|
root = Path(workspace).expanduser().resolve(strict=True)
|
|
if not root.is_dir():
|
|
raise WorkspacePathError(f"workspace is not a directory: {root}")
|
|
return root
|
|
|
|
|
|
def _resolve_existing_path(workspace: str | None, user_path: str | None) -> tuple[Path, Path]:
|
|
"""Resolve a user path and ensure the real target stays inside workspace."""
|
|
|
|
root = _workspace_root(workspace)
|
|
raw_path = Path(user_path or ".").expanduser()
|
|
candidate = raw_path if raw_path.is_absolute() else root / raw_path
|
|
resolved = candidate.resolve(strict=True)
|
|
try:
|
|
resolved.relative_to(root)
|
|
except ValueError as exc:
|
|
raise WorkspacePathError(
|
|
f"path escapes workspace: {user_path or '.'}"
|
|
) from exc
|
|
return root, resolved
|
|
|
|
|
|
def _relative_path(root: Path, path: Path) -> str:
|
|
try:
|
|
return str(path.relative_to(root)) or "."
|
|
except ValueError:
|
|
return str(path)
|
|
|
|
|
|
def _entry_type(path: Path) -> str:
|
|
if path.is_symlink():
|
|
return "symlink"
|
|
if path.is_dir():
|
|
return "directory"
|
|
if path.is_file():
|
|
return "file"
|
|
return "other"
|
|
|
|
|
|
def _entry_payload(root: Path, path: Path) -> dict[str, Any]:
|
|
try:
|
|
stat = path.lstat() if path.is_symlink() else path.stat()
|
|
size = stat.st_size
|
|
except OSError:
|
|
size = None
|
|
return {
|
|
"name": path.name,
|
|
"path": _relative_path(root, path),
|
|
"type": _entry_type(path),
|
|
"size": size,
|
|
}
|
|
|
|
|
|
def _iter_directory(root: Path, directory: Path, *, recursive: bool) -> Iterable[Path]:
|
|
def sort_key(item: Path) -> tuple[bool, str]:
|
|
is_real_directory = not item.is_symlink() and item.is_dir()
|
|
return (not is_real_directory, item.name.lower())
|
|
|
|
entries = sorted(directory.iterdir(), key=sort_key)
|
|
for entry in entries:
|
|
yield entry
|
|
if not recursive or entry.is_symlink() or not entry.is_dir():
|
|
continue
|
|
yield from _iter_directory(root, entry, recursive=True)
|
|
|
|
|
|
def _looks_binary(path: Path) -> bool:
|
|
try:
|
|
with path.open("rb") as handle:
|
|
sample = handle.read(4096)
|
|
except OSError:
|
|
return True
|
|
return b"\0" in sample
|
|
|
|
|
|
def _read_text_file(path: Path) -> str:
|
|
if _looks_binary(path):
|
|
raise ValueError("binary files cannot be read by read_file/search_files")
|
|
return path.read_text(encoding="utf-8")
|
|
|
|
|
|
def _iter_search_files(root: Path, start: Path) -> Iterable[Path]:
|
|
if start.is_file():
|
|
yield start
|
|
return
|
|
|
|
stack = [start]
|
|
visited = 0
|
|
while stack and visited < MAX_SEARCH_FILES:
|
|
current = stack.pop()
|
|
try:
|
|
children = sorted(current.iterdir(), key=lambda item: item.name.lower())
|
|
except OSError:
|
|
continue
|
|
|
|
for child in children:
|
|
if child.is_symlink():
|
|
continue
|
|
if child.is_dir():
|
|
if child.name in SKIP_DIR_NAMES:
|
|
continue
|
|
stack.append(child)
|
|
continue
|
|
if child.is_file():
|
|
visited += 1
|
|
yield child
|
|
if visited >= MAX_SEARCH_FILES:
|
|
break
|
|
|
|
|
|
@dataclass(slots=True)
|
|
class ListDirectoryTool:
|
|
"""List files and directories inside the current workspace."""
|
|
|
|
name: str = "list_directory"
|
|
description: str = (
|
|
"List files and directories inside the current workspace. "
|
|
"Use this before reading files when you need to inspect project structure. "
|
|
"This tool never follows paths outside the workspace."
|
|
)
|
|
toolset: str = "filesystem"
|
|
always_available: bool = True
|
|
workspace: str | None = None
|
|
parameters: dict[str, Any] = field(default_factory=lambda: dict(LIST_DIRECTORY_PARAMETERS))
|
|
|
|
async def execute(
|
|
self,
|
|
*,
|
|
path: str = ".",
|
|
recursive: bool = False,
|
|
max_entries: int = 200,
|
|
workspace: str | None = None,
|
|
) -> str:
|
|
try:
|
|
root, resolved = _resolve_existing_path(workspace, path)
|
|
if not resolved.is_dir():
|
|
return _json_result(False, error="not_a_directory", path=path)
|
|
|
|
limit = _clamp_int(max_entries, default=200, minimum=1, maximum=MAX_LIST_ENTRIES)
|
|
entries: list[dict[str, Any]] = []
|
|
truncated = False
|
|
for entry in _iter_directory(root, resolved, recursive=bool(recursive)):
|
|
entries.append(_entry_payload(root, entry))
|
|
if len(entries) >= limit:
|
|
truncated = True
|
|
break
|
|
|
|
return _json_result(
|
|
True,
|
|
path=_relative_path(root, resolved),
|
|
recursive=bool(recursive),
|
|
entries=entries,
|
|
truncated=truncated,
|
|
)
|
|
except (OSError, WorkspacePathError, ValueError) as exc:
|
|
return _json_result(False, error=str(exc), path=path)
|
|
|
|
|
|
@dataclass(slots=True)
|
|
class ReadFileTool:
|
|
"""Read a UTF-8 text file inside the current workspace."""
|
|
|
|
name: str = "read_file"
|
|
description: str = (
|
|
"Read a UTF-8 text file inside the current workspace with line limits. "
|
|
"Use this to inspect source code, docs, config, or logs. "
|
|
"This tool rejects binary files and paths outside the workspace."
|
|
)
|
|
toolset: str = "filesystem"
|
|
always_available: bool = True
|
|
workspace: str | None = None
|
|
parameters: dict[str, Any] = field(default_factory=lambda: dict(READ_FILE_PARAMETERS))
|
|
|
|
async def execute(
|
|
self,
|
|
*,
|
|
path: str,
|
|
start_line: int = 1,
|
|
max_lines: int = 200,
|
|
workspace: str | None = None,
|
|
) -> str:
|
|
try:
|
|
root, resolved = _resolve_existing_path(workspace, path)
|
|
if not resolved.is_file():
|
|
return _json_result(False, error="not_a_file", path=path)
|
|
|
|
start = _clamp_int(start_line, default=1, minimum=1, maximum=10_000_000)
|
|
limit = _clamp_int(max_lines, default=200, minimum=1, maximum=MAX_READ_LINES)
|
|
content = _read_text_file(resolved)
|
|
lines = content.splitlines()
|
|
selected = lines[start - 1 : start - 1 + limit]
|
|
selected_text = "\n".join(selected)
|
|
char_truncated = False
|
|
if len(selected_text) > MAX_READ_CHARS:
|
|
selected_text = selected_text[:MAX_READ_CHARS]
|
|
char_truncated = True
|
|
|
|
end_line = start + len(selected) - 1 if selected else start - 1
|
|
return _json_result(
|
|
True,
|
|
path=_relative_path(root, resolved),
|
|
start_line=start,
|
|
end_line=end_line,
|
|
total_lines=len(lines),
|
|
truncated=end_line < len(lines) or char_truncated,
|
|
content=selected_text,
|
|
)
|
|
except UnicodeDecodeError:
|
|
return _json_result(False, error="file is not valid UTF-8 text", path=path)
|
|
except (OSError, WorkspacePathError, ValueError) as exc:
|
|
return _json_result(False, error=str(exc), path=path)
|
|
|
|
|
|
@dataclass(slots=True)
|
|
class SearchFilesTool:
|
|
"""Search filenames and UTF-8 text file contents inside the workspace."""
|
|
|
|
name: str = "search_files"
|
|
description: str = (
|
|
"Search file paths and UTF-8 text file contents inside the current workspace. "
|
|
"Use this to find relevant source files, docs, config keys, or log lines. "
|
|
"This tool skips large/binary files and never searches outside the workspace."
|
|
)
|
|
toolset: str = "filesystem"
|
|
always_available: bool = True
|
|
workspace: str | None = None
|
|
parameters: dict[str, Any] = field(default_factory=lambda: dict(SEARCH_FILES_PARAMETERS))
|
|
|
|
async def execute(
|
|
self,
|
|
*,
|
|
query: str,
|
|
path: str = ".",
|
|
max_results: int = 50,
|
|
case_sensitive: bool = False,
|
|
workspace: str | None = None,
|
|
) -> str:
|
|
try:
|
|
if not isinstance(query, str) or not query.strip():
|
|
return _json_result(False, error="query must be a non-empty string")
|
|
root, resolved = _resolve_existing_path(workspace, path)
|
|
if not resolved.is_dir() and not resolved.is_file():
|
|
return _json_result(False, error="path must be a file or directory", path=path)
|
|
|
|
limit = _clamp_int(max_results, default=50, minimum=1, maximum=MAX_SEARCH_RESULTS)
|
|
needle = query if case_sensitive else query.lower()
|
|
results: list[dict[str, Any]] = []
|
|
searched_files = 0
|
|
skipped_files = 0
|
|
|
|
for file_path in _iter_search_files(root, resolved):
|
|
relative = _relative_path(root, file_path)
|
|
haystack_path = relative if case_sensitive else relative.lower()
|
|
if needle in haystack_path:
|
|
results.append(
|
|
{
|
|
"path": relative,
|
|
"line": None,
|
|
"match_type": "path",
|
|
"preview": relative,
|
|
}
|
|
)
|
|
if len(results) >= limit:
|
|
break
|
|
|
|
try:
|
|
if file_path.stat().st_size > MAX_SEARCH_FILE_BYTES or _looks_binary(file_path):
|
|
skipped_files += 1
|
|
continue
|
|
text = file_path.read_text(encoding="utf-8")
|
|
except (OSError, UnicodeDecodeError):
|
|
skipped_files += 1
|
|
continue
|
|
|
|
searched_files += 1
|
|
lines = text.splitlines()
|
|
for index, line in enumerate(lines, start=1):
|
|
haystack_line = line if case_sensitive else line.lower()
|
|
if needle not in haystack_line:
|
|
continue
|
|
results.append(
|
|
{
|
|
"path": relative,
|
|
"line": index,
|
|
"match_type": "content",
|
|
"preview": line[:500],
|
|
}
|
|
)
|
|
if len(results) >= limit:
|
|
break
|
|
if len(results) >= limit:
|
|
break
|
|
|
|
return _json_result(
|
|
True,
|
|
query=query,
|
|
path=_relative_path(root, resolved),
|
|
results=results,
|
|
truncated=len(results) >= limit,
|
|
searched_files=searched_files,
|
|
skipped_files=skipped_files,
|
|
)
|
|
except (OSError, WorkspacePathError, ValueError) as exc:
|
|
return _json_result(False, error=str(exc), path=path)
|