dsh-opencode-go 0.1.21 → 0.1.23

package/docs/development.md

@@ -13,9 +13,9 @@ The root package contains one coherent DSH 0.1.6-alpha.1 development environment
 | `npm test` | Rebuild, then run the core Vitest suite |
 | `npm run test:compat` | Pack once and test the installed artifact across every supported host fixture |
 | `npm run test:compat -- v015-rc1 v017-rc2 v021-alpha1` | Test only the named fixtures; unknown names fail |
-| `npm run test:install` | Test npm and pnpm 11.7.0 Git installs of prebuilt artifacts without plugin build approval |
+| `npm run test:install` | Test npm Git installation and fresh pnpm 11.7.0 Git/tarball installs with no script approvals, plus consumer type resolution |
 | `npm run test:install -- npm` / `-- pnpm` | Run just one package manager; unknown names fail |
-| `npm run verify` | Run core, compatibility, and Git-installation checks |
+| `npm run verify` | Run core, compatibility, and installation checks |
 
 The checks use loopback gateways and local fixtures, not paid inference or an installed user profile. Compatibility and installation checks need registry access; installation checks also require Git. Temporary consumers are created outside the repository and removed on success or failure. Tests never implicitly skip a missing host environment.
 
@@ -25,7 +25,7 @@ The default Git branch ships `lib/` so a GitHub URL, an npm release, and an npm
 
 After source or build-tool changes, run `npm run compile` and commit the regenerated `lib/` with those changes. `npm run check:dist` checks missing, changed, and extra artifacts against an independent rebuild. CI uses `npm run test:ci` so it checks the committed files before running tests, instead of silently replacing stale files first. CSS module filenames are repository-relative, CSS export keys are sorted, and declaration line endings are fixed to LF so artifacts are independent of the checkout path and operating system.
 
-The Git-installation regression creates a fresh repository containing the shipped artifacts but no `src/`, `scripts/`, `tests/`, or `node_modules/`, then installs it with both package managers. Each installed package must expose its host and client entrypoints, declarations, build metadata, and importable host module, and must not declare scripts that trigger Git preparation or dependency installation hooks. pnpm receives no approval for this plugin; only unrelated Google/protobuf scripts are explicitly skipped. The cold Git identity changes for each temporary repository, preventing a previously approved Git build from hiding a missing approval. Consumer profiles and their trust settings are never modified by these tests.
+The installation regression creates a fresh repository containing the shipped artifacts but no `src/`, `scripts/`, `tests/`, or `node_modules/`, then installs it with both package managers. Each installed package must expose its host and client entrypoints, declarations, build metadata, and importable host module, and must not declare scripts that trigger Git preparation or dependency installation hooks. Fresh pnpm consumers install both the Git artifact and a packed npm artifact with `strictDepBuilds=true`, separate empty stores and isolated user configuration. They receive no `allowBuilds` entries, including Google/protobuf skips. The fixtures assert that the private SDK alias, Google SDK and protobufjs are absent, and type-check exported model types without access to development dependencies. The cold Git identity changes for each temporary repository. Consumer profiles and their trust settings are never modified by these tests.
 
 ## Installed-package matrix
 
@@ -41,13 +41,69 @@ The runner performs these steps for each host:
 
 Local compatibility runs are serial by default. Set `DSH_COMPAT_CONCURRENCY` to a positive integer to run that many isolated hosts at once; CI uses four workers and prefers its restored npm download cache, fetching missing packages as needed. Each host keeps its own dependency installation and fixture processes, and all workers consume the same tarball. A failed host does not skip queued hosts or delete files still used by running checks: the runner collects every result before cleanup. Logs are grouped by host, and the console and GitHub job summary report each result and elapsed time.
 
-All host JavaScript imports use ordinary Node resolution. The fixtures do not redirect DSH imports to alternate packages or load the plugin from the source checkout. The client fixture uses the consumer's React, store, and UI primitives, with a CSS loader for published host styles. It verifies the installed browser factory, settings registration, catalog injection, rendering, CSS, and cleanup. Host fixtures retain text streaming, real image processing, history/offload, limits, reasoning, live settings, and profile-bundle checks. Each host also runs all three wire protocols through prompt and tool declaration checks, a streamed tool call, JSON-restored assistant replay, tool-result continuation, and a one-shot request with no tools.
+All host JavaScript imports use ordinary Node resolution. The fixtures do not redirect DSH imports to alternate packages or load the plugin from the source checkout. The client fixture uses the consumer's React, store, and UI primitives, with a CSS loader for published host styles. It verifies the installed browser factory, settings registration, catalog injection, rendering, CSS, and cleanup. Host fixtures retain text streaming, real image processing, history/offload, limits, reasoning, live settings, and profile-bundle checks. Each host also runs all four wire protocols through prompt and tool declaration checks, a streamed tool call, JSON-restored assistant replay, tool-result continuation, and a one-shot request with no tools. Google continuation also checks the retained thought signature.
 
-## Isolated pi-ai dependency
+## Architecture and ownership
 
-The runtime dependency `opencode-go-pi-ai` is an npm alias for `@earendil-works/pi-ai@0.87.1`. All plugin imports, including declaration types and lazy API factories, use the alias. It keeps this plugin's SDK requirement separate from the host's public `@earendil-works/pi-ai` name, so an older plugin that declares pi-ai only as a peer is not redirected by our dependency. The npm and pnpm Git-installation checks include a public pi-ai 0.85.1 and a peer-only probe, and verify that the probe retains 0.85.1 while this plugin resolves its own 0.87.1.
+`src/index.ts` composes the host services. `src/config-contract.ts` is the browser-safe configuration vocabulary; both faces import it instead of maintaining separate interfaces. Version-dependent settings attachment lives in `src/host-settings.ts` and `src/client/host-compat.ts`. `src/settings-bridge.ts` owns section/profile selection and the applied/rejected/unknown write verdict: modern acknowledgments are authoritative, while older hosts require a committed-state check.
 
