深入理解 DSH plugin 工作区:会话归属、置顶顺序、归档准入与失败路径到底怎么判定
“归档被拒”不是权限问题,而是工作区拒绝把正在跑的东西藏起来。 DSH plugin 的归档准入会在写入前询问已组合的提供方:这个会话还有什么在跑。先理解这条规则,再看置顶与归属。 DSH插件 的会话归属看有序 sessionIds,cwd 只做校验。
归属真源是有序 sessionIds
cwd 只做校验,不做归属推导。(来源)
WorkspaceId 是品牌化标识,消费方只看到 Workspace 接口,实现保持包内私有。
所有权的真源是记录中有序的 sessionIds,绝不从会话 cwd 派生。成员资格会把记录的 header cwd 与工作区路径校验;已有候选的完全限定 cwd 在路径解析或目录 stat 时返回 ENOENT,仍保留其归属——这保留了目录缺失或符号链接失效时的记账关系,但不会接纳新会话。
失败语义很克制:失败的写入会拒绝(insertSessionBefore 的账本错误以 WorkspaceMoveInvalidError 拒绝,存储失败以普通错误拒绝);每次被接受的变更都盖上 updatedAt 时间戳,并持久修剪不再通过成员资格检查的候选项。
create 幂等,delete 只删记录
删除工作区不会动文件,也不会动会话。(来源)
WorkspaceRegistry 拥有注册与解析:
create(path, title?)要求完全限定路径并规范化,拒绝不存在的路径(原样传出ENOENT)或非目录;当规范路径已被拥有时原样返回既有实体;否则创建一条标题为title ?? defaultWorkspaceTitle(path)的记录,并前插到持久的注册表顺序中;get(id)与有序的list()是同步缓存读取;resolveByPath(path)应用同一套完全限定 realpath 规范但不创建;delete(id)只移除注册记录、顺序条目与会话账本——目录、用户文件、实时会话和已持久化日志一概不动,因此这些会话变为 Ungrouped;未知 id 返回false。
create 与 delete 会在其两次写入(记录与顺序)可能分叉之前,先持久写入一个待定变更标记。启动时恰好解决被标记的那次变更——通过删除被标记的表行:这补完被中断的 delete,并回滚被中断的 create(注册可以重建,所以回滚是安全方向)。而没有标记的顺序表不一致,则作为损坏大声失败。
cwd 由创建者赋予
注册表不赋 cwd,只做 attach 时复核。(来源)
会话的 cwd 在创建时由创建者赋予,而不是由注册表赋予。API 网关从所选工作区的 path 解析新会话的 cwd(回退到显式或默认 cwd),先创建会话使 cwd 落入其不可变的 SessionHeader,再调用 attachSession,后者会把已存储的 header cwd 与工作区路径重新校验一遍。
首次成功启动时,注册表仅凭已持久化的 header(id、cwd、createdAt——绝不读事件正文)引导历史:把规范 cwd 有效的会话按目录分组为工作区,最新的排在最前;「已初始化」标记最后写入,因此被中断的引导可以安全续跑。
引导只发生这一次:没有 cwd 的历史遗留会话保持 Ungrouped,此后创建的会话只能通过 attachSession 加入工作区。
默认工作区是固定目录
自动标题按目录名生成,展示语言只在浏览器侧。(来源)
控制器的 initializeDefault 不接受请求参数:它拥有固定目录名 default-workspace,解析 Documents 位置,并请求注册表执行一次初始化。
注册表接收目录解析器,以所请求目录(而非规范路径)的最后一段作为初始标题,并将登记与持久化身份一起提交。
语言不会传到 Host——浏览器消费方通过控制器的 workspaceDisplayTitle 为仍保留该自动标题的工作区加标签,因此只有屏幕上的名称跟随读者语言。这条分工让默认工作区在切换语言时不需要改 Host 数据。
置顶:完整数组,最近在前
归档会顺手移除置顶,取消归档不会恢复。(来源)
控制器的传输类型定义了 WorkspacePinSessionRequest 与 WorkspaceUnpinSessionRequest,两者都携带一个 sessionId。
两个操作都返回 WorkspacePinValue:完整的 pinnedSessionIds 数组,最近置顶的会话排在前面。所以客户端不该自己维护一份增量,而应直接用返回值替换。
规则有三条:置顶要求会话已知且未归档;对未置顶的 id 取消置顶会成功,且不改变集合;归档在同一次持久化写入中移除该会话的置顶,取消归档不会恢复置顶。
归档准入:先问还有什么在跑
有活动就拒绝,除非你显式要求先停。(来源)
归档是一个注册表全局的持久化集合,注册表拒绝把正在运行的工作藏在它后面。这条规则是本包声明并派发的两个宿主事件之上的能力接缝:
workspace/session-activity(waterfall)向已组合的提供方询问某会话还有什么在跑;workspace/session-stop(parallel)请它们停止这些工作。
每个提供方像任何监听器一样在根上注册,因此本包不认识 agent、job 或 schedule 的词汇;各族是一个可合并扩展 map 的键。随附加载的提供方合并 turn(Agent 注册表)、job(任务注册表 seam)、subagent(Subagent 运行时)与 schedule(Schedule 插件)。
SessionActivityKindMap 在本包里是空的,因此一个没有编译任何提供方的程序看不到任何键。提供方通过把自己的 SessionActivity 条目前置到 next() 的结果来回答 waterfall;注册表最内层的回调返回空列表,因此没有提供方的组合可自由归档。
archiveSession(sessionId) 在存在性检查之后只询问 waterfall 一次,对非空答案以 WorkspaceActiveSessionError(sessionId、activity)拒绝且不写入;控制器把它映射为 workspace/session-active 错误,其 details 携带同样的两个字段。
archiveSession(sessionId, { stopActivity: true }) 则跳过检查、先写入归档、再派发 workspace/session-stop;提供方抛错只记日志,归档保留,被停止的工作从不等待收敛。已归档的 id 既不询问也不停止。
验证:置顶两个工作区再归档
验证要同时看顺序、拒绝路径与不恢复语义。(来源) 六步:
- 依次置顶会话 A 与 B,断言
pinnedSessionIds中 B 在 A 前。 - 对未置顶的 C 取消置顶,断言成功且数组不变。
- 让某个会话有运行中的任务,调
archiveSession,断言以WorkspaceActiveSessionError拒绝且activity非空。 - 用
{ stopActivity: true }重试,断言归档成功、置顶被同一次写入移除。 - 取消归档,断言会话回来但置顶没有恢复。
delete该工作区,断言会话变成 Ungrouped,且磁盘文件与会话日志都还在。
如果第 3 步被拒绝却没有 activity,说明某个提供方返回了空条目而不是真正的活动明细,排查时先看各族 provider 的合并结果。
工作区的概念与选择,可以对照工作区说明与工作区配置;持久化侧的恢复边界见持久化 seam。
一句话收束: 归属靠有序 sessionIds、create 幂等而 delete 只删记录、cwd 由创建者给、置顶返回完整数组、归档先问活动、取消归档不恢复置顶。
常见问题
不能,DSH plugin 以记录里有序的 sessionIds 为真源。DSH plugin 明确说所有权绝不从会话 cwd 派生,cwd 只用于成员资格校验。
不会,DSH plugin 只移除注册记录、顺序条目与会话账本。DSH plugin 不动目录、用户文件、实时会话和已持久化日志,那些会话变成 Ungrouped。
不会,DSH plugin 在归档时同一次写入里移除置顶。DSH plugin 取消归档只恢复可访问性,不恢复置顶集合。
DSH plugin 会拒绝并带上活动明细。DSH plugin 用 WorkspaceActiveSessionError 返回 sessionId 与 activity,控制器再映射为 workspace/session-active 错误。
相关术语
- WorkspaceId
- WorkspaceId 是工作区记录的品牌化标识,消费方只看到 Workspace 接口,实现保持包内私有。— packages/workspace/workspace/src/types.ts
- WorkspaceRegistry
- WorkspaceRegistry 拥有工作区的注册与解析,提供 create、get、list、resolveByPath 与 delete。— packages/workspace/workspace/src/types.ts
- WorkspacePinValue
- WorkspacePinValue 是置顶操作的返回值,含完整的 pinnedSessionIds 数组,最近置顶的排在前面。— packages/workspace/workspace/src/types.ts
- SessionActivity
- SessionActivity 是一条归档准入理由,含族 kind 与可选的逐项 items。— packages/workspace/workspace/src/types.ts
来源
- DeepSeek Harness 官方参考 - 工作区· deepseek-ai
- packages/workspace/workspace/src/types.ts· deepseek-ai