dsh-plugin-terminal-extension-wait-for

给 DSH 原生 terminal 系列补一个 terminal_wait_for 工具：阻塞到某个字符串出现在持久终端的保留输出里， 或等到超时 / 会话退出 / 会话消失 / 调用被取消。

原生 terminal_send 只等待「就绪」（stdin_read | inferred_idle | timeout | session_exit）， terminal_read 是一次性分页读取——两者都无法表达「等 BUILD OK 或 BUILD FAIL 出现」。 本插件在 ctx.terminals 的公开 owner 隔离面上轮询保留输出实现该能力，不发送任何输入，不干扰在跑的后台 job。

工具契约

参数	必填	语义
sessionId	是	terminal_open / terminal_list 返回的会话 id
pattern	是	JavaScript 正则（大小写敏感）；编译失败自动回退为原文子串匹配；不得为空
timeout_ms	否	上限等待毫秒，默认 10000，钳制到 [minTimeoutMs, maxTimeoutMs]

结果五态（规范 JSON 值）：

kind	说明
found	命中：match（实际命中的文本，多分支模式可据此判断成败）、line（保留 transcript 绝对行号，0 起）、column、line_text、elapsedMs
timeout	超时：totalLines + 尾部 tail（≤ tailLines 行），可据此再 terminal_read
exited	顶层 shell 已退出：带 exitCode / signal
gone	会话已不存在（被关闭）
cancelled	工具调用被中止（exec.signal），立即返回

典型用法（配合后台发送，避免忙轮询）：

terminal_send(sessionId, "make build", run_in_background: true) → jobId
terminal_wait_for(sessionId, "(BUILD OK|BUILD FAIL)", timeout_ms: 300000) → found, match=BUILD FAIL
job_output(jobId) → 收集剩余输出

首轮立即扫描：pattern 已存在于保留输出时立刻返回 found。每轮扫描最近 scanLines 行 （非消费式读取），未命中时检查会话状态。pattern 被 scrollback 上限挤出后会找不到——这是刻意的有界语义。

挂载位置与 realm

插件通过服务名 inject = ['terminals', 'tools'] 访问 ctx.terminals，因此必须和终端服务在同一个 realm：

• 终端服务挂在 profile 根级：dsh plugin --profile <p> add <本包> 即可，bundle 的 cordis.patch.yml 会在根级插入插件行。

• 终端服务挂在 agent preset 的隔离组里（上游 minimal preset、本机 ptc-custom preset 都是 isolate: { terminals: true } 的 persistent-shell 组）：根级行会一直 pending，不会注册工具也不会报错。 此时把包名按行加进那个组的插件列表：

  - id: persistent-shell
    name: cordis:group
    group: true
    isolate:
      terminals: true
    config:
      - id: pty
        name: '@deepseek-ai/dsh-terminal'
      # ... 后端与 tool-terminal ...
      - id: terminal-extension-wait-for
        name: '@huanlin/dsh-plugin-terminal-extension-wait-for'
  

  包本身仍要装进 profile（dsh plugin add），Loader 才能从 profile node_modules 解析到它。

插件不 import @deepseek-ai/dsh-terminal，只在运行时按服务名取用，因此不增加对私有包的解析依赖。

配置

字段	默认	含义
defaultTimeoutMs	10000	模型省略 timeout_ms 时的等待上限
maxTimeoutMs	600000	单次等待硬上限，更大的请求被钳制
minTimeoutMs	100	最小等待上限，更小的请求被钳制
pollIntervalMs	150	轮询间隔；每次轮询都是一次非消费式读取
scanLines	2000	每次轮询扫描的最近保留行数
tailLines	30	timeout 结果携带的尾部行数
maxLineTextChars	1000	found.line_text 的字符上限（超出截断）
maxTailBytes	8192	timeout.tail 的 UTF-8 字节上限（保留尾部）

非法配置（非正数间隔/行数、max < min 等）在插件 apply 时 fail loud。

开发

pnpm install
pnpm run typecheck   # tsc --noEmit（src，影子类型）
pnpm test            # vitest（纯逻辑核心 + 注册层）
pnpm run build       # tsc + tsdown → lib/（预构建入库）

• src/wait-for.ts：等待核心（类型、正则编译与回退、超时钳制、扫描/行号换算、轮询、渲染），依赖注入，可单测
• src/index.ts：插件入口（name / inject / Config / apply），注册 terminal_wait_for
• src/types.d.ts：peer 包的最小影子声明（独立 typecheck，不需要安装宿主）
• 设计/计划：docs/plans/2026-09-30-terminal-wait-for-design.md、docs/plans/2026-09-30-terminal-wait-for-plan.md

运行

# 开发热更新（link:）
dsh plugin --profile <profile> add link:D:\Projects\deepseek-harness\dsh-plugin-terminal-extension-wait-for
# 分发（预构建 lib/，github: 开箱即用）
dsh plugin --profile <profile> add github:huanlinoto/dsh-plugin-terminal-extension-wait-for
# npm
dsh plugin --profile <profile> add @huanlin/dsh-plugin-terminal-extension-wait-for

按「挂载位置与 realm」确认插件行的位置，然后重启 dsh web 并硬刷新（Ctrl+Shift+R）。

检查

pnpm run typecheck
pnpm test
node -e "import('./lib/index.js').then(m => console.log(m.name, m.inject))"

License

AGPL-3.0