云耕用数字人农技顾问进田：一个运行时依赖的种植助手

农户真正需要的，是一个能把话说清楚的农技顾问

在田里干活的人，缺的常常不是知识。病虫害图谱、施肥日历、用药手册，网上一搜就有。麻烦在于，这些现成的东西不会看地说话。

手册上写“早疫病用代森锰锌 600 倍液”，可你的番茄定植才 48 天，正在开花，下部叶片刚冒出轮纹斑。这时候是马上打药，还是先摘病叶降湿度？通用图谱答不了，它不清楚你这块地的墒情、养分和生长阶段。

云耕（YunGeng）想接的正是这个活。它并非普通的问答机器人，而是基于魔珐星云端到端具身交互智能 SDK 搭出来的 AI 种植顾问。思路很直接：让一个有形象、有声音、有表情的“老把式”住进你的田块档案。

农户选中一块田，这位顾问先做巡田通报；碰到病虫害，她按“是什么、为什么、怎么治”分三步讲；遇上水肥问题，她结合生长阶段说原理。这些操作靠语音和手势完成。双手沾泥、打字不便的农户，张口就问，比什么搜索框都顺手。

架构极简：一个运行时依赖就撑起整座农场

翻翻云耕的代码仓库，技术栈简单得有点反直觉。整个项目只有 Vue 3.5.18 这一个运行时依赖。

