dsh-session-toolkit

dsh plugin --profile web add dsh-session-toolkit

dsh-session-toolkit

[English](README.md) | 中文

DeepSeek Harness 的整合插件工具箱。将先前 5 个独立的本地插件——会话身份、全局提示词、会话自动恢复、Session log 按钮平移、会话间消息——合并为单个可安装包(官方 bundle 形态,dsh.bundle.patch),通过 dsh plugin add 安装;另含提示词去重(Prompt Dedup)功能。

当前版本:1.0.0,已对照 DeepSeek Harness dsh-v0.2.0-rc.1 验证——它同时是最低支持版本(契约面 + 全套门,非完整功能回归):0.1.6 及更早会响亮失败而非静默降级(见[兼容性](#compatibility))。

---

功能

会话身份(Session Identity)

每会话人设提示词注入该会话系统提示词(独立段 session-identity,order 40,每次组装按 agent 求值),支持默认身份与每会话覆盖。UI:身份浮层(启用开关、4000 字符软上限、保存/重置、编辑默认身份、继承默认身份)及双入口状态按钮:conversation.session.header.actions(id session-identity,order 40)与 conversation.input.left(id session-identity-input,order 40)。浮层卡片可按标题行拖动:位移每次移动都被钳制在视口内、窗口缩放时重新钳制;卡片比视口大时每个轴都仍可移动,四个边都能拖到。位置不持久化,浮层关闭即复位。

全局提示词(Global Prompt)

设置页(settings.section,id global-prompt,order 30),以 Tabs(全局 / 按工作区 / 组) 渲染。全局 Tab 注入一段作用于所有会话系统提示词的文本(段 global-prompt,order 50);按工作区 Tab 注入按工作区提示词(段 workspace-prompt,order 60);组 Tab 注入按组提示词(段 group-prompt,order 55——见[组提示词](#组提示词group-prompt))。五个提示词段——session-identity(order 40)、peer-inbox-discipline(order 45,见[会话间消息](#会话间消息peer-messaging))、global-prompt(order 50)、group-prompt(order 55)与 workspace-prompt(order 60)——都以 interpolate: false 注册:提示词文本与引用文件里的 {{...}} 一律按字面保留,用户内容永不被改写,未注册的 {{name}} 也不可能让组装失败。0.1.6 之前的内核没有分段的 interpolate 开关,由 lib/prompt-literal.js 在组装结果上退化为 { 连续串空格化。

同一个 webServer 上另注册只读状态路由 GET /api/session-toolkit/state(活跃工作区 + 引用文件读取状态 + 组选择器要用的在线会话清单;非 GET 一律 405),设置页据此读取这些运行时投影——它们不占 settings 命名空间、也从不落盘。

工作区提示词(Workspace Prompt)

为 cwd 前缀匹配到已配置工作区目录(该目录及子目录)的会话注入按工作区提示词。工作区列表由活跃会话的 cwd 聚合而来(ctx.agents.roots(),去重并按会话数计数)。当多个已启用工作区前缀命中某会话的 cwd 时,取最具体(路径最深/最长)者。removed 记录用户已移除的路径,使活跃工作区同步不重新补回。工作区行的启用开关 即时保存(live-save);「保存」按钮仅持久化提示词内容 + 引用文件。

组提示词(Group Prompt)

设置页上的第三个 Tab:组。每个组是一条具名条目:启用开关、提示词正文、引用文件列表,以及显式的成员会话 id 列表;匹配依据是该会话自己的 id,不是它所在目录——这正是「一个组可以跨工作区」的原因。组是额外的一层:它不取代全局提示词,也不取代按工作区提示词。所有启用且 sessions 含当前会话 id 的组都注入到段 group-prompt(order 55,夹在全局 50 与工作区 60 之间),命中的多个组按组键序拼接,块与块之间留一个空行。选择器只列在线(live)会话,且从不自动入组:新会话在你勾选之前不属于任何组;已存在组里但当前离线的会话标为未在线(可移除)。组装上下文里取不到会话 id 时,该段注入空。

引用文件(Referenced Files)

全局提示词、工作区提示词与组提示词均可引用文件列表。每次组装重新读取每个引用文件(UTF-8;按 mtimeMs + 大小缓存,未变化的文件不重复读盘),注入到提示词文本之后。有字节预算(globalPrompt.maxFileBytes / maxTotalBytes,默认 256 KiB / 1 MiB):超限文件跳过而不是阻塞组装。读取失败同样跳过,两种情况都在 UI 中显示具体原因。支持纯文本/markdown。每个文件的读取状态是 host 的运行时投影,经只读路由 GET /api/session-toolkit/state 送到 UI(ok:N 字符 / fail:原因 / 未读取),浏览器半只在设置页打开期间轮询它;状态不写入任何配置文件,内容未变时不重建投影。

会话自动恢复(Session Auto-Resume)

开启开关的会话在 GUI 重启后自动恢复,优先走官方恢复链路(ctx.sessionController.resolveAgent)——它除了 mount preset,还会通过 installSelection 恢复会话自己的模型选择,并做 subagent 归属校验与并发恢复去重;0.1.6 之前没有该服务的内核回落为 ctx.agents.resume + 手工 mount preset,并携带 agentDefaultModel 的默认模型。开启某会话即立即恢复(false→true 边沿)。过滤:开关开启、仅顶层(无 subagent origin、无 delegationDepth > 0、无 parentSession)、非空白(快照形状的 eventCount !== 0)。并发受限(缺省 3,可由 autoResume.concurrency 配置),逐项失败隔离 + 在途集合防重复恢复。

同一个 webServer 上另注册只读状态路由 GET /api/session-toolkit/state(活跃工作区 + 引用文件读取状态;非 GET 一律 405):设置页靠它拿这两项运行时投影,因此它们不再占用 settings 命名空间,也不落盘。

Session log 按钮平移(Session-Log Button Relocation)

遮蔽 conversation.session.header.utilities 中的官方条目(同 id session-log-download,priority −1,cell shadowing),并在 conversation.session.header.actions 注册副本(id session-log-download-moved,order 41),复用官方 sessionLogDownload controller(ctx.get('sessionLogDownload')),下载行为与官方一致。副本对齐 0.1.6 的官方形态——「⋯ 更多操作」菜单(单条「下载 Session 日志」)触发共享对话框(文案走本插件自己的 locale 命名空间);它是冻结的复刻件:官方改版必须人工同步,官方条目新增菜单项时也要重新核对遮蔽策略。

会话管理(Session Admin)

host 平面另注册两个工具,与 send_to_session / list_sessions 同平面:

• create_session —— 自主创建一个新的顶层会话(GUI 左侧导航里的一个聊天窗口)。cwd 与 prompt 均必填:cwd 必须是绝对路径(无 cwd 的会话不会进宿主列表),prompt 是新会话的首条消息。创建成功即产生一条真实用户消息(会真实跑一轮模型、消耗一次调用);按内核设计,产生过事件的会话会被持久化,因此本工具不提供「只登记、不说话」的临时会话。可选 title 会立即设定标题并 pin 住。返回体含 sessionId、cwd、status、title 与 notes。
• rename_session —— 修改一个在线(live)会话的标题。改名会 pin 住标题,不再被自动标题生成覆盖。目标必须是顶层会话且当前在线:目标是子会话(origin=subagent 或 delegationDepth>0)时明确拒绝,不静默改写。

两者都以结构化结果返回(工具执行本身不抛未捕获异常):成功 { ok: true, … },失败 { ok: false, error: '<码>', errorText: '<原始原因>' }。错误码:MODEL_UNAVAILABLE / MODEL_SELECTION_FAILED / MODEL_SELECTION_INVALID / EMPTY_CWD / CWD_NOT_ABSOLUTE / EMPTY_PROMPT / PROMPT_TOO_LONG / PRESET_RESOLVE_FAILED / CREATE_FAILED / CREATE_UNAVAILABLE / CREATE_NO_AGENT / EMPTY_TARGET / EMPTY_TITLE / SESSION_UNAVAILABLE / TARGET_IS_SUBAGENT / TITLE_SERVICE_UNAVAILABLE / UNEXPECTED。

(prompt 缺失由内核工具参数校验在框架层拒绝——内核把它转成工具错误结果，该异常不经本插件代码；prompt 传了但纯空白才由本插件返回 EMPTY_PROMPT。两者都不创建会话。)

两处如实声明:

• 可见性未在工具内验证 —— 「带 prompt 建出的会话会出现在左侧导航」取决于内核是否真正开跑一轮(导航按「空白会话」判据过滤,该状态只在 turn/start 时翻转;followup 只是入队并唤醒驱动)。因此返回体不下「已出现在导航」的结论,notes 会写明这一点。
• preset 降级 —— agentPresets 服务存在但默认 preset 解析失败时,工具返回 PRESET_RESOLVE_FAILED,而不是交付一个没有 preset 的残缺会话;服务整体缺失属合法降级,会话照建并带说明性 notes。

会话间消息(Peer Messaging)

host 平面注册 send_to_session / list_sessions 工具(按 id 或工作区路径寻址会话、wakeup 投递),并在 conversation.session.header.actions(id copy-session-id,order 30)与 conversation.input.left(id copy-session-id-input,order 30)各加「复制会话 ID」按钮。发出消息内容在投递前经 toPlainText 转为纯文本,接收方看到整洁文本而非原始 markdown。wakeup 有两条不同的投递路径:wakeup: true(走 steer)时,目标正在执行 ⇒ 消息进当前轮的下一个步边界(既不新开一轮,也不打断当前步);目标空闲 ⇒ 立刻开一轮;wakeup: false(走 inject)只投递、不唤醒任何人。两种情形仍会排队而不是插入:投递时目标空闲(没有步边界可插,消息在下一个轮次边界被收下),以及内核的 wakingAfterAbort 重分类(上一个活动正在被取消时,steer 被静默降级为 next-turn)。因此 steer 不是「消息永不等待」的承诺——判断一条消息是否真的插入,要看三件事同时成立:target 是 next-step、投递时有轮在跑、且投递到消费之间没有新的 turn/start。

提示词去重(Prompt Dedup)

对 身份 / 全局 / 组 / 工作区 四段系统提示词(段 session-identity、global-prompt、group-prompt、workspace-prompt,order 40/50/55/60)做跨段行级去重。promptDedup.enabled 默认开启(仅显式设为 false 时

…(truncated)