@xiaofeiqwq/vue

MeowFlow

轻量、自由、可自定义的 AI Agent 全栈开发框架。

Lightweight, flexible and customizable full-stack framework for building AI agents.

中文 | English

中文

简介

MeowFlow 是一套用于开发 AI Agent 的 TypeScript 工具库（monorepo），覆盖从调用模型、加载工具与技能、注入提示词，到流式推送、工具调用展示、思考展示与上下文压缩的完整链路。

它把「协议」放在最中心：前后端之间只通过一份与语言无关的事件协议通信，因此：

• 后端可以用这个包快速搭出 Agent，也可以只用核心引擎，自行对接任意模型服务；
• 前端可以用官方 Vue3 组件开箱即用，也可以只依赖协议自行渲染；
• 其他语言的后端只要遵循同一份 JSON 协议，即可被前端组件直接消费。

设计理念

包结构

架构

┌─────────────────────────────────────────────────────────┐
│  前端 (Vue3 / 任意语言)                                    │
│  useAgent() + <AgentChat/>  ← 只依赖协议包                 │
└───────────────▲─────────────────────────────────────────┘
                │  HTTP + SSE (AgentEvent 流)
┌───────────────┴─────────────────────────────────────────┐
│  @xiaofeiqwq/server   createAgentServer / createAgentHandler│
├─────────────────────────────────────────────────────────┤
│  @xiaofeiqwq/core     Agent 主循环                          │
│    ├─ Provider 适配层 (OpenAI 兼容 / Anthropic / 自定义)   │
│    ├─ ToolRegistry + 挂起恢复 (HITL)                       │
│    ├─ Skills / Prompts / 上下文压缩 / SessionStore         │
├─────────────────────────────────────────────────────────┤
│  @xiaofeiqwq/tools    内置工具实现                            │
└─────────────────────────────────────────────────────────┘
                │
                ▼
        模型服务 (OpenAI / DeepSeek / Qwen / Kimi / Claude ...)

安装

需要 Node.js >= 18。当前版本 0.1.0，已发布到 npm。

# 后端
pnpm add @xiaofeiqwq/core @xiaofeiqwq/tools @xiaofeiqwq/server

# 前端
pnpm add @xiaofeiqwq/vue

# 仅在需要自行实现跨语言后端/前端时
pnpm add @xiaofeiqwq/protocol

快速上手

后端：起一个带内置工具的 Agent 服务

import { Agent, openaiCompat } from '@xiaofeiqwq/core';
import { createDefaultTools } from '@xiaofeiqwq/tools';
import { createAgentServer } from '@xiaofeiqwq/server';

const agent = new Agent({
  provider: openaiCompat({
    model: 'deepseek-chat',
    apiKey: process.env.OPENAI_API_KEY!,
    baseURL: 'https://api.deepseek.com/v1',
  }),
  tools: createDefaultTools({ root: process.cwd() }),
  systemPrompt: '你是一个可以读写文件、执行命令的编码助手。',
  // 单进程自动模式：直接处理挂起请求；不传则进入挂起-恢复模式，等待前端 resume。
  onSuspend: (request) => (request.reason === 'approval' ? false : '（未回答）'),
});

const server = createAgentServer({ agent, port: 3000 });
const info = await server.listen();
console.log(`已启动 ${info.url}`);

curl -N -X POST http://localhost:3000/agent/run \
  -H 'Content-Type: application/json' \
  -d '{"input":"列出当前目录下的文件"}'

前端：一个完整的对话界面

<script setup lang="ts">
import { AgentChat, ensureAgentStyles } from '@xiaofeiqwq/vue';
ensureAgentStyles();
</script>

<template>
  <div style="height: 100vh">
    <AgentChat base-url="http://localhost:3000" title="编码助手" show-usage />
  </div>
</template>

也可以只用 headless 组合式函数，自行渲染：

import { useAgent } from '@xiaofeiqwq/vue';

const agent = useAgent({ baseUrl: 'http://localhost:3000' });
await agent.send('你好');
console.log(agent.messages.value); // 响应式，流式更新

完整 Demo（推荐先跑这个）

examples/fullstack 是仓库里唯一的完整示例：Node 端 SSE 服务 + Vue3 聊天界面，覆盖流式输出、思考过程、内置工具调用、自定义工具调用、挂起提问，以及 mock / 真实模型切换。无需 API Key 即可跑通。

pnpm install
pnpm --filter @xiaofeiqwq/example-fullstack dev
# 打开 http://localhost:5173

协议概览

服务端通过 SSE 推送 AgentEvent，全部事件共享统一元信息：v（协议版本）、runId、sessionId、seq（单调递增）、ts。

细节见 @xiaofeiqwq/protocol。

核心概念

• Provider：模型服务适配器。内置 OpenAI 兼容（覆盖 OpenAI / DeepSeek / 通义千问 / Kimi / 智谱 / Ollama / vLLM）与 Anthropic，也可实现 Provider 接口接入任意服务。
• 工具（Tool）：用 defineTool 声明 name / description / parameters(JSON Schema) / execute，返回值会被归一化为 ToolResult；返回 suspend(...) 即可挂起。
• 挂起-恢复（HITL）：需要用户输入或危险操作审批时，框架把状态持久化到 SessionStore，前端 resume(answer) 后从断点继续。
• 技能（Skill）：Markdown + frontmatter 描述的能力，按 lazy（先给索引按需加载）或 eager（全量注入）注入系统提示词。
• 提示词（Prompt）：支持 {{variable}} 模板与从目录批量加载。
• 上下文压缩：超过阈值时用一次模型调用把早期历史压缩为摘要，保留 system 与最近 N 条消息，切分点对齐 user 消息。

