dsh-szg-hint
English | 中文
旁路提示插件：任务执行中插一句话，AI 下一步即刻参考——不打断任务、不污染对话历史。
用户在一次任务执行的过程中插一句话，AI 下一步就参考到，任务不被打断、主对话历史不被污染。
提示只随某一步请求出现一次，随后标记为已参考（前端收到回执）。
与官方 Agent.steer() / Agent.inject() 的区别：那两条通道的消息会进入会话历史（见
agent/inbox/claimed），本插件的注入走 agent/pre-step 只追加进当前这一步的请求，
不调 session.append——所以刷新页面后聊天区看不到它，模型也只看到一次。
安装（任选其一）：
# 从 npm（发布后）
dsh plugin --profile web add dsh-szg-hint
# 从 GitHub 源码（pnpm ≥10 需按提示授权构建脚本，首次 add 会失败并给出确切包键）
dsh plugin --profile web add github:<owner>/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。
半边职责
| 半边 | 职责 |
|---|
Host（src/index.ts + src/store.ts + src/protocol.ts） | 队列（JSONL 落盘）、数据面路由 /dsh-szg-hint/*、agent/pre-step 注入、运行态订阅（turn/start / turn/end）、hint_send / hint_status 工具 |
Client（src/client/） | ./link.ts 一条宿主链路（SSE + 降级轮询 + 写操作），HintBar.tsx 工具行右侧的紧凑入口（conversation.input.right，28px 圆钮 + 上弹面板）：待参考计数角标、输入面板（Enter 发送 / Shift+Enter 换行）、待参考列表与撤销、最近已参考、右上角轻提示 |
两侧共用 src/protocol.ts 的类型契约（只有类型，没有运行时代码）。
数据落 $DSH_HOME/dsh-szg-hint/hints.jsonl（append-only 事件流：put / del 两态，启动回放即得当前
状态；行数超过 2000 自动压缩成「待消费 + 最近 20 条已消费」）。consumed 落盘的意义是重启不重复
消费：模型已经看过的提示不会再灌一遍。
数据通道
| 通道 | 用途 | 行为 |
|---|
GET /dsh-szg-hint/events（SSE） | 主通道 | 状态一变推一帧 event: state（完整快照，含 revision）；动作推一帧 event: hint（added / consumed / cancelled，供轻提示）；开通道先写注释行与 retry，之后每 25 秒一条 : ping。空闲时零流量 |
GET /dsh-szg-hint/state | 轮询兜底 | 返回同一个快照，供 SSE 不可用（老宿主 / 代理干扰）时降级；4 秒一次，连续失败降频到 12 秒 |
POST /dsh-szg-hint | 入队 | 先过信任围栏（见下节）；body { text, sessionId? }（sessionId 留空 = 全局）；返回 { ok, hintId, running, dropped }；running 说明「该会话此刻是否在跑回合」，前端据此选文案 |
DELETE /dsh-szg-hint（body { id }） | 撤销 | 待参考可撤；已被参考返回 409、不存在返回 404（中文原因，前端直接展示）。DELETE /dsh-szg-hint/<id> 是同一动作的路径形式，方便 curl |
浏览器半边只有一条应用路径（normalizeSnapshot + 状态替换），「推来的」与「拉来的」在组件看来完全一样；
动作帧只用于弹轻提示（按「动作 + 提示 id」去重，SSE 重放不会重复弹）。页面不可见时整条链路断开（不占浏览器每源连接配额）。
信任围栏（数据面的来源校验）
数据面所有路径（state / events / POST / DELETE）在分派前统一过宿主的连接信任围栏：
取 connection 服务的 requestRejection(req)，403（Host 不受信）与 401（浏览器未认证）都按原状态码回绝，
只有已认证的页面（带签名会话 cookie）才放行。
为什么不能只靠同源校验：sameOrigin 只检查「带外站 Origin 的浏览器跨站请求」，
不带 Origin 的本地进程（脚本、别的应用）会被直接放行——于是任何本机程序都能读走用户的提示正文与所在会话，
也能 POST 一条提示；而提示会作为 plugin 消息进入正在执行的任务，等同于任意指令注入。来源校验必须落在服务端。
connection 是硬依赖（写在 inject 里），但按结构取值（Reflect.get）而不引入跨包类型依赖；
取不到该服务时每个请求回 503 并在 stderr 说明，而不是静默放行。- 浏览器半边无需改动：同源请求自带 cookie，SSE、轮询与写操作都直接通过。
- 单独部署到「没有
connection 服务」的宿主时，需自行在网关层补认证，否则数据面不可用（503）。
注入语义
- 扩展点：
agent/pre-step waterfall——与记忆插件的逐轮段同一个钩子（系统提示词装配之后、模型请求之前），
但每一步都检查：任务跑着的时候用户随时可能发提示，下一步就该看到它，无论那是第几步。
- 注入形态：一条
plugin 来源的 user 消息（source.plugin = 'dsh-szg-hint'，form: snapshot，段名「旁路提示」），
追加进本步消息序列；它不写进对话历史，只在这一步出现。
- 归属：按 pre-step 负载里的会话取（
payload.agent.session），命中该会话的与全局（sessionId = ''）提示，
最旧优先，单步最多 20 条。拿不到会话 id 时只取全局——「拿不到归属」不等于「可以把别的会话的提示喂过来」。
- 原子性：取走即标记
consumed（同步执行、中途无 await，等价于源侧的事务 SELECT+UPDATE）；
构造注入消息失败会回滚成待消费，下一步重试——绝不出现「标了已参考、模型却没看到」。
- 回执：注入成功推
hint 帧（kind: consumed），前端弹「AI 已参考你的提示」。
Model Experience
-
模型看到什么：一条用户角色消息，正文形如
📌 旁路提示（用户在任务执行过程中插入，不占对话历史，仅本条可见）
请在本步参考下面的要求，然后继续原来的任务；不要停下来等待确认，也不要把它当作新的用户回合。
1. <提示正文>
单条正文超过 600 字会截断展示（队列里保留全文，上限 2000 字）。
-
token 成本：只在有提示的那一步增加一条消息（空队列时不注入任何东西，也不会造成「每步都变」的
缓存抖动）。多条同时到达时合并成一条消息，最多 20 条。
-
KV 缓存：未消费队列为空时，本插件对请求零影响；有提示时该步的消息序列尾部多一条，之后各步
恢复到原序列（提示不再出现第二次）。
-
模型可用的动作：hint_send（向指定会话投递提示，默认落到自己所在会话）、hint_status（查看
待参考与最近已参考）。
工具（模型侧）
| 工具 | 用途 |
|---|
hint_send | 投递一条提示到某会话（留空 sessionId = 当前会话）：{ text, sessionId? }。返回 id、是否即刻生效（目标会话是否在跑）、以及是否因该会话积压上限挤掉了最旧一条 |
hint_status | 查看队列：{ sessionId? }（留空 = 当前会话，* = 全部会话）。返回待参考明细、该会话是否在跑、最近被参考的提示 |
配置
| 键 | 默认 | 说明 |
|---|
enabled | true | 关闭则不注册路由、工具与事件订阅 |
dshHome | '' | 留空取 DSH_HOME，再退回 ~/.dsh |
maxPerStep | 20 | 单步最多消费几条（与源侧一致，防队列积压刷爆上下文） |
maxContentChars | 2000 | 单条正文上限（码点，超出截断） |
maxPendingPerSession | 20 | 单会话待消费上限；超出挤掉最旧一条并在写入响应里报告 |
keepConsumed | 20 | 快照里保留的最近已参考条数（也是压缩时保留的条数） |
heartbeatMs | 25000 | SSE 注释心跳间隔 |
挂载与重建
本包自带 cordis.patch.yml（insert 一行 id: dsh-szg-hint），dsh plugin add 会把它登记成
profile 的一个 bundle 层。新增条目不会被 patchReload 热更新，必须重启 dsh web。
npm run typecheck # tsc --noEmit（host 与 client 一起看）
npm run build # tsdown → lib/index.js（宿主）+ lib/client.js（浏览器）
- 改
src/client/：重建 lib/client.js 即按内容哈希热更新，不必刷新页面。
- 改
src/index.ts / src/store.ts（宿主半边）：必须重启 dsh 宿主。
测试
| 用例 | 覆盖 | 命令 |
|---|
tests/store.spec.ts | 队列契约（12 例）：原子消费不重复、最旧优先与单步上限、会话/全局作用域、拿不到会话时只取全局、撤销三态、注入失败回滚、单会话上限与 dropped 报告、空白拒绝与截断、运行态信号、重启后不重复消费、坏行跳过、快照口径 | npm test |
tests/host-runtime-probe.mjs | 宿主接线（10 项）：ESM 可导入、导出契约（name / inject / Config / apply）、路由前缀、两个工具、两类订阅、注册全部走 ctx.effect | node tests/host-runtime-probe.mjs |
tests/behavior.spec.ts | 行为（19 例，需先 build）：真实 HTTP 数据面（入队 / 快照 / 撤销三态 / 空白与跨站拒绝）、注入语义（会话+全局合并与编号、consumed 不重复、会话隔离、拿不到会话只取全局）、本步被下游拒绝时回滚待下一步、并发取走不重复、积压上限与超长截断、重启不重复注入、坏行容错、模型侧工具契约，以及信任围栏四条（放行 / 401 拒读 / 401 拒写且不落库 / 403） | npm test |
tests/artifact-check.mjs | 产物质检：两半产物对宿主契约的遵守（导出 / 路由前缀 / 依赖外部化 / CSS 内联 / 路径同源）、package.json 声明的入口文件存在性、双语 README 对等（两侧互链 + blob 哈希与 README.i18n.yaml 记录一致） | npm run test:artifact |
Known Limitations and Deferred Work
- UI 文案是中文硬编码：界面语言不跟随宿主 locale，要支持多语言需整体走 locales 抽取。
- 只做文本提示：图片 / 录音转文字再发提示需要额外的附件管道，dsh 输入区的附件通道可直接用。
- 提示不进对话历史，因此刷新页面后聊天区看不到它；待参考与「最近已参考」由快照提供（不落前端历史，
因此也没有跨浏览器持久化）。
- 运行态来自
turn/start / turn/end：宿主重启后内存里的「在跑」集合清空，第一次 turn 事件前
running 为假（文案退化为「下个任务参考」，提示本身照常入队）。
- 多会话并行时 SSE 推的是全局快照，前端按自己的会话过滤；跨会话的动作帧（别的标签页发的提示）
不会在本标签页弹提示。
许可
MIT（见 LICENSE）。插件按 dsh 的插件协议扩展宿主，不改任何官方源码；宿主升级时以
agent/pre-step 与 ctx.tools / webServer 的公开契约为界。
