@zhin.js/runtime 1.0.17 → 1.0.19

package/lib/config-composer.d.ts

@@ -23,6 +23,8 @@ export declare class ConfigValidationError extends Error {
     source?: string | undefined);
 }
 export declare class ConfigComposer {
+    private readonly inactivePluginInstanceKeys;
+    constructor(inactivePluginInstanceKeys?: readonly string[]);
     compose(graph: ProjectGraph, input?: RuntimeConfigDocument, 
     /** Source config file name, annotated on ConfigValidationError. */
     source?: string): Promise<ComposedConfig>;

package/lib/config-composer.js

@@ -36,6 +36,10 @@ export class ConfigValidationError extends Error {
     }
 }
 export class ConfigComposer {
+    inactivePluginInstanceKeys;
+    constructor(inactivePluginInstanceKeys = []) {
+        this.inactivePluginInstanceKeys = inactivePluginInstanceKeys;
+    }
     async compose(graph, input = {}, 
     /** Source config file name, annotated on ConfigValidationError. */
     source) {
@@ -61,7 +65,10 @@ export class ConfigComposer {
                     type: 'object',
                     additionalProperties: false,
                     default: {},
-                    properties: Object.fromEntries(childSchemas.map(([key, schema]) => [key, withDefault(schema)])),
+                    properties: Object.fromEntries([
+                        ...this.inactivePluginInstanceKeys.map((key) => [key, {}]),
+                        ...childSchemas.map(([key, schema]) => [key, withDefault(schema)]),
+                    ]),
                 },
             },
         });

package/lib/host-config-schema.json

