@zhin.js/plugin-runtime 1.0.1 → 1.1.1

package/README.md

@@ -12,6 +12,11 @@ import {
 } from '@zhin.js/plugin-runtime';
 ```
 
+`PluginSetupContext.addFeature(feature, localName, definition)` 是约定目录之外的内存
+Capability 写入口。它仍由上层 Runtime 交给对应 Feature provider 校验和投影；Feature
+通过 `authoring.setupMethod` 和 module augmentation 提供强类型 `addCommand`、
+`addComponent`、`addTool` 等别名。底座只保存通用注册记录，不理解 IM。
+
 ## 生命周期
 
 ```text

package/lib/agent-tools-host.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Plugin-contributed Agent tool registered against the Agent Host.
+ * Captured at setup() time — execute closures must never call plugin locators.
+ *
+ * Access vocabulary (platforms / scopes / permissions / hidden) mirrors the
+ * `@zhin.js/tool` ToolIndex descriptor and is enforced per message by the
+ * Agent runtime via Core `canAccessTool` — one predicate for both paths.
+ */
+export interface AgentToolRegistration {
+    /** Runtime tool name exposed to the model (e.g. `lottery_sync`). */
+    readonly name: string;
+    readonly description: string;
+    /** zod object schema or JSON Schema; drives the deferred catalog + arg validation. */
+    readonly inputSchema?: unknown;
+    readonly keywords?: readonly string[];
+    readonly tags?: readonly string[];
+    /** Limit to these adapter platforms (e.g. `['icqq']`); empty = all. */
+    readonly platforms?: readonly string[];
+    /** Limit to these channel scopes; empty = all. */
+    readonly scopes?: readonly ('private' | 'group' | 'channel')[];
+    readonly permissions?: readonly string[];
+    /** Registered but never offered to the model (callable by name only). */
+    readonly hidden?: boolean;
+    /** Per-tool approval policy; stacks with ExecPolicy. */
+    readonly approval?: 'never' | 'always';
+    /** Plugin/tool origin label (e.g. plugin name) for diagnostics. */
+    readonly source?: string;
+    execute(input: Record<string, unknown>): unknown | Promise<unknown>;
+}
+/**
+ * Generation-owned Agent tool registry provided by the Agent Host.
+ * Absent when AI is not installed/enabled — plugins must guard with `has()`.
+ */
+export interface AgentToolsHost {
+    /** Register a tool for every Agent turn of this generation; returns disposal. */
+    register(tool: AgentToolRegistration): () => void;
+}
+export declare const agentToolsHostToken: import("./token.js").Token<AgentToolsHost>;

package/lib/agent-tools-host.js

@@ -0,0 +1,2 @@
+import { createToken } from './token.js';
+export const agentToolsHostToken = createToken('zhin.agent-tools.host', 'Plugin Runtime agent tools host');

package/lib/capability.d.ts

@@ -6,5 +6,16 @@ export interface CapabilitySlot<T = unknown> {
     readonly localName: string;
     readonly source: string;
     readonly definition: T;
+    /** Setup-owned slots follow their Plugin Scope instead of file-slot HMR. */
+    readonly origin?: 'setup';
+}
+/** A capability declared imperatively while its owning Plugin is assembled. */
+export interface SetupCapabilityRegistration<T = unknown> {
+    readonly id: CapabilityId;
+    readonly owner: PluginId;
+    readonly feature: FeatureId;
+    readonly localName: string;
+    readonly source: string;
+    readonly definition: T;
 }
 export declare function createCapabilitySlot<T>(input: Omit<CapabilitySlot<T>, 'id'>): Readonly<CapabilitySlot<T>>;

package/lib/database-host.d.ts

