dsh-strata-sync 0.0.0-stage → 0.8.1

package/docs/CAPABILITIES.md

@@ -0,0 +1,47 @@
+# Verified model capabilities
+
+Version 0.4.0 adds capability synchronization to the existing preview, backup, rollback and idle-only synchronization workflow. It does not send generation requests or alter Strata Server.
+
+## Input types
+
+The selected `/v1/models` row must explicitly report `architecture.input_modalities` as `text` or `text` plus `image`. The plugin writes the equivalent DSH model `input` array. It does not assume that a model family always has vision enabled. Missing, malformed, duplicated or unsupported modalities preserve the existing field; a new model leaves it unspecified.
+
+## Reasoning choices
+
+The optional, authenticated `GET /props?model=...` response must identify Strata in `build_info`, match the selected canonical model or one of its validated loaded aliases in `model_alias`, and return a reviewed `chat_template`. Aliases must resolve through `alias_of` to that loaded canonical text model. An alias belonging to another model is not accepted. The SHA-256 fingerprint is calculated after CRLF-to-LF normalization. Names, quantization labels, and a template merely mentioning reasoning are insufficient. Only matching fingerprints enable automatic reasoning synchronization.
+
+| Reviewed template | SHA-256 | DSH selection → template value |
+|---|---|---|
+| Qwen3.8-Flash-Next, checked on Huihui v2 UD-IQ4_XS | `12827f24b742ea4e80cdc12dbcf9622227056b9f797252a3149263d4f9aaadce` | `low → low`, `medium → medium`, `xhigh → xhigh` |
+| DeepSeek-V4.1-Flash, checked on IST-DAS 2.00 bpw and its Huihui variant | `6f9bd1f87d9dad376b4c79683934b4254396d826ae514ab0244efa904ce1d1a4` | `low → low`, `high → high`, `max → max` |
+
+Both include `off` as an explicit thinking-disabled choice. The DeepSeek template maps low/high/max to 50/75/100 internally. It does **not** accept the named `medium` level, despite the broader vocabulary accepted by Strata's API parser. Numeric 1–100 efforts are not exposed because DSH's selector uses named levels. No duplicate high/max aliases are added to Qwen.
+
+Inspection date: 2026-10-30. Qwen was read from the running server's `/props`; both DeepSeek tokenizer templates were inspected from installed packs without loading either model. This verifies template support, not model output quality. Template bytes and private configuration are not distributed with the plugin. Any changed or unreviewed template keeps existing reasoning settings, even if its filename is familiar.
+
+## Native DSH dispatch
+
+DSH's `reasoningEfforts` maps offered selector keys to wire values. Model-level `compat.thinkingFormat: chat-template` uses native `chatTemplateKwargs` placeholders:
+
+```json
+{
+  "thinking": { "$var": "thinking.enabled" },
+  "enable_thinking": { "$var": "thinking.enabled" },
+  "reasoning_effort": { "$var": "thinking.effort", "omitWhenOff": true }
+}
+```
+
+`supportsReasoningEffort: false` prevents a competing top-level effort dispatch. When off is selected, both thinking booleans are false and the effort is omitted. When enabled, the matching template value is sent alongside true. This matters for DeepSeek: an effort value by itself does not establish the template's thinking flag.
+
+The plugin merges these reserved dispatch settings into the selected model, preserving unrelated compatibility fields and custom template kwargs. It does not set the provider's default effort, rewrite existing conversations, or change the current session selection. If an explicit provider default is not among verified choices, reasoning updates are skipped with a warning; confirmed input types can still sync. Resolve such a default in DSH Models before applying reasoning synchronization. Existing sessions holding an unsupported selection should start a new conversation or choose a supported level.
+
+Metadata, capability changes and the current configuration participate in stale-preview detection. Raw `/props`, template text and server paths never cross into the plugin UI or saved public diagnostics. Optional metadata failures only skip capability fields; required model/context failures still block synchronization.
+
+## References
+
+- [Strata model metadata and props](https://github.com/Niko1221/Strata/blob/main/serve/server.py)
+- [Strata template handling and effort conversion](https://github.com/Niko1221/Strata/blob/main/serve/frontend.py)
+- [DSH custom model schema](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/llm/llm-pi-ai/src/config.ts)
+- [DSH reasoning selector and dispatch mapping](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/llm/llm-pi-ai/src/catalog.ts)
+
+The broad Strata parser vocabulary is not treated as proof of a particular model template's supported levels.

package/docs/README.zh-CN.md

@@ -0,0 +1,144 @@
+# dsh-strata-sync
+
+[English](https://github.com/ethan741205/dsh-strata-sync/blob/main/README.md) · **简体中文** · [繁體中文](https://github.com/ethan741205/dsh-strata-sync/blob/main/docs/README.zh-TW.md)
+
+让 **DeepSeek Harness（DSH）** 对齐 **Strata Server** 实际加载的模型，并在 DSH **设置 → dsh-strata-sync** 中提供操作界面。
+
+UI 支持 English、简体中文、繁體中文。自动跟随 DSH 界面语言并实时更新，不提供独立语言菜单。DSH 的 `zh` 对应简体中文，`zh-Hant`、`zh-TW`、`zh-HK`、`zh-MO` 对应繁体中文；其他语言使用英文。服务器返回的未知诊断消息保留原文，方便排查。
+
+0.8.1 的动态摘要引导会在每次支持的 Strata 摘要请求前计算长度目标，并在 DSH 原生摘要提示词后**只补充一句**。保留原提示词、输出硬上限与其他设置；设置页解释公式，并区分写作目标与输出硬上限。已有同步保护、启动行为、能力验证及备份机制保持不变。
+
+## 功能
+
+### 动态摘要引导
+
+对于支持的 Strata 路由，插件在每次 DSH 原生摘要请求前重新计算写作目标：
+
+```text
+上下文 = min(已确认的 Strata 上下文, DSH 已有模型上下文)
+目标 = floor(min(上下文 / 16,
+                 本次摘要实际 maxTokens / 2,
+                 待替换内容的估算 tokens / 2))
+```
+
+内容估算只包含这次要替换的对话片段，以及片段内已有的摘要；不包含系统提示词和工具定义。插件在每次摘要前通过只读查询核对 Strata 当前加载模型与上下文，并读取本次摘要请求的实际输出硬上限。上下文取服务器已确认值与 DSH 已有模型设置的较小值，不会因为服务器窗口较大而悄悄扩大较小的客户端预算。目标不是启动 DSH 或同步设置时固定下来的。
+
+摘要硬上限为 4,096、原文足够长时，32K 上下文对应 **2,048 tokens**，64K 对应 **2,048 tokens**；内容较短时目标会降低。**设置 → dsh-strata-sync** 显示公式与本次预览的目标上限，无法提前得知未来摘要的实际目标。
+
+插件只补充一句英文，要求模型按目标长度完成摘要、保留接续未完成工作所需的信息、整合旧摘要，并删除重复或过时细节。原生提示词、八个章节和已有请求参数保持不变。这是启发式写作目标，**不是新的输出硬上限、最佳值，也不能保证不截断**；不增加自动重试流程或额外推理请求。
+
+无法确认路由、必要信息或原生摘要格式，或无法安全估算图片／文件附件的 token 用量时，原请求不变并交给 DSH 处理。请求已取消或插件已禁用时也保留原生处理。计算目标小于 256 tokens 时不补充句子，避免给八个章节强加过小的目标；不取消原生摘要，也不以空摘要替换原文。禁用或移除插件后不再补充这句话，不会改写已保存的对话历史。
+
+### 模型能力自动同步（0.4.0）
+
+预览新增“输入类型”“推理等级”和“推理请求映射”，与 token 预算共用备份、回滚及空闲时才应用的保护。
+
+- 输入类型按服务器明确报告的 `architecture.input_modalities` 设置为文本或文本＋图片；缺少信息或格式不支持时保留原值。
+- 推理等级从 `/props?model=...` 核对 Strata 身份、模型身份及已审查的对话模板指纹，不只凭名称猜测。
+- 已验证的 Qwen3.8-Flash-Next：**off／low／medium／xhigh**；DeepSeek-V4.1-Flash：**off／low／high／max**。包含已核对的 Huihui 版本，以模板而非量化名称判定。
+- 使用 DSH 原生请求映射，同时设置是否思考及推理等级。模板未知或无法获取 props 时，保留原推理设置并显示原因。
+- 不修改提供方默认等级或当前对话选择。提供方默认值与已验证选项冲突时，跳过推理同步并提示。同步后请开启新对话。
+
+详见[能力验证与映射表](https://github.com/ethan741205/dsh-strata-sync/blob/main/docs/CAPABILITIES.md)。不新增其他插件、不修改 Strata 设置。
+
+### 已有同步功能
+
+- 读取 `/v1/models` 和可用的 `/slots`，确认文本模型的正式 ID 和引擎实际上下文，不从模型名称猜测。已确认的别名视为同一模型，图片生成端点不计入文本模型选择。
+- 更新选定 DSH 模型的上下文、输出上限，以及已启用 Agent 预设中的原生 `compaction-basic` 策略；预览会列出受影响的预设。
+- 默认使用“跟随 Strata”选择输出上限；手动覆盖放在“高级设置”。分别显示服务器原值、实际采用值与来源，也可选择让默认模型跟随服务器。
+- 自动同步默认关闭；在启动前启用后，每次 DSH 宿主进程启动、所有任务空闲时同步一次。查询途中开始任务时保留待同步状态，任务完成后补做；成功后不再定期查询。其他错误需手动重试或下次启动再试。运行期间启用会在下次启动生效；立即同步请点击“备份并同步”。
+- 应用前重新确认服务器与同一份设置版本、拒绝过期预览、备份设置；后续写入失败时回滚已完成的更改。偏好保存也会核对版本；未编辑的表单跟随最新值，已有编辑时提示冲突，避免覆盖其他窗口的更改。
+- 同步完成后保留只读结果，包含模型、预算、输出来源及备份信息，并区分已确认与保留原值的能力。
+- 沿用 DSH 现有认证，不在页面或诊断中显示密钥，不跟随 HTTP 重定向。
+
+**同步模型或预算设置后请开启新对话。** 已有对话保留原模型路由与 Agent 预设版本；插件不改写已有对话、不重启 DSH，也不增加额外推理请求。新版插件启用期间，动态摘要引导会作用于支持的摘要请求，不需要修改这些已保存设置。
+
+## 安装与使用
+
+包名为 `dsh-strata-sync`（原名 `@ethan741205/dsh-strata-sync`）；迁移时保留原设置，移除旧 scoped 插件后再安装新包，避免同时加载两份。
+
+
+如需安装已有的 npm 版本，先完成任务并完全退出 DSH Desktop，再使用官方 DSH CLI 从 npm 官方 registry 安装：
+
+```sh
+dsh plugin --profile desktop add dsh-strata-sync --registry=https://registry.npmjs.org/
+```
+
+完成后重新打开 DSH。首次安装会自动选中 bundle；已安装但禁用的 bundle 需在插件管理器重新启用。
+
+要安装**包含动态摘要引导的 0.8.1**，请使用 Node.js 22 或更新版本从此源码构建，并在最后的安装命令前完成任务、完全退出 DSH Desktop：
+
+```sh
+git clone https://github.com/ethan741205/dsh-strata-sync.git
+cd dsh-strata-sync
+npm ci
+npm test
+npm pack
+dsh plugin --profile desktop add ./dsh-strata-sync-0.8.1.tgz
+```
+
+执行最后一行前同样需要完全退出 DSH Desktop，安装完成后重新打开。在其他目录执行时，请使用安装包的绝对路径。
+
+先在 DSH 模型设置建立 Strata 提供方，再打开 **设置 → dsh-strata-sync**：
+
+1. 选择已有 Strata 提供方，点击“保存偏好”。保留“跟随 Strata”，需要手动覆盖输出上限时再展开“高级设置”。
+2. 点击“检查差异”，预览当前加载模型与建议设置。
+3. DSH 空闲时点击“备份并同步”。
+4. 如需自动同步，勾选“启动 DSH 时自动同步”并保存，下次启动生效。原有 `autoSync: true` 会沿用为启动同步。
+5. 开启新对话，使用更新后的 Agent 预设。
+
+无需把 API key 复制到此插件；认证问题请在 DSH 模型设置处理。
+
+## 兼容性
+
+基于 **DSH Desktop 0.2.1-rc.3** 开发和验证。需要标准桌面服务 `configEditor`、`connection`、`agents`、`credentials`、`llm-pi-ai`，以及包含 `compaction-basic` 的已启用 Agent 预设，或生效中的旧式全局压缩插件。仅支持 API key 或无认证的 `openai-completions` 提供方。
+
+Strata 提供方必须明确设置非空的自定义 `models` 列表。仅依赖内置模型目录，或包含非空 `modelOverrides` 的路由，会在预览时拒绝，尚未备份或写入；插件不会将目录型提供方转换为自定义列表，或混用不兼容格式。
+
+无法确认上下文、未加载文本模型、多个文本模型无法判定、slot 容量相互冲突时，会拒绝同步。别名会对应到已加载的正式模型，明确输出非文本的端点会排除；无效别名链会拒绝。目前 UI 跟随单个已加载文本模型，不提供多模型选择器。
+
+启动等待调度包含 DSH 0.2.1-rc.3 的 HMR `executing.exit` 兼容处理，避免计时器保留已完成的设置事务；所有写入仍通过 ConfigEditor 的正常队列。升级 DSH 后需重新验证此兼容处理。
+
+## 预算策略
+
+Strata 通过 `/props?model=...` 的 `default_generation_settings.params.n_predict` 提供共享 `max_tokens` 默认值，以及模型与上下文信息。这不是模型硬性上限，客户端明确指定的请求值会覆盖它。Strata **不提供 DSH 压缩策略**。以下是此插件的客户端策略，配合 DSH 0.2.1-rc.3 原生 4,096-token 上下文安全余量：
+
+```text
+普通输出 = 明确手动覆盖值，否则采用已确认的服务器正整数 n_predict
+备用输出 = min(16384, floor(上下文 × 0.30))
+压缩余量 = 4096
+摘要 maxTokens = 4096
+thresholdRatio = 0.8
+retainRatio = 0.16
+实际压缩阈值 = floor(min(上下文 × 0.8, 上下文 − 普通输出 − 4096))
+近期对话保留量 = floor((上下文 − 普通输出) × 0.16)
+```
+
+输出选择顺序：手动覆盖 → 已确认的服务器正整数值 → 自动计算。缺少值、null、`-1` 或 `0` 表示没有固定上限；无法获取或确认服务器与模型身份时，也使用备用计算并显示原因。明确但格式错误的值会拒绝同步；正数上限若使压缩空间不足，也会拒绝，不会悄悄换成其他值。UI 显示“Strata Server 默认值／手动覆盖／自动计算”。摘要上限仍是 4,096，压缩阈值与保留量按选定的普通输出上限重算。
+
+下表为没有手动覆盖或固定服务器上限时的备用计算示例：
+
+| 上下文 | 普通输出 | 摘要输出 | 压缩余量 | 压缩阈值 | 近期保留量 |
+|---|---:|---:|---:|---:|---:|
+| 32,768 | 9,830 | 4,096 | 4,096 | 18,842（57.50%） | 3,670 |
+| 65,536 | 16,384 | 4,096 | 4,096 | 45,056（68.75%） | 7,864 |
+
+自定义输出上限必须留下有效的正数压缩预算，且近期保留量须低于阈值。不支持小于 8,192 的上下文。推理选项仅在确认支持时同步；保留认证、其他提供方与其他模型策略；选定路由的保留量统一为 `retainRatio: 0.16`，避免沿用不兼容的绝对值。
+
+此策略可修正 32K 路由沿用原生 `headroomTokens: 65536` 等不适当预算。动态摘要引导根据本次摘要上限计算较短的写作目标，不会提高或降低硬上限；两项功能都**不能保证模型每次都能在输出上限内完成回答或摘要**，推理也会消耗输出 tokens。不读取或修改 Strata 的 `fit_max_tokens`；服务器设为 `false` 也不会禁用 DSH 自身的输出限制。
+
+## 备份与恢复
+
+每次应用前，将当前 `cordis.patch.yml` 备份至 profile 旁的 `backups/strata-sync/`，UI 会显示路径。备份可能包含私人提供方设置，请保留在本机，不要公开。
+
+ConfigEditor 负责单项原子写入与热加载；跨多项设置采用补偿回滚，并非数据库事务。如果同时有外部修改，可能需要依据备份手动恢复。关闭自动同步可取消尚未执行的启动同步，并禁用后续启动同步；移除插件**不会撤销已应用的模型与预算**。需要还原时，请先关闭 DSH 再恢复指定备份。
+
+## 开发与版本
+
+0.5.0 移除独立语言菜单与产品声明，改为跟随 DSH 语言及启动时单次同步。0.3.0 首次加入三语 UI，0.2.0 将 UI 移入原生设置。
+
+`src/plugin.mjs` 为宿主插件，`src/client.js` 为原生 ModuleLoader/React UI，`src/core.mjs` 负责信息读取与纯预算计算，`src/summary.mjs` 提供原生摘要请求中间件。执行 `npm test`、`npm run build`、`npm pack --dry-run` 验证。安装包只包含原创插件代码，不包含私人应用程序源码、认证或对话。
+
+自动测试覆盖信息读取、认证与重定向安全、预算、回滚、并发修改、启动等待、别名与非文本生成模型、HMR 去重、预设启用、请求映射及三语界面。动态摘要测试覆盖目标计算与原生请求整合；UI 测试确认预览上限与每次请求实际目标的区别。测试使用模拟服务，不生成模型回答，也不代表实际截断率已验证。版本与验证范围见 [VALIDATION](https://github.com/ethan741205/dsh-strata-sync/blob/main/docs/VALIDATION.md)。参考：[DSH 压缩文档](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/compaction/compaction-basic/README.md)、[Strata](https://github.com/Niko1221/Strata)。
+
+MIT 许可。

package/docs/README.zh-TW.md

@@ -0,0 +1,144 @@
+# dsh-strata-sync
+
+[English](https://github.com/ethan741205/dsh-strata-sync/blob/main/README.md) · [简体中文](https://github.com/ethan741205/dsh-strata-sync/blob/main/docs/README.zh-CN.md) · **繁體中文**
+
+讓 **DeepSeek Harness（DSH）** 對齊 **Strata Server** 實際載入的模型，並在 DSH **設定 → dsh-strata-sync** 中提供操作介面。
+
+UI 支援 English、简体中文、繁體中文。自動跟隨 DSH 介面語言並即時更新，不提供獨立語言選單。DSH 的 `zh` 對應簡體中文，`zh-Hant`、`zh-TW`、`zh-HK`、`zh-MO` 對應繁體中文；其他語言使用英文。伺服器傳回的未知診斷訊息保留原文，以利排查。
+
+0.8.1 的動態摘要引導會在每次支援的 Strata 摘要請求前計算長度目標，並在 DSH 原生摘要提示詞後**只補充一句**。保留原提示詞、輸出硬上限與其他設定；設定頁解釋公式，並區分寫作目標與輸出硬上限。既有同步保護、啟動行為、能力驗證及備份機制保持不變。
+
+## 功能
+
+### 動態摘要引導
+
+對於支援的 Strata 路由，外掛在每次 DSH 原生摘要請求前重新計算寫作目標：
+
+```text
+上下文 = min(已確認的 Strata 上下文, DSH 既有模型上下文)
+目標 = floor(min(上下文 / 16,
+                 本次摘要實際 maxTokens / 2,
+                 待替換內容的估算 tokens / 2))
+```
+
+內容估算只包含這次要替換的對話片段，以及片段內既有的摘要；不包含系統提示詞和工具定義。外掛在每次摘要前透過唯讀查詢核對 Strata 目前載入模型與上下文，並讀取本次摘要請求的實際輸出硬上限。上下文取伺服器已確認值與 DSH 既有模型設定的較小值，不會因為伺服器視窗較大而偷偷擴大較小的客戶端預算。目標不是啟動 DSH 或同步設定時固定下來的。
+
+摘要硬上限為 4,096、原文足夠長時，32K 上下文對應 **2,048 tokens**，64K 對應 **2,048 tokens**；內容較短時目標會降低。**設定 → dsh-strata-sync** 顯示公式與本次預覽的目標上限，無法提前得知未來摘要的實際目標。
+
+外掛只補充一句英文，要求模型依目標長度完成摘要、保留接續未完成工作所需的資訊、整合舊摘要，並刪除重複或過時細節。原生提示詞、八個章節和既有請求參數保持不變。這是啟發式寫作目標，**不是新的輸出硬上限、最佳值，也不能保證不截斷**；不增加自動重試流程或額外推論請求。
+
+無法確認路由、必要資訊或原生摘要格式，或無法安全估算圖片／檔案附件的 token 用量時，原請求不變並交由 DSH 處理。請求已取消或外掛已停用時也保留原生處理。計算目標小於 256 tokens 時不補充句子，避免給八個章節強加過小的目標；不取消原生摘要，也不以空摘要替換原文。停用或移除外掛後不再補充這句話，不會改寫已儲存的對話歷史。
+
+### 模型能力自動同步（0.4.0）
+
+預覽新增「輸入類型」、「推理等級」和「推理請求對應」，與 token 預算共用備份、回復及閒置才套用的保護。
+
+- 輸入類型依伺服器明確回報的 `architecture.input_modalities` 設定為文字或文字＋圖片；缺少資訊或格式不支援時保留原值。
+- 推理等級從 `/props?model=...` 核對 Strata 身分、模型身分及已審查的對話範本指紋，不單憑名稱猜測。
+- 已驗證的 Qwen3.8-Flash-Next：**off／low／medium／xhigh**；DeepSeek-V4.1-Flash：**off／low／high／max**。包含已核對的 Huihui 版本，以範本而非量化名稱判定。
+- 使用 DSH 原生請求對應，同時設定是否思考及推理等級。範本未知或無法取得 props 時，保留原推理設定並顯示原因。
+- 不修改供應者預設等級或目前對話選擇。供應者預設值與已驗證選項衝突時，跳過推理同步並提示。同步後請開新對話。
+
+詳見[能力驗證與對應表](https://github.com/ethan741205/dsh-strata-sync/blob/main/docs/CAPABILITIES.md)。不新增其他外掛、不修改 Strata 設定。
+
+### 既有同步功能
+
+- 讀取 `/v1/models` 與可用的 `/slots`，確認文字模型的正式 ID 和引擎實際上下文，不從模型名稱猜測。已確認的別名視為同一模型，圖片生成端點不列入文字模型選擇。
+- 更新選定 DSH 模型的上下文、輸出上限，以及已啟用 Agent 範本中的原生 `compaction-basic` 策略；預覽會列出受影響的範本。
+- 預設使用「跟隨 Strata」選擇輸出上限；手動覆寫放在「進階設定」。分開顯示伺服器原值、實際採用值與來源，也可選擇讓預設模型跟隨伺服器。
+- 自動同步預設關閉；在啟動前啟用後，每次 DSH 宿主程序啟動、所有工作閒置時同步一次。查詢途中開始工作時保留待同步狀態，工作完成後補做；成功後不再定期查詢。其他錯誤需手動重試或下次啟動再試。執行期間啟用會在下次啟動生效；立即同步請按「備份並同步」。
+- 套用前重新確認伺服器與同一份設定版本、拒絕過期預覽、備份設定；後續寫入失敗時回復已完成的變更。偏好儲存也會核對版本；未編輯的表單跟隨最新值，已有編輯時提示衝突，避免覆蓋其他視窗的變更。
+- 同步完成後保留唯讀結果，包含模型、預算、輸出來源及備份資訊，並區分已確認與保留原值的能力。
+- 沿用 DSH 現有認證，不在頁面或診斷中顯示金鑰，不跟隨 HTTP 重新導向。
+
+**同步模型或預算設定後請開新對話。** 既有對話保留原模型路由與 Agent 範本版本；外掛不重寫既有對話、不重啟 DSH，也不增加額外推論請求。新版外掛啟用期間，動態摘要引導會作用於支援的摘要請求，不需要修改這些已儲存設定。
+
+## 安裝與使用
+
+套件名稱為 `dsh-strata-sync`（原名 `@ethan741205/dsh-strata-sync`）；遷移時保留原設定，移除舊 scoped 插件後再安裝新套件，避免同時載入兩份。
+
+
+若要安裝既有的 npm 版本，先完成工作並完全結束 DSH Desktop，再使用官方 DSH CLI 從 npm 官方 registry 安裝：
+
+```sh
+dsh plugin --profile desktop add dsh-strata-sync --registry=https://registry.npmjs.org/
+```
+
+完成後重新開啟 DSH。首次安裝會自動選取 bundle；已安裝但停用的 bundle 需在外掛管理員重新啟用。
+
+要安裝**包含動態摘要引導的 0.8.1**，請使用 Node.js 22 或更新版本從此原始碼建置，並在最後的安裝命令前完成工作、完全結束 DSH Desktop：
+
+```sh
+git clone https://github.com/ethan741205/dsh-strata-sync.git
+cd dsh-strata-sync
+npm ci
+npm test
+npm pack
+dsh plugin --profile desktop add ./dsh-strata-sync-0.8.1.tgz
+```
+
+執行最後一行前同樣需要完全結束 DSH Desktop，安裝完成後重新開啟。在其他目錄執行時，請使用套件的絕對路徑。
+
+先在 DSH 模型設定建立 Strata 供應者，再開啟 **設定 → dsh-strata-sync**：
+
+1. 選擇既有 Strata 供應者，按「儲存偏好」。保留「跟隨 Strata」，需要手動覆寫輸出上限時再展開「進階設定」。
+2. 按「檢查差異」，預覽目前載入模型與建議設定。
+3. DSH 閒置時按「備份並同步」。
+4. 如需自動同步，勾選「啟動 DSH 時自動同步」並儲存，下次啟動生效。原有 `autoSync: true` 會沿用為啟動同步。
+5. 開啟新對話，使用更新後的 Agent 範本。
+
+不需要把 API key 複製到此外掛；認證問題請在 DSH 模型設定處理。
+
+## 相容性
+
+以 **DSH Desktop 0.2.1-rc.3** 開發及驗證。需要標準桌面服務 `configEditor`、`connection`、`agents`、`credentials`、`llm-pi-ai`，以及含 `compaction-basic` 的已啟用 Agent 範本，或作用中的舊式全域壓縮外掛。僅支援 API key 或無認證的 `openai-completions` 供應者。
+
+Strata 供應者必須明確設定非空的自訂 `models` 清單。僅依賴內建模型目錄，或含非空 `modelOverrides` 的路由，會在預覽時拒絕，尚未備份或寫入；外掛不會將目錄型供應者轉換成自訂清單，或混用不相容格式。
+
+無法確認上下文、未載入文字模型、多個文字模型無法判定、slot 容量互相衝突時，會拒絕同步。別名會對應至已載入的正式模型，明確輸出非文字的端點會排除；無效別名鏈會拒絕。目前 UI 跟隨單一已載入文字模型，不提供多模型選擇器。
+
+啟動等待排程含 DSH 0.2.1-rc.3 的 HMR `executing.exit` 相容處理，避免計時器保留已完成的設定交易；所有寫入仍透過 ConfigEditor 的正常佇列。升級 DSH 後需重新驗證此相容處理。
+
+## 預算策略
+
+Strata 透過 `/props?model=...` 的 `default_generation_settings.params.n_predict` 提供共用 `max_tokens` 預設值，以及模型與上下文資訊。這不是模型硬性上限，客戶端明確指定的請求值會覆寫它。Strata **不提供 DSH 壓縮策略**。下列是此外掛的用戶端策略，配合 DSH 0.2.1-rc.3 原生 4,096-token 上下文安全餘裕：
+
+```text
+一般輸出 = 明確手動覆寫值，否則採用已確認的伺服器正整數 n_predict
+備用輸出 = min(16384, floor(上下文 × 0.30))
+壓縮餘裕 = 4096
+摘要 maxTokens = 4096
+thresholdRatio = 0.8
+retainRatio = 0.16
+實際壓縮門檻 = floor(min(上下文 × 0.8, 上下文 − 一般輸出 − 4096))
+近期對話保留量 = floor((上下文 − 一般輸出) × 0.16)
+```
+
+輸出選擇順序：手動覆寫 → 已確認的伺服器正整數值 → 自動計算。缺少值、null、`-1` 或 `0` 代表沒有固定上限；無法取得或確認伺服器與模型身分時，也使用備用計算並顯示原因。明確但格式錯誤的值會拒絕同步；正數上限若使壓縮空間不足，也會拒絕，不會偷偷換成別的值。UI 顯示「Strata Server 預設值／手動覆寫／自動計算」。摘要上限仍是 4,096，壓縮門檻與保留量依選定的一般輸出上限重算。
+
+下表為沒有手動覆寫或固定伺服器上限時的備用計算範例：
+
+| 上下文 | 一般輸出 | 摘要輸出 | 壓縮餘裕 | 壓縮門檻 | 近期保留量 |
+|---|---:|---:|---:|---:|---:|
+| 32,768 | 9,830 | 4,096 | 4,096 | 18,842（57.50%） | 3,670 |
+| 65,536 | 16,384 | 4,096 | 4,096 | 45,056（68.75%） | 7,864 |
+
+自訂輸出上限必須保留有效的正數壓縮預算，且近期保留量須低於門檻。不支援小於 8,192 的上下文。推理選項僅於確認支援時同步；保留認證、其他供應者與其他模型策略；選定路由的保留量統一為 `retainRatio: 0.16`，以免沿用不相容的絕對值。
+
+此策略可修正 32K 路由沿用原生 `headroomTokens: 65536` 等不適當預算。動態摘要引導依本次摘要上限計算較短的寫作目標，不會提高或降低硬上限；兩項功能都**不能保證模型每次都能在輸出上限內完成回答或摘要**，推理也會消耗輸出 tokens。不讀取或修改 Strata 的 `fit_max_tokens`；伺服器設為 `false` 也不會停用 DSH 自身的輸出限制。
+
+## 備份與復原
+
+每次套用前，將目前 `cordis.patch.yml` 備份至 profile 旁的 `backups/strata-sync/`，UI 會顯示路徑。備份可能包含私人供應者設定，請留在本機，不要公開。
+
+ConfigEditor 負責個別原子寫入與熱載入；跨多項設定採補償回復，並非資料庫交易。若同時有外部修改，可能需要依備份手動復原。關閉自動同步可取消尚未執行的啟動同步，並停用後續啟動同步；移除外掛**不會撤銷已套用的模型與預算**。需要還原時，請先關閉 DSH 再恢復指定備份。
+
+## 開發與版本
+
+0.5.0 移除獨立語言選單與產品聲明，改為跟隨 DSH 語言及啟動時單次同步。0.3.0 首次加入三語 UI，0.2.0 將 UI 移入原生設定。
+
+`src/plugin.mjs` 為宿主外掛，`src/client.js` 為原生 ModuleLoader/React UI，`src/core.mjs` 負責資訊讀取與純預算計算，`src/summary.mjs` 提供原生摘要請求中介層。執行 `npm test`、`npm run build`、`npm pack --dry-run` 驗證。套件只包含原創外掛程式，不包含私人應用程式原始碼、認證或對話。
+
+自動測試涵蓋資訊讀取、認證與重新導向安全、預算、回復、並行修改、啟動等待、別名與非文字生成模型、HMR 去重、範本啟用、請求對應及三語介面。動態摘要測試涵蓋目標計算與原生請求整合；UI 測試確認預覽上限與每次請求實際目標的區別。測試使用模擬服務，不產生模型回答，也不代表實際截斷率已驗證。版本與驗證範圍見 [VALIDATION](https://github.com/ethan741205/dsh-strata-sync/blob/main/docs/VALIDATION.md)。參考：[DSH 壓縮文件](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/compaction/compaction-basic/README.md)、[Strata](https://github.com/Niko1221/Strata)。
+
+MIT 授權。

package/docs/VALIDATION.md

@@ -0,0 +1,122 @@
+# Validation
+
+Validation date: 2026-10-30 (Asia/Taipei).
+
+## Package rename and target ratio 0.8.1
+
+- Package identity, native bundle and client module now use `dsh-strata-sync`; the GitHub repository is unchanged. Existing scoped installations must be migrated, not loaded alongside the renamed plugin.
+- The context contribution to the target changes from `/ 32` to `/ 16`. Summary-cap and selected-source bounds stay at `/ 2`; with a 4,096 summary cap, sufficiently long sources at both 32K and 64K now target 2,048 tokens. Other model and compaction settings are unchanged.
+- Necessary verification consists of the 86 affected summary, plugin and UI tests plus the package verifier. Existing 0.8.0 native-runtime integration evidence below is historical; it was not rerun for this arithmetic/name change.
+
+## Dynamic summary guidance 0.8.0
+
+- Each supported native summary receives exactly one appended sentence. The target is `floor(min(context / 32, request.maxTokens / 2, selected-content estimate / 2))`; context is the smaller of verified server and existing client capacity. Source estimates exclude system messages, tool schemas and the summary instruction. Unknown attachment pricing and targets below 256 leave the native request unchanged.
+- The official `llm/stream` waterfall is used without replacing the compaction engine. Tests exercise actual Cordis 4.0.5 services, plugin lifecycle and waterfall dispatch, with immutable native messages, concurrent summaries, duplicate hooks, cancellation, metadata failures, early stream closure, native errors and unload. All non-message request options and the complete native prompt are preserved.
+- Plugin-level integration tests verify fresh metadata reads per summary, selected-provider/loaded-model matching, server identity, concurrent configuration edits and conservative client/server context matching. They assert zero configuration writes or backups during summary guidance. No prompt, raw tool content or credentials are recorded by the feature.
+- A separate local integration probe called the **installed DSH 0.2.1-rc.3 native `BasicCompactionEngine.summarize()`** through its shipped Cordis runtime. Synthetic text yielded 1,024 at 32K and 2,048 at 64K; its original prompt, 4,096 output cap, signals, tools and configuration remained unchanged. Unloading the hook restored the original prompt. The adapter returned synthetic chunks: **no inference service was contacted**.
+- English, Simplified Chinese and Traditional Chinese settings-render tests cover the read-only explanation, preview ceiling, unavailable values and live locale changes without adding preferences. All three READMEs describe the same behavior and limitations. Package verification checks the new runtime module is included and the authentic native-prompt test fixture is excluded from the public tarball.
+- The target is a heuristic writing instruction. These checks establish integration and preservation, **not** that a real model always meets the target, never truncates, or stops compacting frequently. Natural-work model validation remains separate. No server or model settings are changed by this feature.
+
+## npm documentation packaging 0.7.1
+
+- The 0.7.0 tarball included all three root-level README files. Using the npm 11.19.0 publish-time manifest reader (`pacote` with `fullMetadata` and `fullReadJson`) selected `README.zh-TW.md` rather than `README.md`; the result matched the registry's README filename and length.
+- Version 0.7.1 keeps only the English `README.md` at the package root. The translated READMEs move into `docs/`, along with capability and validation documentation included in the package. README links use absolute GitHub URLs so their destinations work from the npm package page as well as GitHub.
+- All three READMEs now make public-registry installation the primary path and retain source/tarball installation as an alternative. Package metadata supplies explicit documentation, issue-reporting, discovery and publishing information.
+- All **95 tests pass**, including the 94 existing tests and a new publish-artifact regression test. The verifier uses npm's package metadata reader and actual pack file list to check the chosen README, all 11 public files, documentation links, entry points, current build artifacts and publishing metadata. It runs again through `prepublishOnly` for directory publication. Dependency audit reported no known vulnerabilities.
+- This patch changes release packaging and documentation, not the synchronization runtime. The native DSH checks described under 0.7.0 remain the prior integration baseline. Registry publication and npm website rendering must be verified separately after release.
+- The observed 0.7.0 npm page showed no README even though registry metadata contained its text, matching a staged-publishing website/registry discrepancy reported in [npm/cli issue 9405](https://github.com/npm/cli/issues/9405). The root README selection issue is separately reproducible; fixing it does not by itself prove the website discrepancy is resolved.
+
+## Synchronization and settings safeguards 0.7.0
+
+- All **94 tests pass**, including 29 new regression tests. Coverage now includes changes during discovery and queued writes, revision-checked preference patches, multi-window conflicts, busy-to-idle startup deferral, startup readiness errors, alias resolution, non-text generators, unsupported catalog routes, delayed status responses and retained sync results.
+- Explicitly verified the originally reported races: changing model settings during an apply query now rejects the stale preview without overwriting the newer value; a task beginning during startup discovery leaves synchronization pending until idle.
+- The UI follows untouched preferences from other windows, reports conflicts for locally edited preferences, sends only changed fields with their baseline revision, and ignores older delayed status responses. Latest synchronization results from other windows replace older local results.
+- All three locales cover automatic/manual output controls, provenance, partial capability alignment and result summaries. No independent language selector was added.
+- Packed 0.7.0 and installed it through the official DSH plugin installer into the existing isolated DSH Desktop 0.2.1-rc.3 web profile. Startup synchronization, native preference saving/hot reload, manual 8,192-token output preview/application and result-card retention succeeded.
+- Returned the isolated profile to automatic output mode. With a fixture server default of 4,096 and context 32,768, preview and apply used 4,096 output tokens and a 24,576-token (75%) compaction threshold. The UI distinguished the server default, effective value and source, and reported a backup.
+- Native English and Simplified Chinese settings were checked through the browser. The installed host offers en/zh; Traditional Chinese is covered by automated locale/rendering tests. Reviewed the native result-card layout visually.
+- Catalog-only routes and nonempty modelOverrides are rejected during preview; support for editing catalog overrides is not claimed. Existing explicit custom model lists remain supported, including adding the newly loaded canonical model.
+- The fixture accepts metadata requests only. Production DSH, OpenCode and Strata server settings were not modified, and no inference requests were sent.
+
+## Server output defaults 0.6.0
+
+- All 65 tests pass. New coverage includes fixed server caps, absent/null and unlimited (-1/0) defaults, unavailable props, wrong model/Strata identity, invalid types, insufficient compaction space, manual precedence, stale-preview rejection after server-cap changes, applied model limits and translated output provenance.
+- Uses the existing metadata-only GET /props?model=... response, specifically default_generation_settings.params.n_predict. [Strata server source](https://github.com/Niko1221/Strata/blob/main/serve/server.py) exposes the shared max_tokens default there; it is a default rather than a hard model maximum.
+- Native isolated DSH 0.2.1-rc.3 startup sync adopted an 8,192-token fixture default at 32,768 context and saved a backup. English and Chinese previews reported the server source, a 20,480-token compaction threshold and unchanged 4,096 summary allowance.
+- Changing only the fixture cap to -1 yielded a fresh preview of 9,830 output tokens, Automatic calculation, and an 18,842-token compaction threshold. This fallback preview was not applied. Traditional Chinese provenance is covered by UI tests.
+- The updated English settings screenshot is retained locally only; it is not published with this release. Production DSH and the actual Strata server were not modified; no inference requests were sent.
+
+## DSH language and startup synchronization 0.5.0
+
+- All 58 tests pass. Regression coverage includes DSH locale subscriptions and cleanup, ignoring obsolete browser language preferences, Chinese regional variants, idle deferral, one attempt per process/profile, no repeat reads after completion/failure, HMR deduplication and manual retry availability.
+- Installed the packed 0.5.0 bundle only in the existing isolated DSH Desktop 0.2.1-rc.3 web profile. Native English and Chinese UI switches automatically update the plugin. The language selector and product disclaimer are absent. The stock host exposes en/zh; Traditional Chinese regional mapping is covered by automated tests.
+- Enabled startup sync in the UI. Saving the preference left the model at 32,768/9,830. Restarted only the isolated host; it synchronized the fixture model to 65,536/16,384 and displayed its successful sync timestamp and backup path. No Apply action or inference was used.
+- The English screenshot is a fresh native-host capture. Older screenshots are not linked from the current READMEs.
+- Production DSH and Strata configuration were not changed. Language integration uses DSH's locale service (getLocale/subscribe), described in [upstream client locale source](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/client/locale/src/client/index.ts).
+
+## Difference-table layout 0.4.1
+
+All 56 existing tests passed after the UI renderer change. In the isolated native host, a 32K-to-64K preview rendered a 528px table without horizontal overflow, with approximately 180/174/174px columns and right-aligned current/after values. English, Traditional Chinese and Simplified Chinese headers and values were checked in the live DOM. This version also renders capability arrays as chips, nested mappings as expandable details, and stacks rows when the table container is narrower than 440px. The narrow layout has not received a separate visual check. Browser screenshot capture timed out, so existing 0.4.0 screenshots are retained rather than presented as new captures. No synchronization was applied in this layout check.
+
+## Capability synchronization 0.4.0
+
+- All 56 automated tests pass. New checks cover verified template profiles, exact native efforts, unknown/malformed inputs, unverified reasoning preservation, conflicting provider defaults, localized warnings, stale capabilities, rollback and preservation of unrelated compatibility fields.
+- Eight SDK wire tests use the public pi-ai 1.1.0 SDK (matching the installed DSH package version) with mocked fetch responses. Qwen off/low/medium/xhigh and DeepSeek off/low/high/max produce the expected thinking booleans and effort values. No inference endpoint is contacted.
+- Queried the real Strata server's model and props metadata read-only: 32K Qwen with text/image input and the reviewed Qwen template. Inspected installed DeepSeek and Huihui tokenizer templates without loading them. Raw templates stay outside the repository.
+- Installed the plugin into the isolated native DSH Desktop 0.2.1-rc.3 test profile. The fixture served the reviewed Qwen and DeepSeek templates as metadata. Preview/apply succeeded for each, retained 32K/9,830 budgets, saved profile backups, and the second preview showed no changes.
+- Opened DSH's native Models editor and confirmed Qwen's context, output, text/image input and off/low/medium/xhigh entries. The DeepSeek test profile saved off/low/high/max.
+- Unknown templates are covered by preservation tests; the plugin does not infer supported efforts from a model name or claim all future templates are compatible.
+- Model inference quality, physical vision encoding and the production DSH profile were not changed or tested.
+
+## Multilingual release 0.3.0
+
+- All 38 automated tests pass, including Chinese preview labels and warnings, translated apply notices, local language persistence, invalid-language fallback and unchanged RPC write behavior on language switching.
+- Packed and installed 0.3.0 in the isolated DSH Desktop 0.2.1-rc.3 web profile.
+- Verified English, Traditional Chinese and Simplified Chinese in Settings → Strata Sync, including metadata preview and budget labels.
+- Verified the selected language remains after leaving and reopening the Settings section.
+- Captured the three native screenshots linked from the README editions.
+- The npm package includes all three README editions. Unknown backend diagnostics deliberately retain their original text.
+- No production DSH or Strata settings were changed; the native check only read metadata.
+
+## Previous version scope
+
+Version **0.2.0** moves the English interface to **Settings → Strata Sync**. Its Settings navigation, preferences, preview and synchronization were verified in the native host. The synchronization backend is unchanged from 0.1.0; the earlier full automatic-polling validation is retained below.
+
+## Completed automated checks for 0.2.0
+
+`npm test`: 35 passing tests covering discovery, native-client registration and UI behavior, budgeting, credentials, redirects, concurrent changes, lifecycle disposal, rollback, preset activation, retention inheritance and HMR timer context.
+
+The updated UI tests require registration in `settings.section`, reject the old `plugins.item` location, and verify English UI text. Repository source and documentation were also scanned for remaining Chinese text; the screenshot was replaced with the English Settings page.
+
+`npm run build` and `npm pack` produce the native host and browser entries. The package contains original plugin code only; no extracted DSH code, credentials, user conversations, server configuration or backups are distributed.
+
+## Native Settings validation for 0.2.0
+
+Using the installed DSH Desktop 0.2.1-rc.3 host with an isolated web profile and a metadata-only local fixture:
+
+- Installed version 0.2.0 using the official plugin installer.
+- Navigated through Account menu → Settings → Strata Sync; confirmed the page is a first-level Settings section.
+- Switched only the isolated test profile to English to capture an entirely English screenshot.
+- Previewed the context mismatch, used **Back up and sync**, and verified the saved context/output limits were 32,768/9,830 with a profile backup.
+- Saved and cleared an output-budget override using **Save preferences**.
+- Checked again and confirmed the settings were aligned.
+
+No production DSH settings or Strata server settings were changed.
+
+## Earlier native backend validation for 0.1.0
+
+Tested using the installed DSH Desktop 0.2.1-rc.3 host in an isolated web profile, with a local metadata-only fixture. The real user profile and running inference server were not modified.
+
+- Installed the packed bundle through the official DSH plugin installer.
+- Opened the actual DSH Plugins page and Strata Sync UI used by version 0.1.0.
+- Saved preferences, previewed a 64K-to-32K mismatch, and applied the change.
+- Confirmed the native ConfigEditor saved the model limit and the exact provider/model policy in four enabled Agent presets: `standard`, `ptc`, `minimal`, and `cordis`.
+- Confirmed the original profile was backed up, preset activation succeeded, and a second preview reported no differences.
+- Toggled auto-sync off and on in the real UI, changed the fixture to 65,536 tokens, and verified the normal 60-second poll updated the DSH model from 32,768/9,830 to 65,536/16,384 without a manual apply or application restart.
+- Verified metadata traffic uses only `GET /v1/models` and `GET /slots`; no inference endpoint is implemented by the fixture.
+
+The native test exposed two host integration details now covered by regression tests: inactive root compaction placeholders must not be edited, and a timer created during HMR reload must exit the inherited transaction context before future ConfigEditor calls.
+
+## Limits of validation
+
+This validates configuration synchronization and native UI integration, not model answer quality or completion of arbitrary long summaries. No inference benchmark was run. Existing DSH conversations retain their Agent preset revision; start a new conversation after synchronization. The production DSH profile has not been modified or restarted by this validation.

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "dsh-strata-sync",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.1",
+  "description": "Native DSH settings UI for synchronizing Strata Server models, context and compaction budgets",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./client": "./dist/client.js",
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "files": [
+    "dist",
+    "cordis.patch.yml",
+    "README.md",
+    "docs/*.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "node --test test/*.test.mjs",
+    "prepack": "npm run build",
+    "verify:package": "node scripts/verify-package.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-locale"
+      ],
+      "platform": "web"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5",
+    "@deepseek-ai/schemastery": "~3.18.5"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "1.1.0",
+    "@npmcli/package-json": "7.0.5",
+    "jsdom": "26.1.0",
+    "react": "18.3.1",
+    "react-dom": "18.3.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ethan741205/dsh-strata-sync.git"
+  },
+  "homepage": "https://github.com/ethan741205/dsh-strata-sync#readme",
+  "bugs": {
+    "url": "https://github.com/ethan741205/dsh-strata-sync/issues"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "strata",
+    "llm",
+    "plugin",
+    "model-sync"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT"
+}