4.6 KiB
description, kind
| description | kind |
|---|---|
| Host 与 Client 工作区控制：修改工作区导航并跟随其完整投影。 | package-reference |
Workspace Controller
English | 中文
概述
@deepseek-ai/dsh-api-workspace-controller 拥有 Host 的 ctx.workspaceController 服务和生成的 Client ctx.remote.workspace namespace。它的 Remote 方法负责创建、重命名、移除和重排 Workspace，在 Workspace 内重排 Session，归档与取消归档 Session，以及跟随完整的 Workspace 投影。当 Client 必须修改或跟随 Workspace 导航时，请通过 API 网关使用它。本包同时拥有 ctx.directoryPickerController 与生成的 ctx.remote.directoryPicker namespace，因为它承载的选目录 seam 是抽象的，自身从不作为 Loader entry。
目录
使用本包
Host 控制器会串行执行正确性取决于当前注册表状态的变更，并为预期失败抛出带有稳定错误码的 RemoteError。它的 follow() 流会同步订阅持久 Workspace 变更，先发出一份完整 baseline，再按顺序发出 upsert、remove、order、archived 和 pinned 增量。归档与置顶集合都是会话 id 数组，置顶数组把最近置顶的 id 放在前面。重连会以替换 baseline 开始新一代，因此消费方不依赖收到断线期间的每个增量。
Client 入口提供 ClientWorkspaceModel 和 createWorkspaceStateStream()。该模型拥有 Workspace 行、registry 顺序、归档与置顶会话身份、一元变更回显，以及流与一元调用的竞态处理。较新的 Host 行按 updatedAt 获胜；已提交的流顺序优先于较旧的一元响应；已经移除的 Workspace id 不会被延迟数据复活。置顶快照仅在会话身份或顺序变化时更新。该包公开与框架无关的快照和订阅，把导航策略与 React 钩子留给 UI owner。
首次使用工作区
workspace.initializeDefault({ directoryName, title }) 返回持久化的默认工作区；Client service 通过 workspaces.initializeDefault(request, signal?) 提供同一请求。Workspace Client按启动时的语言解析这些名称。Host 将目录放在其账户的 <Documents>/deepseek-harness 下，远程 Web Host 也遵循此规则。目录名必须是非空的单个片段，不能含分隔符、冒号、NUL、首尾空白或末尾句点；标题不能为空。操作系统的文件名限制同样适用。Linux 系统查询要求存在 xdg-user-dir 且启用了 Documents 目录；不具备该条件的 Host 必须配置 documentsDirectory 或使用文件夹选择器。
Workspace 注册表负责资格判断、目录创建和持久化初始化。已有默认工作区直接返回，不再查询 Documents；请求中的名称不会将其重命名。不满足首次使用条件时返回 undefined，启动流程可将目录选择留给用户。名称无效时以 gateway/bad-request 拒绝；查询和创建失败遵循标准 Remote 错误处理。初始化不创建 Session，也不发送消息。
| 配置 | 默认值 | 用途 |
|---|---|---|
documentsDirectory |
系统 Documents 目录 | 完全限定的 Host 目录覆盖值 |
documentsLookupTimeoutMs |
10000 |
操作系统目录查询的正数最大时长，单位为毫秒 |
Documents 查询占用注册表变更队列，因此其他 Workspace 变更（包括登记已选目录）最多可能等待 documentsLookupTimeoutMs。取消可以停止查询；解析成功后，取消不会回滚创建或登记。
模型体验
无，因为 Workspace 组织属于浏览器和 Host 的控制状态，并且不注册提示词、工具或会话事件。
KV Cache 影响
无直接影响；Workspace 变更不会改变模型请求。
已知限制与延期工作
follow()在重连后替换完整投影，不提供持久 cursor 或增量追赶协议。- 进程内删除标记只会在 Client 模型生命周期内阻止延迟数据复活已移除的 Workspace。
开发备注
维护者工作上下文——点击展开
无。
运行时不变式： 不发布伴生入口。Workspace 注册表负责持久化，每次流生成都是完整投影。