dsh-api-runner：让模型在对话里自己调接口、启停服务、读日志

前言¶

在使用 DSH（DeepSeek Harness）做开发时，一个常见场景是：模型改完代码后，需要自己验证。这涉及三件事：调后端接口、启停本地服务、读日志找特征。以前这些动作要手工复制 curl、切窗口重启服务、翻日志定位报错，模型没法独立完成。

dsh-api-runner 把这三件事交给模型直接调用。它是一个 DSH 插件，提供「接口调试」面板，支持在 YAML 里或面板里配置接口、服务、日志，模型通过工具直接发起请求、启停进程、增量读日志，形成「改完自己验」的闭环。

插件定位¶

插件名：dsh-api-runner
维护者：lhhzmz229
分类：工作流
核心价值：让模型在对话里自己调接口、启停本地服务、读日志，改完代码自己验证

插件不依赖任何第三方插件，面板注册到 DSH 自带的席位（左栏全局页、右侧栏页签、设置页），装到任意一份 DSH 上都能用。

核心功能¶

1. 接口调试面板¶

面板「接口调试」提供三处入口：

左栏图标：打开后为中栏整页，无会话也能打开
右侧栏页签：和终端/文件/任务并列，边看对话边调试
设置页里的插件主页：只放跨项目的全局项

面板支持：

可视化增删改接口配置
登录并保存 token
点按钮试调用
列出本机所有运行中的 Java 服务并一键设为 baseUrl

2. 可配置接口¶

接口可在 YAML 里声明，也可以在面板里点选添加。支持配置方法、URL、请求头、body 模板。模型按 id 调用，占位符会自动替换。

3. 登录态管理¶

把某个接口标记为登录接口，调用成功后按 tokenPath 取出 token 存进项目档。后续接口会自动注入 Authorization，无需手工复制 token。

4. 本地服务启停¶

支持两种模式：

managed 模式：插件托管进程，能 start/stop/restart，DSH 重启后服务仍在跑
observe 模式：进程由 IDEA 启动，插件只轮询健康检查，配合 IDEA 的 restart 按钮

5. 日志增量读取¶

按文件 + 字节偏移增量 tail
支持正则过滤
等待特征出现
游标持久化，服务重启不丢

6. 数据库能力（0.3.0 新增）¶

面板多了一个「数据库」页签，支持 SQLite / MySQL / PostgreSQL / Oracle / 达梦。SQLite 开箱即用（零依赖），其它类型需要按需安装驱动。

安装与启用¶

从 npm 安装（推荐）¶

dsh plugin --profile web add dsh-api-runner

npm 上已发布 dsh-api-runner@0.3.0，这是推荐路径，也是 DSH「插件中心」里一键安装的形式。

从 GitHub 源码安装¶

dsh plugin --profile web add github:lhhzmz229/dsh-api-runner

DSH 会把仓库 clone 到 profile 的 node_modules 下。写成带包名的 dsh-api-runner@github:lhhzmz229/dsh-api-runner 也等价。这条依赖本机有 git；装完重启 DSH（或把 dsh-api-runner bundle 关掉再打开）生效。

本地开发：link 安装¶

# 在插件目录下装依赖（只有一个运行时依赖 yaml；npm cache 目录无写权限时用 --cache 指到可写目录）
npm install

# 以 link 方式装进 desktop profile
dsh plugin --profile desktop add "link:/绝对路径/到/dsh-api-runner"

Windows 下 link 路径写成 link:D:/path/to/dsh-api-runner 也等价。

dsh 命令不在 PATH 时，用桌面版自带运行时（路径按你的安装位置调整）：

# Windows
"<DSH 安装目录>/resources/runtime/bin/node.cmd" "<DSH 安装目录>/resources/app.asar/dsh/bin/dsh.js" plugin --profile desktop add "link:..."

# macOS / Linux
"<DSH 安装目录>/resources/runtime/bin/node" "<DSH 安装目录>/resources/app.asar/dsh/bin/dsh.js" plugin --profile desktop add "link:..."

配置文件¶

配置文件按「内置默认 → 全局 → 项目」合并，后者覆盖前者：

${DSH_HOME}/api-runner.yml：全局，所有项目生效
<项目 cwd>/.dsh/api-runner.yml：项目级，建议放这个

文件名也支持 api-runner.yaml / dsh-api-runner.yml。改完保存即生效（按 mtime + size 缓存），不用重启 DSH。

完整示例见仓库中的 dsh-api-runner.example.yml，最小可用示例如下：

defaults:
  timeoutMs: 30000
  headers:
    Content-Type: application/json

env:
  TOKEN: ${DEV_TOKEN}          # 引用环境变量

apis:
  - id: get-user
    name: 查询用户
    method: GET
    url: http://127.0.0.1:8080/api/users/{id}
    headers:
      Authorization: "Bearer ${TOKEN}"

  - id: create-order
    method: POST
    url: http://127.0.0.1:8080/api/orders
    body:
      userId: "{userId}"
      amount: "{amount}"

