dsh-gopeed-downloader

For GitHub Git specs the manager runs git ls-remote (5 s default) first, so git must be installed for a Git-URL install; otherwise install from a release tarball URL. A directory install records a link: dependency, and source edits then need the extra step described in the development notes below.

Gopeed's own source hardcodes network="tcp", address="127.0.0.1:0", apiToken="" (app_controller.dart), and binds it with net.Listen (pkg/rest/server.go). The 9999 in Gopeed's OpenAPI document and JS SDK is a client-side convention (the CLI and gopeed-web build default -P to 9999); the desktop app never listens there unless you set it.

With port at 0 the plugin asks Windows for the ports Gopeed.exe holds (netstat -ano, then Get-NetTCPConnection). When neither discloses them it says so and points at the fixed port instead of guessing. portScan exists for that case and is off by default, because sweeping the dynamic port range touches software unrelated to Gopeed. There is no silent 9999 fallback: it would make an honest "port unknown" diagnosis unreachable.

Save location is decided in this order, first match wins:

1. an explicit path argument to gopeed_add;
2. the session's current working directory, when downloadTarget is workspace (the default);
3. customDownloadPath, when downloadTarget is custom and the field is not empty;
4. otherwise the path is left unset and Gopeed uses the download directory from its own settings.

"Workspace" means the live directory, not the one the session started in. It is the directory the working_directory tool reports, so it follows a cd; the creation-time directory is only the fallback for a host that exposes no such projection. That keeps a download next to the files the agent is actually working on.

The fallbacks are reported, never silent: an unresolvable workspace or a custom target with an empty path still downloads into Gopeed's directory, and jobNote says which fallback happened. gopeed_add also reads the created task back once, because Gopeed fills meta.opts.path with the real directory even when no path was sent -- so the returned path is where the file actually lands rather than an echo of the argument. That read-back is best-effort: a failed GET does not fail an add Gopeed already accepted.

A normalized task looks like this:

{ "id": "0n37...", "name": "a.iso", "status": "running", "protocol": "http",
  "sizeBytes": 11857955, "downloadedBytes": 4200000, "percent": 35.4,
  "sizeKnown": true, "speedBytesPerSec": 1048576,
  "path": "D:\\Downloads", "createdAt": "..." }

Gopeed can POST an event to a URL when a task finishes or fails. This is push, not polling: Gopeed sends DOWNLOAD_DONE / DOWNLOAD_ERROR, and the plugin never guesses that a download ended.

The listener URL always has the form http://127.0.0.1:<port>/webhook.

manual mode: two steps in Gopeed, not one. The settings page shows the URL and a copy button when webhookPort is above 0 (with 0 the port is system-assigned, so read the real URL from gopeed_events after saving). In Gopeed open Settings -> Developer -> Webhook push and do both:

1. turn the "Enable webhook" switch on;
2. click "Add" and paste the listener URL.

An address alone sends nothing. Adding the URL without enabling the switch is the trap hit in practice: the list looks configured and the plugin still receives zero events.

auto mode: the plugin saves the URL. gopeed_events with action: "apply" is the only code path that saves Gopeed config, and it is refused unless webhookMode is auto. It reads the current config, changes only the webhook fields (webhook.enable = true, and the listener URL merged into webhook.urls, keeping every URL you already had), saves the whole config back, then reads it back and reports applied: true only if the URL is really there. A failed read leaves Gopeed untouched. action accepts apply and nothing else -- no "apply and restart", because no agent tool may restart or kill Gopeed.

A full restart is required afterwards. Gopeed applies webhook settings only after a complete restart; closing the window is not a restart (it minimizes to the tray and keeps running with the old settings). The GUI may keep showing the old values in the meantime, so "the settings screen looks unchanged" does not mean the save failed. The only restart entry point is the Restart Gopeed button.

Reading events. Events live in a 50-entry in-memory ring buffer; the oldest are dropped and the buffer is empty after a plugin or DSH restart. gopeed_events filters by since (a timestamp) and unreadOnly. Returning events marks them read, so a second unreadOnly: true call returns nothing until new events arrive. gopeed_process also reports the webhook status, so the wiring can be checked without the buffer.

Three channels, none in the conversation.

