3.1 AIUI Code --智能编码插件

<div style="max-width: 100%; margin: 20px auto;">
    
    <div style="background-color: #ffffff; border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); overflow: hidden; font-family: 'Comic Sans MS', cursive, sans-serif;">
        
        
        <div style="background-color: #F4F8FA; padding: 1px 10px; border-bottom: 1px solid #dee2e6; display: flex; justify-content: space-between; align-items: center;">
            <div style="color: #0E42D2; font-weight: bold;font-size: 1.3rem;">AIUI Code--智能编码插件</div>
            <div>
            </div>
        </div>
        
        <div style="padding: 25px; line-height: 29px; background-image: linear-gradient(transparent 26px, #dee2e6 27px, #dee2e6 27px, transparent 27px); background-size: 100% 28px; min-height: 100px; color: #333;">
            <div>AIUI Code 是一个多平台 AI 编码助手插件，专为讯飞 AIUI 语音交互产品开发设计，同时具备通用开发能力。</div>
            <a href="#AIUI Code简介" style="color: #6f42c1; font-weight: 500;">
            <strong>- 1、AIUI Code简介>>>点击跳转&emsp;&emsp;</strong></a>
            <a href="#核心架构" style="color: #6f42c1; font-weight: 500;">
            <strong>- 2、核心架构>>>点击跳转&emsp;&emsp;</strong></a>
			<a href="#安装指南" style="color: #6f42c1; font-weight: 500;">
            <strong>- 3、安装指南>>>点击跳转&emsp;&emsp;</strong></a>
			<br>
			<a href="#快速开始" style="color: #6f42c1; font-weight: 500;">
            <strong>- 4、快速开始>>>点击跳转&emsp;&emsp;</strong></a>
            <a href="#核心工作流详解" style="color: #6f42c1; font-weight: 500;">
            <strong>- 5、核心工作流详解>>>点击跳转&emsp;&emsp;</strong></a>
			<a href="#AIUI SDK 集成完整链路" style="color: #6f42c1; font-weight: 500;">
            <strong>- 6、AIUI SDK 集成完整链路>>>点击跳转&emsp;&emsp;</strong></a>
			<br>
			<a href="#技能体系详解" style="color: #6f42c1; font-weight: 500;">
            <strong>- 7、技能体系详解>>>点击跳转&emsp;&emsp;</strong></a>
            <a href="#子代理系统" style="color: #6f42c1; font-weight: 500;">
            <strong>- 8、子代理系统>>>点击跳转&emsp;&emsp;</strong></a>
			<a href="#配置与定制" style="color: #6f42c1; font-weight: 500;">
            <strong>- 9、配置与定制>>>点击跳转&emsp;&emsp;</strong></a>
			<br>
			<a href="#常见场景示例" style="color: #6f42c1; font-weight: 500;">
            <strong>- 10、常见场景示例>>>点击跳转&emsp;&emsp;</strong></a>
            <a href="#故障排查" style="color: #6f42c1; font-weight: 500;">
            <strong>- 11、故障排查>>>点击跳转&emsp;&emsp;</strong></a>
			<a href="#最佳实践" style="color: #6f42c1; font-weight: 500;">
            <strong>- 12、最佳实践>>>点击跳转&emsp;&emsp;</strong></a>
			<br>
            <div></div>
        </div>
        
        </div>
    </div>
</div>

## 1. AIUI Code简介

**AIUI Code** 是一个多平台 AI 编码助手插件，专为讯飞 AIUI 语音交互产品开发设计，同时具备通用开发能力。

### 核心特性

- **多平台支持**：兼容 Claude Code、Codex、OpenCode 三个 AI 编码平台
- **AIUI 专属工作流**：覆盖从首次接入到生产排障的全流程
- **三阶段开发模式**：需求澄清 → 计划生成 → 执行实现，文档与代码分离
- **对抗审查机制**：每个产物都有独立子代理进行质量评审
- **智能环境检测**：自动识别项目类型、工具链、平台需求
- **领域适配器**：针对 AIUI/语音领域的专用代码生成和审查

### 适用场景

1. **AIUI SDK 首次集成**：从零搭建 AIUI 语音交互应用
2. **功能开发**：添加唤醒、识别、播报、动态实体等功能
3. **问题排查**：分析日志、定位配置错误、解决集成问题
4. **跨平台移植**：Android、Linux、Windows、RTOS 平台适配
5. **通用开发**：支持任何编程语言和框架的常规开发任务

---

## 2. 核心架构

### 工作流三阶段

```
用户需求
    ↓
[1] aiui-brainstorming (需求澄清)
    → 输出：docs/specs/YYYY-MM-DD-<name>-design.md (设计文档)
    → 评审：spec-reviewer (独立子代理)
    ↓
[2] aiui-planning (计划生成)
    → 输出：docs/plans/YYYY-MM-DD-<name>.md (实现计划)
    → 评审：plan-reviewer (独立子代理)
    ↓
[3] aiui-executing (执行实现)
    → 输出：代码变更
    → 评审：code-reviewer / aiui-code-reviewer (独立子代理)
    ↓
[4] finishing-development (可选，git 收尾)
    → 输出：合并/PR/保留/丢弃
```

### 目录结构

```
aiuicode/
├── .claude-plugin/          # Claude Code 平台适配层
├── .codex-plugin/           # Codex 平台适配层
├── .opencode/               # OpenCode 平台适配层（TypeScript 插件）
├── agents/                  # 子代理定义（8个）
│   ├── plan-writer.md           # 计划生成
│   ├── plan-reviewer.md         # 计划审查
│   ├── spec-reviewer.md         # 设计文档审查
│   ├── code-writer.md           # 通用代码实现
│   ├── code-reviewer.md         # 通用代码审查
│   ├── aiui-code-writer.md      # AIUI/语音领域代码实现
│   ├── aiui-code-reviewer.md    # AIUI/语音领域代码审查
│   └── aiui-e2e-runner.md       # 运行级验证
├── skills/                  # 工作流技能库（30+ 技能）
│   ├── aiui-brainstorming/      # 需求澄清
│   ├── aiui-planning/           # 计划生成
│   ├── aiui-executing/          # 执行实现
│   ├── aiui-workflow-entry/     # AIUI 问题快速路由
│   ├── aiui-preflight/          # 环境门禁（6步检查）
│   ├── aiui-config-authoring/   # 配置编写
│   ├── aiui-artifact-download/  # SDK/资源下载
│   ├── aiui-troubleshoot/       # 故障排查
│   └── ... (更多技能见下文)
├── rules/                   # 始终遵循的规则
│   ├── common/                  # 通用规则
│   └── aiui-domain/             # AIUI 领域规则
├── config/                  # 程序化配置
└── package.json
```

---

## 3. 安装指南

### 前置要求

- **操作系统**：Windows 10+、Linux、macOS
- **AI 编码平台**：Claude Code / Codex / OpenCode 任一
- **Node.js**：18+ (仅 OpenCode 需要)
- **Git**：用于版本控制和工作流管理

---

### ⭐ 一键安装（推荐）

**适用平台**：Claude Code

**使用方法**：复制下面的文本，粘贴到 Claude Code 对话框，AI 会自动帮你完成安装

```
帮我安装并启用 AIUI Code 插件：
插件市场：https://gitee.com/iflytek-aibot/aiuicode.git
插件名称：aiui-code@aiuicode
```

**安装流程**：
1. 📋 复制上面的文本框内容
2. 💬 粘贴到 Claude Code 对话框
3. ⏎ 按回车发送
4. ✅ 等待 AI 自动完成安装

**验证成功**：安装完成后，AI 会回复确认信息，之后你就可以使用所有 AIUI Code 技能了。

---

### Claude Code 手动安装

**适用场景**：需要更多控制或自动安装失败时使用

