@deepseek-ai/dsh-experimental-tool-witr
提供面向模型的 witr 因果进程、端口和锁追踪工具的 DeepSeek Harness 插件
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:martinm86867-ops/dsh-plugin-witr#ab42452bae7f23cd4deddf5a06a106d5d173c55bExperimental Tool Witr 以 @deepseek-ai/dsh-experimental-tool-witr 发布，当前版本为 1.0.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
dsh-plugin-witrThe causal process & port tracing plugin for DeepSeek Harness.
Gives autonomous DeepSeek agents instant root-cause visibility into running processes, port collisions (EADDRINUSE), and stuck file locks.
Autonomous agents frequently stall during development or operational loops when encountering state conflicts:
EADDRINUSE: 3080./var/lib/dpkg/lock-frontend is locked.ps aux only shows an uninformative child process without context.Standard agent workarounds—chaining ps aux, lsof, fuser, netstat, and kill -9—are fragile, hallucination-prone, and risk accidentally terminating the parent terminal or shell.
dsh-plugin-witr wires witr directly into the DeepSeek Harness tool registry via the Cordis plugin lifecycle.
Instead of guessing, the agent calls witr_trace to receive the complete supervisor hierarchy from systemd down through terminal emulators, shells, and parent containers in a single deterministic turn.
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 to pinpoint what launched and maintains the target.3080, 8080) directly into the owning PID, parent shell, working directory, and active Git branch.witr's documented exit codes instead of scraping its output, so warnings, "not found", and "insufficient privileges" arrive as answers and only genuinely broken runs fail the call.exec.signal to the witr subprocess and reports a cancelled call as cancelled rather than as a failure.Ensure the witr binary is installed in your system PATH (e.g. /usr/local/bin/witr):
# Verify witr binary
witr --version
dsh plugin --profile web add @deepseek-ai/dsh-experimental-tool-witr
cordis.patch.yml)Add an - insert: entry to your active profile patch file (~/.dsh/profiles/<profile>/cordis.patch.yml):
- insert:
- id: tool-witr
name: "@deepseek-ai/dsh-experimental-tool-witr"
config:
binaryPath: witr
timeoutMs: 10000
witr_traceWhen mounted, DeepSeek models gain access to the following tool 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, and target are validated before witr runs, so an out-of-vocabulary
kind or format is rejected instead of silently ignored.
Target inference. With no kind, a bare number is tried as a process ID first and then as a
port, a value containing / is treated as a file path, and anything else is a process name. Non-empty
targets are passed to witr after a -- terminator, so a process name that begins with - is never
misread as a command-line flag.
Working directory. A relative file target is resolved against the calling session's working
directory rather than the directory the harness process was launched from.
Concurrency. The tool is read-only, so it is marked concurrency-safe and several traces may share one tool batch.
The plugin reads witr's exit codes rather
than matching output text — witr documents the codes as the contract and the wording of its
human-readable output as explicitly outside it. Only the outcomes that carry no answer fail the tool
call:
witr exit | Meaning | Tool result |
|---|---|---|
0 | Found, clean | Answer |
1 | Found, with warnings | Answer — warnings are the diagnostic payload |
2 | Not found | Answer; also drives the PID → port fallback |
3 | Insufficient privileges | Answer — witr's own output says how to escalate |
4 | Invalid input, or an ambiguous name | Error; retry with exact: true or a fuller name |
5 | Internal error | Error |
6 | Found, but the cause can't be traced | Answer |
| — | witr could not be started at all | Error naming binaryPath |
The canonical result is structured — { output, format, exitCode, warnings? } — with output as
the model-facing projection. warnings is populated when format: "json" supplies witr's documented
Warnings array, and the exit code and warning count travel to the UI as presentation metadata.
Agent call:
{
"name": "witr_trace",
"arguments": {
"target": "3080",
"kind": "port"
}
}
Tool output:
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)
Agent call:
{
"name": "witr_trace",
"arguments": {
"target": "3080",
"format": "mermaid"
}
}
Tool output:
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
Configured via Cordis YAML or the DeepSeek Web Settings UI:
| Option | Type | Default | Description |
|---|---|---|---|
binaryPath | string | "witr" | Path to the witr binary. |
timeoutMs | number | 10000 | Subprocess execution timeout in milliseconds. |
# 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