@zhin.js/service-activity-feedback 1.0.1 → 1.1.0

package/src/executor.ts

@@ -1,23 +1,185 @@
-import type { Adapter } from 'zhin.js';
-import { enableActivityFeedbackForBot, isGenericActivityFeedbackManager, type ActivityFeedbackManager, type ActivityFeedbackPhase, type EndpointWithActivityFeedback, type PlatformActivityFeedbackManager, type ResolvedActivityFeedbackPhaseConfig, type ActivityFeedbackEventContext } from '@zhin.js/agent';
+import { enableActivityFeedbackForBot, isGenericActivityFeedbackManager, type ActivityFeedbackManager, type ActivityFeedbackPhase, type ActivityFeedbackSendPort, type EndpointWithActivityFeedback, type PlatformActivityFeedbackManager, type ResolvedActivityFeedbackPhaseConfig, type ActivityFeedbackEventContext } from '@zhin.js/agent';
+import type { OutboundHost } from 'zhin.js';
 
 /** IM 侧 endpoint 访问 seam（便于测试注入 fake） */
 export interface ActivityFeedbackEndpointAccess {
   resolve(
     platform: string,
-    endpointId: string,
-  ): { endpoint: EndpointWithActivityFeedback; adapter: Adapter } | undefined;
+    endpointKey: string,
+  ): { endpoint: EndpointWithActivityFeedback; outbound: ActivityFeedbackSendPort } | undefined;
 }
 
