albertgranados/dsh-run-environment

dsh-run-environment

CI
License: MIT
Dependencies: 0
Node.js

从你已经在使用的 harness 中，运行你打开的项目。

一个 DeepSeek Harness 插件，它在
Session 头部添加了一个控件：它会检测当前工作区应当如何运行，并直接运行它，而无需
离开对话。

Session 头部中的运行控件

目前已支持检测 Node.js 项目（package.json 脚本，经过排序，使播放按钮落在
dev 上）。其他所有内容都通过用户自定义命令成为一等公民，而针对
其他环境的适配器是该项目的核心增长方向——头部询问的是项目，而不是 npm。

命令菜单：按清单分组的命令、自定义命令和管理

每一行都带有自己的图标和自己的选项；Edit… 可以重命名命令并选择不同的
字形，而无需触碰清单：

编辑对话框：重命名命令并选择其图标

功能

- 检测，而非配置。 一个带有脚本的 package.json 就足够了：无需编写清单，无需
教插件路径。检测基于适配器，因此其他环境可以接入同一
模型，并且菜单会按声明命令的文件（package.json、Makefile、……）对命令进行分组。
- 重命名它们、描述它们、给它们图标。 每一行都带有一个图标——在你选择另一个之前，
是一个中性的星号——以及自己的选项：Set as default、Edit（重命名它、选择一个
字形、编写可选描述），以及对于你自己定义的命令，Delete。
- 一个有意义的播放按钮。 默认是 dev，然后是 start，然后是清单声明的
第一个——由适配器排序，在宿主上解析。
- 运行和停止。 当命令处于活动状态时，按钮会变成停止按钮，而停止
会终止整个进程组（npm → sh → the dev server），而不仅仅是父进程——但会先询问
你。
- 你可以看到正在运行的内容。 活动命令的行会将其图标替换为 harness 的绿色状态
点，无论它位于列表中的哪个位置——包括不是默认命令的命令。按下该行
会在停止它之前询问，因此一次误点不会在思考中途杀死开发服务器。
- 每次运行都会获得一个控制台。 启动命令会在 harness 自带的右侧
Sidebar 中打开其输出：每个命令一个标签页，实时显示，带有运行状态和停止它的方式。它不需要额外的
插件——它依托 Sidebar 的公开标签页 API，而没有该 Sidebar 的客户端则像以往一样直接运行命令。

正在运行的命令行，绿色状态点取代了其图标

当默认命令仍在运行时，同一个圆点会取代标题按钮的播放图标：

带有绿色状态点的标题控件

按下该行会先询问再停止：

正在运行的命令行打开的停止确认
- 任何命令，任何环境。 从菜单中添加你自己的命令（docker compose up -d、
python manage.py runserver 等）。它们通过你的 shell 在项目目录中运行。
- 默认安静。 你从未运行过的命令可以隐藏；隐藏的命令仍可恢复，并且始终排在底部。一个既未检测到任何内容、也未配置任何内容的工作区完全不渲染任何东西。
- 按你想要的顺序排列。 拖动一行即可移动它，顺序会按项目记住。默认命令始终是其所在部分的第一行，因此播放按钮运行的内容始终在你第一眼看到的位置。
- 失败会显示在你正在看的地方。 启动后立即终止的命令会将控件涂成红色，并在工具提示中携带其最后一行输出。
- 零运行时依赖。 宿主端只导入 Node 内置模块和 harness 自身的包；浏览器端由 harness 原样提供，因此从 git 安装只需一条命令，无需构建步骤。72 个测试通过 node --test 离线运行。

安装

从 GitHub 安装
dsh plugin --profile web add github:albertgranados/dsh-run-environment

或从本地检出安装（将包复制到 profile 中）
dsh plugin --profile web add "file:$PWD"

然后重启 harness 并重新加载浏览器页面。该插件声明了 dsh.bundle.patch，因此
dsh plugin 会自行协调 dsh.profile.bundles——无需手动编辑 profile 文件。

使用 dsh plugin --profile web remove dsh-run-environment 卸载。

运行控制台

harness 右侧 Sidebar 中某次运行的控制台

运行命令会在右侧 Sidebar 中打开一个以该命令命名的标签页。其栏中包含菜单使用的相同状态点、命令行，以及一个在终止任何内容前会先询问的 Stop 按钮；主体在运行存活期间流式输出其输出，并在之后保留它，退出状态显示为 Finished、Stopped 或 Failed。

每个命令保留自己的标签页：运行第二个命令会打开第二个控制台，而不是替换第一个；再次运行某个命令会聚焦它已有的控制台。这些标签页属于会话，因此每个对话显示自己的标签页。