1. **添加插件市场**
   ```bash
   /plugin marketplace add https://gitee.com/iflytek-aibot/aiuicode.git
   ```

2. **安装插件**
   ```bash
   /plugin install aiui-code@aiuicode
   ```

3. **验证安装**
   ```bash
   /plugin list
   # 应看到 aiui-code 出现在列表中
   ```

4. **启动使用**
   
   安装完成后，在任意项目中直接使用 AIUI Code 的技能和工作流。

---

### Codex 安装

1. **安装插件**
   ```bash
   codex plugin add ./aiuicode
   ```

2. **验证安装**
   ```bash
   codex plugin list
   ```

3. **启动 Codex**
   ```bash
   cd <your-project>
   codex
   ```

---

### OpenCode 安装

1. **安装依赖**
   ```bash
   cd aiuicode/.opencode
   npm install
   ```

2. **配置项目**（可选，用于多模型策略）
   
   在项目根目录创建 `.opencoderc.json`：
   
   ```json
   {
     "$schema": "https://opencode.ai/config.json",
     "model": "Iflytek-Mass/xopglm51",
     "plugin": [
       "/path/to/aiuicode/.opencode/plugins"
     ],
     "aiuicode": {
       "agents": {
         "plan-writer": { "model": "AstronCodingPlan/xopkimik25" },
         "code-writer": { "model": "AstronCodingPlan/xopkimik25" },
         "aiui-code-writer": { "model": "AstronCodingPlan/xopkimik25" },
         "aiui-e2e-runner": { "model": "AstronCodingPlan/xminimaxm25" },
         "plan-reviewer": { "model": "Iflytek-Mass/xopglm51" },
         "code-reviewer": { "model": "Iflytek-Mass/xopglm51" },
         "aiui-code-reviewer": { "model": "Iflytek-Mass/xopglm51" }
       }
     }
   }
   ```

**模型解析优先级**：
   1. `aiuicode.agents.<agent-name>.model` (最高优先级)
   2. `aiuicode.agents["*"].model`
   3. `aiuicode.models.opus` / `aiuicode.models.sonnet`
   4. `aiuicode.models.default`
   5. 环境变量 `AIUI_MODEL_OPUS` / `AIUI_MODEL_SONNET`
   6. 继承顶层 `model` (最低优先级)

3. **启动 OpenCode**
   ```bash
   cd <your-project>
   opencode
   ```

### 验证安装成功

启动后输入任一命令测试：

```
你好，帮我创建一个简单的 AIUI 语音交互程序
```

或直接调用 AIUI 技能：

```
/aiui-workflow-entry
```

如果插件加载成功，将看到技能响应。

---

## 4. 快速开始

### 场景 1：通用开发任务

**示例：创建一个 Web API**

```
需求：实现一个用户注册 API，包括参数验证、密码加密、数据库存储
```

**执行流程**：

1. **启动需求澄清**
   
   AI 自动进入 `aiui-brainstorming`：
   - Phase 1：扫描工程（识别技术栈、现有代码）
   - Phase 3：意图分类（识别为"通用开发任务"）
   - Phase 4：访谈（询问数据库类型、认证方式等）
   - Phase 6：生成设计文档 `docs/specs/2026-06-26-user-registration-design.md`
   - Phase 7：`spec-reviewer` 子代理评审设计文档

2. **生成实现计划**
   
   设计文档通过评审后，自动进入 `aiui-planning`：
   - 调用 `plan-writer` 子代理生成详细步骤
   - 输出计划文档 `docs/plans/2026-06-26-user-registration.md`
   - 调用 `plan-reviewer` 子代理评审计划

3. **执行实现**
   
   计划通过评审后，进入 `aiui-executing`：
   - 调用 `code-writer` 子代理按步骤实现
   - 每步完成后调用 `code-reviewer` 子代理审查
   - 自动运行测试验证

4. **Git 收尾**（可选）
   
   ```
   /finishing-development
   ```
   选择：合并到主分支 / 创建 PR / 保留分支 / 丢弃变更

### 场景 2：AIUI SDK 首次集成

**示例：在 Linux 设备上集成语音唤醒和识别**

```
需求：在 Ubuntu 20.04 上实现语音唤醒和语音识别功能
```

**执行流程**：

1. **启动需求澄清**
   
   ```
   我想在 Ubuntu 上集成 AIUI 语音功能
   ```
   
   AI 自动进入 `aiui-brainstorming`：
   - Phase 1：扫描工程（检测是否已有 SDK、配置文件等）
   - Phase 2：**环境门禁**（HARD-GATE，必须通过才能继续）
     
     调用 `aiui-preflight` 执行 6 步检查：
     
     ```
     ✓ Step 1: 平台+设备确认 (aiui-audio-environment)
       → 识别：Linux x64, 单麦克风
     
     ✓ Step 2: 工具链可用 (aiui-toolchain-linux)
       → 检查：gcc, CMake, ALSA
     
     ✓ Step 3: SDK 下载 + Demo 研究 (aiui-artifact-download)
       → 下载：libaiui_linux_x64.so
       → 读取 Demo：理解 API 调用方式
     
     ✓ Step 4: 凭据就绪 (aiui-credentials)
       → 获取：appid, key, api_secret, scene
     
     ✓ Step 5: 配置参数确认 (aiui-config-authoring)
       → 生成：aiui.cfg (包含唤醒+识别配置)
     
     ✓ Step 6: SDK 可编译链接 (aiui-sdk-setup)
       → 验证：最小示例编译通过
     ```
   
   - Phase 3：意图分类（识别为"AIUI 集成任务"）
   - Phase 4：访谈（询问唤醒词、识别场景等）
   - Phase 6：生成设计文档
   - Phase 7：评审

2. **生成实现计划**
   
   调用 `aiui-planning` 生成详细步骤

3. **执行实现**
   
   调用 `aiui-executing`：
   - 使用 `aiui-code-writer` 子代理（领域适配器）
   - 使用 `aiui-code-reviewer` 子代理审查
   - 关键点：
     - 正确处理 EVENT_RESULT 两步解析
     - 正确配置音频参数（16kHz PCM）
     - 正确处理唤醒/识别事件回调

### 场景 3：AIUI 问题排查

**示例：识别无结果**

```
AIUI 语音识别没有返回结果，请帮我排查
```

**执行流程**：

1. **快速路由**
   
   AI 自动调用 `aiui-workflow-entry`：
   - 识别为"C 类功能问题"（故障排查）
   - 路由到 `aiui-troubleshoot`

2. **故障排查决策树**
   
   `aiui-troubleshoot` 执行：
   - 收集信息：日志文件、配置文件、代码片段
   - 模式识别：EVENT_RESULT 解析错误 / 配置参数错误 / 网络问题
   - 调用 `aiui-log-analysis` 分析日志
   - 给出修复建议

3. **修复建议示例**
   
   ```
   诊断结果：
   
   问题：EVENT_RESULT 解析错误
   
   原因：代码直接从 info 取结果内容，未调用 getBinary()
   
   修复：
   1. 从 info 解析 data[0].params.sub 和 cnt_id
   2. 使用 getBinary(cnt_id) 获取实际内容
   3. 根据 sub 类型（iat/nlp/tts）解析对应格式
   
   参考文档：docs/aiui/vendor/aiui-sdk-doc/business/3.2.6 回调解析说明.md
   ```

---

## 5. 核心工作流详解

### 阶段 1：aiui-brainstorming（需求澄清）

**职责**：将模糊需求转化为明确的设计文档

**触发条件**：
- 用户提出新任务、功能请求、模糊需求
- 跳过条件：需求已经非常明确且用户说"直接做"或"跳过设计"

**8 个 Phase**：

```
Phase 1: 工程扫描
    ↓
Phase 2: 环境门禁（AIUI 任务必走 HARD-GATE）
    ↓
Phase 3: 意图分类
    ↓
Phase 4: 访谈
    ↓
Phase 5: 方案选项呈现
    ↓
Phase 6: 写设计文档
    ↓
Phase 7: spec-reviewer 评审
    ↓
Phase 8: 交接 aiui-planning
```

