同一个目录输入两遍,列表仍然只有一条——这是设计行为,不是 bug。 DeepSeek Harness 以规范化后的目录路径作为工作区身份:通过 fs.realpath 解析符号链接、.. 和末尾斜杠,再按最终字符串是否相等判断唯一性。软链与目标目录的解析结果相同,因此第二次添加会命中已有记录。
更需要记住的是命中之后的行为:不会创建第二条记录,也不会将新传入的标题应用到旧记录。 这正是「以为添加成功」和「以为标题已改好」两种误解的来源。
先明确一点:这里讨论的是注册表的行为。客户端如何展示结果、是否给出提示,是另一回事,不能据此推断注册表做了什么。
结论先行:比较的到底是什么
| 项目 | 在文档模型里的作用 | 对「重复添加」的影响 |
|---|---|---|
| 输入路径 | 用户提供的完整目录路径 | 不同文本可能解析到同一路径 |
| 规范路径 | 解析后用于目录身份的路径 | 规范字符串相同就命中现有记录 |
| 工作区 ID | 持久记录的稳定标识 | 返回的旧记录保留原 ID |
| 标题 | 显示标签 | 不同记录可以使用相同标题 |
| 会话 cwd | 会话头里不可变的工作目录 | 附加时用同一套规范化规则校验 |
读这张表时,先记住一点:标题不是唯一性依据。 两个不同目录可以使用同一个标题;同一个目录即使第二次传入不同标题,也仍会返回原记录,且标题不变。
一、一次「添加」实际发生了什么
官方工作区参考将工作区定义为一条持久记录,包含四项:稳定 ID、规范路径、显示标题,以及有序的会话归属。
添加操作调用注册表的 create(path, title?)。文档规定:
- 路径规范化后已对应一条记录 → 返回现有实体,保持不变;
- 不创建第二条记录;
- 不写入新标题。
这里容易产生一个误解:「我以为自己改了名字。」标题可以独立于路径身份修改,因此需要单独修改标题,再次添加同一目录不会改名。此外,重复标题本身也被允许——标题从来不是身份标识。
普通创建还有两项硬要求:必须提供完整路径,且目录必须存在。 路径不存在时会保留原始的 ENOENT;目标存在但不是目录,也会被拒绝。因此,「添加悬空软链失败」不能理解为「去重成功」——两者是不同情况:前者是失败,后者则是不需要再添加。
还要区分普通创建与「默认工作区初始化」:后者只在符合条件时递归创建缺失目录,并以请求路径的最后一段作为初始标题。这不代表任意添加一个不存在的目录都会自动创建。
二、第一次使用 Web UI,容易误判的两件事
Web UI 入门说明了入口:全新 Web UI 在「添加并选中工作区」之前没有选中项,会话输入框不可用。
由此容易产生两种误判:
- 启动进程时所在的目录只是「默认文件系统位置」。 有默认位置,不等于已经选中一条工作区记录。输入框无法输入时,先确认是否尚未选中工作区,而不是先怀疑页面故障。
- 选中的是记录,不是路径字符串。 界面上两种看起来不同的写法,可能对应同一条记录;两条标题相同的记录,也可能对应不同目录。判断依据始终是目录身份。
选择和选中的完整流程,参见 会话开始前先选工作区。
三、如何排查「意外的重复」
按以下五步依次检查:
- 记下两次使用的路径写法,以及预期指向的项目。 分享时先对私人目录名脱敏,并确认 UI 中实际选中的是哪条记录。
- 使用所在平台的文件系统工具确认路径是否为软链,以及它解析到哪个现有目录。 参考文档用
fs.realpath定义身份,但没有规定跨平台的检查 shell 命令,因此不要把某条命令的输出当作规范答案。 - 比较解析后的目录身份。 规范字符串相同,文档预测会返回原有工作区且不作修改;此时直接选中该记录即可,不必反复添加别名。
- 如果本意是创建两个独立项目,先确认两条路径最终解析为两个不同的现有目录。修改显示标题或路径文本,都不能证明目录不同。
- 如果解析失败,检查目标是否缺失、路径组件是否不可访问,或目标是否根本不是目录。先恢复目录或修正选择,再重试普通注册。
报告问题时,同时保存原始写法和解析结果。只说「我添加了两次,却只出现一条」,再配一张标题截图,对方仍无法判断两次注册是否指向同一规范路径。
还要留意时间变化带来的问题:一条曾经解析到某个目标的路径,在软链被修改后可能不再指向该目标。 因此应检查当前文件系统状态,而不是沿用上次的结论。
四、会话 cwd 如何校验
这一层的校验比多数人想的更严格。API gateway 为所选工作区创建会话时,会依次:
- 使用工作区路径作为新会话的 cwd;
- 将其写入不可变的会话头;
- 调用
attachSession。
附加过程使用同一套规范化规则,对照保存的会话 cwd 与工作区路径。新附加要求 cwd 能解析到一个匹配的现有目录;缺失或不匹配的路径不能作为新会话加入。
已经归属的候选会话遵循另一条规则,值得单独记住:如果其完整 cwd 在路径解析或目录状态检查中遇到 ENOENT(包括悬空软链),既有候选会保留;而会话头缺失、cwd 无效或规范路径不匹配的候选会被过滤。之后被接受的修改会清理这些被过滤的候选,但不会清理因目录缺失而保留的候选。
注意这条规则的边界:保留归属不会创建目录,也不允许在目录缺失期间新增会话。「仍在列表里」和「当前可用」是两回事。
会话、工作区与 agent 之间的关系,参见 会话与 agent 的关系。
五、目录消失后,记录为什么还在
工作区创建后保存的规范路径不会被重写,即使目录后来消失也一样。不带缓存调用 status():路径当前存在且是目录时返回 ok,否则返回 missing-dir。
这一设计可以区分「保留的记录」与「当前可用的目录」,但不会自动跟踪被移动的项目,也不会修复已修改的链接。要让记录恢复可用,需要把目录放回原处或重新选择。
要按工作区重新关联历史会话,可看 会话引用:把相关会话连起来;要按事件回查历史,可看 查询已有会话与事件。
六、该不该删除或改名
- 修改标题是安全的:标题可以独立于路径身份修改,重复标题也允许。修改标题能让选择器更易读,但不能把一个规范目录拆成两个工作区。
- 删除注册会移除注册、排序项和会话归属;它不会删除目录、文件、实时会话或持久日志——那些会话会变成
Ungrouped。 - 因此,删除注册 ≠ 删除项目目录,但确实会改变工作区的组织方式。不要只因看到一个别名就立刻删除,应先确认当前归属和预期结果。
开始新任务时,选择那条「规范目录正确」的已有记录;查看历史会话时,检查其当前归属和会话头 cwd,不要假设标题或软链会自动决定归属。归属依据是注册表保存的有序会话清单,cwd 用于校验成员关系——每次读取时不会据此重新推导整张清单。
七、安全边界(这段不能省)
- 文档规定的是「规范路径字符串相等」,并没有为所有文件系统别名、平台大小写行为或网络文件系统建立通用规则。 如果相同写法在不同环境中表现不同,应先检查实际环境和安装版本。
- 软链是路径解析问题,不是权限机制。 来源没有声称软链能阻止 Agent 访问文件,也没有把它当作访问控制边界。
- 分享诊断信息时,应将目录路径和会话元数据视为可能包含私人信息的内容。
- 保留归属不证明文件仍存在:「保留缺失工作区」或「保留会话归属」都不能证明文件仍然存在;反过来,删除注册也无法修复缺失的目录。
- 修改链接或移动项目文件之前,先核实实际目标;否则改变的是「以后如何解析」,不是「现在有什么」。
术语
- 符号链接:路径规范化时需要解析目标的文件系统链接。
- 规范路径:作为工作区身份保存的解析后目录路径。
- 工作区 ID:独立于显示标题的稳定记录标识。
- 会话 cwd:保存在会话头中、附加会话时用于校验的工作目录。
Ungrouped:删除工作区注册后,会话不再归属该工作区的状态。
排查清单
- 两次添加是否指向同一个规范目录?先解析,再下结论。
- 查的是当前文件系统状态,还是沿用上次的结论?
- 是否把屏幕上显示的标题当成了身份?
- 添加后没有变化,会不会是命中了已有记录,而标题本来就不会被覆盖?
- 输入框无法输入,是因为尚未选中工作区,还是另有原因?
- 添加悬空软链失败了——是否把它误当成「去重成功」?
- 想要两个独立工作区,是否确认它们解析到两个不同的现有目录?
- 会话 cwd 缺失时,是否区分了「归属被保留」和「还能新建会话」?
- 删除注册前,是否确认它不会删除目录、文件、实时会话和日志?
- 是否把软链说成了访问控制手段?
相关阅读
本文依据 DeepSeek Harness 官方工作区参考与 Web UI 入门整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
插件与文档收录于:https://dsh-plugin.com/zh/blog