不是农技手册冷冰冰地罗列一串药名，而是一位顾问站在田埂上，指着叶片说「你看这同心轮纹，是早疫病，先摘病叶，再打代森锰锌 600 倍液，七天一次打两回」。现状判断、发生原因、用药方案，用语音和手势当面讲清楚。
云耕就是为这个场景而生的项目：AI 种植顾问。田块档案、病虫害诊断、水肥建议、语音巡田问答，全部在一个页面内完成。背后的端到端具身交互智能由魔珐星云端到端 SDK 驱动——一个构造器、一次 ask 调用，感知、理解、表达在同一条链路中闭环。
一、星云控制台配置：六步完成具身应用全链路
在魔珐星云控制台为云耕创建具身交互智能应用，需要完成六个配置步骤。
1、创建具身应用
在控制台新建端到端具身交互智能应用，获取 App ID 和 App Secret。这两个凭证将填入云耕的顾问面板，用于建立与魔珐星云平台的安全连接。
2、形象配置
为顾问选择或定制一个合适的形象。云耕的场景是田间诊断，顾问人设是「农技推广员出身的老把式」——建议选择一个穿着朴素、皮肤晒得健康的形象，让农户感到「站在田里的不是客服，是懂地的人」。
3、场景配置
配置顾问的渲染场景。云耕的顾问面板高度为 440px（大屏 500px），建议选择户外田间风格的场景背景，让顾问形象在面板中居中呈现，与左侧的田块档案形成呼应。
4、音色配置
为顾问选择合适的声音。云耕的人设是「说话接地气、讲实用」，建议选择带乡土气息、语速沉稳的音色，把「小水勤浇还是蹲苗控水」讲出蹲在田边聊天的味道，而不是播报农情简报。
5、表演配置
配置顾问的手势和表情表演。云耕的核心场景是讲解病虫害——顾问在说「摘病叶带出田外」时应该有干脆利落的手势，说到「这块田有点悬」时表情要凝重。表演配置直接影响农技指导的可信度。
6、服务配置：ASR 与大脑
为当前应用配置语音识别和大模型服务。这一步体现了魔珐星云端到端具身交互智能的可插拔架构——星云平台的模块化设计让语音识别和推理引擎各自独立：ASR 支持 Xmov 自研、豆包、腾讯等多家供应商，大脑支持魔珐自研、豆包、OpenAI 兼容协议等多种接入模式，换供应商不需要重写业务代码。
六步配置完成后，将 App ID 和 App Secret 填入云耕项目的 .env.development.local 文件，启动开发服务器即可看到顾问形象自动出现在右侧面板。
二、产品理念：把农技站搬进每一块田
农技服务的痛点不是没有知识——病虫害图谱、施肥日历、用药手册，网上一搜一大把。痛点是知识不会「看田下菜」：手册说早疫病打代森锰锌 600 倍液，可你的番茄才定植 48 天正处在开花期，下部叶片刚出现轮纹斑，此刻最该做的是摘病叶控湿度还是立即打药？图谱不会回答这个问题，因为它不知道你这块田的墒情、养分和生长阶段。
云耕的回答是：让一位有形象、有声音、有表情的顾问住进你的田块档案。她能听、能想、能说，选中一块田，她先给巡田通报；发现病虫害，她按「是什么、为什么、怎么治」三步拆解；水肥问题，她结合生长阶段讲原理——为什么开花期要暂停高氮肥防徒长，为什么盛瓜期要早晚各浇一次。农户可以用语音或文字随时追问，顾问即时回应，就像田埂上站着一位随叫随到的老把式。
具身表达让「农技指导」从查资料变成面对面。顾问形象在右侧面板实时渲染，讲到「先治虫再治病」时配合手势强调顺序，让防治要点变得可感知。这也让服务对象真正扩展到了「不会打字的人」——田间地头，双手沾泥，开口就问，比任何表单和搜索框都自然。
三、技术架构：一个运行时依赖撑起一座农场
云耕的技术栈极简到只有一个运行时依赖。
// 来源：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 目录共 1022 行代码，包含 6 个 Vue 组件（App.vue 主布局 + AppIcon 图标集 + CropList 田块列表 + CropDetail 诊断面板 + AdvisorPanel 顾问面板 + IntroSection 介绍长页）、1 个服务封装层（avatar.ts）、1 个数据层（crops.ts）、1 个类型定义（types/index.ts），外加 main.ts 入口与 style.css 全局样式。
架构的核心思路是「本地档案 + 云端顾问」双循环：田块档案、分类筛选、诊断卡片、水肥建议全部在本地运行，不依赖网络；AI 顾问的语音讲解走端到端具身交互智能单 SDK 链路，ASR、大模型推理、TTS、口型与表情驱动全部由平台内部完成。两个循环互不阻塞——即使顾问连接失败，六块田的档案浏览与诊断信息照常可用。
四、数据模型：六块田档案与三色健康水位
云耕的田块不是演示卡片，而是一套完整的作物档案体系。
// 来源：src/types/index.ts
/** 作物分类 */
export type CropCategory = 'leafy' | 'fruiting' | 'root' | 'vine'
/** 生长阶段 */
export type GrowthStage = 'seedling' | 'growing' | 'flowering' | 'harvest'
/** 健康状态评级 */
export type HealthLevel = 'healthy' | 'warning' | 'critical'
/** 病虫害类型 */
export interface PestIssue {
/** 病虫名称 */
name: string
/** 症状描述 */
symptom: string
/** 严重程度 */
severity: HealthLevel
/** 防治建议 */
treatment: string
}
/** 作物档案 */
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
}
每块田用三级健康评级标注水位：健康（深绿）、预警（金黄）、危急（红褐）。六块田覆盖四种作物分类（叶菜/果菜/根茎/瓜果）与四个生长阶段（苗期/生长期/开花期/收获期），从定植 12 天的大白菜到进入盛瓜期的黄瓜，形成了完整的农时横截面。
病虫害被建模为独立结构而非字符串，因为同一块田可能同时叠加多个问题——辣椒大田 5 号就是典型：病毒病（危急）与日灼斑（预警）并存，防治顺序上必须先拔除病株、喷吡虫啉治虫源，再补钙肥加遮阳网。这种「先治虫再治病」的顺序约束，正是病虫害需要结构化建模的原因。
字段中最特别的是 guideIntro——每块田预置一段讲解引导词，它是「选中即讲解」体验的触发文案。
// 来源：src/data/crops.ts
{
id: 'pepper',
name: '辣椒 · 大田 5 号',
category: 'fruiting',
stage: 'growing',
daysPlanted: 40,
health: 'critical',
soilMoisture: 45,
nutrientLevel: 'poor',
issues: [
{
name: '病毒病',
symptom: '顶端嫩叶皱缩黄绿相间，植株矮化生长点萎缩',
severity: 'critical',
treatment: '病毒病由蚜虫传播，先拔除重病株带出田外，立即喷施吡虫啉治虫源，再喷盐酸嘧肽霉素缓解症状',
},
{
name: '日灼斑',
symptom: '向阳面果实出现水浸状浅斑后干缩',
severity: 'warning',
treatment: '叶片稀少不能遮果，补充钙肥增厚果皮，高温时段加盖 30% 遮阳网',
},
],
fertilizeAdvice: '病株消耗大且缺素明显，随水冲施腐殖酸水溶肥养根，叶面补喷钙镁合一的螯合微肥',
waterAdvice: '避免旱涝交替诱发病毒病显症，改为小水勤浇，每 3 天一次保持湿度 55% 左右',
guideIntro: '辣椒田的病毒病已经显症，这是当前最紧急的一块田，先治虫再治病是正确顺序。',
},
用药建议全部采用真实农技口径：代森锰锌 600 倍液、苦参碱 1000 倍液、磷酸二氢钾 0.2% 叶面肥、硫酸钾 8 公斤/亩——药名、浓度、频次一次给全，这正是行为准则里要求顾问「给出剂量和时间」的数据底气。
五、顾问智能体：端到端 SDK 封装与延迟加载
云耕的 AI 顾问由魔珐星云端到端具身交互智能 SDK 驱动。服务封装层（avatar.ts）负责 SDK 的动态加载、连接管理、交互调用和资源释放。
SDK 采用延迟加载策略——只有当 AdvisorPanel 组件挂载且凭证齐全时，才会动态注入 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。
顾问人设提示词（ADVISOR_ROLE）定义了云耕的行为准则：回答紧扣当前作物档案、病虫害按三步讲、防治建议给出剂量和时间、危急问题优先。
// 来源：src/services/avatar.ts
export const ADVISOR_ROLE = `你是云耕，一位经验丰富的 AI 种植顾问。
## 你的身份
– 名称：云耕
– 身份：农技推广员出身的种植顾问，负责诊断作物长势、识别病虫害、给出施肥浇水建议
– 风格：像田埂上的老把式，说话接地气、讲实用，病虫害诊断条理清晰
## 你的行为准则
1. 回答紧扣当前选中的作物档案：先说现状判断，再给具体可操作的建议（药名、浓度、频次）
2. 病虫害问题按"是什么、为什么、怎么治"三步讲，防治建议要给出剂量和时间
3. 水肥建议结合生长阶段讲原理，让农户知其然也知其所以然
4. 每次回应控制在 3-5 句，先说最要紧的事（危急的病虫害优先）
5. 遇到档案之外的提问，用通用农技知识回答，并提醒结合当地农技站确认`
连接成功后的第一句话同样经过设计——不是泛泛的「你好」，而是让顾问用不超过三句话向农户问好、自报家门、提示操作方式。农户第一次打开页面，就能明确知道这个面板能做什么。
交互面只有 ask / startASR / stopASR / interrupt / destroy 五个方法。农户提问时，askAvatar 将顾问人设、当前作物档案和农户问题合并为一次端到端具身交互智能 SDK 调用，平台内部完成大模型推理、语音合成、口型驱动和表情手势生成。业务侧只写了一个函数调用。
// 来源：src/services/avatar.ts
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}`)
}
六、交互闭环：选中即讲解的田块联动
云耕的核心体验是一条「选中即讲解」的联动链路：点击左侧任意田块卡片，右侧顾问立即开口，对这块田做一段巡田通报。
这段链路的起点在 App.vue。onSelectCrop 先切换选中状态，再判断顾问是否在线——在线时将当前田块的名称、分类、阶段、天数、健康评级、墒情、养分、病虫害清单打包为 AdvisorContext 上下文，连同田块的讲解引导词一起发送。
// 来源：src/App.vue
function onSelectCrop(crop: Crop) {
if (selectedId.value === crop.id) return
selectedId.value = crop.id
// 选中即讲解：顾问在线时自动播报该田块概况
if (avatarState.status === 'online') {
const context: AdvisorContext = {
crop: crop.name,
category: crop.category,
stage: crop.stage,
daysPlanted: crop.daysPlanted,
health: crop.health,
soilMoisture: crop.soilMoisture,
nutrientLevel: crop.nutrientLevel,
issues: crop.issues.map(issue => issue.name),
}
void askAvatar(
`请结合这块田的档案做个简要巡田通报：${crop.guideIntro}`,
JSON.stringify(context),
).catch(() => { avatarState.error = '巡田通报未发送成功，可在右侧重试' })
}
}
两条链路共享同一个 AdvisorContext 接口，但按场景做了差异化裁剪：CropDetail 面板的「让云耕讲讲这块田」按钮触发 onDiagnose 时，病虫害信息带上完整症状描述（issue.name 括号拼接 symptom），供顾问展开完整诊断；而选中即讲解走精简版，只传病虫害名称——巡田通报要短，专项诊断要全。
平台内部随即启动全链路处理：大模型根据作物档案和顾问人设生成讲解——「这块辣椒田的病毒病已经显症，这是当前最紧急的一块田」；TTS 将文字转为语音；口型与表情驱动同步生成。一次 ask 调用，感知、理解、表达在同一条端到端具身交互智能链路中闭环。
回调沿原路返回。avatar.ts 中的 generation 令牌校验确保只有最新连接的回调生效。字幕更新到顾问面板，说话状态同步切换。田块浏览和顾问讲解形成两个独立循环——档案浏览完全在本地运行，讲解走端到端链路，互不阻塞。即使顾问连接失败，农户仍然可以切换田块、查看诊断卡片和用药方案，本地功能永远可用。
语音链路同样为田间场景做了设计。toggleAvatarVoice 管理麦克风状态，interruptAvatar 支持随时打断——顾问正说着早疫病的用药方案，农户想起「辣椒该不该一起打药」，直接开口打断提问，Barge-in 机制让对话像田埂聊天一样自然，而不是等一段播报结束。
七、界面布局：田园绿三栏工作台与介绍长页
云耕的页面布局遵循同系列项目的三栏工作台范式：顶栏 + 左侧田块列表 + 中部诊断面板 + 右侧顾问面板。
左栏（320px）是「我的田块」：顶部按叶菜/果菜/根茎/瓜果四类筛选，下方是六张田块卡片纵向滚动。每张卡片显示作物名、健康标签、生长阶段、种植天数、待处理病虫害数，以及一条直观的土壤湿度进度条——湿度是农事的第一信号，值不值得浇水，看条即知。
中栏是当前田块的诊断面板：头部为作物名、阶段信息与三色健康徽章；三格环境指标（土壤湿度/养分等级/病虫害数）；病虫害诊断卡片按严重程度着色（危急红、预警金），每张卡片内是症状描述加防治建议；底部两张水肥建议卡片，以及一个「让云耕讲讲这块田」的触发按钮。
右栏（380px）是顾问面板。AdvisorPanel 的顾问形象占据核心区域——未连接时是一枚叶片徽记与「每一块田，都有人照看」的引导文案，上线后顾问形象居中渲染，面板底部保留一行小字标注「魔珐星云 · 端到端具身交互智能」。字幕、文字输入框、语音提问/打断/断开三个操作按钮在在线状态下依次排布，麦克风授权与连接设置走原生 dialog 模态。
// 来源：src/components/AdvisorPanel.vue
<div class="advisor-stage" :class="{ online: avatarState.status === 'online' }">
<div ref="container" class="avatar-container"></div>
<div v-if="avatarState.status !== 'online'" class="advisor-placeholder">
<span class="advisor-symbol"><Icon name="leaf" :size="46" /></span>
<div><strong>每一块田，都有人照看</strong><p>{{ avatarState.status === 'connecting' ? '正在连接顾问…' : '连接云耕，开始田间诊断' }}</p></div>
</div>
<span v-if="avatarState.status === 'online'" class="advisor-name">云耕 · 种植顾问</span>
</div>
工作台下方是介绍长页 IntroSection：关于云耕的导语、四项核心能力（长势诊断/病虫害识别/水肥建议/语音巡田）、从建档到回访的四步闭环、六类适用场景（家庭农场/合作社农技员/阳台种植/农技培训/温室大棚/农业院校），收口在一条深绿渐变的技术底座横幅。长页让第一次打开的访客不必连接顾问，也能下滑看懂这个项目在做什么。
整体视觉采用田园绿主题：底色 #f2f6ea、主色 #3d6b25（田野绿）、健康色 #5c8a4d、危急色 #a8442e。病虫害卡片的警示金与红是页面上仅有的暖色，把注意力留给真正紧急的田块。
八、一块田的完整推演：从点击到开口
设计原则讲完，不如跟着一次真实的农技问答走一遍。
农户点击「辣椒 · 大田 5 号」。CropList 发出 select 事件，App.vue 的 selectedId 切换为 pepper，中栏 CropDetail 随之刷新——健康徽章变红、两张病虫害卡片展开、水肥建议同步切换。与此同时，onSelectCrop 检测到顾问在线，将这块田的档案打包为 JSON 上下文。
上下文与引导词进入 askAvatar，拼装为「人设 + 档案 + 问题」的完整提示词，通过一次 ask 调用发往魔珐星云平台。大模型读到的信息是完整的：定植 40 天、生长期、健康评级危急、湿度 45%、养分匮乏、病毒病与日灼斑并存。它生成的巡田通报围绕 guideIntro 的引导展开——「这块田的病毒病已经显症，当前最紧急，先治虫再治病是正确顺序」。
回答经 TTS 转为语音，顾问开口讲解，口型与表情由平台驱动同步生成，字幕实时回填到顾问面板。农户听完通报，点「语音提问」追问「吡虫啉会不会伤蜂」——startASR 启动，识别结果经 ASR 回调实时上屏，顾问基于上下文即时作答。全程农户没有碰过键盘。
这就是端到端具身交互智能的核心价值：不是把 ASR、LLM、TTS 简单拼接，而是围绕一次完整的人机交互形成持续交互循环——感知、理解、表达持续运行、持续调整。魔珐星云将多模态感知、专属智脑、多模态表达、AI 端渲、数字与物理行动连接成一套完整系统，让 AI 通过屏幕和机器人进入真实世界。传统方案需要分别对接各个模块，每一层都需要胶水代码和状态同步；云耕只需要一个 ask 调用，剩下的全部由星云平台内部完成。
