Introduction¶
DSH’s adapter merged 403 into the authentication branch, placing it before quota determination. As a result, failures like “free quota exhausted” only show a “bad key” message in the interface, obscuring the original cause. These failures cannot be resolved by restarting, changing keys, or looking at logs; you need to first know what the installed artifact on your machine actually classifies 403 as.
Below is an introduction to the plugin dsh-error-doctor maintained by mengge237 (Category: Client, 0 stars, MIT, personal project, unrelated to upstream DSH). It only answers one question: what does your current artifact classify 403 as? It does not modify code for you.
What is it¶
One-sentence positioning: Performs a read-only health check on the installed DSH to determine whether a quota-related 403 response is classified as QUOTA or AUTH, and gives a conclusion via exit codes.
It patches the diagnostic method, not DSH itself. In the upstream 0.1.7-rc.1 artifact, 403 is still placed before quota determination. The same shape has been reported upstream in #3222 / #5715 / #3073 / #1127 / #1631. The existing community approach is to “read source code to see if 403 or quota determination appears first.” The author’s first version of this plugin was written exactly this way, but it failed in practice three times in a row (the next section explains why).
Core Functionality¶
The judgment logic is not a static scan of source code, but rather extracting classifyPiAiError, httpErrorCode (called providerError on the 0.1.7 branch, embedding the judgment chain into a homonymous shell) along with isQuotaExceededError from the installed artifact, feeding it a real 403 quota packet, and seeing if it returns QUOTA or AUTH. It does not recognize comments, line numbers, or versions; it still recognizes patches applied by others.
Read-only throughout: does not write files, does not send network requests, does not touch session archives, and does not read keys.
If the shape cannot be determined, it always exits with code 2 and explains the reason, without giving a green conclusion. Verified shapes: httpErrorCode from 0.1.5-rc.2, and providerError from 0.1.7-alpha.2 and 0.1.7-rc.1. If the upstream changes the shape again, it will refuse to judge rather than giving a false conclusion.
Installation and Usage¶
When the plugin is installed, it provides a tool surface to the agent:
dsh plugin --profile web add dsh-error-doctor # Must fully restart dsh web after installation
dsh plugin --profile web remove dsh-error-doctor
Tool name is dsh_error_doctor, with only the optional root parameter.
When used as a library:
import { findRoot, probeInstall } from "dsh-error-doctor";
import { toolConfig } from "dsh-error-doctor/plugin-config";
plugin-config does not import any host packages, so it can be tested on machines without DSH.
Regarding dependencies, there are two points recorded from the author’s practical testing: the host package @deepseek-ai/dsh-tools can only be resolved from the profile tree, so lib/index.js uses dynamic import and degrades on failure—if it cannot be resolved, it logs a warning, does not register the tool, and the CLI remains usable. To use the tool surface, install via the package; do not use link: to link the repository directly into the plugin tree, as static import will break the entire plugin tree (this applies to failure methods like cordis include).
Typical Usage¶
Run CLI, it finds the DSH installation directory from PATH:
node bin/dsh-error-doctor.mjs
Add --json for machine-readable output:
node bin/dsh-error-doctor.mjs --json
The output order is: first report the DSH installation path and version, then give whether each site’s 403 quota packet is classified as QUOTA or AUTH, and finally give the conclusion. The exit code is the criterion:
| Code | Meaning |
|---|---|
| 0 | Both are fixed (quota determination is first) |
| 1 | Both are still in factory shape—most likely the patch was silently wiped out by an upgrade |
| 2 | Cannot read or inconsistent on both sides: do not patch blindly, check the version first |
Running tests does not require installing DSH; fixtures are synthesized by test/make-tree.mjs in a temporary directory (mock tree of two shapes), and the repository does not contain copies of upstream artifacts:
npm test # 9 cases: 4 health checks + 5 tool surface tests
Two of the cases are worth noting: one specifically targets “artifact byte count unchanged after running the probe,” and one targets “must error out if it cannot be read, without giving a green conclusion.”
Why the Criterion Does Not Look at Source Code¶
This section is the most valuable part of this plugin and what differentiates it from “grepping it yourself.” The author’s first version was written according to “who appears first in the source code, 403 or quota determination,” but it failed in practice three times in a row:
- The patch’s own comments say
...then 403, static string scanning read the already-patched artifact as unpatched; - One correct fix method is to put quota determination inside the 403 branch,
if (status === 403) { if (isQuota(...)) return QUOTA; ... }— on the text level 403 comes first, but semantically it is already fixed; - The same artifact file also has another
status === 401 || status === 403, which is the error constructor for the Files API and is unrelated to classification; “taking the first match in the file” would directly change the wrong place (this was actually hit when creating the reference fixtures).
So now the approach of using a runtime probe to feed real packets is still used, rather than text matching.
Applicable Scenarios and Notes¶
Suitable for developers already using DSH who have encountered “invalid key” prompts but are unsure if it’s a key issue or a quota issue. Also suitable for attaching a health check tool to an agent so it can judge the environment status itself.
Notes:
- The plugin runs with the current dsh process permissions; check source code and license (MIT) before installing.
- DSH upgrades overwrite the installation directory; the disappearance of patches is silent and error-free. So “it was working recently” is not evidence; running this command once counts.
- Do not patch directly when skipping exit code 2; check the version first; when it cannot be read, a conclusion that filters out noise is itself wrong.
- This is a personal project unrelated to upstream; issues reported in upstream issues do not mean they are solved.
Conclusion¶
The value of this plugin lies not in providing another diagnostic command, but in the judgment method it chooses: not reading source code text, but feeding real packets to see the return. Regarding the premise that “upgrades silently overwrite the installation directory,” it replaces weak evidence like “it was working recently” with reproducible exit codes, at the cost of running one command. Directory: https://www.skillhub.cn/plugins/mengge237/dsh-error-doctor , Source code: https://github.com/mengge237/dsh-error-doctor .
