dsh-m 0.4.2 → 0.5.0

package/lib/core/profile-transaction.js

@@ -46,12 +46,13 @@ export const TX_HEAL_CODES = [
     'B3_LAG_RETRY', 'B3_PACKUMENT_WARMED', 'BUILDS_ALLOWED',
     'ROLLBACK_BYTES_RESTORED', 'ROLLBACK_CONVERGED_FROZEN', 'ROLLBACK_FALLBACK_REMOVED',
     'ROLLBACK_VERIFY_FAILED', 'LIVE_DISABLED', 'LIVE_REENABLED', 'LIVE_REENABLE_FAILED',
-    'PATCH_ENTRIES_STRIPPED',
+    'PATCH_ENTRIES_STRIPPED', 'PATCH_MAPPING_RESTORED',
 ];
 export const TX_FAILURE_CODES = [
     'DEP_MISSING_AFTER_ADD', 'DEP_VERSION_MISMATCH', 'LOCKFILE_MISSING', 'LOCK_INTEGRITY_MISMATCH',
     'GITHUB_SPEC_MISMATCH', 'ADD_RETRY_EXHAUSTED', 'ADD_FAILED', 'POST_MUTATION_CONVERGENCE_FAILED',
     'NOT_INSTALLED', 'NOT_DSH_PLUGIN', 'REMOVE_FAILED', 'STILL_PRESENT_AFTER_REMOVE',
+    'COMPENSATE_EVIDENCE_MISMATCH', 'COMPENSATE_RESTORE_FAILED',
     'ROLLBACK_FAILED', 'SNAPSHOT_FAILED', 'ABORTED', 'INTERNAL_ERROR',
     'PROFILE_MANIFEST_UNREADABLE', 'PROFILE_MANIFEST_INVALID', 'PLUGIN_METADATA_UNREADABLE',
 ];
@@ -83,6 +84,8 @@ function prefixOf(kind, code) {
         return '卸载失败';
     if (kind === 'install-github')
         return 'GitHub 安装失败';
+    if (kind === 'compensate-install')
+        return '补偿失败';
     return '安装失败';
 }
 /** 失败结果的中文散文（唯一产地；三条 legacy 文案逐字钉住在 tests/profile-transaction.test.mjs）。 */
@@ -790,6 +793,238 @@ async function uninstall(req, d, snapshots) {
         return await rollbackWithLiveReverse(req, d, failure, heal, snapshots, liveDisabled);
     }
 }