{
  "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目录只有约 1000 行代码，结构也清楚：

• 6 个 Vue 组件：主布局、图标集、田块列表、诊断面板、顾问面板和介绍页。
• 1 个服务封装层 (avatar.ts），管 SDK 的动态加载、连接管理和交互调用。
• 1 个数据层 (crops.ts），负责模拟田块档案数据。
• 1 个类型定义 (types/index.ts），用来定义数据结构。

这套架构走的是“本地档案 + 云端顾问”双循环。田块档案浏览、分类筛选、诊断卡片展示都在本地跑，不靠网络；AI 顾问的语音讲解和表情驱动则走端到端具身交互链路。两边互不阻塞——顾问连不上，农户照样能顺畅翻看六块田的档案和诊断信息，基础功能不断档。

数据模型：结构化了，才谈得上智能

云耕里的“田块”不是几张好看的演示卡片，而是一整套作物档案体系。AI 顾问要给出靠谱建议，数据模型就得足够结构化。

export interface Crop {
  id: string
  name: string
  category: CropCategory // 叶菜/果菜/根茎/瓜果
  stage: GrowthStage     // 苗期/生长期/开花期/收获期
  daysPlanted: number    // 种植天数
  health: HealthLevel    // 健康/预警/危急
  soilMoisture: number   // 土壤湿度百分比
  nutrientLevel: 'rich' | 'normal' | 'poor'
  issues: PestIssue[]    // 当前病虫害列表
  fertilizeAdvice: string
  waterAdvice: string
  guideIntro: string     // 讲解引导词
}

其中，issues病虫害被建成独立结构，而不是塞成一个字符串，这点很关键。真实场景里，同一块田经常同时叠着好几个问题。

拿“辣椒·大田 5 号”来说，它可能同时有“病毒病”（危急）和“日灼斑”（预警）。防治次序上，得先拔掉病株、喷吡虫啉治虫源，再补钙肥加遮阳网。数据如果只是扁平文本，AI 很难捋清“先治虫再治病”这层逻辑约束。结构化之后，顾问才能判准优先级，给出合乎农艺逻辑的建议。

另外，每个田块都预置了guideIntro字段。这是“选中即讲解”的触发文案，比如：“辣椒田的病毒病已经显症，这是当前最紧急的一块田，先治虫再治病是正确顺序。”

顾问智能体：端到端 SDK 封装的门道

驱动云耕 AI 顾问的，是魔珐星云端到端具身交互智能 SDK。首屏加载速度怎么提？SDK 走的是延迟加载：顾问面板组件挂载、凭证也齐了，CDN 脚本才会动态注入。

function loadSDK() {
  if (window.XingyunAvatarAgent) return Promise.resolve()
  if (sdkPromise) return sdkPromise
  sdkPromise = new Promise<void>((resolve, reject) => {
    const script = document.createElement('script')
    script.src = 'https://media.xingyun3d.com/.../xmovAvatar_e2e@latest.js'
    script.async = true
    // 设置超时兜底，避免永久 pending
    const timer = setTimeout(() => { 
      script.remove(); 
      reject(new Error('顾问 SDK 加载超时')) 
    }, 15000)
    script.onload = () => { 
      clearTimeout(timer); 
      window.XingyunAvatarAgent ? resolve() : reject(new Error('SDK 不可用')) 
    }
    document.head.append(script)
  })
  return sdkPromise
}

连接管理这块，代码里用的是generation令牌机制。每建立一次连接，generation 就递增一次并捕获当前值；所有回调进来先校验令牌，对不上就静默丢弃。网络一波动，或者切换太快，旧连接的回调想污染新状态，就被这道校验挡住了。

顾问的人设靠ADVISOR_ROLE提示词做了严格限定：

1. 身份：农技推广员出身，做种植顾问，说话接底气。
2. 行为准则：回答紧扣当前作物档案；病虫害按“现状-原因-方案”三步讲；具体药名、浓度、频次必须给出；危急问题排在最前处理。
3. 交互限制：一次回应控制在 3-5 句，别长篇大论。

业务侧要跟顾问交互，其实很简单，调一下askAvatar 函数：

export async function askAvatar(text: string, context: string) {
  if (!agent || avatarState.status !== 'online') return
  avatarState.subtitle = text
  // 将人设、档案上下文和用户问题合并发送
  await agent.ask(`${ADVISOR_ROLE}\n当前作物档案：${context}\n农户问题：${text}`)
}

大模型推理、TTS 语音合成、口型驱动、表情手势生成，平台内部全包了。开发者这边看到的，就是一次透明的端到端调用。

交互闭环：选中即讲解的顺滑体验

云耕交互上最亮眼的是“选中即讲解”。农户在左侧列表点中任意一张田块卡片，右侧顾问马上开口，对这块田播一段简短的巡田通报。

这条链路能跑起来，靠的是App.vue 中的 onSelectCrop 函数：

function onSelectCrop(crop: Crop) {
  selectedId.value = crop.id
  if (avatarState.status === 'online') {
    const context: AdvisorContext = {
      crop: crop.name,
      category: crop.category,
      stage: crop.stage,
      // ...其他关键指标
      issues: crop.issues.map(issue => issue.name),
    }
    // 发送引导词和上下文，触发顾问自动播报
    void askAvatar(
      `请结合这块田的档案做个简要巡田通报：${crop.guideIntro}`,
      JSON.stringify(context),
    )
  }
}

这里分得很细：点“详细诊断”按钮，传过去的是带完整症状描述的上下文，顾问可以展开细讲；“选中即讲解”只传病虫害名称这类精简信息，通报因此短小精悍，不打断用户浏览。

语音交互也照顾到了田间的特殊情况。系统支持 Barge-in（打断）：顾问正讲着早疫病用药方案，农户突然想起“辣椒该不该一起打药”，张口就能打断。SDK 立刻停掉当前播报，识别新指令后即时作答。这么一来，交互更像在田埂上聊天，而不是听录音机放。

界面布局：田园绿三栏工作台

云耕的界面走实用路线，三栏工作台布局，主色调是田园绿（#3d6b25），看着亲近自然。

• 左栏（320px）：“我的田块”。顶部有叶菜、果菜等分类筛选，下面排着田块卡片列表。每张卡片直接显示健康标签、生长阶段、种植天数，还有一条土壤湿度进度条——湿度是农事的第一信号，该不该浇水，看条就清楚。
• 中栏：诊断面板。头部是作物信息和绿/黄/红三色健康徽章。中间是病虫害诊断卡片，按严重程度着色，危急标红，预警标金，就是要抢注意力。底部放着水肥建议卡片，以及“让云耕讲讲这块田”的触发按钮。
• 右栏（380px）：顾问面板。没连接时显示叶片徽记和引导文案；连上以后，顾问形象居中渲染，底部留着字幕、输入框和语音控制按钮。

页面下方另有一个介绍长页，给首次到访的人展示云耕的核心能力：长势诊断、病虫害识别、水肥建议、语音巡田。不连接顾问，用户也能很快明白这产品值在哪。

结语：从工具到伙伴

云耕的价值，不在秀了多少炫酷的 3D 技术，而在于它借端到端具身智能，把农技服务的使用门槛压了下来。

过去做这类方案，ASR、LLM、TTS 和数字人渲染引擎得由开发者一层层分别对接，层与层之间的状态同步都要自己写胶水代码。魔珐星云在云耕里把这些模块收拢成一套完整系统，开发者只管业务逻辑和数据模型，感知、理解、表达这一圈由平台内部跑完。

落到农户这边，变化就是从盯着冷冰冰的文字列表，变成身边有个随叫随到、懂技术又能聊上几句的田间伙伴。AI 指着叶片说出“你看这同心轮纹，是早疫病”的时候，技术才算真正碰着了土地。