MOLAaaaaaaa/dsh-seismicx

dsh-seismicx

一个 DeepSeek Harness 插件，将
SeismicX 地震目录技能 暴露为带类型的、
面向模型的工具。

该技能的 SKILL.md 仍然是可移植的工作流文档——它可以在 Claude Code、
Codex 和 OpenCode 上原样运行。本插件是仅针对 DSH 的增强层，它的存在是为了
完成技能无法做到的三件事：

| | 作为技能 | 作为本插件 |
|---|---|---|
| 参数 | 一个 bash 字符串；错误的 --real-R 元组会在几分钟后才失败 | 在调用边界处、进程启动之前进行校验 |
| 结果 | 模型需要重新解析以获取路径的 stdout 文本 | 一个带类型的 JSON 值，包含 picks_path、map_path、exit_code |
| 长达一小时的拾取 | 一个阻塞式 bash 调用，会淹没上下文窗口 | 一个带有 id、job_status 和 job_kill 的后台任务 |

安装

需要一个可用的 seismicx-catalog-skill 检出及其 Python 环境。

从本地检出安装（最简单）

lib/ 未提交到仓库，因此先构建一次，然后安装该目录：

git clone https://github.com/MOLAaaaaaaa/dsh-seismicx && cd dsh-seismicx && npm install && npm run build

dsh plugin --profile  add /absolute/path/to/dsh-seismicx

pnpm 会链接该检出，因此它会使用你刚刚构建的 lib/，并且不需要构建权限。

从 GitHub 安装

git 安装获取的是源代码，而不是构建产物，因此 pnpm 必须运行本包的 prepare
脚本——而 pnpm ≥10 在你按名称允许它之前会拒绝这样做。第一次 add 会失败并
打印出该键；把它放进该 profile 的 pnpm-workspace.yaml：

allowBuilds:
dsh-seismicx: true

然后重新运行，并固定一个提交，这样之后的推送就无法悄悄改变实际执行的内容：

dsh plugin --profile  add github:MOLAaaaaaaa/dsh-seismicx#

该许可是在安装时于你的机器上、在 agent 所运行的任何沙箱之外执行本包代码的权限。
这里的 prepare 仅做转译（tsc --noCheck），因此它不会像类型检查构建那样
因 peer 版本漂移而失败。

配置

在 profile 的 cordis.patch.yml 中将插件指向该技能：

- id: seismicx
config:
skillRoot: /absolute/path/to/seismicx-catalog-skill
python: /path/to/.venv/bin/python
workdir: /path/to/your/project

如果你不想把路径写进文件，随附的 cordis.patch.yml 会改为从环境变量中
读取 SEISMICX_SKILL_ROOT 和 SEISMICX_PYTHON。

在不接触任何数据的情况下验证接线：

dsh --profile  --dump-config   # the seismicx row should appear

然后让 agent 调用 seismicx_list_models。

配置

| 字段 | 默认值 | 描述 |
|---|---|---|
| skillRoot | —（未设置 ⇒ 不生效） | 技能检出的绝对路径 |
| python | python3 | 用于每个子命令的解释器 |
| workdir | . | 相对输出路径所解析的基准目录 |
| listModels / scan / pick / plotMap | true | 注册对应的工具 |
| allowBackground | true | 允许 seismicx_pick 发布后台作业 |
| quickTimeoutMs | 120000 | 元数据子命令的时间预算 |
| pickTimeoutMs | 3600000 | 前台拾取的时间预算 |
| plotTimeoutMs | 600000 | 地图渲染的时间预算 |

未配置与配置错误的行为有意设计为不同：

- skillRoot 未设置 —— 插件记录一行日志，不注册任何工具。安装此捆绑包永远不会阻止
harness 启动；一个已安装但尚未指向目标的插件属于未配置，而非损坏。
- skillRoot 已设置但为相对路径 —— 在加载时大声失败，并指出有问题的行。这是真正的
配置错误，错误信息应当出现在能标识该行的位置，而不是在模型必须解读的工具调用内部。