#### Phase 1: 工程扫描

**扫描清单**：
1. 项目结构基线
   - 根目录布局
   - 技术栈关键文件（package.json / CMakeLists.txt / pom.xml 等）
   - Git 信息

2. 既有产物
   - `docs/specs/` 已有设计文档
   - `docs/plans/` 已有计划文档
   - `src/` / `tests/` 已有代码

3. AIUI 制品存在性（仅记录，不判定）
   - SDK 库（libaiui.so / aiui.dll）
   - SDK 头文件（AIUI_V2.h）
   - 唤醒资源（vtn.ini / evad_*.jet）
   - 配置文件（aiui.cfg）

**输出**：工程现状摘要（5-10 行结构化信息）

**禁止行为**：
- ❌ 推断目标硬件 OS / 架构
- ❌ 调用工具链探测命令
- ❌ 建议技术路线或方案选项

#### Phase 2: 环境门禁（HARD-GATE）

**触发条件**：
- 工程扫描识别为 AIUI 集成任务
- 环境有缺口（SDK 缺失、凭据缺失等）
- 用户首次接入 AIUI

**6 步检查**（调用 `aiui-preflight`）：

| # | 检查项 | 调用技能 | 依赖 |
|---|--------|---------|------|
| 1 | 平台+设备确认 | aiui-audio-environment | 无 |
| 2 | 工具链可用 | aiui-toolchain-{linux,windows,android} | #1 |
| 3 | SDK 下载 + Demo 研究 | aiui-artifact-download | #1 |
| 4 | 凭据就绪 | aiui-credentials | 无 |
| 5 | 配置参数确认 | aiui-config-authoring | #1, #4 |
| 6 | SDK 可编译链接 | aiui-sdk-setup | #2, #3 |

**HARD-GATE 规则**：全部 PASS 才能进入 Phase 3

#### Phase 3: 意图分类

**分类维度**：
- 任务类型：A(首次接入) / B(功能开发) / C(故障排查) / D(文档查询)
- 领域：通用开发 / AIUI/语音领域

**输出**：明确的任务分类 + 领域标签

#### Phase 4: 访谈

**原则**：
- 只问必须问的
- 使用结构化选择 UI（降低用户成本）
- 避免开放式问题

**示例问题**：
- 目标平台？(Android / Linux / Windows / RTOS)
- 需要哪些功能？(唤醒 / 识别 / 播报 / 动态实体)
- 音频输入方式？(麦克风 / 文件 / 网络流)

#### Phase 5: 方案选项呈现

从候选库挑选 2-3 个方案，呈现：
- 方案描述
- 优缺点（tradeoffs）
- 推荐建议

#### Phase 6: 写设计文档

**输出位置**：`docs/specs/YYYY-MM-DD-<name>-design.md`

**内容结构**：
- 需求背景
- 目标与非目标
- 技术方案
- 架构设计
- 关键决策
- 关键决策
- 风险与缓解

#### Phase 7: spec-reviewer 评审

**评审维度**：
- Completeness（完整性）
- Consistency（一致性）
- Clarity（清晰度）
- Scope（范围合理性）
- YAGNI（不过度设计）

**输出**：
- PASS → 进入 Phase 8
- FAIL → 返回 Phase 6 修改

#### Phase 8: 交接 aiui-planning

自动调用下一阶段技能

---

### 阶段 2：aiui-planning（计划生成）

**职责**：将设计文档转化为可执行的实现计划

**输入**：设计文档路径

**流程**：
1. 读取设计文档
2. 调用 `plan-writer` 子代理生成计划
3. 输出计划文档 `docs/plans/YYYY-MM-DD-<name>.md`
4. 调用 `plan-reviewer` 子代理评审
5. 评审通过 → 交接 `aiui-executing`

**计划文档结构**：

```markdown
## 目标
简述要实现什么

## 前置条件
需要的环境、工具、依赖

## 实现步骤

### Step 1: <任务描述>
**文件**: src/example.cpp  
**操作**: 创建 / 修改 / 删除  
**内容**: [具体代码]  
**验证**: 如何确认完成

### Step 2: 实现事件处理
**文件**: src/event_handler.cpp  
**操作**: 创建  
**内容**: [事件回调处理逻辑]  
**验证**: 事件处理函数编译通过

### Step 3: 编写主程序
**文件**: src/main.cpp  
**操作**: 创建  
**内容**: [初始化 Agent、启动事件循环]  
**验证**: 程序可编译运行

### Step 4: 配置构建脚本
**文件**: CMakeLists.txt  
**操作**: 修改  
**内容**: [链接 SDK、添加源文件]  
**验证**: cmake 配置成功

### Step 5: 测试验证
**文件**: 无  
**操作**: 执行测试  
**内容**: [运行程序，验证功能]  
**验证**: 功能正常，无崩溃
```

**示例**：

```cpp
// Step 2 的代码示例 - 事件处理
void handleEvent(const IAIUIEvent& event) {
    switch (event.getEventType()) {
        case EVENT_RESULT:
            handleResult(event);
            break;
        case EVENT_WAKEUP:
            handleWakeup(event);
            break;
        // 其他事件...
    }
}
```

**plan-reviewer 评审重点**：
- 步骤是否可执行
- 依赖顺序是否正确
- 是否遗漏关键步骤
- 是否存在阻塞问题

---

### 阶段 3：aiui-executing（执行实现）

**职责**：按计划执行代码变更

**输入**：计划文档路径

**执行模式**：

**1. 通用模式**（默认）

```
code-writer → code-reviewer
```

适用于：通用开发任务

**2. 领域适配模式**（AIUI/语音任务）

```
aiui-code-writer → aiui-code-reviewer
```

触发条件：
- 涉及 AIUI SDK
- 涉及语音链路
- 涉及音频采集/唤醒/降噪
- 涉及端侧语音硬件
- 涉及 AIUI 日志协议

**执行流程**：

1. 读取计划文档
2. 逐步执行：
   - 调用对应 code-writer 实现
   - 调用对应 code-reviewer 审查
   - 运行测试验证
3. 所有步骤完成 → 可选进入 finishing-development

**aiui-code-writer 特殊能力**：
- 理解 AIUI SDK 文档
- 正确处理 EVENT_RESULT 两步解析机制
- 正确配置音频参数
- 正确处理唤醒/识别事件
- 遵循 AIUI 最佳实践

**code-reviewer / aiui-code-reviewer 审查重点**：
- 代码质量
- 错误处理
- 资源管理
- 领域特定问题（如 AIUI 回调解析）

---

## 6. AIUI SDK 集成完整链路

### 链路概览

```
用户：我要在 Linux 上集成语音功能
    ↓
brainstorming Phase 1: 工程扫描
    → 发现：无 SDK、无配置
    ↓
brainstorming Phase 2: 环境门禁 (HARD-GATE)
    ↓
    preflight Step 1: 平台+设备确认
        → aiui-audio-environment
        → 输出：Linux x64, 单麦克风, data_source=mic
    ↓
    preflight Step 2: 工具链可用
        → aiui-dev-env-config (配置 ~/.aiui-code/dev-env.yaml)
        → aiui-toolchain-linux (验证 gcc, CMake, ALSA)
        → 输出：✓ PASS
    ↓
    preflight Step 3: SDK 下载 + Demo 研究
        → aiui-artifact-download
        → 下载：libaiui_linux_x64.tar.gz
        → 解压到：sdk/aiui/
        → 读取 Demo：理解 API 调用
        → 输出：✓ SDK 就绪
    ↓
    preflight Step 4: 凭据就绪
        → aiui-credentials
        → 引导用户获取：appid, key, api_secret
        → 自动确定 scene（根据发布状态）
        → 输出：✓ 凭据就绪
    ↓
    preflight Step 5: 配置参数确认
        → aiui-config-authoring
        → 根据设备约束 + 凭据生成 aiui.cfg
        → 包含：音频参数 + 唤醒配置 + 识别配置
        → 输出：✓ cfg/aiui.cfg 已生成
    ↓
    preflight Step 6: SDK 可编译链接
        → aiui-sdk-setup
        → 创建 CMakeLists.txt
        → 编译最小示例
        → 输出：✓ 编译通过
    ↓
    ✅ 全部 PASS，继续 Phase 3
    ↓
brainstorming Phase 3-8: 意图分类 → 访谈 → 设计 → 评审
    ↓
planning: 生成实现计划
    ↓
executing: 执行实现 (aiui-code-writer)
    ↓
完成
```

