偏好增强包 malko/dsh-malko-prefs

dsh-malko-prefs

Vibe coded。 这个插件几乎完全由 AI 助手（OpenCode，deepseek-v4.1-flash）根据自然语言提示词写成，只经过少量人工审查和测试。它不是精心手工打磨的产品：信任之前先读代码，做好遇到粗糙边缘的准备，并检查它改动了你 dsh 配置档里的什么内容——尤其是它会重述你的智能体预设（见安装）。使用风险自负。

DeepSeek Harness（dsh）的个人偏好设置：一个可调优的官方压缩引擎伴侣、一个用于 Models 页面的 llama.cpp 模型信息增强，以及标签页通知，打包成单个 dsh bundle。

- 压缩 —— 官方 @deepseek-ai/dsh-compaction-basic 引擎是参考行为；这个插件把它包了一层，加上设置页面，让阈值、保留量、摘要模型/推理以及可选的回合结束压缩都变成用户可配置。它还加了 /force-compact 命令。
- 模型信息增强 —— 读取 llama.cpp 服务器暴露的更丰富的模型元数据（meta.n_ctx、architecture.input_modalities、aliases），填充对应的 llm-pi-ai 模型条目（上下文窗口、文本/图像输入）。
- 通知 —— 有提问/审批等你处理时，浏览器标签页图标变琥珀色；会话工作中变蓝色；会话在无人值守时结束变绿色；这两种事件都会触发浏览器通知，可选带声音。移植自 dsh-notice-center（MIT）。

要求

- dsh ≥ 0.1.7-rc.1 —— 基于当前设置域（Host 上标记 .volatile() 的 Config 字段，Client 上的 ctx.configForms）以及 BasicCompactionEngine。已在 0.1.7-rc.2 和 0.2.0-rc.2 上测试。
- 一个可用的 llm-pi-ai 服务商（例如你的 llama.cpp 服务器），用于模型信息增强。

安装

从 registry 安装（发布之后）：

dsh plugin --profile web add dsh-malko-prefs
then restart dsh web

或者从本地 checkout / tarball 安装：

dsh plugin --profile web add /path/to/dsh-malko-prefs
dsh plugin --profile web add ./dsh-malko-prefs-0.1.0.tgz

bundle 层做两件事（见 cordis.patch.yml）：

1. 插入 Host 部分：设置服务 malkoPrefs 和 malkoModels 探测 Service，其严格的 Typert wire 定义通过包的 ./typert 导出提供，@deepseek-ai/dsh-typert-loader 在挂载时自动注册；
2. 重述每个随附的智能体预设（preset-cordis、preset-ptc、preset-standard），把官方 compaction-basic 行重定向到 dsh-malko-prefs/compaction。

第二点正是这个文件是生成的、而非手写的原因：补丁会整体替换某一行的 config，而压缩后端嵌套在预设内部，所以换掉它意味着复制整个预设。dsh 升级如果动了预设，升级后要重新生成：
node scripts/gen-preset-override.mjs # auto-detects dsh on PATH
node scripts/gen-preset-override.mjs <presets-dir> # or pass it explicitly
DSH_PRESETS_DIR=<presets-dir> node scripts/gen-preset-override.mjs

生成的 cordis.patch.yml 与生成时所用 dsh 版本的预设组合绑定 —— 插件面向的是随附这些预设的那个 dsh（通过可选的 peerDependencies 声明）。

回滚：dsh plugin --profile web remove dsh-malko-prefs（然后重启）。

设置 ——「Malko's prefs」

在设置里新增一个分区，分为三个子标签页：上下文压缩、 通知 和 llama.cpp 模型（面板滚动时标签栏保持固定）。所有字段 实时生效（无需重启）。

上下文压缩

上下文压缩设置

压缩阈值

| 字段 | 含义 |
| Threshold (tokens) | 以 token 计的绝对压力值，例如 130k / 130K / 1.5m。留空或填 0 = 使用下面的比例。 |
| Context window (tokens) | 绝对阈值所参照的窗口大小（例如 200k）。填 0 = 只用比例。 |
| Threshold ratio | 绝对阈值为空时使用（0.8 = 窗口的 80%）。 |
| Headroom (tokens) | 在输出上限之外预留的余量。官方默认值（65536）会把触发点压到远低于 80%。 |

实际触发点：min(window × ratio, window − output − headroom)；同时设置了绝对阈值
和上下文窗口时，触发点就是该阈值。默认：比例 0.8 + 余量 32768 → 在 200k 窗口上约 160k 触发压缩。

