Skip to content

第 5 章 装进一个工作区:LocalWorkspace ​

本章代码 code/ch05/main.py · 读完约 14 分钟

5.0 上一章留下的问题 ​

第 4.2 节讲权限的时候,我们写了个十来行的函数 safe_path。它干的事很单一,就是把模型给的路径拼回根目录,resolve() 展开 .. 和软链接,再校验一次有没有越过我们划定的界线。

但这套做法留了两个 bug。

第一个 bug 是 Bash。它收的不是路径,是一整条命令——cd / 一句话就出去了。校验路径的办法,对它无效。

第二个 bug 是"每个工具都得自己拦一遍路径"。Read、Write、Edit、Glob、Grep,漏掉哪一个,bug 就出在哪一个身上。

这一章,我们想让工具都在一个指定的工作区里工作。它和上一章那套做法只差一件事,边界由谁来保证。

上一章是代码级的。校验塞在每个工具里面,safe_path 在路径进来时看一眼,越界就拒。工具还是原来那些工具,只是在外面裹了一层。

工作区是环境级的。边界不在代码里,在工具跑的那个文件系统上。Bash 里 cd / 之后看见的世界,由执行环境决定,不由提示词决定。

别急着高兴。"环境级"这话是对工作区这个概念说的,落到具体实现上,强弱差得远。

事实上,对于企业而言,常常会把 agent 放在沙箱里执行,如果你了解沙箱的概念,这一章会很好懂。

但考虑到读者的水平有差异,我们还是选了隔离不那么强的 LocalWorkspace,为的是让更多人先摸清"工作区"这个概念。本机开发用它最省事,工具成套,还带一段现成的提示词。真要隔离,换成沙箱工作区就行,API 基本一样,迁移起来没什么成本。

如果你经常用 workbuddy,会发现它会让你选一个文件夹当工作空间,和我们这一章的工作区是同一个原理。

先看最常用的 LocalWorkspace,它并不能把模型关起来。

它做的事只有一件,给工具定一个起点。Bash 在这个目录里启动,相对路径从这个目录开始算。所以模型敲 ls、敲 python fizz.py,看见的确实是工作区里的东西,看着挺像个笼子。但实际上这个笼子并不太安全,只要模型改一下路径就能跳过你划定的工作区,后面的章节会讲怎么用工程化的方法,让 agent 在工作区里不出界。

5.1 工作区是什么 ​

Workspace 在 AgentScope 里不是"一个文件夹",而是智能体的运行环境。它负责三件事:

工作区的边界

1. 提供工具。 你不再手写 Read()、Write()、Bash()。工作区会根据当前平台自动给你一套,而且都绑在同一个后端上——Bash 的 cwd 锚在 workdir,读写走工作区的后端。至于这个后端是"你家那块盘"还是"容器里的盘",取决于你选哪种工作区。

2. 提供技能。 skills/ 目录下可以放 Markdown 指令集,让智能体按需查阅(第 15 章会提)。

3. 承接上下文卸载。 第 8 章会讲,被压缩掉的对话和被截断的工具结果,会卸载到 sessions/ 目录。原文没丢,智能体需要时可以自己去翻。

还有一件容易被忽略的事:工作区会自动生成一段系统提示,告诉模型这里有什么目录、该怎么组织项目、该怎么用 git。

5.2 用起来 ​

python
from agentscope.workspace import LocalWorkspace
from agentscope.tool import Toolkit

async with LocalWorkspace(workdir="./sandbox") as workspace:
    tools = await workspace.list_tools()
    instructions = await workspace.get_instructions()

    agent = Agent(
        name="Buddy",
        system_prompt="你叫 Buddy,所有文件操作都必须在工作区内完成。\n\n" + instructions,
        model=build_model(),
        toolkit=Toolkit(tools=tools),
        offloader=workspace,
    )

四行关键代码,逐条说明:

async with LocalWorkspace(...):工作区是异步上下文管理器。进入时初始化目录结构,退出时只把连接关掉,workdir 里的文件留在原地(5.5 会验证这一点)。workdir 是相对路径的话,以当前进程的工作目录为基准。

await workspace.list_tools():注意是 await,它返回一个协程。在我的 Windows 机器上,拿到的是:

['PowerShell', 'Edit', 'Glob', 'Grep', 'Read', 'Write']

在 macOS 和 Linux 上,PowerShell 会换成 Bash。同一份代码跨平台可用,这是工作区抽象带来的第一个好处。

await workspace.get_instructions():返回那段自动生成的提示,约 3000 字符。开头是这样:

<workspace>You have access to a local workspace at
C:\Users\xxxx\Desktop\mini-workbuddy\code\ch05\sandbox with the following structure:

注意它把绝对路径写了进去。这是为了让模型知道自己站在哪。

offloader=workspace:这一行现在看不出效果,到第 8 章上下文压缩被触发时,它的作用才显现。

