dsh-plugin-guide 0.3.21 → 0.3.23

package/references/official-docs/docs/subsystems/user-questions.zh.md

@@ -22,7 +22,7 @@ interface AskUserQuestionOption {
 
 ## 呈现意图
 
-`AskUserQuestionIntent` 可选地声明一种已知的决策类型。它按 `kind` 打标签，因此可以增加新的意图；不认识某个标签的 UI 渲染通用选项列表。意图只改变呈现方式——遵循它的 UI 回答的仍是通用 UI 会发送的那些选项标签，因此调用方两种情况下读到的回答字段相同。`approve` 指名肯定选项，而不依赖选项顺序。`ask()` 会拒绝两种无法由类型系统表达的情况：`approve` 未指向该问题自身的任何选项，以及为没有 `detail` 的问题指定意图。
+`AskUserQuestionIntent` 可选地声明一种已知的决策类型。它以 `kind` 作为标记，以便后续加入更多意图；不认识某个标记的 UI 会渲染通用选项列表。意图只改变呈现——遵循它的 UI 回答的选项标签与通用 UI 相同，因此调用方读到的答案字段一致。`approve` 指明表示同意的选项，而不依赖选项顺序。`ask()` 拒绝两种类型无法表达的断言：`approve` 未命名该问题自己的任何选项，以及没有 `detail` 的问题声明了意图。
 
 ```ts type-equiv
 /**
@@ -103,9 +103,96 @@ interface AskUserQuestionAnswer {
 }
 ```
 
+计时回答器收到 `wait: { callId, timed: true }`。调用 id 标识卡片及前台等待。Client 调用 `attachWait` 接手等待并取得剩余时长；传输层转发原事件，不检查或改写这些字段。不带 `timed` 的 `wait` 表示无限期等待的具名卡片请求；没有 `wait` 则表示不带卡片 key 的阻塞请求。
+
+```ts type-equiv
+/** Client-safe payload declared for the user-question answerer waterfall. */
+interface AskUserQuestionRequestEvent {
+  /** Questions to display. */
+  questions: AskUserQuestionItem[]
+  /** Agent identity projected to the corresponding Client Context in transit. */
+  agent?: Agent
+  /** Cancellation lifetime of the pending request. */
+  signal?: AbortSignal
+  /**
+   * Tool call the Client card is keyed by. Timed answerers attach to the
+   * business wait stream before starting their local countdown.
+   */
+  wait?: {
+    /** Tool call the Client card is keyed by. */
+    callId: ToolCallId
+    /** True for a foreground wait that requires a Client claim; absent for indefinite waits. */
+    timed?: boolean
+  }
+}
+```
+
+## 计时问题与迟到回复
+
+计时问题在有界的前台窗口内等待，然后让 agent 继续独立工作。用户在窗口内回答，工具返回整批答案；否则 `TimedUserQuestionResult` 为 `{ pending: true, callId }`。pending 表示问题仍可回答，不是空答案、拒绝、确认或授权。
+
+```ts type-equiv
+/** Timed ask result returned when the foreground answer window closes. */
+type TimedUserQuestionResult = AskUserQuestionAnswer | { pending: true; callId: ToolCallId }
+```
+
+Client 接手通过业务 Remote stream 表达，不等同于 Gateway 投递。`TimedQuestionWait` 保存原 Host deadline，仅在没有接手记录时运行计时器。`attachWait` stream 发出当前剩余时长，Client 用本地时钟倒计时。聚焦、编辑和「慢慢回答」状态仍归本地所有。stream 取消释放相应接手记录；最后一个接手方离开后，Host 恢复原 deadline。无人接手时超时中止前台 waterfall 专属的 signal 并返回 pending，不取消 Turn。Gateway 与 `api-remotes` 不包含问答专属计时策略。
+
+`userQuestions` Session 投影把现有事件折叠成可回答的问题集合与已结算的集合；不记录任何等待状态、聚焦状态或 deadline。每个 `request/header` 都记录了模型看到的确切工具 schema。只有请求头声明了带 `timeout` 参数的 timed `ask_user_question` schema，投影才跟踪原生调用；阻塞式 legacy 工具从不声明它。原生 `tool/call` 打开一个问题。`tool/result` 只在两种情况下把它标为 `continued`：带 pending 载荷，或是 Session resume 修复补写的 `TOOL_OUTCOME_UNKNOWN` 合成结果；回答批次把它连同该批次移入 `settled`，其他结果或失败都丢弃它。`run_code` 的 PTC 子调用若在 `tool/ptc-dispatch` 结果中返回 pending，也会进入投影，尽管请求头只列出 `run_code`。迟到回复在消息获准成为 `user/message` 时，才把已继续的问题连同消息中的回答批次移入 `settled`：计时调用自己的结果记录的是超时，transcript 行无处可读用户最终的选择。排队的回复可在准入前取消，此时问题仍可回答。回复正文不含可读批次时，该调用以零答案结算；回复指向的调用已不在可回答集合中时不改变任何内容。
+
+```ts type-equiv
+/** `open` while the tool call may still return the answer; `continued` once the answer can only arrive as a new turn. */
+type UserQuestionState = 'open' | 'continued'
+```
+
+```ts type-equiv
+/** One unanswered timed `ask_user_question` call reconstructed from the Session log. */
+interface PendingUserQuestion {
+  readonly callId: ToolCallId
+  readonly questions: readonly AskUserQuestionItem[]
+  readonly state: UserQuestionState
+}
+```
+
+```ts type-equiv
+/**
+ * One timed `ask_user_question` call and the answers it settled with: the
+ * batch its own result carried when the user answered inside the window,
+ * otherwise the batch its late reply carried, because that call's own result
+ * recorded the timeout. A transcript row reads what the user finally answered
+ * from here, and only a call listed here was a timed one.
+ */
+interface SettledUserQuestion {
+  /** The settled call. */
+  readonly callId: ToolCallId
+  /** The recorded batch, one entry per question; empty when the late reply carried none. */
+  readonly answers: readonly AskUserQuestionAnswerItem[]
+}
+```
+
+```ts type-equiv
+/**
+ * Both halves of one Session's timed `ask_user_question` state, as every
+ * Client reads them. A call made while the blocking legacy tool was in
+ * effect appears in neither half.
+ */
+interface UserQuestionProjectionView {
+  /** Calls that can still take an answer, in ask order. */
+  readonly active: readonly PendingUserQuestion[]
+  /** Calls an answer settled, in settlement order. */
+  readonly settled: readonly SettledUserQuestion[]
+}
+```
+
+开放中的问题只能通过 waterfall 回答。问题变为 `continued` 后，`answer` Remote 方法向所属 agent 排入一条用户消息，并在其空闲时唤醒它。消息的 source 为 `user-question-reply`，outcome 为 `answered`，正文是 `answer_to_pending_question` 载荷。开放或未知调用返回 `false`；回复仍在排队时的第二次提交以 `REPLY_QUEUED` 拒绝，Host 重启后也一样；遗漏或重复问题的回答批次以 `BAD_ANSWER` 拒绝。
+
+收起 Client 面板不会发送内容。前台超时只结束工具等待。已继续的问题没有期限；在回复进入会话前，问题仍可回答。
+
+Host 重启后，Session 重开时 Remote 层会恢复根 agent。之后的迟到回复会作为新一轮进入。
+
 ## 错误
 
-`UserQuestionError` 继承 `HarnessError`，因此 `ctx.tools.execute()` 会保留 `{ name, code }`，用于面向模型的工具失败，如 `EMPTY_QUESTIONS`、`NO_PROVIDER`、`ASK_ABORTED` 或 UI 侧取消。
+`UserQuestionError` 继承 `HarnessError`，因此 `ctx.tools.execute()` 会保留 `{ name, code }`，用于面向模型的工具失败，如 `EMPTY_QUESTIONS`、`BAD_INTENT`、`NO_PROVIDER`、`ASK_ABORTED` 或 UI 侧取消。
 
 ```ts type-equiv
 /** Stable error taxonomy for user-questions failures. */
@@ -132,6 +219,44 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp
 `ctx.userQuestions`: validation plus the scoped answerer waterfall.
 
 ```ts cordis-catalog
+/**
+ * Answer a continued question. The reply is steered into the agent as a
+ * user message whose source names the call; that message is also the
+ * record that closes the question in the projection.
+ * @param agent - Live root agent for the owning Session.
+ * @param callId - Continued question identity.
+ * @param answer - Complete structured answer batch, one item per question of the call.
+ * @returns Whether the question is still continued; an accepted reply stays
+ *   queued until the agent admits its user message.
+ * @throws {UserQuestionError} `BAD_ANSWER` when the batch does not name each
+ *   question of the call exactly once, or `REPLY_QUEUED` when a reply is
+ *   already waiting for admission.
+ */
+@Remote answer(agent: Agent, callId: ToolCallId, answer: AskUserQuestionAnswer): boolean
+
+/**
+ * Let one answer UI hold a live timed wait. Closing the stream releases its claim.
+ * @param agent - Live root agent owning the question.
+ * @param callId - Foreground tool call to attach to.
+ * @param signal - Remote stream cancellation, including Client disconnect.
+ * @returns One Host-computed remaining duration, or no frames once the wait ended.
+ */
+@Remote({ mode: 'stream' }) async *attachWait(agent: Agent, callId: ToolCallId, signal: AbortSignal): AsyncIterable<{ remainingMs: number }>
+
+/**
+ * Foreground wait whose first settlement the Client decides: the Client
+ * rejects with `ASK_TIMED_OUT` when its countdown ends, and this method maps
+ * that code to the pending result.
+ * @param request - Questions, live owner agent, and abort signal.
+ * @param callId - Tool call identity the Client card is keyed by.
+ * @param timeoutMs - Positive foreground wait in milliseconds.
+ * @returns The answer when it arrives inside the window, otherwise a pending
+ *   result, also when no connected Client claimed the request by the deadline.
+ * @throws {UserQuestionError} `BAD_TIMEOUT` for a non-integer, non-positive,
+ *   or oversized wait.
+ */
+async askTimed( request: AskUserQuestionRequest & { agent: Agent }, callId: ToolCallId, timeoutMs: number, ): Promise<TimedUserQuestionResult>
+
 /**
  * Ask the scoped answerer waterfall and wait for the user's answer.
  *
@@ -151,6 +276,8 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp
 async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
 ```
 
+Types: [Agent](core.zh.md) · [ToolCallId](core.zh.md)
+
 Source: [`packages/interaction/user-questions/src/index.ts`](../../packages/interaction/user-questions/src/index.ts)
 
 <a id="user-questions-events"></a>

package/references/official-docs/docs/subsystems/voice-input.i18n.yaml

@@ -0,0 +1,19 @@
+# Bilingual-pair consistency record for voice-input.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/voice-input.md
+/voice-input:
+  en: b21f58d0dcb90287
+  zh: be60807d02623a87
+/voice-input/provider-selection:
+  en: 3a5ec4718b839349
+  zh: a8448bd6064d4c81
+/voice-input/browser-and-host-ownership:
+  en: 404d67d8276522db
+  zh: f653397888d2e616
+/voice-input/preparation-and-settings:
+  en: 9350b2e58813262e
+  zh: c3b5e5cb100408af
+/voice-input/design-rationale:
+  en: 604b86d95ac007b3
+  zh: 472db5ba5905eddc

package/references/official-docs/docs/subsystems/voice-input.md

@@ -0,0 +1,164 @@
+# Voice input
+
+English | [中文](voice-input.zh.md)
+
+Experimental speech recognition has three roles: the [Service Definition](../../packages/experimental/speech-to-text/README.md) routes named providers, the [SenseVoice provider](../../packages/experimental/speech-to-text-sensevoice/README.md) owns local inference, and the [Remote consumer](../../packages/experimental/api-speech-to-text/README.md) serves the browser. The [optional bundle](../../packages/experimental/voice-input-bundle/README.md) composes them with the microphone UI.
+
+## Provider selection
+
+`SpeechProviderId` brands the registration identity. `SpeechProviderInfo` carries a display name, accepted `languages` hints and `host-local` or `cloud` processing location. `SpeechRequest` contains WAV bytes and optional provider/language selection; `resolve()` produces `SpeechSpec` with one captured provider instance. A missing provider or unsupported language fails; replacement or withdrawal invalidates resolved work. Audio never falls back to a different provider.
+
+`SpeechProvider.transcribe()` accepts one complete `SpeechInput` and an `AbortSignal`. `Transcript` returns plain `text`, `audioSeconds` and `inferenceSeconds`. Providers honor cancellation and settle their work before deregistration completes. The local provider serializes calls, bounds its queue and manages its worker lifetime independently of Sessions.
+
+## Browser and Host ownership
+
+The browser owns microphone tracks and the unsent draft. `TranscriptionRequest` sends canonical base64 PCM16 WAV through the authenticated Remote. `SpeechCatalog` advertises available providers, the default selection and recording byte/duration limits. The API validates this process input before recognition.
+
+The input facade captures a revision-bearing selection before recording. `InputActions.insertText()` inserts one undoable plain-text edit only while the selection revision is current and submission permits editing. A rejected insertion leaves the transcript available for explicit insertion. Switching Sessions or disposing the plugin invalidates late results. Recognition itself writes no Session event; ordinary user submission owns the final model-visible text.
+
+## Preparation and settings
+
+`SpeechProviderInfo.downloadSources` advertises preparation origins. `SpeechPreparationOptions.downloadSource` selects one for a task; omission preserves provider policy. SenseVoice validates the advertised choice, pins a manual source without fallback, and rejects source changes during active preparation. The UI keeps a choice for retries in the current card; it is not a persisted recognition preference.
+
+The Host provider owns one preparation task across page and Session changes. The Client shares one `follow()` subscription across the composer, setup prompt and bundle details. Optional `SpeechSetupEstimate` metadata supplies provider-specific planning hints, separate from measured progress. `SpeechPreparationStepKind` identifies ordered resource operations; `SpeechPreparationStep` records each status and start time. The complete `SpeechPreparationState` retains these steps after cancellation or failure. The collapsed UI shows the current operation; expanding lists all steps, with byte progress or elapsed time only for the running step. Closing an observer never cancels preparation. Verified files survive retries and idle worker reclamation.
+
+Failed preparation can include `SpeechDownloadFailure` with the asset, source origin, classified reason and optional diagnostic code or HTTP status. The Client localizes recovery advice; raw download causes remain on the Host.
+
+The microphone occupies `conversation.input.activity`, between the model selector and Send. Clicking starts capture and expands the toolbar; Stop transcribes and inserts into the draft. The activity preserves the editor and submit action, owns local feedback, and releases expansion on unmount. Cancel, Escape or hiding the page discards capture. Waveform history displays measured microphone amplitude. Bundle details contain recognition preferences, preparation state and progress. Explicit enablement uses `plugins.bundle.activation` to guide users with missing models to setup; the list shows only the bundle description and switch.
+
+## Design rationale
+
+The [voice input decision](../../.agents/notes/implemented/architecture/2026-09-16-experimental-voice-input.md) explains transient audio, explicit provider selection and lazy local preparation.
+
+<!-- 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.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxspeechcontroller--speechcontroller"></a>
+
+### `ctx.speechController` — `SpeechController`
+
+Speech calls never activate or submit to an Agent.
+
+```ts cordis-catalog
+/**
+ * Read provider choices without preparing a recognizer.
+ * @returns available providers, resolved default, and recording limits.
+ */
+@Remote catalog(): SpeechCatalog
+
+/**
+ * Follow provider readiness independently of Session and preparation lifetimes.
+ * @param signal - Client observation lifetime.
+ * @returns initial and subsequent complete readiness snapshots.
+ */
+@Remote({ mode: 'stream' }) async *follow(signal: AbortSignal): AsyncIterable<SpeechCatalog>
+
+/**
+ * Persist the user's recognition preferences.
+ * @param patch - changed preference fields.
+ * @returns after preferences are saved.
+ */
+@Remote configure(patch: SpeechSelectionPatch): Promise<void>
+
+/**
+ * Start or join one Host-owned preparation task.
+ * @param providerId - selected recognizer.
+ * @param options - task-local source selection validated by the provider.
+ */
+@Remote prepare(providerId: SpeechProviderId, options?: SpeechPreparationOptions): void
+
+/**
+ * Explicitly cancel resource preparation.
+ * @param providerId - selected recognizer.
+ * @returns after the preparation task settles.
+ */
+@Remote cancelPreparation(providerId: SpeechProviderId): Promise<void>
+
+/**
+ * Validate and transcribe one recording through the explicit provider selection.
+ * @param request - canonical WAV encoded as base64, provider id and language hint.
+ * @param signal - Client cancellation or Remote contribution disposal.
+ * @returns final transcript without adding a Session event.
+ */
+@Remote async transcribe(request: TranscriptionRequest, signal: AbortSignal): Promise<Transcript>
+```
+
+Source: [`packages/experimental/api-speech-to-text/src/index.ts`](../../packages/experimental/api-speech-to-text/src/index.ts)
+
+<a id="ctxspeechtotext--speechtotext"></a>
+
+### `ctx.speechToText` — `SpeechToText`
+
+Registry shared by all transcription consumers in one Host composition.
+
+```ts cordis-catalog
+/**
+ * Register one recognizer; duplicate ids fail without replacing the original.
+ * @param provider - recognizer owned by the contributing fiber.
+ * @returns idempotent disposer which rejects admission, cancels, and joins accepted work.
+ */
+register(provider: SpeechProvider): () => Promise<void>
+
+/**
+ * Read the current recognizer roster.
+ * @returns available provider facts in registration order.
+ */
+listProviders(): readonly SpeechProviderInfo[]
+
+/**
+ * Observe complete readiness snapshots; a slow reader coalesces intermediate progress.
+ * @param caller - observer lifetime, independent of any preparation task.
+ * @returns an initial snapshot followed by the latest provider states.
+ */
+async *follow(caller: AbortSignal): AsyncIterable<SpeechSnapshot>
+
+/**
+ * Read provider readiness and current user preferences together.
+ * @returns one detached complete observation.
+ */
+snapshot(): SpeechSnapshot
+
+/**
+ * Persist changed selection fields into this plugin's profile entry; the resulting language must be accepted by the selected provider.
+ * @param patch - explicit provider or language changes.
+ * @returns after the profile write and the live update it applies.
+ */
+async configure(patch: SpeechSelectionPatch): Promise<void>
+
+/**
+ * Start or join provider-owned preparation.
+ * @param id - exact registered provider identity.
+ * @param options - task-local source selection validated by the provider.
+ */
+prepare(id: SpeechProviderId, options?: SpeechPreparationOptions): void
+
+/**
+ * Explicitly cancel provider preparation without tying it to a browser connection.
+ * @param id - exact registered provider identity.
+ * @returns after the preparation task settles.
+ */
+async cancelPreparation(id: SpeechProviderId): Promise<void>
+
+/**
+ * Apply composition defaults and capture the selected provider. Missing providers and unsupported languages fail explicitly.
+ * @param request - complete recording and optional selection.
+ * @returns provider-pinned input for transcribe().
+ */
+resolve(request: SpeechRequest): SpeechSpec
+
+/**
+ * Execute exactly the resolved provider; no fallback sends audio elsewhere.
+ * @param spec - resolved input; a withdrawn or replaced registration is rejected.
+ * @param signal - caller cancellation.
+ * @returns final transcript after provider settlement.
+ */
+async transcribe(spec: SpeechSpec, signal: AbortSignal): Promise<Transcript>
+```
+
+Source: [`packages/experimental/speech-to-text/src/index.ts`](../../packages/experimental/speech-to-text/src/index.ts)
+<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/voice-input.zh.md

@@ -0,0 +1,164 @@
+# 语音输入
+
+[English](voice-input.md) | 中文
+
+实验性语音识别包含三个角色：[服务定义](../../packages/experimental/speech-to-text/README.zh.md)路由具名 Provider，[SenseVoice Provider](../../packages/experimental/speech-to-text-sensevoice/README.zh.md)拥有本地推理，[Remote 消费者](../../packages/experimental/api-speech-to-text/README.zh.md)服务浏览器。[可选 Bundle](../../packages/experimental/voice-input-bundle/README.zh.md)将它们与麦克风 UI 组合。
+
+## Provider 选择
+
+`SpeechProviderId` 为注册标识添加类型品牌。`SpeechProviderInfo` 携带显示名称、支持的 `languages` 语言提示及 `host-local` 或 `cloud` 处理位置。`SpeechRequest` 包含 WAV 字节和可选的 Provider、语言选择；`resolve()` 生成捕获一个 Provider 实例的 `SpeechSpec`。缺失的 Provider 或不支持的语言会报错；替换或撤销会使已解析的任务失效。音频不会回退到其他 Provider。
+
+`SpeechProvider.transcribe()` 接收完整的 `SpeechInput` 与 `AbortSignal`。`Transcript` 返回纯文本 `text`、`audioSeconds` 和 `inferenceSeconds`。Provider 响应取消，并在注销完成前结束其任务。本地 Provider 串行执行调用、限制队列，并独立于 Session 管理工作进程生命周期。
+
+## 浏览器与 Host 所有权
+
+浏览器拥有麦克风轨道与未发送的草稿。`TranscriptionRequest` 通过带认证的 Remote 发送规范 base64 PCM16 WAV。`SpeechCatalog` 公布可用 Provider、默认选择及录音字节和时长限制。API 在识别前校验这些进程输入。
+
+输入门面在录音前捕获带版本的选区。`InputActions.insertText()` 仅在选区版本仍有效且提交状态允许编辑时，插入一次可撤销的纯文本编辑。插入被拒绝时，转写文字保留以供显式插入。切换 Session 或释放插件使迟到结果失效。识别本身不写入 Session 事件；普通用户提交拥有最终的模型可见文字。
+
+## 准备与设置
+
+`SpeechProviderInfo.downloadSources` 公布准备阶段的源。`SpeechPreparationOptions.downloadSource` 为单次任务选择一个源；省略时保留提供方策略。SenseVoice 校验公布的选项，固定使用手动指定的源而不回退，并拒绝在准备期间改源。UI 为当前卡片中的重试保留选择，但不会将其保存为识别偏好。
+
+Host Provider 在页面和 Session 变化期间拥有同一个准备任务。Client 在输入框、安装引导弹窗、Bundle 详情之间共享一份 `follow()` 订阅。可选 `SpeechSetupEstimate` 元数据提供各 Provider 的资源预期，与实测进度分开。`SpeechPreparationStepKind` 标识有序资源操作；`SpeechPreparationStep` 记录各步骤状态与开始时间。完整 `SpeechPreparationState` 在取消或失败后保留这些步骤。折叠 UI 显示当前操作，展开后列出所有步骤，仅进行中步骤显示字节进度或等待时间。关闭观察者不会取消准备。已校验文件在重试及空闲进程回收后继续复用。
+
+准备失败时可包含 `SpeechDownloadFailure`，提供文件、下载源、原因分类以及可选错误码或 HTTP 状态。Client 将恢复建议本地化；原始下载错误留在 Host。
+
+麦克风占用模型选择器与发送按钮之间的 `conversation.input.activity`。点击开始录音并展开工具栏；停止后转写并插入草稿。活动栏保留编辑器与提交按钮，拥有局部反馈，并在卸载时释放展开状态。取消、Escape 或隐藏页面会丢弃录音。波形历史展示实测麦克风音量。Bundle 详情包含识别偏好、准备状态和进度。显式启用时通过 `plugins.bundle.activation` 引导缺少模型的用户前往安装；列表只显示 Bundle 描述和开关。
+
+## 设计依据
+
+[语音输入决策](../../.agents/notes/implemented/architecture/2026-09-16-experimental-voice-input.zh.md)解释临时音频、显式 Provider 选择和延迟准备本地运行时。
+
+<!-- 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="ctxspeechcontroller--speechcontroller"></a>
+
+### `ctx.speechController` — `SpeechController`
+
+Speech calls never activate or submit to an Agent.
+
+```ts cordis-catalog
+/**
+ * Read provider choices without preparing a recognizer.
+ * @returns available providers, resolved default, and recording limits.
+ */
+@Remote catalog(): SpeechCatalog
+
+/**
+ * Follow provider readiness independently of Session and preparation lifetimes.
+ * @param signal - Client observation lifetime.
+ * @returns initial and subsequent complete readiness snapshots.
+ */
+@Remote({ mode: 'stream' }) async *follow(signal: AbortSignal): AsyncIterable<SpeechCatalog>
+
+/**
+ * Persist the user's recognition preferences.
+ * @param patch - changed preference fields.
+ * @returns after preferences are saved.
+ */
+@Remote configure(patch: SpeechSelectionPatch): Promise<void>
+
+/**
+ * Start or join one Host-owned preparation task.
+ * @param providerId - selected recognizer.
+ * @param options - task-local source selection validated by the provider.
+ */
+@Remote prepare(providerId: SpeechProviderId, options?: SpeechPreparationOptions): void
+
+/**
+ * Explicitly cancel resource preparation.
+ * @param providerId - selected recognizer.
+ * @returns after the preparation task settles.
+ */
+@Remote cancelPreparation(providerId: SpeechProviderId): Promise<void>
+
+/**
+ * Validate and transcribe one recording through the explicit provider selection.
+ * @param request - canonical WAV encoded as base64, provider id and language hint.
+ * @param signal - Client cancellation or Remote contribution disposal.
+ * @returns final transcript without adding a Session event.
+ */
+@Remote async transcribe(request: TranscriptionRequest, signal: AbortSignal): Promise<Transcript>
+```
+
+Source: [`packages/experimental/api-speech-to-text/src/index.ts`](../../packages/experimental/api-speech-to-text/src/index.ts)
+
+<a id="ctxspeechtotext--speechtotext"></a>
+
+### `ctx.speechToText` — `SpeechToText`
+
+Registry shared by all transcription consumers in one Host composition.
+
+```ts cordis-catalog
+/**
+ * Register one recognizer; duplicate ids fail without replacing the original.
+ * @param provider - recognizer owned by the contributing fiber.
+ * @returns idempotent disposer which rejects admission, cancels, and joins accepted work.
+ */
+register(provider: SpeechProvider): () => Promise<void>
+
+/**
+ * Read the current recognizer roster.
+ * @returns available provider facts in registration order.
+ */
+listProviders(): readonly SpeechProviderInfo[]
+
+/**
+ * Observe complete readiness snapshots; a slow reader coalesces intermediate progress.
+ * @param caller - observer lifetime, independent of any preparation task.
+ * @returns an initial snapshot followed by the latest provider states.
+ */
+async *follow(caller: AbortSignal): AsyncIterable<SpeechSnapshot>
+
+/**
+ * Read provider readiness and current user preferences together.
+ * @returns one detached complete observation.
+ */
+snapshot(): SpeechSnapshot
+
+/**
+ * Persist changed selection fields into this plugin's profile entry; the resulting language must be accepted by the selected provider.
+ * @param patch - explicit provider or language changes.
+ * @returns after the profile write and the live update it applies.
+ */
+async configure(patch: SpeechSelectionPatch): Promise<void>
+
+/**
+ * Start or join provider-owned preparation.
+ * @param id - exact registered provider identity.
+ * @param options - task-local source selection validated by the provider.
+ */
+prepare(id: SpeechProviderId, options?: SpeechPreparationOptions): void
+
+/**
+ * Explicitly cancel provider preparation without tying it to a browser connection.
+ * @param id - exact registered provider identity.
+ * @returns after the preparation task settles.
+ */
+async cancelPreparation(id: SpeechProviderId): Promise<void>
+
+/**
+ * Apply composition defaults and capture the selected provider. Missing providers and unsupported languages fail explicitly.
+ * @param request - complete recording and optional selection.
+ * @returns provider-pinned input for transcribe().
+ */
+resolve(request: SpeechRequest): SpeechSpec
+
+/**
+ * Execute exactly the resolved provider; no fallback sends audio elsewhere.
+ * @param spec - resolved input; a withdrawn or replaced registration is rejected.
+ * @param signal - caller cancellation.
+ * @returns final transcript after provider settlement.
+ */
+async transcribe(spec: SpeechSpec, signal: AbortSignal): Promise<Transcript>
+```
+
+Source: [`packages/experimental/speech-to-text/src/index.ts`](../../packages/experimental/speech-to-text/src/index.ts)
+<!-- END GENERATED cordis-surface -->

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

@@ -1,6 +1,37 @@
-# 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:
+# Bilingual-pair consistency record for web-client.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/web-client.md
-web-client.md: c1c3c70d68aedc63da0a6e7aebd0b48d56886853
-web-client.zh.md: 42adffe958f9034f4d450d99dffcef85bcee19a2
+/web-client-architecture:
+  en: 4936655bc5d3ba5b
+  zh: 062419330dea65b3
+/web-client-architecture/layers-and-ownership:
+  en: c0454bca818f86ee
+  zh: 427582150fd3b976
+/web-client-architecture/browser-boot:
+  en: 5ac7d3aed7bf273a
+  zh: e34869c8ad64052d
+/web-client-architecture/remote-communication:
+  en: 426b09164210b77a
+  zh: ce576099ee668984
+/web-client-architecture/client-models:
+  en: 13be17c2a2790ae9
+  zh: f5af715d0ae222be
+/web-client-architecture/client-models/sessions:
+  en: e010ab37d059025f
+  zh: f857a2fc2720a28f
+/web-client-architecture/client-models/workspaces:
+  en: c063711f8247c240
+  zh: 5e54758bbaf1670c
+/web-client-architecture/conversation-and-presentation:
+  en: 71362f4ac9490bcb
+  zh: 025507ca615f5e2a
+/web-client-architecture/data-paths:
+  en: a254278432416473
+  zh: 567c2d3c6a20b304
+/web-client-architecture/reconnection:
+  en: 478f461e261b1ca5
+  zh: 626791d04656faee
+/web-client-architecture/package-boundaries:
+  en: 3e64e8c28f0c4cb1
+  zh: 47aa81c2ace5ba89

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

@@ -4,6 +4,8 @@ English | [中文](web-client.zh.md)
 
 The Web Client is a browser-side Cordis application assembled from independently loaded plugins. Its architecture has four reusable foundations: [Client Modules](client-modules.md) loads the plugin graph, the [API Gateway](../api-gateway.md) provides typed Host communication, [Slots](slots.md) composes React UI, and [Conversation](conversation.md) turns a Session history window into target-owned views. This page connects those systems and defines where Client models and feature packages belong.
 
+[Keyboard shortcuts](../../packages/client/shortcuts/README.md) owns window-local command registration and physical-key dispatch; [the shortcut reference](../../packages/client/ui-shortcuts/README.md) presents available commands and local input actions. Command owners declare each runtime/platform default and share their existing actions with mouse controls. The shared modal primitive arbitrates top-layer Escape and restores focus.
+
 ## Layers and ownership
 
 | Layer | Main owners | Responsibility |
@@ -27,7 +29,7 @@ The Web boot kernel creates the module system, prefetches `immediately` entries,
 
 Host business services annotate callable methods with Typert Remote decorators. Host generation emits strict descriptors, runtime codecs, declaration merges, and source maps. The Client-side `api-remotes` assembly selects those generated contributions and mounts concrete methods under `ctx.remote.<namespace>` and Session-scoped `agentCtx.remote.<namespace>`. Feature packages depend on the generated service face, not the Gateway implementation or a Host package's runtime entry.
 
-The Connection owns request correlation, the `/api` carrier, trust checks, exact Fetch routes, and connection generations. API Gateway owns Remote dispatch, cancellation, logical streams, and selected Host event forwarding. Controller operations belong on generated Remote methods or explicit Remote streams; feature-owned downloads register exact Fetch routes. The [API Gateway reference](../api-gateway.md) defines generation and invocation, while the [Connection README](../../packages/client/connection/README.md) defines the physical carrier and trust policy.
+The Connection owns request URL resolution, correlation, the `/api` carrier, trust checks, exact Fetch routes, and connection generations. API Gateway owns Remote dispatch, cancellation, logical streams, and selected Host event forwarding. Controller operations belong on generated Remote methods or explicit Remote streams; feature-owned downloads register exact Fetch routes. The [API Gateway reference](../api-gateway.md) defines generation and invocation, while the [Connection README](../../packages/client/connection/README.md) defines the physical carrier and trust policy.
 
 The internal `$events` logical stream is the Connection generation source. Its opening `ready` frame carries the Host home used for path display and establishes the generation after Host listeners are attached, before any controller begins a baseline read. `ctx.remote.$on()` delivers allowlisted ordinary events to the root Client Context and scoped waterfall events to the resolved Session Context; a waterfall listener returns a result, calls `next()`, or rejects.
 
@@ -40,19 +42,21 @@ Each API controller package owns a paired Host and Client face. The Host side ow
 [`api/session-controller`](../../packages/api/session-controller/README.md) exposes Host commands for list, search, creation, prompt, queue, cancellation, pagination, and follow/control streams. Its Client side is organized as `ClientSessions → SessionManager → Session`:
 
 - `ClientSessions` provides `ctx.sessions`, owns references, source counts, Session scopes, and stable `SessionBinding` objects, and projects catalog state without selecting a global current Session.
-- `SessionManager` owns the list baseline, live list/control updates, lazy Session instances, queues, projection stores, subagent catalogs, and conflict ordering between pulls and later updates.
+- `SessionManager` owns the list baseline, live list/control updates, lazy Session instances, projection stores, subagent catalogs, and conflict ordering between pulls and later updates.
 - Each `Session` owns one contiguous logical-event window represented by `SessionEventLikeEntry` values, paging, follow, prompt/control state, and the observable snapshot consumed by adapters.
 
-The durable event path opens `follow()`, whose first frame contains the current header, tail page, cursor, and complete projection baseline. History records have an explicit `event` or `chunks` discriminator and an aligned inner `event`; the journal validates each inclusive logical sequence range before the Client retains the records as `SessionEventLikeEntry` values without per-record conversion. Each physical generation atomically replaces the retained window from that snapshot; standard live events then append by sequence. `page()` is reserved for older history and gap repair. The transient control stream starts every generation with a complete baseline and then applies queue, job, and projection updates.
+The durable event path opens `follow()`, whose first frame contains the current header, tail page, cursor, and complete projection baseline. History records have an explicit `event` or `chunks` discriminator and an aligned inner `event`; the journal validates each inclusive logical sequence range before the Client retains the records as `SessionEventLikeEntry` values without per-record conversion. Each physical generation atomically replaces the retained window from that snapshot; standard live events then append by sequence. `page()` is reserved for older history and gap repair. The transient control stream starts every generation with a complete baseline and then applies projection updates.
 
 ### Workspaces
 
-[`api/workspace-controller`](../../packages/api/workspace-controller/README.md) keeps Workspace mutation policy and the authoritative follow feed on the Host. `ClientWorkspaceModel` owns the browser rows, order, archived Session ids, command echoes, and stream/unary race resolution. Every stream generation starts with a complete baseline followed by `upsert`, `remove`, `order`, and `archived` increments; reconnect replaces the model from the new baseline. `WorkspaceController` exposes that model as `ctx.workspaces`, while `ui-workspace` contributes `useWorkspaces` and navigation callbacks to the UI. The archived Session ids filter every grouping surface and feed the archived-sessions Settings page, which joins the set with the loaded Session summaries and offers one Unarchive action per row; a restore calls the `workspace.unarchiveSession` Remote, and the complete returned set reaches every Client through the `archived` increment.
+[`api/workspace-controller`](../../packages/api/workspace-controller/README.md) keeps Workspace mutation policy and the authoritative follow feed on the Host. `ClientWorkspaceModel` owns browser rows, Workspace order, archived and pinned Session id arrays, command echoes, and stream/unary race resolution. Every stream generation starts with a complete baseline followed by `upsert`, `remove`, `order`, `archived`, and `pinned` increments; reconnect replaces the model from the new baseline. `WorkspaceController` exposes that model as `ctx.workspaces`, while `ui-workspace` contributes `useWorkspaces` and navigation callbacks. The sidebar's `ArchivedFilter` controls default-hidden, shown, or archived-only rows in lists and search. Archived rows retain their ordering slots, render grayed, and cannot open until restored through the row or search-result Unarchive action. Restoration calls `workspace.unarchiveSession`, and its complete archive set reaches Clients through the unary response and `archived` increment. Session display order stays browser-local and includes hidden archives; pinning moves a Session within that full order, while unpinning does not restore its earlier position.
 
 This pairing is not a second source of business truth. Host controllers decide durable state and mutation outcomes; Client models maintain the latest usable local projection, preserve object identity where useful to rendering, and encode how delayed responses and replacement baselines merge.
 
 ## Conversation and presentation
 
+Web and desktop share the [Coding Tools preference](../../packages/client/ui-settings/README.md#use-this-package). It controls diagnostic Views, [available preset choices](../../packages/client/ui-agent-preset/README.md), changed-file cards, and the builtin HTML preview policy without changing Session records.
+
 `ui-session` installs the Session scope adapter and publishes `useSessions`, `useSessionStatus`, `useSessionRetainInfo`, `useSession`, `sessionId`, and `useProjection`. `SessionProvider` inherits an outer binding or binds an explicit `SessionReference`, so concurrent subtrees can target different Sessions. Domain adapters add further standard sources without putting React hooks on the model objects.
 
 `ui-conversation` binds once to each `SessionBinding.eventSource`. Its event registry correlates durable Session events and Client-only `assistant/live-chunk` updates into stable business Contexts, and its view registry materializes target snapshots. Chat Assistant, Trajectory Assistant, and Turn Tail interpret both live chunks and the compact streams embedded in durable settlements, so reconnect and paged history reproduce the same Assistant state without durable token rows. `ui-chat` and `ui-trajectory` register separate Definitions and builders: they may interpret the same event family, but they do not import or share each other's final display model. The shell selects a registered view and passes its snapshot through standard hooks and Slots. [Conversation](conversation.md) defines Context identity, replay, Location data, target builders, and keyed renderers.
@@ -64,7 +68,8 @@ This pairing is not a second source of business truth. Host controllers decide d
 | Path | Sequence |
 |---|---|
 | durable Session display | Host Session log → packed Remote `follow`/`page` history → Client `SessionEventLikeEntry` window → Conversation Contexts → target snapshot (`chat`, `trajectory`, or another registered target) → Slot view → React |
-| transient Session control | Host control baseline → Remote snapshot stream → `SessionManager` queue/job/projection stores → Session and list snapshots → standard hooks → components |
+| transient Session control | Host control baseline → Remote snapshot stream → `SessionManager` projection stores → Session and list snapshots → standard hooks → components |
+| Background jobs | Host job registry → `job.list` / `job.follow` → [`ClientJobs`](../../packages/api/job-controller/README.md) roster and output views → job list and panels |
 | Workspace state | Host Workspace baseline and increments → `ClientWorkspaceModel` → `ctx.workspaces.list` → `useWorkspaces` → sidebar, hero, and navigation entries |
 | scoped interaction | Host Cordis waterfall → API Remotes `$events` → `ctx.remote.$on()` on the Session Context → owning UI package → result or `next()` |
 | user command | component callback → registration inject face or Slot owner → `ctx.sessions`, `ctx.workspaces`, or generated scoped Remote → Host Controller → authoritative update → stream or event projection back to the Client |