Ryuu-64/dsh-session-tools

让对话里的 AI 能新建会话、给别的会话发消息、看看有哪些会话，以及等别的会话干完活。

四个工具，session_create、session_send、list_sessions、session_wait。新会话会出现在左侧会话列表里，和手动新建的完全一样；想让它归到某个工作区下面也可以。

典型用法：你说"帮我开一个会话去查一下这件事"——AI 直接建好，不用你自己新建再复制粘贴。或者你已经有一个会话在跑，说"等它弄完把结果告诉我"，AI 把活派过去，等它做完了再回来接着讲。

session_create：新建会话

参数	是否必填	说明
prompt	必填	新会话要做的第一件事。新会话看不到当前这个会话，所以要把背景写全。
workspacePath	可选	工作区的完整路径。填了，新会话就归到这个工作区下面；不填就是未分组。
title	可选	会话标题。不填就和手动新建一样，由第一句话自动生成。
wait	可选	默认不等。只有一种情况需要等：你要在新建的那个会话跑完第一轮之后才继续。

| timeoutMs | 可选 | wait=true 的等待预算（毫秒），默认 60000，最多 300000。 |

做完返回新会话的名字和 id，你在左侧列表里就能看到它。首次消息投递前失败会清理未完成的创建；投递成功后，等待超时、取消或读取错误都不会删除或停止独立目标会话。

session_send：给别的会话发消息

参数	是否必填	说明
sessionId	必填	目标会话的 id，形如 session-9311a0fb-65c7-4b04-b142-1444642a627e。
message	必填	要发的内容。对方看不到当前这个会话，所以要写清楚。
wait	可选	默认不等：发出去就返回。填 true 就等对方把这条消息处理完，并把它的回答带回来。
timeoutMs	可选	等多久（毫秒）。默认 60000（一分钟），最多 300000（五分钟）。等超了不报错，只告诉你"它还在忙"。

默认发出即返回，返回只代表对方收到了、开始排队处理。消息来源标记为插件，不会被当成是你本人打的字。目标会话如果没开着，会被自动打开再把消息排进去。

填了 wait 就变成"发完等它做完"，AI 拿到对方的回答之后可以接着往下办——比如让一个会话去跑测试，跑完再根据结果决定下一步。当前等待先检查消息已离开队列，再观察会话空闲。这不等同于已经证明某条消息对应的 turn 成功完成；精确的消息与结果归属由 #3 单独处理。

session_wait：等别的会话干完

如果消息已经发出去了，或者那个会话本来就在忙，用这个等它收尾。

参数	是否必填	说明
sessionId	必填	目标会话的 id。
timeoutMs	可选	等多久（毫秒），默认 60000，最多 300000。

它只负责等和看，不去动那个会话：不会打开它、不会改它、也不会打断它。对方本来就没在忙的话，立刻返回，把最后一条回答给你。等超了就说一句"还在忙"，不算失败——你可以过会儿再问一次。

等待结果与取消

三个等待入口统一默认 60 秒、最多 300 秒；省略或非正数使用默认值；类型不符及非有限数由参数校验拒绝。正的小数至少为 1 毫秒。预算从开始观察起计算，包括只读查询和结果读取，不包括审批或创建阶段。

• waitStatus=completed / completed=true：本次空闲观察和读取完成，不代表目标业务任务成功
• waitStatus=timedOut：等待预算耗尽
• waitStatus=callerCancelled：调用方取消本次等待
• 后两种情况 completed=false，仍返回 sessionId 回执，不自动重发、不取消目标任务，也不返回可能过时的答案；可稍后用 session_wait 再查询

每次等待结束都会清理自己的计时器和取消监听器。真实 rc.2 持久化冷读使用只读句柄并传入取消信号，结束时关闭句柄；仅提供旧查询服务的兼容宿主，其不可取消读取由宿主自行管理，但不会延长本次等待预算。rc.2 的 whenIdle() 不接受取消信号，因此只停止观察它，不对目标调用 cancel 或 dispose。

list_sessions：先看看有哪些会话

不用记 id。当你要说的是"发给那个讨论发布的会话"，AI 可以先列出会话（名字、目录、哪个是当前会话、现在在干什么），你说清是哪一个，它再发。

参数	是否必填	说明
limit	可选	最多列几个，默认 20，按最近活动排序。

每条会带一个状态，就是侧边栏上显示的那个东西：

状态	意思
running	进行中，正忙着。
idle	空闲，没在干活（开着或者躺着都算）。
archived	已归档，你把它从侧边栏收起来了。

