dsh 智能体如何作为服务、通过 HTTP/WebSocket 对企业后端提供多轮会话 API？

[HY-love-sleep]

背景

我们基于 dsh 开发智能体, 消费方是企业系统：自研前端 + 集团统一登录
（SSO），后端是部署在内网的 Java 服务。我们希望能把 dsh 作为一个独立服务
通过网络调用——Java 服务不会去拉起 Node 子进程，所以 SDK 的 stdio 通道
（dsh --profile sdk）不适用于我们。

我们需要的能力是带多轮上下文的对话聊天：会话持久化、token 级流式回传给前端、
支持中断/插话。终端用户身份由 Java 后端（SSO）认证后透传给我们，前端不直连 dsh。

我在源码里的调研结论

阅读已安装的包之后，看起来可行的路径是写一个自定义网关插件（我们自己的 bundle），
而不是直接暴露内置的 /api/* BFF：

• 用 ctx.webServer.register({kind:"exact",...}) 注册窄的服务路由，用
  ctx.webServer.registerUpgrade(...) 注册 WebSocket（dsh-host-webserver）。
  这些自定义路由不经过 /api 信任栅栏 / 浏览器 cookie 认证
  （dsh-client-connection），所以服务间鉴权（mTLS / 服务 token）由我们自己实现，
  做法类似 dsh-webhook-github。
• 驱动智能体：ctx.agents.create({sessionId, meta:{cwd}, agentOptions, setup}) /
  ctx.agents.resume(...)，用 agent.followup(createUserMessage(...)) 发消息
  （fire-and-forget），await agent.whenIdle() 等结束，并通过订阅
  ctx.on("session/event", ...)（assistant/chunk、turn/end 等）拿到流式输出，
  再把这些事件桥接到我们自己的 WebSocket，大致参照 dsh-api-session-controller
  里的 follow() 模式。
• 在 setup(agentCtx) 里收敛能力：tools.restrict({deny:["bash","write","edit"]})，
  只保留只读 / RAG / 对话类工具——因为一个网络可达的智能体绝不能持有 shell / 文件写权限。
• 我们注意到 dsh web 命令行显式拒绝 --host 0.0.0.0（RCE 警告），但 webserver
  配置本身支持该地址——所以我们打算通过自定义的服务化 profile 绑定内网网卡，而不是用
  桌面 web profile。

想请教的问题

想请教下社区的大佬们, 这种dsh作为服务给其他后端提供 api 能力, 最佳实践是啥

[argszero]

源级验证过你的大部分结论（master d347e70），你的方案与仓库里被认可的扩展形态一致。先说结论：你的架构 A（自定义窄网关 bundle）是正路，但有第二形态 B（复用首方 Remote/session-controller RPC 面 + 前置自己的鉴权）也值得权衡；另外你计划里的"插话/中断"需要从 followup 升级到两个更精确的原语。

你已验证的结论（均属实）

• ctx.webServer.registerUpgrade(...) 存在（dsh-host-webserver host/webserver/src/index.ts:180），自定义路由不经过 /api 信任栅栏与浏览器 cookie 认证——这正是该接缝的设计：栅栏（dsh-client-connection 的 api-request-trust）只保护首方 BFF；自定义路由的鉴权是插件自己的责任，dsh-webhook-github 就是参考实现（自带签名校验，不依赖任何栅栏）。
• agent 驱动面（core/agent/src/runtime-types.ts）确含 followup(message)（:168）、whenIdle()（:137）等。api-session-controller 的 assistant-stream.ts（"Process-local assistant state retained for reconnecting Web followers"）就是你引用的 follow 模式的正主。
• ACP（packages/acp）= "Automation-only Agent Client Protocol server over JSON-RPC stdio"——与 SDK 一样是 stdio 通道，按你的约束（Java 服务不拉起 Node 子进程）同样排除，你的排除判断正确。

需要升级的两个点

1. "中断/插话" ≠ followup。 followup 只是排队一个普通 turn 并唤醒 driver；它无法打断正在生成的回复。agent 面上还有两个更精确的原语（同文件）：

• steer(message)：向最近一个 step 边界提交转向输入——正在跑的 driver 在下一个 step 边界消费（不中止当前 step）。适合"话说到一半要改方向"的插话。
• cancel(cause, { keepInbox })：中止当前活跃 turn / between-turn 任务（首个 cause 生效）；keepInbox: true 保留已排队工作。适合"停止按钮"语义——中断当前流式回复，之后用 followup 起新 turn。
  所以你的网关协议需要把前端"打断"映射成 steer（温和改向）或 cancel+followup（硬停重启），并透传对应的终止原因给会话（turn/end 的 reason 会带上）。

2. 能力收敛：组合优于限制。 tools.restrict({deny:[...]}) 是第二道防线，不是主防线。cordis 的能力 = 挂载的插件；一个网络可达的服务 profile 应根本不挂载 shell / fs 写 / 浏览器类插件（cordis.yml 组合面裁剪），这样不存在可被 deny 漏掉的工具。restrict 保留给"同一插件集内的临时收窄"。

多用户形态的隐含前提（源码里没有现成答案）

会话是单写者（每会话一个活跃 driver；并发 followup 会按 inbox 顺序排队）。这在单用户 chat 场景没问题，但你的网关是 SSO 多用户：

• 用户隔离由你建：树内没有 per-user 会话 ACL——用户↔会话的映射、每个用户各自的会话命名空间都必须由网关层维护（每个用户建自己的 sessionId，不要跨用户共享）。
• 每会话串行：同一会话的 turn 队列天然串行（driver 逐个消费）；不同用户的"插话"互不影响（各自会话）。
• 读侧归因对你是好消息：自定义路由的 handler 直接拿到原始 Request（不像 Remote RPC 派发那样丢弃 HTTP 请求——那是 A plugin serving an RPC endpoint cannot see the request that called it #5790/WebSocket-dispatched Remote invocations carry no request context #5791 的已知缺口），所以你的 SSO 透传头（X-Forwarded-User 之类）在插件代码里可读，按用户路由即可。
• 会话持久化免费获得：会话是 durable 的（磁盘 JSONL），ctx.agents.resume 按 id 恢复——网关重启不丢上下文。

形态 B 供权衡（复用首方 RPC 面）

你不必从零桥接：web UI 后端（dsh-api-session-controller 的 remote + follow/stream）就是"会话创建/续跑/流式/控制"的完整实现。形态 B = 挂载首方 Remote BFF 但不挂 dsh-client-connection（栅栏/cookie 都随它），在它前面放你自己的鉴权代理/插件。收益：复用经过测试的 follow/assistant-stream/事件投影管线，少写桥接；代价：暴露面是通用 RPC 全集（含清单/历史类方法），你需要在代理层做方法级 ACL——表面控制不如形态 A 精细。两种都成立；社区插件生态里两种都有先例（webhook-github = A；把 api-remotes 当服务面的 BFF 用法 = B）。

一个安全提醒

自定义路由绕过栅栏 = 你就是栅栏。内网绑定（webserver config 支持非 loopback，CLI 拒绝 --host 0.0.0.0 只是便捷命令的安全门）必须配合：TLS 终止 + mTLS 或服务 token（防内网横向）+ 每会话速率/额度（防一个用户打爆共享 host）。你的"服务 profile 不挂桌面 web 插件"方向正确。

你的整个方案本质就是"为 dsh 写一个网关插件/bundle"——这正是仓库对第三方服务集成的开放形态（与 SDK stdio、ACP stdio 并列的第三条路：进程内宿主 + 自定义网络面）。如果落地后愿意分享网关骨架（去业务化的最小 bundle 模板），社区会受益。

[HY-love-sleep]

非常感谢您的建议! 我还有几个问题想请教下您:

1. 官方后续有计划实现这个网关插件吗, 还有您提到的多用户形态,认证中间件等等, 因为感觉企业在 harness 集成上更倾向于 deepseek 这种"品牌更大"的框架, 而这些是企业系统集成避不开的东西;
2. 目前我们自建窄网关的话, 会依赖ctx.webServer.register/registerUpgrade、ctx.agents.create/resume、agent.followup/whenIdle、session/event这些, 这些目前看像是内部 API, 这些 API 算公开稳定的吗, 我害怕过早自建会影响项目后续升级 dsh 版本;
3. 我们目前基于 dsh 开发的更偏向于传统的问答/写作助手, 这块儿比较担心沙箱的权限问题, 目前我们没有用到沙箱的需求, 想请教下我们除了在设置中通过tools.restrict禁用shell/write, 更加合理的沙箱设置姿势是啥呢?
4. 社区后续会接受外部 PR 吗?

非常期待您的答复, 谢谢!