@klarkxy/dsh-plugin-kit 0.3.1 → 0.3.3

package/README.md

@@ -2,73 +2,12 @@
 
 <!-- release-state-note -->
 
-The shared support package for the feature plugins in this repository: shared record types, the plugin-page model menu, host RPC registration, the official-UI style contract, and one native `llm` text call. It is a library, not a DSH bundle — adding it as a dependency gives a feature plugin the pieces it needs, not a new user-visible feature of its own.
-
 [简体中文](docs/README.zh-CN.md)
 
-## What this package is not
-
-- It is a dependency of feature plugins, not a DSH bundle: it declares no `dsh.bundle` and registers no plugin page, so installing it on its own changes nothing the user can see.
-- It never starts inference by itself, and makes no model call unless a feature asks for one.
-- It does not route models by tier, retry, time out, queue, or record usage. Each feature chooses its model on its own plugin-page row and calls the host `llm` service directly; an empty selection uses the current session model, then the host default chat model.
-
-## Entry points
-
-- `.` — the shared contract types, plus `registerHostRpc`, `callLlmText` and `resolveFeatureModel`.
-- `./contracts` — browser-safe types and constants: shared memory/knowledge records, `TaskContract` / `TaskCheckpoint`, `ModelRoute`, `RpcResult`, `CHAT_EVENTS_SLOT`, `projectIdFromCwd`.
-- `./host-rpc` — host RPC registration helper and its context type.
-- `./model-settings` — host-only model settings contributions. Register the owning plugin's read snapshot and CAS writer with `registerModelSettings` inside `ctx.effect`; the hub discovers active owners using `collectModelSettings`. Each registration has an incarnation ID, so a stale page cannot write into a replacement instance. Reads expose only model fields and revision, with an optional independent model catalog; storage and validation stay with the owner.
-- `./client-utils` — browser-safe helpers for native plugin-page seats: `selectedSessionId`, `useNativeSeat`, `useFeatureRefresh`. `react` is an optional peer.
-- `./model-settings-client` — browser-safe optional invalidation subscription using `createModelSettingsSubscriber`. Model Hub mounts the native stream descriptor once; pages own their rereads and draft conflicts. Owners call host-side `notifyModelSettingsChanged` after persistence and memory state commit.
-- `./model-menu` — plugin-page model select: catalog parsing, empty-route handling, reasoning-effort options.
-- `./llm-call` — `callLlmText` and `resolveFeatureModel` as separate exports.
-- `./official-ui` — the shared browser-side style contract: `officialUiCss(roots)`, the `--dsw-*` token allowlist, and the focus/elevation helpers.
-- `./cli-process` — run a resolved executable without a command shell, with bounded output, serialized line callbacks, deadlines and owned-process-tree cancellation. Streaming mode delivers stdout through `onLine`; it does not also retain stdout.
-- `./cli-media` — validate and stage explicit workspace/current-session media, enforce file limits, and publish native image/file attachments. Remote job authority and vendor protocols remain in each plugin; these helpers do not sandbox a vendor CLI's own file access.
-
-Plugins passing their Cordis context to `resolveFeatureModel` must declare `agents`, `sessionProjections` and `agentDefaultModel` in `inject`. These services supply the live session selection and the host default when the plugin has no saved model.
-
-## Plugin UI convention
-
-A feature plugin's browser half composes the host's own UI rather than
-restyling controls of its own. Concretely:
-
-- **Controls come from `@deepseek-ai/dsh-client-ui-primitives`** — `Button`,
-  `Input`, `Checkbox`, `Switch`, `Tag`, `Pill`, `SegmentedControl`, `Menu`,
-  `Modal`, `Tooltip`, `Toast`, `DisclosureRow`, `StateDot`, `PathLabel` and the
-  settings-form suite. The host owns their geometry, focus ring, states and
-  localisation seams, so a copy of one drifts out of style on the next theme
-  change. A native `<select>` is the single exception: the primitives ship none,
-  so keep the platform control and give it the contract's `dsh-ui-select` class.
-- **Layout, type tiers, cards, fields, banners, empty states and floating
-  surfaces come from `./official-ui`**, scoped to the plugin's own root classes
-  so two plugins can mount the same class name without styling each other.
-- **Colour, radius, elevation and focus are written as the host's own
-  `--dsw-*` tokens**, never aliased behind a private palette and never carrying
-  a literal fallback: the host publishes light and dark, so a literal pins one of
-  them. A stylesheet that reaches for an unknown token fails silently — a border
-  disappears, a label inherits the wrong colour — which is why
-  `src/official-ui.spec.ts` fails the build when a plugin's styling names a token
-  that is not on the allowlist.
-
-`OFFICIAL_THEME_TOKEN_NAMES` is that allowlist. Adding a token to it is a
-deliberate act: confirm the name against the host theme first.
-
-## Session ancestry
-
-`isSubagentSession` uses durable session headers, never the author of a user message.
-Explicit subagent origin or positive delegation depth wins. A seeded human fork with
-zero or omitted depth and ordinary/free classification keeps its parent as history
-lineage; incomplete legacy parent metadata still identifies a child session.
-
-## Shared string contracts
-
-`./contracts` is the single source for cross-plugin literals:
+A shared library used by the plugins in this repository. It adds no feature of its own and does not need to be installed separately; plugins that need it install it automatically.
 
