docs: synchronize controller transport documentation

2026-08-29 04:26:38 +00:00 · 2026-08-23 16:16:04 +08:00
parent e38982adc8
commit a49b265f88
60 changed files with 1596 additions and 452 deletions
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/api/workspace-controller/README.md
+README.md: 0e126f1a0cc52353cb479f42a592e8997207e2e5
+README.zh.md: 2a1c56d8c02ffe7ac6a797b2c620ce3be42a3cc4
@@ -0,0 +1,22 @@
+# Workspace Controller
+
+English | [中文](README.zh.md)
+
+`@deepseek-ai/dsh-api-workspace-controller` owns the Host `ctx.workspaceController` service and the generated Client `ctx.remote.workspace` namespace. Its Remote methods create, rename, remove, and reorder Workspaces, reorder Sessions within a Workspace, archive Sessions from Workspace navigation, and follow the complete Workspace projection.
+
+The Host controller serializes mutations whose correctness depends on current registry state and returns stable `WorkspaceError` values for expected failures. Its `follow()` stream synchronously attaches to durable Workspace changes, emits one complete baseline first, then emits ordered `upsert`, `remove`, `order`, and `archived` increments. A reconnect starts another generation with a replacement baseline, so consumers do not depend on receiving every increment while disconnected.
+
+The Client entry provides `ClientWorkspaceModel` and `createWorkspaceStateStream()`. The model owns Workspace rows, registry order, archived Session ids, unary mutation echoes, and stream/unary race resolution. A newer Host row wins by `updatedAt`; a committed stream order outranks an older unary response; a removed Workspace id cannot be resurrected by delayed data. The package exposes framework-neutral snapshots and subscriptions, leaving navigation policy and React hooks to the UI owner.
+
+## Model Experience
+
+None, as Workspace organization is browser and Host control state and registers no prompt, tool, or session event.
+
+#### KV Cache effect
+
+No direct effect; Workspace mutations do not alter model requests.
+
+## Known Limitations and Deferred Work
+
+- `follow()` replaces the whole projection after reconnect and has no durable cursor or incremental catch-up protocol.
+- Process-local deletion markers prevent delayed data from reviving a removed Workspace only for the lifetime of the Client model.
@@ -0,0 +1,22 @@
+# Workspace Controller
+
+[English](README.md) | 中文
+
+`@deepseek-ai/dsh-api-workspace-controller` 拥有 Host 的 `ctx.workspaceController` 服务和生成的 Client `ctx.remote.workspace` namespace。它的 Remote 方法负责创建、重命名、移除和重排 Workspace，在 Workspace 内重排 Session，从 Workspace 导航中归档 Session，以及跟随完整的 Workspace 投影。
+
+Host 控制器会串行执行正确性取决于当前 registry 状态的变更，并为预期失败返回稳定的 `WorkspaceError` 值。它的 `follow()` 流会同步订阅持久 Workspace 变更，先发出一份完整 baseline，再按顺序发出 `upsert`、`remove`、`order` 和 `archived` 增量。重连会以替换 baseline 开始新一代，因此消费方不依赖收到断线期间的每个增量。
+
+Client 入口提供 `ClientWorkspaceModel` 和 `createWorkspaceStateStream()`。该模型拥有 Workspace 行、registry 顺序、已归档 Session id、一元变更回声，以及流与一元调用的竞态处理。较新的 Host 行按 `updatedAt` 获胜；已提交的流顺序优先于较旧的一元响应；已经移除的 Workspace id 不会被延迟数据复活。该包公开与框架无关的快照和订阅，把导航策略与 React hook 留给 UI owner。
+
+## 模型体验
+
+无，因为 Workspace 组织属于浏览器与 Host 控制状态，并且不注册提示词、工具或会话事件。
+
+#### KV Cache 影响
+
+无直接影响；Workspace 变更不会改变模型请求。
+
+## 已知限制与延期工作
+
+- `follow()` 在重连后替换完整投影，不提供持久 cursor 或增量追赶协议。
+- 进程本地删除标记只会在 Client 模型生命周期内阻止延迟数据复活已移除的 Workspace。