dsh-plugin 1.6.11 → 2.0.0

package/lib/services/npm-release-age.js

@@ -0,0 +1,119 @@
+/**
+ * DSH Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * npm 包最新版本的发布时间查询：为「已安装插件是否有更新」提供供应链门禁依据。
+ * pnpm 对发布不满 24h（dsh profile minimumReleaseAge=1440）的版本会静默回退到旧版本，
+ * 因此发布未满门槛的版本不该提示更新（否则用户点了也装不上）。
+ * 结果按包名内存缓存，同一次会话内不重复请求；失败/超时/响应过大一律返回 null，绝不抛错、绝不阻塞。
+ */
+import { get as httpsGet } from 'node:https';
+import { validPackageName } from './profile/profile.js';
+import { fetchViaCurl } from './probe.js';
+/** 请求体包名数量上限：只为已安装插件按需查询，几十个足矣，封顶防滥用。 */
+export const MAX_RELEASE_AGE_PACKAGES = 50;
+/** 单包查询超时（ms）：慢网络下失败即返回 null，不拖住整个响应。 */
+export const RELEASE_AGE_TIMEOUT_MS = 8000;
+/** 响应体上限：完整 packument 可能达数 MB，超限直接放弃，避免异常大包拖垮服务。 */
+const MAX_PACKUMENT_BYTES = 10 * 1024 * 1024;
+export const DEFAULT_NPM_REGISTRY = 'https://registry.npmjs.org';
+/** 会话内缓存（包名 → 版本与发布时间）：只存成功结果，一次网络抖动不会把判断永久粘住。 */
+const releaseCache = new Map();
+/** 从完整 packument 取 dist-tags.latest 对应版本及其发布时间；缺任一字段返回 null。 */
+export function latestReleaseOf(packument) {
+    if (packument === null || typeof packument !== 'object')
+        return null;
+    const doc = packument;
+    const tags = doc['dist-tags'];
+    const version = tags !== null && typeof tags === 'object' ? tags.latest : undefined;
+    if (typeof version !== 'string' || version === '')
+        return null;
+    const time = doc.time;
+    const publishedAt = time !== null && typeof time === 'object' ? time[version] : undefined;
+    if (typeof publishedAt !== 'string' || publishedAt === '')
+        return null;
+    return { version, publishedAt };
+}
+/** 请求体 → 去重后的合法包名列表；非数组 / 超量 / 含非法包名一律 null（拒绝非法输入）。 */
+export function parseReleaseAgeRequest(body) {
+    if (body === null || typeof body !== 'object')
+        return null;
+    const raw = body.packages;
+    if (!Array.isArray(raw) || raw.length > MAX_RELEASE_AGE_PACKAGES)
+        return null;
+    const names = new Set();
+    for (const item of raw) {
+        if (typeof item !== 'string' || item === '' || item.startsWith('-') || !validPackageName(item))
+            return null;
+        names.add(item);
+    }
+    return [...names];
+}
+/** node:https 直连 GET，仅接受 200；超时/超限/网络失败返回 null。 */
+function getJson(url, timeoutMs) {
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = (value) => { if (!done) {
+            done = true;
+            resolve(value);
+        } };
+        const req = httpsGet(url, { timeout: timeoutMs, headers: { accept: 'application/json' } }, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                finish(null);
+                return;
+            }
+            const declared = Number(res.headers['content-length']);
+            if (Number.isFinite(declared) && declared > MAX_PACKUMENT_BYTES) {
+                res.destroy();
+                finish(null);
+                return;
+            }
+            let body = '';
+            let bytes = 0;
+            res.on('data', (chunk) => {
+                bytes += chunk.length;
+                if (bytes > MAX_PACKUMENT_BYTES) {
+                    res.destroy();
+                    finish(null);
+                    return;
+                }
+                body += chunk.toString();
+            });
+            res.on('end', () => finish(body));
+            res.on('error', () => finish(null));
+        });
+        req.on('timeout', () => req.destroy());
+        req.on('error', () => finish(null));
+    });
+}
+/** 拉取一个包的完整 packument 正文；配了代理时复用与安装/目录同一套代理口径（curl 子进程注入 proxy env）。 */
+async function fetchPackument(url, proxy, timeoutMs) {
+    if (proxy !== '') {
+        const r = await fetchViaCurl(url, proxy, timeoutMs);
+        return r.ok && r.body !== '' && Buffer.byteLength(r.body) <= MAX_PACKUMENT_BYTES ? r.body : null;
+    }
+    return getJson(url, timeoutMs);
+}
+/** 查询一个包的最新版本与发布时间（成功结果缓存，同会话内同包不重复请求）；registry 为空回退官方源，失败返回 null。 */
+export async function lookupReleaseAge(packageName, registry, proxy, timeoutMs = RELEASE_AGE_TIMEOUT_MS) {
+    const cached = releaseCache.get(packageName);
+    if (cached !== undefined)
+        return cached;
+    const base = registry.replace(/\/+$/, '') || DEFAULT_NPM_REGISTRY;
+    const body = await fetchPackument(`${base}/${encodeURIComponent(packageName)}`, proxy, timeoutMs);
+    if (body === null)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return null;
+    }
+    const release = latestReleaseOf(parsed);
+    if (release !== null)
+        releaseCache.set(packageName, release);
+    return release;
+}