开发

pnpm install         # 安装依赖
pnpm build           # 构建全部包 (ESM + CJS + d.ts)
pnpm test            # 运行单元测试
pnpm typecheck       # 类型检查
pnpm lint            # ESLint
pnpm format          # Prettier

pnpm --filter @xiaofeiqwq/example-fullstack dev   # 运行完整 demo

许可证

MIT

English

Overview

MeowFlow is a TypeScript toolkit (monorepo) for building AI agents. It covers the whole path from calling models, loading tools and skills, and injecting prompts, to streaming output, tool-call rendering, thinking display, and context compression.

It puts the protocol at the center: frontend and backend communicate only through a language-agnostic event protocol. As a result:

• A backend can bootstrap an agent with this package, or use only the core engine and wire up any model service itself.
• A frontend can drop in the official Vue 3 components, or depend on the protocol alone and render however it likes.
• A backend in any other language can be consumed directly by the frontend components as long as it follows the same JSON protocol.

Design principles

Packages

Install

Node.js >= 18 is required.

# Backend
pnpm add @xiaofeiqwq/core @xiaofeiqwq/tools @xiaofeiqwq/server

# Frontend
pnpm add @xiaofeiqwq/vue

# Only when implementing a cross-language backend/frontend yourself
pnpm add @xiaofeiqwq/protocol

Quick start

Backend: an agent server with built-in tools

import { Agent, openaiCompat } from '@xiaofeiqwq/core';
import { createDefaultTools } from '@xiaofeiqwq/tools';
import { createAgentServer } from '@xiaofeiqwq/server';

const agent = new Agent({
  provider: openaiCompat({
    model: 'deepseek-chat',
    apiKey: process.env.OPENAI_API_KEY!,
    baseURL: 'https://api.deepseek.com/v1',
  }),
  tools: createDefaultTools({ root: process.cwd() }),
  systemPrompt: 'You are a coding assistant that can read/write files and run commands.',
  // Single-process auto mode: resolve suspensions inline. Omit it to use suspend/resume mode.
  onSuspend: (request) => (request.reason === 'approval' ? false : '(no answer)'),
});

const server = createAgentServer({ agent, port: 3000 });
const info = await server.listen();
console.log(`Listening on ${info.url}`);

curl -N -X POST http://localhost:3000/agent/run \
  -H 'Content-Type: application/json' \
  -d '{"input":"List the files in the current directory"}'

Frontend: a complete chat UI

<script setup lang="ts">
import { AgentChat, ensureAgentStyles } from '@xiaofeiqwq/vue';
ensureAgentStyles();
</script>

<template>
  <div style="height: 100vh">
    <AgentChat base-url="http://localhost:3000" title="Coding assistant" show-usage />
  </div>
</template>

Or use the headless composable and render yourself:

import { useAgent } from '@xiaofeiqwq/vue';

const agent = useAgent({ baseUrl: 'http://localhost:3000' });
await agent.send('Hello');
console.log(agent.messages.value); // reactive, streaming updates

Full demo (start here)

examples/fullstack is the single complete example in this repo: a Node SSE server plus a Vue 3 chat UI, covering streaming, thinking, built-in tools, custom tools, suspend/resume, and mock / real model switching. It works without an API key.

pnpm install
pnpm --filter @xiaofeiqwq/example-fullstack dev
# open http://localhost:5173

Protocol at a glance

The server pushes AgentEvents over SSE. Every event shares the same meta: v (protocol version), runId, sessionId, seq (monotonic), ts.

See @xiaofeiqwq/protocol for details.

Core concepts

• Provider: a model-service adapter. Ships with OpenAI-compatible (OpenAI / DeepSeek / Qwen / Kimi / Zhipu / Ollama / vLLM) and Anthropic. Implement the Provider interface to plug in anything else.
• Tool: declare name / description / parameters (JSON Schema) / execute with defineTool. Return values are normalized to ToolResult; return suspend(...) to suspend.
• Suspend/resume (HITL): when user input or approval is needed, state is persisted to a SessionStore; the frontend calls resume(answer) to continue from the breakpoint.
• Skill: capabilities described by Markdown + frontmatter, injected into the system prompt in lazy (index only, loaded on demand) or eager (fully inlined) mode.
• Prompt: {{variable}} templates plus batch loading from a directory.
• Context compression: once a threshold is exceeded, early history is summarized by one model call while the system prompt and the most recent N messages are kept, with the split aligned to a user message.

Development

pnpm install         # install dependencies
pnpm build           # build all packages (ESM + CJS + d.ts)
pnpm test            # run unit tests
pnpm typecheck       # type check
pnpm lint            # ESLint
pnpm format          # Prettier

pnpm --filter @xiaofeiqwq/example-fullstack dev   # run the full demo

License

MIT