Moumantai 场景实战：用自托管 AI Agent 运行时把应用装进手机、手表和嵌入式面板

场景速览：你写了一个记账小应用，想在手机上用、在手表上看、在桌面显示器上操作——但每个平台都要重写一套 UI，数据同步更是噩梦。Moumantai（冇問題）是一个开源的自托管 AI Agent 应用运行时，它的解决思路很简单：一次定义应用，然后投射到任意设备的屏幕上。Schema 定义数据，Tool 定义能力，Face 定义界面——Agent 和用户共用同一套工具，代码处理确定性逻辑，LLM 处理模糊判断。

当个人应用遇上多设备困境

个人开发者的典型痛苦：你在电脑上写了一个支出追踪器，想在通勤时用手机添加一笔消费，在手表上瞥一眼月度汇总，在书房的嵌入式面板上看实时图表。每个平台一套 UI 框架，数据同步靠手写 API，Agent 仅能靠自然语言对话——最终放弃维护。

Moumantai 把这个问题反过来解决：Server 拥有全部状态和应用逻辑，客户端只负责渲染和上报用户意图。你用 TypeScript 插件的格式一次性定义应用（Schema + Tool + Face），Agent 后端（Claude 或 Pi）通过同一套工具操作应用，而客户端的形态可以随意切换——PWA、Android、Wear OS、ESP32 嵌入式面板——它们通过同一个类型化的协议与 Server 通信。

架构三要素：Schema、Tool、Face

Moumantai 的架构哲学是「Schema. Tools. Faces.」——非常熟悉的 CRUD 核心，但加入了 Agent 的智能层。

// 一个简单的支出追踪插件的 Schema 定义
import { sqliteTable, text, real, integer } from "drizzle-orm/sqlite-core";

export const expenses = sqliteTable("expenses", {
  id: integer("id").primaryKey({ autoIncrement: true }),
  amount: real("amount").notNull(),
  description: text("description").notNull(),
  category: text("category").notNull(),
  created_at: text("created_at").notNull(),
});

Schema 拥有状态：每个应用有自己的 SQLite 数据库，保存在 Server 的 Moumantai Home 目录中。

Tool 负责变更：defineTool 定义的操作既是用户点击按钮的底层调用，也是 Agent 用来响应自然语言指令的接口。用户说「加 5 块钱买咖啡」和手动点击「添加支出」按钮，最终到达的是同一个 add_expense 工具。

// 用 defineTool 定义支出添加工具
import { defineTool } from "moumantai";
import { expenses } from "../schema.js";

export default defineTool({
  name: "add_expense",
  description: "Add a new expense entry",
  parameters: {
    amount: { type: "number", required: true, description: "Amount in dollars" },
    description: { type: "string", required: true, description: "What was purchased" },
    category: { type: "string", description: "Expense category (e.g. food, transport)" },
  },
  execute: async ({ params, db }) => {
    const rows = db.insert(expenses).values({
      amount: params.amount as number,
      description: params.description as string,
      category: (params.category as string) ?? "other",
      date: new Date().toISOString(),
    }).returning().all();
    return { result: { success: true, id: rows[0]!.id } };
  },
});

Face 负责展示：每种设备看到同一应用的不同外观。手机上的支出列表是全功能 UI，手表上只显示月度汇总的数字，嵌入式面板展示实时图表——Server 端的呈现分辨率决定每个设备看到什么。

这种设计的最大好处：Agent 和用户操作同一套工具，但谁也绕不开工具的验证规则。Agent 可以替你添加消费、查询汇总、甚至生成图表——但修改数据、删除记录等操作同样受 TypeScript 的类型检查和参数约束。Agent 是辅助，不是取代。

快速上手：5 分钟跑起第一个应用

Moumantai 的安装流程优化得很好，从零到跑起大约 5 分钟：

git clone --recurse-submodules https://github.com/xiang-deng/moumantai.git
cd moumantai

mise install && uv sync
npm install

task server:init

task server:dev    # 终端 A：WebSocket 在 ws://localhost:3000
task pwa:dev       # 终端 B：Vite 在 http://localhost:5174