-export function createRootEndpointAccess(root: {
-  injectAdapter(platform: string): Adapter | undefined;
-}): ActivityFeedbackEndpointAccess {
+/** Slice-2: no Adapter inject — executor start/stop no-op when resolve returns undefined. */
+export function createNoopEndpointAccess(): ActivityFeedbackEndpointAccess {
   return {
-    resolve(platform, endpointId) {
-      const adapter = root.injectAdapter(platform);
-      const endpoint = adapter?.endpoints?.get(endpointId) as EndpointWithActivityFeedback | undefined;
-      if (!endpoint || !adapter) return undefined;
-      return { endpoint, adapter };
+    resolve() {
+      return undefined;
+    },
+  };
+}
+
+function stringifySendContent(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return content == null ? '' : String(content);
+  return content.map((segment) => {
+    if (typeof segment === 'string') return segment;
+    if (segment && typeof segment === 'object') {
+      const data = (segment as { data?: { text?: string }; text?: string }).data
+        ?? (segment as { text?: string });
+      if (typeof data === 'object' && data && 'text' in data && typeof data.text === 'string') {
+        return data.text;
+      }
+      if (typeof (segment as { text?: string }).text === 'string') {
+        return (segment as { text: string }).text;
+      }
+    }
+    return '';
+  }).join('');
+}
+
+/**
+ * Plugin Runtime: resolve endpoints via OutboundHost → ImRuntime.sendEndpointMessage.
+ * Typing/reaction text goes through the unified outbound chain (no legacy Adapter.inject).
+ *
+ * 按 platform:endpointKey 缓存 { endpoint, outbound }：activity manager 挂在
+ * endpoint.$activityFeedback 上，start/stop 必须解析到同一个对象，否则
+ * stop 时拿不到 manager，typing 指示器永远无法停止。
+ */
+export function createOutboundEndpointAccess(
+  outbound: OutboundHost,
+  logger?: { debug: (msg: string, ...args: unknown[]) => void },
+): ActivityFeedbackEndpointAccess {
+  const cache = new Map<string, {
+    endpoint: EndpointWithActivityFeedback;
+    outbound: ActivityFeedbackSendPort;
+  }>();
+  return {
+    resolve(platform, endpointKey) {
+      const key = JSON.stringify([platform, endpointKey]);
+      const cached = cache.get(key);
+      if (cached) return cached;
+      const declared = outbound.capabilities?.({ adapter: platform, endpointKey })?.operations;
+      const supports = (operation: 'recall' | 'edit' | 'reaction' | 'typing') =>
+        declared?.includes(operation) === true;
+      const recall = outbound.recall;
+      const edit = outbound.edit;
+      const addReaction = outbound.addReaction;
+      const removeReaction = outbound.removeReaction;
+      const typing = outbound.typing;
+      const endpoint = {
+        $id: endpointKey,
+        control: {
+          ...(recall && supports('recall') ? {
+            recall: async (message: Parameters<typeof recall>[0]['message']) => {
+              try {
+                await recall({ adapter: platform, endpointKey, message });
+              } catch (error) {
+                logger?.debug(
+                  `[ActivityFeedback] outbound recall failed (${key}):`,
+                  error instanceof Error ? error.message : String(error),
+                );
+              }
+            },
+          } : {}),
+          ...(edit && supports('edit') ? {
+            edit: async (
+              message: Parameters<typeof edit>[0]['message'],
+              content: unknown,
+            ) => {
+              try {
+                return await edit({ adapter: platform, endpointKey, message, content });
+              } catch (error) {
+                logger?.debug(
+                  `[ActivityFeedback] outbound edit failed (${key}):`,
+                  error instanceof Error ? error.message : String(error),
+                );
+                return null;
+              }
+            },
+          } : {}),
+          ...(addReaction && supports('reaction') ? {
+            addReaction: async (
+              message: Parameters<typeof addReaction>[0]['message'],
+              emoji: string,
+              hint?: { sceneType?: 'private' | 'group' | 'channel'; channelId?: string },
+            ) => {
+              try {
+                return await addReaction({
+                  adapter: platform,
+                  endpointKey,
+                  message,
+                  emoji,
+                  sceneType: hint?.sceneType,
+                  channelId: hint?.channelId,
+                });
+              } catch (error) {
+                logger?.debug(
+                  `[ActivityFeedback] outbound addReaction failed (${key}):`,
+                  error instanceof Error ? error.message : String(error),
+                );
+                return null;
+              }
+            },
+          } : {}),
+          ...(removeReaction && supports('reaction') ? {
+            removeReaction: async (
+              message: Parameters<typeof removeReaction>[0]['message'],
+              reactionId: string,
+            ) => {
+              try {
+                await removeReaction({ adapter: platform, endpointKey, message, reactionId });
+              } catch (error) {
+                logger?.debug(
+                  `[ActivityFeedback] outbound removeReaction failed (${key}):`,
+                  error instanceof Error ? error.message : String(error),
+                );
+              }
+            },
+          } : {}),
+          ...(typing && supports('typing') ? {
+            typing: async (
+              conversation: Parameters<typeof typing>[0]['conversation'],
+              active?: boolean,
+            ) => {
+              try {
+                await typing({ adapter: platform, endpointKey, conversation, active });
+              } catch (error) {
+                logger?.debug(
+                  `[ActivityFeedback] outbound typing failed (${key}):`,
+                  error instanceof Error ? error.message : String(error),
+                );
+              }
+            },
+          } : {}),
+        },
+      } as EndpointWithActivityFeedback;
+      const sendPort: ActivityFeedbackSendPort = {
+        send: async ({ conversation, content }) => {
+          const text = stringifySendContent(content);
+          if (!text || !conversation.id) return null;
+          try {
+            const messageId = await outbound.send({
+              adapter: platform,
+              endpointKey,
+              conversation: {
+                kind: conversation.kind,
+                id: conversation.id,
+              },
+              content: text,
+            });
+            return messageId || null;
+          } catch (error) {
+            logger?.debug(
+              `[ActivityFeedback] outbound send failed (${key}):`,
+              error instanceof Error ? error.message : String(error),
+            );
+            return null;
+          }
+        },
+      };
+      const resolved = { endpoint, outbound: sendPort };
+      cache.set(key, resolved);
+      return resolved;
     },
   };
 }
@@ -75,7 +237,7 @@ class GenericPhaseDriver implements PhaseDriver {
   constructor(
     private readonly endpoint: EndpointWithActivityFeedback,
     private readonly platform: string,
-    private readonly adapter: Adapter,
+    private readonly outbound: ActivityFeedbackSendPort,
   ) {}
 
   private async ensureManager(): Promise<ActivityFeedbackManager> {
@@ -85,7 +247,7 @@ class GenericPhaseDriver implements PhaseDriver {
       this.manager = existing;
       return existing;
     }
-    this.manager = enableActivityFeedbackForBot(this.endpoint, this.platform, this.adapter);
+    this.manager = enableActivityFeedbackForBot(this.endpoint, this.platform, this.outbound);
     return this.manager;
   }
 
@@ -118,13 +280,13 @@ class GenericPhaseDriver implements PhaseDriver {
 function createPhaseDriver(
   endpoint: EndpointWithActivityFeedback,
   platform: string,
-  adapter: Adapter,
+  outbound: ActivityFeedbackSendPort,
 ): PhaseDriver {
   const manager = endpoint.$activityFeedback;
   if (manager && !isGenericActivityFeedbackManager(manager)) {
     return new PlatformPhaseDriver(manager);
   }
-  return new GenericPhaseDriver(endpoint, platform, adapter);
+  return new GenericPhaseDriver(endpoint, platform, outbound);
 }
 
 export class ActivityFeedbackExecutor {
@@ -135,23 +297,37 @@ export class ActivityFeedbackExecutor {
     phase: ActivityFeedbackPhase,
     phaseConfig: ResolvedActivityFeedbackPhaseConfig,
   ): Promise<void> {
-    const resolved = this.access.resolve(ctx.platform, ctx.endpointId);
+    const resolved = this.access.resolve(ctx.platform, ctx.endpointKey);
     if (!resolved) return;
-    const driver = createPhaseDriver(resolved.endpoint, ctx.platform, resolved.adapter);
+    const driver = createPhaseDriver(resolved.endpoint, ctx.platform, resolved.outbound);
     await driver.start(ctx, phase, phaseConfig);
   }
 
   async stop(ctx: ActivityFeedbackEventContext, phase: ActivityFeedbackPhase): Promise<void> {
-    const resolved = this.access.resolve(ctx.platform, ctx.endpointId);
+    const resolved = this.access.resolve(ctx.platform, ctx.endpointKey);
     if (!resolved?.endpoint.$activityFeedback) return;
-    const driver = createPhaseDriver(resolved.endpoint, ctx.platform, resolved.adapter);
+    const driver = createPhaseDriver(resolved.endpoint, ctx.platform, resolved.outbound);
     await driver.stop(ctx, phase);
   }
 
-  async updateThinkingText(ctx: ActivityFeedbackEventContext, text: string): Promise<void> {
-    const resolved = this.access.resolve(ctx.platform, ctx.endpointId);
+  async updateText(
+    ctx: ActivityFeedbackEventContext,
+    phase: ActivityFeedbackPhase,
+    text: string,
+  ): Promise<void> {
+    const resolved = this.access.resolve(ctx.platform, ctx.endpointKey);
     if (!resolved) return;
-    const driver = createPhaseDriver(resolved.endpoint, ctx.platform, resolved.adapter);
-    await driver.updateThinkingText(ctx, text);
+    const driver = createPhaseDriver(resolved.endpoint, ctx.platform, resolved.outbound);
+    const manager = resolved.endpoint.$activityFeedback;
+    if (!manager || !isGenericActivityFeedbackManager(manager)) {
+      if (phase === 'thinking') await driver.updateThinkingText(ctx, text);
+      return;
+    }
+    const indicator = manager.getActiveIndicator(phase, ctx.options);
+    if (indicator?.update) await indicator.update(text);
+  }
+
+  async updateThinkingText(ctx: ActivityFeedbackEventContext, text: string): Promise<void> {
+    await this.updateText(ctx, 'thinking', text);
   }
 }

package/src/index.ts

@@ -1,34 +1,13 @@
 /**
  * @zhin.js/service-activity-feedback
+ *
+ * Pure module exports. Plugin Runtime entry is `plugin.ts`.
  */
-import { usePlugin } from 'zhin.js';
-import {
-  createActivityFeedbackOrchestratorFromPlugin,
-  mountActivityFeedbackService,
-} from './ai-event-binder.js';
-import { loadActivityFeedbackServiceConfig, type ActivityFeedbackServiceConfig } from './config.js';
-
-const plugin = usePlugin();
-const { root, logger } = plugin;
-
-const configService = root.inject('config');
-const appConfig = configService?.getPrimary<{ activityFeedback?: ActivityFeedbackServiceConfig }>() || {};
-const serviceConfig = loadActivityFeedbackServiceConfig(appConfig.activityFeedback);
-
-if (serviceConfig.enabled !== false) {
-  mountActivityFeedbackService(
-    plugin,
-    createActivityFeedbackOrchestratorFromPlugin(plugin, serviceConfig),
-  );
-} else {
-  logger.debug('[ActivityFeedback] disabled by activityFeedback.enabled=false');
-}
-
 export {
-  bindActivityFeedbackToAIEvents,
+  bindActivityFeedbackToAIEventBus,
+  createActivityFeedbackAIEventHandlers,
   createActivityFeedbackOrchestrator,
-  createActivityFeedbackOrchestratorFromPlugin,
-  mountActivityFeedbackService,
+  createActivityFeedbackOrchestratorForRuntime,
 } from './ai-event-binder.js';
 export { ActivityFeedbackOrchestrator } from './orchestrator.js';
 export { ActivityFeedbackPolicy } from './policy.js';
@@ -38,4 +17,7 @@ export {
   type ActivityFeedbackServiceConfig,
 } from './config.js';
 export type { ActivityFeedbackEndpointAccess } from './executor.js';
-export default plugin;
+export {
+  createNoopEndpointAccess,
+  createOutboundEndpointAccess,
+} from './executor.js';

package/src/orchestrator.ts

@@ -1,6 +1,8 @@
 import {
   toActivityFeedbackEventContext,
   isActivityFeedbackEnabled,
+  applySubagentActivityPrefixToConfig,
+  withSubagentActivityPrefix,
   type AIEventPayload,
   type ActivityFeedbackPhase,
 } from '@zhin.js/agent';
@@ -10,6 +12,17 @@ import { ActivityFeedbackPolicy } from './policy.js';
 type Logger = { debug: (msg: string, ...args: unknown[]) => void; error: (msg: string, ...args: unknown[]) => void };
 
 export class ActivityFeedbackOrchestrator {
+  private readonly active = new Map<string, {
+    ctx: NonNullable<ReturnType<typeof toActivityFeedbackEventContext>>;
+    phase: ActivityFeedbackPhase;
+  }>();
+  private readonly transient = new Map<string, {
+    timer: ReturnType<typeof setTimeout>;
+    ctx: NonNullable<ReturnType<typeof toActivityFeedbackEventContext>>;
+    phase: ActivityFeedbackPhase;
+  }>();
+  private readonly pendingCleanup = new Set<Promise<void>>();
+
   constructor(
     private readonly policy: ActivityFeedbackPolicy,
     private readonly executor: ActivityFeedbackExecutor,
@@ -18,16 +31,36 @@ export class ActivityFeedbackOrchestrator {
 
   async startPhase(payload: AIEventPayload, phase: ActivityFeedbackPhase, reason: string): Promise<void> {
     const gatePhase = phase as import('@zhin.js/agent').ActivityFeedbackGatePhase;
-    if (!isActivityFeedbackEnabled(payload, gatePhase)) return;
+    if (!isActivityFeedbackEnabled(payload, gatePhase)) {
+      this.log.debug(
+        `[ActivityFeedback] skip ${phase} (${reason}): gate closed`
+        + ` (eligible=${String(payload.hookContext?.activityFeedbackEligible)})`,
+      );
+      return;
+    }
     const ctx = toActivityFeedbackEventContext(payload);
-    if (!ctx) return;
+    if (!ctx) {
+      this.log.debug(
+        `[ActivityFeedback] skip ${phase} (${reason}): unresolvable context`
+        + ` (platform=${String(payload.platform)} endpoint=${String(payload.endpointKey)})`,
+      );
+      return;
+    }
 
     try {
-      const resolution = this.policy.resolvePhase(ctx.platform, ctx.endpointId, phase, ctx.sceneType);
-      if (resolution.kind !== 'active') return;
+      const resolution = this.policy.resolvePhase(ctx.platform, ctx.endpointKey, phase, ctx.sceneType);
+      if (resolution.kind !== 'active') {
+        this.log.debug(
+          `[ActivityFeedback] skip ${phase} (${reason}): policy=${resolution.kind}`
+          + ` (${ctx.platform}:${ctx.endpointKey} ${ctx.sceneType})`,
+        );
+        return;
+      }
 
+      const config = applySubagentActivityPrefixToConfig(resolution.config, payload);
       this.log.debug(`[ActivityFeedback] start ${phase} (${reason}) session=${ctx.sessionId}`);
-      await this.executor.start(ctx, phase, resolution.config);
+      await this.executor.start(ctx, phase, config);
+      this.active.set(this.phaseKey(ctx, phase), { ctx, phase });
     } catch (error) {
       this.log.error(`[ActivityFeedback] start ${phase} failed (${reason}):`, error);
     }
@@ -36,6 +69,9 @@ export class ActivityFeedbackOrchestrator {
   async stopPhase(payload: AIEventPayload, phase: ActivityFeedbackPhase, reason: string): Promise<void> {
     const ctx = toActivityFeedbackEventContext(payload);
     if (!ctx) return;
+    const key = this.phaseKey(ctx, phase);
+    this.clearTransient(key);
+    this.active.delete(key);
 
     try {
       this.log.debug(`[ActivityFeedback] stop ${phase} (${reason}) session=${ctx.sessionId}`);
@@ -46,13 +82,76 @@ export class ActivityFeedbackOrchestrator {
   }
 
   async updateThinkingText(payload: AIEventPayload, text: string): Promise<void> {
+    await this.updatePhaseText(payload, 'thinking', text);
+  }
+
+  async updatePhaseText(
+    payload: AIEventPayload,
+    phase: ActivityFeedbackPhase,
+    text: string,
+  ): Promise<void> {
     const ctx = toActivityFeedbackEventContext(payload);
     if (!ctx || !text) return;
 
     try {
-      await this.executor.updateThinkingText(ctx, text);
+      await this.executor.updateText(ctx, phase, withSubagentActivityPrefix(text, payload));
     } catch (error) {
-      this.log.error('[ActivityFeedback] thinking update failed:', error);
+      this.log.error(`[ActivityFeedback] ${phase} update failed:`, error);
     }
   }
+
+  async showTransientPhase(
+    payload: AIEventPayload,
+    phase: ActivityFeedbackPhase,
+    reason: string,
+  ): Promise<void> {
+    await this.startPhase(payload, phase, reason);
+    const ctx = toActivityFeedbackEventContext(payload);
+    if (!ctx) return;
+    const resolution = this.policy.resolvePhase(ctx.platform, ctx.endpointKey, phase, ctx.sceneType);
+    if (resolution.kind !== 'active') return;
+    const delay = resolution.config.removeDelay ?? 3_000;
+    const key = this.phaseKey(ctx, phase);
+    this.clearTransient(key);
+    const timer = setTimeout(() => {
+      this.transient.delete(key);
+      this.active.delete(key);
+      const cleanup = this.executor.stop(ctx, phase)
+        .catch((error) => {
+          this.log.error(`[ActivityFeedback] transient ${phase} cleanup failed:`, error);
+        })
+        .finally(() => {
+          this.pendingCleanup.delete(cleanup);
+        });
+      this.pendingCleanup.add(cleanup);
+    }, Math.max(0, delay));
+    timer.unref?.();
+    this.transient.set(key, { timer, ctx, phase });
+  }
+
+  async dispose(): Promise<void> {
+    const pending = [...this.active.values()];
+    const timers = [...this.transient.values()];
+    this.active.clear();
+    this.transient.clear();
+    for (const item of timers) clearTimeout(item.timer);
+    await Promise.allSettled([
+      ...pending.map((item) => this.executor.stop(item.ctx, item.phase)),
+      ...this.pendingCleanup,
+    ]);
+  }
+
+  private phaseKey(
+    ctx: NonNullable<ReturnType<typeof toActivityFeedbackEventContext>>,
+    phase: ActivityFeedbackPhase,
+  ): string {
+    return JSON.stringify([ctx.platform, ctx.endpointKey, ctx.sessionId, phase, ctx.messageId]);
+  }
+
+  private clearTransient(key: string): void {
+    const current = this.transient.get(key);
+    if (!current) return;
+    clearTimeout(current.timer);
+    this.transient.delete(key);
+  }
 }

package/src/policy.ts

@@ -23,7 +23,7 @@ export class ActivityFeedbackPolicy {
 
   resolvePhase(
     platform: string,
-    endpointId: string,
+    endpointKey: string,
     phase: ActivityFeedbackPhase,
     sceneType: ActivitySceneType,
   ): PhaseResolution {
@@ -34,7 +34,8 @@ export class ActivityFeedbackPolicy {
     const policy = mergeActivityFeedbackLayers(
       this.service.defaults,
       this.service.platforms?.[platform],
-      this.service.endpoints?.[`${platform}:${endpointId}`],
+      this.service.endpoints?.[`${platform}:${endpointKey}`],
+      schedulePhaseLayer(this.service, phase),
     );
 
     if (policy?.enabled === false) {
@@ -49,3 +50,18 @@ export class ActivityFeedbackPolicy {
     return { kind: 'active', config };
   }
 }
+
+function schedulePhaseLayer(
+  service: ActivityFeedbackServiceConfig,
+  phase: ActivityFeedbackPhase,
+): import('@zhin.js/agent').ActivityFeedbackConfig | undefined {
+  const scheduleKey = phase === 'schedule_start'
+    ? 'start'
+    : phase === 'schedule_finish'
+      ? 'finish'
+      : phase === 'schedule_error'
+        ? 'error'
+        : undefined;
+  const scenes = scheduleKey ? service.schedule?.phases?.[scheduleKey] : undefined;
+  return scenes ? { phases: { [phase]: scenes } } : undefined;
+}

package/plugin.yml

@@ -1,2 +0,0 @@
-name: service-activity-feedback
-description: Activity Feedback 服务 — 订阅 AI 事件，按 endpoint 配置驱动 queued/active/thinking 三阶段反馈