### 关键检查点

#### checkpoint 1: 平台识别

- 使用 `references/registry.yaml` 作为唯一事实源
- 不允许编造设备描述
- data_source 从 registry 读取，不可用户选择

#### checkpoint 2: 工具链验证

- 先配置 `dev-env.yaml`，再验证工具链
- 不重复检测工具路径

#### checkpoint 3: Demo 研究

- 必须读取 SDK Demo 源码
- 理解 API 调用方式、配置格式、目录结构

#### checkpoint 4: scene 确定

- 由 agent 根据发布状态自动确定
- 禁止用户自填 scene

#### checkpoint 5: 配置生成

- 依赖 #1 设备约束 + #4 凭据
- 自动生成，不手动编写

#### checkpoint 6: 编译验证

- 最小示例必须编译通过
- 验证链接无误

---

## 7. 技能体系详解

### 入口与分流技能

#### aiui-workflow-entry

**用途**：明确问题快速路由

**适用场景**：
- 用户有明确问题（"配置不生效"、"识别无结果"）
- 功能咨询（"如何实现声纹识别"）
- 排错（"日志显示 xxx 错误"）

**不适用场景**：
- 模糊需求 → 使用 aiui-brainstorming
- 首次集成 → 使用 aiui-brainstorming

**路由表**：

| 问题类型 | 路由到 |
|---------|--------|
| 配置相关 | aiui-config-authoring |
| 错误排查 | aiui-troubleshoot |
| API 使用 | aiui-api-command-cookbook |
| 下载资源 | aiui-artifact-download |
| 工具链问题 | aiui-toolchain-{platform} |
| 音频问题 | aiui-audio-environment |
| 动态实体/声纹 | aiui-sync-and-voice |

#### aiui-preflight

**用途**：AIUI 集成任务的环境前置门禁

**调用方**：aiui-brainstorming Phase 2

**6 步检查**（详见上文"AIUI SDK 集成完整链路"）

#### aiui-config-authoring

**用途**：根据用例描述选择服务链路和配置模板

**能力**：
- 版本选择（aiui_ver v1/v2/v3）
- 链路选择（本地/云端/混合）
- 参数校验
- 冲突定位

**输入**：
- 设备约束（来自 aiui-audio-environment）
- 凭据（来自 aiui-credentials）
- 功能需求（唤醒 / 识别 / 播报 / 动态实体）

**输出**：
- aiui.cfg 文件

**关键配置项**：
- `global.data_source`：音频数据源（mic / user）
- `global.raw_audio_format`：音频格式（16k, 16bit, mono）
- `interact.ivw`：唤醒配置
- `interact.iat`：识别配置
- `interact.tts`：播报配置

---

### 平台与工具链技能

#### aiui-audio-environment

**用途**：平台+设备确认、音频验证

**两个 Step**：

**Step 1: 平台+设备确认**（preflight 调用）
- 使用 `references/registry.yaml` 匹配设备
- 输出设备约束清单：
  - `data_source`（mic / user）
  - `raw_channels`（原始声道数）
  - `mic_channels`（麦克风数）
  - 唤醒资源要求

**Step 2: 音频验证**（可选，在运行时问题排查时调用）
- 验证采样率（16kHz）
- 验证声道（mono）
- 验证 VAD（Voice Activity Detection）
- 验证唤醒链路

#### aiui-toolchain-windows

**用途**：Windows 平台工具链检测

**检查项**：
- MSVC（Visual Studio）
- CMake
- x64 架构支持

**输出**：PASS / FAIL

#### aiui-toolchain-linux

**用途**：Linux 平台工具链检测

**检查项**：
- gcc / g++
- CMake
- ALSA（音频库）
- glibc 兼容性

**输出**：PASS / FAIL

#### aiui-toolchain-android

**用途**：Android 平台工具链检测

**检查项**：
- Android NDK
- Gradle
- ABI 支持（armeabi-v7a / arm64-v8a）
- RECORD_AUDIO 权限

**输出**：PASS / FAIL

#### aiui-multimodal-socket

**用途**：RK3588 多模态套件集成

**适用场景**：
- RK3588 开发板
- USB 麦克风阵列
- 多模态交互（音频 + 视频）

**配置项**：
- USB 设备识别
- 阵列配置
- 降噪参数

---

### 配置与 API 技能

#### aiui-api-command-cookbook

**用途**：SDK API 调用顺序、命令发送、事件解析

**覆盖内容**：

**1. Agent 生命周期**
- createAgent
- init
- sendCommand
- getEvent
- destroy

**2. 命令发送 (CMD_*)**
- CMD_START：启动交互
- CMD_STOP：停止交互
- CMD_WRITE：写入音频数据
- CMD_BUILD_GRAMMAR：构建语法
- CMD_UPDATE_LOCAL_LEXICON：更新本地词库
- CMD_SYNC：动态实体同步

**3. 事件处理 (EVENT_*)**
- EVENT_STATE：状态变化
- EVENT_RESULT：交互结果（**核心，必读**）
- EVENT_ERROR：错误事件
- EVENT_START_RECORD：开始录音
- EVENT_STOP_RECORD：停止录音
- EVENT_WAKEUP：唤醒事件

**4. EVENT_RESULT 两步解析机制**（高频陷阱）

❌ **错误做法**：
```cpp
// 直接从 info 取结果 —— 错误！
const char* result = event.getInfo();
```

✅ **正确做法**：
```cpp
// Step 1: 解析 info 获取 cnt_id 和 sub
const char* info = event.getInfo();
json j = json::parse(info);
string sub = j["data"][0]["params"]["sub"];
string cnt_id = j["data"][0]["content"][0]["cnt_id"];

// Step 2: 使用 cnt_id 调用 getBinary 获取实际内容
Buffer* buffer = event.getBinary(cnt_id.c_str());

// Step 3: 根据 sub 类型解析
if (sub == "iat") {
    // UTF-8 文本
    string text = string((char*)buffer->data, buffer->size);
} else if (sub == "tts") {
    // 二进制音频（base64 或原始）
    // 保存到文件或播放
} else if (sub == "nlp") {
    // JSON 结果
    json nlp = json::parse(string((char*)buffer->data, buffer->size));
}
```

#### aiui-permissions-setup

**用途**：减少构建过程中的权限确认提示

**配置文件**：`.claude/settings.json`

**推荐配置**：
```json
{
  "allowedCommands": [
    "cmake",
    "make",
    "g++",
    "gcc",
    "adb",
    "gradle",
    "npm"
  ],
  "allowedPaths": [
    "/home/user/project",
    "/opt/aiui-sdk"
  ]
}
```

---

### 资源与高级功能技能

#### aiui-artifact-download

**用途**：下载 SDK 包、唤醒资源、模型文件

**支持资源**：

1. **SDK 包**
   - Linux x64 / arm
   - Windows x64
   - Android (AAR / NDK)
   - macOS

2. **唤醒资源**
   - vtn.ini（唤醒配置）
   - ivw/（唤醒模型）
   - evad_*.jet（VAD 模型）