初始化向导会询问你三件事：Moumantai Home 目录位置（默认 ~/.moumantai/，所有数据存在这里）、LLM 凭据（Claude OAuth token 或 API key）、以及是否启用配对验证。

配对是默认开启的安全机制——只有经过你授权的设备才能连接：

task server:cli -- device pair

approve ABC123

配对成功后，直接在聊天框输入「add 5 dollars for coffee」——内置的 spend-tracker 插件应用会通过 Agent 识别意图，调用 add_expense 工具，然后在 Face 上实时更新汇总。

用 Agent 创建和编辑应用（Dev Mode）

Moumantai 最有意思的特性是 Dev Mode——你可以在 PWA 中用自然语言让 Agent 创建或修改应用，像一个「实时应用编辑器」。

export MOUMANTAI_DEV_MODE=1

Dev Mode 的工作流是 draft → validate → preview → promote：

1. Draft：在 PWA 的 Dev Tab 中描述你要的应用（「创建一个待办事项应用，带截止日期和优先级」）
2. Validate：Agent 写好的 Drizzle Schema、Tool 和 Face 在一个隔离的沙箱中编译通过后才能进入下一步
3. Preview：在配对的设备上预览效果，Agent 不会修改已上线的应用数据
4. Promote：你确认后，Agent 的修改才推送到正式环境

这个流程保证了 Agent 的创作不会意外破坏现有的应用和数据。开发者也可以跳过 Agent，直接在 apps/ 目录下编辑 TypeScript 文件——沿用相同的 Schema、Tool、Face 规则。

多设备覆盖：从手表到嵌入式面板

Moumantai 目前支持四种客户端，每种都用最适合该平台的 UI 框架渲染相同的内容：

所有客户端通过同一个类型化的 wire protocol 与 Server 通信——Protocol Buffer 定义的消息格式自动生成为 TypeScript、Kotlin 和 C 的绑定代码。这意味着：一个应用不需要为每个客户端写适配层。

远程设备通过 Tailscale 安全隧道访问：

task server:dev

task pwa:serve:tailscale TAILSCALE_HOST=..ts.net

tailscale serve --bg --https=443 http://localhost:4173   # PWA
tailscale serve --bg --https=8443 http://localhost:3000  # WebSocket

手机、手表和 ESP32 面板连接后，通过 task server:cli -- device pair 同样完成配对。

什么时候适合用 Moumantai

Moumantai 的定位不是替代成熟的 Web 框架或 SaaS 平台。它的适用场景有清晰的边界：

适合：

• 个人或小团队的内部工具（记账、待办、家居仪表盘）
• 需要跨多个屏幕类型展示数据的场景
• 想要让 Agent 帮忙创建和维护应用但不希望数据上云
• 对「代码处理确定逻辑，Agent 处理模糊需求」这个模式感兴趣的技术探索

不适合：

• 高并发生产级应用（目前没有集群模式）
• 需要复杂用户权限管理的多租户场景
• 不想自托管基础设施的用户

Agent 后端的灵活选择

Moumantai 默认使用 Claude（Claude Agent SDK + Anthropic Claude 模型），但支持通过 Pi Coding Agent 切换到更多供应商：

在 .moumantai/config.json 中切换后端即可。凭据存储在 Server 上，永远不会发送给客户端或插件应用——设备只通过协议与 Server 通信，不直接接触 LLM 凭据。

总结

Moumantai 是一个大胆的尝试：把个人应用的开发范式从「每个平台分别开发」转变为「一次定义，处处投射」。Server 持有状态和执行权，Agent 通过同一套工具操作应用，客户端只负责渲染——这种架构让个人应用开发的门槛降到了写 TypeScript 插件的粒度。

对于技术探索者来说，Moumantai 的价值不在于功能完整度，而在于它展示了 AI Agent 应用的个人化方向：代码处理可靠的部分，Agent 处理灵活的部分，用户始终握有最终决定权。如果你想体验这种全新的应用开发模式，克隆仓库跑一个示例，或者在 Dev Mode 下用自然语言创建一个应用试试——你会对「应用开发」有全新的理解。

相关链接： – Moumantai GitHub 仓库 (MIT) – DeepWiki 文档 – Quick Start 指南