保留

Keep last (tokens)（绝对值，例如 32k）或 Keep ratio —— 逐字保留的近期上下文预算。

行为

- 自动压缩 —— 官方的步间压力压缩与上下文溢出恢复。
- 回合结束时压缩 —— 智能体空闲时再跑一次压缩。

摘要

- Model —— Session model（默认）或 Custom model。
- Provider / Model —— 选择 Custom model 时显示；数据来自 llm-pi-ai 目录。
- Reasoning —— Default、Off，或所选模型声明的任意级别（会话模式只暴露 Default / Off）。指令追加在重放前缀之后，这样服务商的提示词缓存能保持热度。

高级

Summary output cap、Extra compaction attempts、Overflow recovery attempts。

llama.cpp 模型

对每个声明了 baseURL 的 llm-pi-ai 服务商，Fetch from server 会读取
GET {baseURL}/models。随后它会展示每个已发现模型的预览，以及导入会带来
哪些变化：上下文窗口（来自 meta.n_ctx/n_ctx_train）、输出上限、输入模态（来自 architecture.input_modalities）；尚不存在的模型会标记为 new model。勾选你要的模型（或用 Select all），然后点击 Import ——只有选中的那些写入时，已有条目会更新，新条目追加。请求按服务商的方式鉴权：解析端点 apiKeyEnv 里的凭据（先查 dsh credentials，再查宿主环境），然后以 Authorization: Bearer … 发送，所以受 api-key 保护的服务器也能正常工作。

llama.cpp models settings

通知

两个独立功能，都由官方客户端信号驱动（sessions、uiSession.sessionStatus）；除配置外不持久化任何内容。

Notifications settings

标签页状态灯 —— 给浏览器标签页图标重新着色：

| 颜色 | 含义 | 何时清除 |
| 琥珀色 | 有会话在等你（提问 / 审批 / 计划评审） | 你处理完之后 |
| 工作中 | 有会话正在生成 | 会话停止运行时 |
| 绿色 | 你不在时主会话已完成 | 你打开该会话 / 回到标签页时 |
| 空闲 | 无内容可报告（除非你设了颜色，否则用官方 favicon） | — |

优先级为琥珀色 > 工作中 > 绿色 > 空闲，子代理会话会被忽略。所有图标链接一起重绘（DSH 自带深色和浅色两套 favicon，由 prefers-color-scheme 选择）。

系统通知 —— 设置按通知类型分组。一个全局总开关（Enable notifications，默认关闭，需手动开启；浏览器只询问一次权限），一个全局 Notify in the foreground（关闭 = 仅在标签页不可见且未聚焦时触发），一个全局 Volume。然后每种类型一组 —— When a session finishes 和 While waiting for you（提问 / 审批 / 计划评审）—— 每组各有自己的 Notify 开关、Keep on screen（保留到手动关闭）和声音。

声音（按类型）—— 每组的选择器默认是 No sound（全新安装时两个默认值都静音）。列表包括：No sound、两个内置合成提示音（Chime Up / Chime Down，无需素材文件）和 45 个随包附带的 opencode 音效（见 assets/audio/README.md）；选中一个会试听，Host 在 /malko-prefs-sounds/<id>.mp3 提供这些 mp3。如果该路由不可用，播放器会退回提示音 —— 但浏览器可能在你至少与页面交互一次之前阻止音频播放。

声音与横幅解耦：一旦为某类型选了声音，该事件（完成 / 等待）就会播放，即使通知 —— 或该类型 —— 已禁用；选 No sound 则什么都不播。

Sound settings

| 字段 | 键 | 默认值 |
| Color the tab icon | colorsEnabled | 开 |
| Finished / Waiting / Working / Idle color | green / amber / working / black | 绿色/琥珀色用官方侧边栏颜色，工作中用蓝色；black 留空 = 官方 favicon |
| Enable notifications (master) | notifyEnabled | 关 |
| Notify in the foreground (global) | notifyForeground | 关 |
| Volume (global) | notifyVolume | 0.6 |
| 完成：通知 / 保持屏幕常亮 / 声音 | notifyDoneEnabled / notifyDonePersistent / notifyDoneSound | on / off / none |
| 等待：通知 / 保持屏幕常亮 / 声音 | notifyPendingEnabled / notifyPendingPersistent / notifyPendingSound | on / off / none |

