@fraqjs/fraq 0.11.0 → 0.12.0

package/README.md

@@ -50,4 +50,4 @@ npx tsx index.ts
 
 上面的例子只是 Fraq 的最小使用方式，你还可以继续了解如何构造更丰富的消息、定义更复杂的指令参数、编写可复用的插件等。
 
-完整文档请见 [fraq.ntqqrev.org](https://fraq.ntqqrev.org/)。
+完整文档请见 [fraq.dev](https://fraq.dev/)。

package/dist/index.d.mts

@@ -5377,62 +5377,6 @@ interface ApiEndpoints$1 {
   };
 }
 //#endregion
-//#region src/protocol/endpoint.d.ts
-type RequiredKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? never : K }[keyof T];
-type AllOptional<T> = RequiredKeys<T> extends never ? true : false;
-type RawApiEndpoint<E extends keyof ApiEndpoints$1> = {
-  request: ApiEndpoints$1[E]['request_ZodInput'] extends null ? null : ApiEndpoints$1[E]['request_ZodInput'];
-  response: ApiEndpoints$1[E]['response'] extends null ? null : ApiEndpoints$1[E]['response'];
-};
-type ApiEndpointFunction<E extends keyof ApiEndpoints$1> = RawApiEndpoint<E>['request'] extends null
-  ? () => Promise<RawApiEndpoint<E>['response']>
-  : AllOptional<RawApiEndpoint<E>['request']> extends true
-    ? (params?: RawApiEndpoint<E>['request']) => Promise<RawApiEndpoint<E>['response']>
-    : (params: RawApiEndpoint<E>['request']) => Promise<RawApiEndpoint<E>['response']>;
-type ApiEndpoints = { [E in keyof ApiEndpoints$1]: ApiEndpointFunction<E> };
-type EventMap = {
-  [K in Event['event_type']]: Extract<
-    Event,
-    {
-      event_type: K;
-    }
-  >;
-};
-//#endregion
-//#region src/protocol/client.d.ts
-interface MilkyClient extends ApiEndpoints {}
-declare class MilkyClientBase {
-  readonly baseUrl: string;
-  readonly wsBaseUrl: string;
-  private readonly accessToken?;
-  private readonly baseHeaders;
-  constructor(
-    baseUrl: string | URL,
-    options?: {
-      accessToken?: string;
-    },
-  );
-  callApi(endpoint: string, params?: unknown): Promise<unknown>;
-}
-declare function createMilkyClient(...params: ConstructorParameters<typeof MilkyClientBase>): MilkyClient;
-//#endregion
-//#region src/protocol/event.d.ts
-interface MilkyEventSubscription {
-  closed: Promise<void>;
-  stop(): void | Promise<void>;
-}
-interface MilkyEventSource {
-  readonly name?: string;
-  start(onEvent: (event: Event) => void | Promise<void>): Promise<MilkyEventSubscription>;
-}
-interface MilkyWebSocketEventSourceOptions {
-  accessToken?: string;
-}
-declare function createMilkyWebSocketEventSource(
-  baseUrl: string | URL,
-  options?: MilkyWebSocketEventSourceOptions,
-): MilkyEventSource;
-//#endregion
 //#region src/routing/tokenizer.d.ts
 type Token =
   | string