package/lib/services/probe.js

@@ -79,7 +79,7 @@ function macSystemProxy() {
  * `http=host:port;https=host:port`（按协议分别配置）。
  * 字符类必须同时排除 `/` 与 `=`：只排除 `=` 时，带 scheme 的值会让「主机名」吞掉 `//`，
  * 拼出 `http:////127.0.0.1:10793` 这种立刻失败的非法地址 —— 代理本来是通的，却把诊断、
- * 目录拉取、npm/git 预检全判成「不可达」。
+ * 目录拉取、安装前网络探测全判成「不可达」。
  */
 export function parseWinProxyServer(stdout) {
     const m = /([^:\s=/]+):(\d+)/.exec(stdout);
@@ -199,13 +199,13 @@ export function probeUrl(url, proxy, timeoutMs) {
     return curlProbe(target.href, proxy, timeoutMs);
 }
 /**
- * git 通道真实克隆握手探测：spawn git ls-remote（https 传输，与 pnpm 克隆前的
+ * git 真实克隆握手探测：spawn git ls-remote（https 传输，与 pnpm 克隆前的
  * ref 握手一致），注入代理 env，GIT_TERMINAL_PROMPT=0 防凭据提示挂起。
  *
  * 为什么要真实 git 而非 curl 打网页：网页「能打开」和 git「能克隆」是两码事 ——
  * 防火墙/代理常按端口与协议区分，HTTP 页可达不代表 git 传输可达。这里测的就是
- * 克隆握手本身，回答「github:owner/repo 装不装得动」。
- * 供系统诊断 GitHub 通道使用；探测目标用 dshplugin/hello-dsh 小仓库（秒级完成，
+ * 克隆握手本身，回答「能不能连上 github.com」。
+ * 供系统诊断 GitHub 可达性使用；探测目标用 dshplugin/hello-dsh 小仓库（秒级完成，
  * 不打 17MB 的 dsh-plugin-hub 主页）。
  */
 export function gitLsRemote(url, proxy, timeoutMs) {

package/lib/services/profile/installed-versions.js

@@ -3,23 +3,19 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Installed-plugin version tracking.
+ * 已安装插件版本追踪。
  *
- * The installed table (`readInstalled` in routes.ts) only knows the manifest
- * spec of each Git dependency, which carries no version.
- * To let the Plugin Hub tell "an update is available", we record the catalog
- * signal present at install time into a small per-profile JSON file, then
- * compare it against the catalog's current signal later.
+ * 已安装表（routes.ts 的 `readInstalled`）只知道每个 Git 依赖的 manifest spec，不含版本号。
+ * 为让插件中心能判断「有更新」，我们把安装时的目录信号记进一个 per-profile 的小 JSON 文件，
+ * 之后再与目录当前信号比对。
  *
- * Two signals cover every repo:
- *   - version:  the catalog's latest release tag (e.g. v1.2.3). Repos that
- *     publish releases are compared on this.
- *   - updatedAt: the repo's last push time (GitHub pushed_at, `repoUpdatedAt`).
- *     Repos that never publish a release fall back to this: a newer push time
- *     means new commits → an update is available.
+ * 两个信号覆盖所有仓库：
+ *   - version：目录最新 release tag（如 v1.2.3），发 release 的仓库按它比对。
+ *   - updatedAt：仓库最近 push 时间（GitHub pushed_at，即 `repoUpdatedAt`），
+ *     从不发 release 的仓库回退用它：push 时间变新即有新提交 → 有更新。
  *
- * Storage: `DSH_HOME/profiles/<profile>/gro.ngilp-hsd-versions.json`
- *   { "<owner>/<repo>" (lowercase): { version: string, updatedAt: string, installedAt: string } }
+ * 存储：`DSH_HOME/profiles/<profile>/gro.ngilp-hsd-versions.json`
+ *   { "<owner>/<repo>"（小写）: { version, updatedAt, installedAt } }
  */
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -36,20 +32,18 @@ export function readInstalledVersions(profile) {
         return {};
     }
 }
-/** Record the catalog signals (version + repo updated time) present at install time for one repo. */
+/** 记录某仓库安装时的目录信号（版本 + 仓库更新时间）。 */
 export function recordInstalledVersion(profile, repo, version, updatedAt) {
     const table = readInstalledVersions(profile);
     const key = repo.toLowerCase();
-    // 合并写入：保留已记录的 npmPackage（npm 优先通道的 repo → 包名映射），
+    // 合并写入：保留已记录的 npmPackage（repo → 包名映射），
     // 客户端同步版本信号时不能把它覆盖掉
     table[key] = { ...table[key], version, updatedAt, installedAt: new Date().toISOString() };
     writeVersions(profile, table);
 }
 /**
- * Record the npm package name resolved for a repo (npm-first install channel).
- * Called at `/install` time so the mapping exists even before the task finishes;
- * harmless when the repo is not (yet) installed — the client only treats a repo
- * as installed when its dependency key actually exists.
+ * 记录某仓库解析出的 npm 包名。在 `/install` 时调用，让映射在任务完成前就存在；
+ * 仓库尚未安装时也无害 —— 客户端只在依赖 key 真实存在时才把仓库当作已安装。
  */
 export function recordResolvedNpmPackage(profile, repo, npmPackage) {
     const table = readInstalledVersions(profile);
@@ -57,7 +51,7 @@ export function recordResolvedNpmPackage(profile, repo, npmPackage) {
     table[key] = { ...table[key], npmPackage };
     writeVersions(profile, table);
 }
-/** Forget the recorded version for one repo (called on uninstall). */
+/** 清除某仓库记录的版本（卸载时调用）。 */
 export function removeInstalledVersion(profile, repo) {
     const table = readInstalledVersions(profile);
     delete table[repo.toLowerCase()];

package/lib/services/profile/profile.js

@@ -11,7 +11,7 @@ import { homedir } from 'node:os';
 import { basename, dirname, join } from 'node:path';
 import { PACKAGE_RE, REPO_RE } from '../install/install-types.js';
 import { githubReleaseTarget } from '../install/release-target.js';
-/** Resolve the active profile from the booted CLI args, falling back to `web`. */
+/** 从启动参数解析当前 profile，取不到落回 `web`。 */
 export function readProfileArg(fallback = 'web') {
     return profileFromArgv(process.argv, fallback);
 }
@@ -46,44 +46,18 @@ export function profileFromArgv(argv, fallback = 'web') {
     }
     return fallback;
 }
-/** Resolve a profile directory (`DSH_HOME` or `~/.dsh`). */
+/** 解析 profile 目录（`DSH_HOME` 或 `~/.dsh`）。 */
 export function profileDirectory(profile) {
     return join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'profiles', profile);
 }
-/** Build a safe explicit HTTPS Git target, or null when the repo is unsafe.
- *  When `ref` is given it is appended as a Git ref (`#tag` / `#commit`) so an
- *  explicitly pinned revision reaches the installer instead of being dropped. */
+/** 把仓库身份转成规范的 GitHub 目标（git+https），仓库不合法时返回 null。
+ *  带 ref 时按 Git ref（`#tag` / `#commit`）拼接；安装通道已不再使用 git 目标，此函数仅做身份规范化。 */
 export function githubTarget(repo, ref) {
     if (typeof repo !== 'string' || !REPO_RE.test(repo))
         return null;
     const url = `git+https://github.com/${repo}.git`;
     return ref === undefined || ref === null || ref === '' ? url : `${url}#${ref}`;
 }
-/**
- * Extract a validated explicit Git ref (`#<ref>`) from a GitHub spec, or null.
- * Only the fragment of a Git-style address qualifies — a pinned tag/commit is
- * user intent and must survive target normalization, whereas `#…` on a plain
- * web URL (`https://github.com/o/r#readme`) is a page anchor, not a ref.
- * Git-style = `git+…` / `github:` / `git@…` / `…​.git` / bare `owner/repo`.
- * Grammar mirrors a Git ref: no leading `.`/`-`, no `#`/whitespace.
- */
-const GIT_REF_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
-export function githubRefOf(value) {
-    if (typeof value !== 'string')
-        return null;
-    const input = value.trim();
-    const hash = input.indexOf('#');
-    if (hash <= 0)
-        return null;
-    const base = input.slice(0, hash);
-    if (githubRepoOf(base) === null)
-        return null;
-    const gitStyle = /^(?:git\+|github:|git@)/i.test(base) || /\.git$/i.test(base) || !base.includes('://');
-    if (!gitStyle)
-        return null;
-    const ref = input.slice(hash + 1);
-    return GIT_REF_RE.test(ref) ? ref : null;
-}
 /**
  * DSH 命令行前缀（官方唯一形式 `dsh plugin --profile <name> <add|update> <target>`）—— 提取其中的安装目标；
  * 非命令输入原样返回。兼容「直接粘贴完整命令」（防用户输错）：--profile 必填且只有长选项
@@ -114,7 +88,7 @@ export function globalNpmPackagesOf(value) {
         return null;
     return packages;
 }
-/** Extract an owner/repo identity from a catalog value or an installed Git spec. */
+/** 从目录值或已装 Git spec 中提取 owner/repo 身份。 */
 export function githubRepoOf(value) {
     if (typeof value !== 'string')
         return null;
@@ -142,23 +116,22 @@ export function githubRepoOf(value) {
     }
     return null;
 }
-/** Validate an npm package name (uninstall target grammar). */
+/** 校验 npm 包名（卸载目标的语法）。 */
 export function validPackageName(name) {
     return typeof name === 'string' && PACKAGE_RE.test(name);
 }
 /**
- * The exact `allowBuilds` key pnpm printed in its
- * `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` hint. For Git installs pnpm
- * matches against `name@<resolved fetch URL>` — the URL it actually fetches,
- * e.g. `https://codeload.github.com/<owner>/<repo>/tar.gz/<commit>` — not the
- * `git+ssh://`/branch spec. A bare name or a `git+` spec does not match, so
- * the only reliable key is the one pnpm prints verbatim. Null when absent.
+ * 取 pnpm 在 `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` 提示里原样打印的 `allowBuilds` key。
+ * Git 安装时 pnpm 按 `name@<实际 fetch URL>`（如
+ * `https://codeload.github.com/<owner>/<repo>/tar.gz/<commit>`）匹配，而不是 `git+ssh://`
+ * 或分支 spec —— 裸包名与 `git+` spec 都匹配不上，唯一可靠的 key 就是 pnpm 原样输出的那个。
+ * 无则返回 null。
  */
 export function parseAllowBuildsKey(output) {
     const m = /^[ \t]*(\S+@\S+):[ \t]*true[ \t]*$/m.exec(output);
     return m === null ? null : m[1].trim();
 }
-/** Quote a YAML block-mapping key when a plain scalar would be invalid. */
+/** 当裸标量非法时，为 YAML 块映射 key 加引号。 */
 function quoteYamlKey(key) {
     if (/^[-?:,[\]{}#&*!|>'"%@`]/.test(key) || /:(\s|$)/.test(key)) {
         return `'${key.replace(/'/g, "''")}'`;
@@ -166,10 +139,9 @@ function quoteYamlKey(key) {
     return key;
 }
 /**
- * Add one `allowBuilds` entry to the profile's pnpm-workspace.yaml, merging
- * with existing entries and leaving the rest of the yaml intact. Broken
- * placeholder entries (pnpm's failed-install bug writes a literal
- * `set this to true or false` value) are dropped on rewrite.
+ * 向 profile 的 pnpm-workspace.yaml 追加一条 `allowBuilds` 记录：与已有条目合并，
+ * 其余 yaml 保持不变；重写时丢弃损坏的占位条目（pnpm 安装失败的 bug 会写入
+ * 字面量 `set this to true or false`）。
  */
 export function addAllowBuildsKey(profile, key) {
     const file = join(profileDirectory(profile), 'pnpm-workspace.yaml');
@@ -177,7 +149,7 @@ export function addAllowBuildsKey(profile, key) {
     try {
         yaml = readFileSync(file, 'utf8');
     }
-    catch { /* created below */ }
+    catch { /* 文件不存在，下方创建 */ }
     const eol = /\r\n/.test(yaml) ? '\r\n' : '\n';
     const blockRe = /allowBuilds:[ \t]*\r?\n((?:[ \t]+[^\r\n]*\r?\n?)*)/g;
     const map = new Map();

package/lib/services/profile/progress.js

@@ -3,22 +3,19 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Pure progress-estimation helpers shared by the install runner.
+ * 安装执行器共用的纯进度估算工具。
  *
- * The dsh CLI wraps pnpm, which refreshes its `Progress: …` line in place
- * with carriage returns, so raw output arrives as a stream of partial
- * fragments. These helpers normalize one fragment into a clean terminal
- * line and map it onto a 0-100 estimate; keeping them free of I/O makes the
- * estimation logic directly unit-testable (see tests/progress.test.ts).
+ * dsh CLI 包装了 pnpm，pnpm 用回车原地刷新 `Progress: …` 行，因此原始输出是一串碎片。
+ * 这些工具把单个碎片归一化成干净的终端行，并映射到 0-100 估算值；不碰 I/O
+ * 让估算逻辑可直接单测（见 tests/progress.test.ts）。
  */
-/** Strip the `[out]` / `[err]` source prefix and ANSI escape sequences. */
+/** 剥掉 `[out]` / `[err]` 来源前缀与 ANSI 转义序列。 */
 export function cleanLine(raw) {
     return raw.replace(/^\[(?:err|out)\]\s*/, '').replace(/\x1b\[[0-9;]*[A-Za-z]/g, '').trim();
 }
 /**
- * Estimate 0-100 progress from one CLI output line. pnpm emits
- * `Progress: resolved N, reused X, downloaded Y, added Z` during the fetch
- * phase; resolution/install phase lines bump the estimate towards done.
+ * 从单行 CLI 输出估算 0-100 进度。pnpm 在 fetch 阶段输出
+ * `Progress: resolved N, reused X, downloaded Y, added Z`；解析/安装阶段的行把估算值推向完成。
  */
 export function estimateProgress(line) {
     const progress = line.match(/Progress:\s*(.+)/);
@@ -26,7 +23,7 @@ export function estimateProgress(line) {
         let resolved = 0;
         let handled = 0;
         for (const part of progress[1].split(',')) {
-            // pnpm emits `label count` tokens, e.g. `resolved 100, reused 40`
+            // pnpm 输出 `label count` 形式的 token，如 `resolved 100, reused 40`
             const [label, raw] = part.trim().split(/\s+/);
             const value = Number(raw);
             if (label === 'resolved')

package/lib/services/settings.js

@@ -3,9 +3,8 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Hub settings persistence: one `hub-settings.json` per active profile
- * (next to pnpm-workspace.yaml). All fields optional; missing keys fall
- * back to DEFAULT_SETTINGS so old files stay readable as new options land.
+ * 插件中心设置持久化：每个活跃 profile 一个 `hub-settings.json`（与 pnpm-workspace.yaml 同目录）。
+ * 所有字段可选；缺失的 key 回退到 DEFAULT_SETTINGS，新选项上线后旧文件仍可读。
  */
 import { readFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
 import { dirname, join } from 'node:path';
@@ -15,8 +14,6 @@ export const DEFAULT_SETTINGS = {
     proxy: '',
     npmRegistry: '',
     enableNpmInstall: true,
-    enableGitInstall: true,
-    enableDshInstall: true,
     logPath: '',
 };
 export function settingsFile(profile) {

package/lib/types/http/catalog.d.ts

@@ -1,6 +1,6 @@
 import { type WebRoute, type WebServerService } from './shared.ts';
 export declare function profileDirectory(profile: string): string;
-/** Read non-official dependencies installed into one profile. */
+/** 读取安装进某 profile 的非官方依赖。 */
 export declare function readInstalled(profile: string): Record<string, string>;
 /** 读已装依赖实际落在磁盘上的仓库身份（`owner/repo`）：解析 node_modules/<name>/package.json
  *  的 repository 字段。已装 spec 可能是纯版本号（丢了仓库身份），但真实包元数据仍指向来源仓库，

package/lib/types/http/install.d.ts

@@ -3,8 +3,8 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Install/uninstall routes: validate the target and spawn the official dsh CLI
- * (see services/install/install.ts), reporting the captured result back.
+ * 安装/卸载路由：校验目标后 spawn 官方 dsh CLI（见 services/install/install.ts），
+ * 并回传捕获的结果。自定义安装只接受 npm 包名。
  */
 import { type LoaderHandle } from '../services/install/install.ts';
 import { type WebRoute, type WebServerService } from './shared.ts';

package/lib/types/http/npm-release-age.d.ts

@@ -0,0 +1,2 @@
+import { type WebRoute, type WebServerService } from './shared.ts';
+export declare function registerNpmReleaseAgeRoutes(webServer: WebServerService, profile: string): WebRoute[];

package/lib/types/http/routes.d.ts

@@ -3,24 +3,22 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Local HTTP routes exposing real installs to the in-app Plugin Hub UI.
- * The client fetches the same-origin `/dsh-plugin-hub/*` endpoints; the
- * install handler validates the target, then spawns the official dsh CLI
- * (see services/install/install.ts) and reports the captured result back.
+ * 本地 HTTP 路由：把真实安装能力暴露给应用内的插件中心 UI。客户端请求同源
+ * `/dsh-plugin-hub/*` 端点；安装处理校验目标后 spawn 官方 dsh CLI（见
+ * services/install/install.ts）并回传捕获的结果。
  */
 import { type LoaderHandle } from '../services/install/install.ts';
 import { type WebServerService } from './shared.ts';
 /**
- * Register the Plugin Hub API on the host web server and return a disposer.
- * @param webServer - DSH web server service.
- * @param profile - profile that owns plugin mutations.
- * @param loader - running loader (optional): lets uninstall remove the entry
- *   immediately so the page survives a refresh without a host restart.
+ * 在宿主 web server 上注册插件中心 API 并返回 dispose 函数。
+ * @param webServer - DSH web server 服务。
+ * @param profile - 拥有插件变更权限的 profile。
+ * @param loader - 运行中 loader（可选）：让卸载立即移除条目，页面刷新即生效、无需重启宿主。
  */
 export declare function mountPluginHubRoutes(webServer: WebServerService, profile: string, loader?: LoaderHandle): () => void;
-/** Profile resolution shared with the client route docs. */
+/** 与客户端路由文档共用的 profile 解析。 */
 export { readProfileArg } from '../services/install/install.ts';
-/** Re-exported so the host entry (index.ts) keeps importing it from this module. */
+/** 转出以便宿主入口（index.ts）继续从本模块引入。 */
 export type { WebServerService } from './shared.ts';
-/** Re-exported so tests/routes.test.ts keeps importing these from this module. */
+/** 转出以便 tests/routes.test.ts 继续从本模块引入。 */
 export { isDesktopHost, isSameOrigin } from './shared.ts';

package/lib/types/http/shared.d.ts

@@ -3,9 +3,8 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Shared HTTP utilities: route/service types, request validation helpers and
- * the same-origin check guarding every POST mutation. Imported by the other
- * route modules in this directory.
+ * 共享 HTTP 工具：路由/服务类型、请求校验助手，以及守卫每个 POST 变更的同源校验。
+ * 由本目录其它路由模块引入。
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 /**
@@ -26,7 +25,7 @@ export interface WebRoute {
     path: string;
     handler: (request: IncomingMessage, response: ServerResponse) => void | Promise<void>;
 }
-/** The subset of the host web-server service this plugin touches. */
+/** 本插件用到的宿主 web-server 服务子集。 */
 export interface WebServerService {
     register(route: WebRoute): () => void;
 }
@@ -36,8 +35,8 @@ export declare const COMMAND_TIMEOUT_MS: number;
  *  不重复走 curl 拉远程 —— 重启宿主后首次打开同样秒开（缓存跨重启存活）。 */
 export declare const CATALOG_CACHE_TTL_MS: number;
 export declare function sendJson(response: ServerResponse, status: number, value: unknown): void;
-/** POST mutations are only accepted from the local web server origin or the desktop host page.
- *  Exported for tests (tests/routes.test.ts) — the origin check is the whole CSRF defence. */
+/** POST 变更只接受来自本地 web server 来源或桌面宿主页面。转出供测试（tests/routes.test.ts）使用 ——
+ *  来源校验就是全部的 CSRF 防御。 */
 export declare function isSameOrigin(request: IncomingMessage): boolean;
 export declare function requireMethod(request: IncomingMessage, response: ServerResponse, method: 'GET' | 'POST'): boolean;
 export declare function requireTrustedPost(request: IncomingMessage, response: ServerResponse): boolean;

package/lib/types/index.d.ts

@@ -3,18 +3,17 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * dsh-plugin host entry: mounts the Plugin Hub HTTP routes once the host
- * web server service is available. The browser bundle (src/client) talks to
- * these same-origin routes to perform real installs from inside the app.
+ * dsh-plugin 宿主入口：宿主 webServer 服务就绪后挂载插件中心的 HTTP 路由。
+ * 浏览器 bundle（src/client）通过这些同源路由在应用内执行真正的安装。
  */
 import { type LoaderHandle } from './services/install/install.ts';
 import { type WebServerService } from './http/routes.ts';
 export declare const name = "dsh-plugin";
 export interface Config {
-    /** DSH profile that owns plugin mutations. Defaults to the booted profile. */
+    /** 拥有插件变更权限的 DSH profile，缺省用启动时的 profile。 */
     profile?: string;
 }
-/** The subset of the cordis host context this plugin touches. */
+/** 本插件用到的 cordis 宿主上下文子集。 */
 interface HostContext {
     webServer: WebServerService;
     /** 运行中 loader：卸载成功后主动移除条目、立即生效（宿主未提供时卸载仍需重启） */
@@ -23,9 +22,9 @@ interface HostContext {
     effect(callback: () => void, label?: string): void;
 }
 /**
- * Mount the Plugin Hub routes after the web server service becomes available.
- * @param ctx - cordis host context.
- * @param config - optional profile override.
+ * webServer 服务就绪后挂载插件中心路由。
+ * @param ctx - cordis 宿主上下文。
+ * @param config - 可选的 profile 覆盖。
  */
 export declare function apply(ctx: HostContext, config?: Config): void;
 export {};

package/lib/types/services/install/install-types.d.ts

@@ -15,27 +15,26 @@ export interface InstallResult {
 }
 export interface InstallTask {
     id: number;
-    /** 操作目标：显式 HTTPS Git URL（安装）或 npm 包名（卸载），冲突/恢复时需要展示给用户 */
+    /** 操作目标：npm 包名（安装、更新、卸载一致），冲突/恢复时需要展示给用户 */
     target: string;
     /** 展示用目标（owner/repo）：npm 安装时 target 是包名，前端恢复用此字段显示仓库名，保持用户无感知 */
     displayTarget?: string;
-    /** 尝试过的安装方式（npm registry 反查 + 实际执行的 CLI 命令，按先后顺序）：
-     *  失败提 Issue 时如实贴给作者，作者据此反推正确的 npm 包名（组织 scope 与 GitHub 用户名不一致时
-     *  仅凭仓库名猜不到，作者看到我们查过/试过的命令就能直接指认）。 */
+    /** 尝试过的安装方式（实际执行过的 CLI 命令，按先后顺序）：
+     *  失败提 Issue 时如实贴给作者，作者据此判断我们真正执行了什么。 */
     attempts: string[];
     /** 全局 npm 安装（官方 `npm install -g <pkgs>`）：非空时任务执行全局 npm 安装，不进任何 profile */
     globalNpm?: string[];
     action: 'add' | 'remove' | 'update';
-    /** 自定义安装入口渠道（客户端三张卡片：NPM 包 / GitHub 源码 / DSH 命令）：
+    /** 自定义安装入口渠道（NPM 包卡片）：
      *  任务输出行与系统日志据此溯源「从哪个入口发起」；目录插件安装无此字段。 */
-    installChannel?: 'npm' | 'git' | 'dsh';
+    installChannel?: 'npm';
     /** 队列语义：pending 排队中 / running 执行中 / done / failed / cancelled（用户取消） */
     status: 'pending' | 'running' | 'done' | 'failed' | 'cancelled';
     timedOut: boolean;
     exitCode: number | null;
     /** 0-100 估算进度：解析 pnpm 的 `Progress: resolved…` 输出，阶段行兜底 */
     progress: number;
-    /** Newest output lines first (consumer shows the tail). */
+    /** 输出行最新在前（消费方展示尾部）。 */
     lines: string[];
     /** 完成后是否仍需宿主重启才生效：仅「热挂载失败 / 非 dsh 插件 / 更新（ESM 缓存取不到新代码）/
      *  无 loader」等刷新解决不了的兜底场景为 true（弹窗给「立即重启」）；其余一律 false。 */
@@ -66,7 +65,7 @@ export interface QueueItem {
         timeoutMs?: number;
         env?: NodeJS.ProcessEnv;
         globalNpm?: string[];
-        installChannel?: 'npm' | 'git' | 'dsh';
+        installChannel?: 'npm';
     };
 }
 /**
@@ -74,20 +73,20 @@ export interface QueueItem {
  * 它自然清空，正好等于「重启后提醒消失」的语义，无需任何重启探测。
  */
 export interface PendingRestart {
-    /** Git 安装目标（与任务一致；卸载时为展示用的 owner/repo） */
+    /** 安装目标（与任务一致；卸载时为展示用的 owner/repo） */
     target: string;
     /** 待重启语义：install 装完等挂载生效 / uninstall 卸完等清理 loader 残留 */
     kind: 'install' | 'uninstall';
     /** 任务完成时刻（epoch ms） */
     at: number;
 }
-/** Grammar of a catalog GitHub repository identity (`owner/repo`). */
+/** 目录 GitHub 仓库身份（`owner/repo`）的语法。 */
 export declare const REPO_RE: RegExp;
-/** Grammar of an npm package name (used for uninstall targets). */
+/** npm 包名的语法（用于卸载目标）。 */
 export declare const PACKAGE_RE: RegExp;
 /** 捕获输出上限：stdout/stderr 各保留尾部 N 字节。 */
 export declare const CAPTURE_LIMIT_BYTES: number;
-/** Max output lines kept per task (newest wins). */
+/** 每个任务保留的最大输出行数（最新优先）。 */
 export declare const MAX_TASK_LINES = 200;
-/** Max tracked tasks; oldest finished tasks are dropped first. */
+/** 最多跟踪的任务数；超出时先丢弃最早结束的任务。 */
 export declare const MAX_TASKS = 50;

package/lib/types/services/install/install.d.ts

@@ -18,5 +18,5 @@ export type { InstallResult, InstallTask, Invocation, PendingRestart, QueueItem
 export type { LoaderHandle } from '../loader.ts';
 export { addPendingRestart, clearPendingRestart, listPendingRestarts } from '../profile/pending-restart.ts';
 export { dumpLoaderEntries, removeLoadedEntry } from '../loader.ts';
-export { addAllowBuildsKey, githubRefOf, githubRepoOf, githubTarget, globalNpmPackagesOf, installTargetOf, parseAllowBuildsKey, readProfileArg, validPackageName, } from '../profile/profile.ts';
+export { addAllowBuildsKey, githubRepoOf, githubTarget, globalNpmPackagesOf, installTargetOf, parseAllowBuildsKey, readProfileArg, validPackageName, } from '../profile/profile.ts';
 export { activeTask, cancelTask, getTask, hasQueuedTarget, hasRunningTask, runPluginMutation, startPluginMutation } from './task-queue.ts';