前言¶

在 DSH 里跑长任务时，常见需求是「此刻想改方向，但不想打断当前回合、也不想多一条永久聊天记录」。官方通道 Agent.steer() / Agent.inject() 会把消息写进会话历史（经 agent/inbox/claimed），刷新后聊天区仍能看到。若你只想让模型在下一步看到一句补充说明，且只出现一次，就需要走 pre-step 注入而不是 append 历史。

下面介绍社区插件 dsh-szg-hint（维护者 skyyyyyk，分类 admin-security）：宿主侧队列与注入 + Web 客户端入口，数据面请求受宿主信任围栏约束。当前版本 0.2.0，自该版起支持粘贴、拖放或点选附图，图随提示进入下一步。

这是什么¶

dsh-szg-hint 是 DeepSeek Harness 的旁路提示插件：用户在任务执行过程中插一句话（可选图片），AI 在下一步请求里参考，任务不被打断，主对话历史不被污染。提示只随某一步出现一次，前端收到回执后标记为已参考。

注入走 agent/pre-step，追加进当前这一步的请求，不调 session.append；与记忆插件共用同一类钩子（系统提示装配之后、模型请求之前），但每一步都会检查队列。

架构上分为两半：Host（src/index.ts、store.ts、protocol.ts、images.ts）负责 JSONL 队列、路由 /dsh-szg-hint/*、agent/pre-step 注入与 hint_send / hint_status 工具；Client（src/client/）通过 SSE（失败时轮询）同步状态，在对话输入框工具行右侧提供灯泡入口与上弹面板。两侧共用 protocol.ts 的类型契约。

核心功能¶

旁路注入语义¶

• 扩展点：agent/pre-step waterfall。
• 注入形态：来源为 plugin:dsh-szg-hint 的 user 消息（form: snapshot，段名「旁路提示」），只在本步消息序列尾部出现，不写进对话历史。
• 归属：按 pre-step 负载里的 payload.agent.session 匹配该会话提示与全局提示（sessionId 为空）；最旧优先，单步最多消费 20 条。拿不到会话 id 时只取全局，不会跨会话喂提示。
• 原子性：取走即标记 consumed；构造注入失败会回滚为待消费，下一步重试。

模型侧可见正文示例（插件内为中文硬编码）：

📌 旁路提示（用户在任务执行过程中插入，不占对话历史，仅本条可见）
请在本步参考下面的要求，然后继续原来的任务；不要停下来等待确认，也不要把它当作新的用户回合。
1. 照这张参考图把配色改了
   附图 1：ref.png（1600x900，image/png，312 KB）

单条正文超过 600 字会在展示侧截断，队列内保留全文（上限 2000 字）。空队列时不注入，对 KV 缓存无额外抖动。

Web 界面（0.2.0）¶

• 入口：conversation.input.right，28px 圆形按钮，待参考计数角标（超过 99 显示 99+）。
• 输入：Enter 发送，Shift+Enter 换行；纯图提示在列表里显示「（图片提示）」。
• 附图：粘贴、拖到面板、点选文件；本地 image-prep.ts 压缩后上行；缩略图可预览，Esc 先关预览再关面板。
• 数据：SSE GET /dsh-szg-hint/events 为主，GET /dsh-szg-hint/state 为轮询兜底；页面不可见时断开链路。

图片提示（0.2.0）¶

浏览器端只接受 png / jpeg / webp / gif，必要时画布重编码（GIF 不重编码，超限报错）。入库经宿主 ctx.attachments.saveImages，整批成功才写队列；队列文件只存附件引用，图片字节不经 hints.jsonl。

默认限额（可用 cordis 配置覆盖，前端从快照 imageLimits 读取）：

宿主未挂附件服务时，imageLimits.enabled = false，前端禁用附图，纯文字提示不受影响；服务晚于插件就绪后会就地启用，不必重启。

若本步模型 inputModalities 不含 image，核心会把图投影为占位文字，并在能明确判定「看不到」时于正文追加只读副本路径提示（依赖附件服务的 imageHostPath）。

持久化与数据通道¶

队列落盘：$DSH_HOME/dsh-szg-hint/hints.jsonl（append-only，put / del；行数超过 2000 时压缩为「待消费 + 最近 20 条已消费」）。consumed 落盘用于重启后不重复灌给模型。

主要 HTTP 动作（均需过宿主信任围栏）：

• POST /dsh-szg-hint：入队，body { text, sessionId?, images? }。
• DELETE /dsh-szg-hint 或 DELETE /dsh-szg-hint/<id>：撤销待参考项。
• GET /dsh-szg-hint/image/<提示 id>/<序号>：按提示 id 与序号取图（序号从 0 开始）。

模型工具¶

安装与启用¶

环境要求：dsh >= 0.2.0-rc.2（0.2.0 消息来源使用 v4 的 plugin: 命名空间，更老宿主未验证）；Node ^22.19.0 或 >=24.0.0。图片能力依赖宿主附件服务。

任选一种安装方式：

# 从 npm
dsh plugin --profile web add dsh-szg-hint

# 从 GitHub 源码（pnpm ≥10 若因构建脚本被拒，按提示授权包键后重试）
dsh plugin --profile web add github:skyyyyyk/dsh-szg-hint

# 本地 checkout
dsh plugin --profile web add /path/to/dsh-szg-hint

装完后重启 dsh web。验证插件是否载入：

dsh --profile web --dump-config | grep dsh-szg-hint

打开对话页，确认输入框工具行右侧有灯泡按钮；若无，可对照 dump-config 与宿主日志中以 [dsh-szg-hint] 开头的行排查。

常用配置项（节选，默认均已启用）：

许可证：MIT（见仓库 package.json）。

典型用法¶

1. 任务已在跑时，点开灯泡，输入「配色改成品牌绿」并发送；模型在下一步参考后继续原任务，聊天区不会出现这条用户消息。
2. 截图后 Ctrl+V 粘贴到面板，或拖入图片，可发纯图或图文提示；待参考列表可撤销，注入成功后右上角 toast 提示「AI 已参考你的提示」。
3. 对编码智能体说：「给正在跑的任务发一条旁路提示：配色改成品牌绿」——若已安装本插件，可由 hint_send 等能力配合完成。

与官方 steer/inject 的选用：需要永久进历史、可回溯用官方通道；需要一步生效、不占历史用本插件。

适用场景与注意¶

适合：长回合编码或运维任务中临时纠偏；用截图指明 UI/报错位置；希望控制 token——仅有提示的那一步多一条消息。

注意：

• 插件在当前 dsh 进程权限下运行；安装前请自行审阅 GitHub 源码 与 MIT 许可证。
• 数据面与取图路由均受宿主信任围栏保护（未授权连接 401/403）；仍属 admin-security 类能力，勿在不可信环境随意暴露 Web 入口。
• 0.2.0 依赖较新宿主与附件服务；升级前建议在测试 profile 验证 plugin: 命名空间与附图链路。
• 社区目录 skillhub.cn 为独立生态站点，与 DeepSeek / 幻方无官方从属关系；星标与版本以仓库为准。

结尾¶

dsh-szg-hint 把「执行中改要求」做成 pre-step 旁路：不打断任务、不污染对话，0.2.0 起还可带图进下一步。需要试用或看实现细节，可打开目录页与仓库：

• 目录页：https://www.skillhub.cn/plugins/skyyyyyk/dsh-szg-hint
• GitHub：https://github.com/skyyyyyk/dsh-szg-hint