@guoquan.net/flow-engine 0.1.9 → 0.2.0

package/README.md

@@ -4,6 +4,8 @@
 [![CI](https://github.com/guoquan/flow-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/guoquan/flow-engine/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/guoquan/flow-engine/graph/badge.svg?token=2T5SGUBMK4)](https://codecov.io/gh/guoquan/flow-engine)
 [![Deploy to GitHub Pages](https://github.com/guoquan/flow-engine/actions/workflows/deploy.yml/badge.svg)](https://github.com/guoquan/flow-engine/actions/workflows/deploy.yml)
+[![npm version](https://img.shields.io/npm/v/@guoquan.net/flow-engine.svg?style=flat-square)](https://www.npmjs.com/package/@guoquan.net/flow-engine)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 [English](#english) | [中文](#中文)
 
@@ -13,36 +15,72 @@
 
 > **"Flow: Convincing at first breath."**
 
-**Flow** (distributed as `@guoquan.net/flow-engine`) is a high-performance, lightweight web-based digital human engine. It empowers web applications with lifelike AI avatars through simple API-driven interactions.
+**Flow** is a high-performance, lightweight web-based digital human engine based on WebGPU.
 
-### 🌟 Highlights
-- **Modern Rendering**: Based on WebGPU for next-gen performance and visual quality.
-- **Data-Driven**: Animation and behavior fully controlled via JSON configuration.
-- **Zero-Dependency Core**: Pure frontend architecture, easy to integrate into any project.
+### 📦 Installation
 
-### 🛠 Tech Stack
-- **Core**: TypeScript
-- **Rendering**: Three.js (WebGPU Renderer)
-- **Build**: Vite
+This package is distributed under two different scopes depending on the registry:
 
-### 📦 Installation
+#### Stable Versions (Recommended)
 
-You can install the SDK directly from GitHub:
+**From NPM Registry:**
+```bash
+npm install @guoquan.net/flow-engine
+```
 
+**From GitHub Packages Registry:**
+Add a `.npmrc` file to your project:
+```ini
+@guoquan:registry=https://npm.pkg.github.com
+```
+Then install:
 ```bash
-# Using npm
+npm install @guoquan/flow-engine
+```
+
+> **Note**: The naming difference (`@guoquan.net` on NPM vs `@guoquan` on GitHub) is due to account scope requirements on each platform.
+
+#### Development / Latest Version
+
+Install directly from the GitHub repository. You can specify a branch, tag, or commit hash using the `#` prefix:
+
+```bash
+# Latest from main branch
 npm install github:guoquan/flow-engine
 
-# Using pnpm
-pnpm add github:guoquan/flow-engine
+# Specific branch
+npm install github:guoquan/flow-engine#develop
+
+# Specific tag
+npm install github:guoquan/flow-engine#v0.1.9
+
+# Specific commit hash
+npm install github:guoquan/flow-engine#7834b6c
 ```
 
-To use a specific version (recommended):
+### 🌟 Highlights
+- **Modern Rendering**: Based on WebGPU for next-gen performance and visual quality.
+- **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
-npm install github:guoquan/flow-engine#v0.1.0
+# 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.
 
@@ -52,35 +90,71 @@ Please visit **[docs/](./docs/)** for the full documentation and API references.
 
 > **"一开口，就服喽。"**
 
-**Flow** (包名称：`@guoquan.net/flow-engine`) 是一个高性能、轻量级的 Web 端数字人引擎。它旨在通过简单的 API 驱动，为 Web 应用赋予栩栩如生的 AI 化身交互能力。
+**Flow** 是一个高性能、轻量级的基于 WebGPU 的 Web 端数字人引擎。
 
-### 🌟 项目亮点
-- **现代化渲染**：基于 WebGPU，提供下一代渲染性能与视觉效果。
-- **数据驱动**：动画与行为完全通过 JSON 配置文件控制。
-- **零依赖核心**：纯前端架构，无需后端即可运行，易于集成。
+### 📦 安装指南
 
-### 🛠 技术栈
-- **核心**: TypeScript
-- **渲染**: Three.js (WebGPU Renderer)
-- **构建**: Vite
+由于注册表平台限制，本项目在不同平台使用不同的包名作用域：
 
-### 📦 安装
+#### 稳定版本 (推荐)
 
-你可以直接从 GitHub 安装该 SDK：
+**从 NPM 安装:**
+```bash
+npm install @guoquan.net/flow-engine
+```
 
+**从 GitHub Packages 安装:**
+在项目根目录创建 `.npmrc` 文件:
+```ini
+@guoquan:registry=https://npm.pkg.github.com
+```
+然后安装:
 ```bash
-# 使用 npm
+npm install @guoquan/flow-engine
+```
+
+> **注意**: 命名差异（NPM 上为 `@guoquan.net`，GitHub 上为 `@guoquan`）是因为各平台对用户作用域（Scope）的要求不同。
+
+#### 开发版 / 最新版本
+
+直接从 GitHub 仓库安装。你可以使用 `#` 前缀指定分支、标签或提交哈希：
+
+```bash
+# 安装 main 分支最新代码
 npm install github:guoquan/flow-engine
 
-# 使用 pnpm
-pnpm add github:guoquan/flow-engine
+# 指定分支
+npm install github:guoquan/flow-engine#develop
+
+# 指定标签
+npm install github:guoquan/flow-engine#v0.1.9
+
+# 指定提交哈希
+npm install github:guoquan/flow-engine#7834b6c
 ```
 
-建议安装特定版本以保证稳定性：
+### 🌟 项目亮点
+- **现代化渲染**：基于 WebGPU，提供下一代渲染性能与视觉效果。
+- **数据驱动**：动画与行为完全通过 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
-npm install github:guoquan/flow-engine#v0.1.0
+# 启动 MCP 服务器
+npm run mcp
 ```
 
+*   👉 **[阅读 MCP 集成指南](./docs/MCP_GUIDE.md)**
+*   👉 **[API 参考文档](./docs/API_REFERENCE.md)**
+
 ### 📚 文档索引
-请访问 **[docs/](./docs/)** 查看完整文档与 API 说明。
+请访问 **[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;