类class agentscope.tool

Edit

class Edit(ToolBase)

源码Source agentscope/tool/_builtin/_edit.py:26–455

Edit，让智能体以受控方式调用外部能力。位于 agentscope.tool 包，继承自 ToolBase。核心成员包括 check_permissions、match_rule、generate_suggestions、call。

The edit tool for performing exact string replacements in files. Declared in agentscope.tool. Extends ToolBase.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`def __init__(dangerous_files: list[str] = DEFAULT_DANGEROUS_FILES, dangerous_directories: list[str] = DEFAULT_DANGEROUS…`	初始化 `Edit` 实例。 Initialize the edit tool.

属性摘要Attribute Summary

属性Attribute	类型Type	说明Description	值Value
`name`	str	名称字段。	`'Edit'`
`description`	str	`description` 字段。	'Performs exact string replacements in files.\n\nUsage:\n- You must use your `Read` tool at least once in the conversation\n before editing. This tool will error if you attempt an edit without\n reading the file.\n- When editing text from Read tool output, ensure you preserve the\n exact indentation (tabs/spaces) as it appears AFTER the line number\n prefix. The line number prefix format is: line number + tab.\n Everything after that is the actual file content to match. Never\n include any part of the line number prefix in the old_string or\n new_string.\n- ALWAYS prefer editing existing files in the codebase. NEVER write\n new files unless explicitly required.\n- Only use emojis if the user explicitly requests it. Avoid adding\n emojis to files unless asked.\n- The edit will FAIL if `old_string` is not unique in the file.'
`input_schema`	dict[str, Any]	输入模式字段。	{'type': 'object', 'properties': {'file_path': {'type': 'string', 'description': 'The absolute path to the file to edit.'}, 'old_string': {'type': 'string', 'minLength': 1, 'description': 'The nonempty string to replace. Must match exactly including whitespace and indentation.'}, 'new_string': {'type': 'string', 'description': 'The string to replace old_string with.'}, 'replace_all': {'type': 'boolean', 'description': 'If true, replace all occurrences. If false (default), only replace if there is exactly one occurrence.', 'default': False}}, 'required': ['file_path', 'old_string', 'new_string']}
`is_mcp`	bool	是 MCP字段。	`False`
`is_read_only`	bool	`is_read_only` 字段。	`False`
`is_concurrency_safe`	bool	`is_concurrency_safe` 字段。	`False`
`is_external_tool`	bool	是外部工具字段。	`False`
`is_state_injected`	bool	`is_state_injected` 字段。	`True`

方法摘要Method Summary

方法Method	说明Description
`async def check_permissions(tool_input: dict[str, Any], context:` `PermissionContext) -> PermissionDecision`async	检查权限。 Check permissions for file editing.
`async def match_rule(rule_content: str \| None, tool_input: dict[str, Any]) -> bool`async	执行 `match_rule` 方法。 Check if a permission rule matches the file path.
`async def generate_suggestions(tool_input: dict[str, Any]) -> List[PermissionRule]`async	设置该参数。 Generate suggested permission rules for the file path.
`async def call(file_path: str, old_string: str, new_string: str, replace_all: bool = False, _agent_state:` `AgentState \|…`async	向智能体发送输入并返回最终回复。 Execute the edit and return the result.

构造器详情Constructor Detail

Edit

def __init__(dangerous_files: list[str] = DEFAULT_DANGEROUS_FILES, dangerous_directories: list[str] = DEFAULT_DANGEROUS_DIRECTORIES, middlewares: List[ToolMiddlewareBase] | None = None, backend: BackendBase | None = None) -> None

初始化 Edit 实例。

Initialize the edit tool.

参数Parameters

名称Name	类型Type	说明Description
`dangerous_files`默认default `DEFAULT_DANGEROUS_FILES`	list[str]	dangerous 文件（类型 `list[str]`）。Sensitive files that require explicit user confirmation, even in BYPASS mode. Matched by basename (case-insensitive). Defaults to `DEFAULT_DANGEROUS_FILES`. Pass a custom list to fully replace the defaults, or `[]` to disable the filename check.
`dangerous_directories`默认default `DEFAULT_DANGEROUS_DIRECTORIES`	list[str]	dangerous directories（类型 `list[str]`）。Sensitive directories that require explicit user confirmation. Matched when any path segment equals an entry (case-insensitive). Defaults to `DEFAULT_DANGEROUS_DIRECTORIES`. Pass a custom list to fully replace the defaults, or `[]` to disable the directory check.
`middlewares`默认default `None`	List[ToolMiddlewareBase] \| None	中间件列表（类型 `List[ToolMiddlewareBase] \| None`）。Tool middlewares wrapping the tool execution.
`backend`默认default `None`	BackendBase \| None	backend（类型 `BackendBase \| None`）。The sandbox backend to use for file I/O. When `None`, a :class:`LocalBackend` is created.

源码Source agentscope/tool/_builtin/_edit.py:89–123

属性详情Attribute Detail

name

str = 'Edit'

名称字段。声明为 str。

The name field.

源码Source agentscope/tool/_builtin/_edit.py:29

description