3. **语音模型**
   - ASR 模型
   - TTS 音库

**下载流程**：
1. 根据平台选择对应包
2. 验证 MD5
3. 解压到指定目录
4. 更新 CMakeLists.txt / build.gradle

#### aiui-sdk-setup

**用途**：SDK 集成编译、链接问题排查

**能力**：
- 生成 CMakeLists.txt（Linux/Windows）
- 生成 build.gradle（Android）
- 配置链接路径
- 解决常见编译错误

**输出**：
- 可编译的最小示例
- 验证链接成功

#### aiui-sync-and-voice

**用途**：动态实体、声纹识别、声音复刻

**功能模块**：

1. **动态实体同步**
   - 联系人
   - 应用列表
   - 自定义词库
   - 命令：CMD_SYNC

2. **声纹识别**
   - 声纹注册
   - 声纹识别
   - 声纹验证

3. **声音复刻**
   - 采集音频样本
   - 训练音库
   - TTS 合成

---

### 排障与验证技能

#### aiui-troubleshoot

**用途**：通用故障排查

**决策树**：

```
问题描述
    ↓
分类识别
    ├─ 无结果
    │   ├─ 网络问题
    │   ├─ 配置错误
    │   ├─ 事件解析错误
    │   └─ 音频问题
    ├─ 结果截断
    │   ├─ VAD 超时
    │   └─ 网络不稳定
    ├─ 状态异常
    │   ├─ 初始化失败
    │   ├─ 认证失败
    │   └─ 资源缺失
    └─ 其他
        └─ 调用 aiui-log-analysis
```

**排查步骤**：
1. 收集信息（日志、配置、代码片段）
2. 模式识别
3. 定位根因
4. 给出修复建议
5. 提供参考文档

#### aiui-log-analysis（通过 aiui-troubleshoot 调用）

**用途**：日志模式识别

**支持格式**：
- aiui.log（SDK 日志）
- sessinfo（会话信息）
- 事件链路日志

**分析能力**：
- 识别错误码
- 识别超时模式
- 识别认证失败
- 识别网络问题
- 识别音频问题

**输出**：
- 问题定位
- 修复建议
- 相关文档链接

---

### 集成指南技能

#### aiui-integration-guides/android-native

**用途**：Android 原生集成指南

**覆盖内容**：
- AAR 集成
- NDK 集成
- Gradle 配置
- 权限申请（RECORD_AUDIO / INTERNET）
- 混淆规则

#### aiui-integration-guides/embedded-linux

**用途**：嵌入式 Linux 集成指南

**覆盖内容**：
- 交叉编译
- ALSA 配置
- 系统服务集成
- 开机自启动

#### aiui-integration-guides/qt-desktop

**用途**：Qt 桌面集成指南

**覆盖内容**：
- Qt 工程配置
- 信号槽集成
- UI 交互设计

#### aiui-integration-guides/rtos

**用途**：RTOS 集成指南

**覆盖内容**：
- FreeRTOS / RT-Thread 适配
- 任务调度
- 内存管理
- 中断处理

---

## 8. 子代理系统

### 子代理概览

| 子代理 | 职责 | 调用时机 |
|--------|------|---------|
| spec-reviewer | 设计文档审查 | brainstorming Phase 7 |
| plan-writer | 计划生成 | planning |
| plan-reviewer | 计划审查 | planning |
| code-writer | 通用代码实现 | executing (通用模式) |
| code-reviewer | 通用代码审查 | executing (通用模式) |
| aiui-code-writer | AIUI/语音代码实现 | executing (领域模式) |
| aiui-code-reviewer | AIUI/语音代码审查 | executing (领域模式) |
| aiui-e2e-runner | 运行级验证 | executing (可选) |

### spec-reviewer

**输入**：设计文档路径

**评审维度**：
1. **Completeness（完整性）**
   - 是否明确目标与非目标
   - 是否覆盖关键场景
   - 是否遗漏重要决策

2. **Consistency（一致性）**
   - 术语使用是否一致
   - 架构描述是否自洽
   - 方案选择是否矛盾

3. **Clarity（清晰度）**
   - 表述是否清晰
   - 逻辑是否连贯
   - 是否有歧义

4. **Scope（范围合理性）**
   - 范围是否过大
   - 范围是否过小
   - 是否可实现

5. **YAGNI（不过度设计）**
   - 是否引入不必要的复杂性
   - 是否提前优化
   - 是否过度抽象

**输出**：PASS / FAIL + 修改建议

### plan-writer

**输入**：设计文档路径

**输出**：实现计划文档

**生成能力**：
- 将设计转化为可执行步骤
- 识别依赖关系
- 估算工作量
- 标注验证点

### plan-reviewer

**输入**：计划文档路径

**评审重点**：
- 步骤是否可执行
- 依赖顺序是否正确
- 是否遗漏关键步骤
- 是否存在阻塞问题

**策略**：最多 2 轮评审，只找阻塞问题

### code-writer

**输入**：计划文档路径 + 当前步骤

**能力**：
- 读取现有代码
- 匹配项目风格
- 生成符合规范的代码
- 添加必要注释

### code-reviewer

**输入**：代码变更

**评审维度**：
- 代码质量
- 错误处理
- 资源管理
- 性能考虑
- 安全性

### aiui-code-writer（领域适配器）

**输入**：计划文档路径 + 当前步骤

**特殊能力**（在 code-writer 基础上增强）：
1. **理解 AIUI SDK 文档**
   - 自动加载相关文档章节
   - 理解 API 语义
   - 理解配置参数

2. **正确处理 EVENT_RESULT**
   - 两步解析机制
   - 根据 sub 类型处理
   - 正确使用 getBinary

3. **正确配置音频参数**
   - 16kHz 采样率
   - 16bit 位深
   - mono 声道

4. **遵循 AIUI 最佳实践**
   - Agent 生命周期管理
   - 事件循环设计
   - 资源释放

### aiui-code-reviewer（领域适配器）

**输入**：代码变更

**特殊能力**（在 code-reviewer 基础上增强）：
1. **检查 AIUI 专有陷阱**
   - EVENT_RESULT 是否正确解析
   - 是否直接从 info 取结果（错误）
   - getBinary 的 key 是否正确
   - sub=tts 时是否正确处理 base64

2. **检查配置正确性**
   - 音频参数是否匹配
   - 唤醒资源路径是否正确
   - scene 是否正确

3. **检查资源管理**
   - Agent 是否正确销毁
   - Buffer 是否释放
   - 事件是否及时处理

### aiui-e2e-runner

**输入**：实现完成的代码

**验证流程**：
1. **Launch**：启动应用
2. **Readiness**：等待就绪
3. **Stimulus**：施加刺激（如发送音频）
4. **Observe**：观察结果
5. **Assert**：断言验证
6. **Teardown**：清理资源

**适用场景**：
- 集成测试
- 端到端验证
- 回归测试

---

## 9. 配置与定制

### OpenCode 多模型策略

**配置文件**：`.opencoderc.json`

**示例配置**：

```json
{
  "aiuicode": {
    "agents": {
      "plan-writer": { "model": "AstronCodingPlan/xopkimik25" },
      "code-writer": { "model": "AstronCodingPlan/xopkimik25" },
      "aiui-code-writer": { "model": "AstronCodingPlan/xopkimik25" },
      "aiui-e2e-runner": { "model": "AstronCodingPlan/xminimaxm25" },
      "plan-reviewer": { "model": "Iflytek-Mass/xopglm51" },
      "code-reviewer": { "model": "Iflytek-Mass/xopglm51" },
      "aiui-code-reviewer": { "model": "Iflytek-Mass/xopglm51" },
      "spec-reviewer": { "model": "Iflytek-Mass/xopglm51" }
    }
  }
}
```

