一、工作区圈住了四件事

工作区（Workspace）这个说法听起来像【打开的文件夹】，其实比那个重得多。 它一次性决定四件事：

• 能看见哪些文件——工作区之外的路径，Agent 根本看不到。
• 能改哪些文件——写操作被圈在工作区里面。
• 命令在哪儿跑——执行命令时的当前目录。
• 会话存在哪——会话与这个工作区绑定。

这四条加起来，就是【Agent 的现实世界】。 世界之外的东西对它来说不存在——不是它不想管，是它看不见。

二、启动目录 ≠ 选中工作区

这里有一对很容易搞混的概念：

• 启动目录：你是在哪个目录敲下 dsh 的。这只是个默认候选。
• 选中工作区：你在界面上明确选中的那一个。

规矩是：没选中工作区之前，会话输入框是灰的。 很多人第一次遇到这个会以为是软件坏了——其实它是在逼你先把地盘圈清楚。

这两个不一致是头号事故原因。官方把【从错误的目录启动】 称为【我的文件不见了】这类问题的第一来源： Agent 老老实实地对着你没想到的那个目录干了活，你当然找不到它改了什么。

三、为什么必须有这一步

把选择工作区做成强制步骤，是安全设计的一部分。

想象一下反过来的设计：Agent 能访问整个硬盘。 那么它能读你的私人文件、能改系统配置、能删掉它理解错的东西。 一个会执行命令的程序，权限范围必须显式约定清楚。

这跟第 1 章讲的【模型没有手】是一对： Harness 给了它手，工作区就是那只手能伸多远。 再往后，第 4 章讲 Guard、Approval、Sandbox，第 7 章讲执行环境， 都是在这条线上继续往下做。

四、文件多不怕，怕的是搜索不灵

一个常见的顾虑是：我的项目几千个文件，Agent 会不会撑不住？

不会——因为它不需要把文件全读进来。它靠的是【搜索定位 + 按需读取】： 先在文件列表里搜，找到相关的几个，再只读那几个。

所以真正决定体验的不是【工作区有多大】，而是搜索工具灵不灵。 这也解释了配置树里为什么有这么两项：

• tool-fs-search——专门负责在文件系统里搜。
• tool-fs——负责读和写。

一个负责找，一个负责动。日常的绝大部分时间花在找上， 所以搜索的质量，基本决定了这套东西好不好用。

五、动手 Demo：一个工作区，到底圈住了什么

把工作区决定的事项、和两个目录的区别列清楚：

scope = [
    ("能看见哪些文件", "工作区之外的路径，Agent 根本看不到"),
    ("能改哪些文件", "写操作被圈在工作区里面"),
    ("命令在哪儿跑", "执行命令时的当前目录"),
    ("会话存在哪", "会话与这个工作区绑定"),
]
for k, v in scope:
    print("  %-12s %s" % (k, v))
print()
n = 1000
print("工作区里有 %d 个文件，是不是都要读进来？" % n)
print("  不是——靠搜索定位 + 按需读取，真正读进来的通常只有几十个片段")

实跑输出：

--------------------------------------------------------------------
一个工作区，到底圈住了什么
--------------------------------------------------------------------
  工作区（Workspace）就是 Agent 的【现实世界】。
  没选中工作区之前，会话输入框是灰的——这不是没做好，是有意这么设计的。

  它一次性决定了好几件事：

  决定项             具体含义
  ------------------------------------------------------
  能看见哪些文件     工作区之外的路径，Agent 根本看不到
  能改哪些文件       写操作被圈在工作区里面
  命令在哪儿跑       执行命令时的当前目录
  会话存在哪         会话与这个工作区绑定
  ------------------------------------------------------

  有两个目录很容易搞混，它们是不同的东西：

                 含义                           什么时候用到
  -----------------------------------------------------------------------
  启动目录       你是在哪个目录敲下 dsh 的      只是默认的候选
  选中工作区     你在界面上明确选中的那一个     发第一条消息之前必须选中
  -----------------------------------------------------------------------

  这两个不一致会怎样？Agent 会对着你没想到的目录干活。
  官方把【从错误的目录启动】称为【我的文件不见了】这类问题的头号原因。

  算一笔账：工作区里文件多了，是不是都得塞进上下文？

    工作区文件数        1000 个
    一次塞进上下文？    不。靠搜索定位 + 按需读取
    真正读进来的        通常几十个文件的片段

  所以【工作区大】不等于【上下文爆】——前提是搜索工具顶用。
  这也解释了为什么 Standard 里要挂 tool-fs-search。

四条里最容易忽略的是最后一条：会话跟工作区绑定。 换一个工作区，等于换了一个世界——上一个会话的上下文不会跟过来。 很多人觉得【换个目录接着聊】就行，其实那次对话的记忆是带不走的。

30 秒实验

1. 建一个空目录，专门给这本书的实验用（别拿正式项目试）。
2. 想一下：如果 Agent 能访问整个硬盘，你最担心什么。
3. 挑一个你的真实项目目录，估一下有多少文件——再想这些是不是都要塞进上下文。

常见误区

1. 错误：工作区就是【打开文件夹】。——纠正：它同时是权限边界——读写、执行、会话都绑在它上面。
2. 错误：从哪个目录启动就在哪个目录干活。——纠正：必须显式选中工作区才能开始会话；启动目录只是默认候选。
3. 错误：项目太大就别用它跑 Agent。——纠正：大项目靠搜索定位 + 按需读取，真正读进来的通常只有几十个文件的片段。

• ☐ 下一节（2.3 配置模型）

相关笔记

• 环境准备 —— 上一篇装好，这一篇圈地盘
• 配置模型 —— 下一篇给它接上脑子
• 网页自动化 —— 另一处讲【自动化工具的权限边界在哪】
• 🐳 DeepSeek Harness · 索引