-- `MODEL_SETTINGS_CHANGES_REMOTE` — the model-settings change stream provided by `@klarkxy/dsh-model-hub`. Subscribers degrade silently when that package is not installed.
-- `WEB_PROVIDER_AVAILABILITY_EVENT` and `DshWebManagementDescriptor` — native web providers announce a local availability change and optional display metadata.
-- `CREATOR_PRESET_ID` — the host Creator agent-preset id.
+For plugin developers, the source code and type declarations are the reference.
 
-## Development
+## License
 
-Model settings contributions accept `ModelSettingsText` (`string | { zh: string; en: string }`) for provider titles, field labels/descriptions, follow labels and catalog errors. Built-in display copy should include both languages; user data and third-party literal strings stay unchanged. Model Hub resolves the text at render time when the host locale changes.
+[SATA License 2.1](LICENSE)

package/docs/README.zh-CN.md

@@ -2,54 +2,12 @@
 
 <!-- release-state-note -->
 
-本仓库功能插件共用的支撑包：共享记录类型、插件页模型菜单、宿主 RPC 注册、官方 UI 样式契约，以及一次原生 `llm` 文本调用。它是一个库，不是 DSH bundle——把它作为依赖装上，得到的是功能插件需要的零件，而不是一个新的用户可见功能。
-
 [English](../README.md)
 