1. The background job -- primary, and the only channel that can wake an agent. gopeed_add registers a DSH job that polls Gopeed and settles when the download ends; DSH's own dsh-tool-jobs turns that into an in-session completion notice (busy agent: next step; idle agent: woken with a follow-up turn).
2. The bottom-right toast -- opt-in and human-facing (webhookToast, off by default because Gopeed already posts its own Windows notification). The page polls an authenticated GET /api/dsh-gopeed-downloader/notifications route and each toast vanishes after 6 seconds; it never marks the buffer as read.
3. Agent.inject -- the fallback, for a completion no job covers (a download started in the Gopeed UI, or a host whose composition has no ctx.jobs). The same summary is queued as model-facing context for the agent's next pre-step; it does not wake the agent. A task a job owns is deliberately not injected, since both channels carried the same completion and a real session showed the model reading it twice.

webhookNotify (default on) gates channels 2 and 3. Channel 1 follows gopeed_add and needs no webhook at all, so an agent-started download is still reported with webhookMode: "off".

Restarting Gopeed. Press the red Restart Gopeed button on the settings page; it asks for confirmation first. It force-kills the running process (taskkill /F), waits until the pid is really gone from the process table, starts Gopeed again, then waits up to 15 seconds for its endpoint to answer, re-detecting the port as it goes. It does not save webhook config -- registering the listener URL is the separate apply step (or your own entries in manual mode). A plain taskkill (without /F) only posts a close message, which Gopeed answers by minimizing to the tray, so stopping is always forced here.

Run gopeed_process first; it classifies the situation into one of six verdicts.

misconfigured keeps a wrong port from being reported as stopped: telling someone to launch a program that is already running sends them to the wrong fix. It only appears when the process probe can actually see the process. Read processProbe before you believe processFound -- when it is unavailable the environment would not hand over the process list, so processFound: false does not mean Gopeed is down. The probe checks whether it can see its own process first, and reports unavailable rather than an empty list that looks like "not running".

Launching. gopeed_launch needs no configured path; it looks for Gopeed.exe and stops at the first hit:

Steps 3-5 share one PowerShell call and only run when step 2 missed; the result is cached and recomputed if the cached path disappears. Nothing found? The tools do not guess: gopeed_process.advice and gopeed_launch.message list every location tried and ask you to install Gopeed or set the path for a portable build. Launching uses a detached spawn with no console, effectively a double-click, then polls for up to 15 seconds. It re-detects the port while it waits (a fresh Gopeed comes up on a new random port that only appears once the process listens) and probes the resolved port, not the raw 0, so an already-running Gopeed is left alone instead of being launched twice. If the process list cannot be read there is no pid, so the restart path says so and gives manual steps instead of reporting success.

Guiding the user. When any tool hits a connection failure or a timeout, it appends a short English step-by-step notice to that tool's own result (an error message, or gopeed_process.advice): install Gopeed, open its protocol settings and pin the port, match the token. It is appended at most once per plugin lifetime, and a failure to build it never masks the tool's own error. Task-level errors -- an unknown id, for example -- deliberately do not trigger it. A wrong token takes a shorter route: the failure ends with -- the token is wrong; set it in the plugin settings (gopeed_process explains it). That sentence already means the port is right (the 401 answer proves it), so the repair is the token and nothing else.

Sandbox vs. plugin runtime. Read-only diagnosis (tasklist, Get-Process, netstat, Get-NetTCPConnection, netsh, file reads, the loopback probe) runs unconfined, because a confined shell often cannot see other processes at all, which would make the diagnosis worthless. gopeed_launch runs through ctx.sandbox.confine under the calling session's file policy, and, when that policy refuses it, nothing is started: the plugin never silently falls back to an unconfined run. The config-page restart button runs unconfined because it is a user gesture, not an agent action. Every result says which one happened: diagnosticsSandboxed plus diagnosticsSandboxNote, and launchSandboxed / sandboxMode / sandboxDetail on gopeed_launch.

Version badge. The settings page shows the loaded browser bundle next to the backend version reported by gopeed_process. If the page shows a lower version, the browser is still running the previous bundle: restart DSH, then refresh the page.

Polling gopeed_status is the wrong way to wait for a download: it burns a step per check, and the agent has nothing to react to when the file lands. So gopeed_add also registers the download as a DSH background job (kind: 'gopeed', id gopeed-<16 hex>), and DSH reports it when it ends.