services:
  # 插件托管：mvnw spring-boot:run
  - id: app
    mode: managed
    cwd: ../
    command: ./mvnw.cmd
    args: ["spring-boot:run"]
    logPath: ./logs/app.log
    startupTimeoutMs: 90000
    health:
      url: http://127.0.0.1:8080/actuator/health

  # IDEA 里跑，插件只观测（配合 IDEA restart 按钮）
  - id: idea-app
    mode: observe
    health:
      url: http://127.0.0.1:8080/actuator/health
      ports: [8080]

logs:
  - id: app-log
    path: ./logs/app.log

两种占位符¶

写法	何时展开	用途
`${NAME}`	加载配置时	环境变量 / `env:` 段里定义的值，用于 URL、header、command
`{name}`	调用接口时	模型通过 `params` 传入，替换 URL 与 body 里的同名占位

headers 里的 ${VAR} 会展开成真实值，但在返回给模型的 request.headers 里按名字脱敏（token/secret/password/key/auth 等一律 demo***3456）。

工具与动作¶

模型通过 ApiRunner 工具调用，action 取值：

action	作用
`describe`	列出可用接口、服务、日志（含每个接口需要的参数名），不返回 header 值
`call`	按 `api_id` 调接口，`params` 传占位符；已保存 token 会自动注入
`login`	调登录接口并把 token 存进项目档（`api_id` 指向配了 `login.tokenPath` 的接口）
`java`	本机 Java 服务：`java_action` = `list` / `detail`（详情+日志）/ `start`（接管启动）/ `stop` / `restart` / `log` / `ignore` / `unignore` / `save`（保存启动配方）/ `unsave` / `start_saved`（按配方启动，不需要 IDEA 里先有进程）/ `start_all`（一键启动所有已保存的服务，可用 `java_ids` 只启部分）/ `settings`（读或改全局设置）/ `status`
`db`	数据库：`db_action` = `list_connections` / `test` / `save` / `delete` / `query`（执行 SQL，默认只读）/ `list_databases` / `list_tables` / `describe_table`
`service`	`service_action` = `start` / `stop` / `restart` / `wait` / `status`
`log`	增量读日志（`pattern` 正则过滤，`max_bytes` / `max_lines` 限流）
`wait_log`	等某个特征出现在日志里（`timeout_ms` 超时）
`reset_log`	把游标重置到文件末尾
`verify`	一条命令串起「重启 → 等日志特征 → 调接口」，返回分步结果

verify 只有在所有步骤都成功（observe 模式下无法自动重启除外）才返回 ok: true；失败时给出 code（如 STEP_FAILED:log）与可读 message。

典型流程¶

模型可以在对话里按以下步骤完成「改完自己验」：

使用 ApiRunner.call 调用配置好的接口，传入占位符参数
使用 ApiRunner.service start 或 restart 启动或重启本地服务
使用 ApiRunner.wait_log 等待某个特征出现在日志里
再次调用接口验证结果

插件通过 verify 动作将上述步骤串起来，返回分步结果。

兼容与运行要求¶

DSH：>=0.1.0-rc.6 <0.2.0-0 || >=0.2.0-rc.1 <0.3.0-0
Node.js：>=22.5（SQLite 用 Node 内置的 node:sqlite，22.5 起才有）
平台：Windows / macOS / Linux
可选环境：
JDK（jps / jcmd，用于 Java 服务发现与接管）
Maven（mvn，用于接管时编译）
数据库驱动：SQLite 用 Node 内置；MySQL 需 mysql2、PostgreSQL 需 pg、Oracle 需 oracledb、达梦需 dmdb

权限与风险¶

安装前请确认这些行为都在你的预期内：

项目	说明
执行本地命令	用 `jps` / `jcmd` / `mvn` / `netstat` / `lsof` 发现、接管、启停 Java 进程；`managed` 模式会按配置直接拉起与结束子进程
发起 HTTP 请求	只请求你在 YAML 或面板里配置的 URL，可按配置注入 `Authorization` 头
读取本地文件	读取你配置的日志文件（按字节偏移增量读），内容只回给模型，不上传
写入本地文件	`<数据目录>/` 下的状态与 UI 配置；面板保存的 token 明文落在 `api-runner-ui.json`
外联上报	无遥测、无统计上报，插件自身不发起任何外部请求

适用场景与注意¶

适合需要模型在对话里独立完成接口调用、服务启停、日志验证的开发者。插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。

小结¶

dsh-api-runner 让模型在对话里自己调接口、启停本地服务、读日志，改完代码自己验证。它不依赖第三方插件，面板注册到 DSH 自带席位，支持 managed 与 observe 两种服务模式，并提供增量日志读取与数据库能力。

插件主页：https://www.skillhub.cn/plugins/lhhzmz229/dsh-api-runner
GitHub：https://github.com/lhhzmz229/dsh-api-runner