不是引擎冷冰冰地甩出一串评分，而是一位教练坐在棋盘对面，指着棋盘说「这步炮五进四，你看——红方为什么敢在这个时机渡河」。每一步的意图、得失、改进方案，都用语音和手势当面讲清楚。

棋叙就是为这个场景而生的项目：中国象棋 AI 复盘教练。棋盘回放、着法分析、教练语音讲解，全部在一个页面内完成。背后的端到端具身交互智能由魔珐星云端到端具身交互智能单 SDK 驱动——一个构造器、一次 ask 调用，感知、理解、表达在同一条链路中闭环。

---

一、星云控制台配置：六步完成具身应用全链路

在魔珐星云控制台为棋叙创建具身交互智能应用，需要完成六个配置步骤。

1、创建具身应用

在控制台新建端到端应用，获取 App ID 和 App Secret。这两个凭证将填入棋叙的教练面板，用于建立与星云平台的安全连接。

2、形象配置

为教练选择或定制一个合适的形象。棋叙的场景是面对面复盘，教练形象需要专业、亲和——建议选择一个穿着得体、表情自然的半身形象，让学员感到「坐在对面的是一位真正的教练」。

3、场景配置

配置教练的渲染场景。棋叙的教练面板高度为 440px（大屏 500px），建议选择适合半身展示的场景背景，让教练形象在面板中居中呈现，不会被截断或显得空旷。

4、音色配置

为教练选择合适的声音。棋叙的教练人设是「耐心专业、深入浅出」，建议选择沉稳而不沉闷、有亲和力的中年音色。语速适中，让棋理解读听起来像在聊天而不是念课文。

5、表演配置

配置教练的手势和表情表演。棋叙的核心场景是讲解棋步——教练在说到「妙手」时应该有赞赏的表情和手势，说到「失误」时应该沉稳地指出问题。表演配置直接影响讲解的感染力。

6、服务配置：ASR 与大脑

为当前应用配置语音识别和大模型服务。这一步体现了魔珐星云端到端具身交互智能的可插拔架构——可插拔并非简单的 API 拼接，平台依靠标准化接口契约与统一状态管理，保障模块替换后会话状态、事件流转、交互闭环不受破坏。ASR 支持 Xmov 自研、豆包、腾讯等多家供应商，大脑支持魔珐自研、豆包、OpenAI 兼容协议等多种接入模式。

六步配置完成后，将 App ID 和 App Secret 填入棋叙项目的 .env.development.local 文件，启动开发服务器即可看到教练形象自动出现在右侧面板。

---

二、产品理念：让 AI 教练坐在棋盘对面

象棋复盘的痛点不是找不到引擎——Stockfish 随时可以给出 +1.5 的评估分。痛点是没有人告诉你这个 +1.5 意味着什么：为什么这步棋好？好在哪里？如果换一种走法，局面会怎样？

棋叙的回答是：让一位有形象、有声音、有表情的教练坐在你对面，逐步讲解每一步的意图和失误。教练不是读引擎评分的播音员，而是一位能记住整盘棋进程、能引用前文关键着法、能根据复盘阶段调整讲解深度的引导者。

具身表达让「教棋」从看屏幕变成面对面。教练形象在右侧面板实时渲染，讲到关键着法时配合手势和表情，让抽象的棋理变得可感知。学员可以用语音或文字随时提问，教练即时回应——就像真正的面对面复盘一样。

---

三、技术架构：一个运行时依赖撑起一局棋

棋叙的技术栈极简到只有一个运行时依赖。

// 来源：package.json
"dependencies": {
  "vue": "3.5.18"
},
"devDependencies": {
  "@vitejs/plugin-vue": "6.0.1",
  "typescript": "~5.8.3",
  "vite": "7.1.2",
  "vue-tsc": "3.0.5"
}

魔珐星云端到端 SDK 不走 npm，而是通过 CDN 自包含脚本动态加载。业务侧不需要安装任何额外的包——SDK 加载后自动挂载到 window.XingyunAvatarAgent，服务封装层按需构造实例。

整个项目 src 目录共 1217 行代码，包含 5 个 Vue 组件（App.vue 主布局 + AppIcon 图标集 + ChessBoard 棋盘 + CoachPanel 教练面板 + MoveHistory 着法记录）、1 个服务封装层（avatar.ts）、1 个数据层（games.ts）和 1 个类型定义（types/index.ts）。