@@ -5460,6 +5404,8 @@ declare class Tokenizer {
   greedy(): string;
   isCatchAllAvailable(): boolean;
   catchAll(): IncomingSegment[];
+  consumeMention(userId: number): boolean;
+  consumeTextPrefix(prefix: string): boolean;
   private findNextPosition;
   private findTextTokenStart;
   private readTextToken;
@@ -5526,6 +5472,9 @@ declare namespace param {
 type Pattern = Record<string, Parameter<any>>;
 type ParamsOf<P extends Pattern> = { [K in keyof P]: P[K] extends Parameter<infer T> ? T : never };
 type Executor<P extends Pattern> = (session: Session, params: ParamsOf<P>) => void | Promise<void>;
+type RouteMeta = Record<string, unknown> & {
+  tags?: readonly string[];
+};
 interface Command<P extends Pattern> {
   name: string;
   pattern: P;
@@ -5533,10 +5482,12 @@ interface Command<P extends Pattern> {
   description?: string;
   aliases?: string[];
   hidden?: boolean;
+  meta?: RouteMeta;
 }
 interface RawPattern<P extends Pattern> {
   pattern: P;
   execute: Executor<P>;
+  meta?: RouteMeta;
 }
 interface SessionReplyOptions {
   withQuote?: boolean;
@@ -5561,6 +5512,7 @@ declare class CommandBuilder<P extends Pattern = {}, S = Command<P>> {
   private description?;
   private aliases?;
   private hidden?;
+  private routeMeta?;
   constructor(name: string, sink?: (command: Command<P>) => S);
   arg<K extends string, T>(
     key: K,
@@ -5576,11 +5528,40 @@ declare class CommandBuilder<P extends Pattern = {}, S = Command<P>> {
   describe(description: string): CommandBuilder<P, S>;
   alias(...aliases: string[]): CommandBuilder<P, S>;
   hide(): CommandBuilder<P, S>;
+  meta(meta: RouteMeta): CommandBuilder<P, S>;
+  tag(...tags: string[]): CommandBuilder<P, S>;
   execute(executor: Executor<P>): S;
 }
+declare function mergeRouteMeta(left?: RouteMeta, right?: RouteMeta): RouteMeta | undefined;
 //#endregion
 //#region src/routing/router.d.ts
 type SessionPredicate = (session: Session) => boolean;
+type RouteActivation =
+  | {
+      type: 'direct';
+    }
+  | {
+      type: 'mention';
+    }
+  | {
+      type: 'prefix';
+      prefix: string;
+    };
+type RouteDescriptor =
+  | {
+      type: 'command';
+      path: readonly string[];
+      name: string;
+      aliases?: readonly string[];
+      meta?: RouteMeta;
+    }
+  | {
+      type: 'rawPattern';
+      path: readonly string[];
+      meta?: RouteMeta;
+    };
+type RouteActivationResolver = (route: RouteDescriptor, session: Session) => readonly RouteActivation[] | undefined;
+declare const defaultRouteActivationResolver: RouteActivationResolver;
 type RouteEntry =
   | {
       type: 'command';
@@ -5605,11 +5586,13 @@ type RouteBranch =
       type: 'command';
       path: string[];
       command: Command<Pattern>;
+      meta?: RouteMeta;
     }
   | {
       type: 'rawPattern';
       path: string[];
       rawPattern: RawPattern<Pattern>;
+      meta?: RouteMeta;
     };
 type RouteMatchResult =
   | {
@@ -5617,16 +5600,22 @@ type RouteMatchResult =
       path: string[];
       command: Command<Pattern>;
       params: any;
+      activation?: RouteActivation;
     }
   | {
       type: 'rawPattern';
       path: string[];
       rawPattern: RawPattern<Pattern>;
       params: any;
+      activation?: RouteActivation;
     };
 declare class Router {
-  private readonly entries;
-  private readonly groups;
+  private entries;
+  private groups;
+  private activationResolver;
+  private scopeMeta?;
+  setActivationResolver(resolver: RouteActivationResolver): this;
+  withMeta(meta: RouteMeta): Router;
   command(name: string): CommandBuilder;
   command<P extends Pattern>(command: Command<P>): this;
   rawPattern(): CommandBuilder<{}, RawPattern<{}>>;
@@ -5638,17 +5627,107 @@ declare class Router {
   branches(session: Session): RouteBranch[];
   match(session: Session, message: IncomingMessage): RouteMatchResult | undefined;
   dispatch(session: Session, message: IncomingMessage): Promise<boolean>;
-  private matchFrom;
-  private matchEntry;
+  private describeBranch;
+  private consumeActivation;
+  private matchBranch;
+  private matchPath;
   private matchCommand;
-  private matchGroup;
   private matchRawPattern;
   private branchesFrom;
+  private applyScopeMeta;
   private resolveAliasConflicts;
   private validatePattern;
   private capturePattern;
 }
 //#endregion
+//#region src/core/activation.d.ts
+type ContextRouteActivationByScene = Partial<
+  Record<IncomingMessage['message_scene'] | 'default', readonly RouteActivation[]>
+>;
+type ContextRouteActivation = readonly RouteActivation[] | ContextRouteActivationByScene;
+interface ContextRouteActivationMatcher {
+  type?: RouteDescriptor['type'] | readonly RouteDescriptor['type'][];
+  plugin?: string | readonly string[];
+  context?: string | readonly string[];
+  tag?: string | readonly string[];
+  command?: string | readonly string[];
+  path?: readonly string[];
+  route?: readonly string[];
+  predicate?: (route: RouteDescriptor, session: Session) => boolean;
+}
+interface ContextRouteActivationRule {
+  match?: ContextRouteActivationMatcher;
+  activation: ContextRouteActivation;
+}
+interface ContextRouteActivationConfig {
+  default?: ContextRouteActivation;
+  rules?: ContextRouteActivationRule | readonly ContextRouteActivationRule[];
+}
+interface ContextRoutingOptions {
+  activation?: ContextRouteActivationConfig;
+  activationResolver?: RouteActivationResolver;
+}
+declare function createContextRouteActivationResolver(
+  routing: ContextRoutingOptions | undefined,
+  fallback?: RouteActivationResolver,
+): RouteActivationResolver;
+//#endregion
+//#region src/protocol/endpoint.d.ts
+type RequiredKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? never : K }[keyof T];
+type AllOptional<T> = RequiredKeys<T> extends never ? true : false;
+type RawApiEndpoint<E extends keyof ApiEndpoints$1> = {
+  request: ApiEndpoints$1[E]['request_ZodInput'] extends null ? null : ApiEndpoints$1[E]['request_ZodInput'];
+  response: ApiEndpoints$1[E]['response'] extends null ? null : ApiEndpoints$1[E]['response'];
+};
+type ApiEndpointFunction<E extends keyof ApiEndpoints$1> = RawApiEndpoint<E>['request'] extends null
+  ? () => Promise<RawApiEndpoint<E>['response']>
+  : AllOptional<RawApiEndpoint<E>['request']> extends true
+    ? (params?: RawApiEndpoint<E>['request']) => Promise<RawApiEndpoint<E>['response']>
+    : (params: RawApiEndpoint<E>['request']) => Promise<RawApiEndpoint<E>['response']>;
+type ApiEndpoints = { [E in keyof ApiEndpoints$1]: ApiEndpointFunction<E> };
+type EventMap = {
+  [K in Event['event_type']]: Extract<
+    Event,
+    {
+      event_type: K;
+    }
+  >;
+};
+//#endregion
+//#region src/protocol/client.d.ts
+interface MilkyClient extends ApiEndpoints {}
+declare class MilkyClientBase {
+  readonly baseUrl: string;
+  readonly wsBaseUrl: string;
+  private readonly accessToken?;
+  private readonly baseHeaders;
+  constructor(
+    baseUrl: string | URL,
+    options?: {
+      accessToken?: string;
+    },
+  );
+  callApi(endpoint: string, params?: unknown): Promise<unknown>;
+}
+declare function createMilkyClient(...params: ConstructorParameters<typeof MilkyClientBase>): MilkyClient;
+//#endregion
+//#region src/protocol/event.d.ts
+interface MilkyEventSubscription {
+  closed: Promise<void>;
+  stop(): void | Promise<void>;
+}
+interface MilkyEventSource {
+  readonly name?: string;
+  start(onEvent: (event: Event) => void | Promise<void>): Promise<MilkyEventSubscription>;
+}
+interface MilkyWebSocketEventSourceOptions {
+  accessToken?: string;
+}
+declare function createMilkyWebSocketEventSource(
+  baseUrl: string | URL,
+  options?: MilkyWebSocketEventSourceOptions,
+): MilkyEventSource;
+//#endregion
 //#region src/core/filter.d.ts
 type Filter = { [K in keyof EventMap]?: (event: EventMap[K]) => boolean };
 declare namespace filter {
@@ -5731,6 +5810,7 @@ interface ContextOptions {
     maxDelayMs?: number;
   };
   logHandler?: LogHandler;
+  routing?: ContextRoutingOptions;
 }
 interface ContextUrlOptions {
   accessToken?: string;
@@ -5741,6 +5821,7 @@ declare class Context {
   readonly router: Router;
   readonly logger: Logger;
   readonly name: string;
+  readonly routeActivationResolver: RouteActivationResolver;
   private readonly parent?;
   private readonly filter?;
   private readonly eventBus;
@@ -5848,6 +5929,12 @@ export {
   CommandBuilder,
   Context,
   ContextOptions,
+  ContextRouteActivation,
+  ContextRouteActivationByScene,
+  ContextRouteActivationConfig,
+  ContextRouteActivationMatcher,
+  ContextRouteActivationRule,
+  ContextRoutingOptions,
   ContextUrlOptions,
   Disposable,
   EventMap,
@@ -5868,9 +5955,13 @@ export {
   Pattern,
   Plugin,
   RawPattern,
+  RouteActivation,
+  RouteActivationResolver,
   RouteBranch,
+  RouteDescriptor,
   RouteEntry,
   RouteMatchResult,
+  RouteMeta,
   Router,
   ServiceClass,
   Session,
@@ -5878,12 +5969,15 @@ export {
   SessionReplyOptions,
   TypeInstruction,
   combineLogHandlers,
+  createContextRouteActivationResolver,
   createMilkyClient,
   createMilkyWebSocketEventSource,
+  defaultRouteActivationResolver,
   definePlugin,
   filter,
   implementsESNextDisposable,
   isDisposable,
+  mergeRouteMeta,
   type types_d_exports as milky,
   milkyPackageVersion,
   milkyVersion,

package/dist/index.mjs

@@ -1,210 +1,4 @@
 import mitt from "mitt";
-//#region src/protocol/client.ts
-var MilkyClientBase = class {
-	baseUrl;
-	wsBaseUrl;
-	accessToken;
-	baseHeaders;
-	constructor(baseUrl, options) {
-		const normalizedBaseUrl = baseUrl.toString();
-		this.baseUrl = normalizedBaseUrl.endsWith("/") ? normalizedBaseUrl.slice(0, -1) : normalizedBaseUrl;
-		this.wsBaseUrl = this.baseUrl.replace(/^http/, "ws");
-		this.accessToken = options?.accessToken;
-		this.baseHeaders = { "Content-Type": "application/json" };
-		if (options?.accessToken) this.baseHeaders.Authorization = `Bearer ${options.accessToken}`;
-	}
-	async callApi(endpoint, params) {
-		const response = await fetch(`${this.baseUrl}/api/${endpoint}`, {
-			method: "POST",
-			body: JSON.stringify(params ?? {}),
-			headers: this.baseHeaders
-		});
-		if (!response.ok) throw new Error(`API call ${endpoint} failed with HTTP status ${response.status}`);
-		const json = await response.json();
-		if (json.status === "failed") throw new Error(`API call ${endpoint} failed with retcode ${json.retcode}: ${json.message}`);
-		return json.data;
-	}
-};
-function createMilkyClient(...params) {
-	const base = new MilkyClientBase(...params);
-	return new Proxy(base, { get(target, endpoint) {
-		if (typeof endpoint === "string" && endpoint.includes("_")) return (params) => target.callApi(endpoint, params);
-		else return target[endpoint];
-	} });
-}
-//#endregion
-//#region src/protocol/event.ts
-function createMilkyWebSocketEventSource(baseUrl, options) {
-	const normalizedBaseUrl = baseUrl.toString();
-	const wsBaseUrl = normalizedBaseUrl.endsWith("/") ? normalizedBaseUrl.slice(0, -1).replace(/^http/, "ws") : normalizedBaseUrl.replace(/^http/, "ws");
-	return {
-		name: "websocket",
-		async start(onEvent) {
-			const ws = new WebSocket(`${wsBaseUrl}/event${options?.accessToken ? `?access_token=${options.accessToken}` : ""}`);
-			let closeSubscription = () => {};
-			const closed = new Promise((resolve, reject) => {
-				closeSubscription = (error) => {
-					if (error) reject(error);
-					else resolve();
-				};
-			});
-			ws.addEventListener("message", async (event) => {
-				try {
-					if (typeof event.data !== "string") throw new Error(`Expected text frame, got ${typeof event.data}`);
-					await onEvent(JSON.parse(event.data));
-				} catch (error) {
-					closeSubscription(error);
-					ws.close();
-				}
-			});
-			await new Promise((resolve, reject) => {
-				ws.addEventListener("open", () => resolve(), { once: true });
-				ws.addEventListener("error", (event) => reject(/* @__PURE__ */ new Error(`WebSocket error: ${event}`)));
-			});
-			ws.addEventListener("error", (event) => closeSubscription(/* @__PURE__ */ new Error(`WebSocket error: ${event}`)));
-			ws.addEventListener("close", () => closeSubscription(), { once: true });
-			return {
-				closed,
-				stop() {
-					ws.close();
-				}
-			};
-		}
-	};
-}
-//#endregion
-//#region src/protocol/segment.ts
-function msg(strings, ...values) {
-	let buffer = "";
-	const segments = [];
-	for (let i = 0; i < strings.length; i++) {
-		buffer += strings[i];
-		if (i < values.length) {
-			const value = values[i];
-			if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") buffer += value.toString();
-			else {
-				if (buffer) {
-					segments.push({
-						type: "text",
-						data: { text: buffer }
-					});
-					buffer = "";
-				}
-				segments.push(value);
-			}
-		}
-	}
-	if (buffer) segments.push({
-		type: "text",
-		data: { text: buffer }
-	});
-	return trimBoundaryTextSegments(segments);
-}
-function isTextSegment(segment) {
-	return segment.type === "text";
-}
-function withText(segment, text) {
-	return {
-		...segment,
-		data: {
-			...segment.data,
-			text
-		}
-	};
-}
-function trimBoundaryTextSegments(segments) {
-	const result = [...segments];
-	const first = result[0];
-	if (first && isTextSegment(first)) {
-		const text = first.data.text.trimStart();
-		if (text) result[0] = withText(first, text);
-		else result.shift();
-	}
-	const lastIndex = result.length - 1;
-	const last = result[lastIndex];
-	if (last && isTextSegment(last)) {
-		const text = last.data.text.trimEnd();
-		if (text) result[lastIndex] = withText(last, text);
-		else result.pop();
-	}
-	return result;
-}
-let seg;
-(function(_seg) {
-	function mention(userId) {
-		return {
-			type: "mention",
-			data: { user_id: userId }
-		};
-	}
-	_seg.mention = mention;
-	function mentionAll() {
-		return {
-			type: "mention_all",
-			data: {}
-		};
-	}
-	_seg.mentionAll = mentionAll;
-	function face(faceId, options) {
-		return {
-			type: "face",
-			data: {
-				face_id: faceId.toString(),
-				is_large: options?.isLarge ?? false
-			}
-		};
-	}
-	_seg.face = face;
-	function reply(messageSeq) {
-		return {
-			type: "reply",
-			data: { message_seq: messageSeq }
-		};
-	}
-	_seg.reply = reply;
-	function image(uri, options) {
-		return {
-			type: "image",
-			data: {
-				uri,
-				sub_type: options?.subType,
-				summary: options?.summary
-			}
-		};
-	}
-	_seg.image = image;
-	function record(uri) {
-		return {
-			type: "record",
-			data: { uri }
-		};
-	}
-	_seg.record = record;
-	function video(uri, options) {
-		return {
-			type: "video",
-			data: {
-				uri,
-				thumb_uri: options?.thumbUri
-			}
-		};
-	}
-	_seg.video = video;
-	function forward(messages, options) {
-		return {
-			type: "forward",
-			data: {
-				messages,
-				title: options?.title,
-				preview: options?.preview,
-				summary: options?.summary,
-				prompt: options?.prompt
-			}
-		};
-	}
-	_seg.forward = forward;
-})(seg || (seg = {}));
-//#endregion
 //#region src/routing/command.ts
 var CommandBuilder = class {
 	name;
@@ -214,6 +8,7 @@ var CommandBuilder = class {
 	description;
 	aliases;
 	hidden;
+	routeMeta;
 	constructor(name, sink = (command) => command) {
 		this.name = name;
 		this.sink = sink;
@@ -235,6 +30,14 @@ var CommandBuilder = class {
 		this.hidden = true;
 		return this;
 	}
+	meta(meta) {
+		this.routeMeta = mergeRouteMeta(this.routeMeta, meta);
+		return this;
+	}
+	tag(...tags) {
+		this.routeMeta = mergeRouteMeta(this.routeMeta, { tags });
+		return this;
+	}
 	execute(executor) {
 		this.executor = executor;
 		const command = {
@@ -245,9 +48,31 @@ var CommandBuilder = class {
 		if (this.description !== void 0) command.description = this.description;
 		if (this.aliases !== void 0) command.aliases = this.aliases;
 		if (this.hidden !== void 0) command.hidden = this.hidden;
+		if (this.routeMeta !== void 0) command.meta = this.routeMeta;
 		return this.sink(command);
 	}
 };
+function mergeRouteMeta(left, right) {
+	if (left === void 0 && right === void 0) return;
+	const merged = {
+		...left ?? {},
+		...right ?? {}
+	};
+	const tags = uniqueTags(left?.tags, right?.tags);
+	if (tags.length > 0) merged.tags = tags;
+	else delete merged.tags;
+	return Object.keys(merged).length > 0 ? merged : void 0;
+}
+function uniqueTags(...tagLists) {
+	const tags = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const tagList of tagLists) for (const tag of tagList ?? []) {
+		if (seen.has(tag)) continue;
+		seen.add(tag);
+		tags.push(tag);
+	}
+	return tags;
+}
 //#endregion
 //#region src/routing/tokenizer.ts
 const WHITESPACE_CHARS = new Set([
@@ -352,6 +177,33 @@ var Tokenizer = class {
 		this.subOffset = void 0;
 		return segments;
 	}
+	consumeMention(userId) {
+		const token = this.peek();
+		if (typeof token === "object" && token !== null && token.type === "mention" && token.data.user_id === userId) {
+			this.next();
+			return true;
+		}
+		return false;
+	}
+	consumeTextPrefix(prefix) {
+		if (prefix.length === 0) return false;
+		const position = this.findNextPosition();
+		if (position === void 0) return false;
+		const segment = this.segments[position.offset];
+		if (segment.type !== "text") return false;
+		const prefixStart = this.findTextTokenStart(segment.data.text, position.subOffset ?? 0);
+		if (!segment.data.text.startsWith(prefix, prefixStart)) return false;
+		const prefixEnd = prefixStart + prefix.length;
+		const nextSubOffset = this.findTextTokenStart(segment.data.text, prefixEnd);
+		if (nextSubOffset < segment.data.text.length) {
+			this.offset = position.offset;
+			this.subOffset = nextSubOffset;
+		} else {
+			this.offset = position.offset + 1;
+			this.subOffset = void 0;
+		}
+		return true;
+	}
 	findNextPosition() {
 		let offset = this.offset;
 		let subOffset = this.subOffset;
@@ -383,19 +235,35 @@ var Tokenizer = class {
 };
 //#endregion
 //#region src/routing/router.ts
+const DEFAULT_ACTIVATIONS = [{ type: "direct" }];
+const defaultRouteActivationResolver = () => DEFAULT_ACTIVATIONS;
 var Router = class Router {
 	entries = [];
 	groups = /* @__PURE__ */ new Map();
+	activationResolver = defaultRouteActivationResolver;
+	scopeMeta;
+	setActivationResolver(resolver) {
+		this.activationResolver = resolver;
+		return this;
+	}
+	withMeta(meta) {
+		const router = new Router();
+		router.entries = this.entries;
+		router.groups = this.groups;
+		router.scopeMeta = mergeRouteMeta(this.scopeMeta, meta);
+		return router;
+	}
 	command(command) {
 		if (typeof command === "string") return new CommandBuilder(command, (builtCommand) => {
 			this.command(builtCommand);
 			return builtCommand;
 		});
-		this.validatePattern(command.pattern);
-		this.resolveAliasConflicts(command);
+		const scopedCommand = this.applyScopeMeta(command);
+		this.validatePattern(scopedCommand.pattern);
+		this.resolveAliasConflicts(scopedCommand);
 		this.entries.push({
 			type: "command",
-			command
+			command: scopedCommand
 		});
 		return this;
 	}
@@ -404,10 +272,11 @@ var Router = class Router {
 			this.rawPattern(builtCommand);
 			return builtCommand;
 		});
-		this.validatePattern(rawPattern.pattern, { rawPattern: true });
+		const scopedRawPattern = this.applyScopeMeta(rawPattern);
+		this.validatePattern(scopedRawPattern.pattern, { rawPattern: true });
 		this.entries.push({
 			type: "rawPattern",
-			rawPattern
+			rawPattern: scopedRawPattern
 		});
 		return this;
 	}
@@ -422,7 +291,7 @@ var Router = class Router {
 				router
 			});
 		}
-		return router;
+		return this.scopeMeta ? router.withMeta(this.scopeMeta) : router;
 	}
 	filter(predicate) {
 		const router = new Router();
@@ -431,7 +300,7 @@ var Router = class Router {
 			predicate,
 			router
 		});
-		return router;
+		return this.scopeMeta ? router.withMeta(this.scopeMeta) : router;
 	}
 	routes() {
 		return this.entries;
@@ -441,11 +310,19 @@ var Router = class Router {
 		return [];
 	}
 	branches(session) {
-		return this.branchesFrom(session, []);
+		return [...this.branchesFrom(session, [], { includeHidden: false })];
 	}
 	match(session, message) {
-		const tokenizer = new Tokenizer(message.segments);
-		return this.matchFrom(session, tokenizer, []);
+		for (const branch of this.branchesFrom(session, [], { includeHidden: true })) {
+			const descriptor = this.describeBranch(branch);
+			const activations = this.activationResolver(descriptor, session) ?? DEFAULT_ACTIVATIONS;
+			for (const activation of activations) {
+				const tokenizer = new Tokenizer(message.segments);
+				if (!this.consumeActivation(tokenizer, activation, session)) continue;
+				const match = this.matchBranch(branch, tokenizer, activation);
+				if (match !== void 0) return match;
+			}
+		}
 	}
 	async dispatch(session, message) {
 		const match = this.match(session, message);
@@ -460,26 +337,51 @@ var Router = class Router {
 		}
 		return true;
 	}
-	matchFrom(session, tokenizer, path) {
-		const initialState = tokenizer.getState();
-		for (const entry of this.entries) {
-			tokenizer.setState(initialState);
-			const match = this.matchEntry(entry, session, tokenizer, path);
-			if (match !== void 0) return match;
+	describeBranch(branch) {
+		switch (branch.type) {
+			case "command": {
+				const descriptor = {
+					type: "command",
+					path: [...branch.path],
+					name: branch.command.name
+				};
+				if (branch.command.aliases !== void 0) descriptor.aliases = [...branch.command.aliases];
+				if (branch.command.meta !== void 0) descriptor.meta = branch.command.meta;
+				return descriptor;
+			}
+			case "rawPattern": {
+				const descriptor = {
+					type: "rawPattern",
+					path: [...branch.path]
+				};
+				if (branch.rawPattern.meta !== void 0) descriptor.meta = branch.rawPattern.meta;
+				return descriptor;
+			}
 		}
-		tokenizer.setState(initialState);
 	}
-	matchEntry(entry, session, tokenizer, path) {
-		switch (entry.type) {
-			case "command": return this.matchCommand(entry.command, tokenizer, path);
-			case "group": return this.matchGroup(entry.name, entry.router, session, tokenizer, path);
-			case "filter":
-				if (entry.predicate(session) !== true) return;
-				return entry.router.matchFrom(session, tokenizer, path);
-			case "rawPattern": return this.matchRawPattern(entry.rawPattern, tokenizer, path);
+	consumeActivation(tokenizer, activation, session) {
+		switch (activation.type) {
+			case "direct": return true;
+			case "mention": return tokenizer.consumeMention(session.selfId);
+			case "prefix": return tokenizer.consumeTextPrefix(activation.prefix);
+		}
+	}
+	matchBranch(branch, tokenizer, activation) {
+		if (!this.matchPath(branch.path, tokenizer)) return;
+		switch (branch.type) {
+			case "command": return this.matchCommand(branch.command, tokenizer, branch.path, activation);
+			case "rawPattern": return this.matchRawPattern(branch.rawPattern, tokenizer, branch.path, activation);
+		}
+	}
+	matchPath(path, tokenizer) {
+		for (const name of path) {
+			const token = tokenizer.peek();
+			if (typeof token !== "string" || token !== name) return false;
+			tokenizer.next();
 		}
+		return true;
 	}
-	matchCommand(command, tokenizer, path) {
+	matchCommand(command, tokenizer, path, activation) {
 		const token = tokenizer.peek();
 		if (typeof token !== "string" || token !== command.name && !command.aliases?.includes(token)) return;
 		tokenizer.next();
@@ -489,50 +391,55 @@ var Router = class Router {
 			type: "command",
 			path: [...path],
 			command,
-			params
+			params,
+			activation
 		};
 	}
-	matchGroup(name, router, session, tokenizer, path) {
-		const token = tokenizer.peek();
-		if (typeof token !== "string" || token !== name) return;
-		tokenizer.next();
-		return router.matchFrom(session, tokenizer, [...path, name]);
-	}
-	matchRawPattern(rawPattern, tokenizer, path) {
+	matchRawPattern(rawPattern, tokenizer, path, activation) {
 		const params = this.capturePattern(rawPattern.pattern, tokenizer);
 		if (params === void 0 || tokenizer.hasNext()) return;
 		return {
 			type: "rawPattern",
 			path: [...path],
 			rawPattern,
-			params
+			params,
+			activation
 		};
 	}
-	branchesFrom(session, path) {
-		const branches = [];
+	*branchesFrom(session, path, options) {
 		for (const entry of this.entries) switch (entry.type) {
 			case "command":
-				if (!entry.command.hidden) branches.push({
+				if (options.includeHidden || !entry.command.hidden) yield {
 					type: "command",
 					path: [...path],
-					command: entry.command
-				});
+					command: entry.command,
+					meta: entry.command.meta
+				};
 				break;
 			case "group":
-				branches.push(...entry.router.branchesFrom(session, [...path, entry.name]));
+				yield* entry.router.branchesFrom(session, [...path, entry.name], options);
 				break;
 			case "filter":
-				if (entry.predicate(session) === true) branches.push(...entry.router.branchesFrom(session, path));
+				if (entry.predicate(session) === true) yield* entry.router.branchesFrom(session, path, options);
 				break;
 			case "rawPattern":
-				branches.push({
+				yield {
 					type: "rawPattern",
 					path: [...path],
-					rawPattern: entry.rawPattern
-				});
+					rawPattern: entry.rawPattern,
+					meta: entry.rawPattern.meta
+				};
 				break;
 		}
-		return branches;
+	}
+	applyScopeMeta(route) {
+		if (this.scopeMeta === void 0) return route;
+		const meta = mergeRouteMeta(route.meta, this.scopeMeta);
+		if (meta === void 0) return route;
+		return {
+			...route,
+			meta
+		};
 	}
 	resolveAliasConflicts(command) {
 		for (const entry of this.entries) {
@@ -579,6 +486,283 @@ var Router = class Router {
 	}
 };
 //#endregion
+//#region src/core/activation.ts
+function createContextRouteActivationResolver(routing, fallback = defaultRouteActivationResolver) {
+	if (!routing) return fallback;
+	if (routing.activation && routing.activationResolver) throw new Error("Context routing cannot specify both activation and activationResolver.");
+	if (routing.activationResolver) return routing.activationResolver;
+	if (routing.activation) return compileContextRouteActivationConfig(routing.activation, fallback);
+	return fallback;
+}
+function compileContextRouteActivationConfig(config, fallback) {
+	return (route, session) => {
+		for (const rule of contextRouteActivationRules(config.rules)) {
+			if (!matchesContextRouteActivationRule(route, session, rule)) continue;
+			const activation = resolveContextRouteActivation(rule.activation, session.raw.message_scene);
+			if (activation !== void 0) return activation;
+		}
+		if (config.default !== void 0) {
+			const activation = resolveContextRouteActivation(config.default, session.raw.message_scene);
+			if (activation !== void 0) return activation;
+		}
+		return fallback(route, session);
+	};
+}
+function contextRouteActivationRules(rules) {
+	if (rules === void 0) return [];
+	return isContextRouteActivationRuleArray(rules) ? rules : [rules];
+}
+function isContextRouteActivationRuleArray(rules) {
+	return Array.isArray(rules);
+}
+function resolveContextRouteActivation(activation, scene) {
+	if (isRouteActivationArray(activation)) return activation;
+	return activation[scene] ?? activation.default;
+}
+function isRouteActivationArray(activation) {
+	return Array.isArray(activation);
+}
+function matchesContextRouteActivationRule(route, session, rule) {
+	const match = rule.match;
+	if (!match) return true;
+	if (!matchesStringSelector(match.type, route.type)) return false;
+	if (!matchesStringSelector(match.plugin, routeMetaString(route, "plugin"))) return false;
+	if (!matchesStringSelector(match.context, routeMetaString(route, "context"))) return false;
+	if (!matchesTagSelector(match.tag, route.meta?.tags)) return false;
+	if (match.command !== void 0 && (route.type !== "command" || !matchesStringSelector(match.command, route.name))) return false;
+	if (match.path !== void 0 && !sameStringArray(match.path, route.path)) return false;
+	if (match.route !== void 0 && !sameStringArray(match.route, routeSegments(route))) return false;
+	if (match.predicate && match.predicate(route, session) !== true) return false;
+	return true;
+}
+function routeMetaString(route, key) {
+	const value = route.meta?.[key];
+	return typeof value === "string" ? value : void 0;
+}
+function matchesStringSelector(selector, value) {
+	if (selector === void 0) return true;
+	if (value === void 0) return false;
+	return typeof selector === "string" ? selector === value : selector.includes(value);
+}
+function matchesTagSelector(selector, tags) {
+	if (selector === void 0) return true;
+	if (!tags) return false;
+	return typeof selector === "string" ? tags.includes(selector) : selector.some((tag) => tags.includes(tag));
+}
+function routeSegments(route) {
+	if (route.type === "command") return [...route.path, route.name];
+	return route.path;
+}
+function sameStringArray(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+//#endregion
+//#region src/protocol/client.ts
+var MilkyClientBase = class {
+	baseUrl;
+	wsBaseUrl;
+	accessToken;
+	baseHeaders;
+	constructor(baseUrl, options) {
+		const normalizedBaseUrl = baseUrl.toString();
+		this.baseUrl = normalizedBaseUrl.endsWith("/") ? normalizedBaseUrl.slice(0, -1) : normalizedBaseUrl;
+		this.wsBaseUrl = this.baseUrl.replace(/^http/, "ws");
+		this.accessToken = options?.accessToken;
+		this.baseHeaders = { "Content-Type": "application/json" };
+		if (options?.accessToken) this.baseHeaders.Authorization = `Bearer ${options.accessToken}`;
+	}
+	async callApi(endpoint, params) {
+		const response = await fetch(`${this.baseUrl}/api/${endpoint}`, {
+			method: "POST",
+			body: JSON.stringify(params ?? {}),
+			headers: this.baseHeaders
+		});
+		if (!response.ok) throw new Error(`API call ${endpoint} failed with HTTP status ${response.status}`);
+		const json = await response.json();
+		if (json.status === "failed") throw new Error(`API call ${endpoint} failed with retcode ${json.retcode}: ${json.message}`);
+		return json.data;
+	}
+};
+function createMilkyClient(...params) {
+	const base = new MilkyClientBase(...params);
+	return new Proxy(base, { get(target, endpoint) {
+		if (typeof endpoint === "string" && endpoint.includes("_")) return (params) => target.callApi(endpoint, params);
+		else return target[endpoint];
+	} });
+}
+//#endregion
+//#region src/protocol/event.ts
+function createMilkyWebSocketEventSource(baseUrl, options) {
+	const normalizedBaseUrl = baseUrl.toString();
+	const wsBaseUrl = normalizedBaseUrl.endsWith("/") ? normalizedBaseUrl.slice(0, -1).replace(/^http/, "ws") : normalizedBaseUrl.replace(/^http/, "ws");
+	return {
+		name: "websocket",
+		async start(onEvent) {
+			const ws = new WebSocket(`${wsBaseUrl}/event${options?.accessToken ? `?access_token=${options.accessToken}` : ""}`);
+			let closeSubscription = () => {};
+			const closed = new Promise((resolve, reject) => {
+				closeSubscription = (error) => {
+					if (error) reject(error);
+					else resolve();
+				};
+			});
+			ws.addEventListener("message", async (event) => {
+				try {
+					if (typeof event.data !== "string") throw new Error(`Expected text frame, got ${typeof event.data}`);
+					await onEvent(JSON.parse(event.data));
+				} catch (error) {
+					closeSubscription(error);
+					ws.close();
+				}
+			});
+			await new Promise((resolve, reject) => {
+				ws.addEventListener("open", () => resolve(), { once: true });
+				ws.addEventListener("error", (event) => reject(/* @__PURE__ */ new Error(`WebSocket error: ${event}`)));
+			});
+			ws.addEventListener("error", (event) => closeSubscription(/* @__PURE__ */ new Error(`WebSocket error: ${event}`)));
+			ws.addEventListener("close", () => closeSubscription(), { once: true });
+			return {
+				closed,
+				stop() {
+					ws.close();
+				}
+			};
+		}
+	};
+}
+//#endregion
+//#region src/protocol/segment.ts
+function msg(strings, ...values) {
+	let buffer = "";
+	const segments = [];
+	for (let i = 0; i < strings.length; i++) {
+		buffer += strings[i];
+		if (i < values.length) {
+			const value = values[i];
+			if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") buffer += value.toString();
+			else {
+				if (buffer) {
+					segments.push({
+						type: "text",
+						data: { text: buffer }
+					});
+					buffer = "";
+				}
+				segments.push(value);
+			}
+		}
+	}
+	if (buffer) segments.push({
+		type: "text",
+		data: { text: buffer }
+	});
+	return trimBoundaryTextSegments(segments);
+}
+function isTextSegment(segment) {
+	return segment.type === "text";
+}
+function withText(segment, text) {
+	return {
+		...segment,
+		data: {
+			...segment.data,
+			text
+		}
+	};
+}
+function trimBoundaryTextSegments(segments) {
+	const result = [...segments];
+	const first = result[0];
+	if (first && isTextSegment(first)) {
+		const text = first.data.text.trimStart();
+		if (text) result[0] = withText(first, text);
+		else result.shift();
+	}
+	const lastIndex = result.length - 1;
+	const last = result[lastIndex];
+	if (last && isTextSegment(last)) {
+		const text = last.data.text.trimEnd();
+		if (text) result[lastIndex] = withText(last, text);
+		else result.pop();
+	}
+	return result;
+}
+let seg;
+(function(_seg) {
+	function mention(userId) {
+		return {
+			type: "mention",
+			data: { user_id: userId }
+		};
+	}
+	_seg.mention = mention;
+	function mentionAll() {
+		return {
+			type: "mention_all",
+			data: {}
+		};
+	}
+	_seg.mentionAll = mentionAll;
+	function face(faceId, options) {
+		return {
+			type: "face",
+			data: {
+				face_id: faceId.toString(),
+				is_large: options?.isLarge ?? false
+			}
+		};
+	}
+	_seg.face = face;
+	function reply(messageSeq) {
+		return {
+			type: "reply",
+			data: { message_seq: messageSeq }
+		};
+	}
+	_seg.reply = reply;
+	function image(uri, options) {
+		return {
+			type: "image",
+			data: {
+				uri,
+				sub_type: options?.subType,
+				summary: options?.summary
+			}
+		};
+	}
+	_seg.image = image;
+	function record(uri) {
+		return {
+			type: "record",
+			data: { uri }
+		};
+	}
+	_seg.record = record;
+	function video(uri, options) {
+		return {
+			type: "video",
+			data: {
+				uri,
+				thumb_uri: options?.thumbUri
+			}
+		};
+	}
+	_seg.video = video;
+	function forward(messages, options) {
+		return {
+			type: "forward",
+			data: {
+				messages,
+				title: options?.title,
+				preview: options?.preview,
+				summary: options?.summary,
+				prompt: options?.prompt
+			}
+		};
+	}
+	_seg.forward = forward;
+})(seg || (seg = {}));
+//#endregion
 //#region src/core/logging.ts
 var Logger = class {
 	logHandler;
@@ -631,6 +815,7 @@ var Context = class Context {
 	router = new Router();
 	logger;
 	name;
+	routeActivationResolver;
 	parent;
 	filter;
 	eventBus = mitt();
@@ -653,6 +838,8 @@ var Context = class Context {
 		this.logHandler = options?.logHandler ?? parent?.logHandler;
 		this.name = name ?? "root";
 		this.logger = new Logger((message) => this.logHandler?.(message), `context:${this.name}`);
+		this.routeActivationResolver = createContextRouteActivationResolver(options?.routing, parent?.routeActivationResolver);
+		this.router.setActivationResolver(this.routeActivationResolver);
 		this.parent = parent;
 		this.filter = filter;
 		if (parent) {
@@ -1015,6 +1202,10 @@ and implement the dispose method to clean up resources when the context stops.
 	}
 	createProxyContextForPlugin(plugin) {
 		const proxyLogger = new Logger((message) => this.logHandler?.(message), `plugin:${this.name ? `${this.name}/` : ""}${plugin.name}`);
+		const proxyRouter = this.router.withMeta({
+			context: this.name,
+			plugin: plugin.name
+		});
 		let proxyInjections;
 		if (plugin.inject) {
 			proxyInjections = {};
@@ -1026,6 +1217,7 @@ and implement the dispose method to clean up resources when the context stops.
 		}
 		return new Proxy(this, { get(target, prop, receiver) {
 			if (prop === "logger") return proxyLogger;
+			else if (prop === "router") return proxyRouter;
 			else if (proxyInjections && prop in proxyInjections) return proxyInjections[prop];
 			else return Reflect.get(target, prop, receiver);
 		} });
@@ -1382,4 +1574,4 @@ let param;
 	_param.segment = segment;
 })(param || (param = {}));
 //#endregion
-export { CommandBuilder, Context, Logger, Parameter, Router, combineLogHandlers, createMilkyClient, createMilkyWebSocketEventSource, definePlugin, filter, implementsESNextDisposable, isDisposable, milkyPackageVersion, milkyVersion, msg, param, seg };
+export { CommandBuilder, Context, Logger, Parameter, Router, combineLogHandlers, createContextRouteActivationResolver, createMilkyClient, createMilkyWebSocketEventSource, defaultRouteActivationResolver, definePlugin, filter, implementsESNextDisposable, isDisposable, mergeRouteMeta, milkyPackageVersion, milkyVersion, msg, param, seg };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fraqjs/fraq",
   "type": "module",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Milky Bot framework",
   "files": [
     "dist"
@@ -14,7 +14,7 @@
     "type": "git",
     "url": "git+https://github.com/fraqjs/fraq.git"
   },
-  "homepage": "https://fraq.ntqqrev.org/",
+  "homepage": "https://fraq.dev/",
   "license": "MIT",
   "dependencies": {
     "mitt": "^3.0.1"