@zhin.js/command 1.0.2 → 1.0.4

package/README.md

@@ -1,20 +1,58 @@
 # @zhin.js/command
 
-Zhin Plugin Runtime 的 Command Feature。它把 `commands/**/*.ts` 的目录层级映射为命令
-路径，并支持 `[name:type=default]` 参数文件名、owner-scoped Config/Resource 与确定性匹配。
+Zhin Plugin Runtime 的约定式 Command Feature。它发现 `commands/**/*.ts(x)`，将插件树
+路径与文件路径投影为命令，并用 `segment-matcher` 同时匹配纯文本和 canonical IM segments。
+
+## Authoring
 
 ```ts
+// commands/gh/issue/list.ts -> gh issue list
 import { defineCommand } from '@zhin.js/command';
 
 export default defineCommand({
-  description: 'Show runtime status',
-  execute: ({ args }) => args.join(' '),
+  description: 'List GitHub issues',
+  execute: ({ args }) => `issues:${args.join(',')}`,
 });
 ```
 
-definition 在 import 时不注册全局状态；Feature provider 在 generation prepare 阶段发现、
-校验并投影 `CommandIndex`。生产 manifest 指向 `lib/provider.js`。
+最后一个文件名可以声明参数：
+
+```text
+commands/gh/pr/[title:string=defaultTitle].ts -> gh pr [title]
+commands/upload/[asset:image].ts             -> upload <asset>
+```
+
+文本类型包括 `string`、`word`、`text`、`number`、`integer`、`float`、`boolean`；结构化
+类型包括 `mention`、`image`、`face`、`reply`、`forward`、`dice`、`rps`。结构化类型
+直接从对应 segment 取值，不能声明文件名默认值。
+
+`execute()` 收到冻结的 `CommandContext`：
+
+- `params`：路由参数的类型化结果。
+- `args`：匹配后剩余文本按空白切分的兼容视图。
+- `segments`：匹配后剩余的结构化段，媒体和 mention 不会丢失。
+- `config` / `use()` / `owner` / `generation`：owner-scoped Runtime 上下文。
+- `input`：派发来源；IM 中为满足 `CommandMessage` 的 Runtime `Message`。
+- `adapter` / `endpoint`：适配器实例 id 与 endpoint 名。
+- `scene`：`{ id, type, name? }` 场景对象。
+- `sender`：`{ id, name?, role: string[] }` 发送者对象。
 
-验证：`pnpm --filter @zhin.js/command test && pnpm --filter @zhin.js/command build`。
+单文件插件可在 `setup({ addCommand })` 中调用
+`addCommand('hello', defineCommand(...))`。它与目录发现共用 CommandIndex；拆成文件后
+可获得单命令 HMR。
+
+## Runtime
+
+definition 在 import 时不注册全局状态。Feature provider 在 generation prepare 阶段完成
+发现、校验和 `CommandIndex` 投影；静态路由优先于动态路由，同形动态路由在启动期拒绝。
+生产 manifest 指向 `lib/provider.js`。
+
+验证：
+
+```bash
+pnpm --filter @zhin.js/command build
+pnpm --filter @zhin.js/command test
+```
 
-命令目录契约见 [Plugin Runtime 原位迁移](../../../docs/architecture/target-implementation/in-place-migration.md)。
+完整用户契约见[命令创作指南](../../../docs/authoring/commands.md)，架构迁移背景见
+[Plugin Runtime 原位迁移](../../../docs/architecture/target-implementation/in-place-migration.md)。

package/lib/command-index.d.ts

