dsh-plugin-effort-declare 0.1.0 → 0.1.2

package/CONTRIBUTING.en.md

@@ -17,6 +17,8 @@ Write `llm-pi-ai` settings only:
 - No fork of the official Models page
 - No parallel effort table
 - No per-model `reasoningEfforts` in the bundle layer (settings dict merge has no delete semantics)
+- Do not auto-write efforts onto undeclared models at Host start (dict merge cannot delete; it would mutate models the user never saved)
+- Do not hook `agent/request` to fill a default effort for subagents
 - Do not set route-level `reasoning` to `high`
 
 Any new model-visible input must land in a session-log-rebuildable mechanism. This plugin does not inject prompt text.
@@ -38,7 +40,7 @@ pnpm build
 
 Before sending a change, say whether it is a bugfix, UI improvement, or an alignment with a newer DSH / pi-ai schema. Update zh and en docs together. The root README and [INSTALL.en.md](./INSTALL.en.md) are for users; this file and the READMEs under `src/` and `tests/` are for people changing code.
 
-Canonical level names and `thinkingFormat` enums come from the installed `llm-pi-ai` schema / catalog. The repo keeps a fallback whitelist pinned by tests; if the schema drifts, update the tests first, then the UI.
+Canonical level names and `thinkingFormat` enums come from the installed `llm-pi-ai` schema / catalog. The live `thinkingFormat` schema contract is [`tests/fixtures/pi-ai-thinking-format-union.ts`](./tests/fixtures/pi-ai-thinking-format-union.ts). When upgrading DSH, refresh that fixture from `dsh --dump-config` or the settings describe schema, then update `src/core/catalog.ts` and UI copy. Do not value-import `@deepseek-ai/dsh-llm-pi-ai` into the client bundle. Effort keys stay a locally pinned whitelist; if the schema drifts, change the fixture / tests first. Do not offer that list as writable dropdown choices.
 
 ## Publishing to npm
 
@@ -52,6 +54,8 @@ pnpm publish
 
 `pnpm publish` fails on an unclean Git tree. Commit first (and preferably push). Do not pass `--no-git-checks`.
 
+After publish, users update with `dsh plugin --profile web update dsh-plugin-effort-declare` or `add dsh-plugin-effort-declare@latest`. Authors do not implement an update command; official `dsh plugin` forwards the rest of the line to pnpm.
+
 ## Security
 
 Do not paste API keys or `.credentials.yaml` values into logs, screenshots, docs, or issues.

package/CONTRIBUTING.md

@@ -17,6 +17,8 @@
 - 不要 fork 官方模型页
 - 不要平行再存一份档位表
 - 不要在 bundle 层预置 per-model `reasoningEfforts`（settings 字典合并没有删除语义）
+- 不要在 Host 启动时给未声明的模型自动写入档位（字典合并删不掉，会改用户没保存过的模型）
+- 不要挂 `agent/request` 给 subagent 填默认档
 - 不要把路由级 `reasoning` 写成 `high`
 
 新增任何模型可见输入，必须走会话日志可重建的机制。本插件不向模型注入提示词。
@@ -38,7 +40,7 @@ pnpm build
 
 提交前请说明改动是修 bug、增强 UI，还是对齐新的 DSH / pi-ai schema。中英文档一起改。根 README 和 [INSTALL.md](./INSTALL.md) 面向使用者；本文件与 `src/`、`tests/` 的 README 面向改代码的人。
 
-上游档位名与 `thinkingFormat` 枚举以 DSH 安装里 `llm-pi-ai` 的 schema / catalog 为准。仓库内有一份回退白名单，并由测试钉住；schema 漂移时应先改测试再改 UI。
+上游档位名与 `thinkingFormat` 枚举以 DSH 安装里 `llm-pi-ai` 的 schema / catalog 为准。`thinkingFormat` 的现场 schema 契约在 [`tests/fixtures/pi-ai-thinking-format-union.ts`](./tests/fixtures/pi-ai-thinking-format-union.ts)。升 DSH 时用 `dsh --dump-config` 或设置 describe 的 schema 更新该 fixture，再改 `src/core/catalog.ts` 与 UI。不要把 `@deepseek-ai/dsh-llm-pi-ai` 打进 client bundle。档位键仍由测试钉本地白名单；schema 漂移时应先改 fixture / 测试再改 UI。不要把这份名单当作可写入下拉选项。
 
 ## 发布到 npm
 