存在性有意不做检查 —— 该路径可能位于此进程无法 stat 的沙箱或远程执行环境中，而
ctx.subprocess 才是解析它的地方。

配置文件的 cordis.patch.yml 会被监视，因此修正 skillRoot 或 python 无需重启
dsh web 即可生效。

工具

| 工具 | 形态 | 备注 |
|---|---|---|
| seismicx_list_models | 前台，并发安全 | 首先调用以验证 skillRoot/python |
| seismicx_scan | 前台，并发安全 | 波形清单；确认归档可读 |
| seismicx_pick | 前台或后台 | 对连续数据设置 run_in_background |
| seismicx_plot_map | 前台，并发安全 | 返回 map_path；携带 presentationMeta 供 UI 卡片使用 |

seismicx_pick 有意不暴露任何过滤参数：该技能的固定规则是连续波形未经滤波直接送入
PNSN 拾取器。

后台拾取由调用它的 agent 持有，因此 agent 销毁时会取消并等待它。没有 agent 支撑的调用
（直接服务调用而非模型回合）会被拒绝，而不是泄漏一个长达数小时的无主运行。

设计说明

一切都通过 ctx.subprocess，绝不使用 node:child_process。 这个接缝承载了部署的
沙箱与远程执行选择，因此将 subprocess 指向远程运行器的组合会原封不动地带着这些工具一起
迁移。

argv 是数组，绝不经过 shell 解释。 包含 shell 元字符的台站代码或路径无法逃逸到
命令行中。

非零退出码是领域结果，而非抛出异常。 它被表示在规范值中（exit_code、
stderr_tail），以便调用方可以据此分支。只有 spawn 级别的失败才会 reject。

Python 进程不受限制。 在此架构中，限制是使用方的责任 —— ctx.shell 的沙箱提供者
会在将 argv 交给 ctx.subprocess 之前对其进行包装，而此插件不做这种包装。请将这些工具
视为与
bash 工具：它们运行你配置的解释器，并拥有你的环境文件系统和网络访问权限。通过 ctx.sandbox 后端路由 argv 被列为下方待办工作。

尚未完成

- 其余九个子命令。 polarity、associate、locate、magnitude-ml、
mechanism、analyze、build-tools、init-config 以及端到端的 catalog 都遵循
与 seismicx_scan 相同的形态；添加一个只是机械性工作。
- 结构化返回值很浅。 工具报告的是传给它们的路径以及退出事实，而不是行数或残差统计，
因为 CLI 输出的是散文。干净的修复属于上游：在 Python 子命令上添加一个 --json 摘要标志，
然后本插件会将其作为类型化字段呈现，而不是 stdout_tail。
- 没有浏览器部分。 seismicx_plot_map 已经持久化了 presentationMeta.mapPath，
这正是以 seismicx_plot_map 为键的 tool.call.toolview 条目所需要的，以便在对话中内联渲染地图，
而不是留下一个需要打开的路径。GMT/PyGMT 渲染器和一个 shell.overlay 控制面板
（区域、投影、深度切片、沙滩球）是预期的下一步。
- 没有沙箱包装。 ctx.subprocess 被直接调用，因此解释器在不受限的情况下运行
（见上方设计说明）。通过 ctx.sandbox 后端包装 argv 会限制它，
代价是必须为 GPU、模型缓存以及 build-tools 网络访问放宽策略，
而这些是流水线合法需要的。
- 没有能力接缝。 拾取器、关联器、定位器和机制引擎仍然是 CLI 标志，
而不是可替换的 ctx.* 提供者。将它们接缝化，才能让一个刚微调好的检查点
成为插件中的一行，而不是一次代码更改。

许可证

GPL-3.0-only — 见 LICENSE。

本插件以 GPL-3.0 分发，因为它所包装的技能是 GPL-3.0。DeepSeek Harness
本身是 MIT，且不受本许可证覆盖；MIT 与 GPL 单向兼容，因此 GPL
插件可以运行在 MIT harness 上，但本插件的代码不能被重新许可进 harness
仓库。

该技能中捆绑的模型检查点带有它们自己单独的条款；见 assets/models/ 中它们旁边的 .LICENSE 文件。