@@ -3,7 +3,42 @@
     "type": "object",
     "additionalProperties": false,
     "properties": {
-        "http": { "type": "object", "additionalProperties": true, "description": "HTTP, Console, REST/RPC/SSE, and Webhook Host.", "x-descriptionZh": "HTTP、Console、REST/RPC/SSE 与 Webhook Host。" },
+        "http": {
+            "type": "object", "additionalProperties": true,
+            "description": "HTTP, Console, REST/RPC/SSE, and Webhook Host.",
+            "x-descriptionZh": "HTTP、Console、REST/RPC/SSE 与 Webhook Host。",
+            "properties": {
+                "readiness": {
+                    "type": "object", "additionalProperties": false,
+                    "description": "Required runtime components for /pub/ready; no external network probes.",
+                    "x-descriptionZh": "/pub/ready 要求就绪的运行时组件；不执行外部网络探测。",
+                    "properties": {
+                        "database": {
+                            "type": "boolean", "default": true,
+                            "description": "Require an initialized Database Host (not a live database query).",
+                            "x-descriptionZh": "要求 Database Host 已初始化（不执行实时数据库查询）。"
+                        },
+                        "endpoints": {
+                            "type": "array", "uniqueItems": true,
+                            "description": "Required Endpoint admission slots, selected by exact plugin owner and stable slot name.",
+                            "x-descriptionZh": "必须开放入站的 Endpoint，按插件 owner 与稳定槽名精确选择。",
+                            "items": {
+                                "type": "object", "additionalProperties": false, "required": ["owner", "name"],
+                                "properties": {
+                                    "owner": { "type": "string", "pattern": "^root(?:/[a-z0-9][a-z0-9-]*)*$" },
+                                    "name": { "type": "string", "minLength": 1, "pattern": "^[^\\u0000]+$" }
+                                }
+                            }
+                        },
+                        "agents": {
+                            "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 },
+                            "description": "Required configured Agent bindings; does not verify model credentials or provider reachability.",
+                            "x-descriptionZh": "必须存在的 Agent binding；不验证模型凭据或 Provider 网络可用性。"
+                        }
+                    }
+                }
+            }
+        },
         "database": { "type": "object", "additionalProperties": true, "description": "Database Host and dialect connection options.", "x-descriptionZh": "Database Host 与方言连接参数。" },
         "ai": {
             "type": "object",
@@ -160,7 +195,72 @@
         "mcp": { "type": "object", "additionalProperties": true, "description": "Expose Bot tools through an MCP Server.", "x-descriptionZh": "把 Bot 工具公开为 MCP Server。" },
         "a2a": { "type": "object", "additionalProperties": true, "description": "A2A Agent Card, remote execution, and Workroom callbacks.", "x-descriptionZh": "A2A Agent Card、远程执行与 Workroom 回调。" },
         "speech": { "type": "object", "additionalProperties": true, "description": "Speech-to-text and text-to-speech Host.", "x-descriptionZh": "语音识别与语音合成 Host。" },
-        "htmlRenderer": { "type": "object", "additionalProperties": true, "description": "HTML and image rendering options.", "x-descriptionZh": "HTML/图片渲染参数。" },
+        "htmlRenderer": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "HTML and image rendering options backed by Shotium.",
+            "x-descriptionZh": "基于 Shotium 的 HTML/图片渲染参数。",
+            "properties": {
+                "width": { "type": "number", "minimum": 1, "maximum": 30000, "description": "Default layout width in CSS pixels.", "x-descriptionZh": "默认排版宽度（CSS 像素）。" },
+                "defaultWidth": { "type": "number", "minimum": 1, "maximum": 30000, "description": "Legacy alias of width.", "x-descriptionZh": "width 的旧别名。" },
+                "viewport": {
+                    "type": "object",
+                    "additionalProperties": true,
+                    "description": "Default viewport for Shotium rendering.",
+                    "x-descriptionZh": "Shotium 渲染默认视窗。",
+                    "properties": {
+                        "width": { "type": "number", "minimum": 1, "maximum": 30000, "description": "Viewport width in CSS pixels.", "x-descriptionZh": "视窗宽度（CSS 像素）。" },
+                        "height": { "type": "number", "minimum": 1, "maximum": 30000, "description": "Viewport height in CSS pixels.", "x-descriptionZh": "视窗高度（CSS 像素）。" }
+                    }
+                },
+                "backgroundColor": { "type": "string", "description": "Fragment background color.", "x-descriptionZh": "HTML 片段背景色。" },
+                "defaultBackgroundColor": { "type": "string", "description": "Legacy alias of backgroundColor.", "x-descriptionZh": "backgroundColor 的旧别名。" },
+                "scale": { "type": "number", "minimum": 0.01, "maximum": 8, "description": "Device scale factor.", "x-descriptionZh": "设备像素比。" },
+                "type": { "type": "string", "enum": ["png", "jpeg", "webp"], "description": "Default raster output format.", "x-descriptionZh": "默认位图输出格式。" },
+                "quality": { "type": "number", "minimum": 1, "maximum": 100, "description": "Quality for jpeg/webp output.", "x-descriptionZh": "jpeg/webp 输出质量。" },
+                "timeout": { "type": "number", "minimum": 1, "maximum": 600000, "description": "Navigation timeout in milliseconds.", "x-descriptionZh": "导航超时（毫秒）。" },
+                "waitUntil": { "type": "string", "enum": ["load", "networkidle"], "description": "Navigation wait strategy.", "x-descriptionZh": "导航等待策略。" },
+                "fontFamily": { "type": "string", "description": "Default font-family for fragments.", "x-descriptionZh": "HTML 片段默认字体栈。" },
+                "maxImageHeight": { "type": "number", "minimum": 0, "maximum": 100000, "description": "Split overly tall PNGs above this height; 0 disables splitting.", "x-descriptionZh": "超过该高度时切分 PNG；0 表示不切分。" },
+                "sliceCompression": { "type": "number", "minimum": 0, "maximum": 9, "description": "Compression level used when splitting PNGs.", "x-descriptionZh": "PNG 切片时使用的压缩级别。" },
+                "allowFileAccess": { "type": "boolean", "description": "Allow local file subresources.", "x-descriptionZh": "允许访问本地文件子资源。" },
+                "takeOverHtmlSegments": { "type": "boolean", "description": "Take over html/markdown rich-segment image rendering.", "x-descriptionZh": "接管 html/markdown 富媒体段转图。" },
+                "cacheDir": { "type": "string", "description": "HTTP cache directory; use off to disable.", "x-descriptionZh": "HTTP 缓存目录；off 表示关闭。" },
+                "cacheMaxBytes": { "type": "number", "minimum": 0, "description": "Maximum HTTP cache size in bytes.", "x-descriptionZh": "HTTP 缓存最大字节数。" },
+                "userAgent": { "type": "string", "description": "Custom user agent string.", "x-descriptionZh": "自定义 User-Agent。" },
+                "idleTimeoutMs": { "type": "number", "minimum": 0, "maximum": 86400000, "description": "Daemon idle-exit timeout in milliseconds.", "x-descriptionZh": "daemon 空闲退出超时（毫秒）。" },
+                "logStats": { "type": "boolean", "description": "Log render timing statistics.", "x-descriptionZh": "记录渲染耗时统计。" },
+                "mode": { "type": "string", "enum": ["inprocess", "daemon"], "description": "Whether Shotium runs in-process or as a daemon.", "x-descriptionZh": "Shotium 在进程内运行还是以 daemon 运行。" },
+                "aiTextAsImage": {
+                    "anyOf": [
+                        { "type": "boolean" },
+                        {
+                            "type": "object",
+                            "additionalProperties": true,
+                            "description": "Convert plain text output to an image before send.",
+                            "x-descriptionZh": "发送前将纯文本输出转成图片。",
+                            "properties": {
+                                "enabled": { "type": "boolean", "description": "Enable text-to-image conversion.", "x-descriptionZh": "启用文本转图片。" },
+                                "onlyAdapters": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true, "description": "Only apply to these adapter names.", "x-descriptionZh": "仅对这些适配器名称生效。" },
+                                "minLength": { "type": "number", "minimum": 1, "description": "Minimum plain-text length to trigger conversion; defaults to 1 at runtime.", "x-descriptionZh": "触发转换的最小纯文本长度；运行时默认为 1。" },
+                                "maxLength": { "type": "number", "minimum": 1, "description": "Maximum plain-text length to convert; defaults to 12000 at runtime.", "x-descriptionZh": "允许转换的最大纯文本长度；运行时默认为 12000。" },
+                                "skipIfRich": { "type": "boolean", "description": "Skip when content already contains rich segments; defaults to true at runtime.", "x-descriptionZh": "内容已包含富媒体段时跳过；运行时默认为 true。" },
+                                "width": { "type": "number", "minimum": 1, "maximum": 30000, "description": "Image width in CSS pixels.", "x-descriptionZh": "图片宽度（CSS 像素）。" },
+                                "height": { "type": "number", "minimum": 1, "maximum": 30000, "description": "Image height in CSS pixels.", "x-descriptionZh": "图片高度（CSS 像素）。" },
+                                "backgroundColor": { "type": "string", "description": "Image background color.", "x-descriptionZh": "图片背景色。" },
+                                "fontSize": { "type": "number", "minimum": 1, "description": "Font size in CSS pixels.", "x-descriptionZh": "字体大小（CSS 像素）。" },
+                                "color": { "type": "string", "description": "Text color.", "x-descriptionZh": "文字颜色。" },
+                                "padding": { "type": "number", "minimum": 0, "description": "Image padding in CSS pixels.", "x-descriptionZh": "图片内边距（CSS 像素）。" },
+                                "scale": { "type": "number", "minimum": 0.01, "maximum": 8, "description": "Device scale factor.", "x-descriptionZh": "设备像素比。" },
+                                "fileName": { "type": "string", "minLength": 1, "description": "Image file name.", "x-descriptionZh": "图片文件名。" }
+                            }
+                        }
+                    ],
+                    "description": "Optional plain-text to image conversion before send.",
+                    "x-descriptionZh": "发送前可选的纯文本转图片。"
+                }
+            }
+        },
         "assistant": { "type": "object", "additionalProperties": true, "description": "Scheduled jobs, event ingress, and failure notifications.", "x-descriptionZh": "调度任务、事件入口和失败通知。" },
         "log_level": { "type": ["string", "number"], "description": "Runtime log level.", "x-descriptionZh": "Runtime 日志级别。" },
         "plugin": { "type": "object", "description": "Root Plugin configuration; replaced by its project schema during composition.", "x-descriptionZh": "Root Plugin 配置；组合时由项目 Schema 替换。" }

