dsh-instruction-memory 1.0.16 → 1.0.17

package/CHANGELOG.md

@@ -7,6 +7,36 @@
 > 1.0.13 起由 CI 经 OIDC Trusted Publishing 发布（首个带 provenance 的版本）。
 > 这些历史 tag **不应回填**——npm 上的版本号已被占用。
 
+## [1.0.17] — 2026-10-12
+
+### 新增
+
+- **注入预算可视化（F1）**：设置页在「注入字数上限」下方显示用量条与「实际注入 x / y 字符
+  （约 z token，估算）」（token 按 0.6 系数估算，与既有说明同一口径，仅作参考）；被上限略过的
+  **生效中**条目在列表中逐条标注橙色「本轮不注入」（悬停说明原因），极端情况下首条被迫截断时
+  标注红色「已截断」，用量条同时变为警示色并给出条数提示。调高上限或调整优先级保存后标记即时变化。
+- Host 新增导出纯函数 `planInjection(data)`：在**不改变注入文本一个字节**的前提下，返回注入文本、
+  生效上限（clamp 后的 budget）、候选条目数，以及每条 `included`（`{id, chars, truncated}`）
+  / `omitted`（`{id, chars}`）的取舍明细与考虑顺序（先「始终」后「按需」、同档优先级/更新时间降序）；
+  `buildBlock()` 改为它的薄封装。
+- 快照 `injection` 新增 `budget` / `activeCount` / `included` / `omitted` 字段（SSE 帧随之自动携带）。
+  存储格式仍为 v1、**无新增落盘字段**；旧客户端收到新字段自然忽略，新客户端对没有这些字段的旧宿主
+  快照回退到 `data.budgetChars`、不显示条目标记，两侧均不报错。
+
+### 测试
+
+- `smoke-test.mjs` 新增 20+ 条 `planInjection` 断言：空/总开关关闭/非法输入、budget 越界夹取、
+  与 `buildBlock()` 逐字节一致、停用与空条目不参与、「始终」先于「按需」、紧预算下 included/omitted
+  恰好分区全部候选、单条超长首条截断标记、计划本身确定性。
+- `contract-test.mjs` 新增独立验证块：经真实路由在 800 字符上限下断言快照预算、`chars === preview.length`
+  且不超上限、取舍明细恰好覆盖全部生效条目且不含停用条目、预览脚注数量与 omitted 一致、提高上限后
+  全部纳入；并把真实/旧版/垃圾三类快照喂给客户端 reducer 验证接缝。
+- `verify.mjs` 新增客户端 `__budgetMeter` reducer 断言（计划字段优先、旧快照回退、非法项忽略、
+  垃圾输入零值不抛错、percent 封顶 100、0.6 token 估算）及 6 个新 i18n 键的双语存在性；
+  键集与占位符一致性仍由既有用例锁定。
+- `docs/demo.html` 的演示宿主改为实时计算注入计划（与 `planInjection` 同一算法），演示数据
+  默认 800 字符上限以直接展示用量条与「本轮不注入」标记；旧的手工静态预览文本移除。
+
 ## [1.0.16] — 2026-10-05
 
 一次定向缺陷修复 + 宿主范围扩展。每项修复都有对应回归断言（`npm test` 五套件全绿：

package/README.md

@@ -54,6 +54,11 @@ dsh plugin --profile web remove dsh-instruction-memory
   上限单位是**字符**而非 token——按 DeepSeek 官方分词比例约 1 个中文字符 ≈ 0.6 token、
   1 个英文字符 ≈ 0.3 token（不同模型分词有差异，实际用量以模型返回为准），上限 40000
   字符约合 24000 token。
+- **预算用量可视化**：设置页在上限输入框下方显示用量条——「实际注入 x / y 字符（约 z token，
+  估算）」（token 数按 0.6 系数估算，仅作参考）；被上限略过的**生效中**条目会在列表里逐条
+  标注橙色「本轮不注入」（悬停可见原因），极端情况下首条被迫截断时标注红色「已截断」。
+  调高上限或调整优先级后标记实时变化。这些数据只是对注入取舍的**展示**，不改变注入文本本身；
+  存储格式不变，旧宿主/旧客户端对新字段一律忽略，互不影响。
 
 条目全部停用或总开关关闭时，该提示词段落**整个注销**，系统提示词与未安装本插件时逐字节一致。
 