控制台通过菜单已使用的同一路由读取——即命令列表，其中 logs=1 会将每次运行的尾部合并到同一答案中——因此它不需要第二条路由，以免中间的任何东西可能
针对比控制台更旧、不折叠尾部的主机，它会以任一形态回退到日志路由；如果该路由也无法访问，它会显示运行状态，而不会假装主机已消失。它对自己所展示的内容保持诚实。如果其下方的测试框架重启——这会遗忘所有运行——标签页会说明该运行已不再被知晓，而不是假装知道；如果读取失败，它会指明失败的是什么（主机有响应，还是主机无法访问），并在不丢失屏幕上已有输出的情况下重试。只要命令未在运行，栏中就会提供 Run again，因此一个运行已消失的控制台是一条返回的途径，而不是死胡同。

管理菜单中的内容

每一行的三点手柄会在列表上方打开该行的选项，而列表会在它们后面保持打开：

命令行的选项：设为默认、编辑或删除

- Set as default 会将播放按钮移到该命令上。从菜单运行命令也会使其成为默认命令，因此按钮会跟随你最后选择的内容。
- Edit 会重命名命令、选择其图标，并写入一个可选的 description，当你悬停该行时会显示。命令行本身显示为锁定状态：检测到的命令属于其清单，而用户定义的命令就是该命令——重命名它绝不应悄悄改变实际运行的内容。
- Hide 会将检测到的命令从菜单中移除，Unhide 会将其放回。只有属于清单的命令才会提供此选项；你定义的命令则会被删除。
- 拖动一行 可移动它。顺序按项目记忆；默认命令保持在最前，隐藏命令保持在最后，因此你能运行的内容绝不会与你不能运行的内容混在一起。
- 命令正在运行的行会显示绿色状态点，而不是其图标。按下该行、状态点或标题按钮都会打开同一个确认，只有 Stop 会结束进程。
- 分区标题右侧的 Show all 会显示该分区中隐藏的命令，以变暗形式呈现，因此无需离开菜单即可将它们取消隐藏。Show less 会再次隐藏它们。

同一个菜单，其中某个分区的隐藏命令已显示并变暗

工作原理

Session header
└── /run-environment/*  ──►  router ──► adapters (detect)
│        project store (remember)
└──────► runner (spawn, stop, observe)

主机拥有模型；浏览器端只负责渲染它，并回传一个命令 id——绝不是程序名。每个路由都位于测试框架自身的 Host/Origin 防护和登录 cookie 之后。

| 路由 | 用途 |
| --- | --- |
| GET /run-environment/commands?cwd= | 检测到的和用户定义的命令、解析后的默认命令，以及实时运行表。 |
| POST /run-environment/run | { cwd, id } → 启动该命令（并将其记忆为默认命令）。 |
| POST /run-environment/stop | { cwd, id } → 终止该次运行的进程组。 |
| POST /run-environment/state | { cwd, action, … } → set-default、edit、reorder、hide、show、add-custom 或 remove-custom。 |
| GET /run-environment/log?cwd=&id=&bytes= | 某次运行已收集输出的尾部。format=json 会在 output 下返回相同的尾部内容，并在其旁边返回该次运行的信息。 |

设计说明、请求流程以及适配器契约见
docs/architecture.md 和 docs/adapters.md。

支持的环境

| 环境 | 状态 | 检测内容 |
| --- | --- | --- |
| Node.js · npm | 已发布 | package.json 脚本（dev、start 等），排除生命周期伴随脚本。 |
| 其他任何环境 | 当前可用 | 通过菜单为每个项目定义一条用户命令。 |
| Python、Make、Docker Compose、Cargo、Go、Taskfile | 路线图 | 每个环境一个适配器——参见 docs/adapters.md 来编写一个。 |

配置

可选，在配置文件的 cordis.patch.yml 中设置：

- id: run-environment
config:
visibility: auto      # auto | always | never
maxConcurrentRuns: 8
graceMs: 5000         # SIGTERM → SIGKILL grace for a stopped command
shell: ''             # user commands; empty means $SHELL, then /bin/sh

visibility: always 可以让一个尚无适配器识别的目录仍然获得该控件（因而也获得“Add command…”条目）。完整列表见
docs/configuration.md。

状态——默认命令、隐藏命令以及用户定义的命令——按项目存储在
$DSH_HOME/dsh-run-environment/projects.json 下，绝不存放在你的仓库内。

开发

git clone https://github.com/albertgranados/dsh-run-environment
cd dsh-run-environment
npm test                 # node:test, no dependencies, ~0.2 s
scripts/dev-install.sh   # install this checkout into the web profile

欢迎贡献：阅读 CONTRIBUTING.md 了解工作流程（基于主干、约定式提交、必须包含测试），在报告任何敏感问题之前阅读 SECURITY.md，
并阅读 CODE_OF_CONDUCT.md 了解对这里每个人的期望。

许可证

MIT © Albert Granados