架构的核心思路是「本地回放 + 云端教练」双循环：棋盘回放、着法导航、分析展示完全在本地运行，不依赖网络；AI 教练的语音讲解走端到端具身交互智能单 SDK 链路，ASR、大模型推理、TTS、口型与表情驱动全部由平台内部完成。两个循环互不阻塞——即使教练连接失败，棋盘复盘功能照常可用。

---

四、数据模型：五级评价驱动的复盘体系

棋叙的复盘不是简单的「好棋/坏棋」二分法，而是五个等级的精细评价。

// 来源：src/types/index.ts
// 教练评价等级
export type MoveQuality = 'brilliant' | 'good' | 'inaccuracy' | 'mistake' | 'blunder'

// 单步分析
export interface MoveAnalysis {
  quality: MoveQuality
  summary: string
  detail: string
  alternative?: string
}

// 棋局
export interface Game {
  id: string
  title: string
  redPlayer: string
  blackPlayer: string
  date: string
  result: string
  opening: string
  moves: Move[]
  analyses: Record<number, MoveAnalysis>
}

五个等级分别对应不同的颜色标记：妙手（brilliant，翠绿色）、正着（good，深绿色）、不够精确（inaccuracy，金色）、失误（mistake，橙褐色）、败着（blunder，深红色）。这些颜色同时出现在分析卡片的质量徽章、着法记录的质量圆点和侧栏指标统计中，形成统一的视觉语言。

每步分析包含三个层次：summary 是一句话概括（如「炮击中卒！」），detail 是完整的棋理解读，alternative 是改进建议。不是每步棋都有 alternative——只有不够精确、失误和败着才会给出替代走法，因为妙手和正着不需要「如果重来」。

CoachContext 接口定义了教练智能体的上下文契约：当前棋局 ID、当前步数、总步数、复盘阶段（开局/中局/残局）、上一步着法记号和上一步分析摘要。每次向教练提问时，这个上下文会随问题一起发送，确保教练的回应基于完整的棋局进度。

// 来源：src/types/index.ts
// 复盘阶段
export type ReviewPhase = 'opening' | 'middlegame' | 'endgame'

// 教练上下文
export interface CoachContext {
  gameId: string
  currentMove: number
  totalMoves: number
  phase: ReviewPhase
  lastMove: string
  lastAnalysis: string
}

复盘阶段由 getPhase 函数根据当前步数与总步数的比例自动判定：前 25% 为开局，25%-75% 为中局，后 25% 为残局。教练人设提示词要求根据阶段调整讲解深度——开局侧重布局原理，中局侧重战术组合，残局侧重精确计算。

---

五、棋盘系统：SVG 纯函数回放与星位标记

ChessBoard 组件是整个棋叙最核心的视觉模块。它不依赖任何第三方棋盘库，完全用 SVG 手绘了一个标准中国象棋棋盘。

棋盘的核心是一个纯函数计算：根据 moveIndex 从初始局面逐步应用走法，得到当前步的棋盘状态。没有响应式状态库，没有副作用——同样的 moveIndex 永远得到同样的棋盘。

// 来源：src/components/ChessBoard.vue
// 根据 moveIndex 计算当前棋盘状态
const board = computed(() => {
  const b = INITIAL_BOARD.map(row => row.map(cell => cell ? { ...cell } : null))
  const moves = props.game.moves.slice(0, props.moveIndex)
  for (const m of moves) {
    b[m.to.row][m.to.col] = b[m.from.row][m.from.col]
    b[m.from.row][m.from.col] = null
  }
  return b
})

INITIAL_BOARD 是一个 10×9 的二维数组，精确定义了开局时 32 枚棋子的位置。pieceName 函数处理棋子名称的红黑区分——帅/将、仕/士、相/象、炮/砲、兵/卒，每种棋子在不同阵营有不同的汉字写法。

棋盘渲染包含传统元素：楚河汉界文字、九宫格斜线、14 个星位标记（花）。星位标记用 SVG path 绘制四角 L 形，标注炮位和兵/卒位，让棋盘看起来更像一副真实的木质棋具。

// 来源：src/components/ChessBoard.vue
// 星位坐标（炮位 + 卒/兵位）
const STAR_POINTS = [
  { col: 1, row: 2 }, { col: 7, row: 2 },  // 黑炮
  { col: 0, row: 3 }, { col: 2, row: 3 }, { col: 4, row: 3 }, { col: 6, row: 3 }, { col: 8, row: 3 },  // 黑卒
  { col: 1, row: 7 }, { col: 7, row: 7 },  // 红炮
  { col: 0, row: 6 }, { col: 2, row: 6 }, { col: 4, row: 6 }, { col: 6, row: 6 }, { col: 8, row: 6 },  // 红兵
]

