加了软链又加了一遍目录,工作区列表却没多一条:DSH 用规范路径认身份

简介: 工作区的唯一性由**规范化后的目录路径**决定,而不是由输入文本或显示标题决定。因此,「软链 + 真实目录」「末尾是否带斜杠」「路径中包含 `..`」都可能被识别为同一条记录。本文依据官方工作区参考,说明 `realpathNormalize` 解析什么、第二次 `create` 为什么原样返回旧记录、会话 cwd 如何校验,以及目录消失后记录为何仍然存在。

同一个目录输入两遍,列表仍然只有一条——这是设计行为,不是 bug。 DeepSeek Harness 以规范化后的目录路径作为工作区身份:通过 fs.realpath 解析符号链接、.. 和末尾斜杠,再按最终字符串是否相等判断唯一性。软链与目标目录的解析结果相同,因此第二次添加会命中已有记录。

更需要记住的是命中之后的行为:不会创建第二条记录,也不会将新传入的标题应用到旧记录。 这正是「以为添加成功」和「以为标题已改好」两种误解的来源。

先明确一点:这里讨论的是注册表的行为。客户端如何展示结果、是否给出提示,是另一回事,不能据此推断注册表做了什么。

结论先行:比较的到底是什么

项目 在文档模型里的作用 对「重复添加」的影响
输入路径 用户提供的完整目录路径 不同文本可能解析到同一路径
规范路径 解析后用于目录身份的路径 规范字符串相同就命中现有记录
工作区 ID 持久记录的稳定标识 返回的旧记录保留原 ID
标题 显示标签 不同记录可以使用相同标题
会话 cwd 会话头里不可变的工作目录 附加时用同一套规范化规则校验

读这张表时,先记住一点:标题不是唯一性依据。 两个不同目录可以使用同一个标题;同一个目录即使第二次传入不同标题,也仍会返回原记录,且标题不变。

一、一次「添加」实际发生了什么

官方工作区参考将工作区定义为一条持久记录,包含四项:稳定 ID、规范路径、显示标题,以及有序的会话归属。

添加操作调用注册表的 create(path, title?)。文档规定:

  • 路径规范化后已对应一条记录 → 返回现有实体,保持不变;
  • 不创建第二条记录;
  • 不写入新标题。

这里容易产生一个误解:「我以为自己改了名字。」标题可以独立于路径身份修改,因此需要单独修改标题,再次添加同一目录不会改名。此外,重复标题本身也被允许——标题从来不是身份标识。

普通创建还有两项硬要求:必须提供完整路径,且目录必须存在。 路径不存在时会保留原始的 ENOENT;目标存在但不是目录,也会被拒绝。因此,「添加悬空软链失败」不能理解为「去重成功」——两者是不同情况:前者是失败,后者则是不需要再添加。

还要区分普通创建与「默认工作区初始化」:后者只在符合条件时递归创建缺失目录,并以请求路径的最后一段作为初始标题。这不代表任意添加一个不存在的目录都会自动创建。

二、第一次使用 Web UI,容易误判的两件事

Web UI 入门说明了入口:全新 Web UI 在「添加并选中工作区」之前没有选中项,会话输入框不可用。

由此容易产生两种误判:

  1. 启动进程时所在的目录只是「默认文件系统位置」。 有默认位置,不等于已经选中一条工作区记录。输入框无法输入时,先确认是否尚未选中工作区,而不是先怀疑页面故障。
  2. 选中的是记录,不是路径字符串。 界面上两种看起来不同的写法,可能对应同一条记录;两条标题相同的记录,也可能对应不同目录。判断依据始终是目录身份。

选择和选中的完整流程,参见 会话开始前先选工作区。

三、如何排查「意外的重复」

按以下五步依次检查:

  1. 记下两次使用的路径写法,以及预期指向的项目。 分享时先对私人目录名脱敏,并确认 UI 中实际选中的是哪条记录。
  2. 使用所在平台的文件系统工具确认路径是否为软链,以及它解析到哪个现有目录。 参考文档用 fs.realpath 定义身份,但没有规定跨平台的检查 shell 命令,因此不要把某条命令的输出当作规范答案。
  3. 比较解析后的目录身份。 规范字符串相同,文档预测会返回原有工作区且不作修改;此时直接选中该记录即可,不必反复添加别名。
  4. 如果本意是创建两个独立项目,先确认两条路径最终解析为两个不同的现有目录。修改显示标题或路径文本,都不能证明目录不同。
  5. 如果解析失败,检查目标是否缺失、路径组件是否不可访问,或目标是否根本不是目录。先恢复目录或修正选择,再重试普通注册。

