dsh-plugin-guide 0.3.42 → 0.4.1

package/references/official-docs/docs/subsystems/client-modules.zh.md

@@ -1,198 +0,0 @@
-# Client 模块
-
-[English](client-modules.md) | 中文
-
-Web 插件表：[dsh-client-modules](../../packages/client/modules) 中 client 模块系统的 Node 半，以 `ctx.clientModules`（`ClientModuleRegistry`）形式提供。它扫描宿主 Loader 的 entry，找出声明了 `dsh.client` 的包，组合出 `window.__DSH_BOOT__` entry 图，在 `/plugins` 下提供带版本的单资源或多资源 combo 脚本，并以启动协议行回应每次 index 注入收集——这是同一个服务的四个面。它是 Web GUI 栈的一项可选能力，不属于 agent loop（智能体循环）主干，并且是 [dsh-host-webserver](../../packages/host/webserver) 的消费方：[web-server.md](web-server.zh.md) 所述的载体提供本服务注册的前缀路由与其回应的 `webserver/index-inject` 事件。同一个包的浏览器半（`ctx.modules`，即拉取并物化这些 bundle 的 lazy CJS 模块表）属于内核机件，记录在[包 README](../../packages/client/modules/README.zh.md)中，不在本页。
-
-源码：[`packages/client/modules/src/client/manifest.ts`](../../packages/client/modules/src/client/manifest.ts)
-
-## wire
-
-图是 Node 半与浏览器半之间协议层的唯一真源。宿主从扫描到的包组合出 `WebBootEntry` 行与 `WebBootBatch` 描述，随后在 Vite entry 之前向结构化 index 注入表贡献 registration facade、application preload、bootstrap 脚本与图全局量。`global` 行渲染为 `globalThis["__DSH_BOOT__"]`，其中 `<` 已转义，插件可控的字符串因此无法逃出 script 元素。没有有效 manifest 的页面无法启动：浏览器解析器会拒绝畸形 row 或批次、未知成员，以及未恰好归属一个初始 combo 描述的 entry。
-
-```ts type-equiv
-/**
- * One composed client entry pushed by the host (a graph row). Wire
- * single source: the host node half (package root) produces this same shape.
- * `immediately` marks stage-one prefetch. `inject` names package rows whose
- * factories must arrive before this row materializes, while Cordis separately
- * uses the same package edges to compose entries. `external` carries exact
- * non-inject module requests (see {@link WebBootGraph.entries}).
- */
-interface WebBootEntry {
-  /** Entry name == package name. */
-  id: string
-  /**
-   * Revisioned single-resource combo reference used by HMR. It is relative to
-   * the document, so the browser resolves it under whatever mount served the page.
-   */
-  url: string
-  /** Opaque plugin-artifact revision used for HMR cache busting. */
-  rev: string
-  /** Package-name dependency edges used for factory arrival and plugin composition. */
-  inject?: string[]
-  /** Stage-one prefetch mark: load the script for factory registration during module-face boot. */
-  immediately?: boolean
-  /** Non-baseline module specifiers this row requests; omitted when it requests none. */
-  external?: string[]
-}
-```
-
-```ts type-equiv
-/** Initial scheduling phase for one revisioned combo script. */
-type WebBootBatchPhase = 'bootstrap' | 'application'
-```
-
-```ts type-equiv
-/** One initial combo script; a scheduling phase may span several descriptors. */
-interface WebBootBatch {
-  /** Parser-blocking bootstrap or preloaded application scheduling. */
-  phase: WebBootBatchPhase
-  /** Content-addressed combo script reference, document-relative like {@link WebBootEntry.url}. */
-  url: string
-  /** Revision derived from the ordered entry revisions. */
-  rev: string
-  /** Graph entry ids whose factories the script registers, in execution order. */
-  entries: string[]
-}
-```
-
-```ts type-equiv
-/** Host release identity; two releases are the same when both fields are equal. */
-interface WebBootRelease {
-  /** Release version label. */
-  version: string
-  /** Source commit fixed in when the Host was built; absent when the build recorded none. */
-  commit?: string
-}
-```
-
-```ts type-equiv
-/** The composed client entry graph the host injects as `window.__DSH_BOOT__`. */
-interface WebBootGraph {
-  /** Consistency anchor over the current entry and batch descriptors. */
-  rev: string
-  /** Host release identity; absent from a Host that publishes none. */
-  release?: WebBootRelease
-  /**
-   * Composed entries in module-graph order — a dynamic package row precedes
-   * rows whose `external` requests that package. Cordis activation order is
-   * unrelated and remains owned by fiber service waiting.
-   */
-  entries: WebBootEntry[]
-  /** Initial combo descriptors; every entry belongs to exactly one descriptor. */
-  batches: WebBootBatch[]
-}
-```
-
-首次发布与 HMR 都从入口的 mtime、ctime 和大小派生每个 row 的 `rev`，不对可执行字节求哈希。相同产物会跨 Host 重启保持 revision。初始 descriptor 把 row 划入 bootstrap 与 application 两个调度阶段，每个阶段都可以包含多条 descriptor。URL 只含有序 package 资源列表和从这些 row revision 派生的 revision，阶段名不会进入路由。图组合保持 row 顺序，并在 map 形式 URL 超过 3 KiB 前贪心切分，不拼接脚本，也不读取 map。图 revision 对 entry 与 batch descriptor 求哈希。`immediately` 标记第一阶段的 registration barrier；同一 combo 中的 row 共享脚本传输，不同 combo 则独立加载。
-
-`release` 把本包版本与 client 构建固化进 Host 构建产物的源码 commit 配成一对，不计入图 revision。只有 Host 提供页面启动时的 release，页面才应用图和 rebuilt 帧；其他 release 要等页面刷新（[Host release 变化](../../packages/client/modules/README.zh.md#host-release-changes)）。
-
-## 扫描
-
-包加入这张表的方式，是在自己的 package.json 中声明 `dsh.client`（`platform: 'web'`、可选的 `inject` 边、可选的 `immediately`），并在 `exports["./client"]` 导出构建好的 bundle。每个 live row 都从自己的 Loader specifier 与所属 tree `baseUrl` 解析；若 `loader.internal.resolveSync` 可用，则使用 Host face import 所用的同一个实现。最近归属的 package manifest 提供浏览器模块 id，因此相对 source 与 built overlay 仍保留包身份。若不同的 active Loader source 解析到同一包名，组合会失败；一个来源卸载后，仍存活的来源无需重启 fiber 即可提供该 row。
-
-扫描是单包增量的；不存在全量重扫代码路径。fiber 构造或 dispose（资源释放）时的每次 cordis `internal/plugin` 发射都把该 fiber 的 entry 名标脏，一次微任务 flush 把每个脏名与实时 loader entry 对账。激活趟以全部当前 entry 灌入同一个脏集合并同步 flush，因此初扫与稳态共享一条实现——但失败姿态相反。激活时，已加载 entry 中的畸形声明或缺失 bundle 会聚合为一个大声的 `AggregateError`，列出每个损坏的包：该 fiber 进入 FAILED，由启动的大声失败 sweep 上报。稳态下，损坏的包只记录一条警告，且不得殃及其他包。
-
-包元数据——包括「非 client 包」这一否定结论——按 Loader specifier 与所属 tree base URL 缓存至重启。同一来源的 fiber 重启会原样复用其 row 与 rev；bundle 内容变更只经 `rebuilt()` 到达图。
-
-## bundle 路由与 index 注入
-
-`GET`／`HEAD /plugins/??<package-a>/client.js,<package-b>/client.js&rev=<rev>` 寻址一份生成的 combo 脚本；单资源请求采用同一形式，也是 HMR 路径。脚本在首次 `GET` 时只拼接一次，并以 `sourceMappingURL` 结尾，该引用只携带 combo 查询串——`??<package-a>/client.js.map,<package-b>/client.js.map&rev=<rev>`，按脚本自身目录而非文档解析。启动、index 渲染、脚本 `GET` 和 `HEAD` 都不会读取 map 文件；首次 map `GET` 才会读取并校验这些文件、组合一份 Indexed Source Map v3，并缓存该 body。组件有自带 map 时直接用于对应 section；没有时则获得 identity section，其 `sourcesContent` 是捕获的 bundle，source 名取打包后的 `sourceURL` 或插件路由。每条启动请求 URL 按 UTF-8 字节计算都不超过 3 KiB；切分按更长的 map 形式计算。所有 application URL 都会预加载，所有 bootstrap URL 都会在图全局量与 Vite entry 之前执行。已物化响应使用长期 immutable 缓存。未知或被修改的资源列表、缺少 revision 及陈旧 revision 都返回 404，绝不提供其他字节，也不会让 SPA fallback 把 HTML 当作 JavaScript 返回；其他方法返回 405。注入行在每次 index 渲染时携带当前图，因此重新加载总是基于实时组合启动。
-
-## 服务
-
-```ts type-equiv
-/** Filesystem baseline captured before a client artifact snapshot is read. */
-interface ClientArtifactBaseline {
-  /** Absolute path of the client bundle. */
-  readonly path: string
-  /** Bundle modification time in milliseconds. */
-  readonly mtimeMs: number
-  /** Bundle status-change time in milliseconds, including writes that preserve mtime. */
-  readonly ctimeMs: number
-  /** Bundle size in bytes. */
-  readonly size: number
-}
-```
-
-`ClientModuleRegistry`（`ctx.clientModules`，定义于 [`packages/client/modules/src/index.ts`](../../packages/client/modules/src/index.ts)）暴露读取面与重建面；签名见生成的[服务目录](#ctxclientmodules--clientmoduleregistry)。`graph()` 返回当前组合出的图（两次变更之间是同一个稳定对象），`clientPath(id)` 返回 bundle 的绝对路径，`artifactBaseline(id)` 返回读取当前快照前捕获的 bundle stat 值。`fetchBundle()` 解析 HTTP 路由所使用的同一份惰性响应。`rebuilt(id)` 是变化后的 bundle 内容到达图的唯一入口：它从文件系统元数据派生 revision，只有 revision 变化才会读取新字节、重新组合图并发出通知。`onRebuilt` 按发生变化的 bundle 逐个触发并携带新 revision；`onGraphChanged` 在任何一次重新组合了图的 flush 之后触发（行的增删，或 rebuilt 带来的 revision 变化），并采用拉取模型——监听器自行重读 `graph()`。两条通知路径都会兜住监听器异常，因此一个抛错的订阅者既不能让后续订阅者被跳过，也不能杀死触发这次 flush 的一方。
-
-随包提供的 Web 组合通过 [`dsh-client-hmr`](../../packages/client/hmr/README.zh.md) 交付动态图快照。Host 立即转发现有图变化通知，重连会发送当前完整图。图描述浏览器的目标条目，不声明 Host 清理已经完成。产物轮询另外报告重建 revision。仅 source map 变化不会触发重载；新 combo-map URL 只会在 bundle revision 变化后出现，每份 map body 由其首次 `GET` 固定。Client Modules 校验快照，并将对账与重建串行协调；它持有启动创建的条目映射，负责单资源到达、异步移除、未使用模块与样式清理，以及页面本地重试状态。静态平台模块与 bootstrap 保持页面生命周期；Electron 安装属于独立流程。
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxclientmodules--clientmoduleregistry"></a>
-
-### `ctx.clientModules` — `ClientModuleRegistry`
-
-The web plugin table service: incremental `dsh.client` scan + wire composition + bundle route + index injection rows. Construction runs the activation scan synchronously — a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud throw (FAILED fiber; the boot activation audit reports it).
-
-```ts cordis-catalog
-/**
- * Current composed entry graph (stable object between changes).
- * @returns the graph served as `window.__DSH_BOOT__`.
- */
-graph(): WebBootGraph
-
-/**
- * Absolute path of an entry's client bundle.
- * @param id - entry id (package name).
- * @returns the path, or undefined for an unknown id.
- */
-clientPath(id: string): string | undefined
-
-/**
- * Serve an advertised revisioned bundle or source map without a Web server.
- * Unknown URLs return 404, unsupported methods return 405, and `HEAD`
- * returns the same immutable headers without materializing a body. Each body
- * is built once on its first `GET`; script construction never reads maps.
- * @param request - shell-carrier request for a `/plugins` resource.
- * @returns the exact response also exposed by the optional Web route.
- */
-async fetchBundle(request: Request): Promise<Response>
-
-/**
- * Filesystem baseline captured before an entry's current bytes were read.
- * HMR compares it with the live files when installing a watch, so a write
- * between startup composition and watch installation cannot disappear into
- * the watcher's initial state.
- * @param id - entry id (package name).
- * @returns the path and baseline, or undefined for an unknown id.
- */
-artifactBaseline(id: string): ClientArtifactBaseline | undefined
-
-/**
- * Publish one completed bundle generation (the HMR watch's registration
- * hook — the only entry point through which build changes reach the graph).
- * Unchanged mtime, ctime and size preserve the graph without reading the bundle.
- * @param id - entry id (package name).
- * @returns the current artifact rev, or undefined for an unknown id.
- */
-rebuilt(id: string): string | undefined
-
-/**
- * Subscribe to bundle rebuilds; fires only when artifact metadata changes the rev.
- * @param listener - receives the entry id and its new bundle rev.
- * @returns the unsubscriber.
- */
-onRebuilt(listener: (id: string, rev: string) => void): () => void
-
-/**
- * Fires after any flush that recomposed the graph (row added/removed, or a
- * rebuilt rev change). Pull model: listeners re-read {@link graph}.
- * @param listener - notified with no payload.
- * @returns the unsubscriber.
- */
-onGraphChanged(listener: () => void): () => void
-```
-
-Source: [`packages/client/modules/src/index.ts`](../../packages/client/modules/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/client-resources.i18n.yaml

@@ -1,22 +0,0 @@
-# Bilingual-pair consistency record for client-resources.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/subsystems/client-resources.md
-/client-resources:
-  en: a7972413b1780235
-  zh: 74d70a11d7e7f7e3
-/client-resources/addresses:
-  en: 47da087087a3b0c5
-  zh: ddf0ffe347a1fe0c
-/client-resources/registering-a-provider:
-  en: bfe0d08fb20a8f55
-  zh: a569b0e65a343943
-/client-resources/reading-a-resource:
-  en: d1c77f944148b976
-  zh: 882f95a6046ccc80
-/client-resources/holding-and-releasing:
-  en: 4b904d5298237dd3
-  zh: 6952e56fecf9de78
-/client-resources/limits:
-  en: 0bb8c1e28d645c4a
-  zh: 1c353afec3af2546

package/references/official-docs/docs/subsystems/client-resources.md

@@ -1,92 +0,0 @@
-# Client Resources
-
-English | [中文](client-resources.zh.md)
-
-The client resource model turns an address into live data for any Web Client component. [`dsh-client-resources`](../../packages/client/resources/README.md) provides the `ctx.resources` service and the `useResource` global standard hook; a package that owns a kind of content registers one **provider** for its **protocol**, and a component reads the content's current state by **address** without importing the owner's runtime. The right Sidebar's tabs are the model's first consumer ([Right Sidebar](sidebar-right.md)); the decision record is the [client resource model Agent Note](../../.agents/notes/implemented/architecture/2026-09-05-client-resource-model.md).
-
-This page is the developer reference: how to write an address, how to register a provider, how to read a resource, what the states and failures mean, and how the model holds and releases a resource.
-
-## Addresses
-
-A resource address is a `dsh-resource://<type>/…` URL. The host names the protocol and must be a key of `ResourceProtocolMap`; the path is the protocol's own, and its owner percent-encodes each segment. A protocol that needs a scope puts it in the path: the `file` protocol's addresses read `dsh-resource://file/session/<sessionId>/<path>`, where path is workspace-relative or absolute with its leading slashes preserved, built with `fileAddressFor(sessionId, cwd, path)` and read back with `parseFileAddress(address)` from [`dsh-util-workspace-path`](../../packages/util/workspace-path/README.md). The model itself reads only the scheme and the host: `protocolOf(address)` returns the lower-cased host of a `dsh-resource://` URL and `undefined` for anything else. Addresses under any other scheme — the Sidebar's `sidebar://guide` — name no resource and read as `none`.
-
-| Address | Protocol key | Reads as |
-|---|---|---|
-| `dsh-resource://file/session/s1/notes/a.md` | `file` | the metadata of `notes/a.md` under session `s1`'s workspace root, when the `file` provider is registered |
-| `dsh-resource://file/absolute/home/me/notes.md` | `file` | parseable but fails with `workspace-file/unknown-workspace`: no authorizing Session, and neither current nor Tab Session is borrowed |
-| `DSH-RESOURCE://File/session/s1/a` | `file` | a distinct record: addresses compare as strings, and `openResource` accepts only the canonical lower-case spelling that `fileAddressFor` emits |
-| `dsh-resource://subagentchat/session/c1?parent=p1&mode=continuable` | `subagentchat` | an addressed subagent Conversation whose value owns a `SessionReference` until the resource closes |
-| `sidebar://guide` | — | `none`: a navigation address |
-| `/home/me/notes.md` | — | `none`: not a URL |
-
-## Registering a provider
-
-The owner of a protocol declares its value type on `ResourceProtocolMap` and registers one provider inside its own `ctx.effect`, so the protocol lives exactly as long as the plugin ([provide a protocol](../../packages/client/resources/README.md#provide-a-protocol)). `open(address, { signal })` returns a stream of `RemoteResult` frames — the current state first, then one frame per change — and must stop when `signal` aborts. A failure is an `ok: false` frame carrying a `RemoteFailure`; a throw inside the stream is a programming error and is not caught.
-
-```ts ignore-check
-import type { Context } from '@deepseek-ai/cordis'
-import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
-import type {} from '@deepseek-ai/dsh-client-resources/client'
-
-interface NoteView { readonly title: string; readonly updatedAt: string }
-
-declare module '@deepseek-ai/dsh-client-ui-slots' {
-  interface ResourceProtocolMap { note: NoteView }
-}
-
-export const inject = ['resources', 'remote']
-
-export function apply(ctx: Context): void {
-  ctx.effect(() => ctx.resources.register<'note'>({
-    protocol: 'note',
-    async *open(address, { signal }): AsyncIterable<RemoteResult<NoteView>> {
-      const id = new URL(address).pathname.slice(1)
-      yield await ctx.remote.notes.read(id, signal)
-      for await (const change of ctx.remote.notes.follow(id, signal)) yield change
-    },
-  }), 'my-notes: note resource provider')
-}
-```
-
-A protocol has exactly one provider; a second registration throws. Registering while addresses of the protocol are already held opens their streams at once; disposing the provider ends those streams and the addresses read `none` until a provider returns.
-
-## Reading a resource
-
-Every slot component receives `useResource` in its props, whatever its scope ([Slots](slots.md)). `useResource<P>(address)` names the protocol as the type argument and returns the address's current snapshot; subscribing is what holds the resource open, and a component that mounts while another holder keeps the resource alive reads the latest value at once without reopening the stream ([read a resource](../../packages/client/resources/README.md#read-a-resource)).
-
-| `status` | Meaning | `value` | `failure` |
-|---|---|---|---|
-| `none` | No provider is registered for the address's protocol, or the address is not a resource address | `undefined` | `undefined` |
-| `loading` | The provider's stream is open and has not yielded yet | `undefined` | `undefined` |
-| `live` | The latest frame succeeded | the latest `ok` value | `undefined` |
-| `failed` | The latest frame reported a failure | the last `ok` value, kept | the frame's `RemoteFailure` |
-
-```tsx ignore-check
-import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
-import type {} from '@deepseek-ai/dsh-api-workspace-files/client'
-
-type Props = PropsRuntime<'sidebar.right.pane.tab'>
-
-export function FileHeader({ useTabInfo, useResource, t }: Props) {
-  const { tab } = useTabInfo()
-  const meta = useResource<'file'>(tab.contentId)
-  if (meta.status === 'failed') return <p role="alert">{t('failed', { code: meta.failure.code })}</p>
-  return (
-    <header>
-      {tab.title}
-    </header>
-  )
-}
-```
-
-A consumer presents `failed` itself: the model keeps the last value beside the failure so a body can show stale content with a notice rather than a blank, and the next `ok` frame clears the failure. Nothing in the model produces user-visible text.
-
-## Holding and releasing
-
-A resource is alive while it has a holder: a subscribed `useResource`, or a pin. `ctx.resources.pin(address, signal)` keeps a resource open without subscribing until `signal` aborts, and an already-aborted signal pins nothing; the right Sidebar pins every open tab record's address for the record's life, so switching tabs unmounts a body without closing its stream. The first holder opens the provider's stream; the last release aborts it, discards the value, and returns the snapshot to `loading` (provider present) or `none` (absent). A frame the provider yields after that release is dropped, and the iterator is returned. `ctx.resources.source(address)` is the bare observable behind the hook, reference-stable per address, for callers outside React; reading its snapshot does not hold the resource ([lifecycle](../../packages/client/resources/README.md#lifecycle)).
-
-Most streams carry metadata rather than content. The `file` provider's value is `WorkspaceFileStat { absolutePath, version, bytes? }`: the first frame comes from Host `stat`, and later observations update the version. A consumer reads content through the Workspace Files Remote namespace; Preview owns refresh independently per tab ([`dsh-api-workspace-files`](../../packages/api/workspace-files/README.md)). The `subagentchat` provider retains the addressed Session and yields its `SessionReference`, then releases that reference when the resource signal aborts.
-
-## Limits
-
-Records live for the page lifetime: an address's record stays after its last holder leaves, holding no stream and no value, so memory grows with the number of distinct addresses ever read. A provider that ignores `signal` keeps running until its next frame. The failure type is the Remote face's `RemoteFailure`, so a provider whose source is not a Remote call mints one. A misspelled protocol or a malformed address reads as `none` with no other diagnostic.

package/references/official-docs/docs/subsystems/client-resources.zh.md

@@ -1,92 +0,0 @@
-# 客户端资源
-
-[English](client-resources.md) | 中文
-
-客户端资源模型把一个地址变成任何 Web Client 组件都能读的活数据。[`dsh-client-resources`](../../packages/client/resources/README.zh.md) 提供 `ctx.resources` 服务与 `useResource` 全局标准 hook；拥有某类内容的包为它的**协议**注册一个**提供方**，组件按**地址**读取该内容的当前状态，而无需引用拥有者的运行时。右侧 Sidebar 的 tab 是这个模型的第一个消费方（[右侧 Sidebar](sidebar-right.zh.md)）；决策记录见 [客户端资源模型 Agent Note](../../.agents/notes/implemented/architecture/2026-09-05-client-resource-model.zh.md)。
-
-本页是面向开发者的参考：地址怎么写、提供方怎么注册、资源怎么读、状态与失败各是什么意思、模型怎样持有与释放一份资源。
-
-## 地址
-
-资源地址是 `dsh-resource://<type>/…` 形式的 URL。host 命名协议，必须是 `ResourceProtocolMap` 的键；路径归协议自己，由其拥有者逐段做百分号编码。需要作用域的协议把作用域放进路径：`file` 协议的地址形如 `dsh-resource://file/session/<sessionId>/<path>`，其中 path 可以相对工作区根，也可以是保留前导斜杠的绝对路径，用 [`dsh-util-workspace-path`](../../packages/util/workspace-path/README.zh.md) 的 `fileAddressFor(sessionId, cwd, path)` 构造、`parseFileAddress(address)` 读回。模型本身只读 scheme 与 host：`protocolOf(address)` 对 `dsh-resource://` URL 返回小写 host，对其它任何字串返回 `undefined`。其它 scheme 下的地址——Sidebar 的 `sidebar://guide`——不指向资源，读作 `none`。
-
-| 地址 | 协议键 | 读作 |
-|---|---|---|
-| `dsh-resource://file/session/s1/notes/a.md` | `file` | 会话 `s1` 工作区根下 `notes/a.md` 的元数据（`file` 提供方已注册时） |
-| `dsh-resource://file/absolute/home/me/notes.md` | `file` | 可解析，但没有授权 Session，以 `workspace-file/unknown-workspace` 失败；不借用当前或 Tab Session |
-| `DSH-RESOURCE://File/session/s1/a` | `file` | 另一份记录：地址按字符串比较，`openResource` 只接受 `fileAddressFor` 生成的规范小写拼写 |
-| `dsh-resource://subagentchat/session/c1?parent=p1&mode=continuable` | `subagentchat` | 已寻址的 subagent Conversation；其值持有一个 `SessionReference`，直到资源关闭 |
-| `sidebar://guide` | — | `none`：导航地址 |
-| `/home/me/notes.md` | — | `none`：不是 URL |
-
-## 注册提供方
-
-协议拥有者在 `ResourceProtocolMap` 上声明其值类型，并在自己的 `ctx.effect` 里注册一个提供方，使协议与插件同寿（[提供协议](../../packages/client/resources/README.zh.md#provide-a-protocol)）。`open(address, { signal })` 返回一条 `RemoteResult` 帧流——首帧是当前状态，之后每次变化一帧——并且必须在 `signal` 中止时停下。失败是携带 `RemoteFailure` 的 `ok: false` 帧；流里抛出是编程错误，不会被捕获。
-
-```ts ignore-check
-import type { Context } from '@deepseek-ai/cordis'
-import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
-import type {} from '@deepseek-ai/dsh-client-resources/client'
-
-interface NoteView { readonly title: string; readonly updatedAt: string }
-
-declare module '@deepseek-ai/dsh-client-ui-slots' {
-  interface ResourceProtocolMap { note: NoteView }
-}
-
-export const inject = ['resources', 'remote']
-
-export function apply(ctx: Context): void {
-  ctx.effect(() => ctx.resources.register<'note'>({
-    protocol: 'note',
-    async *open(address, { signal }): AsyncIterable<RemoteResult<NoteView>> {
-      const id = new URL(address).pathname.slice(1)
-      yield await ctx.remote.notes.read(id, signal)
-      for await (const change of ctx.remote.notes.follow(id, signal)) yield change
-    },
-  }), 'my-notes: note resource provider')
-}
-```
-
-一个协议恰有一个提供方；第二次注册抛错。注册时若该协议的地址已被持有，则立刻打开它们的流；提供方 dispose 时结束这些流，地址读作 `none` 直到提供方回来。
-
-## 读取资源
-
-每个 slot 组件不论作用域都在 props 上收到 `useResource`（[Slots](slots.zh.md)）。`useResource<P>(address)` 以类型参数命名协议，返回该地址的当前快照；订阅就是持有资源的方式，另一个持有者让资源存活时，新挂载的组件立刻读到最新值而不重开流（[读取资源](../../packages/client/resources/README.zh.md#read-a-resource)）。
-
-| `status` | 含义 | `value` | `failure` |
-|---|---|---|---|
-| `none` | 地址的协议没有注册提供方，或地址不是资源地址 | `undefined` | `undefined` |
-| `loading` | 提供方的流已打开、尚未产出 | `undefined` | `undefined` |
-| `live` | 最新一帧成功 | 最新的 `ok` 值 | `undefined` |
-| `failed` | 最新一帧报告了失败 | 保留的上一个 `ok` 值 | 该帧的 `RemoteFailure` |
-
-```tsx ignore-check
-import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
-import type {} from '@deepseek-ai/dsh-api-workspace-files/client'
-
-type Props = PropsRuntime<'sidebar.right.pane.tab'>
-
-export function FileHeader({ useTabInfo, useResource, t }: Props) {
-  const { tab } = useTabInfo()
-  const meta = useResource<'file'>(tab.contentId)
-  if (meta.status === 'failed') return <p role="alert">{t('failed', { code: meta.failure.code })}</p>
-  return (
-    <header>
-      {tab.title}
-    </header>
-  )
-}
-```
-
-`failed` 由消费方自己呈现：模型把最后一个值留在失败旁，正文可以带提示显示旧内容而不是一片空白，下一个 `ok` 帧会清除失败。模型本身不产生任何用户可见文案。
-
-## 持有与释放
-
-资源有持有者就存活：一个订阅中的 `useResource`，或一次钉住。`ctx.resources.pin(address, signal)` 在不订阅的情况下让资源保持打开直到 `signal` 中止，已中止的信号什么也不钉；右侧 Sidebar 在每条打开的 tab 记录存续期内钉住其地址，因此切 tab 卸载正文不关流。第一个持有者打开提供方的流；最后一个释放时中止它、丢弃值，并把快照回到 `loading`（有提供方）或 `none`（没有）。提供方在这次释放之后产出的帧被丢弃，迭代器被归还。`ctx.resources.source(address)` 是 hook 背后的裸 observable，按地址引用稳定，供 React 之外的调用方使用；只读它的快照不算持有（[生命周期](../../packages/client/resources/README.zh.md#lifecycle)）。
-
-多数流只推元数据而不推内容。`file` 提供方的值是 `WorkspaceFileStat { absolutePath, version, bytes? }`：首帧来自 Host 的 `stat`，后续观察更新版本。消费方自己经 Workspace Files Remote 命名空间读取内容；Preview 按 tab 独立刷新（[`dsh-api-workspace-files`](../../packages/api/workspace-files/README.zh.md)）。`subagentchat` 提供方保留已寻址 Session 并产出其 `SessionReference`，在资源 signal 中止时释放该 reference。
-
-## 限制
-
-记录在页面存续期内保留：地址的记录在最后一个持有者离开后仍留着，不持有流也不持有值，因此内存随读过的不同地址数增长。忽略 `signal` 的提供方会一直跑到它的下一帧。失败类型是 Remote 面的 `RemoteFailure`，来源不是 Remote 调用的提供方得自己铸一个。拼错的协议或畸形的地址读作 `none`，没有别的诊断。

package/references/official-docs/docs/subsystems/commands.i18n.yaml

@@ -1,19 +0,0 @@
-# Bilingual-pair consistency record for commands.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/subsystems/commands.md
-/human-commands:
-  en: cc09de9b4b08d24f
-  zh: 02217510953c535b
-/human-commands/input-metadata:
-  en: 9c7fd38926610b58
-  zh: 40f1b2fd9b18ed52
-/human-commands/definition:
-  en: 8d1944548766d286
-  zh: b804059b5875984f
-/human-commands/invocation-and-result:
-  en: c60c29cb7135ac76
-  zh: c2c2a79d4d73959e
-/human-commands/discovery-and-parsing-views:
-  en: a3bcb9354133cf68
-  zh: 4699cb44ca9662e3