@guoquan.net/flow-engine 0.1.10 → 0.2.0

package/README.md

@@ -63,6 +63,24 @@ npm install github:guoquan/flow-engine#7834b6c
 - **Data-Driven**: Animation and behavior fully controlled via JSON configuration.
 - **Zero-Dependency Core**: Pure frontend architecture, easy to integrate into any project.
 
+### 🏗️ Architecture
+Flow Engine adopts a **Controller-Agent** pattern:
+*   **FlowEngine**: The core scene manager and renderer (WebGPU).
+*   **BehaviorController (Brain)**: A finite state machine managing high-level states (`IDLE`, `TALKING`, `THINKING`).
+*   **LookAtProcessor (Reflex)**: Procedural animation system for eye contact and head tracking.
+*   **MCP Server (Bridge)**: A Node.js server enabling external AI agents to drive the avatar.
+
+### 🤖 AI Agent Integration (MCP)
+Flow Engine includes a built-in **Model Context Protocol (MCP)** server. This allows AI models (like Claude or Gemini) to "see" and "control" the avatar as a tool.
+
+```bash
+# Start the MCP Server
+npm run mcp
+```
+
+*   👉 **[Read the MCP Integration Guide](./docs/MCP_GUIDE.md)**
+*   👉 **[API Reference](./docs/API_REFERENCE.md)**
+
 ### 📚 Documentation
 Please visit **[docs/](./docs/)** for the full documentation and API references.
 
@@ -120,5 +138,23 @@ npm install github:guoquan/flow-engine#7834b6c
 - **数据驱动**：动画与行为完全通过 JSON 配置文件控制。
 - **零依赖核心**：纯前端架构，无需后端即可运行，易于集成。
 
+### 🏗️ 架构设计
+Flow Engine 采用 **Controller-Agent** 模式：
+*   **FlowEngine**: 核心场景管理器与渲染器 (WebGPU)。
+*   **BehaviorController (大脑)**: 有限状态机，管理高级行为状态 (`IDLE`, `TALKING`, `THINKING`)。
+*   **LookAtProcessor (反射)**: 程序化动画系统，负责眼神接触与头部追踪。
+*   **MCP Server (桥梁)**: 一个 Node.js 服务，允许外部 AI Agent 驱动数字人。
+
+### 🤖 AI Agent 集成 (MCP)
+Flow Engine 内置了 **Model Context Protocol (MCP)** 服务器。这使得 AI 模型（如 Claude 或 Gemini）能够将数字人视为一个“工具”并进行控制。
+
+```bash
+# 启动 MCP 服务器
+npm run mcp
+```
+
+*   👉 **[阅读 MCP 集成指南](./docs/MCP_GUIDE.md)**
+*   👉 **[API 参考文档](./docs/API_REFERENCE.md)**
+
 ### 📚 文档索引
 请访问 **[docs/](./docs/)** 查看完整文档与 API 说明。

package/dist/core/BehaviorController.d.ts

@@ -0,0 +1,45 @@
+import { AvatarBehaviorState, BehaviorIntent } from '../types';
+/**
+ * BehaviorController (The Global Brain)
+ * Manages the high-level behavioral state machine of the avatar.
+ */
+export declare class BehaviorController {
+    private currentState;
+    private stateStartTime;
+    private stateTimeout;
+    private isTransitioning;
+    private debug;
+    /**
+     * Optional callback triggered when the behavioral state changes.
+     */
+    onStateChange?: (newState: AvatarBehaviorState, intent: BehaviorIntent) => void;
+    /**
+     * @param options.debug Enable verbose logging for transitions
+     */
+    constructor(options?: {
+        debug?: boolean;
+    });
+    /**
+     * Toggles debug logging mode without re-initializing the controller.
+     */
+    setDebugMode(enabled: boolean): void;
+    /**
+     * @returns Whether debug mode is currently enabled.
+     */
+    isDebugEnabled(): boolean;
+    /**
+     * Drives the brain logic.
+     * @param timeMs Consistent external timestamp (usually from requestAnimationFrame).
+     */
+    update(timeMs: number): void;
+    /**
+     * Core API: Submit a behavioral intent to the brain.
+     * @param intent The desired behavior change
+     * @param timeMs Optional current time (defaults to performance.now())
+     */
+    setIntent(intent: BehaviorIntent, timeMs?: number): void;
+    /**
+     * @returns The current high-level behavior state.
+     */
+    getState(): AvatarBehaviorState;
+}

package/dist/core/BubbleManager.d.ts

@@ -0,0 +1,19 @@
+import * as THREE from 'three';
+export declare class BubbleManager {
+    private scene;
+    private sprite;
+    private target;
+    private offset;
+    private visible;
+    private canvas;
+    private ctx;
+    private texture;
+    constructor(scene: THREE.Scene);
+    setTarget(target: THREE.Object3D): void;
+    show(text: string, type?: 'speech' | 'thought'): void;
+    hide(): void;
+    update(): void;
+    private drawBubble;
+    private drawRoundedRect;
+    private drawCloud;
+}

package/dist/core/FlowEngine.d.ts

@@ -1,3 +1,5 @@
+import { BehaviorIntent, AgentResponse } from '../types';
+import { SayParams, ThinkParams } from '../schemas/actions';
 export declare class FlowEngine {
     private container;
     private scene;
@@ -13,11 +15,15 @@ export declare class FlowEngine {
     private animController;
     private stageAnimController;
     private lookAtProcessor;
+    private brain;
+    private bubbleManager;
     private currentAvatarConfig;
     isDebug: boolean;
     private debugTargetMesh;
     private debugPlaneMesh;
+    private resizeObserver;
     constructor(containerId: string);
+    dispose(): void;
     private setupLights;
     /**
      * Load an avatar by config URL
@@ -33,6 +39,39 @@ export declare class FlowEngine {
     private removeDebugHelpers;
     private onWindowResize;
     isAutoRotate: boolean;
+    /**
+     * HIGH-LEVEL BEHAVIOR API
+     */
+    /**
+     * Submit a 'TALKING' intent to the brain.
+     * @param params Conversation parameters (text, duration)
+     */
+    say(params: SayParams | string): void;
+    /**
+     * Submit a 'THINKING' intent to the brain.
+     * @param params Thought parameters (text, duration)
+     */
+    think(params?: ThinkParams | string): void;
+    /**
+     * Submit a complex behavior intent.
+     * @param intent The behavior intent object
+     */
+    setBehavior(intent: BehaviorIntent): void;
+    /**
+     * Processes a structured response from an AI Agent.
+     * This is the primary bridge for Agent-to-Avatar interaction.
+     * @param response The structured message according to the Unified Action Protocol
+     */
+    processAgentResponse(response: AgentResponse): void;
+    /**
+     * Internal executor for discrete action commands.
+     * Note: Actions scheduled with delay may conflict if state changes rapidly.
+     */
+    private executeCommand;
+    /**
+     * Play a manual low-level action. Interrupts high-level brain state.
+     * @param action State name defined in config.animations.states
+     */
     playAction(action: string): void;
     private animate;
 }

package/dist/core/LookAtProcessor.d.ts

@@ -28,6 +28,14 @@ export declare class LookAtProcessor implements InteractionProcessor {
     update(timeMs: number, delta: number): void;
     private calculateLookAtRotation;
     private updateState;
+    /**
+     * Set a manual world-space target for the avatar to look at.
+     */
+    setTarget(position: THREE.Vector3): void;
+    /**
+     * Return the LookAt system to IDLE state.
+     */
+    reset(): void;
     private onPointerDown;
     private onPointerMove;
     private onPointerUp;