// 走法连线
const moveLine = computed(() => {
  if (props.moveIndex <= 0) return null
  const m = props.game.moves[props.moveIndex - 1]
  if (!m) return null
  return { x1: cx(m.from.col), y1: cy(m.from.row), x2: cx(m.to.col), y2: cy(m.to.row) }
})

走法连线是复盘体验的关键细节：一条绿色虚线从起点连到终点，配合金色起点圆圈和绿色终点圆圈，形成「圈→虚线→圈」的完整视觉链路。学员一眼就能看出这一步棋从哪里走到哪里。

---

六、教练智能体：端到端 SDK 封装与延迟加载

棋叙的 AI 教练由魔珐星云端到端具身交互智能 SDK 驱动。服务封装层（avatar.ts）负责 SDK 的动态加载、连接管理、交互调用和资源释放。

SDK 采用延迟加载策略——只有当 CoachPanel 组件挂载且凭证齐全时，才会动态注入 CDN 脚本并构造实例。页面加载后教练自动连接并显示形象，不需要学员手动点击「连接」按钮。

// 来源：src/services/avatar.ts
function loadSDK() {
  if (window.XingyunAvatarAgent) return Promise.resolve()
  if (sdkPromise) return sdkPromise
  sdkPromise = new Promise<void>((resolve, reject) => {
    sdkScript?.remove()
    const script = document.createElement('script')
    sdkScript = script
    script.src = 'https://media.xingyun3d.com/xingyun3d/general/litesdk/xmovAvatar_e2e@latest.js'
    script.async = true
    const timer = setTimeout(() => { script.remove(); reject(new Error('教练 SDK 加载超时，可继续使用界面操作')) }, 15000)
    script.onload = () => { clearTimeout(timer); window.XingyunAvatarAgent ? resolve() : reject(new Error('教练 SDK 不可用')) }
    script.onerror = () => { clearTimeout(timer); reject(new Error('教练 SDK 加载失败，请检查网络')) }
    document.head.append(script)
  }).catch(error => { sdkPromise = undefined; throw error })
  return sdkPromise
}

connectAvatar 函数是连接流程的核心。它使用 generation 令牌机制防止新旧连接的回调交叉污染——每次连接递增 generation 并捕获当前值，所有回调内先校验令牌再执行，不匹配则静默丢弃。同时用 Promise.race 设置 30 秒超时兜底，避免 agent.init() 因服务端拒绝而永久 pending。

教练人设提示词（COACH_ROLE）定义了棋叙教练的行为准则：根据复盘阶段调整讲解深度、评价客观不偏不倚、记住整盘棋进程并自然引用前文关键着法、每次回应控制在 3-5 句。

// 来源：src/services/avatar.ts
export const COACH_ROLE = `你是棋叙，一位经验丰富的中国象棋复盘教练。
## 你的身份
- 名称：棋叙
- 身份：象棋复盘教练，负责讲解每一步的意图、评价与改进建议
- 风格：耐心专业、深入浅出，善于用比喻让棋理通俗易懂

## 你的行为准则
1. 根据当前复盘阶段调整讲解深度：开局侧重布局原理，中局侧重战术组合，残局侧重精确计算
2. 评价要客观——妙手要指出精妙之处，失误要分析原因并给出改进方案
3. 记住整盘棋的进程，在讲解当前步时自然引用前面的关键着法
4. 每次回应控制在 3-5 句，重点突出，不拖沓
5. 不替学员做决定，而是引导他们思考"为什么这步好/不好"`

交互面只有 ask / startASR / stopASR / interrupt / destroy 五个方法。学员提问时，askAvatar 将教练人设、当前棋局上下文和学员问题合并为一次端到端具身交互智能 SDK 调用，平台内部完成大模型推理、语音合成、口型驱动和表情手势生成。业务侧只写了一个函数调用。

---

七、界面布局：暖色木质棋盘的三栏工作台

棋叙的页面布局严格遵循同系列项目的三栏工作台范式：顶栏 + 侧栏 + 主内容区（含右栏教练面板）。

App.vue 是整个项目的布局中枢，管理棋局选择、步数导航、自动播放和教练上下文构建。

