@vetta-org/plugin-sdk 0.0.1 → 0.0.3

package/dist/index.d.ts

@@ -7,7 +7,7 @@ import type { ComponentType, ReactNode } from "react";
  * 否则宿主回传的 scenario 与此 union 不一致会触发编译错误（即为期望的漂移护栏）。
  */
 export type ConversationScenario = "im-claw" | "conversation" | "project" | "batch" | "automation" | "kb-processing" | "cli";
-export type PluginPermission = "ui.slot.global" | "ui.slot.file-preview" | "ui.slot.activity-tab" | "ui.slot.input-action" | "ui.slot.message" | "ui.slot.tool-call" | "ui.slot.turn-card" | "agent.session.read" | "agent.session.write" | "agent.command.run" | "agent.systemPrompt.read" | "agent.systemPrompt.write" | "agent.systemPrompt.fullControl" | "agent.skills.control" | "agent.mcp.control" | "agent.tools.control" | "agent.tools.register" | "agent.toolHandler.execute" | "agent.state.read" | "agent.state.write" | "agent.continuation.register" | "agent.runtime.configure" | "fs.read" | "fs.write" | "network.fetch" | "images.generate" | "settings.read" | "settings.write";
+export type PluginPermission = "ui.slot.global" | "ui.slot.file-preview" | "ui.slot.activity-tab" | "ui.slot.input-action" | "ui.slot.message" | "ui.slot.tool-call" | "ui.slot.turn-card" | "agent.session.read" | "agent.session.write" | "agent.command.run" | "agent.systemPrompt.read" | "agent.systemPrompt.write" | "agent.systemPrompt.fullControl" | "agent.skills.control" | "agent.mcp.control" | "agent.tools.control" | "agent.tools.register" | "agent.toolHandler.execute" | "agent.state.read" | "agent.state.write" | "agent.continuation.register" | "agent.runtime.configure" | "app.actions.register" | "app.actionHandler.execute" | "fs.read" | "fs.write" | "network.fetch" | "images.generate" | "settings.read" | "settings.write";
 /**
  * MCP server config declared inside a plugin (stdio or http). Relative paths in
  * stdio `command`/`args`/`cwd` are resolved against the plugin root at contribute time.
@@ -24,6 +24,8 @@ export type PluginMcpServerConfig = {
     debug?: boolean;
     displayName?: string;
     description?: string;
+    /** 该 server 的工具允许出现的工作模式 slug（agent_mode 轴，缺省/空 = 通用）。见 ADR-0046。 */
+    agent_mode?: string | string[];
 } | {
     type: "http";
     url: string;
@@ -37,6 +39,8 @@ export type PluginMcpServerConfig = {
     debug?: boolean;
     displayName?: string;
     description?: string;
+    /** 该 server 的工具允许出现的工作模式 slug（agent_mode 轴，缺省/空 = 通用）。见 ADR-0046。 */
+    agent_mode?: string | string[];
 };
 export interface PluginAgentManifest {
     systemPrompt?: {
@@ -379,6 +383,37 @@ export interface PluginUiApi {
      * The host owns the navigation; the plugin only asks to jump there.
      */
     openPluginSettings(): void;
+    /**
+     * Show a global toast in the host UI (bottom-right). No permission required.
+     * Prefer this over swallowing errors into opaque UI copy: pass `error` so
+     * the host attaches a one-click "copy stack" action for the user.
+     *
+     * Capture `ctx.ui.notify` in `activate` if React components need it
+     * (components do not receive `ctx`).
+     */
+    notify(options: PluginNotifyOptions): void;
+}
+/**
+ * Options for {@link PluginUiApi.notify}. Surfaces a host toast so users can
+ * see plugin failures without opening DevTools.
+ */
+export interface PluginNotifyOptions {
+    /** Toast body. Required even when `error` is set (user-facing summary). */
+    message: string;
+    /** Defaults to plugin display name when omitted. */
+    title?: string;
+    /** Defaults to `"info"`; when `error` is set and variant omitted, host uses `"error"`. */
+    variant?: "info" | "success" | "warning" | "error";
+    /**
+     * Optional failure cause. Host formats message + stack and adds a
+     * "复制堆栈" action so the user can paste it into bug reports / chat.
+     */
+    error?: unknown;
+    /**
+     * Auto-dismiss delay in ms. `0` keeps the toast until dismissed.
+     * Defaults: sticky (`0`) when `error` is present, otherwise host default (~4s).
+     */
+    durationMs?: number;
 }
 export interface ConversationState {
     /** Active session runtimeId, or null when no conversation is active. */
@@ -447,6 +482,8 @@ export interface PluginAgentToolRegistration<TInput = unknown> {
     scope_use?: readonly ConversationScenario[];
     /** 需要的会话能力 slug（如 "knowledge"）；全满足才激活。一般插件无需设置。 */
     requires?: string[];
+    /** 允许该工具出现的工作模式 slug（agent_mode 轴，如 "work"/"coding"）。缺省/空 = 通用。见 ADR-0046。 */
+    agent_mode?: readonly string[];
     context?: {
         conversation?: "summary" | "messages";
     };
@@ -627,6 +664,585 @@ export interface PluginContinuationRegistration {
     };
     handler: PluginContinuationHandler;
 }
+export type PluginAppActionEffect = "read" | "write" | "execute";
+export interface PluginAppActionExample<TInput = unknown> {
+    description: string;
+    input: TInput;
+}
+export interface PluginAppActionHandlerContext<TInput = unknown> {
+    invocationId: string;
+    plugin: {
+        id: string;
+        actionId: string;
+        settings: Readonly<Record<string, unknown>>;
+    };
+    input: TInput;
+    signal: AbortSignal;
+}
+export type PluginAppActionHandler<TInput = unknown> = (context: PluginAppActionHandlerContext<TInput>) => unknown | Promise<unknown>;
+export type PluginAppActionReadyHandler<TInput = unknown> = (context: PluginAppActionHandlerContext<TInput>) => void | Promise<void>;
+/** 插件 Action 向宿主返回稳定错误码与可序列化详情。 */
+export declare class PluginAppActionError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(code: string, message: string, details?: unknown);
+}
+export interface PluginAppActionApprovalPresentation {
+    id: string;
+    title: string;
+    description: string;
+}
+export interface PluginAppActionApproval {
+    /** 默认使用的宿主审批界面。 */
+    defaultPresentation: string;
+    /** 可用的宿主审批界面；仅官方插件可以声明。 */
+    presentations: PluginAppActionApprovalPresentation[];
+    /** 根据 input.operation 自动选择审批界面，不要求 Agent 传 approvalUi。 */
+    presentationByOperation?: Record<string, string>;
+    /** 某 operation 明确允许的附加审批界面；宿主仍会拒绝未列出的调用方选择。 */
+    alternativePresentationsByOperation?: Record<string, string[]>;
+}
+export interface PluginAppActionRegistration<TInput = unknown> {
+    /** 插件内局部 id；宿主公开为 `plugin.<pluginId>.<id>`。 */
+    id: string;
+    /** 可信官方插件可指定稳定公共 id；若 id 已被占用则后到者忽略（先注册为准）。 */
+    publicId?: string;
+    title: string;
+    summary: string;
+    description?: string;
+    keywords?: string[];
+    effect: PluginAppActionEffect;
+    /** 官方插件可引用宿主已有审批界面；不能关闭 effect 对应的审批。 */
+    approval?: PluginAppActionApproval;
+    inputSchema: PluginJsonSchema;
+    examples?: PluginAppActionExample<TInput>[];
+    timeoutMs?: number;
+    /** 审批前业务就绪校验；失败时不会向用户弹出审批。 */
+    assertReady?: PluginAppActionReadyHandler<TInput>;
+    handler: PluginAppActionHandler<TInput>;
+}
+export interface PluginAppActionsApi {
+    register<TInput = unknown>(registration: PluginAppActionRegistration<TInput>): Disposable;
+}
+export interface PluginOfficialGeneralSettings {
+    workspacePath: string;
+    defaultExecutionMode?: "sandbox" | "full-access";
+    notificationsEnabled: boolean;
+    debugMode: boolean;
+    sandbox: unknown;
+}
+export type PluginOfficialGeneralSettingsUpdate = {
+    operation: "set-notifications";
+    enabled: boolean;
+} | {
+    operation: "set-execution-mode";
+    mode: "sandbox" | "full-access";
+} | {
+    operation: "set-workspace";
+    path: string;
+};
+export interface PluginOfficialExperimentalSettings {
+    vettaCli: boolean;
+    promptPrediction: boolean;
+    agentSkills: boolean;
+}
+export interface PluginOfficialDownloadItem {
+    id: string;
+    url: string;
+    filename: string;
+    path: string;
+    totalBytes: number;
+    receivedBytes: number;
+    status: "queued" | "downloading" | "paused" | "completed" | "failed" | "canceled";
+    error?: string;
+    createdAt: number;
+    completedAt?: number;
+    speedBytesPerSec?: number;
+}
+export interface PluginOfficialUpdaterState {
+    phase: "idle" | "checking" | "available" | "downloading" | "ready" | "installing" | "error";
+    currentVersion: string;
+    latestVersion?: string;
+    releaseNote?: string;
+    progress?: number;
+    downloadedBytes?: number;
+    totalBytes?: number;
+    assetFileName?: string;
+    error?: string;
+    pendingInstall: boolean;
+}
+export type PluginOfficialWebhookKind = "feishu" | "dingtalk";
+export interface PluginOfficialWebhookEndpoint {
+    id: string;
+    kind: PluginOfficialWebhookKind;
+    name: string;
+    enabled: boolean;
+    createdAt: string;
+    updatedAt: string;
+    urlMask?: string;
+    hasSignSecret?: boolean;
+}
+export interface PluginOfficialWebhookProvider {
+    kind: PluginOfficialWebhookKind;
+    displayName: string;
+    iconClass?: string;
+}
+export interface PluginOfficialWebhookCreateInput {
+    kind: PluginOfficialWebhookKind;
+    name: string;
+    webhookUrl: string;
+    signSecret?: string;
+    enabled?: boolean;
+}
+export interface PluginOfficialWebhookUpdateInput {
+    name?: string;
+    enabled?: boolean;
+    webhookUrl?: string;
+    signSecret?: string;
+}
+export interface PluginOfficialWebhookMessage {
+    title?: string;
+    text: string;
+    level?: "info" | "warn" | "error" | "success";
+}
+export interface PluginOfficialWebhookSendResult {
+    ok: boolean;
+    error?: string;
+}
+export interface PluginOfficialSkillInfo {
+    name: string;
+    alias?: string;
+    description: string;
+    source: string;
+    type: "skill" | "scene";
+}
+export type PluginOfficialInstalledSkill = {
+    name: string;
+    version: string;
+    installedAt: string;
+    source: "market" | "custom";
+    enabled: boolean;
+    type?: "skill" | "scene";
+    alias?: string;
+    marketDescription?: string;
+    description?: string;
+};
+export interface PluginOfficialShortcutBinding {
+    id: string;
+    defaultShortcut: string;
+    shortcut: string;
+    isDefault: boolean;
+}
+export interface PluginOfficialQuickPanelSettings {
+    trigger: "none" | "mod" | "alt" | "shift";
+    postSendBehavior: "foreground" | "background";
+}
+export interface PluginOfficialImStatus {
+    enabled: boolean;
+    transport: string;
+    agentModel: {
+        provider: string;
+        model: string;
+        reasoningLevel?: string;
+    } | null;
+    wechatBound: boolean;
+    feishuAppId: string | null;
+    runtime: unknown;
+}
+export interface PluginOfficialImLog {
+    level: string;
+    msg: string;
+    time: string;
+    fields?: Record<string, unknown>;
+}
+export interface PluginOfficialMcpServerSummary {
+    name: string;
+    type: "http" | "stdio";
+    disabled: boolean;
+    command?: string;
+    url?: string;
+}
+export interface PluginOfficialMcpServerDetail {
+    name: string;
+    type?: "http" | "stdio";
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    disabled?: boolean;
+    autoApprove?: string[];
+    startupTimeout?: number;
+    debug?: boolean;
+}
+export type PluginOfficialMcpUpsertData = {
+    type?: "stdio";
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    disabled?: boolean;
+    autoApprove?: string[];
+    startupTimeout?: number;
+    debug?: boolean;
+} | {
+    type: "http";
+    url?: string;
+    headers?: Record<string, string>;
+    disabled?: boolean;
+    autoApprove?: string[];
+    startupTimeout?: number;
+    debug?: boolean;
+};
+export type PluginOfficialExecutionMode = "inherit" | "sandbox" | "full-access";
+export interface PluginOfficialSelectedSkill {
+    name: string;
+    alias?: string;
+    type: "skill" | "scene";
+}
+export interface PluginOfficialBatchProjectCreateData {
+    name: string;
+    prompt: string;
+    modelKey?: string;
+    folders: string[];
+    concurrency: number;
+    executionMode?: PluginOfficialExecutionMode;
+    artifactPatterns?: string[];
+    notifyEnabled?: boolean;
+    timeoutMinutes?: number;
+    skill?: PluginOfficialSelectedSkill;
+}
+export interface PluginOfficialBatchProjectUpdateData {
+    name?: string;
+    prompt?: string;
+    modelKey?: string;
+    concurrency?: number;
+    executionMode?: PluginOfficialExecutionMode;
+    artifactPatterns?: string[];
+    notifyEnabled?: boolean;
+    timeoutMinutes?: number;
+    newFolders?: string[];
+    skill?: PluginOfficialSelectedSkill | null;
+}
+export interface PluginOfficialSchedulerTaskCreateData {
+    name: string;
+    prompt: string;
+    cron: string;
+    isOnce: boolean;
+    enabled?: boolean;
+    cwd: string;
+    modelKey?: string;
+    executionMode?: PluginOfficialExecutionMode;
+    skill?: PluginOfficialSelectedSkill;
+}
+export interface PluginOfficialSchedulerTaskUpdateData {
+    name?: string;
+    prompt?: string;
+    cron?: string;
+    isOnce?: boolean;
+    enabled?: boolean;
+    cwd?: string;
+    modelKey?: string | null;
+    executionMode?: PluginOfficialExecutionMode;
+    skill?: PluginOfficialSelectedSkill | null;
+}
+export interface PluginOfficialModelSummary {
+    id: string;
+    name?: string;
+    api?: string;
+    reasoning?: boolean;
+}
+export interface PluginOfficialProviderSummary {
+    id: string;
+    displayName: string;
+    baseUrl?: string;
+    api?: string;
+    hasApiKey: boolean;
+    modelCount: number;
+    models: PluginOfficialModelSummary[];
+}
+export interface PluginOfficialProviderDetail {
+    baseUrl?: string;
+    apiKey?: string;
+    api?: string;
+    displayName?: string;
+    authHeader?: boolean;
+    headers?: Record<string, string>;
+    models?: Array<{
+        id: string;
+        name?: string;
+        api?: string;
+        reasoning?: boolean;
+        contextWindow?: number;
+        maxTokens?: number;
+    }>;
+}
+export interface PluginOfficialProviderUpsertData {
+    baseUrl?: string;
+    apiKey?: string;
+    api?: string;
+    displayName?: string;
+    authHeader?: boolean;
+    headers?: Record<string, string>;
+    models?: Array<{
+        id: string;
+        name?: string;
+        api?: string;
+        reasoning?: boolean;
+        contextWindow?: number;
+        maxTokens?: number;
+    }>;
+}
+export interface PluginOfficialProjectEntry {
+    path: string;
+    name?: string;
+}
+export interface PluginOfficialPluginSummary {
+    id: string;
+    name: string;
+    version: string;
+    enabled: boolean;
+    required: boolean;
+    source: string;
+    permissions: string[];
+    description?: string;
+    devWatch?: unknown;
+}
+export interface PluginOfficialKnowledgeBase {
+    id: string;
+    name: string;
+    updatedAt: number;
+    isDefault: boolean;
+    nodes: unknown[];
+}
+export interface PluginOfficialKnowledgeProcessingSettings {
+    enabled?: boolean;
+    pollIntervalMinutes?: number;
+    processingModelKey?: string;
+    processingModelReasoningLevel?: string;
+    agentConcurrency?: number;
+    ocrConcurrency?: number;
+}
+/** 仅宿主验证为官方来源的插件可以调用；普通插件调用时由宿主拒绝。 */
+export interface PluginOfficialApi {
+    general: {
+        getSettings(): Promise<PluginOfficialGeneralSettings>;
+        setSettings(input: PluginOfficialGeneralSettingsUpdate): Promise<PluginOfficialGeneralSettingsUpdate>;
+    };
+    agent: {
+        getExperimental(): Promise<PluginOfficialExperimentalSettings>;
+        setExperimental(input: Partial<PluginOfficialExperimentalSettings>): Promise<PluginOfficialExperimentalSettings>;
+    };
+    downloads: {
+        list(): Promise<PluginOfficialDownloadItem[]>;
+        cancel(id: string): Promise<void>;
+    };
+    updater: {
+        getState(): Promise<PluginOfficialUpdaterState>;
+        getCurrentVersion(): Promise<string>;
+        check(): Promise<PluginOfficialUpdaterState>;
+        download(): Promise<PluginOfficialUpdaterState>;
+        install(): Promise<void>;
+        dismiss(): Promise<void>;
+        cancel(): Promise<void>;
+    };
+    webhook: {
+        list(): Promise<PluginOfficialWebhookEndpoint[]>;
+        listProviders(): Promise<PluginOfficialWebhookProvider[]>;
+        create(input: PluginOfficialWebhookCreateInput): Promise<PluginOfficialWebhookEndpoint>;
+        update(id: string, input: PluginOfficialWebhookUpdateInput): Promise<PluginOfficialWebhookEndpoint>;
+        setEnabled(id: string, enabled: boolean): Promise<PluginOfficialWebhookEndpoint>;
+        delete(id: string): Promise<void>;
+        test(id: string): Promise<PluginOfficialWebhookSendResult>;
+        send(id: string, message: PluginOfficialWebhookMessage): Promise<PluginOfficialWebhookSendResult>;
+    };
+    skills: {
+        list(cwd?: string): Promise<PluginOfficialSkillInfo[]>;
+        getManifest(): Promise<Record<string, PluginOfficialInstalledSkill>>;
+        setEnabled(name: string, enabled: boolean): Promise<{
+            name: string;
+            enabled: boolean;
+        }>;
+        uninstall(name: string, type?: "skill" | "scene"): Promise<void>;
+    };
+    shortcuts: {
+        listAvailableActions(): Array<{
+            id: string;
+            defaultShortcut: string;
+        }>;
+        get(): Promise<{
+            bindings: PluginOfficialShortcutBinding[];
+            quickPanel: PluginOfficialQuickPanelSettings;
+        }>;
+        setBinding(id: string, shortcut: string): Promise<{
+            bindings: PluginOfficialShortcutBinding[];
+        }>;
+        resetBinding(id: string): Promise<{
+            bindings: PluginOfficialShortcutBinding[];
+            shortcut: string;
+        }>;
+        resetAllBindings(): Promise<{
+            bindings: PluginOfficialShortcutBinding[];
+        }>;
+        setQuickPanelTrigger(trigger: PluginOfficialQuickPanelSettings["trigger"]): Promise<PluginOfficialQuickPanelSettings>;
+        setQuickPanelBehavior(behavior: PluginOfficialQuickPanelSettings["postSendBehavior"]): Promise<PluginOfficialQuickPanelSettings>;
+    };
+    im: {
+        getStatus(): Promise<PluginOfficialImStatus>;
+        getLogs(limit?: number): Promise<PluginOfficialImLog[]>;
+        setEnabled(enabled: boolean): Promise<{
+            status: unknown;
+        }>;
+        restart(): Promise<{
+            status: unknown;
+        }>;
+        setAgentModel(modelKey: string | null, reasoningLevel?: string): Promise<{
+            status: unknown;
+        }>;
+        assertModelKeyExists(modelKey: string): Promise<void>;
+    };
+    mcp: {
+        list(): Promise<PluginOfficialMcpServerSummary[]>;
+        get(name: string): Promise<PluginOfficialMcpServerDetail>;
+        listNames(): Promise<string[]>;
+        upsert(name: string, data: PluginOfficialMcpUpsertData): Promise<PluginOfficialMcpServerDetail>;
+        setEnabled(name: string, enabled: boolean): Promise<void>;
+        remove(name: string): Promise<void>;
+    };
+    models: {
+        list(): Promise<{
+            defaultModel: string | null;
+            providers: PluginOfficialProviderSummary[];
+        }>;
+        get(provider?: string): Promise<unknown>;
+        probe(provider: string, model: string): Promise<{
+            ok: boolean;
+            message?: string;
+            error?: string;
+        }>;
+        listProviderIds(): Promise<string[]>;
+        assertModelKeyExists(modelKey: string, operation?: string): Promise<void>;
+        setDefault(modelKey: string): Promise<{
+            defaultModel: string;
+        }>;
+        upsertProvider(provider: string, data: PluginOfficialProviderUpsertData): Promise<PluginOfficialProviderDetail>;
+        removeProvider(provider: string): Promise<void>;
+    };
+    projects: {
+        list(): Promise<{
+            workspacePath: string;
+            projects: PluginOfficialProjectEntry[];
+            archivedProjects: PluginOfficialProjectEntry[];
+        }>;
+        listSessions(cwd: string): Promise<unknown[]>;
+        listRuntimeProjects(): Promise<unknown[]>;
+        create(name: string, path?: string): Promise<PluginOfficialProjectEntry>;
+        open(path: string, name?: string): Promise<PluginOfficialProjectEntry>;
+        rename(path: string, name: string): Promise<PluginOfficialProjectEntry>;
+        archive(path: string): Promise<void>;
+        unarchive(path: string): Promise<void>;
+        remove(path: string): Promise<void>;
+    };
+    plugins: {
+        list(): Promise<PluginOfficialPluginSummary[]>;
+        get(id: string): Promise<PluginOfficialPluginSummary>;
+        setEnabled(id: string, enabled: boolean): Promise<PluginOfficialPluginSummary>;
+        installFromUrl(url: string): Promise<PluginOfficialPluginSummary>;
+        installFromPath(path: string, options?: {
+            grantedPermissions?: string[];
+            enable?: boolean;
+        }): Promise<PluginOfficialPluginSummary>;
+        uninstall(id: string): Promise<void>;
+        reload(id: string): Promise<PluginOfficialPluginSummary>;
+    };
+    knowledge: {
+        list(): Promise<PluginOfficialKnowledgeBase[]>;
+        fileStatuses(): Promise<Record<string, unknown>>;
+        isProcessing(): Promise<boolean>;
+        getProcessing(): Promise<PluginOfficialKnowledgeProcessingSettings>;
+        create(name: string): Promise<void>;
+        rename(name: string, newName: string): Promise<void>;
+        delete(name: string): Promise<void>;
+        addFiles(kbId: string, paths: string[], move?: boolean): Promise<void>;
+        deleteEntry(kbId: string, relPath: string): Promise<void>;
+        scanNow(): Promise<{
+            skipped: boolean;
+            reason?: string;
+        }>;
+        retryFailed(): Promise<{
+            skipped: boolean;
+            reason?: string;
+        }>;
+        setProcessing(data: Partial<{
+            enabled: boolean;
+            pollIntervalMinutes: 3 | 5 | 10 | 30;
+            processingModelKey: string | null;
+            processingModelReasoningLevel: string | null;
+            agentConcurrency: number;
+            ocrConcurrency: number;
+        }>): Promise<PluginOfficialKnowledgeProcessingSettings>;
+    };
+    batchTasks: {
+        listProjects(): Promise<unknown[]>;
+        getProject(projectId: string): Promise<unknown>;
+        listProjectIds(): Promise<string[]>;
+        createProject(data: PluginOfficialBatchProjectCreateData): Promise<unknown>;
+        updateProject(projectId: string, data: PluginOfficialBatchProjectUpdateData): Promise<unknown>;
+        deleteProject(projectId: string): Promise<unknown>;
+        runTask(projectId: string, taskId: string): Promise<unknown>;
+        retryTask(projectId: string, taskId: string): Promise<unknown>;
+        stopTask(projectId: string, taskId: string): Promise<unknown>;
+        deleteTask(projectId: string, taskId: string): Promise<unknown>;
+        resumeTask(projectId: string, taskId: string): Promise<unknown>;
+        resumeTaskWithText(projectId: string, taskId: string, text: string): Promise<unknown>;
+        deleteTaskSession(projectId: string, taskId: string): Promise<unknown>;
+        batchDelete(projectId: string): Promise<unknown>;
+        batchStart(projectId: string): Promise<unknown>;
+        batchStop(projectId: string): Promise<unknown>;
+        batchReset(projectId: string): Promise<unknown>;
+        batchResetFailed(projectId: string, taskIds: string[]): Promise<unknown>;
+    };
+    scheduler: {
+        listTasks(): Promise<unknown[]>;
+        getTask(taskId: string): Promise<unknown>;
+        listTaskIds(): Promise<string[]>;
+        getHistory(taskId: string): Promise<unknown[]>;
+        createTask(data: PluginOfficialSchedulerTaskCreateData): Promise<unknown>;
+        updateTask(taskId: string, data: PluginOfficialSchedulerTaskUpdateData): Promise<unknown>;
+        deleteTask(taskId: string): Promise<unknown>;
+        setEnabled(taskId: string, enabled: boolean): Promise<unknown>;
+        runNow(taskId: string): Promise<unknown>;
+        abort(taskId: string): Promise<unknown>;
+    };
+    appearance: {
+        help(): Promise<unknown>;
+        get(): Promise<unknown>;
+        set(input: {
+            mode?: "light" | "dark" | "auto";
+            themeId?: string;
+            cursorStyle?: "default" | "stoat";
+        }): Promise<unknown>;
+        setLanguage(language: "zh" | "en"): Promise<unknown>;
+        listThemeIds(): string[];
+    };
+    navigation: {
+        help(): unknown;
+        resolveOpen(input: {
+            target: string;
+            tab?: string;
+            section?: string;
+        }): {
+            hashPath: string;
+            resolved: unknown;
+        };
+        open(input: {
+            target: string;
+            tab?: string;
+            section?: string;
+        }): Promise<unknown>;
+    };
+}
 export interface PluginFsEntry {
     name: string;
     path: string;
@@ -773,6 +1389,8 @@ export interface PluginI18nApi {
     /** Fired when the host language changes. */
     onChange(listener: (locale: string) => void): Disposable;
 }
+/** 工作模式（agent_mode 轴，见 ADR-0046）。宿主 Work/Coding，未来可能扩展。 */
+export type AgentMode = "work" | "coding";
 export interface PluginContext {
     plugin: {
         id: string;
@@ -782,11 +1400,17 @@ export interface PluginContext {
     ui: PluginUiApi;
     conversation: PluginConversationApi;
     agent: PluginAgentApi;
+    appActions: PluginAppActionsApi;
+    official: PluginOfficialApi;
     fs: PluginFsApi;
     command: PluginCommandApi;
     images: PluginImagesApi;
     settings: PluginSettingsApi;
     i18n: PluginI18nApi;
+    /** 当前工作模式（agent_mode 轴）。开发者据此做模式定制。见 ADR-0046。 */
+    getAgentMode(): AgentMode;
+    /** 订阅工作模式变更（纯全局实时切换）。返回 Disposable 取消订阅。 */
+    onAgentModeChanged(listener: (mode: AgentMode) => void): Disposable;
 }
 export interface PluginDefinition {
     activate(ctx: PluginContext): void | Promise<void>;