企业官网建设流程全解析

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手

这篇技术指南以 Project AIRI（moeru-ai/airi）2025 年 5 月 16 日发布的开发日志（DevLog）为蓝本，系统拆解 v0.5.0 版本背后的关键技术进展：Airi Card 角色卡协议与编辑器、基于 llama-flow 与 sherpa-onnx 的实时语音管线、Telegram 机器人优化、WebGPU 驱动的背景去除工具，以及用前端框架编写 LLM 提示词的 Velin 项目。读完本文，你将理解这些功能在仓库中的真实实现位置与调用关系，并能直接定位源码深入研读。

为什么这篇 DevLog 值得细读

Project AIRI 是一款自托管的 Grok 风格 AI 伴侣与赛博生命灵魂容器，追求接近 Neuro-sama 的实时语音交互能力，覆盖 Web / macOS / Windows 等多个平台。这篇发布于 v0.5.0 发布节点的开发日志，总结了社区维护者与核心作者在过去数周的主要工作，横跨角色扮演协议、端侧推理、语音识别、消息机器人与提示词工程等多个技术方向。其中多数成果至今仍保留在仓库中，是理解 AIRI 架构演进的重要时间锚点。

日志还串联了两篇更早的阶段性记录，可作为背景阅读：v0.4.0 UI 更新 与 v0.4.0 发布 & 记忆功能介绍。

角色卡（Airi Card）支持：把社区协议变成一等公民

什么是角色卡

角色卡（Character Card）是本地优先聊天应用（如 SillyTavern、RisuAI）与在线角色扮演服务（如 JanitorAI）中定义角色的标准文件格式：一个包含角色背景、性格、开场白与扮演所需上下文的数据文件，通过它可以在不同应用间迁移、分享同一个 LLM 驱动的角色。日志中同时提醒，角色卡并非存储角色扮演上下文的唯一方式，Lorebook（故事书）承担着另一部分关键作用，二者常配合使用。

在 AIRI 中，角色卡能力以Airi Card的形式落地，由社区维护者主导完成。要使用它，只需导航到设置页面（Web 端位于应用右上角，桌面应用则悬停齿轮图标），点击Airi Card按钮进入编辑器界面，即可上传、编辑角色卡进行人格定制。

仓库中的 CCv3 协议实现

角色卡的底层协议实现在@proj-airi/ccc包中（packages/ccc），它负责 Character Card V3（CCv3）JSON 信封的解析、校验与兼容性分类。核心入口是 parseCharacterCardV3：

import { parseCharacterCardV3 } from '@proj-airi/ccc' const { card, compatibility } = parseCharacterCardV3(jsonText) const characterName = card.data.name const versionSupport = compatibility // 'older' | 'current' | 'newer'

从源码结构看，该实现有三个值得注意的设计：

• 兼容性分级：通过resolveCompatibility将spec_version与当前版本（3）比较，返回older/current/newer三档，调用方可以据此决定是否向用户发出警告，而非直接拒绝导入旧卡或新卡（characterCardV3.ts#L203-L210）。
• 未知字段保留：所有 schema 均使用objectWithRest(..., unknown())结构，未来 CCv3 新增字段不会被静默丢弃，保证"读取一张更新的卡、再原样导出"时数据不丢失。
• 明确的错误边界：无法解析的 JSON 或无效结构会抛出InvalidCharacterCardError，并可通过isInvalidCharacterCardError与存储层、文件系统错误区分开（characterCardV3.ts#L150-L164）。

CCv3 信封包含spec: 'chara_card_v3'、spec_version与data三大部分，data中定义了name、personality、scenario、first_mes、mes_example、alternate_greetings、character_book、system_prompt、post_history_instructions、tags、assets、nickname、source等字段。AIRI 的应用层模型则收敛在 packages/ccc/src/define/card.ts，它把协议字段映射为Card类型（含greetings、characterBook、notes、extensions等语义化命名），并提供defineCard/defineCardFn帮助函数。

编辑器与展示组件

Airi Card 的完整编辑与导入导出流程位于 packages/stage-pages/src/pages/settings/airi-card：index.vue负责卡片列表、搜索、排序与导入（通过importAiriCardPackage处理卡片包文件），配套有CardDetailDialog.vue、CardEditor.vue、CardListItem.vue等组件，以及new.vue/edit.vue页面。导入失败时，会按错误码区分"缺少文件"与"文件无效"两种提示。

角色卡展示则被做成一个纯 CSS + JavaScript 驱动的 UI 组件 packages/stage-ui/src/components/menu/character-card.vue：卡片以 CSS 变量（--primary-rgb、--text-shadow-size、--divider-opacity等）控制全套配色与尺寸，利用culori做颜色亮度过滤，并用径向渐变、遮罩（mask-image）生成点阵网格背景与封面渐变，右侧还渲染随机生成的条形码装饰。整个布局不依赖画布计算，任何前端环境都能直接复刻。该组件同样以 Story 形式存在于 UI 组件库中，可交互预览。