package/lib/project-graph.d.ts

@@ -20,6 +20,7 @@ export interface ProjectGraph {
 }
 export interface ProjectGraphServiceOptions {
     readonly engineVersion?: string;
+    readonly disabledPluginInstanceKeys?: readonly string[];
 }
 export declare class ProjectGraphError extends Error {
     constructor(message: string);

package/lib/project-graph.js

@@ -11,11 +11,15 @@ export class ProjectGraphError extends Error {
 export class ProjectGraphService {
     #resolver;
     #engineVersion;
+    #disabledPluginInstanceKeys;
     constructor(resolver, engineVersionOrOptions = runtimeEngineVersion) {
         this.#resolver = resolver;
         this.#engineVersion = typeof engineVersionOrOptions === 'string'
             ? engineVersionOrOptions
             : (engineVersionOrOptions.engineVersion ?? runtimeEngineVersion);
+        this.#disabledPluginInstanceKeys = new Set(typeof engineVersionOrOptions === 'string'
+            ? []
+            : (engineVersionOrOptions.disabledPluginInstanceKeys ?? []));
     }
     async inspect(projectRoot) {
         const rootPackage = await this.#resolver.root(projectRoot);
@@ -58,6 +62,9 @@ export class ProjectGraphService {
                 pluginRefs = mergeChildPluginReferences(manifest.plugins, inheritedPlugins);
             }
         }
+        if (isRoot && this.#disabledPluginInstanceKeys.size > 0) {
+            pluginRefs = pluginRefs.filter((reference) => !this.#disabledPluginInstanceKeys.has(reference.instanceKey));
+        }
         const featurePackages = new Set();
         const features = await Promise.all(featureRefs.map(async (reference) => {
             if (featurePackages.has(reference.package)) {

package/lib/root-runtime.d.ts

@@ -21,6 +21,7 @@ export interface RootRuntimeOptions {
     readonly installResources?: RootResourceInstaller;
     readonly isolation?: IsolatedPluginRuntimePort;
     readonly onControlError?: ControlErrorHandler;
+    readonly disabledPluginInstanceKeys?: readonly string[];
 }
 export type RootHmrOptions = Omit<HmrCoordinatorOptions, 'modules' | 'ownership' | 'runtime'>;
 export declare class RootRuntime {

package/lib/root-runtime.js

@@ -37,6 +37,7 @@ export class RootRuntime {
     #configPatchTail = Promise.resolve();
     #stopResult;
     #controller;
+    #disabledPluginInstanceKeys;
     constructor(options) {
         this.#projectRoot = resolve(options.projectRoot);
         this.#modules = options.modules;
@@ -50,6 +51,7 @@ export class RootRuntime {
             this.#configDocument = structuredClone(options.config ?? {});
         this.#installResources = options.installResources;
         this.#isolation = options.isolation;
+        this.#disabledPluginInstanceKeys = Object.freeze([...(options.disabledPluginInstanceKeys ?? [])]);
         this.#controller = new RootController(emptyState(), options.onControlError, Object.freeze({ ownership: SourceOwnershipIndex.empty() }));
     }
     get snapshot() {
@@ -187,7 +189,9 @@ export class RootRuntime {
     }
     async #inspectProject() {
         const resolver = await NodePackageResolver.create(this.#projectRoot);
-        const graph = await new ProjectGraphService(resolver).inspect(this.#projectRoot);
+        const graph = await new ProjectGraphService(resolver, {
+            disabledPluginInstanceKeys: this.#disabledPluginInstanceKeys,
+        }).inspect(this.#projectRoot);
         await this.#refreshConfigDocument();
         if (this.#configResolver) {
             return {
@@ -196,7 +200,8 @@ export class RootRuntime {
                 primaryConfigDocument: Object.freeze({}),
             };
         }
-        const composed = await new ConfigComposer().compose(graph, this.#configDocument);
+        const composed = await new ConfigComposer(this.#disabledPluginInstanceKeys)
+            .compose(graph, this.#configDocument);
         return {
             graph,
             configResolver: this.#configViewResolver(composed.views),
@@ -243,8 +248,10 @@ export class RootRuntime {
             let prepared;
             signal.throwIfAborted();
             const resolver = await NodePackageResolver.create(this.#projectRoot);
-            const graph = await new ProjectGraphService(resolver).inspect(this.#projectRoot);
-            const planned = await new ConfigPatchPlanner().plan(graph, currentDocument, patches);
+            const graph = await new ProjectGraphService(resolver, {
+                disabledPluginInstanceKeys: this.#disabledPluginInstanceKeys,
+            }).inspect(this.#projectRoot);
+            const planned = await new ConfigPatchPlanner(new ConfigComposer(this.#disabledPluginInstanceKeys)).plan(graph, currentDocument, patches);
             plan = planned;
             if (!planned.documentChanged)
                 return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/runtime",
-  "version": "1.0.17",
+  "version": "1.0.19",
   "description": "Static Plugin graph, generation transaction and HMR Root runtime for Zhin.js",
   "type": "module",
   "main": "./lib/index.js",
@@ -24,9 +24,9 @@
   "devDependencies": {
     "@types/node": "^26.1.2",
     "typescript": "^6.0.3",
-    "@zhin.js/adapter": "1.2.1",
-    "@zhin.js/command": "1.0.16",
+    "@zhin.js/adapter": "1.2.2",
     "@zhin.js/agent-feature": "1.0.13",
+    "@zhin.js/command": "1.0.16",
     "@zhin.js/component": "1.0.13",
     "@zhin.js/layout": "1.0.13",
     "@zhin.js/mcp-feature": "1.0.13",