系统通知需要安全上下文——http://127.0.0.1:PORT 或 localhost。通过局域网 IP 打开时 Notification API 不可用（这是浏览器规则，不是插件规则）；标签页状态灯仍然可用。

命令

- /compact —— dsh 官方命令（空闲时手动压缩）。
- /force-compact —— 立即压缩：智能体空闲时马上执行，否则排队，等下一步模型调用时消费（绕过阈值）。

工作原理

host plugin (lib/index.mjs)
├─ Config (volatile) ──▶ settings page "malko-prefs"
├─ service malkoPrefs ──▶ live prefs + force queue
├─ service malkoModels ──▶ llama.cpp probe (wire def in lib/typert.host.mjs)
├─ /malko-prefs-sounds/<id>.mp3 ──▶ bundled sound library
└─ /force-compact command

client plugin (lib/client.js)
├─ mounts its own malkoModels Remote via ctx.remote.$mount()
├─ tab status light + notifications (src/notify.ts, optional uiSession)
└─ settings page: 3 sub-tabs (compaction / models / notifications)

preset plugin (lib/compaction.mjs)
└─ MalkoCompactionEngine extends BasicCompactionEngine
├─ rebuilds its policy from malkoPrefs before each operation
├─ summarize() → model + reasoning control (cache-safe order)
└─ agent/status idle → optional turn-end compaction

其余部分引擎复用官方引擎（持久事务、裁剪、溢出恢复），所以只要没有偏好改动行为，表现就和 compaction-basic 一致。

注意：service 类不要用 JS 私有成员（#x）——cordis 会把 service 方法绑定到代理上，私有成员会抛 Receiver must be an instance of class ...。

开发

node build.mjs # esbuild → lib/{index,compaction,typert.host}.mjs + lib/client.js
node scripts/check.mjs # static conformance checks

| 文件 | 作用 |
| src/prefs.ts | 偏好字段、默认值、parseTokenText |
| src/index.ts | host 插件：volatile Config、malkoPrefs、/force-compact |
| src/compaction.ts | MalkoCompactionEngine（继承官方引擎） |
| src/remote.ts | 共享 wire 标识 + probeInvocation() 构造器 |
| src/typert.ts | Host Typert 清单（zod 严格编解码器） |
| src/typert.host.ts | dsh-typert-loader 导入的 ./typert 导出入口 |
| src/probe.ts | malkoModels Service（llama.cpp /models 探测） |
| src/client.ts | 设置页（三个子标签页） |
| src/notify.ts | 标签页状态灯 + 通知 + 声音播放器（移植自 dsh-notice-center） |
| assets/audio/ | 45 个内置通知音效（opencode，MIT） |
| src/whale.ts | 重新配色的官方鲸鱼 SVG，用作标签页图标 |
| scripts/gen-preset-override.mjs | 根据已安装的预设重新生成 cordis.patch.yml |
| scripts/check.mjs | manifest / bundle / 缓存安全检查 |

发布

这个包已经可以发布：

- 移除了 private；设置了 LICENSE（MIT）和 author；files 会打包 lib/、cordis.patch.yml、scripts/、assets/ 和 LICENSE。
- prepublishOnly 会运行构建和 scripts/check.mjs。
- 符合规范的 bundle：dsh.bundle.patch、exports["./client"] 和
exports["./package.json"]，客户端 bundle id 等于包名，
客户端只依赖基线平台模块（react、 @deepseek-ai/dsh-client-ui-primitives）。
- 这个名字在 npmjs.com 上还没被占用；用 npm publish 发布（非 scoped / public）。

注意：cordis.patch.yml 是根据随包发布的预设生成的，所以发布前要针对你目标的 dsh 版本重新生成，并让 peerDependencies 的范围保持同步。

限制

- 生成的 cordis.patch.yml 复制的是随包发布的预设；dsh 升级后要重新运行 gen-preset-override.mjs。
- /force-compact 的 busy 路径用的是引擎的上下文溢出入口，它会压缩最大安全头部（retention 0）。
- 模型信息补全在宿主侧完成（浏览器无法跨域访问本地 llama.cpp 服务）。
- 浏览器通知需要安全上下文（127.0.0.1/localhost）；标签页状态灯的绿色/琥珀色状态存在内存里，刷新后会重置。
- 通知声音是尽力而为：浏览器可能在有用户手势之前拦截音频，而且如果 /malko-prefs-sounds 路由不可用，播放器会退回合成提示音。