# 快速跑通

## 1. 接入 SDK

在 `oh-package.json5` 中添加 SDK 依赖：

```json5
{
  "dependencies": {
    "virtualman-stream-sdk": "file:../sdk"
  }
}
```

同时确保 TRTC HarmonyOS SDK 已放入 `sdk/libs/` 目录下，并在 SDK 的 `oh-package.json5` 中配置：

```json5
{
  "dependencies": {
    "@tencentcloud/liteavsdk_trtc": "file:./libs/LiteAVSDK_TRTC_13.4.0.8928.har"
  }
}
```

> **注意**：使用的是专为数智人场景定制的 TRTC 版本，包含 Alpha 通道视频等数智人专属能力，请勿替换为通用版本。

## 2. 配置权限

SDK 需要网络权限和麦克风权限（语音驱动时），请在 `module.json5` 中配置：

```json5
"requestPermissions": [
  { "name": "ohos.permission.INTERNET" },
  {
    "name": "ohos.permission.MICROPHONE",
    "reason": "$string:permission_microphone_reason",
    "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
  }
]
```

## 3. 配置凭证

在 `Config.ets` 中填入您的数智人项目凭证：

```typescript
export class Config {
  static readonly APP_KEY: string = 'xxx'
  static readonly ACCESS_TOKEN: string = 'xxx'
  static readonly ASSET_VIRTUALMAN_KEY: string = 'xxx'       // Asset 建流时使用
  static readonly VIRTUALMAN_PROJECT_ID: string = 'xxx'      // Project 建流时使用
}
```

## 4. 初始化及使用

```typescript
import {
  VirtualmanView, Virtualman,
  VirtualmanParams, VirtualmanProjectParams, AssetVirtualmanParams, ExtraInfo
} from 'virtualman-stream-sdk'
import { Config } from '../Config'

@Entry
@Component
struct Index {
  private virtualman: Virtualman = new Virtualman()
  @State isReady: boolean = false

  aboutToAppear(): void {
    // 第一步：初始化（配置鉴权参数和建流参数，不建流）
    // 注意：ArkTS 严格模式要求使用 new，不可使用匿名对象字面量
    const params = new VirtualmanParams()
    params.appkey = Config.APP_KEY
    params.accesstoken = Config.ACCESS_TOKEN

    // 方式一：项目建流参数
    const projectParams = new VirtualmanProjectParams()
    projectParams.virtualmanProjectId = Config.VIRTUALMAN_PROJECT_ID
    const projectExtra = new ExtraInfo()
    projectExtra.alphaChannelEnable = true
    projectParams.extraInfo = projectExtra
    params.virtualmanProjectParams = projectParams

    // 方式二：资产建流参数
    const assetParams = new AssetVirtualmanParams()
    assetParams.assetVirtualmanKey = Config.ASSET_VIRTUALMAN_KEY
    const assetExtra = new ExtraInfo()
    assetExtra.alphaChannelEnable = true
    assetParams.extraInfo = assetExtra
    params.assetVirtualmanParams = assetParams

    this.virtualman.init(params)

    // 第二步：设置事件回调（挂在 controller 上，而非 VirtualmanView）
    this.virtualman.onError = (error: string): void => {
      console.error(`错误: ${error}`)
    }
    this.virtualman.onMessage = (text: string): void => {
      console.info(`收到WS消息: ${text}`)
    }
    this.virtualman.onWsOpen = (): void => {
      console.info('WebSocket 已连接，可以发送消息')
    }
    this.virtualman.onWsClose = (code: number, reason: string): void => {
      console.info(`WebSocket 已断开: code=${code}`)
    }
  }

  build() {
    Stack() {
      // 第三步：挂载渲染视图（始终挂载，内部管理生命周期）
      VirtualmanView({
        controller: this.virtualman
      })
        .width('100%')
        .height('100%')

      Column() {
        // 方式一：通过 ProjectId 建流
        Button('项目建流')
          .onClick(async (): Promise<void> => {
            const result = await this.virtualman.open()
            if (result.success) {
              this.isReady = true
              console.info(`建流成功, sessionId: ${result.sessionId ?? ''}`)
            } else {
              console.error(`建流失败: ${result.error ?? ''}`)
            }
          })

        // 方式二：通过 AssetVirtualmanKey 建流
        Button('资产建流')
          .onClick(async (): Promise<void> => {
            const result = await this.virtualman.openByAsset()
            if (result.success) {
              this.isReady = true
              console.info(`建流成功, sessionId: ${result.sessionId ?? ''}`)
            } else {
              console.error(`建流失败: ${result.error ?? ''}`)
            }
          })

        // 建流成功后：发送指令
        if (this.isReady) {
          Button('发送对话')
            .onClick((): void => {
              this.virtualman.chat({ text: '你好', isNewChat: true })
            })

          Button('关流')
            .onClick((): void => {
              this.virtualman.close()
              this.isReady = false
            })
        }
      }
    }
  }
}
```

## 5. 运行 Demo

### 5.1 打开工程

使用 DevEco Studio 打开 `harmony` 目录。

### 5.2 配置签名

1. File → Project Structure → Signing Configs
2. 勾选 **Automatically generate signature**
3. 选择你的开发者证书

### 5.3 选择设备并运行

- 在 DevEco Studio 顶部工具栏选择目标设备
- 点击 ▶️ 运行按钮

### 5.4 常见问题

| 问题 | 解决方法 |
|------|----------|
| 运行后黑屏无画面 | 确认 Config.ets 中的凭证填写正确，且网络可用 |
| 编译报找不到 SDK | 确认 oh-package.json5 中 dependencies 路径配置正确 |
| 透明通道不生效 | 确认 open 时传入了 `extraInfo.alphaChannelEnable = true` |
| 建流失败后无法重试 | 建流失败后 open() 返回 `success: false`，按钮仍可点击重新 open |