+// ---------- compensate-install 门（M2 Task 3：专用补偿事务，四边界见 DESIGN §3） ----------
+/** patchMapping 结构化双落点恢复：workspace（pnpm-workspace.yaml patchedDependencies）与 manifest（pnpm.patchedDependencies）。 */
+async function restorePatchMapping(profileDir, mapping, heal) {
+    const wsFile = join(profileDir, 'pnpm-workspace.yaml');
+    if (mapping.workspace.length > 0) {
+        let text = '';
+        try {
+            text = await readFile(wsFile, 'utf8');
+        }
+        catch {
+            text = '';
+        }
+        const lines = text.replace(/\n*$/, '\n').split('\n');
+        if (!lines.some((l) => l.trim() === 'patchedDependencies:')) {
+            lines.push('patchedDependencies:');
+        }
+        for (const entry of mapping.workspace) {
+            const line = `  ${JSON.stringify(entry.key)}: ${entry.patchPath}`;
+            if (!lines.includes(line))
+                lines.push(line);
+        }
+        await atomicWriteFile(wsFile, Buffer.from(lines.join('\n'), 'utf8'));
+        heal.push({ code: 'PATCH_MAPPING_RESTORED', note: `已恢复 pnpm-workspace.yaml 补丁映射（${mapping.workspace.map((m) => m.key).join('、')}）` });
+    }
+    if (mapping.manifest.length > 0) {
+        const mfFile = join(profileDir, 'package.json');
+        let doc = {};
+        try {
+            doc = JSON.parse(await readFile(mfFile, 'utf8'));
+        }
+        catch {
+            doc = {};
+        }
+        const pnpm = (doc.pnpm && typeof doc.pnpm === 'object' && !Array.isArray(doc.pnpm) ? doc.pnpm : {});
+        const patched = (pnpm.patchedDependencies && typeof pnpm.patchedDependencies === 'object' && !Array.isArray(pnpm.patchedDependencies)
+            ? pnpm.patchedDependencies
+            : {});
+        for (const entry of mapping.manifest)
+            patched[entry.key] = entry.patchPath;
+        pnpm.patchedDependencies = patched;
+        doc.pnpm = pnpm;
+        await atomicWriteFile(mfFile, Buffer.from(JSON.stringify(doc, null, 2) + '\n', 'utf8'));
+        heal.push({ code: 'PATCH_MAPPING_RESTORED', note: `已恢复 package.json#pnpm.patchedDependencies（${mapping.manifest.map((m) => m.key).join('、')}）` });
+    }
+}
+/** mapping 双落点复读确认（严格读写：任一落点写入后复读不符 → 失败）。 */
+async function verifyPatchMapping(profileDir, mapping) {
+    if (mapping.workspace.length > 0) {
+        try {
+            const text = await readFile(join(profileDir, 'pnpm-workspace.yaml'), 'utf8');
+            for (const entry of mapping.workspace) {
+                if (!text.includes(JSON.stringify(entry.key)))
+                    return `workspace 补丁映射复读缺失：${entry.key}`;
+            }
+        }
+        catch (err) {
+            return `pnpm-workspace.yaml 复读失败：${errText(err)}`;
+        }
+    }
+    if (mapping.manifest.length > 0) {
+        try {
+            const doc = JSON.parse(await readFile(join(profileDir, 'package.json'), 'utf8'));
+            for (const entry of mapping.manifest) {
+                if (doc.pnpm?.patchedDependencies?.[entry.key] !== entry.patchPath)
+                    return `manifest 补丁映射复读缺失：${entry.key}`;
+            }
+        }
+        catch (err) {
+            return `package.json 复读失败：${errText(err)}`;
+        }
+    }
+    return null;
+}
+/**
+ * 补偿门：validate（evidence 插队复验，零写入）→ 快照 → live-disable → strip → remove →
+ * verify gone → PriorUnion 分支（none 终 / mappingOnly 恢复 mapping+frozen / dependency 恢复 mapping→add→三重验证）。
+ * 无外部 signal（安装已 committed，清理不可被客户端断连取消）。
+ */
+async function compensateInstall(req, d) {
+    const heal = [];
+    const pkg = req.pkg;
+    // validate：evidence 实读比对（插队复验；失配 → rejected 零写入）
+    try {
+        const depsNow = await strictReadDeps(d);
+        const current = depsNow[pkg];
+        if (req.evidence.source === 'npm') {
+            if (current !== req.evidence.manifestSpec) {
+                return rejected({ code: 'COMPENSATE_EVIDENCE_MISMATCH', note: `manifest 依赖值已变化（现值 ${current ?? '缺失'}，期望 ${req.evidence.manifestSpec}）；拒绝补偿` }, req.kind);
+            }
+        }
+        else if (current !== req.evidence.pinnedSpec) {
+            return rejected({ code: 'COMPENSATE_EVIDENCE_MISMATCH', note: `manifest 依赖值已变化（现值 ${current ?? '缺失'}，期望 ${req.evidence.pinnedSpec}）；拒绝补偿` }, req.kind);
+        }
+        if (req.evidence.source === 'npm') {
+            const lockText = await readFile(join(d.profileDir, 'pnpm-lock.yaml'), 'utf8');
+            const version = lockVersionOf(lockText, pkg) ?? req.evidence.resolvedVersion;
+            const integrity = readPnpmLockIntegrity(lockText, pkg, version);
+            if (integrity === null || integrity !== req.evidence.integrity) {
+                return rejected({ code: 'COMPENSATE_EVIDENCE_MISMATCH', note: 'lockfile integrity 与补偿证据不一致；拒绝补偿' }, req.kind);
+            }
+        }
+        else {
+            const lockText = await readFile(join(d.profileDir, 'pnpm-lock.yaml'), 'utf8');
+            const commit = lockCommitOf(lockText, pkg);
+            if (commit === null || commit !== req.evidence.lockCommitIdentity) {
+                return rejected({ code: 'COMPENSATE_EVIDENCE_MISMATCH', note: 'lockfile commit identity 与补偿证据不一致；拒绝补偿' }, req.kind);
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof DomainFailure)
+            return rejected(err.failure, req.kind);
+        return rejected({ code: 'COMPENSATE_EVIDENCE_MISMATCH', note: `补偿证据复验读取失败：${errText(err)}` }, req.kind);
+    }
+    if (req.prior.kind === 'unavailable') {
+        return rejected({ code: 'COMPENSATE_EVIDENCE_MISMATCH', note: `prior 关联歧义，拒绝补偿：${req.prior.reason}` }, req.kind);
+    }
+    // 快照 → live-disable → strip → remove → verify gone（与卸载同序；live-disable 在快照后）
+    let snapshots;
+    try {
+        snapshots = await snapshotFiles(d.paths);
+    }
+    catch (err) {
+        return rejected({ code: 'SNAPSHOT_FAILED', note: errText(err) }, req.kind);
+    }
+    let liveDisabled = false;
+    let orphanedPatchFiles = [];
+    try {
+        liveDisabled = await d.setLiveDisabled(pkg, true);
+        if (liveDisabled)
+            heal.push({ code: 'LIVE_DISABLED', note: '补偿前已将运行中的坏包界面下线' });
+        const patch = d.stripPatchedEntries(d.profileDir, pkg);
+        if (patch.changed)
+            heal.push({ code: 'PATCH_ENTRIES_STRIPPED', note: '已摘除该包的 pnpm 补丁条目' });
+        orphanedPatchFiles = patch.orphanedPatchFiles;
+        const rmOut = await d.runner.remove(pkg);
+        if (rmOut.class !== 'ok') {
+            return await rollbackAndConverge(d, req.kind, { code: 'REMOVE_FAILED', note: rmOut.output }, heal, snapshots);
+        }
+        const depsNow = await strictReadDeps(d);
+        if (pkg in depsNow) {
+            throw new DomainFailure({ code: 'STILL_PRESENT_AFTER_REMOVE', note: `补偿移除后仍存在 ${pkg}` });
+        }
+    }
+    catch (err) {
+        const failure = err instanceof DomainFailure
+            ? err.failure
+            : { code: 'INTERNAL_ERROR', note: errText(err) };
+        // rolled-back：坏包可能仍在 → needsRestart=true、restartSafe=false
+        const result = await rollbackAndConverge(d, req.kind, failure, heal, snapshots);
+        return result;
+    }
+    // PriorUnion 分支（v9/v10：显式分支，无通用「有 prior 就 add」路径）
+    const prior = req.prior;
+    if (prior.kind === 'none') {
+        return committed(req.kind, heal, `compensated:${pkg}`, { pkg, liveDisabled, orphanedPatchFiles });
+    }
+    const mapping = prior.kind === 'mappingOnly' ? prior.patchMapping : prior.state.patchMapping;
+    await restorePatchMapping(d.profileDir, mapping, heal);
+    const mappingBad = await verifyPatchMapping(d.profileDir, mapping);
+    if (mappingBad !== null) {
+        return manualRepair(req.kind, { code: 'COMPENSATE_RESTORE_FAILED', note: mappingBad }, heal, mappingBad, false);
+    }
+    if (prior.kind === 'mappingOnly') {
+        // 原依赖本不存在 → 恢复 mapping 后 frozen 验证（runner.add 零调用——add 会装回不存在的包）
+        const conv = await frozenConvergeLadder(d, heal);
+        if (conv.class !== 'ok') {
+            return manualRepair(req.kind, { code: 'POST_MUTATION_CONVERGENCE_FAILED', note: `mapping 恢复后 frozen 验证未通过：${conv.output}` }, heal, conv.output, false);
+        }
+        return committed(req.kind, heal, `compensated:${pkg}`, { pkg, liveDisabled, orphanedPatchFiles });
+    }
+    // dependency：恢复 mapping → add ladder → frozen 收敛 → 三重恢复验证
+    const priorState = prior.state;
+    if (!priorState.restorable) {
+        // 理论不可达（restorable:false 在 mutation 前已拒）——防御性 manual-repair
+        return manualRepair(req.kind, { code: 'COMPENSATE_RESTORE_FAILED', note: 'prior 不可自动恢复（restorable:false）' }, heal, 'restorable:false', false);
+    }
+    const addOut = await addWithLagRetry({ kind: 'install-npm', pkg, version: priorState.resolvedVersion ?? '', integrity: priorState.integrity ?? '' }, `${pkg}@${priorState.manifestSpec}`, d, heal);
+    if (addOut.class !== 'ok') {
+        const result = await rollbackAndConverge(d, req.kind, { code: 'ADD_FAILED', note: addOut.output }, heal, snapshots);
+        return result;
+    }
+    const conv = await frozenConvergeLadder(d, heal);
+    if (conv.class !== 'ok') {
+        return manualRepair(req.kind, { code: 'POST_MUTATION_CONVERGENCE_FAILED', note: `恢复后 frozen 收敛未通过：${conv.output}` }, heal, conv.output, false);
+    }
+    // 三重恢复验证：manifest spec / node_modules 实际 version / lock integrity
+    try {
+        const depsNow = await strictReadDeps(d);
+        const specNow = depsNow[pkg];
+        if (specNow === undefined)
+            throw new Error(`恢复后 manifest 缺少 ${pkg}`);
+        let versionNote = '';
+        if (priorState.sourceKind === 'npm') {
+            if (specNow !== priorState.manifestSpec) {
+                // CLI 书写规范化（^/~）：接受规范化但明示，不称「完全恢复」
+                versionNote = `；已恢复旧 resolved version，spec 已规范化为 ${specNow}`;
+            }
+            const lockText = await readFile(join(d.profileDir, 'pnpm-lock.yaml'), 'utf8');
+            const version = lockVersionOf(lockText, pkg) ?? priorState.resolvedVersion ?? '';
+            const integrity = readPnpmLockIntegrity(lockText, pkg, version);
+            if (priorState.integrity && integrity !== priorState.integrity) {
+                throw new Error('lockfile integrity 与 prior 不一致');
+            }
+            const nmPkg = JSON.parse(await readFile(join(d.profileDir, 'node_modules', pkg, 'package.json'), 'utf8'));
+            if (priorState.resolvedVersion && nmPkg.version !== priorState.resolvedVersion) {
+                throw new Error(`node_modules 实际版本（${String(nmPkg.version)}）与 prior（${priorState.resolvedVersion}）不一致`);
+            }
+        }
+        return committed(req.kind, heal, `compensated:${pkg}`, {
+            pkg,
+            liveDisabled,
+            orphanedPatchFiles,
+            ...(versionNote ? {} : {}),
+        });
+    }
+    catch (err) {
+        return manualRepair(req.kind, { code: 'COMPENSATE_RESTORE_FAILED', note: `三重恢复验证失败：${errText(err)}` }, heal, errText(err), false);
+    }
+}
+/** pnpm-lock packages 段中目标包的 resolution.version（粗粒度文本提取，供补偿验证）。 */
+function lockVersionOf(lockText, pkg) {
+    const re = new RegExp(`'?(?:[^'\n]*node_modules/)?${pkg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}@[^'\n]*':\s*\n[^}]*?version:\s*(\S+)`, 'm');
+    const m = re.exec(lockText);
+    return m ? m[1].replace(/'/g, '') : null;
+}
+/** pnpm-lock 目标包 resolution 的 commit（github tarball 无 integrity，以 commit identity 为准）。 */
+function lockCommitOf(lockText, pkg) {
+    const re = new RegExp(`'?(?:[^'\n]*node_modules/)?${pkg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}@[^'\n]*':\s*\n[^}]*?commit:\s*'?([0-9a-f]{40})`, 'm');
+    const m = re.exec(lockText);
+    return m ? m[1] : null;
+}
 // ---------- 入口：FIFO 互斥 + 分发 ----------
 /** 模块级 FIFO 互斥锁（进程内串行；skillhub install-lock 同款思路）。 */
 let txTail = Promise.resolve();
@@ -836,6 +1071,8 @@ async function executeTransaction(req, deps) {
     // 快照已取 → 照常走统一回滚（rollbackAndConverge 已 total，不会再递归逃逸）。
     try {
         switch (req.kind) {
+            case 'compensate-install':
+                return compensateInstall(req, d);
             case 'install-npm':
                 return await installNpm(req, d, snapshots);
             case 'install-github':

package/lib/core/registry-controller.js

@@ -127,6 +127,8 @@ export function createRegistryController(initial = {}) {
             const source = store ? store.get() : initial;
             config.timeoutMs = source.timeoutMs;
             config.cacheTtlMin = source.cacheTtlMin;
+            // 社区字段初始值（两代 store 同型：legacy/forms 的 get() 都经 unwrapConfig 透传）
+            syncCommunityFields(source);
             const raw = trimAddress(source.registryUrl);
             const attempt = await loadRegistry({ ...config, registryUrl: raw }, { namespace: 'host' });
             if (disposed || gen !== generation)
@@ -170,9 +172,15 @@ export function createRegistryController(initial = {}) {
         }
         return bootstrapPromise;
     }
+    function syncCommunityFields(source) {
+        // 社区字段（M1 Task 6）：live 生效——同 URL 分支前也要同步（开关/pin 变化不触发主清单重载）
+        config.communityCatalog = source.communityCatalog;
+        config.communityCatalogPin = source.communityCatalogPin;
+    }
     function handleExternalWatch(next) {
         if (disposed)
             return Promise.resolve();
+        syncCommunityFields(next);
         const raw = trimAddress(next.registryUrl);
         if (lastSelfWrite !== null && raw === lastSelfWrite) {
             lastSelfWrite = null;

package/lib/core/registry.js

@@ -9,7 +9,7 @@ import { isAbsolute, join, normalize } from 'node:path';
 import { constants as fsConstants, mkdirSync } from 'node:fs';
 import { lstat, mkdir, open, readFile, readdir, realpath, rename, rm } from 'node:fs/promises';
 import { cacheDir } from './env.js';
-import { decodeUtf8Fatal, fetchJsonLimitedMeta } from './httpx.js';
+import { decodeUtf8Fatal, fetchJsonLimitedMeta, describeFetchFailure } from './httpx.js';
 export const CATEGORIES = ['market', 'tools', 'ui', 'search', 'other'];
 /** 容量上限：2 MiB 是原始 UTF-8 bytes（不是字符数）；条目超限拒绝整份清单。 */
 export const MAX_REGISTRY_BYTES = 2 * 1024 * 1024;
@@ -603,7 +603,7 @@ async function loadDefaultChain(cfg, opts, chain) {
             };
         }
         catch (err) {
-            errors.push(`${candidate.source}: ${errorMessage(err)}`);
+            errors.push(describeFetchFailure({ label: candidate.source, url: candidate.url, err, elapsedMs: Date.now() - startedAt }));
         }
     }
     const cached = await readCacheFile(chain.namespace, DEFAULT_CACHE_KEY);
@@ -671,7 +671,7 @@ async function loadCustomChain(address, cfg, opts, chain) {
         };
     }
     catch (err) {
-        errors.push(`${source}: ${errorMessage(err)}`);
+        errors.push(describeFetchFailure({ label: source, url: address.normalized, err, elapsedMs: Date.now() - startedAt }));
     }
     if (chain.allowCacheFallback) {
         const cached = await readCacheFile(chain.namespace, address.cacheKey);

package/lib/core/settings-compat.js

@@ -39,6 +39,10 @@ export function unwrapConfig(source) {
             out.timeoutMs = raw.timeoutMs;
         if (typeof raw.cacheTtlMin === 'number')
             out.cacheTtlMin = raw.cacheTtlMin;
+        if (typeof raw.communityCatalog === 'boolean')
+            out.communityCatalog = raw.communityCatalog;
+        if (typeof raw.communityCatalogPin === 'string')
+            out.communityCatalogPin = raw.communityCatalogPin;
     }
     return out;
 }

package/lib/core/toggle.js

@@ -22,6 +22,7 @@ import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
 import { listInstalledPlugins } from './installed.js';
 import { isSingleRowPlugin, planRowOverride } from './patch-yaml.js';
 import { PROTECTED_MODULES } from './enablement.js';
+import { withMutationSession } from './market.js';
 import { setLivePluginDisabled, loaderHost } from './live-plugin.js';
 import { webProfileDir } from './env.js';
 export class ToggleError extends Error {
@@ -52,7 +53,11 @@ async function readPatchText(io, path) {
         throw error;
     }
 }
-export async function togglePlugin(pkg, enabled, deps = {}) {
+export function togglePlugin(pkg, enabled, deps = {}) {
+    // M2 Task 3：toggle 纳入统一 mutation session（本体单点获取；自身 file lock 在 session 内层）
+    return withMutationSession(() => togglePluginLocked(pkg, enabled, deps));
+}
+async function togglePluginLocked(pkg, enabled, deps = {}) {
     const key = String(pkg || '').trim();
     // ① 保护门最先：纯名单检查（空 profile 也先于 not-installed 命中）
     if (key === 'dsh-m' || PROTECTED_MODULES.includes(key)) {

package/lib/core/versions.js

@@ -4,6 +4,7 @@
  * GitHub：优先最新 release/tag（更新提示只跟稳定版走，不跟 main HEAD——中间提交可能不稳定）；
  * 未认证限额 60 次/小时，自用足够。
  */
+import { gt } from 'semver';
 import { fetchJsonLimited, HttpError } from './httpx.js';
 /** GitHub 匿名限额（60 次/小时/IP）用尽时返回可读提示（含重置等待分钟数），否则 null。 */
 function githubRateLimitMessage(err) {
@@ -77,46 +78,126 @@ export async function npmLatest(pkg, timeoutMs = 20_000, signal, registry) {
         tarball: typeof data.dist?.tarball === 'string' ? data.dist.tarball : undefined,
     };
 }
-export async function githubTagSha(repo, tag, timeoutMs = 20_000, signal) {
+export async function githubTagSha(repo, tag, timeoutMs = 20_000, signal, budget, apiBase = 'https://api.github.com') {
     // commits/{ref} 会自动解引用 annotated tag，返回的才是可用于 #sha 锁定的 commit
-    const data = await fetchJsonLimited(`https://api.github.com/repos/${repo}/commits/${encodeURIComponent(tag)}`, {
+    const data = await fetchJsonLimited(`${apiBase}/repos/${repo}/commits/${encodeURIComponent(tag)}`, {
         timeoutMs,
         signal,
         headers: { accept: 'application/vnd.github+json' },
+        onRequest: wireReserve(budget),
     });
     const sha = typeof data.sha === 'string' ? data.sha : '';
     if (!/^[0-9a-f]{40}$/.test(sha))
         throw new Error(`GitHub 未返回有效 SHA: ${repo}@${tag}`);
     return sha;
 }
-/** GitHub 来源的“最新稳定点”：优先最新 release（排除 draft/prerelease），无则回退 tags 列表首项。 */
-export async function githubLatestTag(repo, timeoutMs = 20_000, signal) {
-    if (!/^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9._-]+$/.test(repo))
-        throw new Error(`无效 GitHub 仓库: ${repo}`);
+/** 预算拒绝：该跳 fetch 不发出，错误可识别（latestError 呈现，不与其他网络错误混淆）。 */
+export class GithubBudgetExhaustedError extends Error {
+    constructor() {
+        super('GitHub 更新检查预算已用尽，本次检查的剩余条目未完成');
+        this.name = 'GithubBudgetExhaustedError';
+    }
+}
+export const GITHUB_PASSIVE_PER_REQUEST_MAX = 25;
+export const GITHUB_PASSIVE_HOURLY_MAX = 50;
+const HOURLY_MS = 3_600_000;
+/** 宿主级滚动 1 小时命中窗（仅被动探测路径计数；active 调用不经过 reserve 即不受限）。 */
+const hourlyHits = [];
+function hourlyReserve() {
+    const now = Date.now();
+    while (hourlyHits.length > 0 && now - hourlyHits[0] >= HOURLY_MS)
+        hourlyHits.shift();
+    if (hourlyHits.length >= GITHUB_PASSIVE_HOURLY_MAX)
+        return 'exhausted';
+    hourlyHits.push(now);
+    return 'ok';
+}
+/** 测试钩子：清空宿主滚动窗口。 */
+export function _resetGithubHourlyWindowForTests() {
+    hourlyHits.length = 0;
+}
+/** 测试钩子：把窗口内全部命中回拨指定毫秒（模拟时间流逝，测过期滑出）。 */
+export function _backdateGithubHourlyWindowForTests(ms) {
+    for (let i = 0; i < hourlyHits.length; i++)
+        hourlyHits[i] = (hourlyHits[i] ?? 0) - ms;
+}
+export function createGithubRequestBudget(opts = {}) {
+    let used = 0;
+    const max = Math.max(0, Math.floor(opts.perRequestMax ?? GITHUB_PASSIVE_PER_REQUEST_MAX));
+    return {
+        reserve() {
+            if (used >= max)
+                return 'exhausted';
+            if (hourlyReserve() === 'exhausted')
+                return 'exhausted';
+            used += 1;
+            return 'ok';
+        },
+    };
+}
+/** wire 层 reserve 钩子（httpx onRequest）：拒绝即中止该跳且不发出请求；无预算 → undefined（零预算交互）。 */
+function wireReserve(budget) {
+    if (!budget)
+        return undefined;
+    return () => {
+        if (budget.reserve() === 'exhausted')
+            throw new GithubBudgetExhaustedError();
+    };
+}
+const ghFlights = new Map();
+function ghAbortError() {
+    const err = new Error('Aborted');
+    err.name = 'AbortError';
+    return err;
+}
+function raceWaiter(promise, timeoutMs, signal) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`GitHub 请求超时（${timeoutMs}ms）`)), Math.max(1, timeoutMs));
+        const onAbort = () => reject(ghAbortError());
+        if (signal) {
+            if (signal.aborted) {
+                clearTimeout(timer);
+                reject(ghAbortError());
+                return;
+            }
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+        const done = (fn) => {
+            clearTimeout(timer);
+            if (signal)
+                signal.removeEventListener('abort', onAbort);
+            fn();
+        };
+        promise.then((value) => done(() => resolve(value)), (err) => done(() => reject(err)));
+    });
+}
+/** 共享 flight 的实际 fetch 序列：release 路径 1–2 个 wire 请求、fallback 路径逐次 reserve。 */
+async function fetchGithubTag(repo, timeoutMs, signal, budget, apiBase = 'https://api.github.com') {
     const headers = { accept: 'application/vnd.github+json' };
+    const reserve = wireReserve(budget);
     try {
         // 1) 最新 release（404 = 仓库从未发过 release → 回退 tags）
         try {
-            const rel = await fetchJsonLimited(`https://api.github.com/repos/${repo}/releases/latest`, { timeoutMs, signal, headers });
+            const rel = await fetchJsonLimited(`${apiBase}/repos/${repo}/releases/latest`, { timeoutMs, signal, headers, onRequest: reserve });
             const tag = typeof rel.tag_name === 'string' ? rel.tag_name.trim() : '';
             if (tag)
-                return { tag, sha: await githubTagSha(repo, tag, timeoutMs, signal) };
+                return { tag, sha: await githubTagSha(repo, tag, timeoutMs, signal, budget, apiBase) };
         }
         catch (err) {
             const status = err.status;
             if (status !== 404)
                 throw err;
         }
-        // 2) 回退：tags 列表（GitHub 按创建时间倒序，首项即最新）
-        const tags = await fetchJsonLimited(`https://api.github.com/repos/${repo}/tags`, { timeoutMs, signal, headers });
+        // 2) 回退：tags 列表（GitHub 按创建时间倒序，首项即最新）——tag object sha 经 commits/{ref}
+        //    解引用为 commit sha（与 release 路径同语义，annotated tag 的 object sha 不可直接锁定）
+        const tags = await fetchJsonLimited(`${apiBase}/repos/${repo}/tags`, { timeoutMs, signal, headers, onRequest: reserve });
         if (!Array.isArray(tags) || !tags.length)
             throw new Error(`仓库没有任何 tag: ${repo}`);
         const first = tags[0];
         const name = typeof first.name === 'string' ? first.name : '';
-        const sha = first.commit && typeof first.commit.sha === 'string' ? first.commit.sha : '';
-        if (!name || !/^[0-9a-f]{40}$/.test(sha))
+        if (!name)
             throw new Error(`tag 信息无效: ${repo}`);
-        return { tag: name, sha };
+        return { tag: name, sha: await githubTagSha(repo, name, timeoutMs, signal, budget, apiBase) };
     }
     catch (err) {
         const rateLimit = githubRateLimitMessage(err);
@@ -125,18 +206,61 @@ export async function githubLatestTag(repo, timeoutMs = 20_000, signal) {
         throw err;
     }
 }
+function releaseGhFlight(key, flight) {
+    flight.refs -= 1;
+    if (flight.refs <= 0) {
+        flight.ctrl.abort();
+        if (ghFlights.get(key) === flight)
+            ghFlights.delete(key);
+    }
+}
+/**
+ * GitHub 来源的“最新稳定点”：优先最新 release（排除 draft/prerelease），无则回退 tags 列表首项。
+ * Q46 预算语义（M1 Task 5）：
+ * - 同仓库 in-flight single-flight，key = 仓库 + 预算策略池（passive-budgeted / active-unbudgeted 互不 join）；
+ * - 记账：flight 创建时绑定 leader 的预算对象（一次）；reserve() 挂 httpx onRequest，
+ *   每个物理 outbound fetch（含重定向每一跳）各一次；joiner 不重复 reserve（join 零 wire 成本，
+ *   预算已耗尽的 waiter 可免费加入既有 flight）；
+ * - waiter-scoped：每个 waiter 用自己的 timeoutMs/signal race 共享 Promise；任何 waiter 的
+ *   signal 都不影响共享请求——最后一个 waiter 离开才 abort；
+ * - 无 budget 的调用（用户主动 install/upgrade/诊断）零预算交互，不受被动窗口限制。
+ */
+export async function githubLatestTag(repo, timeoutMs = 20_000, signal, budget, apiBase = 'https://api.github.com') {
+    if (!/^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9._-]+$/.test(repo))
+        throw new Error(`无效 GitHub 仓库: ${repo}`);
+    const key = `${budget ? 'passive' : 'active'}§${repo}`;
+    let flight = ghFlights.get(key);
+    if (!flight) {
+        const ctrl = new AbortController();
+        const created = { refs: 0, ctrl, promise: fetchGithubTag(repo, timeoutMs, ctrl.signal, budget, apiBase) };
+        created.promise.finally(() => {
+            if (ghFlights.get(key) === created && created.refs <= 0)
+                ghFlights.delete(key);
+        }).catch(() => undefined);
+        ghFlights.set(key, created);
+        flight = created;
+    }
+    flight.refs += 1;
+    try {
+        return await raceWaiter(flight.promise, timeoutMs, signal);
+    }
+    finally {
+        releaseGhFlight(key, flight);
+    }
+}
+/**
+ * 版本前进比较（0.5.0 语义加固）：标准 semver 前进比较——prerelease < 正式版、
+ * build metadata 不参与比较。旧自定义折叠实现把 `1.2.3-beta.1` 的数字尾段参与比较、
+ * 误判为大于 `1.2.3`，本实现以 semver.gt 修正。非法输入不抛、一律 false。
+ */
 export function isNewerVersion(candidate, current) {
-    const parse = (v) => String(v || '')
-        .replace(/^v/i, '')
-        .split(/[-+.]/)
-        .map((part) => (/^\d+$/.test(part) ? Number(part) : part))
-        .map((n) => (typeof n === 'number' ? n : 0));
-    const a = parse(candidate);
-    const b = parse(current);
-    for (let i = 0; i < Math.max(a.length, b.length); i++) {
-        const diff = (a[i] ?? 0) - (b[i] ?? 0);
-        if (diff !== 0)
-            return diff > 0;
+    // 只接受精确 semver（与收录语义一致：v 前缀/range/tag 不参与比较）；非法输入不抛、一律 false
+    if (!EXACT_VERSION_RE.test(String(candidate ?? '')) || !EXACT_VERSION_RE.test(String(current ?? '')))
+        return false;
+    try {
+        return gt(String(candidate), String(current));
+    }
+    catch {
+        return false;
     }
-    return false;
 }

package/lib/host.js

@@ -24,6 +24,8 @@ export const Config = Schema.object({
     registryUrl: live(Schema.string().description('registry 地址：空值使用默认官方清单；支持 HTTPS URL、loopback HTTP URL 或本机绝对路径/file://（整体覆盖默认清单，live 生效）')),
     timeoutMs: live(Schema.number().default(20000).description('上游请求超时（毫秒）')),
     cacheTtlMin: live(Schema.number().default(60).description('registry 缓存时长（分钟）')),
+    communityCatalog: live(Schema.boolean().default(true).description('社区清单：awesome-dsh-plugin 全量社区目录叠加进市场（只读，live 生效）')),
+    communityCatalogPin: live(Schema.string().description('社区目录版本锁定：精确 semver（如 2026.928.1），空值跟随 latest')),
 });
 export function apply(ctx, config) {
     // 卸载前的 live-disable 依赖 loader（skillhub 同款）