@@ -1,5 +1,5 @@
 import type { CapabilitySlot, PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
-import { type CommandDefinition, type CommandParameterDefinition, type CommandParameterType } from './definition.js';
+import { type CommandDefinition, type CommandParameterDefinition, type CommandParameterType, type CommandSegment } from './definition.js';
 export interface CommandParameterDescriptor extends CommandParameterDefinition {
     readonly required: boolean;
 }
@@ -15,6 +15,7 @@ export interface CommandDispatchResult {
     readonly owner?: PluginId;
     readonly value?: unknown;
 }
+export type CommandMatchInput = string | readonly Readonly<CommandSegment>[];
 export declare class CommandIndex {
     #private;
     private readonly snapshot;
@@ -23,7 +24,7 @@ export declare class CommandIndex {
     list(): readonly CommandDescriptor[];
     has(name: string): boolean;
     execute(name: string, args?: readonly string[]): Promise<unknown>;
-    dispatch(input: string, source?: unknown): Promise<CommandDispatchResult>;
+    dispatch(input: CommandMatchInput, source?: unknown): Promise<CommandDispatchResult>;
 }
 export declare function isCommandIndex(value: unknown): value is CommandIndex;
 export declare class CommandParameterValueError extends TypeError {

package/lib/command-index.js

@@ -1,13 +1,25 @@
+import { SegmentMatcher, TypeMatcherRegistry, } from 'segment-matcher';
 import { createCommandContext, } from './definition.js';
+const segmentFields = {
+    text: 'text',
+    mention: 'target',
+    at: ['target', 'user_id', 'qq'],
+    face: 'id',
+    image: (segment) => segment.data.media ?? segment.data.file ?? segment.data.url ?? segment.data.src,
+    reply: ['message_id', 'reply_id', 'id'],
+    forward: ['forward_id', 'res_id', 'message_id', 'id'],
+    dice: 'result',
+    rps: 'result',
+};
 export class CommandIndex {
     snapshot;
     $projection = 'zhin.command-index/1';
     #commands;
-    #staticCommands = new Map();
-    #dynamicCommands = new Map();
     constructor(slots, snapshot) {
         this.snapshot = snapshot;
         const commands = [];
+        const staticCommands = new Map();
+        const dynamicCommands = new Map();
         for (const slot of slots) {
             const segments = runtimeSegments(slot.owner, slot.localName);
             const parameter = slot.definition.$parameter;
@@ -24,29 +36,30 @@ export class CommandIndex {
                 slot,
                 segments: Object.freeze(segments),
                 parameter,
+                matcher: new SegmentMatcher(matcherPattern(segments, parameter), segmentFields),
             });
             if (!parameter) {
                 const key = segments.join(' ');
-                if (this.#staticCommands.has(key))
+                if (staticCommands.has(key))
                     throw duplicateCommand(key);
-                this.#staticCommands.set(key, record);
+                staticCommands.set(key, record);
             }
             else {
                 const shape = routeShape(segments);
-                if (this.#dynamicCommands.has(shape))
+                if (dynamicCommands.has(shape))
                     throw duplicateCommand(name);
-                this.#dynamicCommands.set(shape, record);
+                dynamicCommands.set(shape, record);
             }
             commands.push(record);
         }
-        this.#commands = Object.freeze(commands);
+        this.#commands = Object.freeze(commands.sort(compareCommands));
     }
     list() {
         return this.#commands.map(toDescriptor);
     }
     has(name) {
         try {
-            return this.#match(name) !== undefined;
+            return this.#match(name, true) !== undefined;
         }
         catch (error) {
             if (error instanceof CommandParameterValueError)
@@ -55,53 +68,65 @@ export class CommandIndex {
         }
     }
     async execute(name, args = []) {
-        const match = this.#match(name);
-        if (!match)
+        const match = this.#match(name, true);
+        if (!match) {
+            this.#diagnoseParameter(name);
             throw new Error(`Unknown Command: ${name}`);
+        }
         return match.command.slot.definition.execute(createCommandContext(this.snapshot, match.command.slot.owner, args, match.params));
     }
     async dispatch(input, source = undefined) {
-        const words = splitCommand(input);
-        for (let consumed = words.length; consumed > 0; consumed -= 1) {
-            const match = this.#match(words.slice(0, consumed).join(' '));
-            if (!match)
+        const match = this.#match(input, false);
+        if (!match)
+            return Object.freeze({ matched: false });
+        const args = textArgs(match.remaining);
+        const value = await match.command.slot.definition.execute(createCommandContext(this.snapshot, match.command.slot.owner, args, match.params, source, match.remaining));
+        return Object.freeze({
+            matched: true,
+            command: match.command.name,
+            owner: match.command.slot.owner,
+            value,
+        });
+    }
+    #match(input, exact) {
+        const segments = normalizeSegments(typeof input === 'string'
+            ? input.trim()
+                ? [{ type: 'text', data: { text: input.trim() } }]
+                : []
+            : input);
+        if (segments.length === 0)
+            return undefined;
+        for (const command of this.#commands) {
+            const result = command.matcher.match(asMatcherSegments(segments));
+            if (!result || !hasCommandBoundary(result.remaining))
                 continue;
-            const args = words.slice(consumed);
-            const value = await match.command.slot.definition.execute(createCommandContext(this.snapshot, match.command.slot.owner, args, match.params, source));
-            return Object.freeze({
-                matched: true,
-                command: match.command.name,
-                owner: match.command.slot.owner,
-                value,
-            });
+            const remaining = normalizeSegments(result.remaining);
+            if (exact && remaining.length > 0)
+                continue;
+            return {
+                command,
+                params: Object.freeze({ ...result.params }),
+                remaining,
+            };
         }
-        return Object.freeze({ matched: false });
+        return undefined;
     }
-    #match(name) {
+    #diagnoseParameter(name) {
         const words = splitCommand(name);
-        // A literal file such as list.ts always wins over [name:string].ts.
-        const staticCommand = this.#staticCommands.get(words.join(' '));
-        if (staticCommand)
-            return { command: staticCommand, params: Object.freeze({}) };
-        for (const command of this.#dynamicCommands.values()) {
+        for (const command of this.#commands) {
             const parameter = command.parameter;
-            const optional = parameter.defaultValue !== undefined;
-            if (words.length !== command.segments.length &&
-                !(optional && words.length === command.segments.length - 1))
+            if (!parameter)
                 continue;
             const parameterIndex = command.segments.findIndex((segment) => segment.startsWith('$'));
+            if (words.length !== command.segments.length)
+                continue;
             if (!command.segments.every((segment, index) => index === parameterIndex || segment === words[index]))
                 continue;
-            const rawValue = words[parameterIndex];
-            const value = rawValue === undefined
-                ? parameter.defaultValue
-                : parseRuntimeValue(parameter, rawValue);
-            return {
-                command,
-                params: Object.freeze({ [parameter.name]: value }),
-            };
+            const value = words[parameterIndex];
+            if (value === undefined || matchesParameter(parameter.type, value))
+                continue;
+            throw new CommandParameterValueError(parameter.name, parameter.type, value);
         }
-        return undefined;
     }
 }
 export function isCommandIndex(value) {
@@ -118,9 +143,9 @@ function assertParameterSegment(segments, parameter, source) {
     const dynamicSegments = segments.filter((segment) => segment.startsWith('$'));
     if (!parameter && dynamicSegments.length === 0)
         return;
-    if (parameter && dynamicSegments.length === 1 &&
-        dynamicSegments[0] === `$${parameter.name}` &&
-        segments.at(-1) === dynamicSegments[0])
+    if (parameter && dynamicSegments.length === 1
+        && dynamicSegments[0] === `$${parameter.name}`
+        && segments.at(-1) === dynamicSegments[0])
         return;
     throw new Error(`Broken dynamic Command identity for ${source}`);
 }
@@ -133,27 +158,93 @@ function displayName(segments, parameter) {
             : `[${segment.slice(1)}]`;
     }).join(' ');
 }
+function matcherPattern(segments, parameter) {
+    return segments.map((segment) => {
+        if (!segment.startsWith('$'))
+            return segment;
+        if (!parameter)
+            throw new Error(`Missing Command parameter metadata: ${segment}`);
+        const type = matcherType(parameter.type);
+        return parameter.defaultValue === undefined
+            ? `<${parameter.name}:${type}>`
+            : `[${parameter.name}:${type}=${String(parameter.defaultValue)}]`;
+    }).join(' ');
+}
+function matcherType(type) {
+    return type === 'string' ? 'word' : type;
+}
 function routeShape(segments) {
     return segments.map((segment) => segment.startsWith('$') ? '$' : segment).join(' ');
 }
+function compareCommands(left, right) {
+    const leftDynamic = left.parameter ? 1 : 0;
+    const rightDynamic = right.parameter ? 1 : 0;
+    return leftDynamic - rightDynamic
+        || staticSegmentCount(right.segments) - staticSegmentCount(left.segments)
+        || right.segments.length - left.segments.length
+        || right.name.length - left.name.length
+        || left.name.localeCompare(right.name);
+}
+function staticSegmentCount(segments) {
+    return segments.filter((segment) => !segment.startsWith('$')).length;
+}
 function splitCommand(value) {
     const normalized = value.trim();
     return normalized ? normalized.split(/\s+/) : [];
 }
-function parseRuntimeValue(parameter, value) {
-    if (parameter.type === 'string')
-        return value;
-    if (parameter.type === 'number') {
-        const number = Number(value);
-        if (value.trim().length > 0 && Number.isFinite(number))
-            return number;
-    }
-    else if (value === 'true' || value === 'false') {
-        return value === 'true';
+function matchesParameter(type, value) {
+    const matcher = TypeMatcherRegistry.getMatcher(matcherType(type));
+    return matcher ? matcher.match(value).success : false;
+}
+function asMatcherSegments(segments) {
+    return segments.map((segment) => ({
+        type: typeof segment.type === 'string' ? segment.type : { name: segment.type.name },
+        data: { ...segment.data },
+    }));
+}
+function hasCommandBoundary(segments) {
+    const first = segments[0];
+    if (!first || first.type !== 'text')
+        return true;
+    const text = first.data.text;
+    return typeof text !== 'string' || text.length === 0 || /^\s/u.test(text);
+}
+function normalizeSegments(input) {
+    const segments = input.map((segment) => ({
+        type: typeof segment.type === 'string' ? segment.type : { name: segment.type.name },
+        data: { ...segment.data },
+    }));
+    trimBoundary(segments, 'start');
+    trimBoundary(segments, 'end');
+    return Object.freeze(segments.map((segment) => Object.freeze({
+        type: typeof segment.type === 'string'
+            ? segment.type
+            : Object.freeze({ name: segment.type.name }),
+        data: Object.freeze(segment.data),
+    })));
+}
+function trimBoundary(segments, side) {
+    while (segments.length > 0) {
+        const index = side === 'start' ? 0 : segments.length - 1;
+        const segment = segments[index];
+        if (!segment || segment.type !== 'text' || typeof segment.data.text !== 'string')
+            return;
+        const text = side === 'start' ? segment.data.text.trimStart() : segment.data.text.trimEnd();
+        if (text) {
+            segment.data.text = text;
+            return;
+        }
+        segments.splice(index, 1);
     }
-    throw new CommandParameterValueError(parameter.name, parameter.type, value);
 }
-function toDescriptor({ slot: _slot, segments: _segments, parameter: _parameter, ...descriptor }) {
+function textArgs(segments) {
+    return Object.freeze(segments.flatMap((segment) => {
+        if (segment.type !== 'text' || typeof segment.data.text !== 'string')
+            return [];
+        return splitCommand(segment.data.text);
+    }));
+}
+function toDescriptor({ slot: _slot, segments: _segments, parameter: _parameter, matcher: _matcher, ...descriptor }) {
     return descriptor;
 }
 function duplicateCommand(name) {

package/lib/definition.d.ts

@@ -1,26 +1,105 @@
 import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import { type CapabilityContext } from '@zhin.js/feature-kit';
 declare const commandBrand: "zhin.command/1";
-export type CommandParameterType = 'string' | 'number' | 'boolean';
-export type CommandParameterValue = string | number | boolean;
+export type CommandParameterType = 'string' | 'number' | 'integer' | 'float' | 'boolean' | 'word' | 'text' | 'mention' | 'image' | 'face' | 'reply' | 'forward' | 'dice' | 'rps';
+export type CommandParameterValue = string | number | boolean | Readonly<Record<string, unknown>> | null;
+/** Minimal structural contract shared with canonical IM segments. */
+export interface CommandSegment {
+    readonly type: string | {
+        readonly name: string;
+    };
+    readonly data: Readonly<Record<string, unknown>>;
+}
 export interface CommandParameterDefinition {
     readonly name: string;
     readonly type: CommandParameterType;
     readonly defaultValue?: CommandParameterValue;
 }
-export interface CommandContext<TConfig = unknown, TInput = unknown> extends CapabilityContext<TConfig> {
+/** 场景：群 / 私聊 / 频道等。 */
+export interface CommandScene {
+    readonly id: string;
+    readonly type: string;
+    readonly name?: string;
+}
+/**
+ * 发送者。
+ * `role` 为角色列表（如 `user` / `trusted` / `master`，以及平台侧 `owner` / `admin` 等）。
+ */
+export interface CommandSender {
+    readonly id: string;
+    readonly name?: string;
+    readonly role: readonly string[];
+}
+/**
+ * 命令侧入站消息契约。
+ *
+ * `@zhin.js/core/runtime` 的 `Message` 结构兼容本接口（duck typing）。
+ * 因架构分层（command 为 Feature 层，不能 import core），此处独立声明。
+ */
+export interface CommandMessage {
+    readonly adapter: string;
+    readonly target: string;
+    readonly content: string;
+    /** 发送者 id（扁平字段；结构化视图见 CommandContext.sender）。 */
+    readonly sender?: string;
+    readonly id?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    /** 若上游已结构化，优先采用。 */
+    readonly scene?: CommandScene;
+    readonly $reply?: (content: unknown) => Promise<unknown>;
+    readonly $replyFrom?: (requester: string, content: unknown) => Promise<unknown>;
+}
+/**
+ * IM 入站快捷字段。
+ * 有 `CommandMessage` 来源时由 {@link resolveCommandSession} 填充；
+ * `CommandIndex.execute(name)` 等无消息路径下为 `undefined`。
+ */
+export interface CommandSession {
+    /**
+     * 适配器插件实例 id（CapabilityId 的 owner 段，如 `root/icqq`）。
+     * 与 `snapshot.config.get(adapter)` 对齐。
+     */
+    readonly adapter?: string;
+    /** Endpoint 名（`metadata.endpoint`）。 */
+    readonly endpoint?: string;
+    /** 场景对象（id / type / name）。 */
+    readonly scene?: CommandScene;
+    /** 发送者对象（id / name / role[]）。 */
+    readonly sender?: CommandSender;
+}
+export interface CommandContext<TConfig = unknown, TInput extends CommandMessage = CommandMessage> extends CapabilityContext<TConfig>, CommandSession {
     readonly args: readonly string[];
     readonly params: Readonly<Record<string, CommandParameterValue>>;
-    readonly input: TInput;
+    /** Structured arguments left after the command pattern was consumed. */
+    readonly segments: readonly Readonly<CommandSegment>[];
+    /**
+     * 派发来源。IM 命中时为 Runtime `Message`（满足 {@link CommandMessage}）；
+     * Host / `CommandIndex.execute` 等无消息路径可能为 `undefined`。
+     */
+    readonly input?: TInput;
 }
-export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput = unknown> {
+export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput extends CommandMessage = CommandMessage> {
     readonly $feature: typeof commandBrand;
     readonly $parameter?: CommandParameterDefinition;
     readonly description?: string;
     execute(context: CommandContext<TConfig, TInput>): TResult | Promise<TResult>;
 }
-export declare function defineCommand<TConfig = unknown, TResult = unknown, TInput = unknown>(definition: Omit<CommandDefinition<TConfig, TResult, TInput>, '$feature' | '$parameter'>): Readonly<CommandDefinition<TConfig, TResult, TInput>>;
-export declare function bindCommandParameter<TConfig, TResult, TInput>(definition: CommandDefinition<TConfig, TResult, TInput>, parameter: CommandParameterDefinition | undefined): Readonly<CommandDefinition<TConfig, TResult, TInput>>;
+declare module '@zhin.js/plugin-runtime' {
+    interface PluginSetupContext<TConfig> {
+        addCommand<TResult = unknown, TInput extends CommandMessage = CommandMessage>(localName: string, definition: CommandDefinition<TConfig, TResult, TInput>): void;
+    }
+}
+/**
+ * 定义一个命令模块（`commands/` 约定目录下默认导出）。
+ * @public 用户侧创作面，承诺 semver（见 docs/contributing/public-api-surface.md）。
+ */
+export declare function defineCommand<TConfig = unknown, TResult = unknown, TInput extends CommandMessage = CommandMessage>(definition: Omit<CommandDefinition<TConfig, TResult, TInput>, '$feature' | '$parameter'>): Readonly<CommandDefinition<TConfig, TResult, TInput>>;
+export declare function bindCommandParameter<TConfig, TResult, TInput extends CommandMessage>(definition: CommandDefinition<TConfig, TResult, TInput>, parameter: CommandParameterDefinition | undefined): Readonly<CommandDefinition<TConfig, TResult, TInput>>;
 export declare function parseCommandDefinition(value: unknown): CommandDefinition;
-export declare function createCommandContext(snapshot: RuntimeSnapshot, ownerId: PluginId, args: readonly string[], params?: Readonly<Record<string, CommandParameterValue>>, input?: unknown): CommandContext;
+export declare function createCommandContext(snapshot: RuntimeSnapshot, ownerId: PluginId, args: readonly string[], params?: Readonly<Record<string, CommandParameterValue>>, input?: unknown, segments?: readonly Readonly<CommandSegment>[]): CommandContext;
+/**
+ * 从派发来源（通常是 Runtime `Message`）解析入站快捷字段。
+ * 不依赖 `@zhin.js/core`，按 {@link CommandMessage} 结构鸭式识别。
+ */
+export declare function resolveCommandSession(input: unknown): CommandSession;
 export {};

package/lib/definition.js

@@ -1,5 +1,9 @@
 import { createCapabilityContext, } from '@zhin.js/feature-kit';
 const commandBrand = 'zhin.command/1';
+/**
+ * 定义一个命令模块（`commands/` 约定目录下默认导出）。
+ * @public 用户侧创作面，承诺 semver（见 docs/contributing/public-api-surface.md）。
+ */
 export function defineCommand(definition) {
     if (typeof definition.execute !== 'function') {
         throw new TypeError('Command execute must be a function');
@@ -21,12 +25,167 @@ export function parseCommandDefinition(value) {
     }
     return definition;
 }
-export function createCommandContext(snapshot, ownerId, args, params = Object.freeze({}), input = undefined) {
+export function createCommandContext(snapshot, ownerId, args, params = Object.freeze({}), input = undefined, segments = Object.freeze([])) {
     const context = createCapabilityContext(snapshot, ownerId);
+    const session = resolveCommandSession(input);
     return Object.freeze({
         ...context,
+        ...session,
         args: Object.freeze([...args]),
         params: Object.freeze({ ...params }),
-        input,
+        segments: freezeSegments(segments),
+        ...(input !== undefined ? { input: input } : {}),
     });
 }
+/**
+ * 从派发来源（通常是 Runtime `Message`）解析入站快捷字段。
+ * 不依赖 `@zhin.js/core`，按 {@link CommandMessage} 结构鸭式识别。
+ */
+export function resolveCommandSession(input) {
+    if (!isCommandMessageLike(input))
+        return Object.freeze({});
+    const metadata = input.metadata && typeof input.metadata === 'object'
+        ? input.metadata
+        : undefined;
+    const adapter = input.adapter.split('\0')[0] || undefined;
+    const endpoint = typeof metadata?.endpoint === 'string' && metadata.endpoint
+        ? metadata.endpoint
+        : undefined;
+    const scene = resolveScene(input, metadata);
+    const sender = resolveSender(input, metadata);
+    return Object.freeze({
+        ...(adapter ? { adapter } : {}),
+        ...(endpoint !== undefined ? { endpoint } : {}),
+        ...(scene !== undefined ? { scene } : {}),
+        ...(sender !== undefined ? { sender } : {}),
+    });
+}
+function isCommandMessageLike(input) {
+    if (!input || typeof input !== 'object')
+        return false;
+    const value = input;
+    return typeof value.adapter === 'string'
+        && typeof value.target === 'string'
+        && typeof value.content === 'string';
+}
+function resolveScene(input, metadata) {
+    if (isCommandScene(input.scene)) {
+        return Object.freeze({
+            id: input.scene.id,
+            type: input.scene.type,
+            ...(input.scene.name !== undefined ? { name: input.scene.name } : {}),
+        });
+    }
+    const parsed = parseTarget(input.target);
+    const type = (typeof metadata?.channelType === 'string' && metadata.channelType)
+        || (typeof metadata?.type === 'string' && metadata.type)
+        || parsed?.type;
+    const id = (typeof metadata?.channelId === 'string' && metadata.channelId)
+        || parsed?.id;
+    if (!type || !id)
+        return undefined;
+    const name = firstString(metadata?.channelName, metadata?.group_name, metadata?.groupName, metadata?.sceneName);
+    return Object.freeze({
+        id,
+        type,
+        ...(name !== undefined ? { name } : {}),
+    });
+}
+function resolveSender(input, metadata) {
+    const structured = input.from;
+    if (isCommandSender(structured)) {
+        return freezeSender(structured);
+    }
+    // 允许上游把 sender 直接做成对象（未来 Runtime Message 演进）
+    if (isCommandSender(input.sender)) {
+        return freezeSender(input.sender);
+    }
+    const id = typeof input.sender === 'string' && input.sender
+        ? input.sender
+        : firstString(metadata?.user_id, metadata?.userId);
+    if (!id)
+        return undefined;
+    const name = firstString(metadata?.nickname, metadata?.senderName, metadata?.name);
+    const role = resolveRoles(metadata);
+    return Object.freeze({
+        id,
+        ...(name !== undefined ? { name } : {}),
+        role,
+    });
+}
+function resolveRoles(metadata) {
+    const roles = [];
+    const push = (value) => {
+        if (typeof value !== 'string')
+            return;
+        const trimmed = value.trim();
+        if (trimmed && !roles.includes(trimmed))
+            roles.push(trimmed);
+    };
+    if (Array.isArray(metadata?.roles)) {
+        for (const item of metadata.roles)
+            push(item);
+    }
+    push(metadata?.senderRole);
+    push(metadata?.role);
+    if (metadata?.isMaster === true)
+        push('master');
+    if (metadata?.isTrusted === true)
+        push('trusted');
+    if (roles.length === 0)
+        roles.push('user');
+    return Object.freeze(roles);
+}
+function parseTarget(target) {
+    const parts = target.split(':').filter(Boolean);
+    if (parts.length < 2)
+        return undefined;
+    const kind = parts[0];
+    if (kind === 'channel' && parts.length >= 3) {
+        return { type: 'channel', id: parts[parts.length - 1] };
+    }
+    if (kind === 'temp' && parts.length >= 3) {
+        return { type: 'private', id: parts[parts.length - 1] };
+    }
+    return { type: kind, id: parts.slice(1).join(':') };
+}
+function isCommandScene(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const scene = value;
+    return typeof scene.id === 'string'
+        && scene.id.length > 0
+        && typeof scene.type === 'string'
+        && scene.type.length > 0;
+}
+function isCommandSender(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const sender = value;
+    return typeof sender.id === 'string'
+        && sender.id.length > 0
+        && Array.isArray(sender.role)
+        && sender.role.every((item) => typeof item === 'string');
+}
+function freezeSender(sender) {
+    return Object.freeze({
+        id: sender.id,
+        ...(sender.name !== undefined ? { name: sender.name } : {}),
+        role: Object.freeze([...sender.role]),
+    });
+}
+function firstString(...values) {
+    for (const value of values) {
+        if (typeof value === 'string' && value.trim())
+            return value;
+    }
+    return undefined;
+}
+function freezeSegments(segments) {
+    return Object.freeze(segments.map((segment) => Object.freeze({
+        type: typeof segment.type === 'string'
+            ? segment.type
+            : Object.freeze({ name: segment.type.name }),
+        data: Object.freeze({ ...segment.data }),
+    })));
+}