dsh-plugin-guide 0.3.41 → 0.4.0

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

@@ -1,447 +0,0 @@
-# Profile 管理
-
-[English](boot.md) | 中文
-
-[boot 包组](../../packages/boot/README.zh.md)负责 launcher 提供的 profile 访问与插件管理器。[插件管理器](../../packages/boot/plugin-manager/README.zh.md)文档说明持久化、重载与包操作行为。
-
-## 管理记录
-
-`PluginEntryId` 标识一个 Loader 条目；调用方从 `listPlugins` 获取，不自行拼接 patch id。
-
-`PluginInfo` 包含模块标识、实际启停状态、fiber 阶段和可选的展示 `meta`，以及唯一的 `patchId` 或 `readOnlyReason`。
-
-`BundleInfo.official` 标识项目维护的随附可选组合包和按需目录项，独立于安装状态。`availability` 表示可读取的安装随附包、profile 包或 `missing`；按需目录项不计入未声明的传递依赖副本。`installed` 记录 profile 的依赖声明。按需条目的 `installTarget` 包含 Host 生成的精确 spec 和版本。`BundleInfo` 还包含包名、可选的安装版本、组合层选择状态、删除可用性、可选的解析错误；由 profile 自身依赖提供、且安装不提供的组合包还带有 `source`，即该依赖在 `pnpm add` 中可用的 spec。它的可选 `meta` 与各行的 `BundleRowInfo.meta` 包含展示文本或元信息诊断；Client 在渲染时选择语言。
-
-`InstallBundleOptions.saveExact` 向共享包安装器传入 `--save-exact`。`InstallBundleOptions.enabled` 默认为 true，false 表示安装但不选择组合包层。`approvedBuilds` 在安装前向指定的待审批包名授予持久脚本权限。`registry` 指定首先询问的注册表；缺省为配置的那个。
-
-`PluginRegistries` 携带配置的第一个注册表（`null` 即 pnpm 自身配置指定的那个）、随后依次询问的备选注册表，以及 `resolved`——pnpm 自身配置指向的 URL，未读到时为 `null`。`InspectOptions.registry` 指定一次查询首先询问的注册表。
-
-`ChangeResult.changed` 报告磁盘修改，独立于 `application`：`applied`、`restart-required`、`overridden` 或 `failed`。可选的 `error` 包含可本地化的错误码和外部诊断。`packageResult` 记录 pnpm 退出码、有界输出、截断标志及完整诊断日志路径；当管理器终止了一个停止打印的运行，还记录 `timedOut`。被终止的运行不论信号留下什么退出状态都归类为 `timeout`，因此安装与删除都报告失败而非成功，也不会再询问下一个注册表。`pendingBuilds` 列出整个 profile 尚未决定的包；`approvedBuilds` 记录本次操作授予权限的包名；`registries` 按顺序列出一次安装问过的注册表；`bundle` 与 `version` 给出完成的安装新增的包及其清单版本；`failedAt` 说明最后一次失败的运行连不上的是所问的注册表，还是 git 或 tarball spec 自身拉取的主机。
-
-## 市场记录
-
-[Plugin Market](../../packages/boot/plugin-market/README.zh.md) 读取第 1 版索引格式，校验由 [`dsh-plugin-market-index`](../../packages/util/plugin-market-index/README.zh.md) 完成。
-
-`MarketIndexSummary` 携带一个已配置的索引 URL，以及最近一次成功读取得到的 `title` 和 `description`；最近一次读取失败时，还携带其 `error`。
-
-`MarketQuery` 选择索引的一页：模糊匹配的 `text`、一个 `category`、必须全部具备的 `labels`、一个 `MarketSort`、`offset`、不超过 100 的 `limit`、表示重新获取而不使用缓存文档的 `refresh`，以及用于继续读取同一文档后续页的 `fetchedAt`。`MarketSearchResult` 携带索引 URL、`title`、可选的 `description`、市场 `metadata`、该文档的 `fetchedAt`、本页的 `entries`、匹配总数 `total` 和 `nextOffset`。每个 `MarketListingEntry` 额外携带 `defaultVersion`，即默认安装的版本，以及 `installation`，即该包名在当前 profile 中的状态；其 `versions` 中的每个版本额外携带 `install`，即交给 `installBundle` 的精确 spec 和可选的首选 registry，以及 `compatibility`，即包含版本豁免在内的 `engines.dsh` 评估结果。
-
-## Profile 重新组合
-
-<a id="profile-reconciliation"></a>
-
-```ts type-equiv
-/** Outcome of {@link Hmr.reconcileProfile}. */
-interface ProfileReconciliation {
-  /** Diagnostics for Loader entries left inactive. */
-  warnings: string[]
-  /** Loaded modules whose files changed on disk and whose previous code keeps running until a restart. */
-  pending: PendingModule[]
-  /**
-   * Why every change waits for a restart: `module-comparison` when module caches cannot be inspected or their files
-   * compared, even when no URLs are known; `package-moved` when the runtime resolution cannot publish a moved package.
-   */
-  restartReason?: 'module-comparison' | 'package-moved'
-}
-```
-
-```ts type-equiv
-/** A changed module that loads only after a restart. */
-interface PendingModule {
-  url: string
-  /**
-   * `host-module`: the process entry point's static graph imports it. `unmanaged-plugin`: it is imported by a plugin
-   * that runs outside a traversable Loader entry. `module-comparison`: loaded modules could not be compared with disk.
-   */
-  reason: 'host-module' | 'unmanaged-plugin' | 'module-comparison'
-}
-```
-
-<!-- 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="ctxconfigeditor--configeditor"></a>
-
-### `ctx.configEditor` — `ConfigEditor`
-
-Persist complete raw configs and apply them through the normal Loader path.
-
-```ts cordis-catalog
-/** Addressable profile rows; nested Includes have independent configuration ownership.
- * @returns Active entries with unique profile patch ids.
- */
-entries(): Entry[]
-
-/** Read inherited and explicit profile values for the active entries.
- * @returns Detached layer values alongside their Loader entries.
- */
-configuration(): Array<{ entry: Entry; inherited: Record<string, unknown>; override: Record<string, unknown> }>
-
-/** Validate, persist, and reconcile a plugin's next config; ordinary fields keep normal lifecycle rules.
- * @param entry Current Loader entry, also used to detect replacement during the write.
- * @param change Derive a raw config from the current entry and its inherited layer.
- * @returns Fulfillment after Loader reconciliation completes.
- */
-async edit( entry: Entry, change: (current: Record<string, unknown>, inherited: Record<string, unknown>) => Record<string, unknown>, ): Promise<void>
-```
-
-Source: [`packages/boot/config-editor/src/index.ts`](../../packages/boot/config-editor/src/index.ts)
-
-<a id="ctxhmr--hmr"></a>
-
-### `ctx.hmr` — `Hmr`
-
-Hot reload service with Cordis-compatible module configuration and events.
-
-```ts cordis-catalog
-/** Serialize a caller-owned mutation with all automatic reload paths.
- * @param operation Work that must not overlap module or configuration replacement.
- * @returns The operation result after its asynchronous work completes.
- */
-runExclusive<T>(operation: () => Promise<T>): Promise<T>
-
-/** Watch a configuration path through the same queue as module replacement.
- * @param filename Absolute path, which may not exist yet.
- * @param refresh Rebuilds configuration from its current files and awaits Loader completion.
- * @returns Disposer closing this registration and waiting for its pending refresh.
- */
-async watchConfig(filename: string, refresh: () => Promise<void>): Promise<() => Promise<void>>
-
-/** Read direct module dependency URLs from the active Node loader.
- * @param url Module URL.
- * @returns Linked module URLs, or an empty list for an uncached module.
- */
-async getLinked(url: string): Promise<string[]>
-
-/**
- * Recompose the profile from its manifest and patch files, replacing running plugins whose loaded files below the
- * profile directory or its linked package targets changed on disk, and publishing its runtime resolution. Changed
- * modules are evicted and the Loader entries running them stop; app-boot's {@link recomposeProfile} then publishes the
- * resolution, applies the generation, starts the stopped entries with the current files and configuration,
- * imports entries whose import failed again, and judges activation. Afterwards the modules below the mappings the
- * recomposition dropped are evicted, so a removed or deselected package is imported afresh when it returns. Callers run
- * inside {@link runExclusive}.
- * @param requiredIds Entry ids whose inactive state is reported as a failure even when it predates this call.
- * @returns Inactive-entry diagnostics, the changed modules that load after a restart, and a profile-wide restart reason.
- * @throws The patch read, publication, preparation, apply, or activation failure of the recomposition, including a
- * replacement plugin that fails to load or start, whose previous code no longer runs.
- */
-async reconcileProfile(requiredIds: readonly string[] = []): Promise<ProfileReconciliation>
-```
-
-Source: [`packages/boot/hmr/src/index.ts`](../../packages/boot/hmr/src/index.ts)
-
-<a id="ctxpluginmanager--pluginmanager"></a>
-
-### `ctx.pluginManager` — `PluginManager`
-
-Manage profile files and apply their declared reload lifecycle.
-
-```ts cordis-catalog
-/** Read exact plugin-version exemptions saved in this profile.
- * @returns Accepted package-name@version keys with the runtime versions they may run on, and any
- * record or file problem the reader rejected, which the caller reports instead of failing.
- */
-@Remote listVersionExemptions(): { exemptions: Record<string, string[]>; warnings: string[] }
-
-/** Grant or revoke one exact plugin/runtime exemption and reevaluate live plugins.
- * @param packageVersion Exact manifest package name followed by @ and its version; never an installation spec or alias.
- * @param runtimeVersion Exact current DSH version for grants; revocation may name a previous runtime.
- * @param enabled Whether to grant rather than revoke the exemption.
- * @param acceptRisk Required true for grants after the user accepts possible crashes and data loss.
- * @returns Saved and runtime outcomes. Startup-only profiles require restart.
- */
-@Remote setVersionExemption(packageVersion: string, runtimeVersion: string, enabled: boolean, acceptRisk?: boolean): Promise<ChangeResult>
-
-/** Read current plugins, including why a row cannot be changed through the profile patch.
- * @returns Current runtime entries with persistent patch targets.
- */
-@Remote async listPlugins(): Promise<PluginInfo[]>
-
-/** Read installed, installation-provided, and offline Official catalog bundles, plus selected non-bundle names.
- * A dependency without a bundle patch is listed, as a `not-bundle` problem, only while it is selected.
- * @returns Package versions, manifest descriptions, the installable spec of profile dependencies, rows, optional
- * display metadata, activation selections, whether the installation offers the bundle, and removal availability.
- */
-@Remote listBundles(): Promise<BundleInfo[]>
-
-/** Read the registries this manager asks: the configured first one, its fallbacks in order, and what pnpm's own configuration names.
- * @returns The registries in pnpm's comparison form; null is the one pnpm's own configuration names, `resolved` as pnpm reads it now.
- */
-@Remote async registries(): Promise<PluginRegistries>
-
-/** Read what a spec names before installing it.
- * @param spec One package spec: a registry name, an absolute path, a git address, or a tarball.
- * @param options The registry asked first.
- * @param signal Ends a registry lookup early.
- * @returns The package the spec names, or why it is refused.
- */
-@Remote async inspect(spec: string, options?: InspectOptions, signal?: AbortSignal): Promise<PluginSpecInspection>
-
-/** Persist a plugin entry's desired enablement and apply it on live profiles.
- * @param id Loader entry identity returned by listPlugins.
- * @param enabled Whether the plugin should run.
- * @returns Saved and runtime outcomes, including higher-priority overrides.
- */
-@Remote setPluginEnabled(id: PluginEntryId, enabled: boolean): Promise<ChangeResult>
-
-/** Select or remove a bundle layer while retaining installed dependencies.
- * @param name Bundle package name.
- * @param enabled Whether the bundle contributes its patch layer.
- * @returns Persisted and runtime outcomes.
- */
-@Remote setBundleEnabled(name: string, enabled: boolean): Promise<ChangeResult>
-
-/**
- * Install a package using the same pnpm implementation as dsh plugin. GitHub
- * repositories get a connection check bounded by githubConnectionTimeoutMs before pnpm starts;
- * only network failures or timeouts stop installation, while pnpm owns authentication and transport fallback. A run
- * that fails, is cancelled, or adds a package without a bundle patch restores
- * `package.json` and `pnpm-lock.yaml` as they were; downloaded files can stay.
- * @param spec One package spec, including local paths relative to the invocation directory.
- * @param options Whether to activate the installed bundle (defaults to true), the request id a cancellation names,
- * the pending build scripts to allow, whether to save an exact dependency, and the registry asked first.
- * @returns Package-manager diagnostics, the registries asked, and the observed activation outcome.
- */
-@Remote installBundle(spec: string, options?: InstallBundleOptions): Promise<ChangeResult>
-
-/** Recover the result of an active installation without cancelling it.
- * @param requestId The id supplied when installation started.
- * @returns The installation's outcome after it settles, or null if no active request has that id.
- * Completed results are not retained; null establishes neither success nor cancellation.
- */
-@Remote async waitForInstall(requestId: PluginInstallRequestId): Promise<ChangeResult | null>
-
-/** Stop an installation this manager owns and wait until its files are back.
- * @param requestId The id the installation was started with.
- * @returns `cancelled` once the Git check or pnpm exited and the files are restored, `too-late` once the bundle is being
- * applied, `not-running` for any other id.
- */
-@Remote async cancelInstall(requestId: PluginInstallRequestId): Promise<PluginInstallCancellation>
-
-/** Unload and remove a profile-owned bundle dependency through dsh plugin's pnpm path; a selected name no
- * dependency holds is only deselected.
- * @param name Installed dependency or selected bundle name.
- * @returns Removal diagnostics and the remaining profile state.
- */
-@Remote removeBundle(name: string): Promise<ChangeResult>
-```
-
-Source: [`packages/boot/plugin-manager/src/index.ts`](../../packages/boot/plugin-manager/src/index.ts)
-
-<a id="ctxpluginmarket--pluginmarket"></a>
-
-### `ctx.pluginMarket` — `PluginMarket`
-
-Fetches, validates, and caches configured market indexes; annotates entries with the profile's installation facts.
-
-```ts cordis-catalog
-/**
- * List the configured index sources without fetching them.
- * @returns every source in order, with the title of its last successful read and, when the last read failed, its error.
- */
-@Remote listIndexes(): MarketIndexSummary[]
-
-/**
- * Replace the configured index sources through Settings, without remounting this service.
- * `plugin-market/changed` announces the committed list. A URL already configured is kept as written, so a client can
- * add or remove sources beside one that `listIndexes` reports as unusable.
- * @param urls - index URLs in display order.
- * @throws {RemoteError} `plugin-market/invalid-index-url` for an invalid new URL or a repeated URL;
- * `plugin-market/settings-unavailable` without Settings or a profile entry.
- */
-@Remote async setIndexes(urls: string[]): Promise<void>
-
-/**
- * Return one page of the plugins of a configured index that match a query. Concurrent reads of a URL share one
- * fetch; a successful document is reused for `cacheTtlMs` unless `refresh` is set. Matching and ordering read only
- * the document; installation status and compatibility are computed for the returned page on every call.
- * @param url - a configured index URL.
- * @param query - text, filters, order, page, and whether to bypass the cached document.
- * @returns the index header, the page's plugins with each plugin's default version and installation status and each
- *   version's compatibility and install arguments, the number of matches, and the next page's offset.
- * @throws {RemoteError} `plugin-market/invalid-query`, `plugin-market/unknown-index`, `plugin-market/invalid-index-url`,
- *   `plugin-market/fetch-failed`, or `plugin-market/invalid-index`.
- */
-@Remote async search(url: string, query: MarketQuery): Promise<MarketSearchResult>
-
-/**
- * Read one plugin of a configured index, using the cached document as `search` does.
- * @param url - a configured index URL.
- * @param name - the plugin's package name.
- * @returns the plugin with its default version, installation status, and annotated versions; undefined when the
- *   index does not list it.
- * @throws {RemoteError} `plugin-market/unknown-index`, `plugin-market/invalid-index-url`, `plugin-market/fetch-failed`,
- *   or `plugin-market/invalid-index`.
- */
-async entry(url: string, name: string): Promise<MarketListingEntry | undefined>
-```
-
-Source: [`packages/boot/plugin-market/src/index.ts`](../../packages/boot/plugin-market/src/index.ts)
-
-<a id="ctxpluginregistryprobe--pluginregistryprobe"></a>
-
-### `ctx.pluginRegistryProbe` — `PluginRegistryProbe`
-
-Compares public registry responses on the Host; the Client owns the initial selection.
-
-```ts cordis-catalog
-/**
- * Race npm and npmmirror HTTPS ping responses through the Host's fetch proxy.
- * Concurrent readers share a probe; a winner cancels and awaits the other request.
- * @returns the first registry with a successful response, or null when disabled or neither responds successfully; results are cached.
- * @throws rejects when the service has been unloaded.
- */
-@Remote async fastest(): Promise<string | null>
-```
-
-Source: [`packages/client/ui-plugin-manager/src/index.ts`](../../packages/client/ui-plugin-manager/src/index.ts)
-
-<a id="ctxprofilecontext--profilecontext"></a>
-
-### `ctx.profileContext` — `ProfileContext`
-
-Current profile facts; scheduling and mutation belong to their callers.
-
-Source: [`packages/boot/app-boot/src/profile-context.ts`](../../packages/boot/app-boot/src/profile-context.ts)
-
-<a id="app-boot-events"></a>
-
-### `app-boot/*` events
-
-<a id="app-bootconfig-reload--emit"></a>
-
-#### `app-boot/config-reload` — emit
-
-Profile patches were reconciled into the running Loader tree: every entry update settled and no new inactive entry was introduced. Carries no diff; listeners re-read Loader entries.
-
-```ts cordis-catalog
-/**
- * Profile patches were reconciled into the running Loader tree: every entry update settled and no new
- * inactive entry was introduced. Carries no diff; listeners re-read Loader entries.
- * @mode emit
- */
-'app-boot/config-reload'(): void
-```
-
-Source: [`packages/boot/app-boot/src/index.ts`](../../packages/boot/app-boot/src/index.ts)
-
-<a id="hmr-events"></a>
-
-### `hmr/*` events
-
-<a id="hmrchange--emit"></a>
-
-#### `hmr/change` — emit
-
-A watched file has no module or configuration handler.
-
-```ts cordis-catalog
-/** A watched file has no module or configuration handler.
- * @mode emit
- * @param url Canonical file URL.
- */
-'hmr/change'(url: string): void
-```
-
-Source: [`packages/boot/hmr/src/index.ts`](../../packages/boot/hmr/src/index.ts)
-
-<a id="hmrreload--emit"></a>
-
-#### `hmr/reload` — emit
-
-Module replacements have finished loading.
-
-```ts cordis-catalog
-/** Module replacements have finished loading.
- * @mode emit
- * @param reloads Replaced plugins and their module locations.
- */
-'hmr/reload'(reloads: Map<Plugin, Reload>): void
-```
-
-Source: [`packages/boot/hmr/src/index.ts`](../../packages/boot/hmr/src/index.ts)
-
-<a id="plugin-manager-events"></a>
-
-### `plugin-manager/*` events
-
-<a id="plugin-managerchanged--emit"></a>
-
-#### `plugin-manager/changed` — emit
-
-The profile's plugins, bundles, or composition changed: a manager operation completed. A patch generation applied outside the manager, by HMR's watcher after a CLI or hand edit, announces nothing here.
-
-```ts cordis-catalog
-/**
- * The profile's plugins, bundles, or composition changed: a manager
- * operation completed. A patch generation applied outside the manager,
- * by HMR's watcher after a CLI or hand edit, announces nothing here.
- * @mode emit
- * @param change - what changed.
- */
-'plugin-manager/changed'(change: PluginChange): void
-```
-
-Source: [`packages/boot/plugin-manager/src/types.ts`](../../packages/boot/plugin-manager/src/types.ts)
-
-<a id="plugin-managerinstall-log--emit"></a>
-
-#### `plugin-manager/install-log` — emit
-
-One chunk of a pnpm run's output, streamed as the run produces it.
-
-```ts cordis-catalog
-/**
- * One chunk of a pnpm run's output, streamed as the run produces it.
- * @mode emit
- * @param chunk - the chunk and the run it belongs to.
- */
-'plugin-manager/install-log'(chunk: PluginInstallLogChunk): void
-```
-
-Source: [`packages/boot/plugin-manager/src/types.ts`](../../packages/boot/plugin-manager/src/types.ts)
-
-<a id="plugin-managerinstall-state--emit"></a>
-
-#### `plugin-manager/install-state` — emit
-
-An installation moved between its Host phases. `installing` is announced once per registry the installation asks, with the attempt's registry and position; `cancelling` and `applying` once.
-
-```ts cordis-catalog
-/**
- * An installation moved between its Host phases. `installing` is announced once per registry the
- * installation asks, with the attempt's registry and position; `cancelling` and `applying` once.
- * @mode emit
- * @param progress - the installation's request id and phase, with the attempt while installing.
- */
-'plugin-manager/install-state'(progress: PluginInstallProgress): void
-```
-
-Source: [`packages/boot/plugin-manager/src/types.ts`](../../packages/boot/plugin-manager/src/types.ts)
-
-<a id="plugin-market-events"></a>
-
-### `plugin-market/*` events
-
-<a id="plugin-marketchanged--emit"></a>
-
-#### `plugin-market/changed` — emit
-
-The configured index sources changed.
-
-```ts cordis-catalog
-/**
- * The configured index sources changed.
- * @mode emit
- */
-'plugin-market/changed'(): void
-```
-
-Source: [`packages/boot/plugin-market/src/types.ts`](../../packages/boot/plugin-market/src/types.ts)
-<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/browser-use.i18n.yaml

