@morehao/dsh-github-trending 0.0.1 → 0.1.2

package/lib/internal.d.ts

@@ -0,0 +1,1443 @@
+import http from 'node:http';
+
+/**
+ * 由 scripts/gen-ipc-types.mjs 从 contract/schema/ipc.v1.json 生成，**不要手改**。
+ * 上游：https://github.com/morehao/trendradar.git@d3bf720a869732e7a2ee04fa39d32dd50868fd61
+ * aggregate：eb7f1ac9e117a709d15d87de89cf30e309c479e62dfa3d320cb8f154d3f1dc1e
+ * 重新生成：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;
+    runAt: string;
+    [key: string]: unknown;
+}
+interface State {
+    ipcSchema: 1;
+    lastRun?: StateRun;
+    [key: string]: unknown;
+}
+declare const IPC_SCHEMA_VERSION: 1;
+
+/**
+ * 错误码：核心码（`ipc.v1` 的 17 个）+ 插件自己的码。
+ *
+ * 核心当前只在 stderr 打 `error: <CODE>: <message>`，模型/抓取的失败甚至没有码，
+ * 所以这里承担两件事：
+ *   1. 从 stderr 里**优先**取出核心自己的码（有码就用码，不改写）；
+ *   2. 没有码时按稳定的文本特征归类，归类结果会标注 `inferred: true`，
+ *      让界面能区分「核心说的」与「插件猜的」。
+ */
+
+/** 插件在核心之外新增的码。前缀统一避免与核心码冲突。 */
+declare const PLUGIN_CODES: readonly ["CORE_UNAVAILABLE", "CORE_INCOMPATIBLE", "CORE_SPAWN_FAILED", "CORE_TIMEOUT", "CORE_CANCELLED", "CORE_CONFIG_CHANNEL_FAILED", "CORE_NOT_DOWNLOADED", "CORE_CHECKSUM_MISMATCH", "IPC_INVALID", "MODEL_KEY_MISSING", "MODEL_NOT_FOUND", "MODEL_PROVIDER_UNSUPPORTED", "GITHUB_AUTH", "PUSH_FAILED", "REPO_DIRTY"];
+type PluginCode = (typeof PLUGIN_CODES)[number];
+type AnyCode = ErrorCode | PluginCode;
+interface ClassifiedError {
+    code: AnyCode;
+    message: string;
+    retriable: boolean;
+    /** true = 插件按文本推断出来的码，不是核心明确返回的。 */
+    inferred: boolean;
+}
+declare function isRetriable(code: string): boolean;
+/** 错误码 → 界面落点。UI 用这个决定红字出现在哪个区块。 */
+type ErrorArea = 'core' | 'model' | 'repo' | 'auth' | 'run';
+declare function areaOf(code: string): ErrorArea;
+/** 每种码一句「下一步怎么做」，避免界面只给码不给路。 */
+declare function hintOf(code: string): string;
+/**
+ * 从核心的 stderr 里解出一个结构化错误。
+ *
+ * 优先级：`error: <CODE>: ...` 的显式码 > 文本归类 > INTERNAL。
+ * message 只取最后一条非空行（核心把根因打在最外层，前面的行多是上下文）。
+ */
+declare function classifyStderr(stderr: string): ClassifiedError;
+/**
+ * 脱敏：先把调用方已知的明文密钥逐个替换，再按形态兜一层。
+ * 所有进日志/返回给前端的 stderr 都必须过这里（AC-P-04 的第一道闸）。
+ */
+declare function redact(input: string, secrets?: Array<string | undefined>): string;
+
+type errors_AnyCode = AnyCode;
+type errors_ClassifiedError = ClassifiedError;
+type errors_ErrorArea = ErrorArea;
+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_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 };
+}
+
+/**
+ * 契约类型与运行时守卫。
+ *
+ * 类型来自 `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` 无需改动即可接住。
+ */
+
+/** 插件能接受的 digest 契约版本（与核心 `version --json` 的 digestSchema 比对）。 */
+declare const SUPPORTED_DIGEST_SCHEMA = 1;
+/** 核心 `version --json` 的输出。 */
+interface VersionInfo {
+    version: string;
+    commit?: string;
+    ipcSchema: number;
+    digestSchema: number;
+    supportedProviders?: string[];
+}
+/** 插件侧的错误信息：`code` 可能是核心码，也可能是插件码（`CORE_*` 等）。 */
+interface RunError {
+    code: AnyCode;
+    message: string;
+    retriable: boolean;
+    details?: Record<string, unknown>;
+}
+/** 归一化后的一次运行结果：状态、历史、工具返回值都用它。 */
+interface RunOutcome {
+    ok: boolean;
+    skipped: boolean;
+    dryRun: boolean;
+    files: FileArtifact[];
+    contentHash?: string;
+    branch?: string;
+    commit?: string;
+    prUrl?: string;
+    error?: RunError;
+    warnings: string[];
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    coreVersion: string;
+}
+declare class IpcError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * 解析「单个 JSON 对象」。核心的 stdout 纪律是只允许一个信封，因此：
+ * 空输出、多文档、非对象一律拒绝，不做「取第一段 JSON」这种猜测。
+ */
+declare function parseJsonObject(text: string): Record<string, unknown>;
+declare function isVersionInfo(value: unknown): value is VersionInfo;
+declare function parseVersionInfo(text: string): VersionInfo;
+interface ParseRunOptions {
+    coreVersion: string;
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    dryRun: boolean;
+}
+/**
+ * 把核心 `run --json` 的 stdout 归一化成 `RunOutcome`。
+ *
+ * 两种形状的判别：有 `ipcSchema` 且 `command === 'run'` 就是契约 `RunResult`；
+ * 否则按当前核心的 `runOutput` 处理。两者都不像就直接 `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_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_SUPPORTED_DIGEST_SCHEMA: typeof SUPPORTED_DIGEST_SCHEMA;
+type ipc_State = State;
+type ipc_StateRun = 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 };
+}
+
+type Provider = string;
+type CommitMode = 'branch' | 'direct';
+type AuthMode = 'device' | 'pat' | 'gh';
+type Since = 'daily' | 'weekly';
+interface ModelSettings {
+    provider: Provider;
+    /** `direct` = 密钥经配置通道直传核心；`proxy` = 宿主 provider 无可导出密钥，走回环代理。 */
+    mode: 'direct' | 'proxy';
+    /** `mode=proxy` 时转发给哪个宿主 provider 路由（核心不认这个值）。 */
+    hostProvider: string;
+    baseURL: string;
+    model: string;
+    /** `ctx.credentials` 的引用名；密钥本身不写进 settings.json。 */
+    apiKeyRef: string;
+    temperature: number;
+    maxTokens: number;
+    allowDegraded: boolean;
+}
+interface RepoSettings {
+    path: string;
+    baseBranch: string;
+    remote: string;
+    commitMode: CommitMode;
+    authorName: string;
+    authorEmail: string;
+}
+interface PRSettings {
+    enabled: boolean;
+    titleTemplate: string;
+    autoMerge: boolean;
+    labels: string[];
+}
+interface GithubSettings {
+    authMode: AuthMode;
+    tokenRef: string;
+}
+interface TrendingSettings {
+    since: Since;
+    languages: string[];
+    topN: number;
+}
+interface OutputSettings {
+    dir: string;
+}
+interface ScheduleSettings {
+    enabled: boolean;
+    /** `HH:MM:SS`（本地墙钟，按 timezone 解释）。 */
+    time: string;
+    timezone: string;
+}
+interface Settings {
+    model: ModelSettings;
+    repo: RepoSettings;
+    pr: PRSettings;
+    github: GithubSettings;
+    trending: TrendingSettings;
+    output: OutputSettings;
+    schedule: ScheduleSettings;
+    /** 核心二进制覆盖；只在开发/排障时用，对应 TRENDING_DIGEST_CORE。 */
+    corePath: string;
+    /** 缓存缺失时是否自动从 Release 下载核心（首次运行需要联网）。 */
+    coreAutoDownload: boolean;
+}
+declare const DEFAULT_SETTINGS: Settings;
+/** 核心支持的 provider 默认端点（空字符串 = 必须由用户填）。 */
+declare const PROVIDER_BASE_URLS: Record<string, string>;
+declare const CORE_PROVIDERS: readonly ["deepseek", "openai-compatible"];
+/**
+ * 把任意来源的对象（磁盘上的旧版本、HTTP 请求体、CLI 导入）收敛成完整设置。
+ * 未知字段一律丢弃：settings.json 只有以下形状，避免旧版本字段悄悄生效。
+ */
+declare function normalizeSettings(input: unknown): Settings;
+interface Problem {
+    field: string;
+    code: string;
+    message: string;
+}
+declare function isValidTimezone(timezone: string): boolean;
+/**
+ * 设置校验。`providers` 来自核心 `version --json` 的 `supportedProviders`
+ * （拿不到时按 CORE_PROVIDERS 兜底）——provider 不在核心能力里必须当场拦下，
+ * 否则会变成运行时一个莫名其妙的模型错误。
+ */
+declare function validateSettings(settings: Settings, providers?: readonly string[]): Problem[];
+declare function effectiveBaseURL(model: ModelSettings): string;
+/** 核心 `config.Config` 的对象形状（随后序列化成 YAML）。 */
+interface CoreConfig {
+    model: {
+        provider: string;
+        name: string;
+        baseURL: string;
+        apiKey: string;
+        temperature: number;
+        maxTokens: number;
+        allowDegraded: boolean;
+    };
+    repo: {
+        path: string;
+        remote: string;
+        baseBranch: string;
+        authorName?: string;
+        authorEmail?: string;
+    };
+    pr: {
+        enabled: boolean;
+        titleTemplate: string;
+        labels: string[];
+        autoMerge: boolean;
+    };
+    trending: {
+        languages: string[];
+        since: string;
+        perLanguage: number;
+    };
+    output: {
+        dir: string;
+        branchPrefix: string;
+        retentionDays: number;
+    };
+}
+/**
+ * 生成核心配置。`apiKey` 单独传入：它只能来自宿主凭据或用户当次输入，
+ * 绝不来自 settings.json。
+ */
+declare function toCoreConfig(settings: Settings, apiKey: string, baseURLOverride?: string): CoreConfig;
+/**
+ * 极简 YAML 序列化：只覆盖「对象/数组/字符串/数字/布尔」。
+ * 字符串一律用 JSON 双引号形式——JSON 字符串是合法 YAML 标量，且能避免
+ * `: `、`#`、`- ` 之类的歧义；密钥因此不需要额外转义规则。
+ */
+declare function toYaml(value: unknown, depth?: number): string;
+
+type config_AuthMode = AuthMode;
+declare const config_CORE_PROVIDERS: typeof CORE_PROVIDERS;
+type config_CommitMode = CommitMode;
+type config_CoreConfig = CoreConfig;
+declare const config_DEFAULT_SETTINGS: typeof DEFAULT_SETTINGS;
+type config_GithubSettings = GithubSettings;
+type config_ModelSettings = ModelSettings;
+type config_OutputSettings = OutputSettings;
+declare const config_PROVIDER_BASE_URLS: typeof PROVIDER_BASE_URLS;
+type config_PRSettings = PRSettings;
+type config_Problem = Problem;
+type config_Provider = Provider;
+type config_RepoSettings = RepoSettings;
+type config_ScheduleSettings = ScheduleSettings;
+type config_Settings = Settings;
+type config_Since = Since;
+type config_TrendingSettings = TrendingSettings;
+declare const config_effectiveBaseURL: typeof effectiveBaseURL;
+declare const config_isValidTimezone: typeof isValidTimezone;
+declare const config_normalizeSettings: typeof normalizeSettings;
+declare const config_toCoreConfig: typeof toCoreConfig;
+declare const config_toYaml: typeof toYaml;
+declare const config_validateSettings: typeof validateSettings;
+declare namespace config {
+  export { type config_AuthMode as AuthMode, config_CORE_PROVIDERS as CORE_PROVIDERS, type config_CommitMode as CommitMode, type config_CoreConfig as CoreConfig, config_DEFAULT_SETTINGS as DEFAULT_SETTINGS, type config_GithubSettings as GithubSettings, type config_ModelSettings as ModelSettings, type config_OutputSettings as OutputSettings, config_PROVIDER_BASE_URLS as PROVIDER_BASE_URLS, type config_PRSettings as PRSettings, type config_Problem as Problem, type config_Provider as Provider, type config_RepoSettings as RepoSettings, type config_ScheduleSettings as ScheduleSettings, type config_Settings as Settings, type config_Since as Since, type config_TrendingSettings as TrendingSettings, config_effectiveBaseURL as effectiveBaseURL, config_isValidTimezone as isValidTimezone, config_normalizeSettings as normalizeSettings, config_toCoreConfig as toCoreConfig, config_toYaml as toYaml, config_validateSettings as validateSettings };
+}
+
+declare const PLUGIN_DIR_NAME = "github-trending";
+declare function homeDir(env?: NodeJS.ProcessEnv): string;
+declare function dshHome(env?: NodeJS.ProcessEnv): string;
+declare function dataDir(env?: NodeJS.ProcessEnv): string;
+declare function runsDir(env?: NodeJS.ProcessEnv): string;
+declare const SETTINGS_FILE = "settings.json";
+declare const STATE_FILE = "state.json";
+declare const HISTORY_FILE = "history.json";
+
+declare const paths_HISTORY_FILE: typeof HISTORY_FILE;
+declare const paths_PLUGIN_DIR_NAME: typeof PLUGIN_DIR_NAME;
+declare const paths_SETTINGS_FILE: typeof SETTINGS_FILE;
+declare const paths_STATE_FILE: typeof STATE_FILE;
+declare const paths_dataDir: typeof dataDir;
+declare const paths_dshHome: typeof dshHome;
+declare const paths_homeDir: typeof homeDir;
+declare const paths_runsDir: typeof runsDir;
+declare namespace paths {
+  export { paths_HISTORY_FILE as HISTORY_FILE, paths_PLUGIN_DIR_NAME as PLUGIN_DIR_NAME, paths_SETTINGS_FILE as SETTINGS_FILE, paths_STATE_FILE as STATE_FILE, paths_dataDir as dataDir, paths_dshHome as dshHome, paths_homeDir as homeDir, paths_runsDir as runsDir };
+}
+
+declare const HISTORY_LIMIT = 30;
+interface DigestIdentity {
+    date: string;
+    contentHash: string;
+    coreVersion: string;
+}
+interface RunRecord {
+    id: string;
+    at: string;
+    kind: 'run' | 'dry-run';
+    ok: boolean;
+    skipped: boolean;
+    /** `null` 表示没有错误。 */
+    errorCode?: string;
+    errorMessage?: string;
+    durationMs: number;
+    files: number;
+    contentHash?: string;
+    branch?: string;
+    commit?: string;
+    prUrl?: string;
+    coreVersion: string;
+    model: {
+        provider: string;
+        model: string;
+    };
+    languages: string[];
+    warnings: string[];
+    logFile?: string;
+}
+interface PendingPr {
+    url: string;
+    createdAt: string;
+}
+interface PluginState {
+    lastRunAt?: string;
+    lastDigest?: DigestIdentity;
+    lastResult?: RunRecord;
+    pendingPr?: PendingPr;
+}
+interface HistoryFile {
+    records: RunRecord[];
+}
+/** 原子写：同目录临时文件写完再 rename，权限 0600。 */
+declare function writeJsonAtomic(file: string, value: unknown): void;
+interface StoreOptions {
+    env?: NodeJS.ProcessEnv;
+    /** 直接指定目录，测试用。 */
+    dir?: string;
+}
+declare class Store {
+    readonly dir: string;
+    private readonly env;
+    constructor(options?: StoreOptions);
+    get settingsPath(): string;
+    get statePath(): string;
+    get historyPath(): string;
+    get logsPath(): string;
+    readSettings(): Settings;
+    writeSettings(settings: Settings): void;
+    readState(): PluginState;
+    writeState(state: PluginState): void;
+    readHistory(): RunRecord[];
+    /** 记录一次运行：历史裁剪到 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;
+}
+/** 运行 id：时间前缀便于按时间排序，随机后缀避免同毫秒撞车。 */
+declare function newRunId(now?: Date): string;
+
+type state_DigestIdentity = DigestIdentity;
+declare const state_HISTORY_LIMIT: typeof HISTORY_LIMIT;
+type state_HistoryFile = HistoryFile;
+type state_PendingPr = PendingPr;
+type state_PluginState = PluginState;
+type state_RunRecord = RunRecord;
+type state_Store = Store;
+declare const state_Store: typeof Store;
+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 };
+}
+
+interface CoreRelease {
+    /** `owner/repo`（GitHub）。 */
+    repo: string;
+    /** 不带 `v` 的版本号，例如 `0.1.0`；对应 tag `v0.1.0`。 */
+    version: string;
+}
+interface ReleaseDescriptor extends CoreRelease {
+    tag: string;
+    goos: string;
+    goarch: string;
+    asset: string;
+    url: string;
+    checksumsUrl: string;
+    cacheDir: string;
+    binaryPath: string;
+    cached: boolean;
+}
+/** 从本包的 package.json 读核心版本（`sync-contract --ref vX` 会同时更新它）。 */
+declare function readCoreRelease(pkg?: {
+    dsh?: {
+        core?: {
+            repo?: unknown;
+            version?: unknown;
+        };
+    };
+}): CoreRelease;
+/** Node 的 platform/arch → Go 的 GOOS/GOARCH（两个生态词汇不同，映射必须显式）。 */
+declare function goTarget(platform?: NodeJS.Platform, arch?: string): {
+    goos: string;
+    goarch: string;
+};
+declare function assetName(platform?: NodeJS.Platform, arch?: string): string;
+declare function describeRelease(release: CoreRelease, options?: {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    arch?: string;
+}): ReleaseDescriptor;
+/** 缓存里的二进制是否可信：可执行 + 与下载时记录的哈希一致。 */
+declare function verifyCached(binaryPath: string): {
+    ok: boolean;
+    reason?: string;
+};
+interface EnsureOptions {
+    release?: CoreRelease;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    arch?: string;
+    /** false 时只查缓存，不联网（设置页探测、离线诊断用）。 */
+    allowDownload?: boolean;
+    /** true 时忽略缓存重新下载（「重新下载核心」按钮）。 */
+    force?: boolean;
+    fetchImpl?: typeof fetch;
+    onProgress?: (event: {
+        phase: 'checksums' | 'download' | 'verify';
+        bytes?: number;
+        total?: number;
+    }) => void;
+}
+interface EnsureResult {
+    path: string;
+    source: 'cache' | 'download';
+    descriptor: ReleaseDescriptor;
+    sha256?: string;
+}
+/**
+ * 确保本地有一份可用的核心二进制。
+ * 缓存命中就不联网；`allowDownload=false` 时缓存缺失直接报错（不带网络副作用）。
+ */
+declare function ensureCore(options?: EnsureOptions): Promise<EnsureResult>;
+
+type release_CoreRelease = CoreRelease;
+type release_EnsureOptions = EnsureOptions;
+type release_EnsureResult = EnsureResult;
+type release_ReleaseDescriptor = ReleaseDescriptor;
+declare const release_assetName: typeof assetName;
+declare const release_describeRelease: typeof describeRelease;
+declare const release_ensureCore: typeof ensureCore;
+declare const release_goTarget: typeof goTarget;
+declare const release_readCoreRelease: typeof readCoreRelease;
+declare const release_verifyCached: typeof verifyCached;
+declare namespace release {
+  export { type release_CoreRelease as CoreRelease, type release_EnsureOptions as EnsureOptions, type release_EnsureResult as EnsureResult, type release_ReleaseDescriptor as ReleaseDescriptor, release_assetName as assetName, release_describeRelease as describeRelease, release_ensureCore as ensureCore, release_goTarget as goTarget, release_readCoreRelease as readCoreRelease, release_verifyCached as verifyCached };
+}
+
+interface CoreLocation {
+    path: string;
+    source: 'settings' | 'env' | 'cache' | 'download';
+    release?: CoreRelease;
+    tag?: string;
+    /** 本次调用是否真的下载了（用于日志与状态提示）。 */
+    downloaded?: boolean;
+    sha256?: string;
+}
+interface LocateOptions {
+    settings: Settings;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    arch?: string;
+    /** 默认 true；false 时只查缓存（设置页探测用）。 */
+    allowDownload?: boolean;
+    forceDownload?: boolean;
+    fetchImpl?: typeof fetch;
+    release?: CoreRelease;
+}
+declare function overridePath(settings: Settings, env?: NodeJS.ProcessEnv): {
+    path: string;
+    source: 'settings' | 'env';
+} | undefined;
+declare function locateCore(options: LocateOptions): Promise<CoreLocation>;
+/** 只读的 Release 视图：不联网、不创建目录，供设置页展示「有没有、从哪来」。 */
+declare function inspectRelease(settings: Settings, options?: {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    arch?: string;
+    release?: CoreRelease;
+}): {
+    descriptor?: ReleaseDescriptor;
+    override?: {
+        path: string;
+        source: 'settings' | 'env';
+    };
+    error?: string;
+};
+
+type locate_CoreLocation = CoreLocation;
+type locate_LocateOptions = LocateOptions;
+declare const locate_inspectRelease: typeof inspectRelease;
+declare const locate_locateCore: typeof locateCore;
+declare const locate_overridePath: typeof overridePath;
+declare namespace locate {
+  export { type locate_CoreLocation as CoreLocation, type locate_LocateOptions as LocateOptions, locate_inspectRelease as inspectRelease, locate_locateCore as locateCore, locate_overridePath as overridePath };
+}
+
+interface HandshakeResult {
+    version: VersionInfo;
+    corePath: string;
+    durationMs: number;
+    /** 核心声明的 provider 能力；设置页据此限制 provider 选择。 */
+    supportedProviders: string[];
+}
+declare const DEFAULT_PROVIDERS: readonly ["deepseek", "openai-compatible"];
+declare function handshake(core: CoreLocation, options?: {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<HandshakeResult>;
+
+declare const handshake$1_DEFAULT_PROVIDERS: typeof DEFAULT_PROVIDERS;
+type handshake$1_HandshakeResult = HandshakeResult;
+declare const handshake$1_handshake: typeof handshake;
+declare namespace handshake$1 {
+  export { handshake$1_DEFAULT_PROVIDERS as DEFAULT_PROVIDERS, type handshake$1_HandshakeResult as HandshakeResult, handshake$1_handshake as handshake };
+}
+
+type ChannelKind = 'fifo' | 'tmpfile';
+interface ConfigChannel {
+    kind: ChannelKind;
+    path: string;
+    /** spawn 之后调用：把内容送进通道。 */
+    publish(content: string): Promise<void>;
+    /** 无论成功失败都要调用；幂等。 */
+    dispose(): Promise<void>;
+}
+declare const WRITE_TIMEOUT_MS = 15000;
+/**
+ * 建配置通道。`preferFifo=false` 或平台不是 POSIX 或 mkfifo 失败时走临时文件。
+ */
+declare function openConfigChannel(options?: {
+    preferFifo?: boolean;
+    writeTimeoutMs?: number;
+}): Promise<ConfigChannel>;
+/** 清理通道所在目录（dispose 之后调用）。 */
+declare function removeChannelDir(channel: ConfigChannel): Promise<void>;
+
+type channel_ChannelKind = ChannelKind;
+type channel_ConfigChannel = ConfigChannel;
+declare const channel_WRITE_TIMEOUT_MS: typeof WRITE_TIMEOUT_MS;
+declare const channel_openConfigChannel: typeof openConfigChannel;
+declare const channel_removeChannelDir: typeof removeChannelDir;
+declare namespace channel {
+  export { type channel_ChannelKind as ChannelKind, type channel_ConfigChannel as ConfigChannel, channel_WRITE_TIMEOUT_MS as WRITE_TIMEOUT_MS, channel_openConfigChannel as openConfigChannel, channel_removeChannelDir as removeChannelDir };
+}
+
+interface ExecResult {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    aborted: boolean;
+    durationMs: number;
+}
+declare function sanitizedEnv(source?: NodeJS.ProcessEnv, extra?: Record<string, string | undefined>): Record<string, string>;
+interface ExecOptions {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    maxStdout?: number;
+    maxStderr?: number;
+}
+/**
+ * 执行一次短命令并收集输出（握手、共存探测都走这里）。
+ * 超时与取消都先 SIGTERM、3 s 后 SIGKILL——核心是单进程，不需要 process group。
+ */
+declare function execCapture(file: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
+
+type exec_ExecOptions = ExecOptions;
+type exec_ExecResult = ExecResult;
+declare const exec_execCapture: typeof execCapture;
+declare const exec_sanitizedEnv: typeof sanitizedEnv;
+declare namespace exec {
+  export { type exec_ExecOptions as ExecOptions, type exec_ExecResult as ExecResult, exec_execCapture as execCapture, exec_sanitizedEnv as sanitizedEnv };
+}
+
+declare const DEFAULT_RUN_TIMEOUT_MS = 120000;
+interface RunCoreOptions {
+    core: CoreLocation;
+    version: VersionInfo;
+    settings: Settings;
+    /** 模型密钥；只进配置通道，不进 argv/env/日志。 */
+    apiKey: string;
+    /** GitHub token；核心只从 env 读（GITHUB_TOKEN/GH_TOKEN）。 */
+    token?: string;
+    date?: string;
+    dryRun: boolean;
+    /** 回环代理地址：覆盖配置里的 model.baseURL（代理模式专用）。 */
+    baseURLOverride?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    onStderr?: (line: string) => void;
+    /** 已知明文，用于日志脱敏。 */
+    secrets?: Array<string | undefined>;
+}
+interface RunCoreResult {
+    outcome: RunOutcome;
+    channelKind: ChannelKind;
+    stderr: string;
+    exitCode: number | null;
+}
+declare function buildCoreArgs(channelPath: string, options: {
+    dryRun: boolean;
+    date?: string;
+}): string[];
+declare function runCore(options: RunCoreOptions): Promise<RunCoreResult>;
+
+declare const run_DEFAULT_RUN_TIMEOUT_MS: typeof DEFAULT_RUN_TIMEOUT_MS;
+type run_RunCoreOptions = RunCoreOptions;
+type run_RunCoreResult = RunCoreResult;
+declare const run_buildCoreArgs: typeof buildCoreArgs;
+declare const run_runCore: typeof runCore;
+declare namespace run {
+  export { run_DEFAULT_RUN_TIMEOUT_MS as DEFAULT_RUN_TIMEOUT_MS, type run_RunCoreOptions as RunCoreOptions, type run_RunCoreResult as RunCoreResult, run_buildCoreArgs as buildCoreArgs, run_runCore as runCore };
+}
+
+/** Release 分发下的核心视图：用户一眼能看出「版本、下没下、从哪来」。 */
+interface ReleaseStatus {
+    repo: string;
+    tag: string;
+    asset: string;
+    url: string;
+    checksumsUrl: string;
+    cacheDir: string;
+    binaryPath: string;
+    cached: boolean;
+}
+interface CoreStatus {
+    state: 'ready' | 'unavailable' | 'incompatible';
+    path?: string;
+    source?: CoreLocation['source'];
+    /** Release 分发状态（有覆盖路径时只有 override，没有 release）。 */
+    release?: ReleaseStatus;
+    override?: {
+        path: string;
+        source: 'settings' | 'env';
+    };
+    download: {
+        state: 'cached' | 'missing' | 'override';
+        reason?: string;
+    };
+    version?: string;
+    commit?: string;
+    ipcSchema?: number;
+    digestSchema?: number;
+    supportedProviders: string[];
+    code?: string;
+    message?: string;
+    hint?: string;
+    checkedAt: string;
+    durationMs?: number;
+}
+interface CoexistenceStatus {
+    found: boolean;
+    path?: string;
+    version?: string;
+    ipcSchema?: number;
+    digestSchema?: number;
+    compatible?: boolean;
+    message?: string;
+}
+/** 在 PATH 里找同名 CLI（只用于共存提示，绝不用于运行）。 */
+declare function findOnPath(command: string, env?: NodeJS.ProcessEnv): string | undefined;
+declare function inspectCore(settings: Settings, options?: {
+    env?: NodeJS.ProcessEnv;
+    fresh?: boolean;
+}): Promise<CoreStatus>;
+/**
+ * 共存检测（FR-P-15 / AC-P-13）：PATH 上有 `trendradar` 就读它的版本，只提示不切换。
+ * 若命中的正是本插件平台包里的二进制（比如用户把它加进了 PATH），不算共存。
+ */
+declare function detectCoexistence(ownPath: string | undefined, options?: {
+    env?: NodeJS.ProcessEnv;
+    fresh?: boolean;
+}): Promise<CoexistenceStatus>;
+
+type core_CoexistenceStatus = CoexistenceStatus;
+type core_CoreStatus = CoreStatus;
+type core_ReleaseStatus = ReleaseStatus;
+declare const core_detectCoexistence: typeof detectCoexistence;
+declare const core_findOnPath: typeof findOnPath;
+declare const core_inspectCore: typeof inspectCore;
+declare namespace core {
+  export { type core_CoexistenceStatus as CoexistenceStatus, type core_CoreStatus as CoreStatus, type core_ReleaseStatus as ReleaseStatus, core_detectCoexistence as detectCoexistence, core_findOnPath as findOnPath, core_inspectCore as inspectCore };
+}
+
+/**
+ * 凭据解析：一律「按操作解析」，不缓存明文（ADR D-04 约束 2）。
+ *
+ * 宿主的凭据服务只回答被问到的引用，**没有枚举**——所以这里的 ref 只来自两处：
+ * 设置里用户选定的 `model.apiKeyRef` / `github.tokenRef`，以及 provider 目录声明的
+ * `nativeAuth.env`。不存在「猜一个 ref 试试」。
+ */
+interface CredentialDescription {
+    configured: boolean;
+    source?: string;
+    writable: boolean;
+}
+interface ResolvedSecret {
+    value?: string;
+    source?: string;
+}
+interface CredentialServices {
+    describe?: (ref: string) => Promise<CredentialDescription> | CredentialDescription;
+    resolve?: (ref: string) => Promise<ResolvedSecret | undefined | null> | ResolvedSecret | undefined | null;
+    set?: (ref: string, value: string) => Promise<unknown> | unknown;
+}
+declare function credentialServices(get: (name: string) => unknown): CredentialServices | undefined;
+declare function describeRef(services: CredentialServices | undefined, ref: string, env?: NodeJS.ProcessEnv): Promise<CredentialDescription>;
+declare function resolveRef(services: CredentialServices | undefined, ref: string, env?: NodeJS.ProcessEnv): Promise<ResolvedSecret>;
+/** GitHub token：按 authMode 取，`gh` 模式读本机 gh 的登录态。 */
+declare function resolveGithubToken(services: CredentialServices | undefined, authMode: 'device' | 'pat' | 'gh', tokenRef: string, deps?: {
+    env?: NodeJS.ProcessEnv;
+    execGh?: () => Promise<string | undefined>;
+}): Promise<{
+    token?: string;
+    source: string;
+}>;
+
+type credentials_CredentialDescription = CredentialDescription;
+type credentials_CredentialServices = CredentialServices;
+type credentials_ResolvedSecret = ResolvedSecret;
+declare const credentials_credentialServices: typeof credentialServices;
+declare const credentials_describeRef: typeof describeRef;
+declare const credentials_resolveGithubToken: typeof resolveGithubToken;
+declare const credentials_resolveRef: typeof resolveRef;
+declare namespace credentials {
+  export { type credentials_CredentialDescription as CredentialDescription, type credentials_CredentialServices as CredentialServices, type credentials_ResolvedSecret as ResolvedSecret, credentials_credentialServices as credentialServices, credentials_describeRef as describeRef, credentials_resolveGithubToken as resolveGithubToken, credentials_resolveRef as resolveRef };
+}
+
+/**
+ * 从宿主的 provider 目录快速填充模型配置（FR-P-03 / AC-P-03）。
+ *
+ * 三种认证形态的判定，只用宿主公开的两个目录：
+ *   - `listProviders()`：当前**活着**的路由（id + 名称）；
+ *   - `listConfigurableProviders()`：连**休眠**路由一起，带 `defaultBaseURL` 与 `nativeAuth`
+ *     （认证读哪些环境变量、是否支持已存的 OAuth 登录）。
+ *
+ * 由此得到三种形态：
+ *   1. `nativeAuth.env` 里有已配置的引用 → `direct`（密钥可解析，经配置通道直传）；
+ *   2. `nativeAuth.oauth === true` 且无可导出密钥 → `proxy`（回环代理转发 `ctx.llm`）；
+ *   3. 都没有 → `missing`（界面要求用户手动填）。
+ *
+ * 这里**不写任何配置**：只产出候选，由用户确认后 `/config` 落盘（禁止静默复制）。
+ */
+
+interface LlmModelCandidate {
+    id: string;
+    name: string;
+}
+interface LlmProviderCandidate {
+    /** 宿主 provider 路由 id。 */
+    id: string;
+    name: string;
+    /** 该路由的默认端点（宿主声明，可能为空）。 */
+    baseURL: string;
+    models: LlmModelCandidate[];
+    credential: {
+        /** 选中的凭据引用名（`direct` 时非空）。 */
+        ref?: string;
+        /** 该路由声明的环境变量名。 */
+        env: string[];
+        configured: boolean;
+        oauth: boolean;
+        mode: 'direct' | 'proxy' | 'missing';
+        source?: string;
+    };
+    /** 映射到核心能接受的 provider 名。 */
+    coreProvider: string;
+}
+interface LlmProviderInfo {
+    id: string;
+    name: string;
+}
+interface LlmConfigurableProvider {
+    provider: string;
+    displayName?: string;
+    defaultBaseURL?: string;
+    nativeAuth?: {
+        env?: readonly string[];
+        oauth?: boolean;
+    };
+}
+interface LlmServices {
+    listProviders?: () => LlmProviderInfo[];
+    listModels?: (provider: string) => Promise<Array<{
+        id?: string;
+        name?: string;
+    }>>;
+    listConfigurableProviders?: () => LlmConfigurableProvider[];
+}
+declare function llmServices(get: (name: string) => unknown): LlmServices | undefined;
+/** 宿主 provider → 核心 provider。核心只认 deepseek / openai-compatible。 */
+declare function coreProviderFor(providerId: string): string;
+interface CandidateOptions {
+    llm: LlmServices | undefined;
+    credentials: CredentialServices | undefined;
+    env?: NodeJS.ProcessEnv;
+}
+declare function listProviderCandidates(options: CandidateOptions): Promise<LlmProviderCandidate[]>;
+/**
+ * 把候选落成模型设置。`mode: 'proxy'` 时清空 baseURL 与 apiKeyRef——
+ * 端点由插件在运行时注入回环代理地址，留存旧值只会误导。
+ */
+declare function applyCandidate(settings: Settings, candidate: LlmProviderCandidate, modelId: string): Settings;
+/** 运行前解析模型密钥：`direct` 走凭据，`proxy` 不需要密钥。 */
+declare function resolveModelKey(settings: Settings, credentials: CredentialServices | undefined, env?: NodeJS.ProcessEnv): Promise<{
+    apiKey?: string;
+    mode: 'direct' | 'proxy';
+    source?: string;
+}>;
+
+type quickfill_CandidateOptions = CandidateOptions;
+type quickfill_LlmModelCandidate = LlmModelCandidate;
+type quickfill_LlmProviderCandidate = LlmProviderCandidate;
+type quickfill_LlmServices = LlmServices;
+declare const quickfill_applyCandidate: typeof applyCandidate;
+declare const quickfill_coreProviderFor: typeof coreProviderFor;
+declare const quickfill_credentialServices: typeof credentialServices;
+declare const quickfill_listProviderCandidates: typeof listProviderCandidates;
+declare const quickfill_llmServices: typeof llmServices;
+declare const quickfill_resolveModelKey: typeof resolveModelKey;
+declare namespace quickfill {
+  export { type quickfill_CandidateOptions as CandidateOptions, type quickfill_LlmModelCandidate as LlmModelCandidate, type quickfill_LlmProviderCandidate as LlmProviderCandidate, type quickfill_LlmServices as LlmServices, quickfill_applyCandidate as applyCandidate, quickfill_coreProviderFor as coreProviderFor, quickfill_credentialServices as credentialServices, quickfill_listProviderCandidates as listProviderCandidates, quickfill_llmServices as llmServices, quickfill_resolveModelKey as resolveModelKey };
+}
+
+/**
+ * 模型连通性预检（FR-P-02 / §13 风险表：保存前预检）。
+ *
+ * 只做一次最小请求，把「能不能连、密钥对不对、模型在不在」区分开：
+ *   - 401/403 → MODEL_UNAUTHORIZED
+ *   - 404 / model not found → MODEL_NOT_FOUND
+ *   - 429 → MODEL_RATE_LIMITED（算连通）
+ *   - 超时 / 网络错误 → MODEL_FAILED
+ *
+ * 代理模式不走 HTTP，直接用 `ctx.llm.stream` 发一个 1 token 的请求。
+ */
+
+interface PreflightResult {
+    ok: boolean;
+    code?: string;
+    message?: string;
+    hint?: string;
+    area?: string;
+    durationMs: number;
+    endpoint?: string;
+    mode: 'direct' | 'proxy';
+}
+declare function preflightModel(options: {
+    settings: Settings;
+    credentials: CredentialServices | undefined;
+    llm: LlmServices | undefined;
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: typeof fetch;
+}): Promise<PreflightResult>;
+
+type preflight_PreflightResult = PreflightResult;
+declare const preflight_preflightModel: typeof preflightModel;
+declare namespace preflight {
+  export { type preflight_PreflightResult as PreflightResult, preflight_preflightModel as preflightModel };
+}
+
+interface StreamChunkLike {
+    type?: string;
+    text?: string;
+    reason?: {
+        kind?: string;
+        failure?: {
+            code?: string;
+            message?: string;
+        };
+    };
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+}
+interface LlmLike {
+    stream(options: Record<string, unknown>): AsyncIterable<StreamChunkLike>;
+}
+interface ProxyOptions {
+    llm: LlmLike;
+    provider: string;
+    model: string;
+    temperature?: number;
+    maxTokens?: number;
+    timeoutMs?: number;
+}
+interface ProxyHandle {
+    url: string;
+    token: string;
+    port: number;
+    requests: number;
+    close(): Promise<void>;
+}
+interface ChatMessage {
+    role?: string;
+    content?: unknown;
+}
+/** 把 OpenAI 的 messages 折成「system + 单个 user」。核心只用单轮，超出部分并入 user。 */
+declare function foldMessages(messages: ChatMessage[]): {
+    system: string;
+    user: string;
+};
+declare function startProxy(options: ProxyOptions): Promise<ProxyHandle>;
+
+type proxy_LlmLike = LlmLike;
+type proxy_ProxyHandle = ProxyHandle;
+type proxy_ProxyOptions = ProxyOptions;
+declare const proxy_foldMessages: typeof foldMessages;
+declare const proxy_startProxy: typeof startProxy;
+declare namespace proxy {
+  export { type proxy_LlmLike as LlmLike, type proxy_ProxyHandle as ProxyHandle, type proxy_ProxyOptions as ProxyOptions, proxy_foldMessages as foldMessages, proxy_startProxy as startProxy };
+}
+
+interface RunSummary {
+    id: string;
+    ok: boolean;
+    skipped: boolean;
+    dryRun: boolean;
+    date?: string;
+    durationMs: number;
+    coreVersion: string;
+    files: number;
+    contentHash?: string;
+    branch?: string;
+    prUrl?: string;
+    error?: {
+        code: string;
+        message: string;
+        hint: string;
+        area: string;
+        retriable: boolean;
+        inferred?: boolean;
+    };
+    warnings: string[];
+    logFile?: string;
+    channel?: 'fifo' | 'tmpfile';
+    proxy?: boolean;
+    /** 核心从哪来：env/settings 覆盖、缓存、还是本次下载。 */
+    coreSource?: 'settings' | 'env' | 'cache' | 'download';
+    coreTag?: string;
+}
+interface RunRequestOptions {
+    dryRun?: boolean;
+    date?: string;
+    trigger: 'manual' | 'schedule' | 'tool';
+}
+interface RunnerDeps {
+    store: Store;
+    get: (name: string) => unknown;
+    env?: NodeJS.ProcessEnv;
+    /** 运行结束（成功或失败）后回调，用于刷新调度/界面缓存。 */
+    onFinished?: (summary: RunSummary) => void;
+}
+declare class Runner {
+    private active;
+    private readonly deps;
+    constructor(deps: RunnerDeps);
+    get running(): {
+        id: string;
+        startedAt: string;
+    } | undefined;
+    cancel(): boolean;
+    run(options: RunRequestOptions): Promise<RunSummary>;
+    private summarize;
+    private failureSummary;
+    /** 写历史与状态；同一天的 skipped 运行不覆盖 lastDigest。 */
+    private record;
+    /** 给设置页/工具用的「核心现在什么状态」。 */
+    coreStatus(fresh?: boolean): Promise<CoreStatus>;
+}
+
+type runner_RunRequestOptions = RunRequestOptions;
+type runner_RunSummary = RunSummary;
+type runner_Runner = Runner;
+declare const runner_Runner: typeof Runner;
+type runner_RunnerDeps = RunnerDeps;
+declare namespace runner {
+  export { type runner_RunRequestOptions as RunRequestOptions, type runner_RunSummary as RunSummary, runner_Runner as Runner, type runner_RunnerDeps as RunnerDeps };
+}
+
+/**
+ * 调度（FR-P-08 / 规格 §9）。
+ *
+ * 规格原本设想「复用宿主 schedule 服务」，但实测：宿主的 `ctx.schedule` 是 **会话本地**
+ * 的提醒（rc.5 才引入，create 需要 sessionId，冷会话不投递），而本插件的运行完全不依赖会话。
+ * 因此这里实现规格 §9 已经写明的兜底：宿主 `timer` 服务（或 `setInterval`）60 s tick、
+ * 按 IANA 时区判当日、6 h 内补跑、同日不重复。
+ *
+ * 「下一次运行」也由同一份时区算术给出，界面与工具都用它。
+ */
+
+interface ScheduleConfig {
+    enabled: boolean;
+    time: string;
+    timezone: string;
+}
+/** 目标时区的墙上时间 → UTC 时刻（按 DST 修正一次，够用且可测）。 */
+declare function zonedTimeToUtc(year: number, month: number, day: number, hour: number, minute: number, second: number, timezone: string): Date;
+declare function parseClock(time: string): {
+    hour: number;
+    minute: number;
+    second: number;
+};
+/** 目标时区下的本地日期串（YYYY-MM-DD）。 */
+declare function zonedDateString(date: Date, timezone: string): string;
+/** 下一次应当运行的时刻（严格晚于 now）。 */
+declare function nextOccurrence(now: Date, schedule: ScheduleConfig): Date;
+/** 今天这一次是否已过点且在补跑窗口内。 */
+declare function isDue(now: Date, schedule: ScheduleConfig): boolean;
+interface SchedulerDeps {
+    store: Store;
+    run: (trigger: 'schedule') => Promise<unknown>;
+    isRunning: () => boolean;
+    getTimer: () => {
+        interval?: (fn: () => void, ms: number) => unknown;
+        timeout?: (fn: () => void, ms: number) => unknown;
+    } | undefined;
+    onError?: (error: unknown) => void;
+}
+declare class Scheduler {
+    private readonly deps;
+    private timerHandle;
+    private stopped;
+    private lastFiredFor;
+    constructor(deps: SchedulerDeps);
+    start(): void;
+    stop(): void;
+    /** 公开给测试：判断此刻是否该跑，并按需触发一次。 */
+    tick(now?: Date): Promise<'skipped' | 'ran' | 'disabled' | 'busy'>;
+    private readSchedule;
+    /** 下一次运行（禁用时为 undefined）。 */
+    next(): Date | undefined;
+    describe(state: PluginState, now?: Date): {
+        enabled: boolean;
+        time: string;
+        timezone: string;
+        nextRunAt?: string;
+        lastRunDate?: string;
+        catchUpMinutes: number;
+        source: 'timer';
+    };
+}
+
+type schedule_ScheduleConfig = ScheduleConfig;
+type schedule_Scheduler = Scheduler;
+declare const schedule_Scheduler: typeof Scheduler;
+type schedule_SchedulerDeps = SchedulerDeps;
+declare const schedule_isDue: typeof isDue;
+declare const schedule_nextOccurrence: typeof nextOccurrence;
+declare const schedule_parseClock: typeof parseClock;
+declare const schedule_zonedDateString: typeof zonedDateString;
+declare const schedule_zonedTimeToUtc: typeof zonedTimeToUtc;
+declare namespace schedule {
+  export { type schedule_ScheduleConfig as ScheduleConfig, schedule_Scheduler as Scheduler, type schedule_SchedulerDeps as SchedulerDeps, schedule_isDue as isDue, schedule_nextOccurrence as nextOccurrence, schedule_parseClock as parseClock, schedule_zonedDateString as zonedDateString, schedule_zonedTimeToUtc as zonedTimeToUtc };
+}
+
+/**
+ * Host HTTP 面：`/api/morehao/github-trending/*`。
+ *
+ * 只有客户端 bundle 会调它。安全基线沿用宿主插件的通行做法：
+ *   - 一律要求自定义头 `x-dsh-github-trending: 1`（跨源请求会先触发预检，等于顺带挡 CSRF）；
+ *   - 响应 `no-store`；
+ *   - 没有任何路由返回密钥明文：只返回「已配置/来源」。
+ */
+
+declare const ROUTE_PREFIX = "/api/morehao/github-trending";
+declare const HEADER = "x-dsh-github-trending";
+interface RouteDeps {
+    store: Store;
+    runner: Runner;
+    scheduler: Scheduler;
+    get: (name: string) => unknown;
+    env?: NodeJS.ProcessEnv;
+    version: string;
+    logger?: (event: string, data?: Record<string, unknown>) => void;
+}
+declare function createRoutes(deps: RouteDeps): (request: http.IncomingMessage, response: http.ServerResponse) => Promise<void>;
+
+declare const routes_HEADER: typeof HEADER;
+declare const routes_ROUTE_PREFIX: typeof ROUTE_PREFIX;
+type routes_RouteDeps = RouteDeps;
+declare const routes_createRoutes: typeof createRoutes;
+declare namespace routes {
+  export { routes_HEADER as HEADER, routes_ROUTE_PREFIX as ROUTE_PREFIX, type routes_RouteDeps as RouteDeps, routes_createRoutes as createRoutes };
+}
+
+interface ImportCandidate {
+    path: string;
+    exists: boolean;
+}
+interface ImportResult {
+    ok: boolean;
+    source?: string;
+    settings?: Settings;
+    imported: string[];
+    skippedSecrets: string[];
+    problems: string[];
+}
+/** 可能的 CLI 配置位置（按顺序取第一个存在的）。 */
+declare function cliConfigCandidates(env?: NodeJS.ProcessEnv, home?: string): string[];
+type YamlValue = string | number | boolean | string[] | YamlMap;
+interface YamlMap {
+    [key: string]: YamlValue;
+}
+/** 只支持两层缩进 map + 标量/flow 数组；其它形状直接抛错。 */
+declare function parseSimpleYaml(text: string): YamlMap;
+declare function importFromCli(filePath: string, base?: Settings): ImportResult;
+/** 找到第一个存在的 CLI 配置并导入。 */
+declare function importFirstAvailable(env?: NodeJS.ProcessEnv, base?: Settings): ImportResult;
+
+type importCli_ImportCandidate = ImportCandidate;
+type importCli_ImportResult = ImportResult;
+declare const importCli_cliConfigCandidates: typeof cliConfigCandidates;
+declare const importCli_importFirstAvailable: typeof importFirstAvailable;
+declare const importCli_importFromCli: typeof importFromCli;
+declare const importCli_parseSimpleYaml: typeof parseSimpleYaml;
+declare namespace importCli {
+  export { type importCli_ImportCandidate as ImportCandidate, type importCli_ImportResult as ImportResult, importCli_cliConfigCandidates as cliConfigCandidates, importCli_importFirstAvailable as importFirstAvailable, importCli_importFromCli as importFromCli, importCli_parseSimpleYaml as parseSimpleYaml };
+}
+
+/**
+ * 两个对外工具：`trending_run` / `trending_history`（规格 §8）。
+ *
+ * 工具名是**稳定对外接口**：一旦发布不再改名；需要新能力时新增工具。
+ * 参数方言用宿主 `dsh-tools` 的「内联 required: true」，输出用标准 JSON Schema。
+ */
+
+declare function createTrendingRunTool(runner: Runner): {
+    name: string;
+    description: string;
+    parameters: {
+        dryRun: {
+            type: string;
+            description: string;
+        };
+        date: {
+            type: string;
+            description: string;
+        };
+    };
+    output: {
+        schema: {
+            readonly type: "object";
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly id: {
+                    readonly type: "string";
+                };
+                readonly ok: {
+                    readonly type: "boolean";
+                };
+                readonly skipped: {
+                    readonly type: "boolean";
+                };
+                readonly dryRun: {
+                    readonly type: "boolean";
+                };
+                readonly durationMs: {
+                    readonly type: "number";
+                };
+                readonly coreVersion: {
+                    readonly type: "string";
+                };
+                readonly files: {
+                    readonly type: "number";
+                };
+                readonly contentHash: {
+                    readonly type: "string";
+                };
+                readonly branch: {
+                    readonly type: "string";
+                };
+                readonly prUrl: {
+                    readonly type: "string";
+                };
+                readonly errorCode: {
+                    readonly type: "string";
+                };
+                readonly errorMessage: {
+                    readonly type: "string";
+                };
+                readonly errorHint: {
+                    readonly type: "string";
+                };
+                readonly warnings: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly markdown: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["ok", "markdown"];
+        };
+        render: (_args: unknown, value: {
+            markdown?: string;
+        }) => {
+            type: string;
+            text: string;
+        }[];
+    };
+    execute(args?: {
+        dryRun?: boolean;
+        date?: string;
+    }, exec?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        warnings: string[];
+        markdown: string;
+        errorCode?: string | undefined;
+        errorMessage?: string | undefined;
+        errorHint?: string | undefined;
+        prUrl?: string | undefined;
+        branch?: string | undefined;
+        contentHash?: string | undefined;
+        id: string;
+        ok: boolean;
+        skipped: boolean;
+        dryRun: boolean;
+        durationMs: number;
+        coreVersion: string;
+        files: number;
+    }>;
+};
+declare function createTrendingHistoryTool(store: Store, scheduler: Scheduler): {
+    name: string;
+    description: string;
+    parameters: {
+        limit: {
+            type: string;
+            description: string;
+        };
+    };
+    output: {
+        schema: {
+            readonly type: "object";
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly lastRunAt: {
+                    readonly type: "string";
+                };
+                readonly nextRunAt: {
+                    readonly type: "string";
+                };
+                readonly coreVersion: {
+                    readonly type: "string";
+                };
+                readonly model: {
+                    readonly type: "string";
+                };
+                readonly provider: {
+                    readonly type: "string";
+                };
+                readonly pendingPr: {
+                    readonly type: "string";
+                };
+                readonly records: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly additionalProperties: true;
+                        readonly properties: {
+                            readonly at: {
+                                readonly type: "string";
+                            };
+                            readonly ok: {
+                                readonly type: "boolean";
+                            };
+                            readonly skipped: {
+                                readonly type: "boolean";
+                            };
+                            readonly errorCode: {
+                                readonly type: "string";
+                            };
+                            readonly durationMs: {
+                                readonly type: "number";
+                            };
+                            readonly files: {
+                                readonly type: "number";
+                            };
+                            readonly branch: {
+                                readonly type: "string";
+                            };
+                            readonly prUrl: {
+                                readonly type: "string";
+                            };
+                            readonly coreVersion: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                };
+                readonly markdown: {
+                    readonly type: "string";
+                };
+            };
+            readonly required: readonly ["markdown"];
+        };
+        render: (_args: unknown, value: {
+            markdown?: string;
+        }) => {
+            type: string;
+            text: string;
+        }[];
+    };
+    execute(args?: {
+        limit?: number;
+    }): Promise<{
+        records: RunRecord[];
+        markdown: string;
+        pendingPr?: string | undefined;
+        coreVersion: string;
+        model: string;
+        provider: string;
+        nextRunAt?: string | undefined;
+        lastRunAt?: string | undefined;
+    }>;
+};
+
+declare const tools_createTrendingHistoryTool: typeof createTrendingHistoryTool;
+declare const tools_createTrendingRunTool: typeof createTrendingRunTool;
+declare namespace tools {
+  export { tools_createTrendingHistoryTool as createTrendingHistoryTool, tools_createTrendingRunTool as createTrendingRunTool };
+}
+
+export { channel, config, core, credentials, errors, exec, handshake$1 as handshake, importCli, ipc, locate, paths, preflight, proxy, quickfill, release, routes, run, runner, schedule, state, tools };