-DSH requests still convert through `toPiContext`, preserving the existing host input and durable replay contracts. Immediately before calling a provider directly, the adapter applies pi-ai's `normalizeContext`. In 0.87.1, direct providers require `TranscriptContext`; only `Models` streaming entry points normalize legacy Context automatically. Normalizing at this call site preserves the system prompt and tool declarations on both text and image paths without tying the SDK format to the DSH version.
+`GoCatalogManager` owns one configuration-keyed catalog per mount. Inference, model discovery and the settings model service share that catalog directly. The inference adapter retains its standalone catalog fallback for public callers. A superseded catalog cannot send a late route-refresh notification.
+
+Model information reads capture the plugin configuration without querying account generations or serializing host settings. Only request preparation and direct dispatch capture an account generation, before asynchronous discovery; prepared dispatch reuses that generation. Account revision checks remain fresh so a manual A → C → A selection still invalidates an older request's account adoption.
+
+The browser sends typed `opencodeGoAccounts.execute` commands for account additions, removals, selection, naming, ordering, automatic switching and key replacement, including staged key drafts. `GoAccountManager` serializes these commands with recovery; both use `accountOperationPatch` to finish the same durable intention. A client-generated addition ID makes RPC retries idempotent. The UI owns drafts, busy state and quota display; the host owns credentials and revision-guarded metadata writes. Add account operations to the shared command contract and host manager, rather than creating another browser write path.
+
+`src/account-policy.ts` decides whether a failed request may try another account and whether a gateway key should be remembered as rejected. Error classification stays in `src/gateway-error.ts`; stream lifecycle and dispatch stay in `src/adapter.ts`. Both terminal stream errors and thrown errors use the same policy, which blocks fallback after any output, positive token usage or cancellation.
+
+## Failure boundaries and resource policy
+
+The gateway uses HTTP 401 for model errors, subscription limits and authentication failures. `gateway-error.ts` classifies captured `error.type`/`error.code` first. Untyped quota text is admitted only on HTTP 401/402/403/429; untyped 5xx keeps `SERVER` (504 keeps `TIMEOUT`) even when diagnostics quote earlier quota failures. A generic 401/403 never proves a key is invalid. Only `INVALID_CREDENTIAL` is remembered as a gateway key rejection; quota failures can switch accounts before output but do not blacklist credentials. HTTP 200 stream errors continue through the stream mapper's fallback classification. Retry-After remains in bounded HTTP evidence for diagnosis; the host owns retry scheduling.
+
+Discovery and credential/image preparation have a default 60-second deadline. Dispatch has a separate default 30-minute deadline spanning discovery, fallback and streaming. The existing idle watchdog still limits an outstanding stream read. Every external wait observes cancellation, including services that ignore their signal; canceling a catalog waiter does not abort the shared refresh. Prepared capability resolution has its own preparation deadline, and the dispatch timer starts when the prepared stream is consumed.
+
+Image count preflight does not estimate encoded bytes on modern hosts. Four shared permits and a 32-task queue bound preparation across simultaneous calls; exact encoded sizes are checked incrementally with unknown sizes contributing zero. A shared 128 MiB lease budget charges each prepared raw image plus occurrence-weighted base64 bytes. Adapter leases last through streaming and release on completion, failure or consumer stop; standalone conversion only holds its lease during conversion. Queue/budget admission fails with `IMAGE_RESOURCE_BUSY`, without account switching. This logical budget excludes decoder RSS, JSON/SDK copies and retained history. A returned raw image exists before its charge is checked, so four active native operations can still produce transient overshoot. Failure aborts queued work. An in-flight service that ignores cancellation retains its permit until it really settles, so cancellation cannot accidentally admit unbounded native work. A permanently stuck service can therefore exhaust these slots and needs host/service recovery. DSH 0.1.5 retains its transient projection policy; later hosts retain durable `IMAGE_OFFLOAD_REQUIRED` retries.
+
+`StagedForm` submits settings set/unset operations in one `scope.mutate` with the captured revision. A refused batch leaves drafts and does not write secrets. Successful settings drafts clear even if a separate secret write fails, allowing an idempotent retry. A newer draft typed during a save is retained. Settings and credentials remain separate stores, without a cross-store transaction.
+
+Account additions and generated-account removals first confirm a durable `accountOperations` intention in the account's own section/profile. The hidden field stores operation ID, kind and account metadata, never a key. The Host reconciles it at startup, settings/credential connection and committed updates. Already stored addition keys gain their metadata; additions without keys remain visible and can be repaired or removed. Deletion intentions finish credential removal before atomically removing metadata and the intention. Revision guards preserve concurrent edits and later selections; a refused store retains the intention, with at most four passes per trigger and a 30-second deadline per operation. Closing or replacing the connection cancels its waits so a new service can resume. Credential deletion requires an exact generated ID/reference pairing; external or shared legacy references keep their values. Recovery acts only while its service connection is current. Cancelling a wait cannot roll back an already accepted storage write. It cannot recover a key that was never stored, provide isolation against arbitrary simultaneous writes in other profiles, or repair operations predating the journal. Manually sharing a generated reference across profiles also shares its deletion lifecycle.
+
+A nonempty gateway listing with no valid model IDs is a discovery failure and preserves served membership. A confirmed empty list clears it. Missing models on a cold or failed listing report `DISCOVERY_FAILED`, while confirmed absence reports `UNKNOWN_MODEL` through the adapter. Mixed valid/invalid rows use valid IDs and expose a warning in `sources.listing.warning`, the settings page and Host logs. The warning includes counts and at most eight row positions, never malformed row contents, and clears after a clean listing. The choice favors usable partial data while making potential membership loss visible. Public disk metadata still does not establish gateway membership after a restart.
+
+The public `onCallTrace` observer receives one content-free summary per dispatch: random call ID, model, elapsed and stage milliseconds, attempt count, outcome and final code. A bounded `attemptDetails` array includes each attempt's stages, outcome/code, HTTP status, selected redacted upstream request ID, first text/reasoning/tool-argument delta latency and image pool diagnostics. Queue wait is summed across image tasks and may exceed wall-clock image-stage time. HTTP evidence files carry the same call ID and attempt number. There is no stable account identity in this trace. The plugin forwards it to the host debug logger. Observer failures cannot alter inference. Compile-time `never` checking and runtime rejection guard the SDK event union; unknown host roles are explicitly rejected. The open peer range is an installation policy, while the installed matrix is the finite evidence of compatibility.
+
+## Reasoning intent
+
+`src/protocol-contract.ts` restricts the experimental `protocolOverrides` surface to DeepSeek V4.1 Flash → Responses. `src/protocol-policy.ts` resolves the wire API, base URL and fresh protocol compatibility profile together on the captured request config, before capacity overrides. The cached catalog remains unmodified. Effort choices stay those advertised by metadata; an unexpected native toggle/budget or source protocol is rejected before inference. Protocol errors do not trigger a second-protocol retry. The installed-host transcript matrix exercises the override as a Chat Completions-declared model through the real Responses SDK, including tool-result continuation and restored replay; focused tests also switch existing histories in both directions and retain only valid native reasoning state.
+
+For latency comparisons, fix the account, proxy/network, prompt, model, reasoning effort, output cap and stable `x-opencode-session` header. Interleave protocols and report cold and warm samples separately. Measure first body-text delta, total time, output/reasoning tokens and failures; the existing `GoCallTrace.firstOutputMs` includes reasoning and tool deltas and is not body-text TTFT. Local fixtures establish compatibility, not live gateway speed or its underlying provider. Run paid live benchmarks only when requested.
+
+`scripts/benchmark-protocols.mjs` compares the plugin already installed in the macOS desktop profile using the app's actual peer packages. It requires explicit `--live`, performs 20 bounded synthetic calls with a 4,096-token output cap, and writes JSON results under `opencode-protocol-benchmark-<runId>` without changing settings or stored credentials. Automatic fallback is disabled in memory. The output includes first and repeated samples, reasoning/output tokens, route headers, and failures; first-session samples do not prove an upstream cache miss. Run its offline observer/statistics check with `node scripts/benchmark-protocols.mjs --self-test`.
+
+```sh
+ELECTRON_RUN_AS_NODE=1 '/Applications/DeepSeek Harness.app/Contents/MacOS/DeepSeek Harness' scripts/benchmark-protocols.mjs --live
+```
+
+Use `--profile`, `--resources`, or `--out` to change the desktop profile, application resources directory, or report directory. The selected account's credential is read from the environment or the user's DSH credential store and stays in memory.
+
+The model catalog records whether controls are a switch, adjustable effort, or a token budget, independently of pi-ai's wire compatibility hints. `src/reasoning.ts` owns the picker choices and translates a validated selection into Default, Off, On, an explicit effort, or a token budget. Model resolution declares no `defaultEffort`: an omitted user choice remains omitted through the DSH runtime.
+
+Before the SDK sends a payload, the shared `onPayload` hook removes automatic thinking controls for Default. For On it retains the SDK's native enable/budget but removes synthetic effort fields. Off and explicit effort keep the SDK's serialization. Other output configuration, rendering and history options are retained, and payload edits do not mutate shared catalog models. Switches keep their previous opaque `high` ID for durable selection compatibility and display it as On. The verified MiMo Flash control override stays in the same reasoning module.
+
+Token budgets use pi-ai's `thinkingBudgets` override; the SDK still handles the wire field, context ceiling, and answer room. Only SDK-supported budget protocols expose the control; adaptive Anthropic models retain effort controls. Models declaring both effort and budget keep their efforts and can add numeric budget choices. Standard budget presets retain the historical `minimal`/`low`/`medium`/`high` IDs. Additional presets use durable `budget:N` IDs and are configured in `modelLimits[modelId].thinkingBudgets`. Catalog bounds reach the settings page through the models RPC; numeric choices and request settings are captured together before dispatch.
+
+## Bundled pi-ai implementation
+
+The development dependency `opencode-go-pi-ai` is an npm alias for `@earendil-works/pi-ai@1.2.0`. esbuild retains the four supported protocol implementations and the OpenCode Go model table, and discards unrelated provider implementations. Public SDK types are flattened into `lib/types/sdk-types.d.ts`; consumers do not need the private alias to resolve them. OpenAI 7.19.0 and Anthropic 0.129.0 remain runtime dependencies at the same versions pi-ai uses. Google 2.21.0 and its required HTTP dependencies are bundled. Bundled code and type licenses ship in `lib/vendor-licenses.txt`.
+
+The published package does not depend on pi-ai or Google/protobuf packages, so their install hooks never run in consumers, including when using Gemini. This avoids the pnpm 11 script-approval interruption that triggered issue #43 without changing the host's policy. An npm consumer separately includes public pi-ai 0.85.1 and a peer-only probe, plus OpenAI 6.40.0 and Anthropic 0.124.0. It verifies that the peer retains pi-ai 0.85.1, the consumer retains both older transport SDKs, and the plugin resolves its own OpenAI 7.19.0 and Anthropic 0.129.0. Other plugins' dependencies still follow the user's host trust settings.
+
+`src/google-generative-ai.ts` reuses pi-ai's native Google message conversion, tool declarations, streaming events, usage and thought-signature replay. A request-scoped `AsyncLocalStorage` binding carries the captured diagnostic/proxy fetch and Harness User-Agent without replacing global fetch. `scripts/google-fetch-bridge.mjs` substitutes one HTTP fetch call in the bundled Google SDK, with an exact 2.21.0 version check and a single-match source check. It also pins pi-ai 1.2.0's Google client factory to `vertexai: false`, guarded by its version and a single constructor match, so host `GOOGLE_GENAI_USE_VERTEXAI` / `GOOGLE_GENAI_USE_ENTERPRISE` settings cannot change the gateway's Gemini route. The environment and other Google clients retain their own backend selection. esbuild and Vitest use the same substitutions; review the bridge before changing either SDK pin. SDK serialization, stream parsing, cancellation and retry handling remain upstream code. Gemini 4 Argon postdates pi-ai 1.2.0, so the wrapper selects its discrete thinking levels explicitly. Default removes Google's nested `thinkingConfig`, while Low/Medium/High retain the metadata-declared levels.
+
+The default public base is `https://opencode.ai/inference/go/v1` for model discovery, every inference protocol and usage requests. `src/gateway-url.ts` migrates the exact legacy official base `https://opencode.ai/zen/go/v1` before request paths are constructed. Both plain and volatile configuration schemas apply the same transform to saved settings and writes; the callback is self-contained because settings schemas serialize its source. Legacy section providers persist raw edits, so `src/host-settings.ts` also rewrites their stored alias on attachment and document changes, with revision checks to preserve concurrent edits. URL validation, direct catalog construction and metadata conversion also apply the migration, including callers that supply raw configuration. The plugin never needs to reach the legacy gateway, even if it stops serving all routes. Custom gateways retain their configured addresses. Directory availability alone does not verify inference routing; a desktop follow-up confirmed the canonical Google route with a bounded real generation and an actual chat response.
+
+The [pi-ai 1.2.0 changelog](https://github.com/earendil-works/pi/blob/v1.2.0/packages/ai/CHANGELOG.md) adds per-key OpenRouter catalogs and provider refresh base URLs, fixes Mistral stream timeouts, and retries Anthropic preferred strict-tool requests once without strict mode when grammar limits are exceeded. Its Google adapter is unchanged from 1.1.0 and still rejects custom fetch. Model/compatibility types now come from shared schema modules; the public declaration bundle must retain those definitions without leaking the private SDK alias.
+
+DSH requests still convert through `toPiContext`, preserving the existing host input and durable replay contracts. Immediately before calling a provider directly, the adapter applies pi-ai's `normalizeContext`. In 1.1.0, direct providers require `TranscriptContext`; only `Models` streaming entry points normalize legacy Context automatically. Normalizing at this call site preserves the system prompt and tool declarations on both text and image paths without tying the SDK format to the DSH version.
 
 This upgrade does not enable developer messages, tool-change blocks, or deferred tool loading. Their existing `UNSUPPORTED_CONTENT` errors remain explicit. The minimum DSH version and peer ranges stay unchanged; new host fixtures verify runtime compatibility rather than expanding the supported content vocabulary.
 
@@ -71,6 +127,8 @@ After changing the root lockfile, verify a clean `npm ci --strict-peer-deps` and
 
 The GitHub workflow runs core and Git-installation checks on Linux and Windows with Node 22.19.0 and 24. Core tests, npm installs, and pnpm installs run as independent jobs, so one slow installation does not consume another check's time allowance. Installation jobs need no root `npm ci`: their runner uses only Node built-ins, and the fresh Git fixture supplies committed artifacts and must not need build dependencies or plugin build approval. The complete installed-host matrix runs separately on Linux/Node 24.
 
+Each isolated installation consumer installs the root's pinned TypeScript version solely to check the plugin's public declarations. That check resolves its compiler from the consumer, so it also runs when the checkout has no `node_modules`. Bundled license text uses LF regardless of the source checkout's line endings, keeping Windows artifact checks reproducible.
+
 Installation jobs reuse the npm download cache and a separate pnpm store, preferring cached packages while still fetching missing data. They never restore the checkout's `node_modules` or `lib/`. CI keeps the npm cache, isolated consumers, and the cached pnpm store under `RUNNER_TEMP`, on the runner's work volume. `DSH_PNPM_STORE_DIR` selects the pnpm store; local runs use the system temporary directory and the default package caches unless overridden.
 
 Every Git-installation run reports fixture preparation, installation, artifact verification, cleanup, and total elapsed time. GitHub job summaries include a phase table. CI also enables npm's internal timing records and uploads the `*-timing.json` files for seven days, for diagnosing dependency resolution and extraction; a timeout may prevent the still-running process from writing its final timing file. The 15-minute job limit remains unchanged.

package/docs/fork-review-2026-09-25.md

@@ -0,0 +1,191 @@
+# 8 个 fork 的改进与吸收建议
+
+检查日期：2026-09-25。基线为本项目 `main` / `origin/main` 的 `8590c5752189658b60240b729666f814f12b27ff`（0.1.12）；已通过 GitHub API 确认远端也是同一提交。检查范围是 GitHub 返回的 8 个公开 fork、全部 14 个公开分支，并结合 PR 状态、实际 diff 和当前实现判断。此次只增加研究记录，没有合并 fork、修改产品代码或发布包。[上游基线](https://github.com/Duskriver/dsh-opencode-go/commit/8590c5752189658b60240b729666f814f12b27ff) · [fork 列表 API](https://api.github.com/repos/Duskriver/dsh-opencode-go/forks?per_page=100)
+
+## 结论
+
+建议优先吸收两个独立小改动，另保留一个低优先级边界修复：
+
+1. **Guojing6：为 models.dev 设置独立下载超时。** 网关列表继续 10 秒，约 5 MB 的元数据快照允许更长下载时间。其 `7f699a4` 只改一个文件，可干净应用到当前 main；仍应补慢响应和超时回退测试，并评估 60 秒等待对模型选择器的影响。
+2. **vjcspy：PR #11 的历史输入校验。** 预先拒绝目前无法表达的 developer 消息、工具增删块和延迟加载工具；补丁小、没有依赖升级，已通过本次隔离类型检查和定向测试。没有已知线上触发来源，属于预防性加固。
+3. **x6nux：宿主降级后处理新版图片卸载标记。** 本次用合成历史在真实 0.1.5-rc.1 LLM 模块上复现当前转换函数崩溃，fork 同输入通过。适合只移植能力判断，并补回归测试；没有验证真实用户会话从新版降级的完整迁移流程。
+
+不建议整体合入 Guojing6 的兼容分支或 vjcspy 的 develop。前者将大量核心能力改为宽泛回退，后者包含发布安装脚本问题；两者的依赖和历史表示改造远大于目前已经支持 rc.1/rc.2 所需的改动。
+
+## 每个 fork 做了什么
+
+下表的“独有提交”按 `main..fork` 计算。它不等于“尚缺功能”：nam278 的功能通过整合提交进入主线，因此原始提交仍显示独有。
+
+| Fork | 分支和独有提交 | 主要改进 | 当前判断 |
+| --- | --- | --- | --- |
+| [liujwcn](https://github.com/liujwcn/dsh-opencode-go) | `main`：1 | 声明 DSH 0.1.7-rc.1 支持，增加独立宿主 fixture 与兼容测试 | 当前 0.1.12 已覆盖，并进一步支持 rc.2，不必再合 |
+| [Guojing6](https://github.com/Guojing6/dsh-opencode-go) | `main`：0；`feat/dsh-0.1.7-rc1-host-drift`：3 | rc.1 开发依赖、宿主 API 回退、旧工具结果转换、Windows 沙箱构建/测试调整、自包含 headless smoke、元数据 60 秒超时 | 建议单独吸收超时改动；其余按具体需求拆分 |
+| [RaulLazaro](https://github.com/RaulLazaro/dsh-opencode-go) | `main` / `fix/default-reasoning-effort`：均 0 | 对不传档位就关闭思考的协议设置默认推理档位 | PR #6 已合，并修正最高档位选择，不必再合 |
+| [xwxYa](https://github.com/xwxYa/dsh-opencode-go) | `main` / `fix/handle-undecoded-compressed-json`：均 0 | 处理缺失编码响应头的压缩 JSON，并限制读取/解压大小 | PR #5 已合；后来演进为请求 `identity` 的实现，不应恢复旧解压逻辑 |
+| [OHeroJ](https://github.com/OHeroJ/dsh-opencode-go) | `main`：0 | 仅保留较早上游快照 | 没有独有改进 |
+| [nam278](https://github.com/nam278/dsh-opencode-go) | `main` / `feat/model-limits-ui`：同一独有提交 | 按模型覆盖上下文和输出容量，设置页搜索、重置、保存/放弃 | 已通过 `9d5cea7` 整合并修复边界问题，不必重复引入 |
+| [x6nux](https://github.com/x6nux/dsh-opencode-go) | `main`：1 | 0.1.5/0.1.6 图片卸载兼容、同时传像素预算和目标尺寸、处理降级历史标记 | 前两项已有等价能力；降级标记处理仍值得单独借鉴 |
+| [vjcspy](https://github.com/vjcspy/dsh-opencode-go) | `master`：0；`develop`：6；`feat/history-guards`：1 | rc.1 开发基线与测试改造、历史转换及 3 类不支持输入校验 | 建议 PR #11；不整体合 develop |
+
+## Guojing6：最有实际收益的是慢网络超时修复
+
+特性分支相对当前 main 独有 `4dec86b`、`da9f044`、`7f699a4` 三个提交，共改 30 个文件，1183 行新增、520 行删除；默认 `main` 没有独有提交。这个分支以 `f65a04b` 为基线，尚未包含本项目最后的 rc.2 支持和用量进度条修复。[完整分支比较](https://github.com/Duskriver/dsh-opencode-go/compare/8590c5752189658b60240b729666f814f12b27ff...Guojing6:7f699a4e5b91792fe5e72951a1229639a775bf2f)
+
+### 建议单独吸收：元数据下载超时
+
+当前 `src/catalog.ts` 的 `/models` 和 `models.dev/api.json` 都使用 10 秒完整请求期限。当前 JSON 请求还明确使用 `accept-encoding: identity`，元数据体积明显大于网关 ID 列表。fork 新增 `MODEL_METADATA_FETCH_TIMEOUT_MS = 60_000`，只用于元数据请求，保留网关 10 秒期限。作者报告代理冷连接下载用时 13.7 秒；这是作者测量，本次未在其网络环境复测。[独立提交](https://github.com/Guojing6/dsh-opencode-go/commit/7f699a4e5b91792fe5e72951a1229639a775bf2f) · [当前目录实现](https://github.com/Duskriver/dsh-opencode-go/blob/8590c5752189658b60240b729666f814f12b27ff/src/catalog.ts) · [当前 identity 请求实现](https://github.com/Duskriver/dsh-opencode-go/blob/8590c5752189658b60240b729666f814f12b27ff/src/json-response.ts)
+
+本次 `git apply --check` 验证该提交补丁可直接应用到当前 main，无需引入 `host.ts` 或升级依赖。移植时需要覆盖：元数据慢于 10 秒但快于新期限、超时复用已缓存元数据、首次失败仅用已有备用配置、网关仍按 10 秒失败。代码用 `Promise.allSettled` 等待两个请求，目录刷新和需要新快照的请求可能因此最多等待约 60 秒；不能只考虑下载成功率。[当前 snapshot/build 流程](https://github.com/Duskriver/dsh-opencode-go/blob/8590c5752189658b60240b729666f814f12b27ff/src/catalog.ts#L115)
+
+### 可以借鉴，但不整体搬入
+
+- **Headless smoke 自动安装 tarball、通过 Node 启动 CLI**：在新建 `DSH_HOME` 中先安装插件，使验证脚本的前置条件更明确，也有助于避开 Windows `.bin` 启动差异。移植时保留本项目对 `standalone-ok` 输出的断言；fork 切换继承 stdio 后删除了该断言。[提交 da9f044](https://github.com/Guojing6/dsh-opencode-go/commit/da9f044) · [fork 脚本](https://github.com/Guojing6/dsh-opencode-go/blob/7f699a4e5b91792fe5e72951a1229639a775bf2f/scripts/headless-smoke.mjs#L34)
+- **Windows 沙箱构建/测试适配**：改用 esbuild CLI、复制 shadow 源码树并重写 CSS import、Vitest threads、继承子进程 stdio。它解决的是作者环境下的 spawn EPERM；本次没有 Windows 环境验证。增加的构建维护成本和移除输出断言的代价，暂不值得随功能补丁一并引入。[构建脚本](https://github.com/Guojing6/dsh-opencode-go/blob/7f699a4e5b91792fe5e72951a1229639a775bf2f/scripts/build.mjs) · [宿主测试](https://github.com/Guojing6/dsh-opencode-go/blob/7f699a4e5b91792fe5e72951a1229639a775bf2f/tests/host-compatibility.spec.ts)
+- **统一 `host.ts` 回退**：namespace 读取适用于已知跨版本导出差异，但这里扩展到了错误类、凭据、图片、远程服务及超时机制。例如缺少 `idleWatchdog` 时直接透传 iterator，流式空闲期限失效；缺少 LlmAdapter 时 apply 记录日志后直接返回。当前已验证的 8 代宿主不需要这些假设性降级，不建议整体采用。[host.ts](https://github.com/Guojing6/dsh-opencode-go/blob/7f699a4e5b91792fe5e72951a1229639a775bf2f/src/host.ts#L246) · [apply](https://github.com/Guojing6/dsh-opencode-go/blob/7f699a4e5b91792fe5e72951a1229639a775bf2f/src/index.ts)
+- **旧 nested tool-result 图片兼容**：新增递归图片检查和已卸载图片投影，但 adapter 的图片入口仍调用宿主的 `contentHasImage`，现代宿主仅扫描顶层；仅修改 context 无法使整条请求链路完整支持旧形状。应先确认宿主会否传入这种混合历史，再统一能力检查、预算计算及转换测试。[fork context](https://github.com/Guojing6/dsh-opencode-go/blob/7f699a4e5b91792fe5e72951a1229639a775bf2f/src/conversion/context.ts) · [fork adapter](https://github.com/Guojing6/dsh-opencode-go/blob/7f699a4e5b91792fe5e72951a1229639a775bf2f/src/adapter.ts)
+
+## x6nux：大部分已覆盖，但降级历史边界仍有价值
+
+`0d6e9af` 的主要改动是通过宿主能力选择图片卸载协议，并同时给附件服务传递 `maxPixels/maxBytes` 和 `width/height`。本项目已经通过 `bd3ba1f` 与 `1785150` 实现相应兼容，而且现实现保留了图片准备前的估算投影与准备后的精确投影，不宜换回整个旧模块。[fork 提交](https://github.com/x6nux/dsh-opencode-go/commit/0d6e9af74bc654358197f5f5dd323a2e8c7b39ed) · [主线图片兼容提交](https://github.com/Duskriver/dsh-opencode-go/commit/178515041e6ade11cf8e292f6880171c2d46adfb) · [当前投影模块](https://github.com/Duskriver/dsh-opencode-go/blob/8590c5752189658b60240b729666f814f12b27ff/src/conversion/image-offload.ts)
+
+尚有差异的是 `isOffloaded()`：fork 只有在宿主具备新版 surface offload API 时才把 `offloaded: true` 当作已卸载；0.1.5 不理解这个标记，仍需按自己的请求预算准备图片。当前 `collectImageRefs` 不分宿主跳过所有带标记图片，旧宿主后续访问 requestImages 中缺失的图片版本时会出错。[fork 能力判断](https://github.com/x6nux/dsh-opencode-go/blob/0d6e9af74bc654358197f5f5dd323a2e8c7b39ed/src/conversion/host-image-offload.ts#L72) · [当前 collectImageRefs](https://github.com/Duskriver/dsh-opencode-go/blob/8590c5752189658b60240b729666f814f12b27ff/src/conversion/context.ts#L106)
+
+本次把两份 context 分别编译到临时目录，使用实际 `dsh-llm-v015-rc1` / `dsh-attachment-v015-rc1` 模块、模拟附件读取服务和同一合成输入进行对照：
+
+```text
+输入：user.content = [{ type: 'image', attachment: 1 字节图片引用, offloaded: true }]
+图片请求预算：100 bytes
+main：读取附件 0 次；TypeError: Cannot read properties of undefined (reading 'bytes')
+x6nux：读取附件 1 次；转换成功，输出 1 个 image 块
+```
+
+这是转换层复现，没有通过真实 CLI 打开降级会话，也没有真实模型请求。因此建议低优先级移植这个能力判断，并明确降级时是按旧宿主规则重发图片还是统一转成占位文本；不要把 fork 的 mock 测试或本次合成测试等同于完整跨版本数据迁移验证。
+
+## vjcspy/dsh-opencode-go
+
+检查日期：2026-09-25。比较基线为本项目当前提交 `8590c5752189658b60240b729666f814f12b27ff`（0.1.12）。本节检查了该 fork 的全部 3 个公开分支、实际代码差异、PR #10 / #11 及官方 DSH 参考实现；没有修改本项目生产代码，没有安装或执行 `develop` 的生命周期脚本。
+
+### 分支范围与结论
+
+| 分支 | 固定提交 SHA | 相对本项目基线 | 结论 |
+| --- | --- | --- | --- |
+| `master` | `8590c5752189658b60240b729666f814f12b27ff` | 完全相同 | 无新增内容 |
+| `feat/history-guards` | `57646f55c57b7291b783ccf80f47acf6bc64e39b` | 领先 1、落后 0；2 文件，+71 / -6 | **建议吸收**；对应开放的 PR #11，是独立、低风险的输入校验补丁 |
+| `develop` | `3f5e0550a1c5cdfedcac88445a20a4d5de9cc373` | 领先 6、落后 0；23 文件，+930 / -1224 | **不建议整分支合入**；主要是开发依赖升级适配，混入安装回归与未完成的旧图片历史兼容 |
+
+来源：[公开分支](https://github.com/vjcspy/dsh-opencode-go/branches)、[guards 固定比较](https://github.com/vjcspy/dsh-opencode-go/compare/8590c5752189658b60240b729666f814f12b27ff...57646f55c57b7291b783ccf80f47acf6bc64e39b)、[develop 固定比较](https://github.com/vjcspy/dsh-opencode-go/compare/8590c5752189658b60240b729666f814f12b27ff...3f5e0550a1c5cdfedcac88445a20a4d5de9cc373)。以上数量由 GitHub Compare API 与本地 Git 交叉核对。
+
+### 建议吸收：历史与工具声明的三项保护
+
+PR #11 的提交直接以本项目当前 HEAD 为父提交，不需要先迁移 `develop`，也不更改依赖、锁文件、已支持宿主范围或持久化格式。可以直接 cherry-pick `57646f55c57b7291b783ccf80f47acf6bc64e39b`，再按本项目流程验证合入。检查时 PR 为 open，GitHub 报告 `mergeable: true`、`mergeable_state: clean`。本次仅评估，没有合并、关闭或评论该 PR。[PR #11](https://github.com/Duskriver/dsh-opencode-go/pull/11)
+
+实际改变如下：
+
+| 输入 | 现有代码行为 | 补丁行为及收益 |
+| --- | --- | --- |
+| 历史中出现 `developer` 角色 | 未识别的角色会落入普通用户消息分支，可能丢失角色语义 | 转换时抛出 `LlmError`，错误码 `UNSUPPORTED_CONTENT`，避免把不支持的高优先级历史按普通用户文本发送 |
+| 顶层内容块为 `tool-addition` / `tool-removal` | 不属于已支持的内容词汇，可能被转换忽略 | 明确拒绝，避免工具状态变更被悄悄丢掉 |
+| 工具声明含 `deferLoading: true` | `toolsOf()` 仅抽取 name / description / parameters，延迟加载标志会丢失 | 明确拒绝，避免把延迟工具当作普通工具发送 |
+
+以上前后行为来自实际转换代码。不能笼统称作“原来一定会得到 provider 的 malformed request”：有些输入会得到可发送但语义错误或内容缺失的请求，这也是该补丁值得吸收的原因。[当前转换实现](https://github.com/Duskriver/dsh-opencode-go/blob/8590c5752189658b60240b729666f814f12b27ff/src/conversion/context.ts)、[补丁实现](https://github.com/vjcspy/dsh-opencode-go/blob/57646f55c57b7291b783ccf80f47acf6bc64e39b/src/conversion/context.ts#L51-L66)
+
+两个历史 guard 放在现有图片角色校验之前，并由同步、异步转换路径共同调用。工具 guard 放在 `toolsOf()`，不依赖历史是否非空。三个错误与 DSH 官方 `dsh-v0.1.7-rc.2` 的参考 pi-ai adapter 一致；该标签固定到 `477b4f420553e8a52c2fbccc464d7561b239c443`，已读取实际源码核实。因为本项目开发类型仍是 `dsh-llm@0.1.6-alpha.1`，使用结构类型收窄是保留旧版本编译支持的适配手段。[fork 工具 guard](https://github.com/vjcspy/dsh-opencode-go/blob/57646f55c57b7291b783ccf80f47acf6bc64e39b/src/conversion/context.ts#L143-L155)、[官方历史 guard](https://github.com/deepseek-ai/deepseek-harness/blob/477b4f420553e8a52c2fbccc464d7561b239c443/packages/llm/llm-pi-ai/src/context.ts#L49-L66)、[官方工具 guard](https://github.com/deepseek-ai/deepseek-harness/blob/477b4f420553e8a52c2fbccc464d7561b239c443/packages/llm/llm-pi-ai/src/context.ts#L129-L143)
+
+安全与兼容性判断：补丁只读取输入、抛出错误，不写历史、附件、设置或凭据，也没有新增网络端点。正常支持的消息仍使用原有转换路径；传入这三类原本不支持的输入会由“尝试转换”变成“明确失败”，属于预期的收紧行为。PR 作者明确表示目前没有已知生产来源，这一点应按作者声明理解，本次没有独立证明所有外部插件均不可能生成它们。因此优先级是预防性加固，不应宣传为已复现的线上事故修复。[PR 的范围说明](https://github.com/Duskriver/dsh-opencode-go/pull/11)
+
+一个非阻塞细节：异步路径的 `deferLoading` 校验仍在最后构造 envelope 时执行，可能先读取图片附件；它保证生成请求前失败，但不是所有图片工作前都失败。此顺序来自共享的 `piContext()` / `toolsOf()` 调用，且与官方实现一致。若将来要求“无效工具声明绝不读取附件”，应单独提前做 options 校验。[异步路径](https://github.com/vjcspy/dsh-opencode-go/blob/57646f55c57b7291b783ccf80f47acf6bc64e39b/src/conversion/context.ts#L325-L405)
+
+### 已执行的 PR #11 验证
+
+在独立 `/tmp` Git worktree 中使用当前项目已经安装的依赖，显式运行可信的 Vitest 和 TypeScript CLI；没有运行 fork 的 `npm install`、`postinstall` 或 `pretest`。环境：macOS arm64、Node `v24.14.1`、Vitest `4.1.11`。
+
+| 检查 | 本次实际结果 |
+| --- | --- |
+| 基线 `8590c575…` 的 `tests/conversion-context.spec.ts` | 22 / 22 通过 |
+| guards 提交 `57646f55…` 的同一测试文件 | 25 / 25 通过 |
+| guards 提交的 Host `tsc -p tsconfig.host.json --noEmit` | 通过 |
+| guards 提交的 Client `tsc -p tsconfig.client.json --noEmit` | 通过 |
+
+新增 3 个测试分别覆盖 developer、tool-addition、deferLoading，并各检查同步与异步两条入口；同步侧还断言 `LlmError` 类型，两个入口均断言错误码与完整信息。尚未单独覆盖 `tool-removal`、空 history 配合 deferred tools、`deferLoading: false` 的正常路径，可以在吸收时补上边界用例；它们不是当前发现的实现错误。[新增测试](https://github.com/vjcspy/dsh-opencode-go/blob/57646f55c57b7291b783ccf80f47acf6bc64e39b/tests/conversion-context.spec.ts#L571-L625)
+
+“304 tests / build 通过”是 PR 作者提供的验证声明，本子任务没有将其冒充为本次完整验证；本次直接执行的范围见上表。主项目整体检查结果应在总报告中另列。
+
+### develop 的 6 个提交究竟增加了什么
+
+| 固定提交 | 改动与价值 | 吸收建议 |
+| --- | --- | --- |
+| [`bbef5f458b5785166ddd81aff39ce1ad5100d337`](https://github.com/vjcspy/dsh-opencode-go/commit/bbef5f458b5785166ddd81aff39ce1ad5100d337) | 开发依赖迁移到 DSH rc.1；运行时 `dsh-brand` 升到 rc.1、Schemastery 升到 3.18.4；新增 `.npmrc` 与 fixture symlink `postinstall` | 暂不迁移；并非仅 devDependency 变化，且引入下述发布包安装问题 |
+| [`50c788830508f9552ab853496ba6745eb1f33ffe`](https://github.com/vjcspy/dsh-opencode-go/commit/50c788830508f9552ab853496ba6745eb1f33ffe) | 适配 rc.1 类型：`RequestMessage`、settings / client 的结构访问、图标 Medium 兜底；中间版本同时删除旧 settings 和 nested tool-result 路径 | 不能单独挑这个提交；后续两次 fix 正是在恢复这次删除的向后兼容 |
+| [`455de34af4c9448f2b823db889e5e42ed5a7a321`](https://github.com/vjcspy/dsh-opencode-go/commit/455de34af4c9448f2b823db889e5e42ed5a7a321) | 用 `SettingsCompat` 结构类型恢复 0.1.5 / 0.1.6 `installSection` | 本项目原本就有 fallback，主要是 fork 的类型适配与回归修复 |
+| [`10bf28b85972f3b8893743ad8bcfe85b1f94ab15`](https://github.com/vjcspy/dsh-opencode-go/commit/10bf28b85972f3b8893743ad8bcfe85b1f94ab15) | 结构方式恢复旧 nested tool-result；增加深层图片检测、nested offloaded image 文本替换和 3 个 guard | guard 选用 PR #11 的独立版本；不要原样搬入其余图片逻辑 |
+| [`873ee67f4b4b0e8b7ac46572fd951db653b41d18`](https://github.com/vjcspy/dsh-opencode-go/commit/873ee67f4b4b0e8b7ac46572fd951db653b41d18) | 动态配置测试改走新版 entry form，增加 settings fallback 定向测试，改消息 source fixture，固定测试 `NODE_ENV` | 可提取少量独立测试；不宜把旧 settings 文件验证整体替换掉 |
+| [`3f5e0550a1c5cdfedcac88445a20a4d5de9cc373`](https://github.com/vjcspy/dsh-opencode-go/commit/3f5e0550a1c5cdfedcac88445a20a4d5de9cc373) | 私有 fork 版本名改为 `0.1.12-vjcspy.1` | 无上游产品价值，不吸收 |
+
+需要纠正“develop 才新增 rc.1 / rc.2 兼容”这一印象：当前基线已经支持新的独立 `tool` role、`configForms`、`configure` 优先 / `installSection` fallback 和 Regular / 14 图标兼容；peer 范围与八代宿主矩阵也已包含 rc.1 / rc.2。develop 中许多结构 cast 与 `RequestMessage` 类型替换，目的是用新开发依赖重新编译原有跨版本行为，不是当前用户缺失的新能力。关闭的 [PR #10](https://github.com/Duskriver/dsh-opencode-go/pull/10) 也不应重复当成待移植的新特性。[当前 settings 实现](https://github.com/Duskriver/dsh-opencode-go/blob/8590c5752189658b60240b729666f814f12b27ff/src/index.ts#L206-L240)、[当前客户端入口](https://github.com/Duskriver/dsh-opencode-go/blob/8590c5752189658b60240b729666f814f12b27ff/src/client/index.ts#L43-L84)、[当前验证记录](https://github.com/Duskriver/dsh-opencode-go/blob/8590c5752189658b60240b729666f814f12b27ff/docs/verification.md)
+
+### develop 的两个主要问题
+
+**1. 发布包增加了会引用缺失文件的 postinstall。**
+
+已验证事实：`package.json` 第 61 行增加 `postinstall: node scripts/materialize-fixture-links.mjs`，但 `files` 白名单第 32–38 行只包含 `lib`、patch、notices、docs、examples；`scripts` 与 `tests/hosts` 均不在包内。对固定 develop 提交执行 `npm pack --dry-run --json --ignore-scripts --workspaces=false`，确认打包清单没有该脚本与 tests 目录。这个 dry-run 未构建，所以也没有生成 lib；这里只用它核实受白名单控制的脚本/测试文件缺失，不把未构建的 lib 当作缺陷。[manifest](https://github.com/vjcspy/dsh-opencode-go/blob/3f5e0550a1c5cdfedcac88445a20a4d5de9cc373/package.json#L32-L62)
+
+由此可以确定：按当前清单发布后，在执行生命周期脚本的普通 npm 安装中，该 postinstall 会引用不存在的文件，预期报 `MODULE_NOT_FOUND`。本次没有执行消费者安装，因此具体错误是基于文件清单与 Node 入口语义的推断，并非抓取到的安装日志。即使仅补发脚本仍不完整：脚本无条件 `readdirSync(tests/hosts)`，发布包没有此目录时又会失败；它本质上只服务开发 fixture，应留在显式开发准备步骤，或至少同时解决发布环境跳过逻辑。[脚本入口及目录遍历](https://github.com/vjcspy/dsh-opencode-go/blob/3f5e0550a1c5cdfedcac88445a20a4d5de9cc373/scripts/materialize-fixture-links.mjs#L23-L35)
+
+**2. 新增旧 nested 图片支持只补了 context，入口选择和总预算仍不一致。**
+
+已验证的代码事实：develop 在 context 内新增 `contentHasImageDeep()`，递归收集图片并处理 nested offloaded image；但 `src/adapter.ts` 没有任何变更，仍使用宿主的 `contentHasImage()` 决定图片模型校验和是否选择异步图片转换。官方 rc.2 的这个函数仅检查顶层；其 `requiredImageOffload()` / `projectOffloadedImages()` 也只遍历顶层。develop 的 `image-offload.ts` 只换了类型，仍把原始结构传给宿主 API。[deep 检测](https://github.com/vjcspy/dsh-opencode-go/blob/3f5e0550a1c5cdfedcac88445a20a4d5de9cc373/src/conversion/context.ts#L60-L75)、[adapter 分支选择](https://github.com/vjcspy/dsh-opencode-go/blob/3f5e0550a1c5cdfedcac88445a20a4d5de9cc373/src/adapter.ts#L269-L300)、[官方顶层检测](https://github.com/deepseek-ai/deepseek-harness/blob/477b4f420553e8a52c2fbccc464d7561b239c443/packages/llm/llm/src/content.ts#L126-L128)、[官方图片遍历与预算](https://github.com/deepseek-ai/deepseek-harness/blob/477b4f420553e8a52c2fbccc464d7561b239c443/packages/llm/llm/src/content.ts#L216-L333)
+
+据上述控制流推导，在 rc.1 / rc.2 宿主接受原始旧嵌套历史的前提下：
+
+- 若所有图片都在旧 `tool-result` 块内部，adapter 判定没有图片，进入同步转换；新增 deep 检测随后报“需要附件服务”，即使实际上已配置服务也无法重放。它从静默丢图变成明确拒绝有价值，但不能称为完成了兼容。
+- 若还有一张顶层图片触发异步路径，context 会读出并发送嵌套图片，但宿主的总量检查漏计嵌套图片，因此可能超过 `maxRequestImageBytes`。已有 offloaded 标记的嵌套图片可由新增分支替换为文本，但这不解决未 offload 图片的预算问题。[同步拒绝](https://github.com/vjcspy/dsh-opencode-go/blob/3f5e0550a1c5cdfedcac88445a20a4d5de9cc373/src/conversion/context.ts#L257-L265)、[嵌套图片转换](https://github.com/vjcspy/dsh-opencode-go/blob/3f5e0550a1c5cdfedcac88445a20a4d5de9cc373/src/conversion/context.ts#L115-L152)、[图片预算桥接](https://github.com/vjcspy/dsh-opencode-go/blob/3f5e0550a1c5cdfedcac88445a20a4d5de9cc373/src/conversion/image-offload.ts#L25-L47)
+
+这两个情形是静态控制流推断，本次未运行完整 develop，也未证明当前生产宿主会把这种历史原样交给插件。develop 自己的提交说明亦称相关 nested 分支在已发布宿主上不可达。若以后确需迁移旧历史，应明确规范化策略，覆盖 adapter 入口、tool 配对、图片预算、offload 协议和不可变历史，而不是只移植深层 helper。新增 legacy 测试仅验证同步文本 tool-result，没有覆盖上述混合图片场景。[develop 新增测试](https://github.com/vjcspy/dsh-opencode-go/blob/3f5e0550a1c5cdfedcac88445a20a4d5de9cc373/tests/conversion-context.spec.ts#L573-L618)
+
+### develop 中值得单独借鉴的内容
+
+- **优先借鉴 settings fallback 的定向回归测试。** `tests/settings-compat.spec.ts` 检查旧服务注册、source / onChange 驱动路由、新服务优先 configure 三点，能防止以后升级开发类型时误删旧分支。上游无需为这些测试一起迁移依赖或改生产逻辑；迁入时补足 Context dispose，并保持现有真实宿主矩阵。[测试文件](https://github.com/vjcspy/dsh-opencode-go/blob/3f5e0550a1c5cdfedcac88445a20a4d5de9cc373/tests/settings-compat.spec.ts)
+- **新版 profile fixture 可以作为新增覆盖，不应替代旧文件存储测试。** develop 通过真实 Loader / Settings 加一个内存 config editor 验证 entry form 更新，思路合理；但它替换了现有旧 FileSettings 测试，且删掉“非法 baseURL 拒绝后 settings.yaml 原文仍为空”的磁盘断言。内存 fixture 无法证明持久化文件没有被改写。当前上游另有 profile compatibility fixture，新增前应先查重。[fixture](https://github.com/vjcspy/dsh-opencode-go/blob/3f5e0550a1c5cdfedcac88445a20a4d5de9cc373/tests/support/profile-fixture.ts)、[动态配置测试改动](https://github.com/vjcspy/dsh-opencode-go/commit/873ee67f4b4b0e8b7ac46572fd951db653b41d18)
+- **`NODE_ENV=test` 可按实际问题选择吸收。** 无条件在 Vitest 配置内设置 test 环境，是开发测试的稳定性调整，不改变发布运行时；fork 注释声称修复 production shell 影响 Vite 解析的问题，本次没有复现该场景，不能据此认定当前环境必需。[Vitest 配置](https://github.com/vjcspy/dsh-opencode-go/blob/3f5e0550a1c5cdfedcac88445a20a4d5de9cc373/vitest.config.ts#L1-L8)
+- **图标第三重 Medium fallback 当前收益很小。** 基线已有 Regular → 14，rc.2 包同时导出 Regular 与 Medium，所以现有目标宿主不需要走第三重兜底；develop 直接引用 `IconChevronDownOutlineMedium` 的类型也是为升级开发依赖服务，不能将这段源码机械复制回旧类型基线。[fork 图标适配](https://github.com/vjcspy/dsh-opencode-go/blob/3f5e0550a1c5cdfedcac88445a20a4d5de9cc373/src/client/Section.tsx#L22-L29)
+
+最终建议：先吸收 PR #11 的单提交保护；单独提取 settings fallback 回归测试作为后续小改动；保留目前经过多代宿主验证的依赖与运行时适配。develop 的整套依赖迁移、postinstall、版本名和不完整图片历史兼容均不直接合入。
+
+
+## 已经吸收或已被当前实现覆盖的工作
+
+- **liujwcn / PR #10**：`f3acbb8` 增加 rc.1 engine/peer 范围、fixture 和测试。PR 已关闭但没有 merge commit；应按当前代码覆盖情况判断。本项目 `8590c57` 已覆盖 rc.1，还增加 rc.2 和真实 Web/Headless bundle admission 测试，因此没有缺少的 rc.1 功能。[PR #10](https://github.com/Duskriver/dsh-opencode-go/pull/10) · [当前宿主矩阵](https://github.com/Duskriver/dsh-opencode-go/blob/8590c5752189658b60240b729666f814f12b27ff/tests/host-compatibility.spec.ts)
+- **RaulLazaro / PR #6**：对 deepseek、zai、qwen、qwen-chat-template 设置默认 effort，优先 high，否则最高非 off 档位。提交 `f4c919f` 已在 main 历史中；主线合并时还修正原代码回退选成最低档位的问题。当前的默认与显式档位验证已经覆盖各代宿主。[PR #6](https://github.com/Duskriver/dsh-opencode-go/pull/6) · [修正提交](https://github.com/Duskriver/dsh-opencode-go/commit/c371872) · [当前 adapter](https://github.com/Duskriver/dsh-opencode-go/blob/8590c5752189658b60240b729666f814f12b27ff/src/adapter.ts#L196)
+- **xwxYa / PR #5**：针对响应头缺失而收到原始 gzip/br/deflate 字节时 JSON 解析失败，加入安全读取/解压路径。PR 已合，分支 tip `13c3436` 是 main 祖先。当前主线改为显式请求 `accept-encoding: identity`，共享有大小上限的 JSON reader，并处理瞬时连接重置；旧手动解压猜测逻辑已被移除，不应再次搬回。[PR #5](https://github.com/Duskriver/dsh-opencode-go/pull/5) · [当前 JSON reader](https://github.com/Duskriver/dsh-opencode-go/blob/8590c5752189658b60240b729666f814f12b27ff/src/json-response.ts) · [主线验证记录](https://github.com/Duskriver/dsh-opencode-go/blob/8590c5752189658b60240b729666f814f12b27ff/docs/verification.md)
+- **nam278 / PR #3**：模型容量覆盖、搜索和重置 UI、保存/放弃流程已通过 `9d5cea7` 整合并保留贡献者署名。整合实现进一步限制显式输出预算、保留原始目录值和缓存、支持继承配置的 null 重置、避免异步混用配置；再 cherry-pick 原始版本会重复或削弱已有行为。[PR #3 关闭说明](https://github.com/Duskriver/dsh-opencode-go/pull/3#issuecomment-5774872925) · [整合提交](https://github.com/Duskriver/dsh-opencode-go/commit/9d5cea7f287e636283123b5abad1889fe6ec0797) · [容量回归测试](https://github.com/Duskriver/dsh-opencode-go/blob/8590c5752189658b60240b729666f814f12b27ff/tests/model-limits.spec.ts)
+- **OHeroJ**：唯一公开分支 `main` 指向 `acefef5`，是当前 main 的祖先，独有提交 0，落后 22 个提交；没有额外实现可吸收。[固定快照](https://github.com/OHeroJ/dsh-opencode-go/tree/acefef59422bde84b1b2cedc58680d86e262613e)
+
+## 本次验证与范围
+
+- GitHub API 列出 8 个 fork / 14 个分支；在隔离 Git 仓库比较固定提交的祖先关系、独有提交和 diff，未更改当前仓库 remotes 或分支。
+- 当前 main 实际执行 `npm test`：Host/Client 类型检查、构建成功，**22 个测试文件、301 个测试通过**。仍有宿主 UI 包缺少 source map 的已有警告。
+- PR #11 在临时副本执行定向测试：基线 **22/22**，补丁后 **25/25**；Host/Client `tsc --noEmit` 均通过。未声称此次重跑了该 PR 的完整 304 项套件。
+- Guojing6 的 `7f699a4` 通过 `git apply --check`；本次没有复测作者代理网络的 13.7 秒下载，也未执行该 fork 的完整测试套件。
+- x6nux 的降级图片标记差异已做转换层运行对照；没有验证真实历史文件迁移、Windows UI 或付费模型请求。
+
+## 分支快照清单
+
+所有 ahead/behind 均相对固定上游 `8590c5752189658b60240b729666f814f12b27ff`，ahead 是 fork 独有提交数。
+
+| 仓库 | 分支 | Tip | ahead / behind |
+| --- | --- | --- | --- |
+| liujwcn | main | `f3acbb8f736809e1bd8e751bf03bb77972a71d4c` | 1 / 1 |
+| Guojing6 | main | `f65a04bd8b8e38e4edb1ff7474b3ad946ed3b271` | 0 / 1 |
+| Guojing6 | feat/dsh-0.1.7-rc1-host-drift | `7f699a4e5b91792fe5e72951a1229639a775bf2f` | 3 / 1 |
+| RaulLazaro | main | `7c2c6364b175deb0a58b22bdb5cea9887545a571` | 0 / 7 |
+| RaulLazaro | fix/default-reasoning-effort | `f4c919f60577213cf472e0ad556ba05d5f895863` | 0 / 6 |
+| xwxYa | main | `6bbe0b3f1df95506376cdda6577db91bd7e18e80` | 0 / 12 |
+| xwxYa | fix/handle-undecoded-compressed-json | `13c343641000b5e4a41e213db17fc8ce6d0585ce` | 0 / 8 |
+| OHeroJ | main | `acefef59422bde84b1b2cedc58680d86e262613e` | 0 / 22 |
+| nam278 | main | `293f01941c3fcde4e3cb3fced87a38f9c813e622` | 1 / 22 |
+| nam278 | feat/model-limits-ui | `293f01941c3fcde4e3cb3fced87a38f9c813e622` | 1 / 22 |
+| x6nux | main | `0d6e9af74bc654358197f5f5dd323a2e8c7b39ed` | 1 / 26 |
+| vjcspy | master | `8590c5752189658b60240b729666f814f12b27ff` | 0 / 0 |
+| vjcspy | develop | `3f5e0550a1c5cdfedcac88445a20a4d5de9cc373` | 6 / 0 |
+| vjcspy | feat/history-guards | `57646f55c57b7291b783ccf80f47acf6bc64e39b` | 1 / 0 |
+

package/docs/independent-package.md

@@ -8,8 +8,8 @@ The package's bundle keeps the configuration entry `id: opencode-go` so existing
 
 Published `@deepseek-ai/dsh-llm-pi-ai` versions `0.1.5-rc.2` and `0.1.6-alpha.1` do not export `./conversion`. This package therefore carries the request-history, stream, and replay conversion modules under `src/conversion`, with the upstream MIT license. It does not import unpublished files or bundle the whole adapter. Protocol transport remains implemented by pi-ai. Conversion maintenance is now this project's responsibility; a future public conversion library can replace these modules once published and tested.
 
-The build uses esbuild and lightningcss directly. Node imports stay external; the browser factory follows DSH's `window.__ModuleLoader__.load` format, embeds CSS Modules, and allows only the declared platform module imports. A package-level builder is sufficient for this single external plugin; extracting a general DSH build-tool package would require a separate release and is not a prerequisite for installation.
+The build uses esbuild and lightningcss, with Rollup to flatten the exported SDK declarations. The host bundles the required pi-ai implementation and only the OpenCode Go model catalog. DSH services, Undici, OpenAI and Anthropic SDKs stay external; DSH class identities remain shared. The browser factory follows DSH's `window.__ModuleLoader__.load` format, embeds CSS Modules, and allows only the declared platform module imports. A package-level builder is sufficient for this single external plugin; extracting a general DSH build-tool package would require a separate release and is not a prerequisite for installation.
 
-Multi-version host fixtures have independent manifests and lockfiles, outside the root npm dependency graph. Package installation builds only the plugin. Compatibility verification installs one generated tarball into isolated consumers and uses their ordinary module resolution; it does not substitute selected host modules into the root process. See [development and verification](development.md).
+Multi-version host fixtures have independent manifests and lockfiles, outside the root npm dependency graph. Consumer installation uses prebuilt artifacts and does not run a plugin build. Compatibility verification installs one generated tarball into isolated consumers and uses their ordinary module resolution; it does not substitute selected host modules into the root process. See [development and verification](development.md).
 
 The initial source derives from the user's working copy of DeepSeek Harness on branch `oh-my-dsh`, whose HEAD was `2c8555b323f3b49eac743bafd527f9f3238bf548`, including the uncommitted OpenCode Go settings changes present when this project was created. Runtime conversion modules retain their published behavior. The original checkout is unchanged by this extraction.