spyfree/dsh-media-guard

dsh-media-guard

为 DeepSeek Harness（DSH）提供图像优化、智能保留和可观测性。

dsh-media-guard 在每次 agent-loop 模型调用之前，对发往提供方的图像视图进行优化。它会清点附件引用、压缩过大的图像、按内容地址去重、优先保留当前轮次和用户媒体，并将仍然无法容纳的媒体替换为事实性的 Evidence Notes。持久会话日志和原始附件永远不会被修改；压缩后的变体通过 DSH 的不可变附件存储添加。

DSH 0.1.0-rc.8 已经提供了本插件最初填补的基线安全层：附件准入会拒绝不安全的单图/单消息输入，而 offloadRequestImages() 允许官方 Pi AI 和 DeepSeek 适配器通过替换最旧的图像，将聚合 Base64 图像负载限制在 20 MiB。因此，Media Guard 是一个优化、保留策略和可观测性层，而非声称 DSH 缺乏请求大小保护。它剩余的优势在于：压缩而非立即移除、内容地址去重、当前轮次/来源感知的保留、更严格的可配置预算、Evidence Notes、报告，以及对不调用 DSH 辅助函数的第三方适配器的统一覆盖。

这是 pi-media-guard 的 DSH 移植版；在宿主允许的范围内，规划器、公平份额计算、证据说明和失败策略逐行共享。

Alpha： 此产品线实现了账本、规划器、基于 sharp 的压缩、预算驱动的外置化、llm/stream 投影以及本地报告 UI。请求路径、附件 API、客户端 bundle、可选的 webServer 接缝，以及与 rc.8 offloadRequestImages() 的共存，均已针对 @deepseek-ai/dsh-* 0.1.0-rc.8 进行测试。DSH 本身仍是开发者预览版，其 API 可能仍会变动。

工作原理

- 注册在 llm/stream waterfall 上，并且仅对 agent-loop 构建的请求生效（isAgentLoopRequest）。手工构建的调用——视觉桥接的 VLM 流量、压缩、重放——会原样通过，插件自身投影后的重新分发也会原样通过，从而终止递归。
- 核算为零字节成本：DSH 图像块携带内容寻址的附件引用（sha256:…），并带有精确的字节大小和尺寸，因此账本、去重和预算计算从不读取图像数据。只有被选中进行压缩的图像才会通过 ctx.attachments 读取。
- 过大的图像使用本包自有的 sharp 依赖进行约束，编码为 WebP，并通过 ctx.attachments.saveImage 保存回去。变体会按源内容地址和目标进行缓存，因此重复项和后续匹配的请求会复用同一个已存储引用。
- 当投影改变任何内容时，会通过 ctx.llm.stream(...) 派发一个全新请求——冻结的循环构建请求和已存储的会话保持不变；只有面向提供方的视图发生变化。
- 在 protect 模式下，序列化预算被限制为镜像适配器的 maxRequestImageBytes，因此官方 rc.8 适配器通常看到的是一个已经安全的请求，不会执行第二次、不可见的最旧优先移除。
- 如果投影本身失败，会走一条刻意简化的应急路径，剥离每一个图像叶子节点。该防护绝不会静默回退为发送超大原始请求。

安装

dsh plugin --profile  add dsh-media-guard

之后重启该 profile。该 bundle 会向 DSH 现有的 home composer 状态栏插入一行 media-guard；默认配置无需任何设置。

直接从 git 主机安装（dsh plugin --profile  add github:spyfree/dsh-media-guard）会通过该包自包含的 prepare 脚本构建 dist/；pnpm ≥ 10 会在首次安装时要求你在该 profile 的 pnpm-workspace.yaml 中允许该构建，正如 DSH 的打包指南所述。

默认行为

- 在每次 agent-loop 提供方请求之前以 protect 模式运行。
- 应用保守的默认预算：8 个媒体块，2 MiB 序列化（Base64）/ 1.5 MiB 解码后总量，每张图像 512 KiB 序列化大小。
- 优先保留当前轮次的媒体，而非较旧的媒体；优先保留用户媒体，而非工具媒体。
- 按内容地址对相同图像去重；后续副本变为重复说明。
- 将溢出的媒体叶子节点替换为确定性的 Evidence Notes（哈希、大小、尺寸、来源、原因——不编造描述，不包含指令）。
- 保留消息数量、顺序、角色、id、来源以及工具调用/结果配对。
- 在每次受防护调用后发出 media-guard/report 事件，并为报告 UI 保留有界的、仅含元数据的内存历史；绝不记录或发出图像字节。

默认预算是一种保守的优化策略，并非对任何提供方最大请求体大小的声明。它远低于 DSH 官方适配器默认的 20 MiB，因此 Media Guard 会先行动，而核心辅助程序通常是无操作。只有在同时考虑路由实际适配器上限的情况下，才按路由提高该值。

配置

从你的 profile 的 cordis.patch.yml 中，通过针对该行 id 的扁平 patch 条目覆盖插件行（与 DSH 自身 bundle 使用的形式相同）：

