因果追踪器 martinm86867-ops/dsh-plugin-witr

dsh-plugin-witr

因果进程与端口追踪插件，专为 DeepSeek Harness 打造。

让自主运行的 DeepSeek 智能体一眼看清运行中的进程、端口冲突（EADDRINUSE）和卡死的文件锁，直接定位根因。

问题所在

智能体在开发或运维循环中，一旦碰上状态冲突，经常就卡住了：
- 本地开发服务器起不来，报 EADDRINUSE: 3080。
- 环境命令挂住不动，因为 /var/lib/dpkg/lock-frontend 被锁了。
- 一个长期驻留的后台 worker 占着内存，可 ps aux 只显示一个没头没尾的子进程，看不出上下文。

智能体惯用的绕路办法——把 ps aux、lsof、fuser、netstat、kill -9 串起来跑——既脆弱又容易瞎编，还可能误杀父终端或 shell。

解决方案

dsh-plugin-witr 借助 Cordis 插件生命周期，把 witr 直接接进 DeepSeek Harness 的工具注册表。

智能体不用再猜，直接调用 witr_trace，一轮就能拿到完整的监管层级：从 systemd 一路往下，经过终端模拟器、shell，再到父容器。

graph TD
A[DeepSeek Agent Loop] -->|witr_trace tool call| B[dsh-plugin-witr]
B -->|Cordis Effect / AbortSignal| C[witr Causal Engine]
C -->|Procfs & Netstat Inspection| D[Linux Kernel / Sockets]
D -->|Root Cause Tree + Metadata| C
C -->|Formatted Tree / Mermaid / JSON| B
B -->|Structured Result Block| A

功能

- 完整因果链路： 沿 systemd -> ptyxis -> bash -> node -> esbuild 反向追踪进程，查清是谁启动并维持着目标进程。
- 端口冲突定位： 把端口号（如 3080、8080）直接翻译成占用它的 PID、父 shell、工作目录和当前 Git 分支。
- 文件锁诊断： 找出是哪个后台进程或守护进程占着文件描述符不放。
- 多格式输出： 支持人类可读的诊断文本、紧凑的层级树、JSON，以及用于可视化文档的 Mermaid.js 流程图。JSON 输出会省略进程环境变量，所以追踪进程绝不会把它的密钥带进模型上下文。
- DeepSeek 插件管理器 UI： 完整声明的 Cordis bundle，带本地化元数据、图标，以及 Web UI 中可配置的运行时参数。
- 退出码保真： 按 witr 文档化的退出码对每条 trace 分类，而不是去抓取它的输出，所以警告、「未找到」、「权限不足」都会作为答案返回，只有真正跑挂的运行才会让调用失败。
- 取消与安全： 严格只读；把 exec.signal 转发给 witr 子进程，取消的调用报告为已取消，而不是失败。

安装

前置条件

确保 witr 二进制已装进系统 PATH（例如 /usr/local/bin/witr）：

Verify witr binary
witr --version

方法 1：通过 DeepSeek 命令行添加

dsh plugin --profile web add @deepseek-ai/dsh-experimental-tool-witr

方法 2：配置档挂载（cordis.patch.yml）

在生效的配置档补丁文件（~/.dsh/profiles/<profile>/cordis.patch.yml）里加一条 - insert: 条目：

- insert:
- id: tool-witr
name: "@deepseek-ai/dsh-experimental-tool-witr"
config:
binaryPath: witr
timeoutMs: 10000

模型工具规范：witr_trace

挂载后，DeepSeek 模型即可使用以下工具 schema：

witr_trace({
target: string, // Port ("3080"), PID ("1234"), name ("node"), or file path
kind?: "port" | "pid" | "file" | "name", // Explicit discriminator; inferred when omitted
format?: "standard" | "tree" | "mermaid" | "dot" | "json",
exact?: boolean // Disable substring matching when searching by name
})

kind、format 和 target 会在 witr 运行前校验，所以超出取值范围的 kind 或 format 会被拒绝，而不是被悄悄忽略。