@@ -1,12 +1,15 @@
+export interface DatabaseHostSelection {
+    where(query: Record<string, unknown>): DatabaseHostSelection;
+    orderBy(field: string, direction?: 'ASC' | 'DESC'): DatabaseHostSelection;
+    limit(count: number): DatabaseHostSelection;
+    then<TResult1 = Record<string, unknown>[], TResult2 = never>(onfulfilled?: ((value: Record<string, unknown>[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+}
 /**
  * Minimal model surface shared by lottery / rss / group-suite memory stores
  * and the Host-backed `@zhin.js/database` adapter.
  */
 export interface DatabaseHostModel {
-    select(): {
-        where(query: Record<string, unknown>): Promise<Record<string, unknown>[]>;
-        then<TResult1 = Record<string, unknown>[], TResult2 = never>(onfulfilled?: ((value: Record<string, unknown>[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
-    };
+    select(...fields: string[]): DatabaseHostSelection;
     insert(row: Record<string, unknown>): Promise<unknown>;
     delete(): {
         where(query: Record<string, unknown>): Promise<unknown>;
@@ -14,6 +17,11 @@ export interface DatabaseHostModel {
     update(patch: Record<string, unknown>): {
         where(query: Record<string, unknown>): Promise<unknown>;
     };
+    /**
+     * DB 侧计数（聚合下推，避免为计数整表加载）。
+     * 可选：轻量 test/memory host 可不实现，调用方降级为 select 计数。
+     */
+    count?(where?: Record<string, unknown>): Promise<number>;
 }
 export type DatabaseHostType = 'related' | 'document' | 'keyvalue';
 export interface DatabaseHostTable {

package/lib/generation-store.d.ts

@@ -0,0 +1,32 @@
+import { DisposeStack, type Dispose } from './dispose.js';
+/**
+ * Minimal structural view of a plugin setup context: anything owning a
+ * generation-scoped lifecycle (e.g. PluginSetupContext) can provide values.
+ */
+export interface GenerationStoreContext {
+    readonly lifecycle: DisposeStack;
+}
+export interface GenerationStore<T> {
+    /**
+     * Publish `value` as the current generation's value. The registration is
+     * removed automatically when `context.lifecycle` disposes (generation end);
+     * the returned Dispose unregisters manually and is idempotent.
+     */
+    provide(context: GenerationStoreContext, value: T): Dispose;
+    /** Latest live value; throws a store-named error when none was provided. */
+    use(): T;
+    /** Latest live value, or `undefined` when none was provided. */
+    tryUse(): T | undefined;
+    /** Drop every registration across all generations. Mainly for tests. */
+    clear(): void;
+}
+/**
+ * Generation-scoped replacement for module-level `let _x` singletons.
+ *
+ * Provided values form a stack: the newest live registration wins, and when a
+ * generation ends its registration is removed via `context.lifecycle`,
+ * re-exposing the previous generation's value. This structurally prevents
+ * stale references to an already disposed generation (the repeater singleton
+ * / rss `_db` class of bugs).
+ */
+export declare function createGenerationStore<T>(name: string): GenerationStore<T>;

package/lib/generation-store.js

@@ -0,0 +1,38 @@
+/**
+ * Generation-scoped replacement for module-level `let _x` singletons.
+ *
+ * Provided values form a stack: the newest live registration wins, and when a
+ * generation ends its registration is removed via `context.lifecycle`,
+ * re-exposing the previous generation's value. This structurally prevents
+ * stale references to an already disposed generation (the repeater singleton
+ * / rss `_db` class of bugs).
+ */
+export function createGenerationStore(name) {
+    const registrations = [];
+    const unregister = (registration) => {
+        const index = registrations.lastIndexOf(registration);
+        if (index >= 0)
+            registrations.splice(index, 1);
+    };
+    return {
+        provide(context, value) {
+            const registration = Object.freeze({ value });
+            registrations.push(registration);
+            context.lifecycle.add(() => unregister(registration));
+            return () => unregister(registration);
+        },
+        use() {
+            const latest = registrations[registrations.length - 1];
+            if (!latest) {
+                throw new Error(`Generation store "${name}" has no live value — call provide(context, value) during plugin setup`);
+            }
+            return latest.value;
+        },
+        tryUse() {
+            return registrations[registrations.length - 1]?.value;
+        },
+        clear() {
+            registrations.length = 0;
+        },
+    };
+}

package/lib/inbox.d.ts

@@ -0,0 +1,35 @@
+import type { DatabaseHost } from './database-host.js';
+/**
+ * 统一收件箱（console endpoint-detail 消息历史/请求/通知视图）表定义与写入辅助。
+ *
+ * 列结构对齐 packages/im/zhin/src/setup/register-inbox.ts（legacy 读路径 SSOT），
+ * request/notice 额外补 consumed/consumed_at 列（对齐 legacy host-api
+ * endpoint-persistence 的 console_bot_requests/notices consumed 标记方式），
+ * 供 console-rpc-extended 的 endpoint:requestConsumed/noticeConsumed 写路径使用。
+ */
+export declare const INBOX_TABLE_MESSAGE = "unified_inbox_message";
+export declare const INBOX_TABLE_REQUEST = "unified_inbox_request";
+export declare const INBOX_TABLE_NOTICE = "unified_inbox_notice";
+export declare const INBOX_MESSAGE_DEFINITION: Record<string, unknown>;
+export declare const INBOX_REQUEST_DEFINITION: Record<string, unknown>;
+export declare const INBOX_NOTICE_DEFINITION: Record<string, unknown>;
+export declare const INBOX_TABLE_DEFINITIONS: Readonly<Record<string, Record<string, unknown>>>;
+/**
+ * 在 DatabaseHost 上注册三张收件箱表（幂等：已定义或已启动的 host 跳过）。
+ * 必须在 host.start() 之前调用（define 在 started 后会抛错）。
+ */
+export declare function defineInboxTables(host: Pick<DatabaseHost, 'define' | 'tables' | 'started'>): void;
+/**
+ * 写一行收件箱记录；表未注册（或 host 未启动导致 model 缺失）时返回 false。
+ * 写失败向上抛，由调用方决定降级策略。
+ */
+export declare function insertInboxRow(host: Pick<DatabaseHost, 'models'>, table: string, row: Record<string, unknown>): Promise<boolean>;
+/** Console SSE 事件 fan-out 的最小结构（@zhin.js/host-http ConsoleEventHub 满足该形状）。 */
+export interface RuntimeEventPublisher {
+    publish(type: string, data: unknown): void;
+}
+/**
+ * Root 级事件发布口（console hub）。basic/cli console-api-installer 提供；
+ * 适配器等插件经 CapabilityContext.use 解析后 publish endpoint:request/notice 等事件。
+ */
+export declare const runtimeEventPublisherToken: import("./token.js").Token<RuntimeEventPublisher>;

package/lib/inbox.js

@@ -0,0 +1,99 @@
+import { createToken } from './token.js';
+/**
+ * 统一收件箱（console endpoint-detail 消息历史/请求/通知视图）表定义与写入辅助。
+ *
+ * 列结构对齐 packages/im/zhin/src/setup/register-inbox.ts（legacy 读路径 SSOT），
+ * request/notice 额外补 consumed/consumed_at 列（对齐 legacy host-api
+ * endpoint-persistence 的 console_bot_requests/notices consumed 标记方式），
+ * 供 console-rpc-extended 的 endpoint:requestConsumed/noticeConsumed 写路径使用。
+ */
+export const INBOX_TABLE_MESSAGE = 'unified_inbox_message';
+export const INBOX_TABLE_REQUEST = 'unified_inbox_request';
+export const INBOX_TABLE_NOTICE = 'unified_inbox_notice';
+export const INBOX_MESSAGE_DEFINITION = {
+    id: { type: 'integer', primary: true, autoIncrement: true },
+    adapter: { type: 'text', nullable: false },
+    endpoint_id: { type: 'text', nullable: false },
+    platform_message_id: { type: 'text', nullable: false },
+    channel_id: { type: 'text', nullable: false },
+    channel_type: { type: 'text', nullable: false },
+    channel_name: { type: 'text', nullable: true },
+    channel_parent_type: { type: 'text', nullable: true },
+    channel_parent_id: { type: 'text', nullable: true },
+    sender_id: { type: 'text', nullable: false },
+    sender_name: { type: 'text', nullable: true },
+    sender_payload: { type: 'text', nullable: false },
+    content: { type: 'text', nullable: false },
+    raw: { type: 'text', nullable: true },
+    created_at: { type: 'integer', nullable: false },
+};
+export const INBOX_REQUEST_DEFINITION = {
+    id: { type: 'integer', primary: true, autoIncrement: true },
+    adapter: { type: 'text', nullable: false },
+    endpoint_id: { type: 'text', nullable: false },
+    platform_request_id: { type: 'text', nullable: false },
+    type: { type: 'text', nullable: false },
+    scene_type: { type: 'text', nullable: true },
+    scene_id: { type: 'text', nullable: false },
+    sub_type: { type: 'text', nullable: true },
+    actor_id: { type: 'text', nullable: false },
+    actor_name: { type: 'text', nullable: true },
+    comment: { type: 'text', nullable: true },
+    created_at: { type: 'integer', nullable: false },
+    resolved: { type: 'integer', nullable: false, default: 0 },
+    resolved_at: { type: 'integer', nullable: true },
+    consumed: { type: 'integer', nullable: false, default: 0 },
+    consumed_at: { type: 'integer', nullable: true },
+};
+export const INBOX_NOTICE_DEFINITION = {
+    id: { type: 'integer', primary: true, autoIncrement: true },
+    adapter: { type: 'text', nullable: false },
+    endpoint_id: { type: 'text', nullable: false },
+    platform_notice_id: { type: 'text', nullable: false },
+    type: { type: 'text', nullable: false },
+    scene_type: { type: 'text', nullable: true },
+    scene_id: { type: 'text', nullable: false },
+    sub_type: { type: 'text', nullable: true },
+    actor_id: { type: 'text', nullable: true },
+    actor_name: { type: 'text', nullable: true },
+    target_id: { type: 'text', nullable: true },
+    target_name: { type: 'text', nullable: true },
+    payload: { type: 'text', nullable: false },
+    created_at: { type: 'integer', nullable: false },
+    consumed: { type: 'integer', nullable: false, default: 0 },
+    consumed_at: { type: 'integer', nullable: true },
+};
+export const INBOX_TABLE_DEFINITIONS = Object.freeze({
+    [INBOX_TABLE_MESSAGE]: INBOX_MESSAGE_DEFINITION,
+    [INBOX_TABLE_REQUEST]: INBOX_REQUEST_DEFINITION,
+    [INBOX_TABLE_NOTICE]: INBOX_NOTICE_DEFINITION,
+});
+/**
+ * 在 DatabaseHost 上注册三张收件箱表（幂等：已定义或已启动的 host 跳过）。
+ * 必须在 host.start() 之前调用（define 在 started 后会抛错）。
+ */
+export function defineInboxTables(host) {
+    if (host.started)
+        return;
+    const existing = new Set(host.tables());
+    for (const [name, definition] of Object.entries(INBOX_TABLE_DEFINITIONS)) {
+        if (!existing.has(name))
+            host.define(name, definition);
+    }
+}
+/**
+ * 写一行收件箱记录；表未注册（或 host 未启动导致 model 缺失）时返回 false。
+ * 写失败向上抛，由调用方决定降级策略。
+ */
+export async function insertInboxRow(host, table, row) {
+    const model = host.models.get(table);
+    if (!model)
+        return false;
+    await model.insert(row);
+    return true;
+}
+/**
+ * Root 级事件发布口（console hub）。basic/cli console-api-installer 提供；
+ * 适配器等插件经 CapabilityContext.use 解析后 publish endpoint:request/notice 等事件。
+ */
+export const runtimeEventPublisherToken = createToken('zhin.runtime.event-publisher', 'Runtime event publisher (console SSE hub fan-out)');

package/lib/index.d.ts

@@ -1,13 +1,25 @@
+/** @internal Runtime 内部：CapabilitySlot（feature 与 projection 之间的载体）。 */
 export * from './capability.js';
 export * from './dispose.js';
 export * from './identity.js';
+export * from './generation-store.js';
 export * from './handoff.js';
+/** @public 用户侧创作面：`definePlugin`（`plugin.ts` 约定入口，承诺 semver）。 */
 export * from './plugin.js';
+/** @internal Runtime 内部：RootRuntime / RootController。 */
 export * from './root-controller.js';
 export * from './shared-lifetime.js';
+/** @internal Runtime 内部：SnapshotStore / RuntimeSnapshot。 */
 export * from './snapshot.js';
 export * from './token.js';
+/** @public Host token：`scheduleHostToken`（承诺 semver）。 */
 export * from './schedule-host.js';
+/** @public Host token：`databaseHostToken`（承诺 semver）。 */
 export * from './database-host.js';
+/** @public Host token：`agentToolsHostToken`（experimental）。 */
+export * from './agent-tools-host.js';
 export * from './html-renderer.js';
+/** @public Host token：`outboundHostToken`（承诺 semver）。 */
 export * from './outbound-host.js';
+export * from './inbox.js';
+export * from './system-log.js';

package/lib/index.js

@@ -1,13 +1,25 @@
+/** @internal Runtime 内部：CapabilitySlot（feature 与 projection 之间的载体）。 */
 export * from './capability.js';
 export * from './dispose.js';
 export * from './identity.js';
+export * from './generation-store.js';
 export * from './handoff.js';
+/** @public 用户侧创作面：`definePlugin`（`plugin.ts` 约定入口，承诺 semver）。 */
 export * from './plugin.js';
+/** @internal Runtime 内部：RootRuntime / RootController。 */
 export * from './root-controller.js';
 export * from './shared-lifetime.js';
+/** @internal Runtime 内部：SnapshotStore / RuntimeSnapshot。 */
 export * from './snapshot.js';
 export * from './token.js';
+/** @public Host token：`scheduleHostToken`（承诺 semver）。 */
 export * from './schedule-host.js';
+/** @public Host token：`databaseHostToken`（承诺 semver）。 */
 export * from './database-host.js';
+/** @public Host token：`agentToolsHostToken`（experimental）。 */
+export * from './agent-tools-host.js';
 export * from './html-renderer.js';
+/** @public Host token：`outboundHostToken`（承诺 semver）。 */
 export * from './outbound-host.js';
+export * from './inbox.js';
+export * from './system-log.js';

package/lib/plugin.d.ts

@@ -1,6 +1,6 @@
 import type { Dispose, DisposeStack } from './dispose.js';
 import type { GenerationHandoffRegistry } from './handoff.js';
-import type { PluginId } from './identity.js';
+import type { FeatureId, PluginId } from './identity.js';
 import type { Scope, Token } from './token.js';
 export interface PluginMetadata {
     readonly displayName?: string;
@@ -23,6 +23,11 @@ export interface PluginSetupContext<TConfig = unknown> {
     readonly resources: Scope;
     readonly lifecycle: DisposeStack;
     readonly handoff: GenerationHandoffRegistry;
+    /**
+     * Registers an in-memory definition through the same validation and
+     * projection transaction used by convention-discovered capabilities.
+     */
+    addFeature<TDefinition>(feature: FeatureId | string, localName: string, definition: TDefinition): void;
 }
 export interface PluginDefinition<TConfig = unknown> {
     readonly name: string;

package/lib/root-controller.d.ts

@@ -4,6 +4,11 @@ export type RootState = 'idle' | 'running' | 'stopping' | 'stopped' | 'failed';
 export type PrepareGeneration = (current: RuntimeSnapshot) => PreparedGeneration | Promise<PreparedGeneration>;
 export type PrepareTransaction = (current: RuntimeSnapshot) => PreparedGeneration | undefined | Promise<PreparedGeneration | undefined>;
 export type ControlErrorHandler = (error: unknown) => void;
+export interface GenerationCommitEvent {
+    readonly previous: RuntimeSnapshot;
+    readonly current: RuntimeSnapshot;
+}
+export type GenerationCommitListener = (event: GenerationCommitEvent) => void;
 export declare class RootController {
     #private;
     private readonly onControlError;
@@ -11,6 +16,8 @@ export declare class RootController {
     constructor(initial: SnapshotState, onControlError?: ControlErrorHandler);
     get state(): RootState;
     get generation(): number;
+    /** Observe successful generation commits, including the initial start. */
+    onGenerationCommit(listener: GenerationCommitListener): () => void;
     start(prepare: PrepareGeneration): Promise<RuntimeSnapshot>;
     transact(prepare: PrepareTransaction): Promise<RuntimeSnapshot>;
     reload(_target: PluginId | string, prepare: PrepareTransaction): Promise<RuntimeSnapshot>;

package/lib/root-controller.js

@@ -4,6 +4,7 @@ export class RootController {
     snapshots;
     #state = 'idle';
     #tail = Promise.resolve();
+    #generationCommitListeners = new Set();
     constructor(initial, onControlError = () => undefined) {
         this.onControlError = onControlError;
         this.snapshots = new SnapshotStore(initial);
@@ -14,6 +15,13 @@ export class RootController {
     get generation() {
         return this.snapshots.current.generation;
     }
+    /** Observe successful generation commits, including the initial start. */
+    onGenerationCommit(listener) {
+        this.#generationCommitListeners.add(listener);
+        return () => {
+            this.#generationCommitListeners.delete(listener);
+        };
+    }
     start(prepare) {
         return this.#enqueue(async () => {
             if (this.#state !== 'idle') {
@@ -27,11 +35,9 @@ export class RootController {
                     activated = true;
                     await prepared.handoff.activateNext();
                 }
-                const handoff = prepared.handoff;
-                const snapshot = this.snapshots.commit(0, prepared);
-                prepared = undefined;
                 this.#state = 'running';
-                this.#openNext(handoff);
+                const snapshot = this.#commitGeneration(0, prepared);
+                prepared = undefined;
                 return snapshot;
             }
             catch (error) {
@@ -59,10 +65,8 @@ export class RootController {
                     activated = true;
                     await prepared.handoff.activateNext();
                 }
-                const handoff = prepared.handoff;
-                const snapshot = this.snapshots.commit(previous.value.generation, prepared);
+                const snapshot = this.#commitGeneration(previous.value.generation, prepared);
                 prepared = undefined;
-                this.#openNext(handoff);
                 return snapshot;
             }
             catch (error) {
@@ -93,17 +97,38 @@ export class RootController {
         this.#tail = result.catch(() => undefined);
         return result;
     }
+    #commitGeneration(expectedGeneration, prepared) {
+        const previous = this.snapshots.current;
+        const snapshot = this.snapshots.commit(expectedGeneration, prepared);
+        this.#openNext(prepared.handoff);
+        const event = Object.freeze({ previous, current: snapshot });
+        const listeners = [...this.#generationCommitListeners];
+        queueMicrotask(() => {
+            for (const listener of listeners) {
+                try {
+                    listener(event);
+                }
+                catch (error) {
+                    this.#reportControlError(error);
+                }
+            }
+        });
+        return snapshot;
+    }
     #openNext(handoff) {
         try {
             handoff?.openNext();
         }
         catch (error) {
-            try {
-                this.onControlError(error);
-            }
-            catch {
-                // Error reporting cannot roll back an already committed generation.
-            }
+            this.#reportControlError(error);
+        }
+    }
+    #reportControlError(error) {
+        try {
+            this.onControlError(error);
+        }
+        catch {
+            // Error reporting cannot roll back an already committed generation.
         }
     }
     async #rollback(prepared, state, transactionError) {

package/lib/system-log.d.ts

@@ -0,0 +1,19 @@
+import type { DatabaseHost } from './database-host.js';
+/**
+ * 系统日志表（console logs 页数据源）定义与写入辅助。
+ *
+ * 列结构对齐 packages/im/core/src/models/system-log.ts（legacy SystemLogDefinition，
+ * 读取端为 packages/host/http console-rest-pages registerLogsRoutes）。
+ */
+export declare const SYSTEM_LOG_TABLE = "SystemLog";
+export declare const SYSTEM_LOG_DEFINITION: Record<string, unknown>;
+/**
+ * 在 DatabaseHost 上注册系统日志表（幂等：已定义或已启动的 host 跳过）。
+ * 必须在 host.start() 之前调用（define 在 started 后会抛错）。
+ */
+export declare function defineSystemLogTable(host: Pick<DatabaseHost, 'define' | 'tables' | 'started'>): void;
+/**
+ * 写一行系统日志；表未注册（或 host 未启动导致 model 缺失）时返回 false。
+ * 写失败向上抛，由调用方决定降级策略。
+ */
+export declare function insertSystemLogRow(host: Pick<DatabaseHost, 'models'>, row: Record<string, unknown>): Promise<boolean>;

package/lib/system-log.js

@@ -0,0 +1,37 @@
+/**
+ * 系统日志表（console logs 页数据源）定义与写入辅助。
+ *
+ * 列结构对齐 packages/im/core/src/models/system-log.ts（legacy SystemLogDefinition，
+ * 读取端为 packages/host/http console-rest-pages registerLogsRoutes）。
+ */
+export const SYSTEM_LOG_TABLE = 'SystemLog';
+export const SYSTEM_LOG_DEFINITION = {
+    id: { type: 'integer', primary: true, autoIncrement: true },
+    level: { type: 'text', nullable: false },
+    name: { type: 'text', nullable: false },
+    message: { type: 'text', nullable: false },
+    source: { type: 'text', nullable: false },
+    timestamp: { type: 'date', nullable: false },
+};
+/**
+ * 在 DatabaseHost 上注册系统日志表（幂等：已定义或已启动的 host 跳过）。
+ * 必须在 host.start() 之前调用（define 在 started 后会抛错）。
+ */
+export function defineSystemLogTable(host) {
+    if (host.started)
+        return;
+    if (!host.tables().includes(SYSTEM_LOG_TABLE)) {
+        host.define(SYSTEM_LOG_TABLE, SYSTEM_LOG_DEFINITION);
+    }
+}
+/**
+ * 写一行系统日志；表未注册（或 host 未启动导致 model 缺失）时返回 false。
+ * 写失败向上抛，由调用方决定降级策略。
+ */
+export async function insertSystemLogRow(host, row) {
+    const model = host.models.get(SYSTEM_LOG_TABLE);
+    if (!model)
+        return false;
+    await model.insert(row);
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/plugin-runtime",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Zero-dependency Plugin tree, Scope and atomic generation runtime for Zhin",
   "type": "module",
   "main": "./lib/index.js",