**策略说明**：
- **写类子代理**（plan-writer, code-writer, aiui-code-writer）：使用编码能力强的模型
- **审查类子代理**（*-reviewer）：使用推理能力强的模型
- **验证类子代理**（aiui-e2e-runner）：使用平衡型模型

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `AIUIPOWERS_DOCS_ROOT` | AIUI 文档根目录 | `<plugin>/skills/aiui-sdk/docs/aiui` |
| `AIUI_MODEL_OPUS` | Opus 级别模型 | 继承主配置 |
| `AIUI_MODEL_SONNET` | Sonnet 级别模型 | 继承主配置 |

### dev-env.yaml 配置

**位置**：`~/.aiui-code/dev-env.yaml`

**用途**：持久化开发环境信息，避免重复检测

**示例**：
```yaml
linux:
  gcc_path: /usr/bin/gcc
  cmake_path: /usr/bin/cmake
  alsa_available: true

windows:
  msvc_path: "C:\Program Files\Microsoft Visual Studio\2022\Community"
  cmake_path: "C:\Program Files\CMake\bin\cmake.exe"

android:
  ndk_path: "/home/user/Android/Sdk/ndk/25.1.8937393"
  gradle_path: "/home/user/.gradle"
```

---

## 10. 常见场景示例

### 示例 1：首次接入（Linux 单麦）

**需求**：
```
在 Ubuntu 20.04 上实现语音唤醒和识别，使用单麦克风
```

**执行过程**：

1. **brainstorming**
   - Phase 1：扫描工程（发现无 SDK）
   - Phase 2：preflight 6 步检查（全 PASS）
   - Phase 3-8：生成设计文档

2. **planning**
   - 生成 10 步实现计划

3. **executing**
   - 使用 aiui-code-writer
   - 生成代码文件：
     - `src/aiui_client.cpp`（Agent 封装）
     - `src/event_handler.cpp`（事件处理）
     - `src/main.cpp`（主程序）
     - `CMakeLists.txt`（构建脚本）
     - `cfg/aiui.cfg`（配置文件）

**关键代码片段**：

```cpp
// EVENT_RESULT 正确处理
void handleResult(const IAIUIEvent& event) {
    const char* info = event.getInfo();
    json j = json::parse(info);
    
    for (auto& data : j["data"]) {
        string sub = data["params"]["sub"];
        string cnt_id = data["content"][0]["cnt_id"];
        
        Buffer* buffer = event.getBinary(cnt_id.c_str());
        
        if (sub == "iat") {
            string text = string((char*)buffer->data, buffer->size);
            cout << "识别结果: " << text << endl;
        } else if (sub == "nlp") {
            json nlp = json::parse(string((char*)buffer->data, buffer->size));
            cout << "NLP结果: " << nlp.dump(2) << endl;
        }
    }
}
```

### 示例 2：添加动态实体

**需求**：
```
在现有 AIUI 应用中添加联系人动态实体同步
```

**执行过程**：

1. **workflow-entry**
   - 识别为"功能咨询"
   - 路由到 aiui-sync-and-voice

2. **aiui-sync-and-voice**
   - 提供动态实体同步方案
   - 生成代码示例

3. **executing**（可选，如果用户要求实现）
   - 添加 CMD_SYNC 调用
   - 构建实体 JSON

**关键代码片段**：
```cpp
// 动态实体同步
void syncContacts(IAIUIAgent* agent, const vector<Contact>& contacts) {
    json entity;
    entity["name"] = "IFLYTEK.contact";
    
    json data = json::array();
    for (const auto& c : contacts) {
        json item;
        item["contact_name"] = c.name;
        item["phone_number"] = c.phone;
        data.push_back(item);
    }
    entity["data"] = data;
    
    json syncData;
    syncData["syncData"] = json::array({entity});
    
    IAIUIMessage* msg = IAIUIMessage::create(CMD_SYNC);
    msg->setData(syncData.dump().c_str(), syncData.dump().size());
    agent->sendMessage(msg);
    msg->destroy();
}
```

### 示例 3：排查识别无结果

**问题**：
```
AIUI 识别没有返回结果，日志中看到 EVENT_RESULT 但无内容
```

**执行过程**：

1. **workflow-entry**
   - 识别为"故障排查"
   - 路由到 aiui-troubleshoot

2. **aiui-troubleshoot**
   - 请求用户提供：代码片段、日志
   - 分析：发现直接从 info 取结果
   - 定位：EVENT_RESULT 解析错误

3. **给出修复方案**
   ```
   问题：代码直接从 info 读取结果内容
   
   修复：改用两步解析机制
   1. 从 info 解析 cnt_id
   2. 调用 getBinary(cnt_id) 获取实际内容
   ```

### 示例 4：跨平台移植（Linux → Android）

**需求**：
```
将现有 Linux AIUI 应用移植到 Android
```

**执行过程**：

1. **brainstorming**
   - Phase 1：扫描（发现已有 Linux 代码）
   - Phase 2：preflight（Android 分支）
     - aiui-toolchain-android（检查 NDK）
     - aiui-artifact-download（下载 Android SDK）
   - 生成设计文档（突出差异点）

2. **planning**
   - 识别平台差异：
     - SDK 接口（AAR vs NDK）
     - 权限申请
     - 音频录制方式
     - 配置路径

3. **executing**
   - 生成 Android 工程结构
   - 适配 Java/Kotlin 调用层
   - 配置 Gradle
   - 添加权限声明

**关键差异**：
- Linux：直接调用 libaiui.so
- Android：通过 AAR 封装，Java 接口

### 示例 5：声学测试（麦克风阵列性能验证）

**需求**：
```
我有一个 6+1 环形麦克风阵列设备，需要验证麦克风性能是否合格，
准备集成 AIUI 唤醒和识别
```

**适用场景**：
- 新设备首次接入前的硬件验证
- 多麦阵列幅值一致性检查
- 量产线上声学性能测试
- 现场出现唤醒率低、识别准确率低时的根因定位

**执行过程**：

1. **触发方式**
   
   两种入口任选其一：
   ```
   方式 A: 用户主动触发（关键词）
   "帮我做一下声学测试" / "测试麦克风" / "回采测试"
   
   方式 B: preflight 自动调用
   在 brainstorming Phase 2 的 preflight Step 2 中，
   如检测到多麦阵列设备，自动调用 aiui-acoustic-test
   
   方式 C: 斜杠命令
   /acoustic-test
   ```

2. **Step 0：加载项目上下文**
   - 检查 Python 3.8+ 环境
   - 自动提取已有信息（平台、设备型号、SDK 版本、通道布局）
   - **禁止重复询问**已记录的信息

3. **执行 5 项声学测试**
   
   | 测试项 | 目的 | 物理操作 |
   |--------|------|---------|
   | 麦克风幅值 | 验证各麦克风灵敏度一致性 | 在固定距离播放标准音 |
   | 回采幅值 | 验证回声参考通道幅值 | 播放参考音通过扬声器 |
   | 气密性 | 验证麦克风封装气密性 | 用蓝丁胶堵孔测试 |
   | 回采相位 | 验证回采通道与麦克风的相位关系 | 同步播放+录音 |
   | 静音底噪 | 验证设备静默时的噪声水平 | 安静环境下纯录音 |

4. **自动化流程**
   ```
   AI 用 Bash 工具自动执行：
   ├─ 编译录音 demo
   ├─ 在设备上运行录音
   ├─ 提取录音文件到本地
   ├─ 调用分析脚本（Python）
   ├─ 生成 Markdown 报告
   └─ 输出 PDF 报告
   
   求助用户的时机仅限：
   - 物理操作（摆音箱、堵孔、移除蓝丁胶）
   - 必须用户决策的选择题
   - AI 多次修复仍失败
   ```