@@ -52,6 +54,8 @@ pnpm publish
 
 `pnpm publish` 在 Git 有未提交改动时会失败。应先 commit（建议再 push），不要用 `--no-git-checks` 绕过。
 
+发布后用户用 `dsh plugin --profile web update dsh-plugin-effort-declare` 或 `add dsh-plugin-effort-declare@latest` 更新。作者无需在插件里实现更新命令；官方 `dsh plugin` 会把参数转给 pnpm。
+
 ## 安全
 
 不要在日志、截图、文档或 issue 中粘贴 API 密钥或 `.credentials.yaml` 的值。

package/INSTALL.en.md

@@ -9,14 +9,18 @@
 
 Back to the [README](./README.en.md). Requires DeepSeek Harness **0.1.0-rc.8 or newer**. Do not use `npm install`; use `dsh plugin` below.
 
-## Desktop users: do this first
+## Third-party DSH: set DSH_HOME first
 
-`dsh plugin` installs into the **current** `DSH_HOME`. If unset, that is `.dsh` in your user folder — **not** Desktop’s data directory.
+`dsh plugin` installs into the **current** `DSH_HOME`. If unset, that is `.dsh` in your user folder. Third-party distributions often use a different home; point it at the home your DSH actually uses.
 
-PowerShell:
+```bash
+# Linux / macOS
+export DSH_HOME=/path/to/your/dsh-home
+```
 
 ```powershell
-$env:DSH_HOME = "$env:APPDATA\io.github.hairyf.deepseek-harness-desktop\data\dsh"
+# Windows PowerShell
+$env:DSH_HOME = "X:\path\to\your\dsh-home"
 ```
 
 Set this before the install command. The profile name is usually `web`.
@@ -35,6 +39,32 @@ dsh --profile web --dump-config
 
 The output should mention `dsh-plugin-effort-declare`.
 
+## Update
+
+The plugin is published to npm. Updates also go through `dsh plugin` (the official CLI forwards the rest of the line to pnpm). Do not use `npm update`.
+
+Third-party DSH still needs `DSH_HOME` set first, same as install.
+
+Already installed from npm, upgrade to the newest version in the existing semver range:
+
+```bash
+dsh plugin --profile web update dsh-plugin-effort-declare
+```
+
+Latest release, including rewriting the dependency range:
+
+```bash
+dsh plugin --profile web add dsh-plugin-effort-declare@latest
+```
+
+Then restart DSH. Use `dsh --profile web --dump-config` to confirm the layer is still present.
+
+Installed from GitHub: run `add` again, or pin a commit:
+
+```bash
+dsh plugin --profile web add github:zimodzh/dsh-plugin-effort-declare
+```
+
 ## Other methods
 
 GitHub:
@@ -53,7 +83,7 @@ dsh plugin --profile web add file:/absolute/path/to/dsh-plugin-effort-declare
 
 ## After install
 
-Restart DSH (on Desktop, restart its backend). Open **Settings → Reasoning efforts**. Add a custom provider on the Models page first; otherwise this page has nothing to edit.
+Restart DSH. Open **Settings → Reasoning efforts**. Add a custom provider on the Models page first; otherwise this page has nothing to edit.
 
 ## Uninstall
 

package/INSTALL.md

@@ -9,14 +9,18 @@
 
 回到 [README](./README.md)。需要 DeepSeek Harness **0.1.0-rc.8 或更新**。不要用 `npm install`，必须用下面的 `dsh plugin` 命令。
 
-## Desktop 用户请先做这一步
+## 第三方 DSH：先设置 DSH_HOME
 
-`dsh plugin` 会装进**当前** `DSH_HOME`。没设置时默认是用户目录下的 `.dsh`，**不是** Desktop 自己的数据目录。
+`dsh plugin` 会装进**当前** `DSH_HOME`。没设置时默认是用户目录下的 `.dsh`。第三方发行版的数据目录往往不是这条路径，需要改成你这份 DSH 实际使用的 home。
 