为什么要把 instructions 拼进 system_promptAgent 不会自动读取工作区的提示,你必须手动拼。漏了这一步,模型不知道自己有 data/、skills/、sessions/ 这三个目录,会在根目录下乱建文件。 提示词不是越长越好,但关于环境的提示不能少,模型看不见你的文件系统,你告诉它什么,它的世界就有多大。

5.3 路径边界是怎么生效的 ​

工作区不是在系统层面做隔离(LocalWorkspace 没有这个能力)。它能做的是两件事,而且两件都很软。

  1. 给工具一个起点。Bash 在这个目录里启动,它敲的相对路径从这里算。这条对 Read/Write 无效,那两个工具只收绝对路径,起点对它们没有意义。
  2. 让权限系统认「工作目录」这个概念。默认模式下,越出工作目录的改动会先问你一句;ACCEPT_EDITS 模式下,工作目录内的改动直接放行,不再打断。

第一件事决定模型从哪儿看,第二件事决定要不要问你一声。至于硬闯,本地这两层都拦不住,得靠容器。5.5 的代码还顺手把模式设成了 BYPASS,连"问一声"也省了,先求跑通,第 7 章再收回来。

下图是七种主流后端的对比(包里还有一种是 macOS 专用的 AppleContainerWorkspace,没画进来)。LocalWorkspace 不提供真正的隔离,它跑在你的系统上,PowerShell 或 Bash 能做的事它都能做,只是被权限规则约束着。

七种工作区后端

LocalWorkspace 适合本地开发和教学——快、直观、文件能直接用编辑器打开看。

但只要这个 Agent 会接受来自他人的输入,就该换成管控更强的隔离环境。原因很简单:容器里 rm -rf / 只是删掉一个容器,本机上 rm -rf / 是另一回事。

5.4 先读后写 ​

第 3 章提过 Write 的"先读后写"规则,现在能说清它的价值了。

设想这个场景:工作区里有一份 config.yaml,模型要"把数据库地址改成新地址"。如果没有这条规则,它可能直接 Write 一份全新的 config.yaml,里面只有数据库地址,其他配置全没了。对于 agent 来说,它没有恶意,它只是没看过原文,以为那文件里只有地址。

有了这条规则,Write 会失败,模型收到"文件已存在但未读取",于是乖乖先 Read,看到全部配置,再用 Edit 做精确替换。

这条规则把"模型必须有完整信息才能改动"编码进了工具的行为里。这是工程约束优于提示词约束的一个案例。

5.5 完整代码 ​

python
"""第 5 章:给 Agent 一个工作区。

比上一章多了什么:
  1. LocalWorkspace:给工具一个起点,并统一提供它们
  2. 工具不再是手写的,而是工作区根据平台自动提供
  3. offloader:把上下文卸载到工作区
"""

import asyncio
import os

from dotenv import load_dotenv

from agentscope.agent import Agent
from agentscope.credential import OpenAICredential
from agentscope.message import UserMsg
from agentscope.model import OpenAIChatModel
from agentscope.permission import PermissionMode
from agentscope.tool import Toolkit
from agentscope.workspace import LocalWorkspace

load_dotenv(override=True)

API_KEY = os.getenv("OPENAI_API_KEY", "")
BASE_URL = os.getenv("OPENAI_BASE_URL", "")
MODEL_NAME = os.getenv("OPENAI_MODEL", "gpt-4o-mini")

WORKDIR = "./sandbox"


def build_model() -> OpenAIChatModel:
    return OpenAIChatModel(
        credential=OpenAICredential(api_key=API_KEY, base_url=BASE_URL or None),
        model=MODEL_NAME,
    )


def prepare_files() -> None:
    """在工作区里放两份材料,供 Agent 阅读。"""
    os.makedirs(WORKDIR, exist_ok=True)
    with open(os.path.join(WORKDIR, "README.md"), "w", encoding="utf-8") as f:
        f.write(
            "# 项目说明\n\n"
            "这是一个用于演示工作区的示例项目。\n"
            "它包含三个模块:采集、清洗、导出。\n"
            "目前采集模块已完成,清洗模块在开发中。\n",
        )
    with open(os.path.join(WORKDIR, "todo.txt"), "w", encoding="utf-8") as f:
        f.write("1. 完成清洗模块\n2. 补充单元测试\n3. 写导出文档\n")


def tree(path: str) -> str:
    """打印目录树,用来确认 Agent 真的写了文件。"""
    lines = []
    for root, dirs, files in os.walk(path):
        dirs[:] = [d for d in dirs if d not in {"__pycache__"}]
        level = root.replace(path, "").count(os.sep)
        lines.append("  " * level + os.path.basename(root) + "/")
        for name in sorted(files):
            lines.append("  " * (level + 1) + name)
    return "\n".join(lines)


