@zhin.js/core 1.3.4 → 1.4.0

package/lib/plugin-runtime/im/outbound-segments.js

@@ -0,0 +1,59 @@
+import { htmlToFallbackText } from '../../built/html-to-text.js';
+const DEFAULT_CARD_WIDTH = 540;
+const DEFAULT_CARD_FILENAME = 'card.png';
+export function isOutboundSegment(value) {
+    return typeof value === 'object'
+        && value !== null
+        && !Array.isArray(value)
+        && typeof value.type === 'string';
+}
+/**
+ * Normalize a rendered outbound payload to wire segments:
+ * - segment arrays stay arrays (html segments converted per element);
+ * - a single segment object is wrapped into a one-element array;
+ * - anything else (plain strings, legacy `{ text }` shorthands) passes through.
+ */
+export async function normalizeOutboundPayload(payload, renderer) {
+    if (Array.isArray(payload)) {
+        return Promise.all(payload.map((item) => normalizeOutboundSegment(item, renderer)));
+    }
+    if (isOutboundSegment(payload)) {
+        return [await normalizeOutboundSegment(payload, renderer)];
+    }
+    return payload;
+}
+async function normalizeOutboundSegment(segment, renderer) {
+    if (!isOutboundSegment(segment) || segment.type !== 'html')
+        return segment;
+    const data = segment.data ?? {};
+    const html = typeof data.html === 'string' ? data.html : '';
+    if (html && renderer) {
+        try {
+            const result = await renderer.render(html, {
+                width: typeof data.width === 'number' ? data.width : DEFAULT_CARD_WIDTH,
+                format: 'png',
+                ...(typeof data.backgroundColor === 'string'
+                    ? { backgroundColor: data.backgroundColor }
+                    : {}),
+            });
+            if (result.format === 'png' && result.data && typeof result.data === 'object') {
+                return {
+                    type: 'image',
+                    data: {
+                        base64: Buffer.from(result.data).toString('base64'),
+                        name: typeof data.fileName === 'string' ? data.fileName : DEFAULT_CARD_FILENAME,
+                    },
+                };
+            }
+        }
+        catch {
+            // 渲染失败 → 文本降级
+        }
+    }
+    return { type: 'text', data: { text: htmlSegmentFallbackText(data, html) } };
+}
+function htmlSegmentFallbackText(data, html) {
+    if (typeof data.text === 'string' && data.text.length > 0)
+        return data.text;
+    return html ? htmlToFallbackText(html) : '';
+}

package/lib/plugin.d.ts

