siyuan 1.2.2-alpha.0 → 1.2.2

package/CHANGELOG.md

@@ -1,8 +1,16 @@
 # Changelog
 
-## v1.2.2 2026
+## v1.2.3 2026
 
-* [:art: add kernel type definitions and update package exports](https://github.com/siyuan-note/petal/pull/49)
+
+## v1.2.2 2026-6-30
+
+* [Align with SiYuan's latest type definitions](https://github.com/siyuan-note/petal/pull/54)
+* [Deprecate updateTransaction and replace with updateTransactionElement](https://github.com/siyuan-note/siyuan/issues/17828)
+* [Improve LocalStorage related APIs](https://github.com/siyuan-note/siyuan/pull/17482)
+* [Add kernel type definitions and update package exports](https://github.com/siyuan-note/petal/pull/49)
+* [Add MCP interface and handler types to kernel definitions](https://github.com/siyuan-note/petal/pull/53)
+* [Provides plugin functions for exporting files](https://github.com/siyuan-note/siyuan/issues/15484)
 
 ## v1.2.1 2026-04-21
 

package/kernel.d.ts

@@ -2,8 +2,7 @@
 /// <reference types="@dop251/types-goja_nodejs-global" />
 /// <reference types="@dop251/types-goja_nodejs-url" />
 
-export { };
-
+import type { JSONSchema } from "zod/v4/core";
 declare global {
     const siyuan: ISiyuan;
 }
@@ -127,6 +126,45 @@ export interface IEventMessage {
     detail: any;
 }
 
+/**
+ * Published on the runtime event bus after the plugin starts successfully
+ * and enters the running state.
+ */
+export interface IStartEventMessage extends IEventMessage {
+    type: 'start';
+    detail: null;
+}
+
+/**
+ * Published on the runtime event bus at the beginning of a clean plugin
+ * shutdown, before the runtime is torn down.
+ */
+export interface IStopEventMessage extends IEventMessage {
+    type: 'stop';
+    detail: null;
+}
+
+/** File-system event kind emitted by the kernel storage watcher. */
+export type TFsNotifyOperation = 'CREATE' | 'WRITE' | 'RENAME' | 'REMOVE';
+
+/**
+ * Published on the runtime event bus when a watched storage path is
+ * created, written, renamed, or removed.
+ *
+ * Watching is managed via {@link IStorage.watcher}.
+ */
+export interface IFsNotifyEventMessage extends IEventMessage {
+    type: 'fs-notify';
+    detail: {
+        /** The type of file-system change that triggered this event. */
+        operation: TFsNotifyOperation;
+        /** Path relative to the plugin's storage directory. */
+        path: string;
+    }
+}
+
+export type TEventMessage = IStartEventMessage | IStopEventMessage | IFsNotifyEventMessage | IEventMessage;
+
 // ── WebSocket ─────────────────────────────────────────────────────────────────
 
 /**
@@ -265,7 +303,7 @@ export interface IWebSocket {
     /** Negotiated sub-protocol, or an empty string if none was negotiated. */
     readonly protocol: string;
     /** Current connection state. See {@link TWebSocketReadyState}. */
-    readyState: TWebSocketReadyState;
+    readonly readyState: TWebSocketReadyState;
     /** The WebSocket server URL (e.g. `"ws://127.0.0.1:6806/ws/…"`). */
     readonly url: string;
     /** Called when the connection is established. */
@@ -327,7 +365,7 @@ export interface IWebSocket {
  */
 export interface IEventSource {
     /** Current connection state. See {@link TEventSourceReadyState}. */
-    readyState: TEventSourceReadyState;
+    readonly readyState: TEventSourceReadyState;
     /** The original path passed to {@link IClient.event}, e.g. `"/api/…"`. */
     readonly url: string;
     /** Called when the connection is established. */
@@ -409,10 +447,8 @@ export interface IPlugin {
  * advancing to the next lifecycle stage. Unset callbacks (`null`) are skipped.
  */
 export interface IPluginLifecycle {
-    /** Called when the plugin script is first evaluated (before the runtime is fully ready). */
+    /** Called when the plugin script is first evaluated (before the `running` state.). */
     onload: (() => void | Promise<void>) | null;
-    /** Called after the plugin has fully loaded and its runtime is initialized. */
-    onloaded: (() => void | Promise<void>) | null;
     /** Called when the plugin transitions to the `running` state. */
     onrunning: (() => void | Promise<void>) | null;
     /** Called when the plugin is being unloaded (e.g. on shutdown or hot-reload). */
@@ -429,11 +465,10 @@ export interface IEvent {
     /**
      * Inbound kernel event handler.
      *
-     * @remarks Assign a function to receive every kernel broadcast event.
-     * If the function returns a `Promise`, the kernel awaits its resolution
-     * before delivering the next event. Set to `null` to stop receiving events.
+     * @remarks Assign a function to receive every kernel dispatched event.
+     * Set to `null` to stop receiving events.
      */
-    handler: ((event: IEventMessage) => void | Promise<void>) | null;
+    handler: ((event: TEventMessage) => void | Promise<void>) | null;
     /**
      * Publishes an event to the in-process event bus.
      *
@@ -499,8 +534,32 @@ export interface IStorage {
      * @returns An array of {@link IStorageEntry} descriptors.
      */
     list(path: string): Promise<IStorageEntry[]>;
+    readonly watcher: IStorageWatcher;
+}
+
+/**
+ * Controls which storage paths the plugin's file-system watcher monitors.
+ * Changes on watched paths are delivered as {@link IFsNotifyEventMessage}
+ * events on the runtime event bus.
+ */
+export interface IStorageWatcher {
+    /**
+     * Resolves `path` and registers it with the file-system watcher.
+     * @param path - Path relative to the storage directory to start watching.
+     */
+    add(path: string): Promise<void>;
+    /**
+     * Resolves `path` and unregisters it from the file-system watcher.
+     * @param path - Path relative to the storage directory to stop watching.
+     */
+    remove(path: string): Promise<void>;
 }
 
+/**
+ * RPC / MCP method handler type.
+ */
+export type THandler = (...args: any[]) => any | Promise<any>;
+
 /**
  * JSON-RPC method registry for the plugin.
  *
@@ -513,12 +572,12 @@ export interface IRpc {
      * Registers a named RPC method callable by external clients.
      *
      * @param name         - Unique method name used to dispatch the call.
-     * @param fn           - Handler function; may be async.
+     * @param handler      - Handler function; may be async.
      * @param descriptions - Optional human-readable description strings.
      */
     bind(
         name: string,
-        fn: (...args: any[]) => any | Promise<any>,
+        handler: THandler,
         ...descriptions: string[]
     ): Promise<void>;
     /**
@@ -533,7 +592,78 @@ export interface IRpc {
      * @param method - Notification method name.
      * @param params - Optional notification parameters.
      */
-    broadcast(method: string, params?: any): Promise<void>;
+    broadcast(method: string, params?: any[] | Record<string, any>): Promise<void>;
+}
+
+/**
+ * MCP (Model Context Protocol) interface exposed to plugins.
+ *
+ * Allows plugins to register and unregister tools that are surfaced to MCP clients
+ * (e.g., AI assistants) through the kernel's built-in MCP server.
+ */
+export interface IMcp {
+    /**
+     * Register a tool with the MCP server.
+     *
+     * The tool name is automatically namespaced to avoid collisions between plugins.
+     * The actual registered name follows the pattern `plugin__<plugin-name>__<tool-name>`.
+     *
+     * @param name - The tool name, local to this plugin (e.g. `"my-tool"`).
+     * @param config - Metadata describing the tool to MCP clients.
+     * @param handler - The function invoked when an MCP client calls the tool.
+     * @returns The registration record, including the fully-qualified tool name.
+     */
+    registerTool(
+        name: string,
+        config: IMcpToolConfig,
+        handler: THandler,
+    ): Promise<IRegisteredTool>;
+
+    /**
+     * Unregister a previously registered tool.
+     *
+     * Uses the same local name passed to {@link registerTool}; the kernel resolves
+     * the fully-qualified name internally.
+     *
+     * @param name - The local tool name used when the tool was registered.
+     */
+    unregisterTool(name: string): Promise<void>;
+}
+
+/**
+ * Metadata describing an MCP tool to clients.
+ *
+ * All fields are optional; omitting them produces a tool with no description or
+ * schema constraints, which is valid but less discoverable.
+ */
+export interface IMcpToolConfig {
+    /** Human-readable display name shown in MCP client UIs. */
+    title?: string;
+    /** Natural-language description of what the tool does, used by AI clients for tool selection. */
+    description: string;
+    /** JSON Schema describing the tool's input parameters. */
+    inputSchema: JSONSchema.ObjectSchema;
+    /** JSON Schema describing the tool's output. */
+    outputSchema?: JSONSchema.Schema;
+}
+
+/**
+ * The registration record returned by {@link IMcp.registerTool}.
+ *
+ * Extends {@link IMcpToolConfig} with the resolved fully-qualified name and the
+ * handler that was registered.
+ */
+export interface IRegisteredTool extends IMcpToolConfig {
+    /**
+     * The fully-qualified tool name as registered with the MCP server.
+     *
+     * The kernel namespaces tool names to prevent collisions between plugins.
+     * A tool registered as `"my-tool"` in plugin `"my-plugin"` becomes
+     * `"plugin__my_plugin__my_tool"`.
+     *
+     * @example "plugin__plugin_name__tool_name"
+     */
+    name: string;
 }
 
 // ── Server request types ─────────────────────────────────────────────────────
@@ -878,24 +1008,119 @@ export interface IHttpResponse {
 
 // ── Server handler interfaces ─────────────────────────────────────────────────
 
+/**
+ * A single Server-Sent Event (SSE) frame sent from the server to the client.
+ *
+ * Each field corresponds to a line prefix defined by the SSE specification
+ * {@link https://html.spec.whatwg.org/multipage/server-sent-events.html | HTML Standard - 9.2 Server-sent events}.
+ */
+export interface IServerSentEvent {
+    /** `id:` field — sets the event source's last-event-ID, used for reconnection replay. */
+    id?: string;
+    /** `event:` field — custom event type. */
+    event?: string;
+    /** `data:` field — the payload of the event. Multi-line values are joined with `\n`. */
+    data: any;
+    /** `retry:` field — overrides the client's reconnection delay (milliseconds). */
+    retry?: number;
+}
+
+/**
+ * Server-side SSE (Server-Sent Events) port provided to
+ * {@link IServerEventSourceRequest.port}.
+ *
+ * @remarks
+ * The kernel opens the SSE response stream before invoking the handler.
+ * Once streaming begins, {@link IEventSourcePort.onopen} fires to signal that
+ * the stream is ready for events. Call {@link IEventSourcePort.send} to push
+ * SSE events to the client and {@link IEventSourcePort.close} to terminate
+ * the stream. The connection stays open until `close()` is called or the
+ * client disconnects.
+ */
+export interface IEventSourcePort {
+    /** Called once when the SSE stream is ready to accept events. */
+    onopen: ((event: IEventSourceOpenEvent) => void | Promise<void>) | null;
+    /** Called when the client disconnects or after {@link IEventSourcePort.close}. */
+    onclose: ((event: IEventSourceCloseEvent) => void | Promise<void>) | null;
+    /**
+     * Pushes one SSE event to the connected client.
+     *
+     * @remarks
+     * `send` is synchronous — no `await` required. It enqueues the event in
+     * the kernel's SSE write buffer; the actual flush is asynchronous.
+     *
+     * @param event - The SSE event to send.
+     */
+    send(event: IServerSentEvent): void;
+    /** Terminates the SSE stream and closes the response. */
+    close(): void;
+}
+
+/**
+ * The request object received by {@link IServerScope.ws | WebSocket server handlers}.
+ *
+ * @remarks
+ * Extends {@link IServerRequest} with a `port` property that mirrors the
+ * {@link IWebSocket} client interface. The kernel upgrades the HTTP connection
+ * to WebSocket before invoking the handler. After the handler returns, the
+ * kernel auto-opens the port's read loop if `port.open()` was not called
+ * explicitly.
+ */
+export interface IServerWebSocketRequest extends IServerRequest {
+    /**
+     * Bidirectional WebSocket port connected to the client.
+     *
+     * @remarks
+     * Assign event callbacks (`onopen`, `onmessage`, `onping`, `onpong`,
+     * `onclose`, `onerror`) before the handler returns. Calling `port.open()`
+     * is optional — the kernel opens the read loop automatically.
+     */
+    readonly port: Omit<IWebSocket, "extensions" | "url">;
+}
+
+/**
+ * The request object received by {@link IServerScope.es | SSE server handlers}.
+ *
+ * @remarks
+ * Extends {@link IServerRequest} with a `port` property for pushing
+ * Server-Sent Events to the client. The kernel opens the SSE response before
+ * the handler is invoked; {@link IEventSourcePort.onopen} fires once streaming
+ * begins.
+ */
+export interface IServerEventSourceRequest extends IServerRequest {
+    /**
+     * Server-side SSE port for pushing events to the connected client.
+     *
+     * @remarks
+     * Assign `onopen` and `onclose` callbacks in the handler body. Call
+     * `port.send(eventType, data)` inside `onopen` to emit SSE events.
+     */
+    readonly port: IEventSourcePort;
+}
+
 /**
  * Handler slot for one request type within a server scope.
  *
- * @remarks The object is sealed by the kernel; only the `handler` property
- * may be reassigned. Set `handler` to `null` to leave the slot empty — the
- * kernel will return `500 Internal Server Error` for any unhandled request.
+ * @remarks
+ * The object is sealed by the kernel; only the `handler` property may be
+ * reassigned. Set `handler` to `null` to leave the slot empty — the kernel
+ * will return `500 Internal Server Error` for any unhandled request.
  *
  * @typeParam TRes - Expected return type of the handler function.
+ * @typeParam TReq - Request object type passed to the handler. Defaults to
+ *   {@link IServerRequest} for the HTTP slot; specialised to
+ *   {@link IServerWebSocketRequest} and {@link IServerEventSourceRequest} for the WS and SSE
+ *   slots respectively.
  */
-export interface IServerRequestHandler<TRes> {
+export interface IServerRequestHandler<TRes, TReq extends IServerRequest = IServerRequest> {
     /**
      * The function invoked for each incoming request of this type.
      *
-     * @remarks The kernel passes the parsed {@link IServerRequest} as the
-     * sole argument and awaits any returned `Promise` before writing the
-     * response.
+     * @remarks
+     * The kernel passes the parsed request as the sole argument and awaits
+     * any returned `Promise` before writing the response.
      */
-    handler: ((request: IServerRequest) => TRes | Promise<TRes>) | null;
+    handler: ((request: TReq) => TRes | Promise<TRes>) | null;
 }
 
 /**
@@ -915,15 +1140,23 @@ export interface IServerScope {
     /**
      * WebSocket upgrade handler.
      *
-     * @remarks Reserved — not yet implemented by the kernel.
+     * @remarks
+     * The handler receives an {@link IServerWebSocketRequest} that includes
+     * `request.port`, a bidirectional {@link IWebSocket} connected to the
+     * client. Assign event callbacks before the handler returns; the kernel
+     * auto-opens the port's read loop afterwards.
      */
-    readonly ws: IServerRequestHandler<void>;
+    readonly ws: IServerRequestHandler<void, IServerWebSocketRequest>;
     /**
      * Server-Sent Events handler.
      *
-     * @remarks Reserved — not yet implemented by the kernel.
+     * @remarks
+     * The handler receives an {@link IServerEventSourceRequest} that includes
+     * `request.port`, an {@link IEventSourcePort} for pushing SSE events.
+     * Assign `onopen` / `onclose` callbacks and call `port.send` inside
+     * `onopen`.
      */
-    readonly es: IServerRequestHandler<void>;
+    readonly es: IServerRequestHandler<void, IServerEventSourceRequest>;
 }
 
 /**
@@ -963,6 +1196,8 @@ export interface ISiyuan {
     readonly storage: IStorage;
     /** JSON-RPC method registry. */
     readonly rpc: IRpc;
+    /** MCP method registry. */
+    readonly mcp: IMcp;
     /** Network client utilities (HTTP, WebSocket, SSE). */
     readonly client: IClient;
     /** Web request handler registry. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siyuan",
-  "version": "1.2.2-alpha.0",
+  "version": "1.2.2",
   "contributors": [
     "zuoez02",
     "Vanessa",
@@ -40,6 +40,7 @@
   "dependencies": {
     "@dop251/types-goja_nodejs-buffer": "latest",
     "@dop251/types-goja_nodejs-global": "latest",
-    "@dop251/types-goja_nodejs-url": "latest"
+    "@dop251/types-goja_nodejs-url": "latest",
+    "zod": "latest"
   }
 }

package/siyuan.d.ts

@@ -1,32 +1,23 @@
 import type {
     IGetDocInfo,
     IGetTreeStat,
-    IMenuBaseDetail,
+    IKernelPlugin,
+    IKernelPluginState,
     IMenu,
+    IMenuBaseDetail,
+    IMenuItem,
+    IModels,
     IObject,
     IPosition,
-    ISiyuan,
-    IWebSocketData,
     IProtyle,
     IProtyleOptions,
-    TProtyleAction,
-    IMenuItem,
     IRefDefs,
+    ISiyuan,
+    IWebSocketData,
     TEditorMode,
+    TProtyleAction,
 } from "./types";
-import {
-    Config,
-    Custom,
-    Lute,
-    Protyle,
-    Toolbar,
-    subMenu,
-    App,
-    Files,
-    Tab,
-    Model,
-    MobileCustom,
-} from "./types";
+import {App, Config, Custom, Files, Lute, MobileCustom, Model, Protyle, subMenu, Tab, Toolbar,} from "./types";
 
 export * from "./types";
 
@@ -35,7 +26,7 @@ declare global {
     }
 }
 
-export type TDock = "file" | "outline" | "inbox" | "bookmark" | "tag" | "graph" | "globalGraph" | "backlink"
+export type TDock = "file" | "outline" | "inbox" | "bookmark" | "tag" | "graph" | "globalGraph" | "backlink" | "agentChat"
 
 export type TTab = "Outline" | "Graph" | "Backlink" | "Asset" | "Editor" | "Search" | "siyuan-card"
 
@@ -230,6 +221,7 @@ export interface IEventBusMap {
         languageElements: HTMLElement[],
         protyle: IProtyle
     };
+    "kernel-plugin-state-change": IKernelPluginState;
 }
 
 export interface IPluginDockTab {
@@ -378,21 +370,11 @@ export function exitSiYuan(): void
 
 export function getAllEditor(): Protyle[]
 
+export function saveExportFile(uri: string, msgId?: string): Promise<void>;
+
 export function getAllTabs(type?: TTab | string): Tab[]
 
-export function getAllModels(): {
-    editor: [],
-    graph: [],
-    asset: [],
-    outline: [],
-    backlink: [],
-    search: [],
-    inbox: [],
-    files: [],
-    bookmark: [],
-    tag: [],
-    custom: [],
-}
+export function getAllModels(): IModels
 
 export function openSetting(app: App): Dialog | undefined;
 
@@ -443,6 +425,7 @@ export function hideMessage(id?: string): void;
 export abstract class Plugin {
     eventBus: EventBus;
     i18n: IObject;
+    kernel: IKernelPlugin;
     data: any;
     displayName: string;
     readonly name: string;
@@ -534,6 +517,24 @@ export abstract class Plugin {
 
     addCommand(options: ICommand): void;
 
+    /**
+     * 按名称取密钥值（来自「设置 → 密钥和变量」的密钥库）。找不到时返回空字符串。
+     * 密钥在内核侧加密存储，此处读到的是运行时明文；仅在本地管理员身份下可用。
+     */
+    getSecret(name: string): string;
+
+    /**
+     * 按名称取变量值（来自「设置 → 密钥和变量」的变量库）。找不到时返回空字符串。
+     * 变量以明文存储，用于非敏感配置。
+     */
+    getVariable(name: string): string;
+
+    addAgentAction(options: {
+        name: string,
+        description: string,
+        handler: (args: Record<string, unknown>, app: App) => Promise<{ result?: string, error?: string }>,
+    }): string;
+
     addFloatLayer(options: {
         refDefs: IRefDefs[],
         x?: number,