str = 'Performs exact string replacements in files.\n\nUsage:\n- You must use your `Read` tool at least once in the conversation\n  before editing. This tool will error if you attempt an edit without\n  reading the file.\n- When editing text from Read tool output, ensure you preserve the\n  exact indentation (tabs/spaces) as it appears AFTER the line number\n  prefix. The line number prefix format is: line number + tab.\n  Everything after that is the actual file content to match. Never\n  include any part of the line number prefix in the old_string or\n  new_string.\n- ALWAYS prefer editing existing files in the codebase. NEVER write\n  new files unless explicitly required.\n- Only use emojis if the user explicitly requests it. Avoid adding\n  emojis to files unless asked.\n- The edit will FAIL if `old_string` is not unique in the file.'

description 字段。声明为 str。

The description field.

源码Source agentscope/tool/_builtin/_edit.py:32

input_schema

dict[str, Any] = {'type': 'object', 'properties': {'file_path': {'type': 'string', 'description': 'The absolute path to the file to edit.'}, 'old_string': {'type': 'string', 'minLength': 1, 'description': 'The nonempty string to replace. Must match exactly including whitespace and indentation.'}, 'new_string': {'type': 'string', 'description': 'The string to replace old_string with.'}, 'replace_all': {'type': 'boolean', 'description': 'If true, replace all occurrences. If false (default), only replace if there is exactly one occurrence.', 'default': False}}, 'required': ['file_path', 'old_string', 'new_string']}

输入模式字段。声明为 dict[str, Any]。

The input schema field.

源码Source agentscope/tool/_builtin/_edit.py:51

is_mcp

bool = False

是 MCP字段。声明为 bool。

The is mcp field.

源码Source agentscope/tool/_builtin/_edit.py:83

is_read_only

bool = False

is_read_only 字段。声明为 bool。

The is read only field.

源码Source agentscope/tool/_builtin/_edit.py:84

is_concurrency_safe

bool = False

is_concurrency_safe 字段。声明为 bool。

The is concurrency safe field.

源码Source agentscope/tool/_builtin/_edit.py:85

is_external_tool

bool = False

是外部工具字段。声明为 bool。

The is external tool field.

源码Source agentscope/tool/_builtin/_edit.py:86

is_state_injected

bool = True

is_state_injected 字段。声明为 bool。

The is state injected field.

源码Source agentscope/tool/_builtin/_edit.py:87

方法详情Method Detail

check_permissions

async def check_permissions(tool_input: dict[str, Any], context: PermissionContext) -> PermissionDecision

async

检查权限。

This method implements Edit-specific permission checks: 1.

参数Parameters

名称Name	类型Type	说明Description
`tool_input`	dict[str, Any]	工具输入（类型 `dict[str, Any]`）。The tool input containing "file_path" key
`context`	PermissionContext	权限上下文使用模式和规则。The permission context with mode and rules

返回Returns PermissionDecision

返回PermissionDecision。`PermissionDecision`:

源码Source agentscope/tool/_builtin/_edit.py:125–187

match_rule

async def match_rule(rule_content: str | None, tool_input: dict[str, Any]) -> bool

async

执行 match_rule 方法。

Matches rule_content as a glob pattern against the "file_path" parameter using fnmatch.

参数Parameters

名称Name	类型Type	说明Description
`rule_content`	str \| None	规则内容（类型 `str \| None`）。Glob pattern to match against the file path (e.g., "src/**"), or None to match all invocations
`tool_input`	dict[str, Any]	工具输入（类型 `dict[str, Any]`）。The tool input data containing "file_path" key

返回Returns bool

返回布尔值，表示判断结果。`bool`:

源码Source agentscope/tool/_builtin/_edit.py:189–217

generate_suggestions

async def generate_suggestions(tool_input: dict[str, Any]) -> List[PermissionRule]

async

设置该参数。

Suggests a glob pattern covering the parent directory of the file, allowing the user to grant permission for the entire directory at once.

参数Parameters

名称Name	类型Type	说明Description
`tool_input`	dict[str, Any]	工具输入（类型 `dict[str, Any]`）。The tool input data containing "file_path" key

返回Returns List[PermissionRule]

返回PermissionRule列表。`List[PermissionRule]`:

源码Source agentscope/tool/_builtin/_edit.py:219–256

call

async def call(file_path: str, old_string: str, new_string: str, replace_all: bool = False, _agent_state: AgentState | None = None) -> ToolChunk

async

向智能体发送输入并返回最终回复。

Execute the edit and return the result.

参数Parameters

名称Name	类型Type	说明Description
`file_path`	str	文件路径（类型 `str`）。The file path.
`old_string`	str	旧的 string（类型 `str`）。The old string.
`new_string`	str	新建 string（类型 `str`）。The new string.
`replace_all`默认default `False`	bool	replace 所有（类型 `bool`）。The replace all.
`_agent_state`默认default `None`	AgentState \| None	智能体状态（类型 `AgentState \| None`）。The agent state.

返回Returns ToolChunk

返回ToolChunk。Returns tool chunk.

源码Source agentscope/tool/_builtin/_edit.py:258–455

继承成员Inherited Members

继承自Inherited from ToolBase

__call__, check_external_result, check_read_only, metadata_schema, mcp_name, dangerous_files, dangerous_directories