@@ -180,6 +180,7 @@ export declare namespace Plugin {
         'message.send': [MessageSendPayload];
         "message.receive": [import('./message.js').Message];
         "endpoint.login.pending": [import('./built/login-assist.js').PendingLoginTask];
+        "endpoint.login.expired": [import('./built/login-assist.js').PendingLoginTask];
         'endpoint.connect': [import('./built/endpoint-lifecycle.js').EndpointLifecyclePayload];
         'endpoint.disconnect': [import('./built/endpoint-lifecycle.js').EndpointLifecyclePayload];
         'endpoint.error': [import('./built/endpoint-lifecycle.js').EndpointLifecyclePayload];

package/lib/tool-zod.d.ts

@@ -10,9 +10,24 @@
  *   const tool = createToolFromZod('my_tool', '描述', z.object({ id: z.string() }), async (args) => { ... });
  *   plugin.addTool(tool);
  */
-import type { Tool } from './types.js';
+import type { Tool, ToolParametersSchema } from './types.js';
 import type { Message } from './message.js';
 type MaybePromise<T> = T | Promise<T>;
+export type ToolSchemaParseResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Normalize a JSON Schema or Zod object schema into the canonical Core tool
+ * parameter schema. Zod remains an optional peer: this adapter uses only its
+ * public instance methods and retains a structural fallback for Zod 3.
+ */
+export declare function toolInputSchemaToParameters(schema: unknown): ToolParametersSchema;
+/** Validate input with a Zod-like schema, or pass it through for JSON Schema. */
+export declare function parseToolInputSchema<T>(schema: unknown, input: unknown): ToolSchemaParseResult<T>;
 export interface CreateToolFromZodOptions {
     tags?: string[];
     keywords?: string[];

package/lib/tool-zod.js

@@ -10,62 +10,151 @@
  *   const tool = createToolFromZod('my_tool', '描述', z.object({ id: z.string() }), async (args) => { ... });
  *   plugin.addTool(tool);
  */
-function zodFieldToJsonSchema(z) {
-    if (!z || !z._def)
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function getShape(schema) {
+    const shape = schema?.shape;
+    if (typeof shape === 'function') {
+        const value = shape();
+        return isRecord(value) ? value : undefined;
+    }
+    return isRecord(shape) ? shape : undefined;
+}
+function acceptsUndefined(schema) {
+    const candidate = schema;
+    if (typeof candidate?.safeParse === 'function') {
+        try {
+            return candidate.safeParse(undefined).success;
+        }
+        catch {
+            // Fall through to structural compatibility for non-Zod lookalikes.
+        }
+    }
+    const def = candidate?._def;
+    const kind = def?.typeName ?? def?.type;
+    return kind === 'ZodOptional'
+        || kind === 'ZodDefault'
+        || kind === 'optional'
+        || kind === 'default';
+}
+function requiredFromShape(schema, fallback) {
+    const shape = getShape(schema);
+    if (!shape)
+        return fallback?.length ? [...fallback] : undefined;
+    const required = Object.entries(shape)
+        .filter(([, field]) => !acceptsUndefined(field))
+        .map(([key]) => key);
+    return required.length ? required : undefined;
+}
+function descriptionOf(schema, def) {
+    const description = schema?.description ?? def.description;
+    return typeof description === 'string' ? description : undefined;
+}
+function zodFieldToJsonSchema(schema) {
+    const candidate = schema;
+    const def = candidate?._def;
+    if (!isRecord(def))
         return { type: 'string' };
-    const def = z._def;
-    const typeName = def.typeName;
-    if (typeName === 'ZodOptional' || typeName === 'ZodDefault') {
-        const inner = def.innerType ?? def.type;
-        return zodFieldToJsonSchema(inner);
+    const kind = def.typeName ?? def.type;
+    if (kind === 'ZodOptional' || kind === 'ZodDefault' || kind === 'optional' || kind === 'default') {
+        return zodFieldToJsonSchema(def.innerType ?? def.type);
     }
-    if (typeName === 'ZodString') {
-        const out = { type: 'string' };
-        if (def.description)
-            out.description = def.description;
-        return out;
+    const description = descriptionOf(schema, def);
+    const withDescription = (type) => description
+        ? { type, description }
+        : { type };
+    if (kind === 'ZodString' || kind === 'string')
+        return withDescription('string');
+    if (kind === 'ZodNumber' || kind === 'number')
+        return withDescription('number');
+    if (kind === 'ZodBoolean' || kind === 'boolean')
+        return withDescription('boolean');
+    if (kind === 'ZodEnum' || kind === 'enum') {
+        const values = Array.isArray(def.values)
+            ? def.values
+            : isRecord(def.entries)
+                ? Object.values(def.entries)
+                : [];
+        return { ...withDescription('string'), enum: values };
     }
-    if (typeName === 'ZodNumber') {
-        const out = { type: 'number' };
-        if (def.description)
-            out.description = def.description;
-        return out;
+    if (kind === 'ZodArray' || kind === 'array') {
+        return {
+            ...withDescription('array'),
+            items: zodFieldToJsonSchema(def.element ?? def.type),
+        };
     }
-    if (typeName === 'ZodBoolean') {
-        const out = { type: 'boolean' };
-        if (def.description)
-            out.description = def.description;
-        return out;
+    if (kind === 'ZodObject' || kind === 'object') {
+        return toolInputSchemaToParameters(schema);
     }
-    if (typeName === 'ZodEnum') {
-        return { type: 'string', enum: def.values };
+    return withDescription('string');
+}
+function isJsonObjectSchema(schema) {
+    if (!isRecord(schema) || schema.type !== 'object')
+        return false;
+    return typeof schema.safeParse !== 'function';
+}
+function fromNativeJsonSchema(schema) {
+    const candidate = schema;
+    if (typeof candidate?.toJSONSchema !== 'function')
+        return undefined;
+    try {
+        const converted = candidate.toJSONSchema();
+        if (!isRecord(converted) || converted.type !== 'object')
+            return undefined;
+        return {
+            ...converted,
+            type: 'object',
+            properties: isRecord(converted.properties)
+                ? converted.properties
+                : {},
+            required: requiredFromShape(schema, Array.isArray(converted.required)
+                ? converted.required.filter((key) => typeof key === 'string')
+                : undefined),
+        };
     }
-    if (typeName === 'ZodArray') {
-        return { type: 'array', items: zodFieldToJsonSchema(def.type ?? def.element) };
+    catch {
+        return undefined;
     }
-    return { type: 'string' };
 }
-function zodToJsonSchema(schema) {
-    const result = {
+/**
+ * Normalize a JSON Schema or Zod object schema into the canonical Core tool
+ * parameter schema. Zod remains an optional peer: this adapter uses only its
+ * public instance methods and retains a structural fallback for Zod 3.
+ */
+export function toolInputSchemaToParameters(schema) {
+    if (isJsonObjectSchema(schema))
+        return schema;
+    const native = fromNativeJsonSchema(schema);
+    if (native)
+        return native;
+    const shape = getShape(schema);
+    const properties = {};
+    if (shape) {
+        for (const [key, value] of Object.entries(shape)) {
+            properties[key] = zodFieldToJsonSchema(value);
+        }
+    }
+    return {
         type: 'object',
-        properties: {},
-        required: [],
+        properties: properties,
+        required: requiredFromShape(schema),
     };
-    if (!schema || !schema.shape)
-        return result;
-    const shape = schema.shape;
-    const properties = result.properties;
-    const required = [];
-    for (const [key, value] of Object.entries(shape)) {
-        const zodValue = value;
-        properties[key] = zodFieldToJsonSchema(zodValue);
-        const typeName = zodValue?._def?.typeName;
-        if (typeName !== 'ZodOptional' && typeName !== 'ZodDefault') {
-            required.push(key);
-        }
+}
+/** Validate input with a Zod-like schema, or pass it through for JSON Schema. */
+export function parseToolInputSchema(schema, input) {
+    const candidate = schema;
+    if (typeof candidate?.safeParse !== 'function') {
+        return { ok: true, data: input };
     }
-    result.required = required.length > 0 ? required : undefined;
-    return result;
+    const parsed = candidate.safeParse(input);
+    if (parsed.success)
+        return { ok: true, data: parsed.data };
+    const issues = parsed.error?.issues ?? parsed.error?.errors ?? [];
+    const error = issues
+        .map((issue) => `${(issue.path ?? []).join('.') || 'root'}: ${issue.message ?? 'invalid'}`)
+        .join('; ');
+    return { ok: false, error: error || 'Invalid arguments' };
 }
 /**
  * 从 Zod 模式创建 Tool，便于类型安全与校验。
@@ -75,17 +164,15 @@ export function createToolFromZod(name, description, schema, execute, options) {
     if (!schema?.safeParse) {
         throw new Error('createToolFromZod: schema must be a Zod object schema (e.g. z.object({ ... })). Install zod: pnpm add zod');
     }
-    const parameters = zodToJsonSchema(schema);
+    const parameters = toolInputSchemaToParameters(schema);
     return {
         name,
         description,
         parameters,
         execute: async (args, message) => {
-            const parsed = schema.safeParse(args);
-            if (!parsed.success) {
-                const msg = parsed.error.errors?.map((e) => `${e.path?.join('.') ?? 'root'}: ${e instanceof Error ? e.message : String(e)}`).join('; ') ?? 'Invalid arguments';
-                return `Error: ${msg}`;
-            }
+            const parsed = parseToolInputSchema(schema, args);
+            if (!parsed.ok)
+                return `Error: ${parsed.error}`;
             return execute(parsed.data, message);
         },
         tags: options?.tags,

package/lib/utils.d.ts

@@ -17,6 +17,9 @@ import type { ButtonData, KeyboardFallback, KeyboardSegmentData } from "./built/
 import type { MediaRef } from "./built/segment-contract/types.js";
 /**
  * 组合中间件,洋葱模型
+ *
+ * 空中间件列表时必须仍调用 `next`——入站管线把 MessageDispatcher
+ * 作为 terminal next 传入；吞掉 next 会导致命令/AI 永远不跑。
  */
 export declare function compose<P extends RegisteredAdapter = RegisteredAdapter>(middlewares: MessageMiddleware<P>[]): (message: Message<AdapterMessage<P>>, next?: () => Promise<void>) => Promise<void>;
 export declare function segment<T extends object>(type: string, data: T): {

package/lib/utils.js

@@ -15,12 +15,15 @@ import { KeyboardSegment } from "./built/interactive-segments/keyboard-segment.j
 import { ButtonSpec, normalizeKeyboardRows } from "./built/interactive-segments/button-spec.js";
 /**
  * 组合中间件,洋葱模型
+ *
+ * 空中间件列表时必须仍调用 `next`——入站管线把 MessageDispatcher
+ * 作为 terminal next 传入；吞掉 next 会导致命令/AI 永远不跑。
  */
 export function compose(middlewares) {
-    if (middlewares.length === 0) {
-        return () => Promise.resolve();
-    }
     return function (message, next = () => Promise.resolve()) {
+        if (middlewares.length === 0) {
+            return next();
+        }
         let index = -1;
         const dispatch = async (i = 0) => {
             if (i <= index) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/core",
-  "version": "1.3.4",
+  "version": "1.4.0",
   "description": "Zhin机器人核心框架",
   "type": "module",
   "main": "./lib/index.js",
@@ -21,6 +21,11 @@
       "development": "./src/built/queue-im-field-contract.ts",
       "import": "./lib/built/queue-im-field-contract.js"
     },
+    "./runtime": {
+      "types": "./lib/plugin-runtime/im/index.d.ts",
+      "development": "./src/plugin-runtime/im/index.ts",
+      "import": "./lib/plugin-runtime/im/index.js"
+    },
     "./jsx": {
       "types": "./lib/jsx.d.ts",
       "development": "./src/jsx.ts",
@@ -45,9 +50,14 @@
     "segment-matcher": "^1.0.5",
     "smol-toml": "^1.7.0",
     "yaml": "^2.9.0",
-    "@zhin.js/kernel": "1.0.3",
-    "@zhin.js/database": "1.0.76",
-    "@zhin.js/logger": "1.0.74",
+    "@zhin.js/adapter": "1.1.0",
+    "@zhin.js/command": "1.0.2",
+    "@zhin.js/component": "1.0.2",
+    "@zhin.js/database": "1.0.77",
+    "@zhin.js/kernel": "1.0.4",
+    "@zhin.js/logger": "1.0.75",
+    "@zhin.js/middleware": "1.0.2",
+    "@zhin.js/plugin-runtime": "1.1.0",
     "@zhin.js/schema": "1.0.71"
   },
   "peerDependencies": {
@@ -61,8 +71,9 @@
   "devDependencies": {
     "@types/node": "^26.1.0",
     "@types/qrcode": "^1.5.5",
+    "ajv": "8.18.0",
     "typescript": "^6.0.3",
-    "@zhin.js/ai": "1.4.4"
+    "@zhin.js/ai": "1.4.5"
   },
   "repository": {
     "type": "git",