子代理会话不会列出来（那是 AI 自己派出去的活）。已归档的会话会列出来并标 archived——因为"已归档"只是你把它从侧边栏收起来了，它本身还在；AI 看到这个标记就知道那是你收起来的会话，可以据此决定要不要往里发消息。

limit 填得不合理会按合理值处理：填 0 或负数按 1 算，填超过 100 按 100 算，小数取整。

动手前会先问你

新建会话、或者往别的会话发消息，通常会先请求确认，写清它要干什么，比如：

允许一次：在工作区 E:\Users\Ryuu\Desktop 新建会话，内容是「查一下某件事」

只有本次明确返回“允许一次”才放行；拒绝、取消、没应答、服务缺失或无法判断权限时停止。仅当宿主公开权限接口明确返回 sandbox=danger-full-access 且 approval=never 时免确认。never 单独表示审批请求自动拒绝；例如 workspace-write + never 不会放行。宿主在工具执行前已有的拒绝规则仍然生效。

目标会话没开着时，确认前只读查询并检查目标；获准后重新检查，再恢复会话、发送消息。审批拒绝或取消不会激活目标。

只是等一个会话做完、或者列一下有哪些会话，不会弹卡：这两件事不往任何地方写东西。

建好的会话，卡片上点一下就能过去

做完之后，对话里那张卡片会变成「已创建会话」加一个按钮——点一下直接跳到新建的那个会话，不用去左侧列表里找。

（这一部分由插件的浏览器端负责渲染，所以旧的对话记录也会跟着变成可点。）

安装

dsh plugin --profile desktop add @ryuu-64/dsh-session-tools

从源码装：

git clone https://github.com/Ryuu-64/dsh-session-tools.git
dsh plugin --profile desktop add link:C:\path\to\dsh-session-tools

装完重启 DSH 就能用，不需要其它设置。用 link: 方式装的，改完源码要重启应用才生效。

使用限制

• 不会顺手新建工作区。workspacePath 必须是已经存在的那个工作区的路径；写错了它会报错，并把现有的工作区列出来给你挑。
• 不能给子代理发消息。目标必须是普通会话；AI 派出去的子代理要用 send_message。也不能给当前这个会话自己发。
• 关掉的会话要有工作目录才能唤醒。发消息时如果目标会话没开着，插件会把它重新打开；但如果那条会话没记录工作目录，就打不开、发不进去，会明确告诉你原因。
• 重启期间收不到。新建会话是立刻生效的；发出去的消息要等对方会话被打开处理，所以 DSH 得开着。等待也一样，DSH 关了就没法等。
• 归属定了就不能改。会话归到哪个工作区是记在账上的，建完之后没法在工作区之间搬。
• 需要桌面版。工作区归属靠桌面版才挂载的那个工作区服务，插件把它列为必需依赖，所以命令行无界面模式（headless）下这个插件不会加载。

开发与回归检查

测试基线固定为 DSH 0.1.5-rc.2。使用 Node 22.19.0（22 系列最低支持版本）或 Node 24：

npm ci --ignore-scripts --no-audit --no-fund
npm run check

package-lock.json 固定完整依赖图；开发依赖和 overrides 把宿主组件固定在同一 rc.2 基线，避免上游宽松 peer 范围混入其他预发布版本。安装无需生命周期脚本，仓库 .npmrc 也将其禁用。CI 在 Node 22.19.0 和 24 上各自执行干净安装、完整测试和语法检查，某一版本失败不会取消另一版本。

测试分层：

• 策略和边界单元测试：用小型服务替身覆盖输入校验、权限组合、并发和取消时序
• 真实宿主集成：临时配置经官方 Cordis Loader 加载真实工具运行时、AgentLoop、审批、工作区和 JSONL 持久化；仅模型请求和人工审批答复使用脚本边界，不发送真实网络请求或用户消息
• 发布物回归：运行 npm pack，从解包后的入口经 Loader 加载插件；读取磁盘中的创建结果，用打包的客户端、官方 SlotCore 与真实 React 验证卡片文字和导航回调。这是无浏览器渲染测试，不宣称覆盖完整桌面 UI
• 资源清理：测试拥有并关闭临时目录、Agent、读句柄和计时器；默认等待预算还通过独立子进程正常退出回归，不能依赖强制结束进程来通过

目前没有把上述结果外推为 DSH 0.2 兼容承诺；升级宿主基线需要另行验收。