dsh-m 0.0.3 → 0.1.1

package/lib/core/dsh-cli.js

@@ -0,0 +1,320 @@
+/**
+ * Spawn `dsh plugin`。与 skillhub 同款关键约束：
+ * - 不经 agent 的沙箱 shell（它写不了 profile 目录）；
+ * - 在 dsh web 宿主进程内时，用 `node <自身 entry> plugin ...` 重入自身；
+ * - 目标串白名单校验；超时对进程组发 SIGTERM；只保留末 256KB 输出；
+ * - prepare 被拦 → 写 dangerouslyAllowAllBuilds 重试（明确报告，DESIGN.md §3 基线 4）。
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { installTimeoutMs, WEB_PROFILE, webProfileDir } from './env.js';
+import { createProgressTracker } from './progress.js';
+const TARGET_RE = /^[A-Za-z0-9@:./_#+-]+$/;
+const NDJSON_COMMANDS = new Set(['add', 'remove', 'install']);
+export const BOOT_ID = `${String(process.pid)}-${String(Date.now())}`;
+export const progress = {
+    active: false,
+    target: '',
+    startedAt: 0,
+    lastLine: '',
+    phase: null,
+    done: 0,
+    total: null,
+    currentPackage: null,
+    downloaded: null,
+    size: null,
+    ndjson: false,
+    error: null,
+};
+export function publicInstallStatus() {
+    return {
+        active: progress.active,
+        target: progress.target,
+        seconds: progress.active ? Math.round((Date.now() - progress.startedAt) / 1000) : 0,
+        lastLine: progress.lastLine,
+        phase: progress.phase,
+        done: progress.done,
+        total: progress.total,
+        currentPackage: progress.currentPackage,
+        downloaded: progress.downloaded,
+        size: progress.size,
+        ndjson: progress.ndjson,
+        error: progress.error,
+        boot: BOOT_ID,
+    };
+}
+function beginProgress(target) {
+    progress.active = true;
+    progress.target = target;
+    progress.startedAt = Date.now();
+    progress.lastLine = '';
+    progress.phase = null;
+    progress.done = 0;
+    progress.total = null;
+    progress.currentPackage = null;
+    progress.downloaded = null;
+    progress.size = null;
+    progress.ndjson = false;
+    progress.error = null;
+    return createProgressTracker();
+}
+function makeProgressFeeder(tracker) {
+    let lineBuffer = '';
+    return (chunk) => {
+        lineBuffer += chunk;
+        let nl;
+        while ((nl = lineBuffer.indexOf('\n')) !== -1) {
+            const line = lineBuffer.slice(0, nl);
+            lineBuffer = lineBuffer.slice(nl + 1);
+            const trimmed = line.trim();
+            if (trimmed === '')
+                continue;
+            tracker.feed(trimmed);
+            if (!trimmed.startsWith('{'))
+                progress.lastLine = trimmed.slice(0, 200);
+        }
+    };
+}
+function syncProgress(tracker) {
+    const snap = tracker.snapshot;
+    progress.phase = snap.phase;
+    progress.done = snap.done;
+    progress.total = snap.total;
+    progress.currentPackage = snap.currentPackage;
+    progress.downloaded = snap.downloaded;
+    progress.size = snap.size;
+    progress.ndjson = snap.seen;
+    if (snap.error !== null)
+        progress.error = snap.error;
+}
+export function webProfileName() {
+    return WEB_PROFILE;
+}
+export function isSafePluginTarget(target) {
+    return TARGET_RE.test(target);
+}
+export function nodeExecutable(argv0 = process.argv0, execPath = process.execPath) {
+    if (argv0 !== undefined && argv0 !== '' && isAbsolute(argv0) && existsSync(argv0))
+        return argv0;
+    return execPath;
+}
+/** 宿主进程内时重入自身 entry（skillhub 同款）；否则退回 PATH 上的 dsh。 */
+export function dshArgv(input = {}) {
+    const argv = input.argv ?? process.argv;
+    const execArgv = input.execArgv ?? process.execArgv;
+    const execPath = input.execPath ?? process.execPath;
+    const argv0 = input.argv0 ?? process.argv0;
+    const platform = input.platform ?? process.platform;
+    const node = nodeExecutable(argv0, execPath);
+    const entry = argv[1];
+    if (entry !== undefined && /[\\/](?:bin\.(?:js|ts)|dsh)$/.test(entry)) {
+        const abs = resolve(entry);
+        return { file: node, args: [...execArgv, abs], cwd: dirname(abs), viaShell: false };
+    }
+    return { file: 'dsh', args: [], cwd: undefined, viaShell: platform === 'win32' };
+}
+/** pnpm 9 需要 -w 于 workspace 根；其他主版本在非 workspace 下拒绝 -w。 */
+export function pluginArgsFor(profileDirectory, pluginArgs) {
+    const args = [...pluginArgs];
+    if (args[0] !== 'add' && args[0] !== 'remove')
+        return args;
+    if (!existsSync(join(profileDirectory, 'pnpm-workspace.yaml')))
+        return args;
+    return [args[0], '-w', ...args.slice(1)];
+}
+/** add/remove/install 追加 ndjson reporter，供进度解析（人类回退行由 feeder 记录 lastLine）。 */
+export function preparePluginArgs(profileDirectory, pluginArgs) {
+    const args = pluginArgsFor(profileDirectory, pluginArgs);
+    const command = args[0];
+    if (command !== undefined && NDJSON_COMMANDS.has(command))
+        return [...args, '--reporter=ndjson'];
+    return args;
+}
+export function isPrepareBlocked(text) {
+    return /needs to execute build scripts|allowBuilds|ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED|ERR_PNPM_IGNORED_BUILDS/i.test(text);
+}
+export function withDangerouslyAllowAllBuilds(yaml) {
+    if (/(?:^|\n)dangerouslyAllowAllBuilds:\s*true\s*(?:\n|$)/.test(yaml))
+        return yaml;
+    if (/(?:^|\n)dangerouslyAllowAllBuilds:\s*/m.test(yaml)) {
+        return yaml.replace(/^dangerouslyAllowAllBuilds:\s*.*$/m, 'dangerouslyAllowAllBuilds: true');
+    }
+    if (yaml.trim() === '')
+        return 'dangerouslyAllowAllBuilds: true\n';
+    return `${yaml.replace(/\s*$/u, '\n')}\ndangerouslyAllowAllBuilds: true\n`;
+}
+/** 基线 §17.4：放行构建脚本前必须能被明确报告（返回值带 usedAllowAllBuilds）。 */
+function writeDangerouslyAllowAllBuilds(profileDirectory) {
+    const file = join(profileDirectory, 'pnpm-workspace.yaml');
+    let yaml = '';
+    try {
+        yaml = readFileSync(file, 'utf8');
+    }
+    catch {
+        /* created below */
+    }
+    const next = withDangerouslyAllowAllBuilds(yaml);
+    if (next === yaml)
+        return false;
+    mkdirSync(profileDirectory, { recursive: true });
+    writeFileSync(file, next);
+    return true;
+}
+export function rewritePnpmError(err) {
+    const text = err instanceof Error ? err.message : String(err);
+    if (isPrepareBlocked(text)) {
+        return new Error('该插件需要执行构建脚本（prepare），pnpm 默认拦截。dsh-m 已写入 profile 的 dangerouslyAllowAllBuilds 并重试；若仍失败请检查 web profile 是否可写。');
+    }
+    if (/ERR_PNPM_PUBLIC_HOIST_PATTERN_DIFF/.test(text)) {
+        return new Error('当前 profile 的 node_modules 由不同主版本的 pnpm 生成，安装前需要先重建依赖。');
+    }
+    return err instanceof Error ? err : new Error(text);
+}
+export async function runCommand(command, args, options) {
+    return new Promise((resolvePromise, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env, CI: 'true' },
+            stdio: ['ignore', 'pipe', 'pipe'],
+            shell: options.viaShell === true,
+            detached: options.detached === true && process.platform !== 'win32',
+        });
+        let out = '';
+        let settled = false;
+        const finish = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', onAbort);
+            if (err)
+                reject(err);
+            else
+                resolvePromise(out);
+        };
+        const killChild = () => {
+            if (process.platform !== 'win32' && child.pid !== undefined) {
+                try {
+                    process.kill(-child.pid, 'SIGTERM');
+                    return;
+                }
+                catch {
+                    /* fall through */
+                }
+            }
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                /* already gone */
+            }
+        };
+        const timer = setTimeout(() => {
+            killChild();
+            finish(new Error(`命令超时 ${options.timeoutMs}ms`));
+        }, options.timeoutMs);
+        const onAbort = () => {
+            killChild();
+            finish(new Error('命令已取消'));
+        };
+        options.signal?.addEventListener('abort', onAbort, { once: true });
+        child.stdout?.on('data', (chunk) => {
+            const text = chunk.toString();
+            out = (out + text).slice(-256 * 1024);
+            options.onChunk?.(text);
+        });
+        child.stderr?.on('data', (chunk) => {
+            const text = chunk.toString();
+            out = (out + text).slice(-256 * 1024);
+            options.onChunk?.(text);
+        });
+        child.on('error', (err) => finish(err));
+        child.on('close', (code) => {
+            if (code === 0)
+                finish();
+            else
+                finish(new Error(`命令失败 (exit ${code}): ${out.trim().slice(-800) || 'no output'}`));
+        });
+    });
+}
+export async function runDshPlugin(profile, pluginArgs, deps = {}) {
+    if (profile !== WEB_PROFILE)
+        throw new Error('仅支持 web profile');
+    const target = pluginArgs[pluginArgs.length - 1] ?? '';
+    if (!isSafePluginTarget(target))
+        throw new Error(`拒绝不安全的安装目标: ${target}`);
+    const argv = (deps.dshArgv ?? dshArgv)();
+    const prepared = preparePluginArgs(deps.profileDir ?? webProfileDir(), pluginArgs);
+    const tracker = beginProgress(target);
+    const feed = makeProgressFeeder(tracker);
+    const run = deps.runCommand ?? runCommand;
+    try {
+        return await run(argv.file, [...argv.args, 'plugin', '--profile', profile, ...prepared], {
+            cwd: argv.cwd,
+            timeoutMs: deps.timeoutMs ?? installTimeoutMs(),
+            env: { CI: 'true' },
+            viaShell: argv.viaShell,
+            detached: process.platform !== 'win32',
+            onChunk: (text) => {
+                feed(text);
+                syncProgress(tracker);
+            },
+        });
+    }
+    catch (err) {
+        // 失败/超时时也把原因写入状态端点，轮询侧能看到错误终态
+        const text = err instanceof Error ? err.message : String(err);
+        if (progress.error === null)
+            progress.error = text.slice(0, 800);
+        throw err;
+    }
+    finally {
+        progress.active = false;
+    }
+}
+/**
+ * 安装。返回 usedAllowAllBuilds 供 UI 明确报告「该插件执行了构建脚本」。
+ * source 形如：`pkg@1.2.3`（npm 精确锁定）或 `github:owner/repo#sha`（锁 SHA）。
+ */
+export async function addDshPlugin(source, deps = {}) {
+    const run = deps.runDshPlugin ?? runDshPlugin;
+    const allowAllBuilds = deps.allowAllBuilds ?? writeDangerouslyAllowAllBuilds;
+    const retryAfterPrepare = async () => {
+        const changed = allowAllBuilds(deps.profileDir ?? webProfileDir());
+        try {
+            return { output: await run(WEB_PROFILE, ['add', source]), usedAllowAllBuilds: true };
+        }
+        catch (retryErr) {
+            throw rewritePnpmError(retryErr);
+        }
+    };
+    try {
+        return { output: await run(WEB_PROFILE, ['add', source]), usedAllowAllBuilds: false };
+    }
+    catch (err) {
+        const text = err instanceof Error ? err.message : String(err);
+        if (text.includes('ERR_PNPM_PUBLIC_HOIST_PATTERN_DIFF')) {
+            await run(WEB_PROFILE, ['install', '--no-frozen-lockfile']);
+            try {
+                return { output: await run(WEB_PROFILE, ['add', source]), usedAllowAllBuilds: false };
+            }
+            catch (retryErr) {
+                if (!isPrepareBlocked(retryErr instanceof Error ? retryErr.message : String(retryErr))) {
+                    throw rewritePnpmError(retryErr);
+                }
+                return retryAfterPrepare();
+            }
+        }
+        if (!isPrepareBlocked(text))
+            throw rewritePnpmError(err);
+        return retryAfterPrepare();
+    }
+}
+/** 卸载（转发 pnpm remove；调用方须先做 live-disable）。 */
+export async function removeDshPlugin(pkg, deps = {}) {
+    if (!isSafePluginTarget(pkg))
+        throw new Error(`无效插件包名: ${pkg}`);
+    const run = deps.runDshPlugin ?? runDshPlugin;
+    return run(WEB_PROFILE, ['remove', pkg]);
+}