-PowerShell：
+```bash
+# Linux / macOS
+export DSH_HOME=/path/to/your/dsh-home
+```
 
 ```powershell
-$env:DSH_HOME = "$env:APPDATA\io.github.hairyf.deepseek-harness-desktop\data\dsh"
+# Windows PowerShell
+$env:DSH_HOME = "X:\path\to\your\dsh-home"
 ```
 
 设好后再跑安装命令。配置档名称一般是 `web`。
@@ -35,6 +39,32 @@ dsh --profile web --dump-config
 
 输出里应出现 `dsh-plugin-effort-declare`。
 
+## 更新
+
+插件已发布到 npm。更新也走 `dsh plugin`（官方会把参数转给 pnpm），不要用 `npm update`。
+
+第三方 DSH 仍须先设置 `DSH_HOME`，与安装相同。
+
+已从 npm 安装过，升级到 semver 范围内的新版本：
+
+```bash
+dsh plugin --profile web update dsh-plugin-effort-declare
+```
+
+要最新正式版（含改依赖范围）：
+
+```bash
+dsh plugin --profile web add dsh-plugin-effort-declare@latest
+```
+
+然后重启 DSH。可用 `dsh --profile web --dump-config` 确认层还在。
+
+从 GitHub 装的：再执行一次下面的命令，或使用带 commit 的规格：
+
+```bash
+dsh plugin --profile web add github:zimodzh/dsh-plugin-effort-declare
+```
+
 ## 其他方式
 
 GitHub：
@@ -53,7 +83,7 @@ dsh plugin --profile web add file:/绝对路径/dsh-plugin-effort-declare
 
 ## 装完之后
 
-重启 DSH（Desktop 请重启其后端）。打开 **设置 → 推理档位**。先在「模型」页添加第三方提供方，本页才会出现可编辑的条目。
+重启 DSH。打开 **设置 → 推理档位**。先在「模型」页添加第三方提供方，本页才会出现可编辑的条目。
 
 ## 卸载
 

package/README.en.md

@@ -7,13 +7,21 @@
   </samp>
 </p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/dsh-plugin-effort-declare" target="_blank" rel="noopener noreferrer"><img alt="npm" src="https://img.shields.io/npm/v/dsh-plugin-effort-declare"></a>
+  <a href="https://github.com/zimodzh/dsh-plugin-effort-declare/commits/master" target="_blank" rel="noopener noreferrer"><img alt="last commit" src="https://img.shields.io/github/last-commit/zimodzh/dsh-plugin-effort-declare"></a>
+  <a href="https://github.com/zimodzh/dsh-plugin-effort-declare" target="_blank" rel="noopener noreferrer"><img alt="repo size" src="https://img.shields.io/github/repo-size/zimodzh/dsh-plugin-effort-declare"></a>
+  <a href="./LICENSE" target="_blank" rel="noopener noreferrer"><img alt="license" src="https://img.shields.io/github/license/zimodzh/dsh-plugin-effort-declare"></a>
+  <a href="https://github.com/deepseek-ai/deepseek-harness" target="_blank" rel="noopener noreferrer"><img alt="Agent" src="https://img.shields.io/badge/Agent-Deepseek%20Harness-000000"></a>
+</p>
+
 Add reasoning-effort options to OpenAI-compatible models you added yourself, so the Effort row shows up in the composer.
 
-This is a community plugin. It is not an official DeepSeek project and is not endorsed by DeepSeek. Requires DeepSeek Harness **0.1.0-rc.8 or newer**.
+> This is a community-maintained third-party plugin. It is not an official DeepSeek project and is not endorsed by DeepSeek. Requires **DeepSeek Harness 0.1.0-rc.8** or later. Versions before **DeepSeek Harness 0.1.0-rc.8** have not been tested and are not guaranteed to work.
 
 ## Why
 
-Custom providers you add on the Models page usually have no reasoning levels, so the composer hides Effort. This plugin adds a **Reasoning efforts** page in Settings: you pick which levels a model can offer. The per-turn choice and the HTTP request still go through DSH. This plugin only writes settings, not API keys.
+Hand-added third-party providers on the Models page need a reasoning-level declaration before Effort appears in the composer. They usually do not declare it. This plugin therefore adds a **Reasoning efforts** page in Settings: you pick which levels a model can offer. The per-turn choice and the HTTP request still go through DSH. This plugin only writes settings, not API keys.
 
 - Does not change models you have not saved
 - Does not change the current or default effort