报告问题时,同时保存原始写法和解析结果。只说「我添加了两次,却只出现一条」,再配一张标题截图,对方仍无法判断两次注册是否指向同一规范路径。

还要留意时间变化带来的问题:一条曾经解析到某个目标的路径,在软链被修改后可能不再指向该目标。 因此应检查当前文件系统状态,而不是沿用上次的结论。

四、会话 cwd 如何校验

这一层的校验比多数人想的更严格。API gateway 为所选工作区创建会话时,会依次:

  1. 使用工作区路径作为新会话的 cwd;
  2. 将其写入不可变的会话头;
  3. 调用 attachSession。

附加过程使用同一套规范化规则,对照保存的会话 cwd 与工作区路径。新附加要求 cwd 能解析到一个匹配的现有目录;缺失或不匹配的路径不能作为新会话加入。

已经归属的候选会话遵循另一条规则,值得单独记住:如果其完整 cwd 在路径解析或目录状态检查中遇到 ENOENT(包括悬空软链),既有候选会保留;而会话头缺失、cwd 无效或规范路径不匹配的候选会被过滤。之后被接受的修改会清理这些被过滤的候选,但不会清理因目录缺失而保留的候选。

注意这条规则的边界:保留归属不会创建目录,也不允许在目录缺失期间新增会话。「仍在列表里」和「当前可用」是两回事。

会话、工作区与 agent 之间的关系,参见 会话与 agent 的关系。

五、目录消失后,记录为什么还在

工作区创建后保存的规范路径不会被重写,即使目录后来消失也一样。不带缓存调用 status():路径当前存在且是目录时返回 ok,否则返回 missing-dir。

这一设计可以区分「保留的记录」与「当前可用的目录」,但不会自动跟踪被移动的项目,也不会修复已修改的链接。要让记录恢复可用,需要把目录放回原处或重新选择。

要按工作区重新关联历史会话,可看 会话引用:把相关会话连起来;要按事件回查历史,可看 查询已有会话与事件。

六、该不该删除或改名

  • 修改标题是安全的:标题可以独立于路径身份修改,重复标题也允许。修改标题能让选择器更易读,但不能把一个规范目录拆成两个工作区。
  • 删除注册会移除注册、排序项和会话归属;它不会删除目录、文件、实时会话或持久日志——那些会话会变成 Ungrouped。
  • 因此,删除注册 ≠ 删除项目目录,但确实会改变工作区的组织方式。不要只因看到一个别名就立刻删除,应先确认当前归属和预期结果。

开始新任务时,选择那条「规范目录正确」的已有记录;查看历史会话时,检查其当前归属和会话头 cwd,不要假设标题或软链会自动决定归属。归属依据是注册表保存的有序会话清单,cwd 用于校验成员关系——每次读取时不会据此重新推导整张清单。

七、安全边界(这段不能省)

  • 文档规定的是「规范路径字符串相等」,并没有为所有文件系统别名、平台大小写行为或网络文件系统建立通用规则。 如果相同写法在不同环境中表现不同,应先检查实际环境和安装版本。
  • 软链是路径解析问题,不是权限机制。 来源没有声称软链能阻止 Agent 访问文件,也没有把它当作访问控制边界。
  • 分享诊断信息时,应将目录路径和会话元数据视为可能包含私人信息的内容。
  • 保留归属不证明文件仍存在:「保留缺失工作区」或「保留会话归属」都不能证明文件仍然存在;反过来,删除注册也无法修复缺失的目录。
  • 修改链接或移动项目文件之前,先核实实际目标;否则改变的是「以后如何解析」,不是「现在有什么」。

术语

  • 符号链接:路径规范化时需要解析目标的文件系统链接。
  • 规范路径:作为工作区身份保存的解析后目录路径。
  • 工作区 ID:独立于显示标题的稳定记录标识。
  • 会话 cwd:保存在会话头中、附加会话时用于校验的工作目录。
  • Ungrouped:删除工作区注册后,会话不再归属该工作区的状态。