@@ -1,19 +0,0 @@
-# Bilingual-pair consistency record for browser-use.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/browser-use.md
-/browser-use:
-  en: c4c91e07977a0d7b
-  zh: ae7bf1da6f4019a5
-/browser-use/choose-a-provider:
-  en: 1e8ff2e03064fcff
-  zh: d7164f738e5b4c5c
-/browser-use/session-ownership:
-  en: a6cd1aa7ea518c3f
-  zh: 44d2b40a15f81ce9
-/browser-use/mcp-initialization:
-  en: ac4bcaf872ec5ed8
-  zh: 57d699d1b6e07caf
-/browser-use/tools-and-recorded-results:
-  en: 968055589fb64b35
-  zh: d549a52809ddcf58

package/references/official-docs/docs/subsystems/browser-use.md

@@ -1,67 +0,0 @@
-# Browser use
-
-English | [中文](browser-use.zh.md)
-
-Browser use lets a model inspect and operate web pages through a configured backend. DSH owns the task loop; the provider supplies browser operations and keeps browser state across turns of one live Session.
-
-## Choose a provider
-
-Mount [`dsh-browser-use`](../../packages/browser-use/browser-use/README.md) and one provider in the same composition. The providers are experimental public npm packages and require explicit activation. Their initial browser engine is Chromium.
-
-| Provider | Integration |
-|---|---|
-| [Playwright MCP](../../packages/experimental/browser-use-playwright-mcp/README.md) | Playwright's browser-control MCP tools |
-| [Chrome DevTools MCP](../../packages/experimental/browser-use-chrome-devtools-mcp/README.md) | Chrome DevTools inspection and control through MCP |
-| [Stagehand](../../packages/experimental/browser-use-stagehand-native/README.md) | Native browser operations with AI-assisted actions, observation, and extraction |
-
-The shared service registers only a name and rejects any second provider, including another instance with the same name. It has no common browser-operation methods, browser resources, or model-controlled selector. Provider configuration in a profile or preset selects launch or attachment for that activation.
-
-## Session ownership
-
-A launched browser belongs to the exact live Agent and Session that uses it. Calls across turns reuse that browser. Disposing the Session runtime closes its launched resources; reloading or forking a Session starts fresh browser state. Browser profiles and login state are not restored from the Session log.
-
-An attached browser remains externally owned. The provider reserves it for one Session within that provider instance, preserves its existing browser state, and rejects simultaneous attachment by another Session. Teardown disconnects and leaves the external browser running. Separate DSH processes and other clients remain outside this reservation.
-
-Provider shutdown stops tool admission and waits for owned work and resource cleanup before releasing the shared provider registration. Cancellation cannot undo a browser action already delivered.
-
-## MCP initialization
-
-An MCP provider initializes one client for each live Agent created after the provider loads. The existing serial `agent/created` event awaits connection and discovery before creation or resume completes and queued input runs. The client remains with the Session across turns. Startup failure or cancellation rejects creation or resume and triggers client cleanup.
-
-If an attachment is busy, that activation continues without the browser and does not retry on later turns. After release, a newly created or resumed activation can acquire it. Loading or reloading the provider does not adopt already active Sessions; the [shared runtime](../../packages/experimental/browser-use-runtime/README.md) owns these initialization rules.
-
-## Tools and recorded results
-
-Provider tools use the normal DSH execution pipeline and Session log. The providers own their tool schemas, result rendering, image support, configuration, and upstream limitations; the shared service adds no model-visible content. Stagehand's AI-assisted operations use its explicitly configured native model while DSH retains the task loop. DSH model routing, credential reuse, underlying inference request/response capture, and integration into Session usage accounting are deferred; returned SDK data and metadata remain ordinary logged tool results.
-
-Browser MCP connections also expose [resources and server instructions](mcp.md). Resource calls addressed to a browser server use its Session queue and reject other Sessions; server instructions are assembled only for its owning Session.
-
-The [decision record](../../.agents/notes/implemented/architecture/2026-09-12-browser-use-provider-registration.md) explains the registration-only service and per-Session ownership.
-
-<!-- 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="ctxbrowseruse--browseruseregistry"></a>
-
-### `ctx.browserUse` — `BrowserUseRegistry`
-
-Owns one optional provider registration in the shared browser-use service.
-
-```ts cordis-catalog
-/**
- * Reserve the sole provider slot until the contribution is disposed.
- * A second registration fails even when it repeats the current name. Providers
- * must stop their tools and await owned work before releasing this registration.
- * @param name - provider-owned name used in registration diagnostics.
- * @returns the effect disposer for this exact registration.
- */
-register(name: BrowserUseProviderName): () => Promise<void>
-```
-
-Source: [`packages/browser-use/browser-use/src/index.ts`](../../packages/browser-use/browser-use/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/browser-use.zh.md

@@ -1,67 +0,0 @@
-# 浏览器操作
-
-[English](browser-use.md) | 中文
-
-浏览器操作让模型通过配置的后端检查与操作网页。DSH 拥有任务循环；提供方提供浏览器操作，并在一个实时 Session 的多个轮次之间保留浏览器状态。
-
-## 选择提供方
-
-在同一组合中挂载 [`dsh-browser-use`](../../packages/browser-use/browser-use/README.zh.md) 和一个提供方。这些提供方是实验性公共 npm 包，需要显式激活。它们最初支持的浏览器引擎是 Chromium。
-
-| 提供方 | 集成方式 |
-|---|---|
-| [Playwright MCP](../../packages/experimental/browser-use-playwright-mcp/README.zh.md) | Playwright 的浏览器控制 MCP 工具 |
-| [Chrome DevTools MCP](../../packages/experimental/browser-use-chrome-devtools-mcp/README.zh.md) | 通过 MCP 进行 Chrome DevTools 检查与控制 |
-| [Stagehand](../../packages/experimental/browser-use-stagehand-native/README.zh.md) | 原生浏览器操作，支持 AI（人工智能）辅助的动作、观测与提取 |
-
-共享服务只注册名称，并拒绝任何第二次提供方注册，包括同名实例。它不包含通用浏览器操作方法、浏览器资源或模型控制的选择器。Profile 或 preset 中的提供方配置为此次激活选择启动或附加模式。
-
-## Session 所有权
-
-启动的浏览器属于使用它的确切实时 Agent 与 Session。跨轮次的调用复用该浏览器。Session 运行时释放时关闭其启动的资源；重新加载或 fork Session 时创建全新浏览器状态。浏览器 profile 和登录状态不会从 Session 日志恢复。
-
-附加的浏览器仍归外部所有。提供方在该提供方实例内将浏览器保留给一个 Session，保留现有浏览器状态，并拒绝另一个 Session 同时附加。清理会断开连接并保持外部浏览器运行。独立 DSH 进程与其他客户端不受此保留约束。
-
-提供方关闭时先停止接收工具调用，并等待自有工作与资源清理完成，再释放共享提供方注册。取消无法撤销已交付的浏览器操作。
-
-## MCP 初始化
-
-MCP 提供方为其加载后创建的每个活动 Agent 初始化一个客户端。现有的串行 `agent/created` 事件等待连接和发现结束后，创建或恢复才完成，排队输入才开始运行。客户端跨轮次归 Session 所有。启动失败或取消会拒绝创建或恢复，并触发客户端清理。
-
-如果附加连接已被占用，本次激活不使用浏览器，但继续运行，后续轮次不会重试。连接释放后，新创建或恢复的激活可以获取它。加载或重新加载提供方不会接管已经活动的 Session；[共享运行时](../../packages/experimental/browser-use-runtime/README.zh.md)拥有这些初始化规则。
-
-## 工具与记录结果
-
-提供方工具使用常规 DSH 执行管线与 Session 日志。提供方拥有自己的工具 schema、结果渲染、图像支持、配置和上游限制；共享服务不添加模型可见内容。Stagehand 的 AI 辅助操作使用其显式配置的原生模型，DSH 保留任务循环。DSH 模型路由、凭据复用、底层推理请求/响应捕获，以及与 Session 用量计量的集成均属暂缓工作；返回的 SDK 数据和元数据仍作为普通工具结果记录。
-
-浏览器 MCP 连接还提供[资源和服务器指令](mcp.zh.md)。发往浏览器服务器的资源调用使用其 Session 队列，并拒绝其他 Session 的请求；服务器指令只会组装到所属 Session 的提示词中。
-
-[决策记录](../../.agents/notes/implemented/architecture/2026-09-12-browser-use-provider-registration.zh.md)解释只注册名称的服务与按 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="ctxbrowseruse--browseruseregistry"></a>
-
-### `ctx.browserUse` — `BrowserUseRegistry`
-
-Owns one optional provider registration in the shared browser-use service.
-
-```ts cordis-catalog
-/**
- * Reserve the sole provider slot until the contribution is disposed.
- * A second registration fails even when it repeats the current name. Providers
- * must stop their tools and await owned work before releasing this registration.
- * @param name - provider-owned name used in registration diagnostics.
- * @returns the effect disposer for this exact registration.
- */
-register(name: BrowserUseProviderName): () => Promise<void>
-```
-
-Source: [`packages/browser-use/browser-use/src/index.ts`](../../packages/browser-use/browser-use/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/claude-code-mods.i18n.yaml

@@ -1,28 +0,0 @@
-# Bilingual-pair consistency record for claude-code-mods.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/claude-code-mods.md
-/claude-code-mods-compatibility:
-  en: e520df3bf44e1160
-  zh: 557956eaf6faf4a7
-/claude-code-mods-compatibility/packaging-and-loading:
-  en: 75cf021ce8babaab
-  zh: caa20540f8bce11a
-/claude-code-mods-compatibility/events:
-  en: cea776ec0063c311
-  zh: 6b8c8b32f2f7ede9
-/claude-code-mods-compatibility/the-chain:
-  en: 111c186536345342
-  zh: 8ddc81c78c05a840
-/claude-code-mods-compatibility/members:
-  en: 11c3d07e9deea30a
-  zh: 3a47a1114869d845
-/claude-code-mods-compatibility/drawing:
-  en: 1bd1a60970fcf426
-  zh: 8f6a8e069f742fb7
-/claude-code-mods-compatibility/testing:
-  en: 8b3530b79e09a067
-  zh: c041e63f7fd8de5a
-/claude-code-mods-compatibility/the-example-mods:
-  en: b3ef5ea831c5c48f
-  zh: fa64186430e7c772