第 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 用起来
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_prompt
Agent不会自动读取工作区的提示,你必须手动拼。漏了这一步,模型不知道自己有data/、skills/、sessions/这三个目录,会在根目录下乱建文件。 提示词不是越长越好,但关于环境的提示不能少,模型看不见你的文件系统,你告诉它什么,它的世界就有多大。
5.3 路径边界是怎么生效的
工作区不是在系统层面做隔离(LocalWorkspace 没有这个能力)。它能做的是两件事,而且两件都很软。
- 给工具一个起点。
Bash在这个目录里启动,它敲的相对路径从这里算。这条对Read/Write无效,那两个工具只收绝对路径,起点对它们没有意义。 - 让权限系统认「工作目录」这个概念。默认模式下,越出工作目录的改动会先问你一句;
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 完整代码
"""第 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.txtsummary.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
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 用了绝对路径,然后在别的机器上跑
LocalWorkspace(workdir="C:/Users/你/Desktop/sandbox") # 换台机器就废了除非你确定部署环境固定,否则用相对路径,或者从环境变量读。
5.7 小结
- 工作区是运行环境,负责提供工具、提供技能、承接上下文卸载
list_tools()按平台给工具,Windows 上是PowerShell,Linux 上是Bash- 工作区会自动生成约 3000 字符的系统提示,必须手动拼进
system_prompt LocalWorkspace只给工具一个起点,不校验路径、不隔离进程;要隔离就换 Docker- "先读后写"把工程约束编码进了工具行为,比提示词可靠
下一章要解决的问题:工作区给的工具是通用的——读、写、搜、跑命令。但你的业务是具体的:查内部数据库、调某个接口、按公司规则算报价。这些工具,框架没有,得你自己写。