耳朵在听，嘴巴在说：实时语音管线的重构

从"手动排队"到类型安全的流式处理

日志指出，截至 4 月中旬，AIRI 中 VAD（语音激活检测）、ASR（自动语音识别）与 TTS（文本转语音）的串联"非常复杂且难以使用"。在旧实现中，开发者需要手动包装队列结构，再借助 Vue 响应式驱动的工作流系统把大量异步任务链接起来。作者与 @himself65 合作，将目光投向来自 Llama Index 的事件驱动库llama-flow——它专门用于处理基于事件的 LLM 流式令牌流与音频字节，体积小且类型安全，显著降低了语音管线的编排成本。

300~500 行代码的 WebAI 实时语音聊天示例

为证明这套方案的可行性，作者发布了WebAI 实时语音聊天示例：在浏览器中用约 300～500 行 TypeScript 即可复现 ChatGPT 语音聊天系统。示例被刻意拆解为四个可独立学习的小型应用，按依赖递进：

1. VAD：仅做语音激活检测；
2. VAD + ASR：检测到语音后转写为文本；
3. VAD + ASR + LLM 聊天：接入大模型完成对话；
4. VAD + ASR + LLM 聊天 + TTS：最终形成完整的语音对话闭环。

这种阶梯式演示让开发者可以逐层理解"每个环节负责什么、数据如何在模块间流动"。

sherpa-onnx 与 xsAI 🤗 Transformers.js

探索过程中团队发现 k2-fsa/sherpa-onnx 仓库——它支持跨 macOS、Windows、Linux、Android、iOS 等平台、覆盖 12 种语言的 18 种语音处理任务。在此基础上，@luoling 补充了一个 sherpa-onnx 驱动的"VAD + ASR + LLM 聊天 + TTS"完整演示。

语音演示的沉淀直接催生了新副项目xsAI 🤗 Transformers.js：它简化了 WebGPU 驱动的模型推理调用，用 workers 提供服务，同时保持与既有 xsAI 项目的 API 兼容性，并支持 Node.js。这意味着可以通过一个开关在云端 LLM / 语音提供商与本地 WebGPU 模型之间自由切换，甚至能在浏览器中实验简单的 RAG 与重排序系统，而无需任何后端服务器。安装方式非常轻量：

npm install xsai-transformers

这一方向的后续演进在仓库中留下了明确的源码印记：本地语音识别被实现为sherpaw-transcription提供者（packages/provider-inference/src/providers/local/sherpaw-transcription/index.ts），它通过createSherpawTranscriptionDefinition注册为speech-to-text/asr/stt/streaming-transcription任务提供者，无需 API Key，requiresCredentials: false，可用性由"存在模型资源 + Worker + WebAssembly"共同决定。模型目录（models.ts）中固定了三种量化模型：中英双语 Paraformer、中英双语 X-ASR 480ms INT8、以及支持阿拉伯语/英语/印尼语/日语/俄语/泰语/越南语/中文八语言的 Zipformer，并提供按语言过滤与"桌面端优先 X-ASR、移动端优先 Paraformer"的默认选择逻辑，模型产物按sherpaw/{model.id}/{revision}路径缓存。

Telegram 机器人：动画贴纸与提示词瘦身

日志同步介绍了 AIRI 的 Telegram 机器人进展：

• 动画贴纸理解：机器人新增了对动画贴纸的处理能力，由ffmpeg驱动，现在可以读取并理解用户发送的动画贴纸甚至视频内容；
• 系统提示词大幅瘦身：通过重构，系统提示词大小减少了超过80%的令牌用量，显著降低每次请求的上下文开销。

这两点在仓库中均有对应实现：动画贴纸与普通贴纸的 LLM 处理逻辑位于 integrations/telegram-bot/src/llm/animated-sticker.ts 与 integrations/telegram-bot/src/llm/sticker.ts；而瘦身后的系统提示词以 Velin 模板形式存在——integrations/telegram-bot/src/prompts/system-ticking-v1.velin.md 是一个.velin.md文件，在<script setup>中声明 props（如responseLanguage），并定义list_chats、send_message、send_sticker、list_stickers、read_unread_messages、continue、break、sleep等一系列动作契约，供 LLM 以结构化方式驱动机器人行为。

WebGPU 驱动的背景去除工具

为给角色卡准备图像素材，日志提到团队基于 Xenova 的既有工作，自制了一个 WebGPU 驱动的背景去除器，并集成到 AIRI 的 devtools 页面中。