- id: media-guard
config:
mode: protect            # observe | optimize | protect
log: false               # true prints a one-line summary per projection
budget:
maxMediaBlocks: 8
maxSerializedMediaBytes: 2097152
maxDecodedMediaBytes: 1572864
maxSerializedBytesPerImage: 524288
adapterMaxRequestImageBytes: 20971520 # mirror adapter setting; rc.8 default
profiles:                  # keyed by the request's provider route id
my-vision-gateway:
maxSerializedMediaBytes: 12582912
maxDecodedMediaBytes: 9437184
adapterMaxRequestImageBytes: 12582912 # 与此路由的适配器保持一致
statusPollIntervalMs: 2000 # 主页行的刷新频率

profiles 条目比顶层 budget 更具体，因此对于它声明的字段，即使两者都已设置，它也会在其路由上优先生效。adapterMaxRequestImageBytes 不会配置 DSH 的适配器；请从该适配器的路由配置中镜像该值。Media Guard 会将其解析后的 maxSerializedMediaBytes 限制为匹配的全局值或路由值。全局默认值为 20 MiB，与官方 rc.8 Pi AI 和 DeepSeek 适配器一致。如果某个适配器配置的值低于该值，请在此处镜像其较低的值；如果第三方适配器有不同的上限，请显式声明该路由。

模式：

- observe：仅清点和报告；
- optimize：压缩但不外部化；
- protect：先压缩，然后外部化超出容量的媒体（默认）。

在 observe 和 optimize 模式下，超出预算的图片会故意保留在 Media Guard 之后，因此官方适配器仍可能应用其自身的最旧优先卸载策略。报告描述的是 Media Guard 的输出，而不是之后仅由适配器执行的步骤。当 UI 必须描述最终图片选择时，请使用 protect 并正确镜像上限。任何插件都无法内省部署定义的适配器设置，因此非默认适配器上限必须在配置中镜像。

enabled: false 会完全绕过该防护。每个配置字段都会单独验证；无效值会回退到其保护性默认值并被报告——损坏的配置绝不会放宽预算或关闭该防护。

与 Pi 原版不同，这里没有内置的提供商配置文件：DSH 提供商路由由部署定义，因此在你为其声明配置文件之前，每条路由都会获得保守的默认值。

报告 UI

DSH 主主页现在在编辑器下方带有一个紧凑的实时 Media Guard 行，
位于与 DSH 自身统计行相同的 conversation.composer.dock 条带中。它的作用域为活动会话，从该会话的仅元数据报告端点刷新，并显示当前压力、保留的图片数、序列化媒体预算、压缩、去重或外部化计数，以及当原始请求超出预算时的 input over limit 标记。
例如：

media near limit now · 4/4 images kept · 1.5M/2.0M · 2 compressed · input over limit

这是主要的概览界面；它不会打开新页面。

当配置文件包含 DSH 的 Web 服务器时（正常的 web 配置文件），打开：

http://:/media-guard

该页面是详细的可选视图：它显示进程生命周期总计以及最近 100 个受防护的请求。它使用配置的刷新频率轮询位于 /media-guard/api/reports 的同一个只读 JSON 端点。主页行会添加活动会话的 sessionId 查询参数；详细页面则有意不添加它
关闭，因此显示的是进程级历史记录。两个界面都只包含元数据；报告历史保存在内存中，DSH 重启时会重置。
主行节奏通过 statusPollIntervalMs 配置；API 将经过验证的值通告给浏览器 bundle。
会话范围内的最新摘要最多保留最近 100 个会话身份；进程级总计保持为生命周期总计。
在无头配置中，可选路由根本不会被注册，而守卫和 media-guard/report 事件继续正常工作。

市场发现

该包在 package.json 中声明其 DSH bundle、服务器插件类型、可选的 Web 服务器对等依赖以及隐私披露。GitHub 仓库带有 DSH 市场扫描器使用的 dsh-plugin 主题；推送后，基于主题的市场通常会在下一个索引周期刷新它。不使用安装脚本——官方配置包流程会构建并注册 cordis.patch.yml。

匿名回归

测试套件复现了最初的四个图像失败分布：

1.82 MB + 0.74 MB + 1.21 MB + 2.80 MB = 6,567,972 Base64 bytes

在没有编解码器的情况下，protect 会确定性地使请求低于默认的 2 MiB 聚合预算。该回归的确定性编解码器在 1,600,000 个序列化字节下保持所有四个视觉输入可用；随附的 sharp 编解码器会单独针对相同的序列化字节契约进行测试，并且当无法达到目标时始终回退到正常的外部化。

开发

需要 Node.js 22.19 或更高版本，与 DSH 自身的 engines 要求一致。

npm install
npm test
npm run typecheck
npm run lint
npm run build

安全与隐私

插件以用户的完整本地权限运行。安装前请审查代码。此插件仅通过 DSH 经过验证的附件 API 读取压缩候选内容，通过同一 API 存储压缩变体，不发送任何遥测数据，并且从不记录附件内容、载荷或凭据。报告和诊断信息仅包含元数据。存储的变体遵循附件存储的保留策略；内存中的报告历史在重启时重置。

许可证

MIT