5. **输出产物**
   ```
   MicTest/
   ├── recordings/          # 各项测试录音文件
   │   ├── mic_amplitude/
   │   ├── echo_amplitude/
   │   ├── airtight/
   │   ├── echo_phase/
   │   └── noise_floor/
   ├── analysis/            # 分析中间结果
   └── reports/
       ├── report.md        # Markdown 报告（中文测试项名）
       └── report.pdf       # PDF 报告
   ```

**关键点**：
- **Demo 双重价值**：声学测试的录音 demo 同时是 executing 阶段录音模块的参考实现
- **跨平台支持**：Android / Linux / Windows / RTOS 均可使用
- **脚本只读**：`skills/aiui-acoustic-test/scripts/` 下的脚本不允许修改，遇到设备不兼容应反馈而非改脚本
- **报告自动化**：从录音到 PDF 报告全自动，开发者只做物理操作

**典型问题**：
- 麦克风幅值不一致 → 焊接问题 / 元器件批次差异
- 气密性差 → 外壳装配不良
- 静音底噪高 → 电源干扰 / 屏蔽不良
- 回采相位异常 → 回采线路连接错误

### 示例 6：RK3588 多模态套件接入

**需求**：
```
我有讯飞 RK3588 多模态成品设备（极简多模态/地铁/一体机/AIUI开发套件），
需要在我的应用中接收降噪音频、视频帧、识别结果
```

**适用场景**：
- RK3588 成品设备的应用层对接
- 多模态交互（音频 + 视频 + 识别）
- 不需要修改 RK3588 内部 SDK，仅作为 Socket 客户端接收数据
- 触发关键词：`RK3588 Socket`、`9080`、`9090`、`19199`、`极简多模态`、`地铁多模态`

**数据流方向**：**设备 → 你的应用**（不是反向）

**执行过程**：

1. **触发**
   ```
   "帮我对接 RK3588 多模态设备" 
   / "用 9080 端口接收音频"
   / "极简多模态怎么接入"
   ```
   
   AI 自动调用 `aiui-multimodal-socket`

2. **硬件前置检查**
   
   AI 引导确认：
   ```
   ☐ 声卡板 ↔ 3588 主板：4pin 音视频线已连接
   ☐ 回声参考：声卡 "echo" 口 ↔ 3588 耳机口（3.5mm）
   ☐ 摄像头：4pin USB2.0 已连接声卡板
   ☐ 网络：3588 已联网，且与应用主机同网段
   ☐ 设备 IP：通过串口 type=0x05 查询 local_ip
   ```

3. **三个 Socket 协议要点**
   
   | 端口 | 协议 | 模式 | 数据 |
   |------|------|------|------|
   | 9080 | 音频 | 单工（设备→应用） | type=0x0a, PCM 16k/16bit/mono |
   | 9090 | 视频 | 半双工（带 ACK） | type=0x07 格式 + 0x08 图像 + 0x09/0x0b 人脸 |
   | 19199 | 识别语义 | 双工 | type=0x04 GZIP JSON, type=0x05 主控 |
   
   **公共帧格式**：
   ```
   [0xA5][0x01][type][len][msgId:2B LE][payload][checksum]
   ```

4. **架构实现要点**
   
   ```
   应用层
   ├── AudioSocket (独立线程) ──→ 端口 9080
   ├── VideoSocket (独立线程) ──→ 端口 9090
   └── EventSocket (独立线程) ──→ 端口 19199
   ```
   
   **强制要求**：
   - ✅ 三 Socket 独立线程（不能合并）
   - ✅ 全连接判定（三个全连才算"已连接"）
   - ✅ 视频帧必须回 ACK（500ms 超时设备会推"最新"帧）
   - ✅ type=0x04 必须先 GZIP 解压再解析

5. **EVENT_RESULT 字段解析**（高频陷阱）
   
   19199 端口的 `aiui_event` 字段：
   
   ```javascript
   // IAT (语音识别)
   result.text.ws[].cw[0].w  // 提取识别文本
   
   // NLP (语义)
   result.nlp.text + result.nlp.status  // 流式累积
   
   // TTS (播报)
   result.data  // base64 解码为 PCM
   ```
   
   **⚠️ 禁止凭协议文档或训练记忆猜测字段路径**——先 dump 真实数据再写代码

6. **流式 UI 测试要求**（UI 组件强制）
   
   涉及流式数据的 UI 组件，**测试必须覆盖至少 3 帧场景**：
   
   | 场景 | 行为 | 常见错误 |
   |------|------|---------|
   | IAT 流式识别 | 首帧新建气泡，中间帧**更新同一气泡**，末帧固定 | 每帧都新建气泡 |
   | NLP 流式回复 | `isStart=true` 新建，后续**追加 delta** | 用 `setText` 替换而非 `appendText` 追加 |
   | TTS 流式播放 | 每次 `feedPcm` **追加** PCM | QBuffer pull 模式导致重放 |

7. **集成步骤**（executing 阶段）
   ```
   Step 1: 建立三个 Socket 连接（独立线程）
   Step 2: 实现帧解析器（公共帧 + 各 type 处理）
   Step 3: 实现视频 ACK 机制
   Step 4: 实现 GZIP 解压
   Step 5: 实现状态机（全连接判定）
   Step 6: 实现 EVENT_RESULT 弹性解析
   Step 7: 实现流式 UI 渲染（IAT/NLP/TTS）
   Step 8: 接入主控命令（type=0x05）
   ```

**关键差异（vs 直接集成 AIUI SDK）**：
- ✅ 不需要 AIUI SDK 编译/链接
- ✅ 不需要 aiui.cfg 配置
- ✅ 不需要凭据（设备已内置）
- ✅ 直接接收降噪后的音频和识别结果
- ⚠️ 需要严格遵循 Socket 协议
- ⚠️ 需要处理 ACK 和 GZIP

**典型问题**：
- 视频卡顿 → 没有及时回 ACK
- 识别结果解析为空 → GZIP 未解压 / 字段路径错误
- 三个端口连接不稳定 → 没用独立线程 / 状态机判定错误
- 流式气泡重复 → UI 组件没区分首帧/中间帧/末帧

---

## 11. 故障排查

### 常见问题 1：技能无响应

**症状**：
```
/aiui-workflow-entry
(无任何输出)
```

**原因**：
- 插件未正确加载
- 技能路径配置错误

**解决**：
1. 检查插件安装
   ```bash
   claude plugin list
   ```

2. 检查技能路径
   - Claude Code: `.claude-plugin/`
   - Codex: `.codex-plugin/`
   - OpenCode: `.opencode/plugins/`

3. 重新加载插件
   ```bash
   claude plugin reload aiuicode
   ```

### 常见问题 2：preflight 卡在某一步

**症状**：
```
✓ Step 1: 平台+设备确认
✓ Step 2: 工具链可用
❌ Step 3: SDK 下载 (超时)
```

**原因**：
- 网络问题
- 下载链接失效
- 磁盘空间不足

**解决**：
1. 检查网络连接

2. 手动下载 SDK
   ```bash
   # 从讯飞开放平台下载
   # 解压到 sdk/aiui/
   ```

3. 跳过下载，直接配置路径
   ```
   我已经手动下载了 SDK 到 /path/to/sdk，请跳过下载步骤
   ```

### 常见问题 3：EVENT_RESULT 解析失败

**症状**：
```
收到 EVENT_RESULT，但解析结果为空或乱码
```

**原因**：
- 未使用两步解析机制
- getBinary 的 key 错误
- sub=tts 时当作 UTF-8 解析

