前言¶
DeepSeek Harness（DSH）提供多种运行 profile，其中只有 web 能在进程不退出的前提下长期承载会话。dsh web 自带的 /api 面向浏览器：需要启动 token、签名 cookie，以及 Host/Origin 信任边界，从 shell 或远端脚本直接调用并不顺手。
DSH bundle 插件可以通过 ctx.webServer 注册一等 HTTP 路由，这些路由落在上面的浏览器围栏之外。dsh-ctl 利用这一机制，在环回地址上暴露一套小型的 JSON API；再配合 SSH，可以在不向外网暴露端口的情况下，远程列出、创建、注入 prompt、跟踪输出并取消会话。
下面介绍该插件的定位、能力、安装方式与典型用法。
这是什么¶
dsh-ctl 是维护者 StarChen-Cycler 发布的 DSH 工作流类插件（社区目录分类：工作流）。它为长期运行的 DeepSeek Harness dsh web 进程提供 Loopback HTTP control plane：在本地 HTTP 服务上挂载 /ctl/* 接口，并用仓库内 scripts/ 下的 ctl 辅助脚本包装 curl，使具备 SSH 权限的机器用 ssh <host> ctl ... 即可完成运维式操控。
插件当前版本为 0.1.4（MIT 许可证），与资料中声明的 DSH 0.1.5-rc.2 做过验证。
核心功能¶
资料中可核实的操作面包括：
- 健康与索引：
GET /ctl/health查看版本、端口、pid、平台、Node、运行时长等；GET /ctl为路由索引。 - 会话生命周期：列出会话（可按
running=1筛出正在执行的）、创建会话（可指定cwd、预设权限等）、单会话查询、重命名、取消当前 turn。 - 驱动与观测：向会话注入 prompt（
queue等待当前 turn 结束再投递，steer切入当前 turn）；tail读取历史快照与实时帧；inspect读持久化状态且不唤醒 agent；control查看 live 队列与运行统计。 - 扩展能力：会话绑定 schedule（cron、daily、weekly 等）；
hypo-checkpoint与dsh-hypo-before-compact相关的 memory checkpoint 开关；presets查询 profile 暴露的权限预设；调试用的debug/shape只读 schema 内省。
GET /ctl/sessions?running=1 反映进程内 live 状态而非磁盘归档，资料称在 prompt 后约 300 ms 内 running 会变为 true，turn 结束后回到 false。判断会话是否在跑应依赖 running 等 live 信号，不宜仅凭 lastUserInputAt 时间戳推断。
环境与依赖¶
- DSH
0.1.5-rc.2或更新（dsh --version自检）。 - 使用基于
@deepseek-ai/dsh-web-app的 profile（官方web模板或派生模板）。 - Node.js 18+（DSH 自带运行时，一般无需系统 Node）。
安装与启用¶
先基于默认 web 模板创建专用 profile，再以 link 方式安装插件（安装命令须与 README 一致，勿凭仓库名臆造 github: 写法）：
# 从官方 web 模板创建 profile
dsh --profile fleet --from-default-profile web
# 安装插件（路径、tarball 或发布后的 npm 均可）
dsh plugin --profile fleet add link:/absolute/path/to/dsh-ctl
dsh plugin 会在 profile 目录内转发给 pnpm 并记录 bundle，无需手改 package.json。安装完成后 profile 的 bundles 中会包含 dsh-base、dsh-web-app、dsh-ctl。
启动常驻服务时关闭自动打开浏览器，端口可自行选择，绑定地址保持默认环回：
dsh --profile fleet --port 17390 --no-open
长期运行可交给本机服务管理器（Linux 上可用 systemd，macOS 可用 launchd 等）。README 给出了 macOS LaunchAgents 的 ProgramArguments 示例，核心即为上述 dsh --profile fleet --port 17390 --no-open。
典型用法¶
凡能 SSH 到宿主机的机器均可执行下列命令，无需端口转发或额外 tunnel（README 原文表述）。
# 健康检查
ssh <host> ctl health
# 会话列表，最新在前
ssh <host> ctl sessions --limit 20
# 仅当前正在执行的会话
ssh <host> ctl sessions --running
# 在指定工作区创建会话
ssh <host> ctl create --cwd /srv/work
# 注入任务
ssh <host> ctl prompt <session-id> "summarise the failing tests"
# 读取输出（历史快照 + 最长 N 秒 live 帧）
ssh <host> ctl tail <session-id>
# 停止当前 turn
ssh <host> ctl cancel <session-id>
对已在跑的会话，可先 ctl control 看队列，用 ctl inspect 读持久化状态；注入时选用 --mode queue（进入下一轮）或 --mode steer（切入当前轮）。两种模式在送达前都会先返回，在 control 里观察队列，而不是在落地前指望 tail。
可将 scripts/ 中的 ctl 拷到目标主机，或在本地用 --host 指定远程。
更完整的请求/响应形状见仓库 docs/API.md。
适用场景与注意¶
适合谁：需要在单机或内网保留一个 dsh web 进程，又从 CI、跳板机或其它节点用 SSH 编排 agent 会话的团队；希望避免把 DSH Web UI 的 cookie/token 流程硬塞进 shell 脚本的场景。
权限与安全：插件路由挂在同一 dsh web 进程上，以该进程的权限访问工作区与工具能力。安装前应阅读源码与 MIT 许可证，确认 link: 路径可信；控制面默认在 loopback，对外暴露仍取决于你如何部署 SSH 与主机加固。
生态说明：DSH 强调「一切皆插件」；SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方并无官方从属关系，本文不以「官方应用商店」口吻描述。
结尾¶
dsh-ctl 把常驻 dsh web 翻译成一套可通过 SSH 调用的环回 JSON API，补上「只有 web profile 能保活会话、但浏览器 API 难脚本化」之间的缝隙。
- 社区目录页：https://www.skillhub.cn/plugins/StarChen-Cycler/dsh-ctl
- 源码与 README：https://github.com/StarChen-Cycler/dsh-ctl