目标推断。 不传 kind 时，纯数字先按进程 ID 试，再按端口试；含 / 的值当作文件路径；其余一律当作进程名。非空 target 会加 -- 终止符后传给 witr，所以以 - 开头的进程名绝不会被误读成命令行参数。

工作目录。 相对 file target 按发起调用的会话工作目录解析，而不是按启动 harness 进程时所在的目录。智能体调用拿不到该目录时，相对 file target 会被拒绝，而不是悄悄按 harness 进程目录解析——请改用绝对路径重试。

并发。 该工具只读，因此标记为并发安全，多条 trace 可以共用一个工具批次。

结果

插件读取 witr 的退出码，而不是匹配输出文本——witr 把退出码当作契约，并明确把人类可读输出的措辞排除在契约之外。只有不携带答案的结果才会让工具调用失败：

| witr 退出码 | 含义 | 工具结果 |
| 0 | 找到，干净 | 回答 |
| 1 | 找到，有警告 | 回答 —— 警告就是诊断载荷 |
| 2 | 未找到 | 回答；同时驱动 PID → 端口回退 |
| 3 | 权限不足 | 回答 —— witr 自己的输出会说明如何提权 |
| 4 | 输入无效，或名称有歧义 | 错误；用 exact: true 或更完整的名称重试 |
| 5 | 内部错误 | 错误 |
| 6 | 找到，但原因无法追溯 | 回答 |
| — | witr 完全无法启动 | 错误，并指明 binaryPath |
| 其他任何非零值 | 无法识别的状态（信号、超时，或未来版本的 witr 退出码） | 错误 —— 绝不当作回答 |

规范结果是结构化的 —— { output, format, exitCode, warnings? } —— 其中 output 是面向模型的那一层投影。当 format: "json" 给出 witr 文档中说明的 Warnings 数组时，warnings 会被填充；退出码和警告数量作为展示元数据传到 UI。

智能体交互示例

1. 诊断被占用的端口

智能体调用： {
"name": "witr_trace",
"arguments": {
"target": "3080",
"kind": "port"
}
}

工具输出： Target : node Process : node (pid 9056) {forked} User : martin Command : node --import tsx/esm apps/cli/src/bin.ts web Started : 1 hour ago (Wed 2026-10-14 10:05:05 +01:00)

Why It Exists :
systemd (pid 1) → systemd (pid 4297) → ptyxis (pid 6407) → ptyxis-agent (pid 6421) → bash (pid 9030) → node (pid 9040) → sh (pid 9055) → node (pid 9056)

Source : sh (shell)
Working Dir : /home/martin/deepseek
Git Repo : deepseek (master)
Sockets : 127.0.0.1:3080 (TCP | LISTENING, 2 connections)

2. 生成可视化的 Markdown 架构图

智能体调用： {
"name": "witr_trace",
"arguments": {
"target": "3080",
"format": "mermaid"
}
}

工具输出：
graph TD
p1["systemd (pid 1)"]
p4297["systemd (pid 4297)"]
p1 --> p4297
p6407["ptyxis (pid 6407)"]
p4297 --> p6407
p6421["ptyxis-agent (pid 6421)"]
p6407 --> p6421
p9030["bash (pid 9030)"]
p6421 --> p9030
p9056["node (pid 9056) :3080"]
p9030 --> p9056
style p9056 fill:#2ecc71,stroke:#27ae60,stroke-width:2px,color:#ffffff

配置 Schema

通过 Cordis YAML 或 DeepSeek Web 设置界面配置：

| 选项 | 类型 | 默认值 | 说明 |
| binaryPath | string | "witr" | witr 二进制的路径。留空则回退到 "witr"。 |
| timeoutMs | number | 10000 | 子进程执行超时，单位毫秒（最小 1；不可用的值回退到 10000）。 |

开发与构建

Install dependencies
pnpm install

Typecheck the source and test suite
pnpm run typecheck

Compile TypeScript
pnpm run build

Run unit tests (Vitest)
pnpm run test

许可证

MIT © 2026 Martin M