@zhin.js/core 1.4.0 → 1.4.2

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

@@ -1,6 +1,30 @@
 import { htmlToFallbackText } from '../../built/html-to-text.js';
+import { toCanonicalSegments } from '../../built/generic-segment-mapper.js';
+import { effectiveKeyboardFallbackMap, renderKeyboardAsText, } from '../../built/interactive-segments/resolve.js';
+import { DEFAULT_INTERACTIVE_POLICY, isKeyboardSegment, } from '../../built/interactive-segments/types.js';
+import { isMediaRef } from '../../built/segment-contract/index.js';
 const DEFAULT_CARD_WIDTH = 540;
 const DEFAULT_CARD_FILENAME = 'card.png';
+const DEFAULT_MEDIA_POLICY = 'base64';
+/** 平台名 → 出站媒体策略（任务 C 声明式 policy 落地前的内置来源）。 */
+const OUTBOUND_MEDIA_POLICY_BY_ADAPTER = { qq: 'base64',
+    icqq: 'base64',
+    slack: 'base64',
+    'weixin-ilink': 'base64',
+    telegram: 'url-or-text',
+    line: 'url-or-text',
+    lark: 'url-or-text',
+    kook: 'url-or-text',
+    dingtalk: 'url-or-text',
+    'wechat-mp': 'url-or-text',
+    wecom: 'url-or-text',
+    email: 'url-or-text',
+    github: 'url-or-text',
+    milky: 'url-or-text',
+    napcat: 'passthrough',
+    onebot11: 'passthrough',
+    onebot12: 'passthrough',
+};
 export function isOutboundSegment(value) {
     return typeof value === 'object'
         && value !== null
@@ -8,26 +32,142 @@ export function isOutboundSegment(value) {
         && typeof value.type === 'string';
 }
 /**
- * Normalize a rendered outbound payload to wire segments:
- * - segment arrays stay arrays (html segments converted per element);
+ * 解析端点的出站媒体策略：优先读 adapter definition 上声明的
+ * `segments.outboundMedia`（任务 C 挂载点；多 endpoint 展开的 `slot~entry`
+ * id 回退到 slot id 查声明），否则按平台名查内置表，
+ * 未知平台回退 `base64`（历史行为）。
+ */
+export function resolveOutboundMediaPolicy(adapter, snapshot) {
+    const slot = snapshot.capabilities.get(adapter)
+        ?? snapshot.capabilities.get(baseSlotCapabilityId(adapter));
+    const declared = readDeclaredMediaPolicy(slot?.definition);
+    if (declared)
+        return declared;
+    const packageName = slot ? snapshot.tree.get(slot.owner)?.packageName : undefined;
+    const adapterType = adapterTypeName(packageName);
+    return (adapterType ? OUTBOUND_MEDIA_POLICY_BY_ADAPTER[adapterType] : undefined)
+        ?? DEFAULT_MEDIA_POLICY;
+}
+function readDeclaredMediaPolicy(definition) {
+    if (!definition || typeof definition !== 'object')
+        return undefined;
+    const segments = definition.segments;
+    if (!segments || typeof segments !== 'object')
+        return undefined;
+    const declared = segments.outboundMedia;
+    // 过渡期单值策略字符串
+    if (declared === 'base64' || declared === 'url-or-text' || declared === 'passthrough') {
+        return declared;
+    }
+    // 任务 C 契约：媒体来源形式数组 → 投递策略。
+    // base64 可直发；无 base64 但端点可自行物化（upload/path）→ passthrough；
+    // 仅 url → 非 URL 媒体文本降级。
+    if (Array.isArray(declared)) {
+        if (declared.includes('base64'))
+            return 'base64';
+        if (declared.includes('upload') || declared.includes('path'))
+            return 'passthrough';
+        if (declared.includes('url'))
+            return 'url-or-text';
+    }
+    return undefined;
+}
+/**
+ * 平台名 → 出站 interactive 策略（adapter 未声明 `segments.interactive` 时
+ * 的内置来源）：telegram / discord 端点自行把 keyboard 编码为原生按钮；
+ * 其余平台默认 'text'（编号文本降级，对齐旧轨 DEFAULT_INTERACTIVE_POLICY）。
+ */
+const OUTBOUND_INTERACTIVE_POLICY_BY_ADAPTER = {
+    telegram: 'native',
+    discord: 'native',
+};
+/**
+ * 解析端点的出站 interactive 策略：优先读 adapter definition 上声明的
+ * `segments.interactive`，否则按平台名查内置表，未知平台回退 'text'。
+ */
+export function resolveOutboundInteractivePolicy(adapter, snapshot) {
+    const slot = snapshot.capabilities.get(adapter)
+        ?? snapshot.capabilities.get(baseSlotCapabilityId(adapter));
+    const declared = readDeclaredInteractivePolicy(slot?.definition);
+    if (declared)
+        return declared;
+    const packageName = slot ? snapshot.tree.get(slot.owner)?.packageName : undefined;
+    const adapterType = adapterTypeName(packageName);
+    return (adapterType ? OUTBOUND_INTERACTIVE_POLICY_BY_ADAPTER[adapterType] : undefined)
+        ?? DEFAULT_INTERACTIVE_POLICY;
+}
+function readDeclaredInteractivePolicy(definition) {
+    if (!definition || typeof definition !== 'object')
+        return undefined;
+    const segments = definition.segments;
+    if (!segments || typeof segments !== 'object')
+        return undefined;
+    const declared = segments.interactive;
+    return declared === 'native' || declared === 'text' ? declared : undefined;
+}
+/**
+ * keyboard 段中央降级：'text' 端点把 keyboard 渲染为编号文本（复用旧轨
+ * `renderKeyboardAsText`），并把有效 fallback 映射经 `remember` 回调写入
+ * 中央存储（供入站数字回跳解析）；'native' 端点透传 keyboard。
+ */
+export function applyOutboundInteractivePolicy(payload, policy, remember) {
+    if (policy !== 'text' || !Array.isArray(payload))
+        return payload;
+    return payload.map((item) => {
+        if (!isKeyboardSegment(item))
+            return item;
+        const data = item.data;
+        remember?.(effectiveKeyboardFallbackMap(data));
+        return { type: 'text', data: { text: renderKeyboardAsText(data) } };
+    });
+}
+/** 多 endpoint 展开的 record id（`slot.id~entry`）→ slot id（entry 名禁含 `~`，见 adapter-index）。 */
+function baseSlotCapabilityId(adapter) {
+    const tilde = adapter.indexOf('~');
+    return (tilde === -1 ? adapter : adapter.slice(0, tilde));
+}
+/** `@zhin.js/adapter-icqq` → `icqq`；非 adapter 包名原样返回。 */
+function adapterTypeName(packageName) {
+    if (!packageName)
+        return undefined;
+    return packageName.replace(/^@[^/]+\/adapter-/, '');
+}
+/**
+ * Normalize a rendered outbound payload toward canonical wire segments:
+ * - segment arrays stay arrays (html segments converted per element,
+ *   其余段经 `toCanonicalSegments` 归一为 canonical Segment)；
  * - 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) {
+export async function normalizeOutboundPayload(payload, renderer, options) {
+    const mediaPolicy = options?.mediaPolicy ?? DEFAULT_MEDIA_POLICY;
     if (Array.isArray(payload)) {
-        return Promise.all(payload.map((item) => normalizeOutboundSegment(item, renderer)));
+        const resolved = await Promise.all(payload.map((item) => normalizeOneSegment(item, renderer, mediaPolicy)));
+        return applyOutboundMediaPolicy(resolved, mediaPolicy);
     }
     if (isOutboundSegment(payload)) {
-        return [await normalizeOutboundSegment(payload, renderer)];
+        return applyOutboundMediaPolicy([await normalizeOneSegment(payload, renderer, mediaPolicy)], mediaPolicy);
     }
     return payload;
 }
-async function normalizeOutboundSegment(segment, renderer) {
-    if (!isOutboundSegment(segment) || segment.type !== 'html')
-        return segment;
+/**
+ * 单个出站项 → canonical Segment：
+ * - html 段走渲染/文本降级专线（产物已是 canonical 兼容形状，不再过
+ *   `toCanonicalSegments`，以免 legacy 双写字段被 strip）；
+ * - 其余项经 `toCanonicalSegments` 归一（字符串→text、at→mention、
+ *   旧 wire 字段 `{url,file,base64}`→MediaRef）。
+ */
+async function normalizeOneSegment(item, renderer, mediaPolicy) {
+    if (isOutboundSegment(item) && item.type === 'html') {
+        return renderHtmlSegment(item, renderer, mediaPolicy);
+    }
+    return toCanonicalSegments([item])[0];
+}
+async function renderHtmlSegment(segment, renderer, mediaPolicy) {
     const data = segment.data ?? {};
     const html = typeof data.html === 'string' ? data.html : '';
-    if (html && renderer) {
+    // url-or-text 端点无法投递 base64 图片（本层无上传通道），直接文本降级，跳过渲染。
+    if (html && renderer && mediaPolicy !== 'url-or-text') {
         try {
             const result = await renderer.render(html, {
                 width: typeof data.width === 'number' ? data.width : DEFAULT_CARD_WIDTH,
@@ -37,10 +177,14 @@ async function normalizeOutboundSegment(segment, renderer) {
                     : {}),
             });
             if (result.format === 'png' && result.data && typeof result.data === 'object') {
+                const base64 = Buffer.from(result.data).toString('base64');
                 return {
                     type: 'image',
                     data: {
-                        base64: Buffer.from(result.data).toString('base64'),
+                        // canonical MediaRef 为主，legacy `base64`/`name` 双写保持旧 adapter 可读
+                        // （Wave 2 适配器迁移完成后移除 legacy 字段）。
+                        media: { kind: 'base64', value: base64, mime_type: 'image/png' },
+                        base64,
                         name: typeof data.fileName === 'string' ? data.fileName : DEFAULT_CARD_FILENAME,
                     },
                 };
@@ -52,6 +196,25 @@ async function normalizeOutboundSegment(segment, renderer) {
     }
     return { type: 'text', data: { text: htmlSegmentFallbackText(data, html) } };
 }
+/**
+ * 媒体协商：仅 `url-or-text` 需要在本层动作——image 段的非 URL MediaRef
+ * （base64 / 本地路径）无法投递，降级为文本（alt 优先）。
+ */
+function applyOutboundMediaPolicy(segments, mediaPolicy) {
+    if (mediaPolicy !== 'url-or-text')
+        return segments;
+    return segments.map((segment) => {
+        if (segment.type !== 'image')
+            return segment;
+        const media = segment.data.media;
+        if (!isMediaRef(media) || media.kind === 'url')
+            return segment;
+        const alt = typeof segment.data.alt === 'string' && segment.data.alt
+            ? segment.data.alt
+            : '[image]';
+        return { type: 'text', data: { text: alt } };
+    });
+}
 function htmlSegmentFallbackText(data, html) {
     if (typeof data.text === 'string' && data.text.length > 0)
         return data.text;

package/lib/plugin.d.ts

@@ -22,9 +22,11 @@ export type DisposeFn<A> = (context: ArrayItem<A>) => MaybePromise<void>;
 export type ContextList<CS extends (keyof Plugin.Contexts)[]> = CS extends [infer L, ...infer R] ? R extends (keyof Plugin.Contexts)[] ? [ContextItem<L>, ...ContextList<R>] : never[] : never[];
 type ContextItem<L> = L extends keyof Plugin.Contexts ? Plugin.Contexts[L] : never;
 /**
- * usePlugin - 获取或创建当前插件实例
- * 类似 React Hooks 的设计，根据调用文件自动创建插件树
- * 同一上下文中同一文件多次调用返回同一实例
+ * 获取当前插件实例（经典 AsyncLocalStorage 路径）。
+ * 同一上下文中同一文件多次调用返回同一实例。
+ *
+ * @deprecated 仅 `zhin.js/node`（`bootstrapNode`）可用；`zhin runtime start` 下不工作。
+ * 新插件请用 `definePlugin` + 约定目录。见 `docs/contributing/public-api-surface.md`。
  */
 export declare function usePlugin(): Plugin;
 export interface Plugin extends Plugin.Extensions {

package/lib/plugin.js

@@ -31,9 +31,11 @@ function pluginCreateRequire() {
 // usePlugin — 获取或创建当前插件实例
 // ============================================================================
 /**
- * usePlugin - 获取或创建当前插件实例
- * 类似 React Hooks 的设计，根据调用文件自动创建插件树
- * 同一上下文中同一文件多次调用返回同一实例
+ * 获取当前插件实例（经典 AsyncLocalStorage 路径）。
+ * 同一上下文中同一文件多次调用返回同一实例。
+ *
+ * @deprecated 仅 `zhin.js/node`（`bootstrapNode`）可用；`zhin runtime start` 下不工作。
+ * 新插件请用 `definePlugin` + 约定目录。见 `docs/contributing/public-api-surface.md`。
  */
 export function usePlugin() {
     // 必须传入 plugin.ts 的 import.meta.url：getCurrentFile 默认锚定在 plugin-context.ts，
@@ -477,30 +479,42 @@ export class Plugin extends PluginBase {
      */
     async reload(plugin = this) {
         const p = plugin;
-        this.logger.info(formatCompact({ name: p.name, reload: true }));
-        const now = Date.now();
-        if (!p.parent) {
-            // 根插件重载 = 退出进程（由 CLI 重启）
-            return process.exit(51);
-        }
-        const entry = p.filePath;
-        const parent = p.parent;
-        await p.stop();
-        let fresh;
+        // A burst of file events for one logical save (or an overlapping edit
+        // while a reload is still in flight) must not start a second concurrent
+        // stop()+import() cycle for the same plugin.
+        if (p._reloading)
+            return;
+        p._reloading = true;
         try {
-            fresh = await parent.import(entry, now);
+            this.logger.info(formatCompact({ name: p.name, reload: true }));
+            const now = Date.now();
+            if (!p.parent) {
+                // 根插件重载 = 退出进程（由 CLI 重启）
+                process.exit(51);
+                return;
+            }
+            const entry = p.filePath;
+            const parent = p.parent;
+            await p.stop();
+            let fresh;
+            try {
+                fresh = await parent.import(entry, now);
+            }
+            catch (err) {
+                this.logger.error(formatCompact({
+                    name: p.name,
+                    reload: false,
+                    error: err instanceof Error ? err.message : String(err),
+                    hint: 'full_restart',
+                }));
+                throw err;
+            }
+            await fresh.broadcast('mounted');
+            this.logger.debug(formatCompact({ name: fresh.name, reload_ms: Date.now() - now }));
         }
-        catch (err) {
-            this.logger.error(formatCompact({
-                name: p.name,
-                reload: false,
-                error: err instanceof Error ? err.message : String(err),
-                hint: 'full_restart',
-            }));
-            throw err;
+        finally {
+            p._reloading = false;
         }
-        await fresh.broadcast('mounted');
-        this.logger.debug(formatCompact({ name: fresh.name, reload_ms: Date.now() - now }));
     }
     /**
      * 监听文件变化（Plugin 类型窄化版本）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/core",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Zhin机器人核心框架",
   "type": "module",
   "main": "./lib/index.js",
@@ -40,6 +40,26 @@
       "types": "./lib/jsx-dev-runtime.d.ts",
       "development": "./src/jsx-dev-runtime.ts",
       "import": "./lib/jsx-dev-runtime.js"
+    },
+    "./feature/adapter": {
+      "types": "./lib/feature/adapter.d.ts",
+      "development": "./src/feature/adapter.ts",
+      "import": "./lib/feature/adapter.js"
+    },
+    "./feature/command": {
+      "types": "./lib/feature/command.d.ts",
+      "development": "./src/feature/command.ts",
+      "import": "./lib/feature/command.js"
+    },
+    "./feature/component": {
+      "types": "./lib/feature/component.d.ts",
+      "development": "./src/feature/component.ts",
+      "import": "./lib/feature/component.js"
+    },
+    "./feature/middleware": {
+      "types": "./lib/feature/middleware.d.ts",
+      "development": "./src/feature/middleware.ts",
+      "import": "./lib/feature/middleware.js"
     }
   },
   "files": [
@@ -50,15 +70,15 @@
     "segment-matcher": "^1.0.5",
     "smol-toml": "^1.7.0",
     "yaml": "^2.9.0",
-    "@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/adapter": "1.1.2",
+    "@zhin.js/command": "1.0.4",
+    "@zhin.js/component": "1.0.4",
+    "@zhin.js/database": "1.0.78",
+    "@zhin.js/kernel": "1.0.5",
     "@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"
+    "@zhin.js/middleware": "1.0.4",
+    "@zhin.js/plugin-runtime": "1.1.1",
+    "@zhin.js/schema": "1.0.72"
   },
   "peerDependencies": {
     "zod": "^4.0.0"
@@ -73,7 +93,7 @@
     "@types/qrcode": "^1.5.5",
     "ajv": "8.18.0",
     "typescript": "^6.0.3",
-    "@zhin.js/ai": "1.4.5"
+    "@zhin.js/ai": "1.4.6"
   },
   "repository": {
     "type": "git",
@@ -93,6 +113,32 @@
   "engines": {
     "node": "^20.19.0 || >=22.12.0"
   },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./lib/index.js",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/component",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/middleware",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
   "scripts": {
     "build": "tsc",
     "clean": "rimraf lib"