@@ -35,7 +43,13 @@ Do not use `npm install`. In a terminal:
 dsh plugin --profile web add dsh-plugin-effort-declare
 ```
 
-If you use **DeepSeek Harness Desktop**, set `DSH_HOME` first or the package lands in the wrong folder. See the [install guide](./INSTALL.en.md).
+If you use third-party DSH, you must set `DSH_HOME` first, or the package lands in another directory. See the [install guide](./INSTALL.en.md). To update an npm install:
+
+```bash
+dsh plugin --profile web update dsh-plugin-effort-declare
+```
+
+Or `add dsh-plugin-effort-declare@latest`. Details: [install guide](./INSTALL.en.md) **Update**.
 
 Restart DSH, then open **Settings → Reasoning efforts**. Add a custom provider on the Models page first. GitHub, local folder, and uninstall: [install guide](./INSTALL.en.md).
 

package/README.md

@@ -7,13 +7,21 @@
   </samp>
 </p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/dsh-plugin-effort-declare" target="_blank" rel="noopener noreferrer"><img alt="npm" src="https://img.shields.io/npm/v/dsh-plugin-effort-declare"></a>
+  <a href="https://github.com/zimodzh/dsh-plugin-effort-declare/commits/master" target="_blank" rel="noopener noreferrer"><img alt="last commit" src="https://img.shields.io/github/last-commit/zimodzh/dsh-plugin-effort-declare"></a>
+  <a href="https://github.com/zimodzh/dsh-plugin-effort-declare" target="_blank" rel="noopener noreferrer"><img alt="repo size" src="https://img.shields.io/github/repo-size/zimodzh/dsh-plugin-effort-declare"></a>
+  <a href="./LICENSE" target="_blank" rel="noopener noreferrer"><img alt="license" src="https://img.shields.io/github/license/zimodzh/dsh-plugin-effort-declare"></a>
+  <a href="https://github.com/deepseek-ai/deepseek-harness" target="_blank" rel="noopener noreferrer"><img alt="Agent" src="https://img.shields.io/badge/Agent-Deepseek%20Harness-000000"></a>
+</p>
+
 给自己添加的 OpenAI 兼容模型补上「推理强度」选项，对话里的 Effort 行就会出现。
 
-这是社区插件，不是 DeepSeek 官方项目，也未获官方背书。需要 DeepSeek Harness **0.1.0-rc.8 或更新**。
+> 这是社区维护的第三方插件，不是 DeepSeek 官方项目，也未获官方背书。需要 **DeepSeek Harness 0.1.0-rc.8** 及以上， **DeepSeek Harness 0.1.0-rc.8** 之前的版本没测试过，不保证可用。
 
 ## 它解决什么
 
-你在「模型」页手工加的第三方接口，通常没有推理档位，所以对话里看不到 Effort。装上本插件后，设置里会多一页 **推理档位**：勾选这个模型能提供哪些档。对话里怎么选、请求怎么发给接口，仍由 DSH 处理。本插件只改设置，不改密钥。
+在「模型」页手工加的第三方供应商，需要先声明能选哪些推理档，对话里才会出现 Effort。但通常它们不会声明。所以本插件在设置里加一页 **推理档位**：勾选这个模型能提供哪些档位。对话里怎么选、请求怎么发给接口，仍由 DSH 处理。本插件只改设置，不改密钥。
 
 - 不会自动改你没保存过的模型
 - 不会改你当前选中的档位，也不会改默认档位
@@ -35,7 +43,13 @@
 dsh plugin --profile web add dsh-plugin-effort-declare
 ```
 
-若使用 **DeepSeek Harness Desktop**，必须先设置 `DSH_HOME`，否则会装到另一份目录。步骤见 [安装说明](./INSTALL.md)。
+若使用第三方DSH，必须先设置 `DSH_HOME`，否则会装到另一份目录。步骤见 [安装说明](./INSTALL.md)。更新已安装的 npm 包：
+
+```bash
+dsh plugin --profile web update dsh-plugin-effort-declare
+```
+
+或 `add dsh-plugin-effort-declare@latest`。详见 [安装说明](./INSTALL.md) 的「更新」。
 
 装完后重启 DSH，打开 **设置 → 推理档位**。请先在「模型」页添加过第三方提供方。GitHub、本地文件夹和卸载也在 [安装说明](./INSTALL.md)。