package/lib/core/env.js

@@ -0,0 +1,18 @@
+/** 路径与环境约定（DESIGN.md §11：profile 是唯一事实源） */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const WEB_PROFILE = 'web';
+export function dshHome() {
+    return process.env.DSH_HOME || join(homedir(), '.dsh');
+}
+export function webProfileDir() {
+    return join(dshHome(), 'profiles', WEB_PROFILE);
+}
+/** registry 缓存目录（可被 DSHM_CACHE_DIR 覆盖，便于测试） */
+export function cacheDir() {
+    return process.env.DSHM_CACHE_DIR || join(dshHome(), 'dshm', 'cache');
+}
+/** 安装类操作的超时（毫秒） */
+export function installTimeoutMs() {
+    return Number(process.env.DSHM_INSTALL_TIMEOUT_MS) || 15 * 60 * 1000;
+}

package/lib/core/httpx.js

@@ -0,0 +1,94 @@
+/**
+ * 安全基线 §17.1：仅 HTTPS（loopback http 例外）+ 响应大小上限 + 超时。
+ * skillhub 的缺口（无统一体积上限）在这里补齐。
+ */
+export class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+const MAX_DEFAULT = 2 * 1024 * 1024; // 2MB：registry/npm metadata 足够
+export function assertSafeUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new HttpError(400, `无效 URL: ${raw}`);
+    }
+    if (url.protocol === 'https:')
+        return url;
+    if (url.protocol === 'http:' && ['127.0.0.1', 'localhost', '::1'].includes(url.hostname)) {
+        return url; // 本地 registry 覆盖调试用（DESIGN.md §2.1）
+    }
+    throw new HttpError(400, `仅允许 HTTPS: ${raw}`);
+}
+async function readCapped(res, maxBytes) {
+    const declared = Number(res.headers.get('content-length') || 0);
+    if (declared > maxBytes)
+        throw new HttpError(502, `响应过大: ${declared} > ${maxBytes}`);
+    const reader = res.body?.getReader();
+    if (!reader)
+        return Buffer.alloc(0);
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel().catch(() => undefined);
+            throw new HttpError(502, `响应超过上限 ${maxBytes} 字节`);
+        }
+        chunks.push(Buffer.from(value));
+    }
+    return Buffer.concat(chunks);
+}
+export async function fetchJsonLimited(url, opts = {}) {
+    assertSafeUrl(url);
+    const res = await fetch(url, {
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 20_000),
+        headers: { accept: 'application/json', 'user-agent': 'dsh-m (personal marketplace)', ...opts.headers },
+        redirect: 'follow',
+    });
+    if (!res.ok)
+        throw new HttpError(res.status, `HTTP ${res.status}: ${url}`);
+    const buf = await readCapped(res, opts.maxBytes ?? MAX_DEFAULT);
+    try {
+        return JSON.parse(buf.toString('utf8'));
+    }
+    catch (err) {
+        throw new HttpError(502, `响应不是合法 JSON: ${url}`);
+    }
+}
+export async function fetchTextLimited(url, opts = {}) {
+    assertSafeUrl(url);
+    const res = await fetch(url, {
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 20_000),
+        headers: { 'user-agent': 'dsh-m (personal marketplace)', ...opts.headers },
+        redirect: 'follow',
+    });
+    if (!res.ok)
+        throw new HttpError(res.status, `HTTP ${res.status}: ${url}`);
+    const buf = await readCapped(res, opts.maxBytes ?? MAX_DEFAULT);
+    return buf.toString('utf8');
+}
+/** 可达性探测（icon/homepage 校验用）：2xx 即可达。 */
+export async function isReachable(url, timeoutMs = 8000) {
+    try {
+        assertSafeUrl(url);
+        const res = await fetch(url, {
+            method: 'HEAD',
+            signal: AbortSignal.timeout(timeoutMs),
+            headers: { 'user-agent': 'dsh-m (personal marketplace)' },
+            redirect: 'follow',
+        });
+        return res.ok || res.status === 405; // 有的站点拒绝 HEAD，视为可达
+    }
+    catch {
+        return false;
+    }
+}