package/lib/client.js

@@ -58,6 +58,12 @@ window.__ModuleLoader__.load({
 .im-tag-always { color:var(--dsw-alias-brand-primary,#3b6cff); border-color:currentColor; }
 .im-tag-auto { color:var(--dsw-alias-state-success-primary,#18a058); border-color:currentColor; }
 .im-tag-high { color:var(--dsw-alias-state-warn-primary,#d97706); border-color:currentColor; }
+.im-tag-off { color:var(--dsw-alias-state-warn-primary,#d97706); border-color:currentColor; }
+.im-tag-cut { color:var(--dsw-alias-state-error-primary,#d94838); border-color:currentColor; }
+.im-meter { height:6px; border-radius:999px; overflow:hidden;
+  background:var(--dsw-alias-bg-layer-2,rgba(0,0,0,.08)); }
+.im-meter-fill { height:100%; border-radius:999px; background:var(--dsw-alias-brand-primary,#3b6cff); }
+.im-meter-fill-warn { background:var(--dsw-alias-state-warn-primary,#d97706); }
 .im-empty { padding:26px; border-radius:10px; text-align:center; font-size:12px;
   border:1px dashed var(--dsw-alias-border-l2,rgba(0,0,0,.18)); color:var(--dsw-alias-label-secondary,#8a9099); }
 .im-err { font-size:12px; color:var(--dsw-alias-state-error-primary,#d94838); }
@@ -79,6 +85,7 @@ window.__ModuleLoader__.load({
 .im-body-open { max-height:none; }
 .im-more { margin-top:4px; font-size:11.5px; color:var(--dsw-alias-brand-primary,#3b6cff); cursor:pointer; user-select:none; }
 .im-search-meta { margin-top:5px; }
+.im-meter-line { margin-top:5px; }
 .im-undo { display:flex; align-items:center; gap:10px; padding:9px 13px; border-radius:8px; font-size:12px;
   border:1px solid var(--dsw-alias-border-l2,rgba(0,0,0,.14)); background:var(--dsw-alias-bg-layer-2,rgba(0,0,0,.04)); }
 .im-undo button { border:1px solid var(--dsw-alias-brand-primary,#3b6cff); color:var(--dsw-alias-brand-primary,#3b6cff);
@@ -140,6 +147,12 @@ window.__ModuleLoader__.load({
         'budget.unitHint': '单位是字符，不是 token',
         'budget.rangeError': '上限需在 {min} ~ {max} 之间',
         'budget.note': '单位为字符、非 token：按 DeepSeek 分词约 1 个中文字符 ≈ 0.6 token（英文 ≈ 0.3），{max} 字符上限约合 {tokens} token，实际以模型为准。',
+        'budget.used': '实际注入 {used} / {budget} 字符（约 {tokens} token，估算）',
+        'budget.omitted': '有 {count} 条生效指令因超出上限本轮未注入，可调高上限或调整优先级',
+        'tag.omitted': '本轮不注入',
+        'tag.truncated': '已截断',
+        'tag.omittedTitle': '因超出注入字数上限，本条当前不会进入系统提示词',
+        'tag.truncatedTitle': '本条过长，仅开头部分进入系统提示词',
         'rules.label': '生效规则',
         'rules.note': '「始终」无条件生效；「按需」由模型按相关性自动判断。超出上限时按优先级保留，其余暂不注入。',
         'search.placeholder': '搜索指令：标题 / 内容 / 适用场景（共 {count} 条）',
@@ -217,6 +230,12 @@ window.__ModuleLoader__.load({
         'budget.unitHint': 'The unit is characters, not tokens',
         'budget.rangeError': 'The limit must be between {min} and {max}',
         'budget.note': 'Characters, not tokens: with DeepSeek tokenization roughly 1 Chinese character ≈ 0.6 token (English ≈ 0.3), the {max}-character ceiling is about {tokens} tokens; actual usage depends on the model.',
+        'budget.used': '{used} of {budget} characters actually injected (≈{tokens} tokens, estimate)',
+        'budget.omitted': '{count} active entries are not injected this turn because the limit is exceeded; raise the limit or adjust priorities',
+        'tag.omitted': 'Not injected',
+        'tag.truncated': 'Truncated',
+        'tag.omittedTitle': 'This entry currently stays out of the system prompt because the injection size limit is exceeded',
+        'tag.truncatedTitle': 'This entry is too long; only its beginning reaches the system prompt',
         'rules.label': 'How instructions apply',
         'rules.note': '“Always” applies unconditionally; “On demand” lets the model judge by relevance. When the limit is exceeded, higher-priority entries are kept and the rest are skipped.',
         'search.placeholder': 'Search instructions: title / content / scenario ({count} in total)',
@@ -497,6 +516,41 @@ window.__ModuleLoader__.load({
       return focused ? currentText : String(incoming)
     }
 
+    /**
+     * Reduce a snapshot's injection plan to the values the header meter and
+     * the entry badges render. Pinned as a pure export so the fallback math is
+     * testable without React.
+     *
+     * Tolerates an older Host whose snapshot predates the plan fields: the
+     * ceiling then falls back to data.budgetChars and there are simply no
+     * per-entry marks (included/omitted). Garbage input degrades to zeros
+     * instead of throwing mid-render.
+     */
+    function budgetMeter(snapshot) {
+      const inj = snapshot !== null && typeof snapshot === 'object'
+        && snapshot.injection !== null && typeof snapshot.injection === 'object'
+        ? snapshot.injection : {}
+      const data = snapshot !== null && typeof snapshot === 'object'
+        && snapshot.data !== null && typeof snapshot.data === 'object'
+        ? snapshot.data : {}
+      const budget = typeof inj.budget === 'number' && inj.budget > 0
+        ? inj.budget
+        : (typeof data.budgetChars === 'number' && data.budgetChars > 0 ? data.budgetChars : 0)
+      const used = typeof inj.chars === 'number' && inj.chars >= 0 ? inj.chars : 0
+      const countFlagged = (list, wantTruncated) =>
+        Array.isArray(list)
+          ? list.filter((item) => item !== null && typeof item === 'object'
+            && typeof item.id === 'string' && item.id !== ''
+            && (wantTruncated ? item.truncated === true : true)).length
+          : 0
+      const omitted = countFlagged(inj.omitted, false)
+      const truncated = countFlagged(inj.included, true)
+      const percent = budget > 0 ? Math.min(100, Math.round((used / budget) * 100)) : 0
+      // The same rough ratio the budget note quotes; displayed as an ESTIMATE.
+      const tokens = Math.round(used * 0.6)
+      return { budget, used, omitted, truncated, percent, tokens }
+    }
+
     async function callHost(method, args) {
       // A hung host used to pin the panel on 保存中… forever; fail visibly
       // after a generous timeout instead.
@@ -837,6 +891,23 @@ window.__ModuleLoader__.load({
       const injection = view.injection || { registered: false, chars: 0, error: null }
       const entries = data.entries.slice().sort((a, b) => (b.priority - a.priority) || (b.updatedAt - a.updatedAt))
       const activeCount = entries.filter((e) => e.enabled && e.content !== '').length
+      // Budget usage + per-entry marks straight from the Host's injection plan.
+      // Older hosts simply publish none of these fields: the meter falls back
+      // to data.budgetChars and the maps stay empty.
+      const meter = budgetMeter(view)
+      const omittedById = new Map()
+      const truncatedById = new Map()
+      {
+        const planItems = injection && typeof injection === 'object' ? injection : {}
+        for (const item of Array.isArray(planItems.omitted) ? planItems.omitted : []) {
+          if (item !== null && typeof item === 'object' && typeof item.id === 'string') omittedById.set(item.id, item)
+        }
+        for (const item of Array.isArray(planItems.included) ? planItems.included : []) {
+          if (item !== null && typeof item === 'object' && item.truncated === true && typeof item.id === 'string') {
+            truncatedById.set(item.id, item)
+          }
+        }
+      }
       const keyword = query.trim().toLowerCase()
       const visible = keyword === ''
         ? entries
@@ -902,6 +973,19 @@ window.__ModuleLoader__.load({
             h('label', { className: 'im-label' }, t('rules.label')),
             h('div', { className: 'im-meta' },
               t('rules.note')))),
+        (data.enabled === true && activeCount > 0)
+          ? h('div', { key: 'meter' },
+            h('div', { className: 'im-meter' },
+              h('div', {
+                className: 'im-meter-fill' + (meter.omitted > 0 ? ' im-meter-fill-warn' : ''),
+                style: { width: meter.percent + '%' },
+              })),
+            h('div', { className: 'im-meta im-meter-line' },
+              t('budget.used', { used: meter.used, budget: meter.budget, tokens: meter.tokens })),
+            meter.omitted > 0
+              ? h('div', { className: 'im-warn im-meter-line' }, t('budget.omitted', { count: meter.omitted }))
+              : null)
+          : null,
         entries.length > 0 ? h('div', { key: 'search' },
           h('input', {
             className: 'im-input',
@@ -987,6 +1071,17 @@ window.__ModuleLoader__.load({
         ]
         if (entry.priority === 2) tags.push(h('span', { className: 'im-tag im-tag-high', key: 'p' }, t('priority.high')))
         else if (entry.priority === 0) tags.push(h('span', { className: 'im-tag', key: 'p' }, t('priority.low')))
+        // Budget marks from the Host's injection plan. Only active entries can
+        // appear in the plans, so a disabled entry never gets a stale mark.
+        if (omittedById.has(entry.id)) {
+          tags.push(h('span', {
+            className: 'im-tag im-tag-off', key: 'off', title: t('tag.omittedTitle'),
+          }, t('tag.omitted')))
+        } else if (truncatedById.has(entry.id)) {
+          tags.push(h('span', {
+            className: 'im-tag im-tag-cut', key: 'cut', title: t('tag.truncatedTitle'),
+          }, t('tag.truncated')))
+        }
         return h('div', {
           className: 'im-item' + (entry.enabled ? '' : ' im-item-off'),
           key: entry.id,
@@ -1136,6 +1231,7 @@ window.__ModuleLoader__.load({
     exports.__confirmDiscard = confirmDiscard
     exports.__importSizeVerdict = importSizeVerdict
     exports.__nextBudgetText = nextBudgetText
+    exports.__budgetMeter = budgetMeter
     exports.__strings = STRINGS
     exports.__ns = NS
     exports.__dictionaryT = dictionaryT

package/lib/index.js

@@ -518,19 +518,41 @@ function formatEntry(entry, tag) {
 }
 
 /**
- * Render the injected block. Deliberately deterministic: identical memory
- * produces byte-identical text on every step, so the prompt prefix stays
- * cacheable across a session.
+ * Build the injection plan: the exact text assembled into the system prompt
+ * PLUS the per-entry decisions behind it, so the settings page can show how
+ * much of the character budget is in use and flag the enabled entries the
+ * current budget leaves out.
+ *
+ * Deliberately deterministic: identical memory produces a byte-identical
+ * plan on every step, so the prompt prefix stays cacheable across a session.
+ *
+ * Returned shape:
+ *   {
+ *     text:        string  — exactly what buildBlock() returns
+ *     budget:      number  — the clamped budgetChars in effect
+ *     activeCount: number  — enabled, non-blank candidates considered
+ *     included:    [{ id, chars, truncated }] — entries that reach the prompt,
+ *                    in consideration order (始终 first, then 按需; within
+ *                    each, priority desc then updatedAt desc); chars is the
+ *                    rendered length of that entry's block (its cut length
+ *                    when truncated)
+ *     omitted:     [{ id, chars }] — active entries the budget could not fit;
+ *                    chars is the full rendered block length they would need
+ *   }
+ *
+ * Disabled or blank entries are candidates for neither list: they are not
+ * competing for the budget at all. When nothing renders, `text` is '' and
+ * `included` is [] even though `budget` still reports the effective ceiling.
  */
-export function buildBlock(data) {
-  if (data === null || typeof data !== 'object' || data.enabled !== true) return ''
+export function planInjection(data) {
+  const budget = clampBudget(data !== null && typeof data === 'object' ? data.budgetChars : undefined)
+  const blank = () => ({ text: '', budget, activeCount: 0, included: [], omitted: [] })
+  if (data === null || typeof data !== 'object' || data.enabled !== true) return blank()
   const active = (Array.isArray(data.entries) ? data.entries : [])
     .filter((entry) => entry.enabled === true && entry.content !== '')
-  if (active.length === 0) return ''
+  if (active.length === 0) return blank()
   active.sort((a, b) => (b.priority - a.priority) || (b.updatedAt - a.updatedAt))
 
-  const budget = clampBudget(data.budgetChars)
-
   // Richest preamble that still leaves room for one real entry plus the
   // worst-case omission footer. A tight budget degrades the preamble instead of
   // silently injecting nothing.
@@ -565,6 +587,8 @@ export function buildBlock(data) {
   }
 
   const blocks = []
+  const included = []
+  const omittedPlan = []
   let used = header.length
   let omitted = 0
 
@@ -576,6 +600,7 @@ export function buildBlock(data) {
     if (used + block.length + 2 + reserve <= budget) {
       used += block.length + 2
       blocks.push(block)
+      included.push({ id: entry.id, chars: block.length, truncated: false })
       return
     }
     // The first entry always gets in, truncated if the budget demands it: a
@@ -593,17 +618,36 @@ export function buildBlock(data) {
         const body = head + note
         blocks.push(body)
         used += body.length + 2
+        included.push({ id: entry.id, chars: body.length, truncated: true })
         return
       }
     }
     omitted += 1
+    omittedPlan.push({ id: entry.id, chars: block.length })
   }
 
   for (const entry of active) if (entry.mode === 'always') consider(entry, '始终')
   for (const entry of active) if (entry.mode !== 'always') consider(entry, '按需')
 
-  if (blocks.length === 0) return ''
-  return header + blocks.join('\n\n') + footerFor(omitted)
+  if (blocks.length === 0) {
+    return { text: '', budget, activeCount: active.length, included: [], omitted: omittedPlan }
+  }
+  return {
+    text: header + blocks.join('\n\n') + footerFor(omitted),
+    budget,
+    activeCount: active.length,
+    included,
+    omitted: omittedPlan,
+  }
+}
+
+/**
+ * Render the injected block text. A thin wrapper over planInjection: the
+ * decision process lives in one place, and callers that only need the text
+ * (the prompt section) keep this byte-stable entry point.
+ */
+export function buildBlock(data) {
+  return planInjection(data).text
 }
 
 /* ------------------------------------------------------------------ *
@@ -725,6 +769,22 @@ export function apply(ctx) {
     }
   }
 
+  /**
+   * The full injection plan (text + per-entry budget decisions) behind the
+   * registered section. The snapshot publishes it so the settings page can
+   * show budget usage and mark the enabled entries that currently do not fit.
+   * A render failure degrades to an empty plan at the effective ceiling
+   * rather than throwing into the route/SSE path.
+   */
+  const sectionPlan = () => {
+    try {
+      return planInjection(state.data)
+    } catch (err) {
+      console.error('[instruction-memory] render failed:', err)
+      return { text: '', budget: clampBudget(state.data.budgetChars), activeCount: 0, included: [], omitted: [] }
+    }
+  }
+
   /**
    * The thunk handed to the harness.
    *
@@ -1287,7 +1347,8 @@ export function apply(ctx) {
   /* ---------------- snapshots ---------------- */
 
   const snapshot = () => {
-    const preview = sectionText()
+    const plan = sectionPlan()
+    const preview = plan.text
     return {
       data: {
         version: 1,
@@ -1310,6 +1371,16 @@ export function apply(ctx) {
         available: true,
         error: state.sectionError,
         chars: preview.length,
+        /**
+         * The budget decision behind `preview`, for the settings page's
+         * usage meter and per-entry marks. `budget` is the effective ceiling;
+         * `included`/`omitted` carry one item per active entry in
+         * consideration order; disabled or blank entries appear in neither.
+         */
+        budget: plan.budget,
+        activeCount: plan.activeCount,
+        included: plan.included.map((item) => ({ id: item.id, chars: item.chars, truncated: item.truncated === true })),
+        omitted: plan.omitted.map((item) => ({ id: item.id, chars: item.chars })),
         /**
          * How many times the harness has pulled this section into a prompt since
          * boot. 0 means "prepared, never assembled" — the distinction the old

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-instruction-memory",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "description": "User-only instruction memory for DSH: long-term instructions maintained in the settings UI and auto-injected into every conversation — the model has no write access. 指令记忆：只由用户在设置页维护的长期指令，自动注入此后每轮对话；模型没有任何写入口。",
   "license": "MIT",
   "type": "module",