dsh-plugin-guide 0.3.41 → 0.4.0

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

@@ -1,19 +0,0 @@
-# Bilingual-pair consistency record for translation.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/translation.md
-/text-translation:
-  en: fe10b0616f7bc164
-  zh: 84a392a62efdaab9
-/text-translation/requests-and-results:
-  en: 485abf6107c73e68
-  zh: 78a274d488274035
-/text-translation/failures-and-data-handling:
-  en: 436e55e924e3ad1e
-  zh: c8548fda1e86b078
-/text-translation/persistent-translations:
-  en: 40d175fbe66fd4cd
-  zh: bff18511a8d386e9
-/text-translation/reasoning-display:
-  en: aaf7d361b682fe4a
-  zh: 485e89bdb063665e

package/references/official-docs/docs/subsystems/translation.md

@@ -1,103 +0,0 @@
-# Text translation
-
-English | [中文](translation.zh.md)
-
-The experimental [translator](../../packages/experimental/translator/README.md) translates text through anonymous browser endpoints or explicitly selected paid native Flash routes. Consumers own display, scheduling, and Session activation; Session-bound requests retain reusable results through an active Session writer.
-
-## Requests and results
-
-`TranslationProvider` selects `bing`, `google`, `deepseek-account` or `deepseek-official`. `TranslationRequest` supplies `text`, `targetLanguage`, and optional `sourceLanguage`, `provider` and branded `sessionId`. `resolve()` captures explicit routing in `TranslationSpec`: the configured provider defaults to Bing and omitted source language uses automatic detection. Common Chinese locale tags map to the selected provider's language codes. `translate()` returns plain text from the resolved provider.
-
-The service exposes its configured `maxTextChars`, measured in UTF-16 code units. Consumers split longer inputs before requesting translation. Each call bounds the response bytes and includes the response-body read in its deadline. Caller cancellation and service disposal abort accepted requests; disposal waits for them to settle.
-
-## Failures and data handling
-
-`TranslationError` carries a `TranslationErrorCode` distinguishing text limits, HTTP failures, invalid responses, response limits, owned deadlines, and request failures. `TRANSLATION_SESSION_REQUIRED` rejects a missing persistence backend or Session; `TRANSLATION_SESSION_INACTIVE` rejects an uncached inactive Session before provider dispatch; `TRANSLATION_STORAGE_ERROR` rejects invalid saved records or failed durability. Provider diagnostics omit submitted text and response bodies. Failed calls do not select another provider. Responses are validated as external JSON and redirects are rejected.
-
-`TRANSLATION_UNAVAILABLE` rejects a missing active built-in owner or registered route, unconfigured credentials, absent exact `deepseek-flash` catalog membership, an owner, model-configuration (Official `models` or Account `modelOverrides`), or Official credential-reference change before dispatch, provider withdrawal, or a prepared call whose reasoning effort is not `off`. A native `finish` with reason `error` maps to `TRANSLATION_REQUEST_FAILED`; a missing or other non-`stop` finish maps to `TRANSLATION_INVALID_RESPONSE`.
-
-Google receives source text in a form POST body; Bing receives it in a JSON POST body. Both are remote services. Their anonymous endpoints provide no supported developer availability or quota guarantee. Regional connectivity must be verified on the user's network.
-
-## Persistent translations
-
-Session-bound calls use `plugin:translator/request` and `plugin:translator/result` for every provider. Requests retain exact source, language tags, selected provider and recipe identity; a successful result references its request sequence. Optional request metadata holds provider-specific details without changing these record types. The translator checkpoints requests before external dispatch and completed results before returning them. Read-only cache lookup precedes provider work and needs no live Session; failures and incomplete attempts do not supply reusable text. New records use the active Session's existing writer. The translator opens no write handle and does not activate a Session. Translation records preserve the original events and model input. Anonymous calls without a Session stay stateless; paid routes require a Session. Experimental record retention across future format migrations is best-effort.
-
-Paid cache misses require an active built-in Account or Official owner, configured credentials and exact `deepseek-flash` catalog membership; names and version labels are irrelevant, and pi-ai is excluded. Each miss prepares a separate text-only query with thinking off. Its exact config, system and unique user fragment occupy optional `metadata.modelRequest` in the same request record. Saved results are read before this admission, so missing credentials do not invalidate existing translations. Native request extensions receive no main Session identity and cannot upload its full log.
-
-## Reasoning display
-
-The [optional bundle](../../packages/experimental/cot-translation-bundle/README.md) composes the translator with the [GUI consumer](../../packages/experimental/client-ui-cot-translation/README.md). Its `cotTranslation` Remote serves authenticated browser calls. When a Session is inactive and has no saved result, the Host joins normal Session controller activation and retries once. Activation retains normal preset hooks, resume markers, and interrupted-turn repair; cancellation stops the caller's wait and prevents a later translation call without cancelling shared activation. Bundle settings select a translation service and target language; `auto` follows the active interface language.
-
-`CotTranslationPreferences` contains the accepted provider and target language. `CotTranslationSnapshot` pairs these preferences with the translator's current `maxTextChars` and eligible provider IDs. The browser reads this Host snapshot before registering translation controls, including when local settings storage is unavailable. Accepted settings updates and reconnects refresh both values; a changed request limit cancels and splits the expanded text again.
-
-The GUI registers in the session-scoped `conversation.chat.reasoning.body` single Slot, replacing Chat's default entry. Both entries reuse the official `conversation.chat.reasoning.content` Factory; the translation wrapper selects display text, owns its toolbar and view state, and supplies its localized labels without duplicating Markdown rendering. While enabled, the GUI translates completed paragraphs and request-sized prefixes of long streaming paragraphs only after expansion, and restores completed results from the current Session. Its local cache only optimizes that disclosure. The unfinished tail remains original. Original remains accessible. Closing the disclosure, switching provider or language, and unloading cancel outstanding calls and exclude late results. Provider failure preserves the original and requires an explicit retry; translated text never replaces original Session events or model input.
-
-<!-- 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="ctxcottranslation--cottranslationcontroller"></a>
-
-### `ctx.cotTranslation` — `CotTranslationController`
-
-Optional reasoning translation delegates Session-bound storage to the translator.
-
-```ts cordis-catalog
-/**
- * Read accepted translation preferences and the current request limit without sending text.
- * @param signal - browser query cancellation or Remote contribution withdrawal.
- * @returns authoritative preferences, eligible routes, and maximum UTF-16 text length per request.
- */
-@Remote async limits(signal: AbortSignal): Promise<CotTranslationSnapshot>
-
-/**
- * Translate one displayed fragment through the reader's selected provider.
- * @param request - original text and Session identity supplied by the Client; provider and explicit
- * target language match accepted preferences, while auto uses the browser locale.
- * @param signal - browser cancellation or Remote contribution withdrawal.
- * @returns translated text; an uncached inactive Session joins ordinary GUI activation before retry.
- * Failures omit the source and provider response. Cancellation stops this caller's wait, not shared activation.
- */
-@Remote async translate(request: TranslationRequest, signal: AbortSignal): Promise<string>
-```
-
-Source: [`packages/experimental/client-ui-cot-translation/src/index.ts`](../../packages/experimental/client-ui-cot-translation/src/index.ts)
-
-<a id="ctxtranslator--translator"></a>
-
-### `ctx.translator` — `Translator`
-
-One Host service with explicit routing, cancellation and quiescent unload.
-
-```ts cordis-catalog
-/**
- * Inspect eligible native routes without inference; saved results remain readable for unavailable routes.
- * @param signal - optional caller cancellation, combined with service disposal.
- * @returns anonymous choices followed by eligible explicitly selected paid routes.
- */
-async availableProviders(signal?: AbortSignal): Promise<readonly TranslationProvider[]>
-
-/**
- * Resolve provider and source-language defaults without sending text.
- * @param request - consumer text, destination and optional routing choices.
- * @returns a complete specification; exceeding `maxTextChars` throws `TRANSLATION_TEXT_LIMIT`.
- */
-resolve(request: TranslationRequest): TranslationSpec
-
-/**
- * Translate one resolved specification; the selected provider receives its text.
- * @param spec - complete routing and language choices from `resolve()`.
- * @param signal - optional caller cancellation, combined with service disposal.
- * @returns translated plain text, durably retained before return when a Session is supplied.
- * An uncached supplied Session must be active; otherwise rejects with `TRANSLATION_SESSION_INACTIVE` before dispatch.
- * Rejects provider/storage/limit failures and preserves cancellation reasons.
- */
-async translate(spec: TranslationSpec, signal?: AbortSignal): Promise<string>
-```
-
-Source: [`packages/experimental/translator/src/index.ts`](../../packages/experimental/translator/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/translation.zh.md

@@ -1,103 +0,0 @@
-# 文本翻译
-
-[English](translation.md) | 中文
-
-实验性 [translator](../../packages/experimental/translator/README.zh.md) 通过免登录浏览器端点或显式选择的付费原生 Flash 路由翻译文本。消费者负责展示、调度及 Session 激活；绑定 Session 的请求通过已激活 Session 的写入器保留可复用结果。
-
-## 请求与结果
-
-`TranslationProvider` 选择 `bing`、`google`、`deepseek-account` 或 `deepseek-official`。`TranslationRequest` 提供 `text`、`targetLanguage` 及可选的 `sourceLanguage`、`provider` 与带品牌类型的 `sessionId`。`resolve()` 将显式路由写入 `TranslationSpec`：配置的默认 Provider 为 Bing，省略源语言时自动检测。常见中文 locale 标签映射为所选 Provider 的语言代码。`translate()` 返回所选 Provider 翻译后的纯文本。
-
-服务公开配置的 `maxTextChars`，单位为 UTF-16 code unit。消费者先拆分超长输入，再请求翻译。每次调用限制响应字节数，并将响应体读取计入超时。调用者取消和服务卸载都会中止已接收的请求；卸载等待这些请求完成。
-
-## 失败与数据处理
-
-`TranslationError` 的 `TranslationErrorCode` 区分文本超限、HTTP 失败、无效响应、响应超限、服务自身超时与请求失败。`TRANSLATION_SESSION_REQUIRED` 拒绝缺失的持久化后端或 Session，`TRANSLATION_SESSION_INACTIVE` 在调用 Provider 前拒绝未激活且缓存未命中的 Session，`TRANSLATION_STORAGE_ERROR` 拒绝无效保存记录或持久化失败。Provider 错误信息省略提交的文本与响应体。失败时不选择其他 Provider。响应作为外部 JSON 校验，重定向被拒绝。
-
-`TRANSLATION_UNAVAILABLE` 拒绝缺失的活跃内置所有者或已注册路由、未配置的凭据、目录中不存在精确的 `deepseek-flash`、派发前所有者、模型配置（官方路由的 `models` 或账号路由的 `modelOverrides`）或官方凭据引用变化、提供方卸载，以及准备后的调用推理强度不是 `off` 的情况。原生 `finish` 的原因为 `error` 时映射为 `TRANSLATION_REQUEST_FAILED`；缺失 finish 或其他非 `stop` 原因映射为 `TRANSLATION_INVALID_RESPONSE`。
-
-Google 在 form POST 请求体中接收原文，Bing 在 JSON POST 请求体中接收原文。两者都是远端服务。免登录端点不保证开发者 API 的可用性或免费额度。区域连通性须在用户网络上验证。
-
-## 持久化翻译
-
-绑定 Session 的调用对所有 Provider 使用 `plugin:translator/request` 与 `plugin:translator/result`。请求保留精确原文、语言标签、所选 Provider 和翻译规则标识，成功结果引用请求序号。可选请求 metadata 保存 Provider 专有细节，不改变记录类型。translator 在外部派发前完成请求检查点，在返回前完成结果检查点。只读缓存查找先于 Provider 调用，且不要求 Session 已激活；失败或未完成尝试不提供可复用译文。新记录使用已激活 Session 的现有写入器。translator 不打开写句柄，也不激活 Session。翻译记录保留原始事件与模型输入。不指定 Session 的匿名调用保持无状态；付费路由要求 Session。未来格式迁移对实验性记录的保留为尽力而为。
-
-付费缓存未命中时要求内置账号或官方 API 所有者处于活动状态、凭据已配置，且目录包含 ID 恰好为 `deepseek-flash` 的模型；名称和版本标签不参与匹配，pi-ai 路由被排除。每次未命中准备一次关闭思考的独立纯文本查询。精确配置、系统指令和唯一原文片段保存在同一请求记录的可选 `metadata.modelRequest` 中。读取保存结果先于此项准入，因此凭据缺失不会使既有译文失效。原生请求扩展不接收主 Session 身份，不能上传其完整日志。
-
-## 思考内容展示
-
-[可选 Bundle](../../packages/experimental/cot-translation-bundle/README.zh.md) 将 translator 与 [GUI 消费者](../../packages/experimental/client-ui-cot-translation/README.zh.md) 组合。其 `cotTranslation` Remote 为经过身份验证的浏览器调用提供服务。Session 未激活且没有已保存结果时，Host 等待 Session controller 的正常激活，再重试一次。激活保留正常的 preset 钩子、恢复标记和中断轮次修复；取消会结束调用者的等待并阻止随后调用翻译，不取消共享激活。Bundle 设置选择翻译服务及目标语言；`auto` 跟随当前界面语言。
-
-`CotTranslationPreferences` 包含已接受的翻译服务和目标语言。`CotTranslationSnapshot` 将这些偏好与 translator 当前的 `maxTextChars` 及可用服务 ID 一起返回。浏览器在注册翻译控件前读取此 Host 快照，本地设置存储不可用时也如此。接受的设置更新及重新连接会刷新这两项值；请求长度限制变化时，展开内容的请求被取消并重新分片。
-
-GUI 向 Session 作用域的 `conversation.chat.reasoning.body` single Slot 注册，替换 Chat 的默认条目。两个条目均复用官方 `conversation.chat.reasoning.content` Factory；翻译包装选择显示文本，自行维护工具栏和视图状态，传入自己的本地化 labels，不重复实现 Markdown 渲染。启用后，GUI 只在展开后翻译完整段落和流式长段落中达到请求长度的前缀，并从当前 Session 恢复已完成结果；本地缓存只优化当前展开区域。未完成的末尾片段保留原文。原文始终可访问。关闭展开内容、切换 Provider 或语言、卸载插件都会取消未完成调用并忽略迟到的结果。Provider 失败时保留原文，必须显式重试；译文从不替换原始 Session 事件或模型输入。
-
-<!-- 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="ctxcottranslation--cottranslationcontroller"></a>
-
-### `ctx.cotTranslation` — `CotTranslationController`
-
-Optional reasoning translation delegates Session-bound storage to the translator.
-
-```ts cordis-catalog
-/**
- * Read accepted translation preferences and the current request limit without sending text.
- * @param signal - browser query cancellation or Remote contribution withdrawal.
- * @returns authoritative preferences, eligible routes, and maximum UTF-16 text length per request.
- */
-@Remote async limits(signal: AbortSignal): Promise<CotTranslationSnapshot>
-
-/**
- * Translate one displayed fragment through the reader's selected provider.
- * @param request - original text and Session identity supplied by the Client; provider and explicit
- * target language match accepted preferences, while auto uses the browser locale.
- * @param signal - browser cancellation or Remote contribution withdrawal.
- * @returns translated text; an uncached inactive Session joins ordinary GUI activation before retry.
- * Failures omit the source and provider response. Cancellation stops this caller's wait, not shared activation.
- */
-@Remote async translate(request: TranslationRequest, signal: AbortSignal): Promise<string>
-```
-
-Source: [`packages/experimental/client-ui-cot-translation/src/index.ts`](../../packages/experimental/client-ui-cot-translation/src/index.ts)
-
-<a id="ctxtranslator--translator"></a>
-
-### `ctx.translator` — `Translator`
-
-One Host service with explicit routing, cancellation and quiescent unload.
-
-```ts cordis-catalog
-/**
- * Inspect eligible native routes without inference; saved results remain readable for unavailable routes.
- * @param signal - optional caller cancellation, combined with service disposal.
- * @returns anonymous choices followed by eligible explicitly selected paid routes.
- */
-async availableProviders(signal?: AbortSignal): Promise<readonly TranslationProvider[]>
-
-/**
- * Resolve provider and source-language defaults without sending text.
- * @param request - consumer text, destination and optional routing choices.
- * @returns a complete specification; exceeding `maxTextChars` throws `TRANSLATION_TEXT_LIMIT`.
- */
-resolve(request: TranslationRequest): TranslationSpec
-
-/**
- * Translate one resolved specification; the selected provider receives its text.
- * @param spec - complete routing and language choices from `resolve()`.
- * @param signal - optional caller cancellation, combined with service disposal.
- * @returns translated plain text, durably retained before return when a Session is supplied.
- * An uncached supplied Session must be active; otherwise rejects with `TRANSLATION_SESSION_INACTIVE` before dispatch.
- * Rejects provider/storage/limit failures and preserves cancellation reasons.
- */
-async translate(spec: TranslationSpec, signal?: AbortSignal): Promise<string>
-```
-
-Source: [`packages/experimental/translator/src/index.ts`](../../packages/experimental/translator/src/index.ts)
-<!-- END GENERATED cordis-surface -->

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

@@ -1,25 +0,0 @@
-# Bilingual-pair consistency record for typert.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/typert.md
-/typert-remote-calls:
-  en: ccc2694e359c2333
-  zh: cd68bf5e74e2d685
-/typert-remote-calls/lookup-and-context-declarations:
-  en: 8725fa62f36364d7
-  zh: 0f2ff4bdf13ff55b
-/typert-remote-calls/invocation-descriptors:
-  en: 21e88d68154c2c92
-  zh: 8c9e05c65ef0f34d
-/typert-remote-calls/remote-access-resources:
-  en: fa95f70437c07395
-  zh: d4870b678b569a89
-/typert-remote-calls/typert-registry:
-  en: 5827ef50011811c9
-  zh: 21a9e7b368ba211a
-/typert-remote-calls/host-gateway:
-  en: 58b923de12e48f18
-  zh: d3c2372d8becf65e
-/typert-remote-calls/consumer-remote:
-  en: 324386c600a5fdf5
-  zh: 7963501eb663e228