对应实现位于 apps/stage-web/src/pages/devtools/background-removal.vue：页面通过createBackgroundRemovalAdapter()创建适配器，将 Xenova/modnet 的推理卸载到 Web Worker执行，避免阻塞主线程。页面启动时adapter.load()会自动检测 WebGPU，不可用时回退到 WASM。处理流程上，图片先被绘制到 canvas 取得ImageData，再交由 worker 中的processImage推理，最后把结果putImageData回 canvas 并导出 PNG。界面支持多图上传、批量处理、进度百分比、悬停预览与批量下载，文件名会追加-background-removed后缀。

语音提供商扩展：xsAI & unSpeech

语音能力方面，v0.5.0 新增了对阿里云模型工作室与火山引擎作为语音提供商的支持。这意味着 AIRI 的 TTS/语音合成链路可以接入这两家国内云厂商的服务，与本地 WebGPU 模型、其他在线提供商并存，供用户按需选择。这一扩展方向与上述 sherpaw 本地识别、云端语音提供商共同构成 AIRI"既可本地、又可云端"的语音服务矩阵。

UI 组件库的稳步迭代

日志还记录了 UI 层面的多处改进：

• 新增教程步骤器（Stepper）、**文件上传（InputFile）与文本区域（Textarea）**组件，统一进入 UI 组件库的 Story 目录；
• 修复了若干颜色问题，并完成排版（Typography）改进。

这些组件与 Story 均可在仓库的 packages/stage-ui 中找到对应源码，组件库以 Story（histoire）形式提供交互式预览与回归基准。

Velin：用 Vue / React 编写 LLM 提示词

动机：提示词也是可编程的

在完成角色卡支持后，团队发现"模板变量渲染与组件复用"体验不佳：如果有一个可复用的组件提示词库，能够跨代理、跨角色扮演应用甚至跨角色卡使用，那么设定"中世纪奇幻背景"时只需专注于新角色的写作，世界设定可以像组件一样被包裹在外层；甚至可以在夜晚到来时，通过if/if-else控制流注入特殊提示词。更进一步，若用 Vue SFC 或 React JSX 编写模板，就能解析模板并识别 props，在编写提示词时渲染一个用于调试与测试的表单面板，甚至把整个 Lorebook 与角色卡在单一交互页面中可视化。

用 npm 包使用 Velin

由此诞生了Velin——一个用前端框架（Vue / React）编写 LLM 提示词的工具，目标是将此模式扩展到更多框架与平台。它提供了编辑器与实时渲染的在线游乐场，并享受 npm 包生态（可以直接 import 任意包）。同时提供编程式 API，支持 Markdown 格式（MDX 处于开发中，MDC 已支持）：

npm install @velin-dev/core

AIRI 仓库自身的实践也验证了这一模式：上述 Telegram 机器人的系统提示词正是以.velin.md形式维护（integrations/telegram-bot/src/prompts/system-ticking-v1.velin.md），在<script setup>中声明 props 并用模板语法组织动作定义，是"用组件思维管理提示词"的活样例。

v0.5.0 里程碑回顾

由于这篇 DevLog 同时宣告 v0.5.0 发布，日志梳理了该版本的完整里程碑（Roadmap v0.5 共完成 92 个任务）：

• UI：加载屏幕与教程模块；多个错误修复，包括加载状态与 Firefox 兼容性问题；
• 身体：动作嵌入与基于语义的 RAG（在私有仓库 moeru-ai/motion-gen 中开发）；使用嵌入提供商与 DuckDB WASM 的向量存储与检索；
• 输入：修复 Discord 语音频道的语音识别；
• 输出：实验性唱歌功能；
• 工程：跨项目共享 UnoCSS 配置；模型目录（moeru-ai/inventory）；跨组织的包重组；
• 资源：新的角色资源（贴纸、UI 元素、VTuber 标志）；语音线选择功能；角色 "Me" 与 "ReLU" 的 Live2D 建模；
• 社区：日语 README 与全面的文档。

其中"使用嵌入提供商与 DuckDB WASM 的向量存储和检索"在仓库中同样留有实现——@proj-airi/drizzle-duckdb-wasm与@proj-airi/duckdb-wasm两个包（packages/drizzle-duckdb-wasm、packages/duckdb-wasm）即为浏览器内向量存储与检索能力的基础设施。

结语

v0.5.0 是 Project AIRI 从"能对话的 UI 重构"迈向"完整赛博生命体验"的关键一跳：角色卡把社区角色扮演协议融入产品成为一等公民，端侧语音管线以类型安全的方式重构了 VAD/ASR/TTS 的编排，sherpa-onnx 与 xsAI 🤗 Transformers.js 让"本地 WebGPU + 云端提供商"的混合推理成为现实，而 Velin 则开创了"用组件思维写提示词"的新范式。如果你正在研究角色卡协议解析、浏览器端语音管线或提示词工程化，上述源码路径都是可以直接下钻的切入点。

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手