dsh-flash-ctx-mon 0.0.0-stage → 0.1.6

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,248 @@
-# Temporary Holding Version
+# dsh-flash-ctx-mon
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> The **context monitor** companion plugin for
+> [dock-flash](https://gitee.com/lenin.guo/dock-flash) — it registers its own alert
+> provider and its own panel switch instead of living inside dock-flash's `apply()`.
+
+Apache-2.0
+
+**[中文](./README.zh-CN.md)**
+
+## What it does
+
+Two capabilities, one in each half of the plugin:
+
+1. **Context monitor** — reads the **precise** token usage DSH already reports on its
+   session event stream and turns pressure on the model's context window into
+   dock-flash alerts, at three rising thresholds.
+2. **Session skills chip** — a chip in the conversation header listing the skills the
+   current session has actually loaded, resolved against the skill catalog.
+
+The monitor is **on by default** — only an explicit "off" turns it off — and it is
+**entirely client-side**.
+
+## What it registers
+
+### Host half — `src/index.ts` → `dist/index.js`
+
+A Cordis plugin named `dsh-flash-ctx-mon`.
+
+| Thing | Detail |
+| --- | --- |
+| Settings namespace | `dsh-flash-ctx-mon` |
+| Fields | `ctxApproxWindow`, `ctxThresholdInfo`, `ctxThresholdWarning`, `ctxThresholdError`, `ctxPollBase`, `ctxPollMin`, `modelContextWindows`, `modelContextWindowSources` |
+| Routes | **none** |
+| Host-side services | **none** (`inject: []`) |
+
+**The host half exists only to hold the settings namespace and its schema.** There is no
+collector and no route, because there is nothing to collect on the host: token usage
+arrives through DSH session events (`ctx.get('sessions')`), the model catalog through
+`remote.session.modelCatalog()`, and the skill catalog through `remote.skills.list()` —
+all of it in the browser.
+
+### Browser half — `lib/client.js` (no build step)
+
+| Registration | Through |
+| --- | --- |
+| Alert provider `dsh-flash-ctx-mon:context-alert` | `ctx.get('dockFlashAlerts').registerProvider()` |
+| Panel switch `dsh-flash-ctx-mon:monitor-context` | `ctx.get('quickControl').registerSwitch()` |
+| Session header chip `dsh-flash-ctx-mon-skills` | `ctx.inject(['slots'])` → `conversation.session.header.actions` |
+
+Switch properties: `type: 'toggle'`, `group: 'system'`, `cluster: 'system-alerts'`,
+`order: 59`, `icon: 'message'`, plus a **Configure** button. Its visibility follows
+dock-flash's `dock-flash:system-alerts` master toggle — with the alert registry switched
+off there is nothing for this switch to drive. It deliberately carries **no `subtitle`**:
+the live "model · 12%" readout it used to print on the row is already the first thing in
+the panel the Configure button opens.
+
+> **Dual discovery, plus a fallback poll.** `ctx.get('quickControl')` /
+> `ctx.get('dockFlashAlerts')` resolve asynchronously, so registration has three routes:
+> the `dock-flash:ready` event (dock-flash loaded after us), a synchronous `ctx.get()`
+> check (it loaded before us), and a fallback poll of up to 15 attempts 200 ms apart.
+> The first to succeed sets `_registered`, so nothing registers twice.
+
+## The switch
+
+In dock-flash's quick panel, under **⚙️ System → System Alerts**, find **Context
+Monitor**:
+
+- turning it **off** writes `'0'` to `localStorage['dsh-flash-ctx-mon:monitor-context']`
+  and calls `setProviderEnabled(…, false)` on the alert registry, so the provider stops
+  producing alerts;
+- turning it **on** restores both.
+
+**Who wins.** The browser key is the authority, and **absence means on**
+(`getItem(key) !== '0'`). The host's own fields are all `volatile()`, so DSH resets them
+to their defaults on every restart — the browser is what remembers your choice.
+
+## The config modal
+
+**Configure** beside the switch opens the context monitor panel:
+
+| Control | Range | Step | Default |
+| --- | --- | --- | --- |
+| Context Window Size `ctxApproxWindow` | 64000–512000 tokens | 8000 | 128000 |
+| Info Threshold `ctxThresholdInfo` | 30–80 % | 1 | 70 |
+| Warning Threshold `ctxThresholdWarning` | 50–92 % | 1 | 85 |
+| Error Threshold `ctxThresholdError` | 70–98 % | 1 | 95 |
+| Context Poll Base Interval `ctxPollBase` | 5000–60000 ms | 1000 | 20000 |
+| Context Poll Min Interval `ctxPollMin` | 1000–10000 ms | 500 | 2000 |
+
+Below the sliders the panel reports the live state — **Current Model**, **Window Size**,
+**Window Source** (Session Event / Model Catalog / Error Parsed / Manual / Built-in /
+Fuzzy Match / Fallback), **Data Source** (Precise / Awaiting data), **Input Tokens** and
+**Context Pressure** — and carries the **Model Window Map** editor, a **Refresh
+Catalog** action, and a preview of what the alert messages look like.
+
+## Alerts
+
+Emitted only when the token source is `precise`; with no session-event usage data the
+monitor reports "Awaiting data" and **emits nothing** — it does not guess from message
+counts.
+
+| Level | At | Title |
+| --- | --- | --- |
+| ℹ️ info | ≥ `ctxThresholdInfo` (70 %) | Session context getting long |
+| 🟡 warning | ≥ `ctxThresholdWarning` (85 %) | Session context nearly exhausted |
+| 🔴 error | ≥ `ctxThresholdError` (95 %) | Session context almost exhausted |
+
+Each message carries the percentage and the reading it came from — `model ·
+12.4K/128K` in precise mode. Alerts are `dismissible` and flow through dock-flash's
+registry, so they appear in the panel's alert list and as toasts like any other.
+
+## How a model's window is resolved
+
+`_resolveWindow(model)` reads `modelContextWindows` — the **user-mapped** table in the
+settings namespace — and labels each answer with its provenance from
+`modelContextWindowSources`. A model that is not in the map resolves to `null`, and the
+caller falls back to `ctxApproxWindow` (the "Fallback" source).
+
+**The built-in window table has been retired.** `_KNOWN_WINDOWS` is empty and the
+catalog auto-fill is a documented no-op, so today the map is the only source of a real
+window size — which is why the panel's Model Window Map editor is how you teach it about
+a model it gets wrong.
+
+> Both map fields are `volatile()`, and that is **not** a statement that they are
+> transient. The settings service rejects any patched path that is not under a volatile
+> node (`Config field "…" is not volatile`), so a non-volatile `modelContextWindows`
+> meant every mapping the panel wrote was rejected, rolled back and lost — a mapped
+> model kept falling back to `ctxApproxWindow`. Volatile is what makes the write legal;
+> the value still lands in the profile patch and survives a restart.
+
+## Polling
+
+The monitor samples on an adaptive interval: `ctxPollBase` is the **ceiling** used while
+usage is low, and the interval tightens as usage rises, never below `ctxPollMin`. In
+precise mode the base interval is doubled automatically, because the event source pushes
+updates rather than being polled. A skill being used forces an immediate poll, so its
+notice is claimed while the use is still fresh.
+
+## The skills chip
+
+A chip in the conversation header, registered into `conversation.session.header.actions`
+as `dsh-flash-ctx-mon-skills` (order 15). It lists the skills **the current session** has
+loaded — subagents and other sessions are excluded, because the slot hands the component
+the id of the session it renders for.
+
+Detection uses DSH's own marker: the `<skill_content name="X">` block emitted when a
+skill body is loaded. It arrives on two paths — the model calling the `skill` tool, and a
+user typing `/name` in the composer (which produces **no** tool call of its own) — and a
+failed call carries no block, so failures are not counted. Names are resolved against the
+skill catalog (`remote.skills.list()`), and the popup shows uses, first/last use and the
+catalog description, with **Open in sidebar**.
+
+The tracker is deliberately **independent of the monitor switch**: the chip keeps working
+with the context monitor switched off.
+
+## Settings
+
+| Field | Default | Notes |
+| --- | --- | --- |
+| `ctxApproxWindow` | 128000 | Fallback window for a model the map does not know |
+| `ctxThresholdInfo` | 70 | % of the window |
+| `ctxThresholdWarning` | 85 | % — must exceed the info threshold |
+| `ctxThresholdError` | 95 | % — must exceed the warning threshold |
+| `ctxPollBase` | 20000 | ms, the low-usage ceiling |
+| `ctxPollMin` | 2000 | ms, the floor |
+| `modelContextWindows` | `{}` | model id → window size |
+| `modelContextWindowSources` | `{}` | model id → provenance tag |
+
+## Dependencies
+
+| Package | Type | Purpose |
+| --- | --- | --- |
+| `@deepseek-ai/cordis` | peer | the plugin framework |
+| `dock-flash` `>=1.5.0-0 <2.0.0-0 \|\| >=2.0.0-0 <3.0.0-0` | peer | supplies the `quickControl` and `dockFlashAlerts` services and the `dock-flash:ready` event |
+| `dock-base` `>=0.1.2-0 <1.0.0-0 \|\| >=0.2.0-0 <1.0.0-0` | peer, optional | workbench mode only |
+| `@deepseek-ai/schemastery` | dependency | the settings schema (`volatile()`) |
+
+There is **no hard dependency** on dock-flash: every service is resolved through
+`ctx.get(...)`, and compatibility is declared by the **peer range** — the same shape
+dock-flash itself uses towards dock-base. The range carries one branch per tuple whose
+prereleases must resolve, so both the 1.x and 2.x lines are accepted, prereleases
+included.
+
+## Install
+
+```sh
+dsh plugin --profile <profile> add dsh-flash-ctx-mon
+```
+
+Requires **dock-flash ≥ 1.5** — it supplies the `quickControl` and
+`dockFlashAlerts` services and the `dock-flash:ready` event, and any 2.x satisfies it.
+Restart DSH after installing.
+
+`cordis.patch.yml` inserts the host row. Its `name` is a **package name**, resolved
+through the profile's `node_modules` — **never a relative path**.
+
+The browser half needs no row: the module loader discovers it from `package.json`'s
+`exports["./client"]` plus `dsh.client` and serves it at
+`/plugins/dsh-flash-ctx-mon/client.js`.
+
+## Build
+
+```sh
+pnpm install
+pnpm run build       # tsc → dist/index.js   (host half only)
+pnpm run typecheck
+node scripts/verify-config-volatile.mjs ./dist/index.js
+```
+
+`dist/index.js` is **tracked on purpose**, for the same reason dock-flash tracks its own:
+a git install fetches sources and runs no build script, so a repository without `dist/`
+would arrive missing the host entry point that `main` and `exports["."]` point at.
+`lib/client.js` is a single file edited directly; it has no build step and takes effect
+on page refresh.
+
+`scripts/verify-config-volatile.mjs` loads the built host half and re-runs the settings
+service's own volatile-path test against it — the invariant the two map fields must
+satisfy, or every write to them is rejected.
+
+## Layout
+
+```
+src/index.ts      HOST half      → tsc → dist/index.js
+lib/client.js     BROWSER half   → no build, edited directly
+dist/index.js     compiled host half — tracked on purpose
+cordis.patch.yml  bundle layer: inserts the host row into the profile
+scripts/          verify-config-volatile.mjs — the volatile-schema check
+.github/workflows/sync-from-gitee.yml — the Gitee → GitHub mirror
+```
+
+Gitee is the authoritative repository; GitHub (`github.com/tcgbp/dsh-flash-ctx-mon`) is a
+mirror of it and the host of the release tarball.
+
+## Privacy and limits (deliberate)
+
+- **Nothing leaves the machine.** The monitor reads DSH's own session events and two
+  client remotes; it has no host route, no collector and no outbound request.
+- **Precise or nothing.** With no session-event usage data the monitor shows "Awaiting
+  data" and raises no alert, rather than estimating from message counts.
+- **Per-session skills only.** The chip counts the current session; subagent sessions and
+  other conversations are excluded. A session that is no longer retained reports "Skill
+  catalog unavailable" with a Retry.
+- **Bounded tracking.** Tracked skills are capped at 200 per session (defensive), and a
+  skill notice is only announced for a use within the last 15 seconds, so replaying a
+  session's history does not fire a burst of notices.
+- **UI language**: the panel and the alert text carry both Chinese and English, and
+  follow DSH's language setting.

package/README.zh-CN.md

@@ -0,0 +1,216 @@
+# dsh-flash-ctx-mon
+
+> [dock-flash](https://gitee.com/lenin.guo/dock-flash) 的**上下文监控**配套插件 —— 它自己注册
+> 告警提供者与面板开关，而不是住在 dock-flash 的 `apply()` 里。
+
+Apache-2.0
+
+**[English](./README.md)**
+
+## 它做什么
+
+两个能力，分别落在插件的两半：
+
+1. **上下文监控** —— 直接读取 DSH 会话事件流里已有的**精确** token 用量，把模型上下文窗口的
+   压力按三档递进的阈值变成 dock-flash 告警。
+2. **会话技能芯片** —— 会话标题栏上的一枚芯片，列出**当前会话**真正加载过的技能，并用技能
+   目录补全信息。
+
+监控**默认开启**（只有显式关闭才会关掉），并且**完全在客户端**。
+
+## 它注册了什么
+
+### 宿主半 —— `src/index.ts` → `dist/index.js`
+
+一个名为 `dsh-flash-ctx-mon` 的 Cordis 插件。
+
+| 项目 | 说明 |
+| --- | --- |
+| 设置命名空间 | `dsh-flash-ctx-mon` |
+| 字段 | `ctxApproxWindow`、`ctxThresholdInfo`、`ctxThresholdWarning`、`ctxThresholdError`、`ctxPollBase`、`ctxPollMin`、`modelContextWindows`、`modelContextWindowSources` |
+| 路由 | **无** |
+| 宿主侧服务 | **无**（`inject: []`） |
+
+**宿主半存在的唯一目的是承载设置命名空间与它的 schema。** 没有采集器、没有路由，因为宿主侧
+本来就无可采集：token 用量来自 DSH 会话事件（`ctx.get('sessions')`），模型目录来自
+`remote.session.modelCatalog()`，技能目录来自 `remote.skills.list()` —— 全都在浏览器里。
+
+### 浏览器半 —— `lib/client.js`（无构建步骤）
+
+| 注册项 | 经由 |
+| --- | --- |
+| 告警提供者 `dsh-flash-ctx-mon:context-alert` | `ctx.get('dockFlashAlerts').registerProvider()` |
+| 面板开关 `dsh-flash-ctx-mon:monitor-context` | `ctx.get('quickControl').registerSwitch()` |
+| 会话标题芯片 `dsh-flash-ctx-mon-skills` | `ctx.inject(['slots'])` → `conversation.session.header.actions` |
+
+开关属性：`type: 'toggle'`、`group: 'system'`、`cluster: 'system-alerts'`、`order: 59`、
+`icon: 'message'`，外加一个**配置**按钮。它的可见性跟随 dock-flash 的
+`dock-flash:system-alerts` 总开关 —— 告警注册表关掉之后，这个开关没有东西可驱动。它故意
+**不带 `subtitle`**：过去印在行上的 "模型 · 12%" 实时读数，现在就在「配置」按钮打开的
+面板第一屏。
+
+> **双路发现，外加兜底轮询。** `ctx.get('quickControl')` / `ctx.get('dockFlashAlerts')` 是
+> 异步解析的，所以注册有三条路径：`dock-flash:ready` 事件（dock-flash 比我们晚加载）、同步
+> `ctx.get()` 检查（它比我们早加载）、以及最多 15 次、每次间隔 200 ms 的兜底轮询。先成功
+> 的那个会置上 `_registered`，所以不会重复注册。
+
+## 开关
+
+在 dock-flash 快捷面板的 **⚙️ 系统 → 系统告警** 下，找到 **上下文监控**：
+
+- **关**：向 `localStorage['dsh-flash-ctx-mon:monitor-context']` 写入 `'0'`，并对告警注册表
+  调用 `setProviderEnabled(…, false)`，提供者随之停止产出告警；
+- **开**：两者一起恢复。
+
+**谁说了算。** 浏览器里那个键是权威，且**键不存在即为开**（`getItem(key) !== '0'`）。宿主
+侧的字段全部是 `volatile()`，每次重启 DSH 都会把它们重置为默认值 —— 记住你选择的是浏览器。
+
+## 配置面板
+
+开关旁的**配置**按钮打开上下文监控面板：
+
+| 控件 | 范围 | 步长 | 默认 |
+| --- | --- | --- | --- |
+| 上下文窗口大小 `ctxApproxWindow` | 64000–512000 token | 8000 | 128000 |
+| 信息阈值 `ctxThresholdInfo` | 30–80 % | 1 | 70 |
+| 警告阈值 `ctxThresholdWarning` | 50–92 % | 1 | 85 |
+| 错误阈值 `ctxThresholdError` | 70–98 % | 1 | 95 |
+| 上下文轮询基础间隔 `ctxPollBase` | 5000–60000 ms | 1000 | 20000 |
+| 上下文轮询最小间隔 `ctxPollMin` | 1000–10000 ms | 500 | 2000 |
+
+滑块下方是实时状态：**当前模型**、**窗口大小**、**窗口来源**（会话事件 / 模型目录 / 错误
+解析 / 手动配置 / 内置表 / 模糊匹配 / 估算默认）、**数据来源**（精确 / 等待数据）、
+**输入Token** 与 **上下文压力**；此外还有**模型窗口映射**编辑器、**刷新目录**动作，以及
+告警消息样式的预览。
+
+## 告警
+
+仅在 token 来源为 `precise` 时产出；没有会话事件用量数据时，监控显示「等待数据」并且
+**什么都不发** —— 它不会拿消息条数去猜。
+
+| 级别 | 触发 | 标题 |
+| --- | --- | --- |
+| ℹ️ 信息 | ≥ `ctxThresholdInfo`（70 %） | 会话上下文较长 |
+| 🟡 警告 | ≥ `ctxThresholdWarning`（85 %） | 会话上下文即将用尽 |
+| 🔴 错误 | ≥ `ctxThresholdError`（95 %） | 会话上下文几乎用尽 |
+
+每条消息都带上百分比与它所依据的读数 —— 精确模式下形如 `模型 · 12.4K/128K`。告警是
+`dismissible` 的，并且走 dock-flash 的注册表，所以它们和其它告警一样出现在面板告警列表与
+弹窗通知里。
+
+## 模型窗口是怎么解析出来的
+
+`_resolveWindow(model)` 读取 `modelContextWindows` —— 设置命名空间里那张**用户映射**表 —— 并
+用 `modelContextWindowSources` 给每个结果标上来源。表里没有的模型解析结果为 `null`，调用方
+回退到 `ctxApproxWindow`（即「估算默认」来源）。
+
+**内置窗口表已经退役。** `_KNOWN_WINDOWS` 为空，目录自动填充是一个有文档说明的空实现，所以
+今天映射表是真实窗口大小的唯一来源 —— 这也正是「模型窗口映射」编辑器存在的意义：教会它某个
+它算错的模型。
+
+> 两个映射字段都是 `volatile()`，而这不代表它们是**临时**的。设置服务会拒绝任何不在 volatile
+> 节点下的写入路径（`Config field "…" is not volatile`），所以 `modelContextWindows` 曾经因为
+> 不是 volatile，导致面板写下的每一条映射都被宿主拒绝、被客户端回滚、然后丢失 —— 被映射过的
+> 模型依旧回退到 `ctxApproxWindow`。volatile 是让写入合法的前提；值本身照旧落在 profile patch
+> 里，重启后仍在。
+
+## 轮询
+
+监控按自适应间隔采样：`ctxPollBase` 是占比低时使用的**天花板**，占比越高间隔越密，但不会低于
+`ctxPollMin`。精确模式下基础间隔会自动加倍，因为事件源是主动推送而不是被轮询。有技能被使用时
+会立刻触发一次采样，好让它的提示在「新鲜」窗口内被认领。
+
+## 技能芯片
+
+会话标题栏上的一枚芯片，以 `dsh-flash-ctx-mon-skills`（order 15）注册进
+`conversation.session.header.actions`。它列出**当前会话**加载过的技能 —— 子代理与其它会话被
+排除在外，因为 slot 会把「它正在为哪个会话渲染」的 id 交给组件。
+
+检测用的是 DSH 自己的标记：技能正文被加载时输出的 `<skill_content name="X">` 块。它从两条
+路径到达 —— 模型调用 `skill` 工具，以及用户在输入框敲 `/name`（这条路径**不产生**工具调用）
+—— 而失败的调用不带这个块，所以失败不会被计入。名字会用技能目录（`remote.skills.list()`）
+解析，弹层显示调用次数、首次/最近使用时间与目录描述，并提供**在侧栏打开**。
+
+该追踪器刻意**独立于监控开关**：上下文监控关掉之后，芯片照常工作。
+
+## 设置项
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `ctxApproxWindow` | 128000 | 映射表不认识的模型所用的回退窗口 |
+| `ctxThresholdInfo` | 70 | 占窗口百分比 |
+| `ctxThresholdWarning` | 85 | % —— 必须大于信息阈值 |
+| `ctxThresholdError` | 95 | % —— 必须大于警告阈值 |
+| `ctxPollBase` | 20000 | ms，占比低时的天花板 |
+| `ctxPollMin` | 2000 | ms，地板 |
+| `modelContextWindows` | `{}` | 模型 id → 窗口大小 |
+| `modelContextWindowSources` | `{}` | 模型 id → 来源标记 |
+
+## 依赖
+
+| 包 | 类型 | 用途 |
+| --- | --- | --- |
+| `@deepseek-ai/cordis` | peer | 插件框架 |
+| `dock-flash` `>=1.5.0-0 <2.0.0-0 \|\| >=2.0.0-0 <3.0.0-0` | peer | 提供 `quickControl`、`dockFlashAlerts` 服务与 `dock-flash:ready` 事件 |
+| `dock-base` `>=0.1.2-0 <1.0.0-0 \|\| >=0.2.0-0 <1.0.0-0` | peer，可选 | 仅 workbench 模式 |
+| `@deepseek-ai/schemastery` | dependency | 设置 schema（`volatile()`） |
+
+对 dock-flash **没有硬依赖**：所有服务都通过 `ctx.get(...)` 解析，兼容性由 **peer 范围**声明
+—— 与 dock-flash 自己对 dock-base 的写法同形。该范围按「预发布必须能解析的 tuple」逐条分支，
+因此 1.x 与 2.x 两条线都被接受，预发布版本也算在内。
+
+## 安装
+
+```sh
+dsh plugin --profile <profile> add dsh-flash-ctx-mon
+```
+
+需要 **dock-flash ≥ 1.5**：它提供 `quickControl`、`dockFlashAlerts` 服务与 `dock-flash:ready` 事件，任何 2.x 都满足。安装后请重启 DSH。
+
+`cordis.patch.yml` 负责插入宿主行。它的 `name` 是**包名**，经 profile 的 `node_modules`
+解析 —— **绝不是相对路径**。
+
+浏览器半不需要任何行：模块加载器从 `package.json` 的 `exports["./client"]` 配合 `dsh.client`
+发现它，并在 `/plugins/dsh-flash-ctx-mon/client.js` 提供。
+
+## 构建
+
+```sh
+pnpm install
+pnpm run build       # tsc → dist/index.js   （仅宿主半）
+pnpm run typecheck
+node scripts/verify-config-volatile.mjs ./dist/index.js
+```
+
+`dist/index.js` 是**有意纳入版本控制**的，理由与 dock-flash 相同：git 安装只取源码、不跑任何
+构建脚本，所以没有 `dist/` 的仓库会缺少 `main` 与 `exports["."]` 指向的宿主入口。
+`lib/client.js` 是单文件直接编辑，无构建步骤，刷新页面即生效。
+
+`scripts/verify-config-volatile.mjs` 会加载构建好的宿主半，并对它重跑设置服务自己的
+volatile 路径检查 —— 也就是那两个映射字段必须满足的不变量，不满足则每次写入都会被拒绝。
+
+## 目录结构
+
+```
+src/index.ts      HOST half      → tsc → dist/index.js
+lib/client.js     BROWSER half   → no build, edited directly
+dist/index.js     compiled host half — tracked on purpose
+cordis.patch.yml  bundle layer: inserts the host row into the profile
+scripts/          verify-config-volatile.mjs — the volatile-schema check
+.github/workflows/sync-from-gitee.yml — the Gitee → GitHub mirror
+```
+
+Gitee 是权威仓库；GitHub（`github.com/tcgbp/dsh-flash-ctx-mon`）是它的镜像，也是发布用
+tarball 的托管处。
+
+## 隐私与边界（有意为之）
+
+- **不出本机。** 监控只读 DSH 自己的会话事件与两个客户端 remote；它没有宿主路由、没有采集器、
+  也没有任何对外请求。
+- **精确，否则不发。** 没有会话事件用量数据时显示「等待数据」且不发告警，而不是拿消息条数
+  估算。
+- **技能仅限本会话。** 芯片只统计当前会话；子代理会话与其它对话排除在外。已不再保留的会话
+  会显示「技能目录读取失败」并给出重试。
+- **有界追踪。** 每个会话最多追踪 200 个技能（防御性上限）；只有当某次使用发生在最近 15 秒内
+  时才会发出提示，所以重放一个会话的历史不会一次爆出一串提示。
+- **界面语言**：面板与告警文案同时提供中英文，并跟随 DSH 的语言设置。