async def main() -> None:
    prepare_files()

    # workspace 是异步上下文管理器:进入时初始化目录,退出时只关连接
    async with LocalWorkspace(workdir=WORKDIR) as workspace:
        tools = await workspace.list_tools()
        print("=" * 70)
        print("工作区提供了这些工具:", [t.name for t in tools])
        print("=" * 70)

        instructions = await workspace.get_instructions()
        print(f"工作区还会自动写一段系统提示(共 {len(instructions)} 字符),开头是这样:")
        print("-" * 70)
        print(instructions[:260].strip() + " ……")
        print("-" * 70)
        print()

        agent = Agent(
            name="Buddy",
            system_prompt=(
                "你叫 Buddy,是一个文件管理助手。"
                "所有文件操作都必须在当前工作区内完成,不要访问工作区以外的路径。"
                "\n\n" + instructions
            ),
            model=build_model(),
            toolkit=Toolkit(tools=tools),
            offloader=workspace,  # 上下文被压缩时,原文卸载到这里
        )

        # 命令行脚本没有确认界面,工作区的写操作默认会停下来等人点头。
        # 先整体放行;第 7 章会把这件事重新管起来。
        agent.state.permission_context.mode = PermissionMode.BYPASS

        question = (
            "看一下工作区里有哪些文件,把 README 的内容总结成三行,"
            "然后写入 summary.md。"
        )
        print(f">>> 你:{question}\n")
        reply = await agent.reply(UserMsg(name="user", content=question))
        print(f"<<< Buddy:{reply.get_text_content()}\n")

    # 退出 async with 会调用框架的 LocalWorkspace.close():只关闭 MCP 连接,不删除工作区文件
    print("=" * 70)
    print(f"工作区当前结构({WORKDIR}):")
    print(tree(WORKDIR))


if __name__ == "__main__":
    asyncio.run(main())

运行结果(目录部分是真实的):

工作区提供了这些工具: ['PowerShell', 'Edit', 'Glob', 'Grep', 'Read', 'Write']
工作区还会自动写一段系统提示(共 2955 字符),开头是这样:
----------------------------------------------------------------------
<workspace>You have access to a local workspace at
C:\Users\xxxx\Desktop\mini-workbuddy\code\ch05\sandbox with the following structure:
----------------------------------------------------------------------

>>> 你:看一下工作区里有哪些文件,把 README 的内容总结成三行,然后写入 summary.md。

<<< Buddy:已读取 README.md,总结如下,并已写入 summary.md。

======================================================================
工作区当前结构(./sandbox):
sandbox/
  README.md
  summary.md
  todo.txt

summary.md 是 Agent 自己创建的。退出 async with 之后它还在,因为工作区是持久化的。

这里的 __aexit__ 不在本章代码里,而是 LocalWorkspace 从框架基类继承的,它只调用 LocalWorkspace.close(),把有状态的 MCP 连接关掉,再把 is_alive 置成 False,workdir 里的文件一个都不碰。真正会删文件的是另一个方法 reset(),它清掉 skills/、sessions/、data/ 和 .mcp。

换成 DockerWorkspace 这类沙箱后端,close() 要做的就多了,它得断开网关、停掉并移除容器。本地工作区这么轻,是因为它压根没有容器可收。

现在,我们惊喜地发现,AI 已经能在你的电脑上创建文件啦,距离真正的 agent 帮你干活,越来越近啦~~

5.6 三个常见错误 ​

错误 1:忘了 await

python
tools = workspace.list_tools()      # 拿到一个协程对象
agent = Agent(..., toolkit=Toolkit(tools=tools), ...)

报错信息通常是 'coroutine' object is not iterable。list_tools()、get_instructions()、get_tool_schemas() 全是异步方法。

错误 2:把工作区当成安全边界

LocalWorkspace 只给工具一个起点,既不校验路径,也不隔离进程。模型通过 PowerShell 执行 Get-Content C:\Users\你\Desktop\a.txt 依然可能成功,因为那是命令,不是路径参数;就算走 Read,参数里填一个绝对路径也照开。

真正的隔离需要容器,或者在权限系统里对命令做静态分析(第 7 章)。

错误 3:workdir 用了绝对路径,然后在别的机器上跑

python
LocalWorkspace(workdir="C:/Users/你/Desktop/sandbox")   # 换台机器就废了

除非你确定部署环境固定,否则用相对路径,或者从环境变量读。

5.7 小结 ​

  • 工作区是运行环境,负责提供工具、提供技能、承接上下文卸载
  • list_tools() 按平台给工具,Windows 上是 PowerShell,Linux 上是 Bash
  • 工作区会自动生成约 3000 字符的系统提示,必须手动拼进 system_prompt
  • LocalWorkspace 只给工具一个起点,不校验路径、不隔离进程;要隔离就换 Docker
  • "先读后写"把工程约束编码进了工具行为,比提示词可靠

下一章要解决的问题:工作区给的工具是通用的——读、写、搜、跑命令。但你的业务是具体的:查内部数据库、调某个接口、按公司规则算报价。这些工具,框架没有,得你自己写。

教程正文采用 CC BY-NC-SA 4.0 许可,code/ 下示例代码可自由使用