前言¶

在 DSH 里和智能体协作时，对话窗口往往占满屏幕，但本地开发仍要同时跑后端、前端，甚至注册中心或迁移脚本。IDE 的运行配置通常是「单选」：点一次只能起一个进程，日志分散在多个窗口，前端起来时也缺少「后端已在应答」的客观依据。多项目 monorepo 还要自己记目录、命令和启动顺序。

dsh-dev-runner 是 DeepSeek Harness 的客户端插件，把项目表、启动顺序、就绪探测和日志收进右侧栏，并在会话顶栏提供整栈启停。它对具体技术栈不做假设——Maven、npm、Python、Go、Docker Compose 都以数据形式配置，自动发现只给出可审查的提议。

这是什么¶

• 名称：dsh-dev-runner（仓库 1020252969/dsh-dev-runner）
• 维护者：1020252969
• 分类：客户端（侧栏 + 顶栏控件）
• 定位：一键拉起整套开发环境；在侧栏增删改项目，在同一侧读带颜色、可搜索、可下载的日志，全程不必为启停反复切出对话。

插件不替代构建系统：清单里读不到的意图（例如多模块 Maven 要先 install）仍需你自行用启动前步骤或命令表达。

核心功能¶

项目编排¶

• 一张可见的项目表，每项包含工作目录、常驻命令、环境变量、角色（backend / frontend / service / infra）等。
• 启动前步骤（before）：可设输出校验（expect）和「失败也继续」（continueOnError）。
• 就绪判定用 TCP 端口、主机或 HTTP URL 探测，而不是仅看进程是否存在；HTTP 任意响应即视为就绪并回报状态码。
• dependsOn：例如后端就绪后再起前端。
• autoRestart 带熔断：短时间连续异常退出多次后停止继续拉起。
• oneShot：本应退出的命令（迁移、代码生成等）以 done 结束，不算失败，依赖方仍可继续。

自动发现¶

指定根目录后，插件读取常见清单并提议启动命令与端口依据（按下「应用」前不会写入）：

端口来自配置文件、.env、脚本参数或 Compose 映射；未写明时标注为约定值；不猜测未激活的 profile 或占位符环境变量。扫描默认最多 120 秒，可取消；目录留空时默认扫第一个已配置项目的父目录。Vite 代理指向后端端口，或扫描中只有一个后端时，前端提议会自动接到该后端。

侧栏与顶栏¶

• 侧栏：项目列表（状态、运行时长、重启次数）、表单编辑、校验（缺字段、非法端口、环依赖等会拒保存并列原因）。
• 日志：ANSI 彩色、筛选与跳转、跟随、清空、复制、下载为 ‹id›.log；内存保留约每项目 2000 行。
• 顶栏药丸：状态点、运行中/总数、整栈启动/停止；点状态可打开面板。空会话无会话头时该控件不可见。

HTTP 接口¶

路由前缀 /dev-runner/api，仅回环访问，跨源页面无法借浏览器驱动。提供状态、项目 CRUD、单项目/整栈启停、发现与应用候选、日志分页与文本下载等（详见仓库 README 表格）。

安装与启用¶

桌面 profile 安装：

dsh plugin --profile desktop add dsh-dev-runner

从本地源码目录安装（客户端无构建步骤，可直接 file: 路径）：

dsh plugin --profile desktop add 'file:<absolute path to the checkout>'

装好后侧栏引导会出现 Dev services。默认无需额外配置：打开面板输入扫描目录，确认候选即可落盘。

环境要求（来自 package.json）：DSH >=0.2.0-rc.2 || >=0.2.1-rc.2 || >=0.2.2-alpha.3；peer 依赖 @deepseek-ai/schemastery ^3.18.4。

典型用法¶

配置来源¶

生效表有两个来源，同时存在时以存储文件为准：

1. <DSH_HOME>/.dev-runner/projects.json（未设置 DSH_HOME 时用 ~/.dsh）
2. profile 补丁 cordis.patch.yml 里 dev-runner.config.projects

GET /status 与面板会标明当前来源（store、store-empty 或 config）。删掉 projects.json 可回退到 YAML 补丁。

profile 示例片段¶

在 cordis.patch.yml 中预置后端 + 前端与依赖（路径需改为你的绝对路径）：

- insert:
    - id: dev-runner
      name: 'dsh-dev-runner'
      config:
        discoverDepth: 2
        projects:
          - id: backend
            name: API
            cwd: <absolute path to your shop-api checkout>
            command: mvn -Dmaven.test.skip=true spring-boot:run
            role: backend
            readyPort: 8080
            readyTimeoutMs: 180000
            env:
              SPRING_PROFILES_ACTIVE: dev
          - id: frontend
            name: 商城前端
            cwd: <absolute path to your shop-ui checkout>
            command: npm run dev:h5
            role: frontend
            readyPort: 5173
            args: -- --host
            dependsOn: [backend]
            autoRestart: true
            before:
              - name: 生成接口代码
                command: npm run gen:api
                expect: 'generated'

常用字段：readyPort / readyHost / readyUrl、dependsOn、before、autoRestart、oneShot 等；完整说明见 README 项目字段表。

日常操作¶

1. 打开侧栏 Dev services 面板，必要时对仓库根目录执行自动发现并应用候选。
2. 在顶栏点击整栈启动，或按依赖顺序单独启停项目。
3. 在侧栏查看日志；需要留档时用下载得到 ‹id›.log。

也可通过 /dev-runner/api 脚本化（例如 POST /start-all、POST /discover）。

适用场景与注意¶

适合：经常在 DSH 会话旁同时维护后端 + 前端（或其它多进程栈）；希望用端口/URL 证明「可以连了」再串行启动；希望日志集中在侧栏而不是多个终端。

边界与权限：

• 插件以当前 DSH 进程权限启动子进程；安装前应阅读源码与 MIT 许可证。
• Windows 上难以向子进程组投递 SIGINT，停止行为为直接终止，面板会如实说明。
• 就绪探测不等于健康检查：端口通即算就绪，应用可能仍在预热。
• 环境变量：插件只下发你在项目里声明的 env；宿主会先剥离凭据与 DSH_*，需要继承的内容请显式写入。

社区目录 SkillHub 插件页 与 GitHub 为独立信息源，与 DeepSeek / 幻方无官方从属关系；DSH 生态一贯是「一切皆插件」，可按需从目录或仓库安装。

结尾¶

dsh-dev-runner 把「项目表 + 依赖顺序 + 就绪探测 + 侧栏日志」接到 DSH 桌面客户端上，用数据描述命令而非绑定某一框架。若你正在 SkillHub 或 GitHub 上挑选客户端类 DSH 插件，可用官方命令 dsh plugin --profile desktop add dsh-dev-runner 试用；细节与 API 以 GitHub README 为准。