排查清单

  1. 两次添加是否指向同一个规范目录?先解析,再下结论。
  2. 查的是当前文件系统状态,还是沿用上次的结论?
  3. 是否把屏幕上显示的标题当成了身份?
  4. 添加后没有变化,会不会是命中了已有记录,而标题本来就不会被覆盖?
  5. 输入框无法输入,是因为尚未选中工作区,还是另有原因?
  6. 添加悬空软链失败了——是否把它误当成「去重成功」?
  7. 想要两个独立工作区,是否确认它们解析到两个不同的现有目录?
  8. 会话 cwd 缺失时,是否区分了「归属被保留」和「还能新建会话」?
  9. 删除注册前,是否确认它不会删除目录、文件、实时会话和日志?
  10. 是否把软链说成了访问控制手段?

相关阅读

本文依据 DeepSeek Harness 官方工作区参考与 Web UI 入门整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
插件与文档收录于:https://dsh-plugin.com/zh/blog

目录
相关文章
|
17天前
|
Linux 开发工具 iOS开发
Codex保姆级教程(下载+安装+登录+使用,含所有版本,2026最新)
Codex是OpenAI推出的开源AI编程智能体,本地运行,可理解整个代码库,支持自然语言指令改代码、执行命令、跑测试、修Bug,兼容Win/macOS/Linux。(239字)
7136 54
|
4天前
|
JSON 前端开发 API
阿里云最新Qwen4-Max大模型介绍:模型定位、特征、能力、适用场景解析
2026 年 11 月 11 日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问 AI 平台 Token Plan,并同步接入千问办公、Qoder 等入口。该版本聚焦知识理解、世界感知、编程与 Agentic 四项升级,主打复杂编程、专业办公、前端设计与专业软件操作。预览期至 11 月 25 日 24:00,到期后模型标识下线;限时 2 折、新用户再享 5 折,最低 1 折可体验。
|
5天前
|
云安全 人工智能 安全
|
18天前
|
JavaScript API iOS开发
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(DSH)是DeepSeek于2026年开源的MIT协议AI Agent框架,支持插件化组装模型、工具、沙箱与UI,兼容主流大模型。本文提供免Node.js的桌面端安装包(Win/macOS),含详细图文教程及热门插件推荐。
5512 66
|
12天前
|
Linux 开发工具 iOS开发
2026最新codex下载安装保姆级使用教程(下载+安装+登录+使用,含所有历史版本)
本文详解OpenAI Codex国内快速上手指南:提供Win/macOS/Linux全平台免安装包、npm/Homebrew等多方式安装、账号/API Key双登录、简体中文切换,覆盖下载、安装、汉化、使用及高频避坑(如微软商店失败、npm超时等),10分钟即可跑通。
2778 9
|
4天前
|
人工智能 前端开发 API
阿里云Qwen4-Max 大模型详解:定位、特征、能力、适用场景与相对Qwen3-Max差异解析
2026年11月11日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问AI平台Token Plan并接入千问办公、Qoder等入口。该版本聚焦知识理解、世界感知、编程与Agentic四项升级,主打复杂编程、专业办公、前端设计与专业软件操作等真实任务。预览期为11月11日10:00至11月25日24:00,仅支持Token Plan调用,到期后模型标识下线;限时2折、新用户再享5折,最低1折可体验。
|
10天前
|
人工智能 安全 API
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(dsh)是DeepSeek AI于2026年开源的轻量级Agent运行框架,基于Cordis内核,践行“一切皆插件”理念。支持Web/桌面双端,开箱即用;内置多模型接入、丰富插件生态(超3.5万),适配编程、办公、创作等场景。(239字)
1798 1
|
2天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
1250 0
|
8天前
|
人工智能 iOS开发 开发者
2026年 Codex 下载地址更新:codexdown.cn 已更换为 codexdown.cc(附 Codex 客户端下载)
2026年Codex官方下载站已由codexdown.cn正式迁移至codexdown.cc,提供Windows/macOS最新客户端、历史版本、安装教程及配置指南,开发者可一站式获取稳定、安全、签名验证的AI编程工具资源。(239字)
1668 0

热门文章

最新文章