Skip to content

Commit 19e31c0

Browse files
zsxh1990zsxh1990
committed
feat(lessons): add DSH plugin install codeload-timeout lesson (from Ikalus1988#1418)
Signed-off-by: zsxh1990 <290087845+zsxh1990@users.noreply.github.com>
1 parent 4226f6c commit 19e31c0

2 files changed

Lines changed: 88 additions & 0 deletions

File tree

‎data/lessons.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1259,6 +1259,26 @@
12591259
"evidence_source": "inferred",
12601260
"trust_score": 0.35
12611261
},
1262+
{
1263+
"id": "dsh-plugin-install-github-codeload-timeout",
1264+
"title": "dsh-plugin-install-github-codeload-timeout",
1265+
"domain": "contrib",
1266+
"tags": [],
1267+
"summary": "Installing a DSH (DeepSeek Harness) plugin from the [dsh-plugin.org](https://dsh-plugin.org) marketplace failed with `安装失败 — 请求超时：无法访问 GitHub 或网络不稳定` (request t…",
1268+
"preview": "## Problem\n\nInstalling a DSH (DeepSeek Harness) plugin from the [dsh-plugin.org](https://dsh-plugin.org) marketplace failed with `安装失败 — 请求超时：无法访问 GitHub 或网络不稳定` (request timeout: cannot reach GitHub or network unstable). The marketplace's registered install command was:\n\n```bash\ndsh plugin --profile web add github:ikalus1988/misakanet\n```\n\n## Root Cause\n\n`dsh plugin add github:<owner>/<repo>` resolves through **codeload.github.com** to download the repository tarball. In some networks (especially in CN/GFW environments), `codeload.github.com` is blocked or times out while `api.github.com`, `raw.githubusercontent.com`, and `registry.npmjs.org` remain reachable. The install log shows:\n\n```\n[WARN] GET https://codeload.github.com/ikalus1988/misakanet/tar.gz/2932d914... error (23). Will retry in 10 seconds. 2 retries left.\n[WARN] ... Will retry in 1 minute. 1 retries left.\n```\n\nError code 23 = write error during curl download (network-level), not a plugin defect.\n\nA second contributing factor: the marketplace metadata (`npmPackage` field) may be stale/empty, forcing the marketplace to fall back to the git channel even when an npm package exists.\n\n## Fix\n\n1. **Prefer the npm channel** when the plugin is published to npm (independent of GitHub codeload):\n\n```bash\ndsh plugin add misakanet # from npm registry — fast, no GitHub dependency\n```\n\n2. Verify connectivity per endpoint before choosing a channel:\n\n```bash\ncurl -sS -o /dev/null -w \"%{http_code}\\n\" https://codeload.github.com/ # often blocked\ncurl -sS -o /dev/null -w \"%{http_code}\\n\" https://registry.npmjs.org/ # usually OK\n```\n\n3. On Windows, note that `python3` may not exist — only `python`. Cross-platform plugin test helpers must detect this:\n\n```js\nconst python = process.env.PYTHON || (process.platform === 'win32' ? 'python' : 'python3');\n```\n\n4. If you maintain a marketplace listing, keep `npmPackage` updated so the marketplace offers the npm channel.\n\n## Verification\n\n- `dsh plugin add misakanet` completes in ~1s (resolved, downloaded, added) when the package is on npm.\n- `dsh plugin --profile <name> --dump-config` shows the `# == misakanet` layer for the installed bundle.\n- The failing git-channel command reproduces the timeout deterministically in networks where codeload is blocked.",
1269+
"url": "lessons/contrib/dsh-plugin-install-github-codeload-timeout.md",
1270+
"created": "",
1271+
"updated": "",
1272+
"triggers": null,
1273+
"validity_period_days": 365,
1274+
"environment_version": "",
1275+
"confidence": 0.5,
1276+
"status": "active",
1277+
"verified": true,
1278+
"evidence_level": "E0",
1279+
"evidence_source": "inferred",
1280+
"trust_score": 0.35
1281+
},
12621282
{
12631283
"id": "erreur-permission-docker-linux",
12641284
"title": "erreur-permission-docker-linux",

‎lessons/contrib/dsh-plugin-install-github-codeload-timeout.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
title: DSH Plugin Install Failures — GitHub codeload Timeout vs npm Channel
3+
domain: mcp
4+
tags:
5+
- dsh
6+
- deepseek-harness
7+
- plugin
8+
- npm
9+
- codeload
10+
- github
11+
- timeout
12+
- install
13+
status: published
14+
created: '2026-09-01'
15+
language: en
16+
source: issue-1418
17+
evidence_level: E0
18+
---
19+
20+
## Problem
21+
22+
Installing a DSH (DeepSeek Harness) plugin from the [dsh-plugin.org](https://dsh-plugin.org) marketplace failed with `安装失败 — 请求超时：无法访问 GitHub 或网络不稳定` (request timeout: cannot reach GitHub or network unstable). The marketplace's registered install command was:
23+
24+
```bash
25+
dsh plugin --profile web add github:ikalus1988/misakanet
26+
```
27+
28+
## Root Cause
29+
30+
`dsh plugin add github:<owner>/<repo>` resolves through **codeload.github.com** to download the repository tarball. In some networks (especially in CN/GFW environments), `codeload.github.com` is blocked or times out while `api.github.com`, `raw.githubusercontent.com`, and `registry.npmjs.org` remain reachable. The install log shows:
31+
32+
```
33+
[WARN] GET https://codeload.github.com/ikalus1988/misakanet/tar.gz/2932d914... error (23). Will retry in 10 seconds. 2 retries left.
34+
[WARN] ... Will retry in 1 minute. 1 retries left.
35+
```
36+
37+
Error code 23 = write error during curl download (network-level), not a plugin defect.
38+
39+
A second contributing factor: the marketplace metadata (`npmPackage` field) may be stale/empty, forcing the marketplace to fall back to the git channel even when an npm package exists.
40+
41+
## Fix
42+
43+
1. **Prefer the npm channel** when the plugin is published to npm (independent of GitHub codeload):
44+
45+
```bash
46+
dsh plugin add misakanet # from npm registry — fast, no GitHub dependency
47+
```
48+
49+
2. Verify connectivity per endpoint before choosing a channel:
50+
51+
```bash
52+
curl -sS -o /dev/null -w "%{http_code}\n" https://codeload.github.com/ # often blocked
53+
curl -sS -o /dev/null -w "%{http_code}\n" https://registry.npmjs.org/ # usually OK
54+
```
55+
56+
3. On Windows, note that `python3` may not exist — only `python`. Cross-platform plugin test helpers must detect this:
57+
58+
```js
59+
const python = process.env.PYTHON || (process.platform === 'win32' ? 'python' : 'python3');
60+
```
61+
62+
4. If you maintain a marketplace listing, keep `npmPackage` updated so the marketplace offers the npm channel.
63+
64+
## Verification
65+
66+
- `dsh plugin add misakanet` completes in ~1s (resolved, downloaded, added) when the package is on npm.
67+
- `dsh plugin --profile <name> --dump-config` shows the `# == misakanet` layer for the installed bundle.
68+
- The failing git-channel command reproduces the timeout deterministically in networks where codeload is blocked.

0 commit comments

Comments
 (0)