package/lib/core/installed.js

@@ -0,0 +1,186 @@
+/**
+ * 已装插件识别（DESIGN.md §3）：profile 的 package.json 是唯一事实源，
+ * 不引入额外状态文件。移植自 skillhub installed-plugins.ts（去 README 暂缓）。
+ */
+import { open, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { isSafePluginTarget, removeDshPlugin } from './dsh-cli.js';
+import { webProfileDir } from './env.js';
+const PKG_NAME_RE = /^(@[A-Za-z0-9-*~][A-Za-z0-9-*._~]*\/)?[A-Za-z0-9-._~]+$/;
+export function isSafePkgName(raw) {
+    const name = String(raw || '').trim();
+    if (!name || name.length > 214)
+        return false;
+    if (!PKG_NAME_RE.test(name))
+        return false;
+    return !name.split('/').some((part) => part === '' || part === '.' || part.startsWith('.') || part.startsWith('_') || part.includes('..'));
+}
+export function parseSpecSource(spec) {
+    const raw = String(spec || '').trim();
+    if (raw.startsWith('link:'))
+        return 'link';
+    if (raw.startsWith('file:'))
+        return 'file';
+    if (raw.startsWith('github:') || /^https:\/\/github\.com\//i.test(raw))
+        return 'github';
+    if (raw)
+        return 'npm';
+    return 'unknown';
+}
+/**
+ * 解析依赖的包目录：
+ * - `link:` 是活的开发目录符号链接，解析真实目标（已装页展示本地路径有价值）；
+ * - 其余（npm / github / file-tarball / file-dir）pnpm 都会把内容物化到 node_modules/<pkg>，
+ *   统一从那里读。skillhub 同款语义——file: 特判回 tarball 路径是错的（读不到 package.json）。
+ */
+export function resolvePluginDir(profileDir, pkg, spec) {
+    if (!isSafePkgName(pkg))
+        return null;
+    const source = parseSpecSource(spec);
+    if (source === 'link') {
+        const target = String(spec).slice('link:'.length).trim();
+        if (!target.startsWith('/') || target.includes('\0'))
+            return null;
+        return resolve(target);
+    }
+    return join(resolve(profileDir), 'node_modules', pkg);
+}
+/** 从 repository 字段（字符串或 {url}，git+/ssh/https 形态）提取 github owner/repo。 */
+export function githubRepoFromRepository(raw) {
+    let url = '';
+    if (typeof raw === 'string')
+        url = raw;
+    else if (raw && typeof raw === 'object') {
+        const u = raw.url;
+        if (typeof u === 'string')
+            url = u;
+    }
+    const m = /github\.com[/:]([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+?)(?:\.git)?$/i.exec(url.trim());
+    return m ? `${m[1]}/${m[2]}` : null;
+}
+export async function readPkgJson(dir) {
+    try {
+        const raw = JSON.parse(await readFile(join(dir, 'package.json'), 'utf8'));
+        return raw && typeof raw === 'object' ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function readProfileDeps(profileDir) {
+    try {
+        const raw = JSON.parse(await readFile(join(profileDir, 'package.json'), 'utf8'));
+        if (!raw || typeof raw !== 'object' || !raw.dependencies || typeof raw.dependencies !== 'object')
+            return {};
+        const out = {};
+        for (const [name, spec] of Object.entries(raw.dependencies)) {
+            if (typeof spec === 'string' && spec !== '')
+                out[name] = spec;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+function sanitizePkgJson(raw, fallbackName) {
+    return {
+        name: typeof raw.name === 'string' && raw.name.trim() ? raw.name.trim().slice(0, 200) : fallbackName,
+        version: typeof raw.version === 'string' ? raw.version.trim().slice(0, 64) : '',
+        description: typeof raw.description === 'string' ? raw.description.trim().slice(0, 500) : '',
+        homepage: typeof raw.homepage === 'string' && /^https?:\/\//i.test(raw.homepage) ? raw.homepage.slice(0, 300) : '',
+        path: '',
+        githubRepo: githubRepoFromRepository(raw.repository),
+    };
+}
+/** 枚举 web profile 已安装插件（只读）。 */
+export async function listInstalledPlugins(profileDir = webProfileDir()) {
+    const root = resolve(profileDir);
+    const deps = await readProfileDeps(root);
+    const items = [];
+    let others = 0;
+    for (const pkg of Object.keys(deps).sort()) {
+        const spec = deps[pkg];
+        const dir = resolvePluginDir(root, pkg, spec);
+        const raw = dir ? await readPkgJson(dir) : null;
+        if (!raw || !('dsh' in raw)) {
+            others += 1;
+            continue;
+        }
+        const info = sanitizePkgJson(raw, pkg);
+        items.push({
+            pkg,
+            name: info.name,
+            version: info.version,
+            description: info.description,
+            homepage: info.homepage,
+            spec,
+            source: parseSpecSource(spec),
+            dsh: true,
+            path: dir,
+            githubRepo: githubRepoFromRepository(raw.repository),
+        });
+    }
+    return { items, others, profileDir: root };
+}
+/** 从 web profile 卸载已安装的 dsh 插件。pkg 必须来自 profile 依赖（先 live-disable，见 market.ts）。 */
+export async function removeInstalledPlugin(pkg, profileDir = webProfileDir(), deps = {}) {
+    const key = String(pkg || '').trim();
+    if (!isSafePkgName(key) || !isSafePluginTarget(key))
+        throw new Error(`无效插件包名: ${pkg}`);
+    const root = resolve(profileDir);
+    const listed = await readProfileDeps(root);
+    if (!(key in listed))
+        throw new Error(`web profile 未安装该插件: ${key}`);
+    const dir = resolvePluginDir(root, key, listed[key]);
+    const raw = dir ? await readPkgJson(dir) : null;
+    if (!raw || !('dsh' in raw))
+        throw new Error(`不是 dsh 插件: ${key}`);
+    await removeDshPlugin(key, deps);
+    return { pkg: key };
+}
+// ---------- README 预览（借鉴 skillhub，64KB 截断） ----------
+const README_MAX_BYTES = 64 * 1024;
+const README_FILES = ['README.md', 'README.markdown', 'README'];
+/** 限量读取文本文件：只读前 limit 字节，超限标记 truncated。 */
+async function readTextLimited(path, limit) {
+    let fh;
+    try {
+        fh = await open(path, 'r');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const buf = Buffer.alloc(limit + 1);
+        const { bytesRead } = await fh.read(buf, 0, buf.length, 0);
+        return {
+            text: buf.subarray(0, Math.min(bytesRead, limit)).toString('utf8'),
+            truncated: bytesRead > limit,
+        };
+    }
+    finally {
+        await fh.close().catch(() => undefined);
+    }
+}
+/** 读取单个已安装插件的 README（UTF-8，≤64KB，超限截断）。pkg 必须来自 profile 依赖。 */
+export async function readInstalledPluginReadme(pkg, profileDir = webProfileDir()) {
+    const key = String(pkg || '').trim();
+    if (!isSafePkgName(key))
+        throw new Error(`无效插件包名: ${pkg}`);
+    const root = resolve(profileDir);
+    const deps = await readProfileDeps(root);
+    if (!(key in deps))
+        throw new Error(`web profile 未安装该插件: ${key}`);
+    const dir = resolvePluginDir(root, key, deps[key]);
+    if (!dir)
+        throw new Error(`无法解析插件目录: ${key}`);
+    const raw = await readPkgJson(dir);
+    const name = raw && typeof raw.name === 'string' && raw.name.trim() ? raw.name.trim() : key;
+    for (const file of README_FILES) {
+        const text = await readTextLimited(join(dir, file), README_MAX_BYTES);
+        if (text)
+            return { pkg: key, name, readme: text.text, truncated: text.truncated };
+    }
+    return { pkg: key, name, readme: '', truncated: false };
+}

package/lib/core/live-plugin.js

@@ -0,0 +1,42 @@
+/**
+ * 卸载前先让 loader 里的 live fiber 下线，否则 client-modules 仍列出该包，
+ * 浏览器请求 /plugins/<name>/client.js 会 404。移植自 skillhub live-plugin.ts。
+ */
+let boundHost;
+export function bindLoaderHost(host) {
+    boundHost = host;
+}
+export function loaderHost() {
+    return boundHost;
+}
+export async function setLivePluginDisabled(pkg, disabled, host = boundHost) {
+    const name = String(pkg || '').trim();
+    const entries = host?.loader?.entries;
+    if (!name || typeof entries !== 'function')
+        return false;
+    let found = false;
+    for (const entry of entries.call(host.loader)) {
+        if (!entry || entry.options?.name !== name)
+            continue;
+        if (typeof entry.update !== 'function')
+            continue;
+        found = (await flipEntry(entry, disabled)) || found;
+    }
+    return found;
+}
+async function flipEntry(entry, disabled) {
+    const flag = disabled ? true : null;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            await entry.update({ disabled: flag }, false, true);
+        }
+        catch {
+            return false;
+        }
+        const live = entry.fiber !== undefined;
+        if (live !== disabled)
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, 200));
+    }
+    return true;
+}