-## 本包不做什么
-
-- 它是功能插件的依赖，不是 DSH bundle：不声明 `dsh.bundle`，也不注册插件页，单独安装它不会让用户看到任何变化。
-- 它自身从不发起推理：没有功能要求时，它不会发起任何模型调用。
-- 它不做模型档位路由、重试、超时、排队或用量记录。每个功能在自己的插件页选择模型，并直接调用宿主 `llm`；未选择时使用当前会话模型，再回落到宿主默认对话模型。
-
-## 入口
-
-- `.` — 共享契约类型，以及 `registerHostRpc`、`callLlmText`、`resolveFeatureModel`。
-- `./contracts` — 浏览器安全的类型与常量：共享记忆/知识记录、`TaskContract` / `TaskCheckpoint`、`ModelRoute`、`RpcResult`、`CHAT_EVENTS_SLOT`、`projectIdFromCwd`。
-- `./host-rpc` — 宿主 RPC 注册辅助及其上下文类型。
-- `./model-settings` — 仅供宿主使用的模型设置贡献入口。在 `ctx.effect` 中用 `registerModelSettings` 登记所属插件的模型快照和 CAS 保存接口，枢纽通过 `collectModelSettings` 发现活动入口。每次注册有独立实例标识，旧页面不能写入重新加载的实例。只公开模型字段、版本以及可选的独立模型目录；存储与校验仍归所属插件维护。
-- `./client-utils` — 浏览器安全的原生插件页座位辅助：`selectedSessionId`、`useNativeSeat`、`useFeatureRefresh`。`react` 是可选对等依赖。
-- `./model-settings-client` — 浏览器安全的可选模型设置订阅。`createModelSettingsSubscriber` 复用原生远程流，模型枢纽统一注册描述符；消费页处理刷新和草稿冲突。所属插件在持久化和内存更新完成后用宿主入口的 `notifyModelSettingsChanged` 发出失效提示。
-- `./model-menu` — 插件页模型菜单：目录解析、空路由处理、思考强度选项。
-- `./llm-call` — 单独导出 `callLlmText` 与 `resolveFeatureModel`。
-- `./official-ui` — 浏览器端共享样式契约：`officialUiCss(roots)`、`--dsw-*` token 白名单，以及焦点环与层级辅助。
-- `./cli-process` — 不经命令 shell 运行已解析的可执行文件，提供输出上限、串行逐行回调、超时及本次进程树的取消。流式模式通过 `onLine` 交付 stdout，不再重复保留 stdout 字符串。
-- `./cli-media` — 校验并暂存明确指定的工作区／当前会话媒体，限制文件大小，返回原生图片和文件附件。远端任务授权与厂商协议由各插件负责；这些辅助不为厂商 CLI 自身的文件访问提供沙箱。
-
-将 Cordis 上下文传给 `resolveFeatureModel` 的插件须在 `inject` 中声明 `agents`、`sessionProjections` 和 `agentDefaultModel`。插件未保存模型时，这三个服务提供当前会话选择和宿主默认模型。
-
-## 插件 UI 约定
-
-功能插件的浏览器端用宿主自己的组件拼装界面，而不是自己重画控件。具体是：
-
-- **控件来自 `@deepseek-ai/dsh-client-ui-primitives`**——`Button`、`Input`、`Checkbox`、`Switch`、`Tag`、`Pill`、`SegmentedControl`、`Menu`、`Modal`、`Tooltip`、`Toast`、`DisclosureRow`、`StateDot`、`PathLabel` 与设置表单套件。几何、焦点环、状态和本地化接口都由宿主掌握，抄一份就会在下次换肤时掉队。原生 `<select>` 是唯一例外：官方组件里没有它，保留平台控件并套用契约的 `dsh-ui-select` 即可。
-- **排版、字阶、卡片、表单、横幅、空态和浮层来自 `./official-ui`**，并限定在该插件自己的根类名下，因此两个插件可以挂同名类而互不影响。
-- **颜色、圆角、层级和焦点环直接写宿主的 `--dsw-*` token**，不另起一套私有别名，也不带字面量回落：宿主同时发布浅色与深色，字面量会把其中一套钉死。样式表里写错 token 不会报错——边框直接消失、文字继承错颜色——所以 `src/official-ui.spec.ts` 会在插件样式表点到白名单之外的 token 时让构建失败。
-
-`OFFICIAL_THEME_TOKEN_NAMES` 就是这份白名单。往里加 token 是一个需要确认的动作：先对照宿主主题核实名字。
-
-## 会话关系
-
-`isSubagentSession` 只读取持久会话头，不根据 user 消息判断真人。明确的子代理来源或正派发深度优先；派发深度为零或由原生宿主省略、明确带 seed 的普通/自由真人分叉保留 parent 作为历史继承关系，仅有 parent 的旧会话及未知元数据仍按子线程处理。
-
-## 跨插件字符串契约
-
-`./contracts` 是插件间字面量的单一来源：
+本仓库插件共用的支撑库。它自身不提供功能，也不需要单独安装；需要它的插件会自动带上。
 
-- `MODEL_SETTINGS_CHANGES_REMOTE`：由 `@klarkxy/dsh-model-hub` 提供的模型设置变更流。未安装该包时，订阅方静默降级。
-- `WEB_PROVIDER_AVAILABILITY_EVENT` 与 `DshWebManagementDescriptor`：原生网页供应商宣布本地可用性变化，以及可选的展示元数据。
-- `CREATOR_PRESET_ID`：宿主 Creator 预设 id。
+插件开发者请直接参考源码和类型声明。
 
-## 开发
+## 许可证
 
-模型设置贡献的提供方标题、字段名称与说明、跟随模式名称及目录错误支持 `ModelSettingsText`（`string | { zh: string; en: string }`）。内置展示文案提供中英文，用户数据和第三方字符串保留原文；模型设置页在渲染时跟随宿主语言解析。
+[SATA License 2.1](../LICENSE)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@klarkxy/dsh-plugin-kit",
-  "version": "0.3.1",
-  "description": "Shared types, model-menu helpers, and host RPC registration. Does not call models.",
+  "version": "0.3.3",
+  "description": "Shared support library for klarkxy DSH plugins.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "engines": {
@@ -84,7 +84,7 @@
     "test": "vitest run --root ../.. --config vitest.editor-plugins.config.ts --maxWorkers=2 plugins/dsh-plugin-kit/src"
   },
   "dependencies": {
-    "@klarkxy/dsh-model-route": "0.2.1"
+    "@klarkxy/dsh-model-route": "0.2.3"
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-llm": ">=0.2.0-rc.2",
@@ -139,6 +139,6 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dshRelease": {
-    "contentHash": "f069c84f4156bbfef9e5c0f4cecf06ef3407e04fb3e14a35354ce6bc9627e2ae"
+    "contentHash": "5049672e4364c593787689cdfc6274890f95fdf684d5068d7df25bcf630faaed"
   }
 }