@morehao/dsh-github-trending 0.2.0 → 0.3.1

package/lib/index.js

@@ -5,22 +5,17 @@ import {
   Store,
   createRoutes,
   createTrendingHistoryTool,
-  createTrendingRunTool
-} from "./chunk-HIJIQJCZ.js";
+  createTrendingRunTool,
+  createUpdateService,
+  readPluginInfo
+} from "./chunk-NMINPPWO.js";
 import "./chunk-XLIFTAVL.js";
 
 // src/index.ts
-import { createRequire } from "module";
 var name = "dsh-github-trending";
 var inject = ["webServer"];
 function readVersion() {
-  try {
-    const require2 = createRequire(import.meta.url);
-    const pkg = require2("../package.json");
-    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
+  return readPluginInfo().version;
 }
 var VERSION = readVersion();
 function apply(ctx, config = {}) {
@@ -31,6 +26,18 @@ function apply(ctx, config = {}) {
     ctx.logger?.info?.(`[dsh-github-trending] ${event}${suffix}`);
   };
   const store = new Store({ env, ...config.stateDir === void 0 ? {} : { dir: config.stateDir } });
+  try {
+    const migration = store.migrateLegacyState();
+    if (migration.stateChanged || migration.historyMarked > 0) {
+      log("state.migrated", {
+        clearedDigest: migration.clearedDigest,
+        clearedPendingPr: migration.clearedPendingPr,
+        historyMarked: migration.historyMarked
+      });
+    }
+  } catch (error) {
+    ctx.logger?.warn?.(`[dsh-github-trending] \u65E7\u72B6\u6001\u8FC1\u79FB\u5931\u8D25\uFF1A${error instanceof Error ? error.message : String(error)}`);
+  }
   if (config.corePath !== void 0 && config.corePath !== "") {
     const settings = store.readSettings();
     if (settings.corePath === "") store.writeSettings({ ...settings, corePath: config.corePath });
@@ -39,6 +46,7 @@ function apply(ctx, config = {}) {
     store,
     get,
     env,
+    logger: log,
     onFinished: (summary) => log("run.finished", { id: summary.id, ok: summary.ok, skipped: summary.skipped, files: summary.files })
   });
   const scheduler = new Scheduler({
@@ -51,7 +59,29 @@ function apply(ctx, config = {}) {
     },
     onError: (error) => ctx.logger?.warn?.(`[dsh-github-trending] \u5B9A\u65F6\u8FD0\u884C\u5931\u8D25\uFF1A${error instanceof Error ? error.message : String(error)}`)
   });
-  const handler = createRoutes({ store, runner, scheduler, get, env, version: VERSION, logger: log });
+  const pluginInfo = readPluginInfo();
+  const update = createUpdateService({
+    get,
+    env,
+    meta: {
+      name: pluginInfo.name,
+      version: VERSION,
+      ...pluginInfo.repository === void 0 ? {} : { repository: pluginInfo.repository }
+    },
+    logger: log
+  });
+  const handler = createRoutes({
+    update,
+    store,
+    runner,
+    scheduler,
+    get,
+    env,
+    version: VERSION,
+    pluginName: pluginInfo.name,
+    ...pluginInfo.repository === void 0 ? {} : { repository: pluginInfo.repository },
+    logger: log
+  });
   const register = () => {
     const webServer = ctx.webServer ?? get("webServer");
     if (webServer === void 0 || typeof webServer.register !== "function") {

package/lib/internal.d.ts

@@ -1,61 +1,9 @@
+import { ErrorCode, FileArtifact, ErrorInfo, RunRequest, RunResult, State, StateRun } from '@morehao/trendradar-contract';
 import http from 'node:http';
+import { Updater, PluginMeta, Logger } from '@morehao/dsh-plugin-kit/update';
 
 /**
- * 由 scripts/gen-ipc-types.mjs 从 contract/schema/ipc.v1.json 生成，**不要手改**。
- * 上游：https://github.com/morehao/trendradar.git@5cf0ad26c5748cf2bc9a1cc4ce66a09411d590f7
- * aggregate：4717074d26d1a6d85c1885bd052d411f81c20b39467cb81c398f565bbe34dcde
- * 重新生成：npm run gen:ipc
- */
-type ErrorCode = "INTERNAL" | "CONFIG_INVALID" | "PAYLOAD_TOO_LARGE" | "FETCH_FAILED" | "FETCH_RATE_LIMITED" | "PARSE_FAILED" | "MODEL_UNAUTHORIZED" | "MODEL_RATE_LIMITED" | "MODEL_TIMEOUT" | "MODEL_FAILED" | "MODEL_BAD_OUTPUT" | "GIT_NOT_INSTALLED" | "REPO_NOT_GIT" | "REPO_DIRTY" | "GIT_OPERATION_FAILED" | "PR_FAILED" | "NOT_MERGEABLE";
-interface ErrorInfo {
-    code: ErrorCode;
-    message: string;
-    retriable: boolean;
-    details?: Record<string, unknown>;
-    [key: string]: unknown;
-}
-interface FileArtifact {
-    path: string;
-    bytes: number;
-    sha256: string;
-    [key: string]: unknown;
-}
-interface RunRequest {
-    ipcSchema: 1;
-    command: "run" | "serve" | "config" | "version";
-    configPath?: string;
-    date?: string;
-    dryRun?: boolean;
-    outputDir?: string;
-}
-interface RunResult {
-    ipcSchema: 1;
-    ok: boolean;
-    command: "run" | "serve" | "config" | "version";
-    startedAt: string;
-    finishedAt: string;
-    skipped: boolean;
-    files: FileArtifact[];
-    error?: ErrorInfo;
-    warnings?: string[];
-    [key: string]: unknown;
-}
-interface StateRun {
-    date: string;
-    contentHash: string;
-    outputDir?: string;
-    runAt: string;
-    [key: string]: unknown;
-}
-interface State {
-    ipcSchema: 1;
-    lastRun?: StateRun;
-    [key: string]: unknown;
-}
-declare const IPC_SCHEMA_VERSION: 1;
-
-/**
- * 错误码：核心码（`ipc.v1` 的 17 个）+ 插件自己的码。
+ * 错误码：核心码（契约包 `ipc.v2` / `errors.v2` 的 17 个）+ 插件自己的码。
  *
  * 核心当前只在 stderr 打 `error: <CODE>: <message>`，模型/抓取的失败甚至没有码，
  * 所以这里承担两件事：
@@ -79,8 +27,15 @@ declare function isRetriable(code: string): boolean;
 /** 错误码 → 界面落点。UI 用这个决定红字出现在哪个区块。 */
 type ErrorArea = 'core' | 'model' | 'repo' | 'auth' | 'run';
 declare function areaOf(code: string): ErrorArea;
+/**
+ * push 失败的细分原因。核心新版本会在 `details.reason` 里给出；旧核心只有
+ * stderr 时按文本兜底。`stale-lease` 必须排在 `non-fast-forward` 之前：
+ * 前者是 lease 基线过期，后者是历史分叉，下一步完全不同。
+ */
+type GitReason = 'stale-lease' | 'non-fast-forward' | 'auth' | 'protected' | 'hook' | 'pathspec' | 'unknown';
+declare function reasonOf(code: string, message?: string, details?: Record<string, unknown>): string | undefined;
 /** 每种码一句「下一步怎么做」，避免界面只给码不给路。 */
-declare function hintOf(code: string, message?: string): string;
+declare function hintOf(code: string, message?: string, reason?: string): string;
 /**
  * 从核心的 stderr 里解出一个结构化错误。
  *
@@ -99,38 +54,32 @@ declare function redact(input: string, secrets?: Array<string | undefined>): str
 type errors_AnyCode = AnyCode;
 type errors_ClassifiedError = ClassifiedError;
 type errors_ErrorArea = ErrorArea;
+type errors_GitReason = GitReason;
 declare const errors_PLUGIN_CODES: typeof PLUGIN_CODES;
 type errors_PluginCode = PluginCode;
 declare const errors_areaOf: typeof areaOf;
 declare const errors_classifyStderr: typeof classifyStderr;
 declare const errors_hintOf: typeof hintOf;
 declare const errors_isRetriable: typeof isRetriable;
+declare const errors_reasonOf: typeof reasonOf;
 declare const errors_redact: typeof redact;
 declare namespace errors {
-  export { type errors_AnyCode as AnyCode, type errors_ClassifiedError as ClassifiedError, type errors_ErrorArea as ErrorArea, errors_PLUGIN_CODES as PLUGIN_CODES, type errors_PluginCode as PluginCode, errors_areaOf as areaOf, errors_classifyStderr as classifyStderr, errors_hintOf as hintOf, errors_isRetriable as isRetriable, errors_redact as redact };
+  export { type errors_AnyCode as AnyCode, type errors_ClassifiedError as ClassifiedError, type errors_ErrorArea as ErrorArea, type errors_GitReason as GitReason, errors_PLUGIN_CODES as PLUGIN_CODES, type errors_PluginCode as PluginCode, errors_areaOf as areaOf, errors_classifyStderr as classifyStderr, errors_hintOf as hintOf, errors_isRetriable as isRetriable, errors_reasonOf as reasonOf, errors_redact as redact };
 }
 
-/**
- * 契约类型与运行时守卫。
- *
- * 类型来自 `contract/schema/ipc.v1.json` 的生成物（`ipc.gen.ts`）；本文件只放
- * 契约没有、但插件必须理解的东西：核心 `version --json` 的握手形状、核心 `run --json`
- * 的输出形状，以及把两种结果形状归一化成 `RunOutcome` 的解析器。
- *
- * 为什么同时接受两种形状：`contract/schema/ipc.v1.json` 定义的是 `RunResult`
- * （`ok`/`startedAt`/`error.code`），而当前核心的 `run --json` 输出的是一份更小的
- * `runOutput`（`files`/`skipped`/`branch`/`prUrl`/`digest.contentHash`），错误只走
- * stderr 文本。核心补上信封后，`parseRunResult` 无需改动即可接住。
- */
-
+/** 插件实现所对应的 IPC 契约版本（契约包 `ipc.v2.json` 的 wire 整数）。 */
+declare const IPC_SCHEMA_VERSION: 2;
 /** 插件能接受的 digest 契约版本（与核心 `version --json` 的 digestSchema 比对）。 */
-declare const SUPPORTED_DIGEST_SCHEMA = 1;
+declare const SUPPORTED_DIGEST_SCHEMA: 2;
+/** 契约包 `contractVersion` 的主版本；0.x 期间同主版本即视为同一契约线。 */
+declare const SUPPORTED_CONTRACT_MAJOR = 0;
 /** 核心 `version --json` 的输出。 */
 interface VersionInfo {
     version: string;
     commit?: string;
     ipcSchema: number;
     digestSchema: number;
+    contractVersion?: string;
     supportedProviders?: string[];
 }
 /** 插件侧的错误信息：`code` 可能是核心码，也可能是插件码（`CORE_*` 等）。 */
@@ -150,6 +99,8 @@ interface RunOutcome {
     branch?: string;
     commit?: string;
     prUrl?: string;
+    /** 核心给出的跳过原因：merged | pr-closed | unchanged（可选，旧核心没有）。 */
+    skipReason?: string;
     error?: RunError;
     warnings: string[];
     startedAt: string;
@@ -168,6 +119,7 @@ declare class IpcError extends Error {
 declare function parseJsonObject(text: string): Record<string, unknown>;
 declare function isVersionInfo(value: unknown): value is VersionInfo;
 declare function parseVersionInfo(text: string): VersionInfo;
+/** 契约包 `RunResult` → 插件内部 `RunOutcome` 的唯一映射。 */
 interface ParseRunOptions {
     coreVersion: string;
     startedAt: string;
@@ -178,33 +130,34 @@ interface ParseRunOptions {
 /**
  * 把核心 `run --json` 的 stdout 归一化成 `RunOutcome`。
  *
- * 两种形状的判别：有 `ipcSchema` 且 `command === 'run'` 就是契约 `RunResult`；
- * 否则按当前核心的 `runOutput` 处理。两者都不像就直接 `IPC_INVALID`，
- * 绝不「猜字段」——结果信封读错会把失败当成功写进状态。
+ * 唯一接受的形状是契约 `RunResult`（`ipcSchema=2` / `command=run`），并用契约包
+ * 自带的 ajv 校验器校验。任何其它形状直接 `IPC_INVALID`——结果信封读错会把失败
+ * 当成功写进状态。
  */
 declare function parseRunResult(text: string, options: ParseRunOptions): RunOutcome;
 
-type ipc_ErrorCode = ErrorCode;
-type ipc_ErrorInfo = ErrorInfo;
-type ipc_FileArtifact = FileArtifact;
+declare const ipc_ErrorCode: typeof ErrorCode;
+declare const ipc_ErrorInfo: typeof ErrorInfo;
+declare const ipc_FileArtifact: typeof FileArtifact;
 declare const ipc_IPC_SCHEMA_VERSION: typeof IPC_SCHEMA_VERSION;
 type ipc_IpcError = IpcError;
 declare const ipc_IpcError: typeof IpcError;
 type ipc_ParseRunOptions = ParseRunOptions;
 type ipc_RunError = RunError;
 type ipc_RunOutcome = RunOutcome;
-type ipc_RunRequest = RunRequest;
-type ipc_RunResult = RunResult;
+declare const ipc_RunRequest: typeof RunRequest;
+declare const ipc_RunResult: typeof RunResult;
+declare const ipc_SUPPORTED_CONTRACT_MAJOR: typeof SUPPORTED_CONTRACT_MAJOR;
 declare const ipc_SUPPORTED_DIGEST_SCHEMA: typeof SUPPORTED_DIGEST_SCHEMA;
-type ipc_State = State;
-type ipc_StateRun = StateRun;
+declare const ipc_State: typeof State;
+declare const ipc_StateRun: typeof StateRun;
 type ipc_VersionInfo = VersionInfo;
 declare const ipc_isVersionInfo: typeof isVersionInfo;
 declare const ipc_parseJsonObject: typeof parseJsonObject;
 declare const ipc_parseRunResult: typeof parseRunResult;
 declare const ipc_parseVersionInfo: typeof parseVersionInfo;
 declare namespace ipc {
-  export { type ipc_ErrorCode as ErrorCode, type ipc_ErrorInfo as ErrorInfo, type ipc_FileArtifact as FileArtifact, ipc_IPC_SCHEMA_VERSION as IPC_SCHEMA_VERSION, ipc_IpcError as IpcError, type ipc_ParseRunOptions as ParseRunOptions, type ipc_RunError as RunError, type ipc_RunOutcome as RunOutcome, type ipc_RunRequest as RunRequest, type ipc_RunResult as RunResult, ipc_SUPPORTED_DIGEST_SCHEMA as SUPPORTED_DIGEST_SCHEMA, type ipc_State as State, type ipc_StateRun as StateRun, type ipc_VersionInfo as VersionInfo, ipc_isVersionInfo as isVersionInfo, ipc_parseJsonObject as parseJsonObject, ipc_parseRunResult as parseRunResult, ipc_parseVersionInfo as parseVersionInfo };
+  export { ipc_ErrorCode as ErrorCode, ipc_ErrorInfo as ErrorInfo, ipc_FileArtifact as FileArtifact, ipc_IPC_SCHEMA_VERSION as IPC_SCHEMA_VERSION, ipc_IpcError as IpcError, type ipc_ParseRunOptions as ParseRunOptions, type ipc_RunError as RunError, type ipc_RunOutcome as RunOutcome, ipc_RunRequest as RunRequest, ipc_RunResult as RunResult, ipc_SUPPORTED_CONTRACT_MAJOR as SUPPORTED_CONTRACT_MAJOR, ipc_SUPPORTED_DIGEST_SCHEMA as SUPPORTED_DIGEST_SCHEMA, ipc_State as State, ipc_StateRun as StateRun, type ipc_VersionInfo as VersionInfo, ipc_isVersionInfo as isVersionInfo, ipc_parseJsonObject as parseJsonObject, ipc_parseRunResult as parseRunResult, ipc_parseVersionInfo as parseVersionInfo };
 }
 
 type Provider = string;
@@ -403,11 +356,30 @@ declare namespace paths {
 }
 
 declare const HISTORY_LIMIT = 30;
+/** 预览副本上限：最多保留 30 份，和 history 的 30 天窗口对齐。 */
+declare const PREVIEW_LIMIT = 30;
+/** 一次预览只读这么多字节；超过的不复制，避免把大文件塞进状态目录。 */
+declare const PREVIEW_MAX_BYTES: number;
+/** 契约 v2 的固定内容哈希算法；旧版状态没有这个字段，据此识别 legacy。 */
+declare const CONTENT_HASH_ALGO_V2 = "jcs-sha256-v1";
 interface DigestIdentity {
     date: string;
     contentHash: string;
+    /** 产出该 hash 的算法；v2 新写的一律是 jcs-sha256-v1。 */
+    contentHashAlgo: string;
     coreVersion: string;
 }
+/**
+ * 预览副本的元数据：只记「哪份文件、多大、内容 sha256」，正文进 previews/。
+ * `file` 是仓库内相对路径，不落绝对路径（避免把用户目录写进状态）。
+ */
+interface PreviewMeta {
+    file: string;
+    bytes: number;
+    sha256: string;
+    /** 只读接口截断时为 true；当前 512 KB 上限下正常不会出现。 */
+    truncated?: boolean;
+}
 interface RunRecord {
     id: string;
     at: string;
@@ -417,12 +389,19 @@ interface RunRecord {
     /** `null` 表示没有错误。 */
     errorCode?: string;
     errorMessage?: string;
+    /** push 等失败的机器可判定原因（stale-lease / non-fast-forward / auth ...）。 */
+    errorReason?: string;
+    /** 跳过原因：merged / pr-closed / unchanged。 */
+    skipReason?: string;
     durationMs: number;
     files: number;
+    /** 运行所属的调度时区日期（YYYY-MM-DD）；旧记录可能没有。 */
+    date?: string;
     contentHash?: string;
     branch?: string;
     commit?: string;
     prUrl?: string;
+    preview?: PreviewMeta;
     coreVersion: string;
     model: {
         provider: string;
@@ -431,6 +410,8 @@ interface RunRecord {
     languages: string[];
     warnings: string[];
     logFile?: string;
+    /** true = 契约 v1 时代留下的旧记录（contentHash 算法不同，不可与 v2 比较）。 */
+    legacy?: boolean;
 }
 interface PendingPr {
     url: string;
@@ -440,6 +421,8 @@ interface PendingPr {
 }
 interface PluginState {
     lastRunAt?: string;
+    /** 最近一次成功（ok=true，含 skipped）的运行时间；调度用它锁当天。 */
+    lastSuccessAt?: string;
     lastDigest?: DigestIdentity;
     lastResult?: RunRecord;
     pendingPr?: PendingPr;
@@ -447,6 +430,12 @@ interface PluginState {
 interface HistoryFile {
     records: RunRecord[];
 }
+interface LegacyMigrationResult {
+    stateChanged: boolean;
+    clearedDigest: boolean;
+    clearedPendingPr: boolean;
+    historyMarked: number;
+}
 /** 原子写：同目录临时文件写完再 rename，权限 0600。 */
 declare function writeJsonAtomic(file: string, value: unknown): void;
 interface StoreOptions {
@@ -462,26 +451,50 @@ declare class Store {
     get statePath(): string;
     get historyPath(): string;
     get logsPath(): string;
+    get previewsPath(): string;
     readSettings(): Settings;
     writeSettings(settings: Settings): void;
     readState(): PluginState;
     writeState(state: PluginState): void;
+    /**
+     * 把 v1 时代遗留的 state / history 一次性清洗落盘：清掉不可信的 lastDigest 与
+     * 与之绑定的 pendingPr，并给旧历史记录打 legacy 标。插件启动时调用一次。
+     */
+    migrateLegacyState(): LegacyMigrationResult;
     readHistory(): RunRecord[];
+    /** 原始历史（不做 legacy 标注）：写入路径用它，避免把「读时标注」持久化。 */
+    private readHistoryRaw;
     /** 记录一次运行：历史裁剪到 30 条，state 同步更新。 */
     recordRun(record: RunRecord, next?: Partial<PluginState>): void;
     newLogPath(id: string): string;
     appendLog(file: string, line: string): void;
     hasLog(file: string): boolean;
     readLog(file: string, maxBytes?: number): string;
+    /** 预览副本路径；写入前才建目录，读接口不会凭空创建目录。 */
+    previewPath(id: string): string;
+    /** 写预览副本：同目录临时文件 + rename、0600；写完裁到 30 份。 */
+    writePreview(id: string, text: string): void;
+    /** 读预览副本；不存在/不可读返回 undefined，超过上限时截断。 */
+    readPreview(id: string, maxBytes?: number): {
+        text: string;
+        truncated: boolean;
+    } | undefined;
+    /** 只保留最近 `keep` 份预览副本；按 mtime 倒序，任何错误都忽略。 */
+    prunePreviews(keep?: number): void;
 }
 /** 运行 id：时间前缀便于按时间排序，随机后缀避免同毫秒撞车。 */
 declare function newRunId(now?: Date): string;
 
+declare const state_CONTENT_HASH_ALGO_V2: typeof CONTENT_HASH_ALGO_V2;
 type state_DigestIdentity = DigestIdentity;
 declare const state_HISTORY_LIMIT: typeof HISTORY_LIMIT;
 type state_HistoryFile = HistoryFile;
+type state_LegacyMigrationResult = LegacyMigrationResult;
+declare const state_PREVIEW_LIMIT: typeof PREVIEW_LIMIT;
+declare const state_PREVIEW_MAX_BYTES: typeof PREVIEW_MAX_BYTES;
 type state_PendingPr = PendingPr;
 type state_PluginState = PluginState;
+type state_PreviewMeta = PreviewMeta;
 type state_RunRecord = RunRecord;
 type state_Store = Store;
 declare const state_Store: typeof Store;
@@ -489,7 +502,7 @@ type state_StoreOptions = StoreOptions;
 declare const state_newRunId: typeof newRunId;
 declare const state_writeJsonAtomic: typeof writeJsonAtomic;
 declare namespace state {
-  export { type state_DigestIdentity as DigestIdentity, state_HISTORY_LIMIT as HISTORY_LIMIT, type state_HistoryFile as HistoryFile, type state_PendingPr as PendingPr, type state_PluginState as PluginState, type state_RunRecord as RunRecord, state_Store as Store, type state_StoreOptions as StoreOptions, state_newRunId as newRunId, state_writeJsonAtomic as writeJsonAtomic };
+  export { state_CONTENT_HASH_ALGO_V2 as CONTENT_HASH_ALGO_V2, type state_DigestIdentity as DigestIdentity, state_HISTORY_LIMIT as HISTORY_LIMIT, type state_HistoryFile as HistoryFile, type state_LegacyMigrationResult as LegacyMigrationResult, state_PREVIEW_LIMIT as PREVIEW_LIMIT, state_PREVIEW_MAX_BYTES as PREVIEW_MAX_BYTES, type state_PendingPr as PendingPr, type state_PluginState as PluginState, type state_PreviewMeta as PreviewMeta, type state_RunRecord as RunRecord, state_Store as Store, type state_StoreOptions as StoreOptions, state_newRunId as newRunId, state_writeJsonAtomic as writeJsonAtomic };
 }
 
 interface CoreRelease {
@@ -509,7 +522,7 @@ interface ReleaseDescriptor extends CoreRelease {
     binaryPath: string;
     cached: boolean;
 }
-/** 从本包的 package.json 读核心版本（`sync-contract --ref vX` 会同时更新它）。 */
+/** 从本包的 package.json 读核心版本（`scripts/set-core-version.mjs` 会更新它）。 */
 declare function readCoreRelease(pkg?: {
     dsh?: {
         core?: {
@@ -717,6 +730,8 @@ interface RunCoreOptions {
     token?: string;
     date?: string;
     dryRun: boolean;
+    /** 谁触发的运行：核心用它在定时运行时尊重「人工关闭的 PR」。 */
+    trigger?: 'manual' | 'schedule';
     /** 回环代理地址：覆盖配置里的 model.baseURL（代理模式专用）。 */
     baseURLOverride?: string;
     signal?: AbortSignal;
@@ -1177,7 +1192,11 @@ interface RunSummary {
     files: number;
     contentHash?: string;
     branch?: string;
+    commit?: string;
     prUrl?: string;
+    preview?: PreviewMeta;
+    /** 核心给出的跳过原因（merged / pr-closed / unchanged）。 */
+    skipReason?: string;
     error?: {
         code: string;
         message: string;
@@ -1185,6 +1204,8 @@ interface RunSummary {
         area: string;
         retriable: boolean;
         inferred?: boolean;
+        /** 机器可判定的细分原因（push 失败时由核心给出）。 */
+        reason?: string;
     };
     warnings: string[];
     logFile?: string;
@@ -1205,6 +1226,8 @@ interface RunnerDeps {
     env?: NodeJS.ProcessEnv;
     /** 运行结束（成功或失败）后回调，用于刷新调度/界面缓存。 */
     onFinished?: (summary: RunSummary) => void;
+    /** 预览副本这类「可失败但不阻断运行」的事件走这里，不写进 warnings。 */
+    logger?: (event: string, data?: Record<string, unknown>) => void;
 }
 declare class Runner {
     private active;
@@ -1218,6 +1241,15 @@ declare class Runner {
     run(options: RunRequestOptions): Promise<RunSummary>;
     private summarize;
     private failureSummary;
+    /**
+     * 从本次核心返回的 artifact 清单里选当天的 `.md`，只读复制到 previews/。
+     *
+     * 这是插件**唯一**读取用户仓库的场景，而且只读核心自己刚写出的那一份：
+     * - 路径必须在 `repo.path` 内（词法 + realpath 各判一次，挡 `..`/绝对路径/符号链接）；
+     * - 上限 512 KB、拒绝 NUL、sha256 必须与契约声明一致；
+     * - 任何一步失败都只记日志，返回 undefined；运行结果不受影响。
+     */
+    private capturePreview;
     /** 写历史与状态；同一天的 skipped 运行不覆盖 lastDigest。 */
     private record;
     /** 给设置页/工具用的「核心现在什么状态」。 */
@@ -1233,6 +1265,22 @@ declare namespace runner {
   export { type runner_RunRequestOptions as RunRequestOptions, type runner_RunSummary as RunSummary, runner_Runner as Runner, type runner_RunnerDeps as RunnerDeps };
 }
 
+interface PluginInfo {
+    name: string;
+    version: string;
+    repository?: string;
+}
+/** 只放行 GitHub 的 http(s) 地址；ssh / git+ 前缀先归一化。 */
+declare function normalizeRepositoryUrl(value: unknown): string | undefined;
+declare function readPluginInfo(): PluginInfo;
+
+type pluginInfo_PluginInfo = PluginInfo;
+declare const pluginInfo_normalizeRepositoryUrl: typeof normalizeRepositoryUrl;
+declare const pluginInfo_readPluginInfo: typeof readPluginInfo;
+declare namespace pluginInfo {
+  export { type pluginInfo_PluginInfo as PluginInfo, pluginInfo_normalizeRepositoryUrl as normalizeRepositoryUrl, pluginInfo_readPluginInfo as readPluginInfo };
+}
+
 /**
  * 调度（FR-P-08 / 规格 §9）。
  *
@@ -1276,7 +1324,8 @@ declare class Scheduler {
     private readonly deps;
     private timerHandle;
     private stopped;
-    private lastFiredFor;
+    /** 当天已尝试次数与时间；只在内存里，进程重启后重新计数。 */
+    private readonly attempts;
     constructor(deps: SchedulerDeps);
     start(): void;
     stop(): void;
@@ -1329,6 +1378,11 @@ interface RouteDeps {
     /** 注入用：pendingPr 对账的 fetch 实现（测试不联网）。 */
     fetchImpl?: typeof fetch;
     version: string;
+    /** 自更新服务（共享包引擎）；缺省时 /update 返回 404，不影响其它路由。 */
+    update?: Updater;
+    /** 包名与仓库地址都来自 package.json，由 src/index.ts 传入。 */
+    pluginName?: string;
+    repository?: string;
     logger?: (event: string, data?: Record<string, unknown>) => void;
 }
 declare function createRoutes(deps: RouteDeps): (request: http.IncomingMessage, response: http.ServerResponse) => Promise<void>;
@@ -1341,6 +1395,24 @@ declare namespace routes {
   export { routes_HEADER as HEADER, routes_ROUTE_PREFIX as ROUTE_PREFIX, type routes_RouteDeps as RouteDeps, routes_createRoutes as createRoutes };
 }
 
+interface UpdateServiceDeps {
+    get: (name: string) => unknown;
+    env: NodeJS.ProcessEnv;
+    meta: PluginMeta;
+    logger?: Logger;
+    fetchImpl?: typeof fetch;
+    /** 测试注入；默认走本仓的 execCapture。 */
+    exec?: (file: string, args: string[], options?: ExecOptions) => Promise<ExecResult>;
+    readFile?: (path: string) => Promise<string>;
+}
+declare function createUpdateService(deps: UpdateServiceDeps): Updater;
+
+type update_UpdateServiceDeps = UpdateServiceDeps;
+declare const update_createUpdateService: typeof createUpdateService;
+declare namespace update {
+  export { type update_UpdateServiceDeps as UpdateServiceDeps, update_createUpdateService as createUpdateService };
+}
+
 interface ImportCandidate {
     path: string;
     exists: boolean;
@@ -1582,4 +1654,4 @@ declare namespace tools {
   export { tools_createTrendingHistoryTool as createTrendingHistoryTool, tools_createTrendingRunTool as createTrendingRunTool };
 }
 
-export { channel, config, core, credentials, errors, exec, github, handshake$1 as handshake, importCli, ipc, locate, paths, pendingPr, preflight, proxy, quickfill, release, repo, routes, run, runner, schedule, state, tools };
+export { channel, config, core, credentials, errors, exec, github, handshake$1 as handshake, importCli, ipc, locate, paths, pendingPr, pluginInfo, preflight, proxy, quickfill, release, repo, routes, run, runner, schedule, state, tools, update as updateService };

package/lib/internal.js

@@ -11,6 +11,7 @@ import {
   locate_exports,
   paths_exports,
   pending_pr_exports,
+  plugin_info_exports,
   preflight_exports,
   proxy_exports,
   quickfill_exports,
@@ -21,8 +22,9 @@ import {
   runner_exports,
   schedule_exports,
   state_exports,
-  tools_exports
-} from "./chunk-HIJIQJCZ.js";
+  tools_exports,
+  update_exports
+} from "./chunk-NMINPPWO.js";
 import {
   exec_exports
 } from "./chunk-XLIFTAVL.js";
@@ -40,6 +42,7 @@ export {
   locate_exports as locate,
   paths_exports as paths,
   pending_pr_exports as pendingPr,
+  plugin_info_exports as pluginInfo,
   preflight_exports as preflight,
   proxy_exports as proxy,
   quickfill_exports as quickfill,
@@ -50,5 +53,6 @@ export {
   runner_exports as runner,
   schedule_exports as schedule,
   state_exports as state,
-  tools_exports as tools
+  tools_exports as tools,
+  update_exports as updateService
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morehao/dsh-github-trending",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "GitHub 趋势日报插件：每天定时 spawn 本地 trendradar 核心，抓取 Trending、生成中文简介与总结，提交到你的仓库并自动合并 PR。",
   "type": "module",
   "main": "lib/index.js",
@@ -14,13 +14,11 @@
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./locale/*.json": "./locale/*.json",
     "./icon": "./icon.svg",
-    "./contract/*": "./contract/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib",
     "client.js",
-    "contract",
     "locale",
     "cordis.patch.yml",
     "icon.svg",
@@ -51,13 +49,17 @@
       "optional": true
     }
   },
+  "dependencies": {
+    "@morehao/dsh-plugin-kit": "0.1.0",
+    "@morehao/trendradar-contract": "0.2.0"
+  },
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
     "core": {
       "repo": "morehao/trendradar",
-      "version": "0.2.0"
+      "version": "0.3.1"
     },
     "client": {
       "platform": "web",
@@ -75,8 +77,8 @@
     "dev:client": "node scripts/build-client.mjs --watch",
     "typecheck": "tsc --noEmit",
     "check:types": "tsc -p tsconfig.client.json",
-    "gen:ipc": "node scripts/gen-ipc-types.mjs",
-    "check:contract": "node scripts/sync-contract.mjs --check && node scripts/gen-ipc-types.mjs --check",
+    "set-core-version": "node scripts/set-core-version.mjs",
+    "check:contract": "node --test test/contract.test.mjs",
     "check:lockfile": "node scripts/check-lockfile.mjs",
     "check:syntax": "node scripts/check-syntax.mjs",
     "check:naming": "node scripts/check-naming.mjs",

package/contract/CONTRACT.sha256

@@ -1,10 +0,0 @@
-# trendradar contract hash (v1)
-# algorithm: sha256 per file (sorted), then sha256 of the concatenated lines
-f34aa3642938bad32df912768d543925f91858da66a8e726e4e4bf88a07d086c  fixtures/digest-degraded.json
-7bc67dcdc36c7b81df1915c4b50025cef6f0304ef2feb24f393d17771df252c9  fixtures/digest-empty-lang.json
-4fe9d91ce3f0ddcc17982e4f0acac950ebc6ec7f63427fe962ea581f3114c0c4  fixtures/digest-normal.json
-d52adbbb473d7ee2d856398a5651f96ba2019ee53ba6e14c27ef2d792b5db723  schema/api.v1.yaml
-ca9b640f374cded12a09ea00f0686eac14eee59eef94c27a61016175bc0d4ebb  schema/digest.v1.json
-cf8eb4f069e71c8738ccd5c4ffbfb266124ee86161fe8ad0677c9782d3ef8552  schema/ipc.v1.json
-2140c9d538bc935c092a83fb6377e3878b2c060992bf458f2437898f4649d41d  schema/model.v1.json
-aggregate: 4717074d26d1a6d85c1885bd052d411f81c20b39467cb81c398f565bbe34dcde