• gopeed_add returns jobId; its own output names the matching job_output call and says explicitly not to poll for progress. Only when no job could be started does the output suggest polling gopeed_status.
• The job polls the task every 3 seconds, slowing to every 30 seconds while the task is pause or wait.
• On completion it settles as completed with the file size; on a Gopeed error status as failed; when the task disappears from Gopeed as killed (removed outside the plugin).
• dsh-tool-jobs then delivers its own completion notice. This is the official DSH mechanism (ctx.jobs plus dsh-tool-jobs notices), not a user message the plugin forged, and nothing is added to the transcript by the plugin.
• gopeed_control with action: "remove" cancels the tracking job, so a removed download never leaves an orphan poller behind.
• job_output <jobId> (optionally with wait: true) reads the job and blocks up to the configured timeout. Use it to collect a job before the final answer instead of busy-polling.

Degradation is reported, never silent. Without a ctx.jobs service, gopeed_add still works: jobId is "" and jobNote says why, so no completion notice will arrive -- follow the download with gopeed_status or the webhook channel then.

A stalled task is not a failed task. A task that stays pause / wait for 24 hours stops being tracked and is reported as killed with "task still pause, download NOT cancelled"; a still-moving download also stops being tracked after 24 hours, and its detail says the download itself was not touched. failed is reserved for an unreachable endpoint or a Gopeed error status.

Reloads and restarts. A plugin reload (or a profile remount) stops every tracker; each settles as killed with a detail saying the download state is now unknown and the Gopeed task may still be running -- DSH's outcome vocabulary has no "unknown", so the detail is the only honest place to say it. A DSH restart loses tracking entirely, because the jobs live inside the DSH process; the downloads keep running in Gopeed.

DSH projects every tool's {name, description, parameters} into the system prompt on every turn (output.schema and render do not), so that text is a permanent cost. The seven tools measure:

The total is 1452 characters, 352 over the 1100 target. Each description is one fragment that never repeats the gopeed_ prefix, and parameter descriptions are dropped except path (a wrong "file instead of directory" silently downloads to the wrong place). additionalProperties: false is left out to match the shape defineTool produces (validation happens in execute). The one meaning that cannot live in a name -- force deletes files -- is carried by gopeed_control's description.

The schema skeleton (names, required arrays, enum values) is deliberately kept: that is what DSH validates, so shrinking it further would drop parameters, not characters. name and the value enums stay for the same reason: hiding a real parameter or a legal value costs more in wrong calls than the characters save. Every download capability is still exposed. The download wake-up costs zero prompt characters, because jobId / jobNote live in output.schema only.

A local checkout installs as a directory spec (an absolute path). DSH records it as a link: dependency, and edits are picked up by a DSH restart -- or, for changes inside apply(), by calling plugin_manager's set_plugin on include:gopeed with enabled: false then enabled: true, which re-runs apply() so tool descriptions and render strings update immediately. Module-level state is not guaranteed to reset, so changes to lib/ or top-level constants still call for a full restart. Front-end changes in client.js need a browser page refresh.

One manual step for link installs. Node resolves the bare imports @deepseek-ai/schemastery and @deepseek-ai/cosmokit relative to the plugin's real path. When that path sits outside the profile, the profile's node_modules is not on the resolution chain, so a local checkout needs those two packages next to index.js. They are optional peer dependencies and are not vendored here: copy them from your DSH installation (matching versions) into a local node_modules/, which .gitignore keeps out of the repository. Installing from npm, a Git URL or a tarball does not need this.

Layout. package.json (bundle manifest), cordis.patch.yml (inserts one row, id: gopeed), index.js (host half: Config and the seven tools), client.js (web half: the form, the toast overlay and the restart button), lib/api.js (REST client, task normalization, process probing and launching), lib/webhook.js (loopback webhook receiver and the 50-entry ring buffer), locale/ and icon.svg. Neither lib/ module imports anything from DSH, so both can be exercised with plain Node.

Language policy. The plugin carries no Chinese: every string in index.js and lib/ is English (tool names, descriptions, render() output, messages, error text, comments), because tool descriptions sit in the system prompt on every turn. Chinese lives only in the docs -- docs/README.zh.md and docs/GETTING-STARTED.md are reading material for Chinese-speaking humans, not agent input. One deliberate exception: client.js ships a zh / en dictionary for the settings form and the toasts, because that interface is read by the person configuring the plugin. When editing a string, ask who reads it: model context -> English; a human in the Web UI or on GitHub -> follow that split.