**解决**：
参考 [aiui-api-command-cookbook](#aiui-api-command-cookbook) 的正确做法

### 常见问题 4：编译错误

**症状**：
```
undefined reference to `AIUI::createAgent`
```

**原因**：
- CMakeLists.txt 链接路径错误
- SDK 库文件缺失

**解决**：
1. 检查 CMakeLists.txt
   ```cmake
   link_directories(${CMAKE_SOURCE_DIR}/sdk/aiui/lib)
   target_link_libraries(myapp aiui pthread)
   ```

2. 检查库文件
   ```bash
   ls sdk/aiui/lib/libaiui.so
   ```

3. 调用 aiui-sdk-setup 重新生成构建脚本

### 常见问题 5：认证失败

**症状**：
```
EVENT_ERROR: error_code=10114, error_desc="appid invalid"
```

**原因**：
- appid 错误
- scene 错误
- 网络不通

**解决**：
1. 检查 aiui.cfg
   ```
   global.appid=<正确的appid>
   ```

2. 检查 scene（不可手动填写）
   ```
   由 aiui-credentials 自动确定
   ```

3. 检查网络
   ```bash
   ping api.xfyun.cn
   ```

---

## 12. 最佳实践

### 1. 优先使用工作流

**❌ 避免**：
```
请帮我写一个 AIUI 唤醒识别的代码
```

直接写代码，跳过设计和计划，容易遗漏关键细节

**✅ 推荐**：
```
我要在 Linux 上实现 AIUI 唤醒和识别
```

让 AI 自动进入 brainstorming → planning → executing 流程，确保完整性

### 2. 信任环境门禁

**❌ 避免**：
```
跳过 preflight，直接写代码
```

环境未就绪会导致后续大量返工

**✅ 推荐**：
让 preflight 完整执行 6 步检查，确保环境就绪后再进入开发

### 3. 明确问题时使用 workflow-entry

**✅ 适用场景**：
- "配置 scene 参数不生效"
- "如何实现声纹识别"
- "日志显示 10114 错误"

快速路由到对应技能，节省时间

**❌ 不适用场景**：
- "我想做个语音助手"（模糊需求 → brainstorming）

### 4. 理解两步解析机制

**EVENT_RESULT 是最高频陷阱**

务必记住：
1. info 只是元数据
2. 实际内容在 getBinary(cnt_id)
3. 根据 sub 类型解析

### 5. 保持文档同步

**工作流产物**：
- `docs/specs/` - 设计文档
- `docs/plans/` - 实现计划
- 代码变更

保持三者一致，便于后续维护和回溯

### 6. 善用对抗审查

**每个产物都有独立审查**：
- spec-reviewer：设计文档
- plan-reviewer：实现计划
- code-reviewer / aiui-code-reviewer：代码

信任审查结果，及时修正问题

### 7. 配置 dev-env.yaml

**一次配置，持久使用**

避免每次都重新检测工具链

### 8. 领域适配器自动触发

**不需要手动指定**：
- 任务涉及 AIUI → 自动使用 aiui-code-writer
- 通用开发 → 自动使用 code-writer

信任 AI 的判断

### 9. 阅读 SDK 文档

**关键文档位置**：
- `skills/aiui-sdk/docs/`
- 尤其是：
  - `3.2.6 回调解析说明.md`（EVENT_RESULT）
  - `3.2.5 数据发送方式.md`（CMD_WRITE）
  - `3.2.7 交互结果协议说明.md`（结果格式）
  - `3.7 错误码列表.md`（排错）

### 10. 逐步验证

**每步完成后验证**：
- 编译通过
- 测试通过
- 符合预期

不要等到全部完成才验证

---

## 附录

### A. 技能索引

**工作流技能**：
- aiui-brainstorming
- aiui-planning
- aiui-executing
- finishing-development

**入口与分流**：
- aiui-workflow-entry
- aiui-preflight
- aiui-config-authoring

**平台与工具链**：
- aiui-audio-environment
- aiui-toolchain-windows
- aiui-toolchain-linux
- aiui-toolchain-android
- aiui-multimodal-socket
- aiui-dev-env-config

**配置与 API**：
- aiui-api-command-cookbook
- aiui-permissions-setup

**资源与高级功能**：
- aiui-artifact-download
- aiui-sdk-setup
- aiui-sync-and-voice
- aiui-credentials

**排障与验证**：
- aiui-troubleshoot
- aiui-verification

**集成指南**：
- aiui-integration-guides/android-native
- aiui-integration-guides/embedded-linux
- aiui-integration-guides/qt-desktop
- aiui-integration-guides/rtos

**其他**：
- aiui-acoustic-test（声学测试）
- aiui-custom-wakeword（自定义唤醒词）
- aiui-mic-record（麦克风采集）
- aiui-vtn-sdk-integration（外部 VTN 集成）
- aiui-multimodal-avvad（唇形降噪/人脸唤醒）

### B. 子代理索引

- spec-reviewer：设计文档审查
- plan-writer：计划生成
- plan-reviewer：计划审查
- code-writer：通用代码实现
- code-reviewer：通用代码审查
- aiui-code-writer：AIUI/语音代码实现
- aiui-code-reviewer：AIUI/语音代码审查
- aiui-e2e-runner：运行级验证

### C. 关键配置文件

**插件配置**：
- `.opencoderc.json`（OpenCode 项目配置）
- `~/.aiui-code/dev-env.yaml`（开发环境配置）
- `.claude/settings.json`（权限配置）

**AIUI 配置**：
- `cfg/aiui.cfg`（AIUI SDK 配置）
- `sdk/aiui/`（SDK 安装目录）
- `AIUI/assets/`（唤醒资源目录）

**工作流产物**：
- `docs/specs/`（设计文档）
- `docs/plans/`（实现计划）

### D. 快速命令参考

**调用技能**：
```
/aiui-workflow-entry
/aiui-brainstorming
/aiui-planning
/aiui-executing
/finishing-development
```

**查看帮助**：
```
帮我介绍一下 AIUI Code
```

**快速开始**：
```
我要在 [平台] 上实现 AIUI [功能]
```

**问题排查**：
```
AIUI [具体问题描述]，请帮我排查
```

**功能咨询**：
```
如何实现 [AIUI 功能]
```

### E. 错误码速查

| 错误码 | 含义 | 解决方案 |
|--------|------|---------|
| 10114 | appid 无效 | 检查 aiui.cfg 中的 appid |
| 10160 | scene 无效 | 由 aiui-credentials 自动确定 |
| 10200 | 网络错误 | 检查网络连接 |
| 10700 | 引擎错误 | 检查唤醒资源路径 |
| 20001 | 音频格式错误 | 检查 16kHz PCM mono |
| 20003 | VAD 超时 | 调整 vad_eos 参数 |

详见：`skills/aiui-sdk/docs/business/3.7 错误码列表.md`

### F. 资源链接

**讯飞开放平台**：
- https://www.xfyun.cn/
- AIUI SDK 下载
- 凭据管理
- 文档中心

**相关仓库**（如适用）：
- aiui-sdk：SDK 源码
- aiui-sdk-pack：预编译包

### G. 更新日志

**v1.0.0**（当前版本）
- 支持 Claude Code / Codex / OpenCode 三平台
- 完整工作流（brainstorming → planning → executing）
- 30+ AIUI 专属技能
- 8 个子代理系统
- 对抗审查机制

---

## 结语

AIUI Code 旨在降低 AIUI SDK 集成门槛，通过结构化工作流和领域专用知识，帮助开发者快速构建语音交互应用。

**核心理念**：
1. **文档与代码分离**：设计 → 计划 → 实现，职责清晰
2. **对抗审查**：每个产物独立评审，确保质量
3. **领域适配**：自动识别 AIUI 任务，调用专用适配器
4. **环境门禁**：集成前强制检查，避免返工

**开始使用**：
```
我要在 [你的平台] 上实现 [你的需求]
```

让 AIUI Code 引导你完成从需求到实现的全过程。

**获取帮助**：
- 查看项目 README.md
- 调用 `/aiui-workflow-entry` 快速路由
- 阅读 SDK 文档：`skills/aiui-sdk/docs/`

**贡献与反馈**：
欢迎提出改进建议，帮助 AIUI Code 变得更好。

---

**文档版本**：1.0.0  
**最后更新**：2026-06-26