dsh-plugin-git-commit-push 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ygzhang-lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,473 @@
+# dsh-plugin-git-commit-push
+
+English | [中文](README.md)
+
+DSH (DeepSeek Harness) Git commit and push plugin, one call to complete: summarize changes, automatically generate commit messages for each changed file according to Conventional Commits, ask for tagging if necessary, and then push to the Git remote repository configured for the current project.
+
+- Users can complete a commit and push with just a 0 Token through the `/git-commit-push` slash command (without going through the model, as the script automatically generates simple and clear commits according to the rules);
+- DSH can utilize the `git_commit_push` tool, requiring minimal tokens to accomplish high-quality annotations and complete a single commit and push.
+  This plugin serves as a tool-based replacement for the earlier `.agents/skills/git-commit-push` Skill. It condenses the process of running dozens of Shell scripts and reading through a pile of raw Git output, which is typically required for pure Skill work, into **1-2 tool invocations + a compact card**.
+
+Installing gives you three surfaces:
+
+| Surface       | Name                                             | Used by                                         |
+| ------------- | ------------------------------------------------ | ----------------------------------------------- |
+| Tool          | `git_commit_push` (`prepare` / `apply` / `auto`) | the model                                       |
+| Slash command | `/git-commit-push`                               | you, **with no model round-trip at all**        |
+| Skill         | `git-commit-push`                                | the model, loading the full procedure on demand |
+
+- Platforms: **Windows and macOS / Linux** (see "Platforms")
+- Requirements: DSH `>=0.2.0-rc.1 <0.3.0`, Node `>=20`, git `>=2.36`
+
+## Install
+
+### A. Plugins page (recommended)
+
+DSH → **Settings → Plugins** → type the package name into the install field:
+
+```
+dsh-plugin-git-commit-push
+```
+
+Then **restart DSH**. The same page can **enable / disable / uninstall** it — which is exactly why this
+package declares `dsh.bundle.patch` and makes itself a DSH _bundle_. Without that declaration the page
+answers every request with **"这个包没有声明组合包，不能作为插件管理"** (host code `not-bundle`).
+
+### B. Command line
+
+```sh
+dsh plugin --profile <profile> add dsh-plugin-git-commit-push     # install
+dsh plugin --profile <profile> remove dsh-plugin-git-commit-push  # uninstall
+```
+
+`<profile>` is your profile name (`web`, `headless`, a custom one). Both directions edit the profile's
+`package.json` (dependency + `dsh.profile.bundles`) and **need a DSH restart**.
+
+### C. From a checkout (development / offline)
+
+Clone the repository and use the installer to wire the checkout into a profile as a `link:` dependency:
+
+```powershell
+# Windows (default profile: desktop)
+powershell -ExecutionPolicy Bypass -File .\setup.ps1
+powershell -ExecutionPolicy Bypass -File .\setup.ps1 -Profile web
+powershell -ExecutionPolicy Bypass -File .\setup.ps1 -Uninstall
+```
+
+```bash
+# macOS / Linux
+sh setup.sh              # default profile: desktop
+sh setup.sh web          # a specific profile
+sh setup.sh web --uninstall
+```
+
+The scripts do two things (idempotent, with backups): add the checkout as a `link:` dependency and add the
+package name to `dsh.profile.bundles`, then run `pnpm install` inside the profile. **The mount row is not
+written by the scripts** — it comes from this package's own bundle patch (see "The DSH bundle contract").
+They also **remove** the mount row an older revision wrote into the profile's `cordis.patch.yml`, because
+Loader `insert` is append-only and the same id mounted twice would register the plugin twice.
+
+> Do not mix the three ways: a package should be mounted exactly once per profile.
+
+### After installing
+
+Once DSH is restarted:
+
+- the model can call `git_commit_push`, and you can type `/git-commit-push`;
+- Settings → Plugins lists this package (title "Git 提交与推送", with an icon) and can enable/disable/uninstall it;
+- the model's skill catalog contains `git-commit-push`;
+- Settings shows this plugin's **configuration form** (11 fields, applied live with no restart).
+
+## Trigger policy (read this first)
+
+**Only two situations may use it; it never fires on its own:**
+
+1. **the user typed the `/git-commit-push` slash command** — the command runs it, no model involved;
+2. **the user explicitly asked** to commit and/or push ("commit", "push", "提交", "推送").
+
+**Finishing an edit, completing a task, an almost-over session, or a user saying "save it" are NOT
+triggers.** Editing files is not a request to commit them. When in doubt, ask instead of committing.
+
+The rule is stated in three model-visible places: the `git_commit_push` tool description (the first thing
+a model reads when choosing a tool), [SKILL.md](./SKILL.md) (registered as an embedded skill at mount
+time), and the command description. The plugin cannot enforce it inside `execute` — by then the decision
+has already been made.
+
+## Is "0 tokens for commit + push" accurate?
+
+**Partly — it needs qualification.** The honest split is by path:
+
+| Path                                     | Model tokens   | Why                                                                                                                                                                                                                    |
+| ---------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **1. `/git-commit-push` slash command**  | **0 (really)** | No model request is made at all. Command discovery, execution and UI output cost no model tokens, and the result is rendered in the UI only — it never enters the transcript. This is the **only** truly 0-token path. |
+| **2. `git_commit_push(auto)` tool call** | a few          | The model has to emit the call (arguments + thinking). The plugin writes the message itself, so there is **no** second round-trip; the card is ~200 tokens. One round trip.                                            |
+| **3. `prepare` + `apply` (default)**     | ~2 round trips | Only the `prepare` card (~200 tokens) and the `apply` `message` argument enter the context — **no diff is read**.                                                                                                      |
+
+So: "the slash command costs 0 tokens" is accurate; "the tool costs 0 tokens" is **not** — the model still
+pays for each call. What the plugin saves is **comparative**: reading raw git output (thousands of tokens →
+~200) and several round trips.
+
+One **fixed cost** must also be stated: while the plugin is installed and the tool is visible to the model,
+its schema (a ~1.5 KB description plus parameters) enters **every** request — roughly **600 tokens**, paid
+even when you never commit. If you only want `/git-commit-push` and never let the model call the tool, moving
+the tool out of the model-visible surface (or `deferLoading` it) removes that cost.
+
+## Usage
+
+```
+git_commit_push({ action: "prepare" })                        # survey only, no writes
+git_commit_push({ action: "apply", message: "feat(x): …" })   # commit + push
+git_commit_push({ action: "auto" })                           # commit with the rule-generated message
+git_commit_push({ action: "apply", message: "…", tag: "v1.2.3" })
+git_commit_push({ action: "prepare", cwd: "/path/to/repo" })   # session cwd is not the repository
+```
+
+`/git-commit-push` variants (**0 tokens, no model involved**):
+`/git-commit-push`, `/git-commit-push --prepare`, `/git-commit-push --no-push`, `/git-commit-push --en`, `/git-commit-push --tag=v1.2.3`, `/git-commit-push fix login timeout`.
+
+### What the card looks like
+
+```
+🔎 **改动预览（未提交）** · `main` · 3 files · +48 / -12
+status: 1 added / 2 modified
+  added    src/foo/bar.ts +40/-0 → feat(foo): add bar component
+  modified src/foo/baz.ts +8/-10 → fix(foo): correct parseThing decision
+  deleted  src/old.ts → refactor: remove old
+tag evidence: version 1.2.3 → 1.2.4 (package.json)
+recent style: "feat(ui): add theme switch" "fix(api): correct retry decision"
+subject: `feat(foo): update bar component`
+(preview only — nothing committed, nothing pushed)
+```
+
+And after a commit:
+
+```
+✅ **Git 提交并推送成功** · `main` · `a1b2c3d`
+信息：feat(foo): 更新 bar 组件
+提交 3 个文件 · +48 / -12
+  - feat(foo): 新增 bar 组件 · src/foo/bar.ts
+  - fix(foo): 修正 parseThing 判断 · src/foo/baz.ts
+  - refactor: 移除 old · src/old.ts
+标签：v1.2.4
+推送：已推送（含标签）
+```
+
+Four outcomes are unmistakable, so a card can no longer be mistaken for "nothing happened":
+
+| First line                      | Meaning                                                               |
+| ------------------------------- | --------------------------------------------------------------------- |
+| `✅ **Git 提交并推送成功**`     | committed and pushed                                                  |
+| `✅ **Git 提交成功（未推送）**` | committed; `autoPush` is off or this call said `--no-push`            |
+| `⚠️ **已提交，但推送失败**`     | the commit is local, the push failed (reason in `说明：`)             |
+| `❌ **提交失败**`               | nothing was committed; your changes are untouched in the working tree |
+
+Other states: `ℹ️ **没有需要提交的改动**`, `⚠️ **当前目录不是 Git 仓库**` (with the candidate repositories listed),
+`❌ **未初始化 Git**`, `❌ **找不到 git**`.
+
+### Multiple files: one commit, one note per file
+
+Several files are still **one commit**, but its body carries one typed Conventional note per file instead of a single
+sentence pretending to cover all of them:
+
+```
+feat(api): 更新 decideRetry
+
+- feat(api): 更新 decideRetry · src/api/retry.ts
+- docs: 更新文档 guide · docs/guide.md
+- test(api): 新增 retry.test.ts · src/api/retry.test.ts
+```
+
+- Every note describes **that one file**: the type comes from the file itself (`docs/` → `docs:`, `*.test.ts` →
+  `test:`), the scope is its directory (dropped when it would only repeat the type, so `docs(docs)` never appears),
+  and the summary prefers a symbol the file's own diff declares (`update decideRetry`).
+- Supply only a **subject** (a single-line `message`) and the per-file notes are appended for you; supply your own
+  body (a multi-line `message`) and it is used **verbatim**, with no generated notes added.
+- A **single-file commit has no body** — its subject says it all.
+- The body names at most `maxFilesShown` files (12 by default); the rest collapse into `- …另有 N 个文件`.
+
+(Card text is localized: `defaultLanguage: "zh"` or `"en"` — including the per-file notes. The card _format_ is
+Chinese-and-English-mixed by design: the verdict line and labels are Chinese in both locales, the file notes follow
+the message language.)
+
+## Settings
+
+**Prefer DSH's own settings form.** The plugin exports a Cordis `Config` schema, so its row accepts a `config`
+mapping: DSH's settings service derives a namespace from it, the Settings page renders the fields, and
+`@deepseek-ai/dsh-config-editor` writes the choice into the active profile's `cordis.patch.yml` — on the very
+row this bundle inserts — applying it through the Loader. Every field is declared **volatile**, so a change
+does not remount the plugin and needs no DSH restart: it takes effect on the next tool call.
+
+**Three sources, highest first:**
+
+| Layer | Location                                                                                | Written by                                              |
+| ----- | --------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| 1     | the row's `config` (the profile's `cordis.patch.yml`)                                   | DSH's settings form                                     |
+| 2     | `<DSH_HOME>/git-commit-push.config.json` (default `~/.dsh/git-commit-push.config.json`) | you, by hand; the fallback for `link:`/offline installs |
+| 3     | the shipped template `git-commit-push.config.json`                                      | the package                                             |
+| —     | built-in defaults                                                                       | whatever none of the above sets                         |
+
+A missing file is not an error. A file that exists but is not valid JSON is **reported** — the result card
+gains a "配置未生效: …" line rather than silently doing nothing. Omitted keys keep their defaults.
+
+| Key                         | Default  | Meaning                                                                                | In the form |
+| --------------------------- | -------- | -------------------------------------------------------------------------------------- | ----------- |
+| `autoPush`                  | `true`   | push after a successful commit                                                         | ✅          |
+| `autoAdd`                   | `true`   | `git add -A` before committing                                                         | ✅          |
+| `tagOnVersionChange`        | `true`   | ask about a tag when a version file changed                                            | ✅          |
+| `tagOnBreaking`             | `true`   | ask when a public declaration was removed                                              | ✅          |
+| `tagOnFileCount`            | `10`     | ask when ≥ N files changed (`0` disables)                                              | ✅          |
+| `tagPrefix`                 | `"v"`    | suggested tag prefix                                                                   | ✅          |
+| `askBeforeTag`              | `true`   | `false` tags silently (the only "no question" switch)                                  | ✅          |
+| `askTimeoutMs`              | `120000` | how long the tag question waits                                                        | ✅          |
+| `defaultLanguage`           | `"zh"`   | language of the generated message (`zh`/`en`)                                          | ✅          |
+| `maxFilesShown`             | `12`     | how many paths the card lists                                                          | ✅          |
+| `pinnedIdentity.name/email` | empty    | applied per commit with `-c user.name/-c user.email`; your git config is never written | ✅          |
+
+> Where exactly the form lives depends on your DSH version (the plugins/config entry in Settings). The
+> **Settings → Plugins → Plugin list** tab is explicitly **read-only** (it lets users inspect plugins
+> _without changing their configuration_); the editable form comes from the settings service. Field
+> descriptions are Chinese, matching the default message language — DSH has no per-field localization yet.
+
+**Why a JSON file still exists**: the `Config` schema needs `@deepseek-ai/schemastery`, declared here as an
+ordinary **dependency** so an npm install brings it along. With a `link:` (source checkout) install pnpm does
+not install a link target's dependencies and the host's module resolution may not reach it either. In that
+case the plugin **still works** — it just has no form (`Config === undefined`), and the JSON file is the only
+way in. That is why the file stays, and why it outranks the shipped template.
+
+Environment: `DSH_HOME` is the DSH home (default `~/.dsh`, Windows `%USERPROFILE%\.dsh`); it also decides
+where the user settings file lives.
+
+## The `git-commit-push` skill
+
+[SKILL.md](./SKILL.md) is registered as an **embedded skill** (`ctx.skills.register(...)`) when the
+plugin mounts, so there is nothing to copy into a skills directory after an npm install. The skill name
+matches the package name (minus the `dsh-plugin-` prefix): the tool, the command, the skill and the npm
+package share one name instead of two.
+
+- To **override** it, keep a project-level skill of the same name (`.agents/skills/git-commit-push/SKILL.md`).
+  The registry ranks **project > runtime registration**, so your copy wins.
+- A host without a skill registry still works: the skill and the `/git-commit-push` command are **optional
+  capabilities** (awaited through a scoped `ctx.inject`), and losing either never affects the
+  `git_commit_push` tool.
+- **Coming from an early revision**: if you manually installed the old SKILL.md into
+  `~/.agents/skills/git-commit/`, that is a user-level skill under a _different_ name and will appear next
+  to the bundled `git-commit-push`. The package now owns that content, so deleting that directory is
+  recommended (or keep it and put your own rules there — different names, so neither shadows the other).
+
+## Safety boundary
+
+**Never**: modify `.gitignore`, write git config (including `user.name`/`user.email`), `push --force`,
+`reset --hard`, `git clean`, `checkout -- <path>`, or `commit --no-verify`.
+[lib/git.js](./lib/git.js) is the only place that talks to git and its command set is fixed — adding a
+destructive verb means changing that file first.
+
+**Handled automatically**: `push -u origin <branch>` when there is no upstream; a rejected push
+(the remote moved) retries once after `pull --rebase`; on a rebase conflict it aborts **only the rebase it
+started itself** (probing `rebase-merge`/`rebase-apply` first, so your own rebase progress is never
+discarded) and reports honestly; an existing or invalid tag name is skipped with an explanation.
+
+**Tagging is conservative**: a tag is created only with your explicit consent (or `askBeforeTag: false`).
+An explicitly passed `tag` argument is treated as an instruction and skips the question. No answerer
+available, you are not present (a delegated call), or the wait timed out — all mean **do not tag**, and the
+card tells you how to add it later with the `tag` argument.
+
+**It does not guess**: when the session directory is not a repository it reports the candidate repositories
+for you to pick with `cwd` instead of committing in one of them, and "git is not installed" is a different
+failure from "this is not a repository".
+
+## Platforms
+
+| Capability                  | Windows                                   | macOS / Linux                         |
+| --------------------------- | ----------------------------------------- | ------------------------------------- |
+| Runtime (the plugin itself) | ✅                                        | ✅ audited: no missed platform branch |
+| Installers (path C)         | `setup.ps1` (PowerShell)                  | `setup.sh` (POSIX sh)                 |
+| Uninstall                   | `setup.ps1 -Uninstall`                    | `setup.sh <profile> --uninstall`      |
+| Profile manifest edit       | both call the same `lib/profile-edit.mjs` | same                                  |
+
+Audit notes for `index.js` + `lib/*`:
+
+- the only platform branch is `DEV_NULL` (Windows `NUL` vs `/dev/null`), used solely by the **test fixture**
+  to isolate git's global config; the plugin's real git calls deliberately keep your global config
+  (credential helper, `pull.rebase`, `core.autocrlf` live there, and clearing it would change how your
+  repositories behave);
+- no hard-coded drive letters, no `C:\`, no dependency on `powershell`; modules use relative `./`
+  specifiers (safe on case-sensitive filesystems); temporary directories come from `os.tmpdir()`;
+- `setup.sh` avoids two cross-platform traps on purpose: **no `sed -i`** (BSD/macOS and GNU differ) and
+  **no `readlink -f`** (absent on macOS), using POSIX `awk` and `cd`+`pwd` instead.
+
+## Self-check
+
+No DSH required, and it never touches your repositories (tests build their own repos under the system temp
+directory and delete them):
+
+```bash
+npm test                        # = node self-test.mjs && node self-test-git.mjs
+node self-test.mjs              # pure logic + packaging/config/form/skill contracts (86 checks)
+node self-test-git.mjs          # real git: porcelain -z framing, rename attribution, version detection, end-to-end commit, per-file notes, card verdicts (24 checks)
+node capture-git-format.mjs     # prints raw git -z bytes, for diagnosing framing
+```
+
+On Windows with the runtime DSH ships:
+
+```powershell
+& "$env:USERPROFILE\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe" self-test.mjs
+```
+
+One test in `self-test-git.mjs` is **deliberately independent of the implementation**: it asks git the same
+question twice — once with `git status --porcelain -z` and once with the plain, non-NUL format — and
+requires both to describe the same set of paths. A broken parser therefore fails the test instead of
+agreeing with itself.
+
+That test has a history worth keeping: the first `lib/survey.js` imported a function from a module that did
+not export it. The ESM link error made the whole plugin graph unevaluable, so neither `git_commit_push` nor
+`/git-commit-push` registered — and the pure-logic test never touched `survey.js`. Both test files now import
+the complete module graph explicitly, and `apply()` validates the schema with `toolDefinitionProblems()`
+before registering.
+
+The last two sections of `self-test.mjs` check **packaging and runtime contracts** rather than algorithms:
+
+- the declared `dsh.bundle.patch` exists and is non-empty, inserts **exactly one** mount row (two rows mount
+  the plugin twice), uses the stable id `git-commit-push` and names this package; neither installer writes a
+  mount row of its own;
+- **the `files` whitelist covers every relative module the entry point imports** — the classic npm
+  publishing accident, where the package installs cleanly and then fails to load;
+- the `exports` subpaths, `locale/*.json` and `icon` the Plugins page reads (relative path, allowed type,
+  ≤256 KiB);
+- every DSH peer is `optional` (otherwise pnpm tries to install a host package into the user's profile),
+  plus `dsh.manifestVersion` and `engines.dsh`;
+- **the settings layers and the field table agree**: the field table, the built-in defaults and the shipped
+  template cannot drift, the UI layer (row config) beats the JSON file, `pinnedIdentity` merges per key, and
+  only a parsed value that differs from the default counts as "the user set it";
+- **the form is either published or degraded**: when `@deepseek-ai/schemastery` resolves, `Config` must be
+  built with every field volatile; when it does not, `Config` must be `undefined` and the tool must still
+  register;
+- settings precedence (user file > shipped template) and the rule that **a malformed config must be
+  reported**;
+- the skill definition parsed from SKILL.md satisfies the registry's `validateRuntimeSkill` rules, and
+  `apply()` on a mock host really registers the tool, the command and the skill.
+
+Two small readers exist for exactly the syntax this project writes (the YAML patch, the skill frontmatter):
+the package ships zero dependencies, so the test will not pull in a YAML parser to read three lines — and a
+line it cannot read fails the test instead of being ignored.
+
+## Layout
+
+```
+index.js                 plugin entry: tool definition, /git-commit-push command, skill registration, orchestration
+cordis.patch.yml         the bundle patch: the single mount row (dsh.bundle.patch points at it)
+icon.svg                 Plugins page icon (package.json "icon")
+locale/en.json           Plugins page display text (meta.title / meta.description, English)
+locale/zh.json           same, Chinese
+lib/git.js               the only git layer: fixed argv, timeouts, output caps, porcelain parsing, platform probing
+lib/analyze.js           change classification + rule-based Conventional Commits + card rendering
+lib/survey.js            one repository survey: status / numstat / log / bounded diff
+lib/config.js            settings + the field table: row config > user file > template > defaults, and reporting a broken file
+lib/schema.js            the Cordis Config (schemastery): the visual form + volatile fields, degrading gracefully when the library is unreachable
+lib/skill.js             parses SKILL.md into the runtime skill definition (frontmatter included)
+lib/profile-edit.mjs     profile manifest editor shared by both installers (idempotent, keeps unknown fields, no BOM, self-verifying)
+setup.ps1                Windows install / uninstall (path C)
+setup.sh                 macOS / Linux install / uninstall (path C)
+self-test.mjs            pure logic + packaging/config/form contracts (86 checks)
+self-test-git.mjs        real-git integration (24 checks, own temporary repository)
+capture-git-format.mjs   prints raw git -z bytes (framing diagnostics)
+e2e-check.mjs            calls run() directly, to verify the commit path without restarting DSH
+```
+
+Design trade-offs. The tool definition is a **hand-written object** instead of `defineTool(...)`; the only
+host import in the runtime is a deliberate exception — `lib/schema.js` uses `createRequire` to obtain
+`@deepseek-ai/schemastery` so the plugin can declare a `Config`, and the whole thing is wrapped in a
+`try/catch`: when it cannot be reached, `Config === undefined` (no form) and the plugin and its tool keep
+working. Every other module still imports only Node built-ins and relative paths, because this package may be
+`link:`ed from outside a profile or sit inside `node_modules`, and mounting must not fail because the host's
+module resolution does not reach it. (`@deepseek-ai/schemastery` is an ordinary `dependencies` entry, so an
+npm install brings it; a `link:` install does not install a link target's dependencies, which makes that
+degradation path real rather than theoretical.)
+
+The price is writing a **real JSON Schema by hand**: `parameters` needs `type: "object"` + `properties` +
+`required: []`, and `output.schema`'s `required` must be an **array of strings** — `defineTool`'s
+per-property `required: true` form is compiled by `defineTool` itself, and a hand-written definition
+carrying it is rejected **at registration time**, taking the whole plugin down.
+`toolDefinitionProblems()` is the regression test for that rule.
+
+`exports` carries `./package.json` and `./locale/*` besides `.`: the Plugins page resolves
+`<specifier>/package.json` and `<specifier>/locale/en.json` through Node's module resolver
+(`readPluginMeta`), and an exports map with only `.` makes both lookups fail with
+`ERR_PACKAGE_PATH_NOT_EXPORTED`, degrading the title to the bare module specifier.
+
+`peerDependencies` declares only `@deepseek-ai/dsh-tools`, marked **optional**: the peer exists so DSH's
+compatibility gate (`evaluatePluginCompatibility`, which reads `peerDependencies`) can compare the host
+version, and `optional` guarantees pnpm never downloads a host package to satisfy it. The plugin imports
+nothing from it.
+
+## The DSH bundle contract (what this package had to learn)
+
+Everything below was verified against the implementation inside the shipped `dsh` bundle
+(`packages/boot/plugin-manager`, `packages/boot/app-boot`, `packages/boot/package-manifest`,
+`packages/skill/skill`) rather than guessed.
+
+1. **A bundle is a `package.json` with `dsh.bundle.patch`** — one file path or an ordered list of paths,
+   relative to the package root. For a name selected in `dsh.profile.bundles` the launcher resolves it with
+   `bundlePatchFiles` / `bundlePatchPaths` and applies that patch as one layer. When `dsh.bundle` cannot be
+   resolved it throws `profile bundle "…" declares no dsh.bundle in its package.json` and **skips the
+   layer** (recorded in `skippedBundles`) instead of failing the boot.
+2. **The Plugins page only manages bundles.** `listBundles()` lists a selected name with no `dsh.bundle` as
+   `error.code = "not-bundle"` — the sentence the page shows. Enable/disable only change membership in
+   `dsh.profile.bundles` (the dependency stays); uninstall touches the dependency. An unselected plain
+   dependency is not listed at all.
+3. **The compatibility check only looks at `@deepseek-ai/dsh` and `@deepseek-ai/dsh-*` peers**, compares with
+   `includePrerelease`, and takes the runtime version from `dsh-app-boot`. `peerDependenciesMeta.optional`
+   does not affect it.
+4. **`dsh.manifestVersion` and `engines.dsh` are declarative only** — installers and loaders do not enforce
+   them — but they are the public author fields documented by `@deepseek-ai/dsh-package-manifest`, so this
+   package declares both.
+5. **Display metadata** comes from `readPluginMeta`, which resolves `<name>/package.json`,
+   `<name>/locale/*.json` and the `icon` field (relative path, SVG/PNG/JPEG/WebP, ≤256 KiB, must stay inside
+   the package directory) through Node; `locale/en.json` is the reference file.
+6. **Embedded skills** use `ctx.skills.register({ name, description, content, … })`: `name` must match
+   `/^[a-z0-9]+(?:-[a-z0-9]+)*$/`, `description` and `content` must be non-empty strings (re-validated on
+   load by `validateDefinition`), the registry fills in the `runtime` provider, and precedence is
+   **project > runtime > user**.
+7. **Visual configuration means exporting a `Config` schema** (schemastery, zod-style). DSH's settings
+   service (`@deepseek-ai/dsh-settings` + `@deepseek-ai/dsh-config-editor`) derives a namespace and a form for
+   entries that declare one (`SettingsNamespaceView.autoGenerate`), and writes land in that entry's `config`
+   in the profile patch; a plugin can opt out with `settings.configure({ auto: false })`. A field marked
+   `.volatile()` only commits new values and announces `loader/volatile-update` (the Loader compares with
+   `equalExceptVolatile`) — **no remount** — while an ordinary field change remounts the row. Volatile
+   placement is strict: a fixed object path, never a dict value, array item, map key or union/lazy branch
+   (`validateVolatileSchema` throws otherwise).
+8. **The settings page is not a general plugin settings UI**: `@deepseek-ai/dsh-settings` shows only volatile
+   fields of active, uniquely addressable entries, the **Plugin list** tab is read-only, and the
+   `pluginManager/*` RPCs only install/enable/disable/uninstall — so the one requirement for "visually
+   configurable" is that the plugin declares `Config` itself.
+
+Two more traps worth knowing:
+
+- Loader `insert` is append-only and does not deduplicate — the same `id` inserted twice mounts the plugin
+  twice, so there must be exactly one mount.
+- A profile's `pnpm-workspace.yaml` normally sets `autoInstallPeers: false` and `nodeLinker: hoisted`, so
+  peers are never auto-installed and an unmet one is a warning. That is the second reason this package marks
+  its peer optional.
+
+## Maintainers: publishing to npm
+
+```sh
+npm login                      # or NPM_TOKEN in CI
+npm test                       # prepublishOnly runs it too
+npm publish                    # publishConfig pins the registry to registry.npmjs.org
+```
+
+- `publishConfig.registry` is set explicitly because a machine-level `~/.npmrc` pointing at a read-only
+  mirror (npmmirror) would otherwise send `npm publish` to the wrong place.
+- Mirrors take a while to sync after a publish, so a user installing immediately may not see the new version.
+- Bump the version by SemVer; `dsh.manifestVersion` is the **manifest format** identifier and is unrelated
+  to the package version, so it does not move with it.
+- When runtime behaviour changes, update `engines.dsh` and the `@deepseek-ai/dsh-tools` peer range together —
+  they decide whether the Plugins page reports an incompatibility.
+- `@deepseek-ai/schemastery` in `dependencies` is a **real dependency** (the settings form needs it) and pnpm
+  installs it for the user. Before widening its range, check that the target DSH version still has the schema
+  API used here (`.default/.description/.min/.volatile`); otherwise the form takes the degraded path
+  (`Config === undefined` — everything still works, there is just no visual configuration).
+
+## License
+
+MIT © ygzhang-lab. See [LICENSE](./LICENSE).