// 来源：src/App.vue
// 教练上下文
const context = computed<CoachContext>(() => ({
  gameId: game.value.id,
  currentMove: moveIndex.value,
  totalMoves: game.value.moves.length,
  phase: phase.value,
  lastMove: currentMove.value?.notation ?? '开局',
  lastAnalysis: currentAnalysis.value?.summary ?? '请开始复盘',
}))

// 指标数据
const totalMoves = computed(() => game.value.moves.length)
const brilliantCount = computed(() => Object.values(game.value.analyses).filter(a => a.quality === 'brilliant').length)
const mistakeCount = computed(() => Object.values(game.value.analyses).filter(a => a.quality === 'mistake' || a.quality === 'blunder').length)

左栏（252px）放棋局列表、复盘阶段切换、进度滑块和棋局详情。学员可以在开局/中局/残局之间快速跳转，也可以拖动滑块精确定位到任意一步。

主内容区左侧是棋盘卡片、三格指标（总步数/妙手/失误）和着法分析卡片。着法分析卡片根据当前选中步骤实时切换内容：有分析时显示着法记号、阵营、评价徽章、详细解读和改进建议；无分析时显示引导提示。底部是开局-中局-残局的阶段进度条。

主内容区右侧（400px，大屏 440px）是教练面板和着法记录。CoachPanel 的教练形象占据面板约 85% 的高度——标题、状态、字幕、快捷问题、输入控件都是叠在画面之上的半透明浮层，而不是独立区块纵向堆叠。页面加载后教练自动连接并显示形象。

整体视觉采用暖色木质棋盘主题：底色 #f8f4ec、主色 #5c3d1e（深木色）、强调色 #c4a76c（古铜金）、棋盘底色 #e8d5a8。红方棋子用 #c0392b，黑方棋子用 #2c3e50，在暖色背景上形成清晰的视觉对比。

---

八、一局复盘：从落子到讲解的全链路推演

与其罗列设计决策，不如跟着一步棋走一遍完整链路——看学员点击「上一步」后，数据如何在各模块之间流转。

第 5 步，红方炮五进四。学员点击上一步，moveIndex 从 5 变成 4。ChessBoard 的 computed 重新计算棋盘状态——INITIAL_BOARD 逐步应用前 4 步走法，得到第 4 步结束时的局面。没有状态库的撤销操作，没有数据库查询，一次纯函数调用，同样的 moveIndex 永远返回同样的棋盘。

与此同时，CoachPanel 检测到上下文变化。currentMove、phase、lastAnalysis 三个字段同步更新，教练面板将当前步数、复盘阶段（开局）、上一步着法记号（炮二平五）打包为 JSON，通过 askAvatar 发送给魔珐星云平台。

平台内部随即启动全链路处理：大模型根据完整的 12 步棋谱和教练人设提示词生成讲解——「炮五进四！红炮果断渡河击中卒，直接威胁黑方中路」；TTS 将文字转为语音；口型与表情驱动同步生成。一次 ask 调用，感知、理解、表达在同一条端到端具身交互智能链路中闭环，业务侧只写了一个函数调用。

回调沿原路返回。avatar.ts 中的 generation 令牌校验确保只有最新连接的回调生效，旧连接的回调被静默丢弃。字幕更新到教练面板，说话状态同步切换。棋盘回放和教练讲解形成两个独立循环——回放完全在本地运行，讲解走端到端链路，互不阻塞。即使教练连接失败，学员仍然可以拖动进度条、切换棋局、逐步回放，本地功能永远可用。

这就是端到端具身交互智能的核心价值：不是把 ASR、LLM、TTS 简单拼接，而是围绕一次完整的人机交互形成持续交互循环——感知、理解、表达持续运行、持续调整。魔珐星云将多模态感知、专属智脑、多模态表达、AI 端渲、数字与物理行动连接成一套完整系统，让 AI 通过屏幕和机器人进入真实世界。传统方案需要分别对接各个模块，每一层都需要胶水代码和状态同步；棋叙只需要一个 ask 调用，剩下的全部由星云平台内部完成。

魔珐星云是一套端到端具身交互智能平台，让 AI 通过屏幕和机器人进入真实世界，成为能够感知、理解、表达并行动的智能体。

如果你想亲自体验端到端具身交互智能的魅力，或者基于魔珐星云平台搭建属于自己的具身交互智能体，欢迎访问魔珐星云官网，开启你的具身交互智能实战之旅：https://xingyun3d.com?utm_campaign=daily&utm_source=CSDNwanfen2&utm_medium=&utm_term=&utm_content=