小刀智能体

基于 Nuxt 4 构建的现代化、AI 原生的知识管理与内容发布系统。将多模型 AI 辅助、富内容创作、多格式笔记与可插拔工具系统整合到单个可自托管的 TypeScript 应用中。

项目概览

Xiaodao Agent 是一个可自主托管、AI 原生的内容与知识平台。它统一了完整的发布系统（文章、页面、评论、媒体）、多格式笔记本（Markdown、思维导图、流程图、白板、电子表格），以及一个智能体层：该层可通过自然语言规划任务、调用工具并操作站点自身的数据。

整个项目基于 Nuxt 4 与 TypeScript 构建：一套代码库同时支撑服务端渲染的前端与 Nitro API 后端，并通过 shared/ 层共享类型、Schema 与工具函数。多个 AI 提供商（DeepSeek、OpenAI、Anthropic、Google、Alibaba、Moonshot、MiniMax、Zai 以及任何 OpenAI 兼容网关）经由 Vercel AI SDK 接入，支持按用户与按会话的模型覆盖、流式响应、工具循环与自动上下文压缩。

亮点

AI 原生而非“外挂”：智能体、工具调用、上下文总结与内容辅助都是一等公民模块。
TypeScript 全栈：跨客户端、服务端与数据库操作共享类型与 Zod 校验 Schema。
可自主托管、数据主权自有：数据不会离开你的 MySQL 数据库；你完全掌控整个部署。
可插拔、易扩展：主题布局与 AI 工具自动注册；运行时工具可在管理后台配置，无需改代码。

主要特性

AI 智能

多提供商支持：DeepSeek、OpenAI（GPT 系列）、Anthropic（Claude）、Google（Gemini）、Alibaba（Qwen）、Moonshot（Kimi）、MiniMax、Zai（Z.ai）以及 OpenAI 兼容网关。
WebSocket 实时流式传输：聊天作为后台任务执行，并通过 WebSocket 推送细粒度的 part 事件（upsert / delta / remove / snapshot）以及按会话的繁忙状态，使每个打开的标签页保持同步（详见下文“生产部署”）。
流式智能体对话：支持多轮上下文、工具循环（最多 50 步）与推理（reasoning）控制。
自动上下文压缩：长会话在触及 token 窗口前会被总结为结构化状态快照。
会话与文章标题/摘要生成。
内容辅助：由 AI 驱动的文章创作、润色与摘要接口。
敏感词过滤：在消息抵达模型之前进行过滤。

内容管理

文章、页面、附件、笔记、待办、链接、密码保护与共享内容：全部统一到由枚举 type 驱动的 contents 表中。
丰富的状态生命周期：publish、draft、pending、trash。
细粒度可见性：public、private、hidden、password。
层级化分类、自由标签、目录（catalog）、话题（topic）、书签、收藏箱（vault）与文件夹：统一建模为多态 metas 表。
基于 markdown-it 的 Markdown 创作，并通过 highlight.js 实现语法高亮。
查看、评论与点赞计数；自动生成缩略图；WebP 转换。

笔记本与知识工具

Markdown 笔记、Notion 风格的块级富文本编辑器（悬停/固定工具栏、/ 命令、链接气泡、代码块），以及 KaTeX 数学公式、思维导图、流程图、白板与电子表格（由 exceljs 驱动）。
用于组织知识的文件夹层级与目录。
每篇笔记的个人、共享与公开可见性控制。
支持自动元数据提取的外部链接书签。
带状态跟踪与 AI 辅助规划的待办事项。
文档导入：可从 .docx（mammoth）、PDF（unpdf）以及邮件文件（.eml/.msg，经 mailparser + cfb）提取文本。

媒体中心

带类型与大小策略的批量文件上传。
由 sharp 提供的图片实时处理：压缩、水印、缩略图。
WebP 转换与头像生成路由（!avatar、!thumbnail、!webp）。
可选通过 WebDAV 的远程存储。

安全与访问

基于 JWT 的会话 Cookie 与 Bearer Token API 访问，在 server/middleware/auth.ts 中校验。
bcryptjs 密码哈希，盐值可配置。
带过期与吊销能力的按用户 API Token。
基于角色的访问：admin、writer、commenter、reader、user、deleted。
通过飞书与 GitHub 实现第三方登录。
通过 ip2region 实现的 IP 地理位置归属，用于评论来源标注。

平台与 SEO

以 SSR 优先的 Nuxt 4 渲染，并结合静态资源压缩（gzip + brotli）。
可配置的文章、页面、附件、分类、标签、作者、搜索与分享链接短链接（permalink）。
自动生成 sitemap.xml、RSS 2.0 与 Atom 订阅源（按分类、按标签、按作者）。
面向传统博客客户端互操作的 XML-RPC 与 Pingback/Trackback 接口。
使用 @nuxtjs/i18n 国际化（内置 zh-CN 与 en-US，可扩展）。
主题系统，支持自动发现的布局与样式表。

自动化

内置 cron 调度器（node-cron），每 10 分钟运行一次，用于：
- 定时数据库备份（本地归档或 WebDAV 上传）。
- 按用户配额与保留策略清理过期附件。
用于优雅停机的维护模式中间件。

技术栈

前端

领域	库
框架	Nuxt 4.4、Vue 3（组合式 API）
UI 组件	Arco Design Vue
状态管理	Pinia
国际化	@nuxtjs/i18n
工具库	@vueuse/core、lodash、mitt
Markdown	markdown-it、highlight.js、lowlight
富文本 / 块编辑器	自定义 `BlockEditor`（块、悬停/固定工具栏、链接气泡）
数学公式渲染	katex
电子表格	exceljs
日期	dayjs（+ timezone、UTC、custom parse）
图标	自定义 iconfont 字体集

后端

领域	库
运行时	Nitro（Nuxt 4 服务端）
数据库	MySQL 5.7+（经 `mysql2`）
ORM	Drizzle ORM
实时通信	Nitro experimental WebSocket（`h3` / `crossws`）
AI SDK	Vercel AI SDK 7（`ai`、`@ai-sdk/*`）
文档解析	`mammoth`（docx）、`unpdf`（PDF）、`mailparser` + `cfb`（eml/msg）
图片处理	`sharp`
WebDAV	`webdav`
订阅源	`feed`
XML 解析	`fast-xml-parser`、`node-html-parser`
认证	`jsonwebtoken`、`bcryptjs`
邮件	`nodemailer`
日志	`consola`、`pino`
调度	`node-cron`
校验	`zod`

开发

领域	工具
语言	TypeScript 5.9
包管理器	pnpm 12.x（经 `packageManager` 强制）
Lint	ESLint（经 `@nuxt/eslint`）
类型检查	`vue-tsc`
数据库迁移	`drizzle-kit`
打包分析	`rollup-plugin-visualizer`

环境要求

Node.js 18.0 或更新版本（推荐 20.x LTS）。
pnpm 12.x（经 packageManager 字段强制）。
MySQL 5.7 或更新版本（推荐 8.0；需 utf8mb4）。
磁盘：应用 + 上传内容至少需 5 GB 可用空间。
内存：最低 2 GB；生产环境承载 AI 负载时推荐 4 GB。

快速开始

1. 克隆仓库

BASH

git clone https://github.com/xiaodaozhi/xiaodao-agent.git
cd xiaodao-agent

2. 安装依赖

BASH

pnpm install

3. 准备数据库

创建 utf8mb4 数据库并配置专属用户：

SQL

CREATE DATABASE xiaodao_agent CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'xiaodao'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON xiaodao_agent.* TO 'xiaodao'@'localhost';
FLUSH PRIVILEGES;

4. 启动开发服务器

BASH

pnpm dev

打开 http://localhost:3000/install 并跟随安装向导：

环境检查（Node.js 版本、可写目录、MySQL 扩展）。
数据库连接配置（主机、端口、数据库、用户、密码、表前缀）。
站点基础信息（站点名、URL、描述、管理首页）。
管理员账号创建（用户名、邮箱、密码）。

向导会写入 init.json 并以 init.lock 锁定安装。首次连接时通过 Drizzle 自动创建表结构。

5. 登录

访问 http://localhost:3000/login，使用刚创建的管理员账号登录。管理后台位于 http://localhost:3000/admin。

生产部署

构建

BASH

pnpm build

构建输出一个独立的 Nitro 服务器 .output/server/index.mjs，并包含预压缩的静态资源（gzip + brotli）。

使用 PM2 运行

BASH

npm install -g pm2
pm2 start .output/server/index.mjs --name xiaodao-agent
pm2 save
pm2 startup

反向代理（Nginx）

NGINX

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_cache_bypass $http_upgrade;
    }
}

WebSocket 支持

服务端启用了 Nitro 的 experimental WebSocket 层（nitro.experimental.websocket），用于实时 AI 聊天流式传输。聊天补全通过 HTTP 受理后作为后台任务运行，随后服务端通过两个 WebSocket 端点广播细粒度事件：

/api/admin/ws/ai/events：页面级按用户的通道，承载所有会话的繁忙状态变化（使会话侧栏保持实时）。
/api/admin/ws/ai/sessions/{id}/events：按会话的通道，使用增量协议（upsert / delta / remove / snapshot）流式推送文本/推理/工具 part，并附带会话繁忙与通知事件。连接建立时会先发送完整快照 seed 帧，使中途加入的观察者与进行中的生成对齐；轻量 ping/pong 心跳保持空闲连接存活。

请确保你的反向代理如上转发 Upgrade 与 Connection 头，以便 WebSocket 升级能够通过。

子路径部署

设置 APP_BASE_URL 以部署到子路径下（例如位于其他应用之后）：

BASH

pnpm build:agent   # cross-env APP_BASE_URL=/agent/ nuxt build

postbuild 脚本（scripts/postbuild.js）会相应地调整资源路径。

Docker

DOCKERFILE

FROM node:20-alpine
WORKDIR /app

COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
RUN npm install -g pnpm@11.5.2 && pnpm install --frozen-lockfile

COPY . .
RUN pnpm build

EXPOSE 3000
CMD ["node", ".output/server/index.mjs"]

更新

BASH

git pull origin main
pnpm install
pnpm build
pm2 restart xiaodao-agent

升级前请始终备份数据库与 uploads/ 目录。

项目结构

TEXT

xiaodao-agent/
├── app/                         # 前端应用
│   ├── assets/                  # 字体、图片、全局样式
│   ├── components/              # Vue 组件
│   │   ├── admin/               # 管理后台组件
│   │   │   ├── chat/             # AI 聊天 UI + 工具卡片（WebSocket 驱动）
│   │   │   ├── home/            # 仪表盘组件
│   │   │   ├── knowledge/        # 笔记本块编辑器、思维导图、流程图、白板、电子表格
│   │   │   ├── layout/          # 页头、页脚、菜单
│   │   │   ├── profile/         # 个人资料、登录、密码、Token
│   │   │   └── settings/        # 设置面板
│   │   ├── global/              # 共享组件（markdown、图标选择器）
│   │   ├── install/             # 安装向导
│   │   └── login/               # 登录页组件
│   ├── composables/             # API 组合式函数（useAiApi、useApi、……）
│   ├── directive/               # v-permission 指令
│   ├── layouts/                 # admin、default、blank
│   ├── locales/                 # 管理后台 UI 翻译
│   ├── middleware/              # 路由守卫（auth.global.ts）
│   ├── pages/                   # 基于文件的路由（admin/*、install、login、auth/[app]）
│   ├── plugins/                 # $api、arco、auth、dayjs、directives、bfcache
│   ├── routes/                  # 页面路由配置与菜单项
│   ├── themes/                  # 自动注册的主题布局（default）
│   └── utils/                   # 客户端工具与 Pinia 状态
├── server/                      # Nitro 后端
│   ├── api/                     # 基于文件的 API 路由
│   │   ├── admin/               # 需认证的管理端点（含 /api/admin/ws/ai/** WebSocket）
│   │   └── ...                  # 公开端点（articles、auth、install 等）
│   ├── db/                      # Drizzle 客户端 + schema.ts + migrations
│   ├── locales/                 # 服务端翻译字符串
│   ├── middleware/             # auth、logger、maintenance
│   ├── plugins/                # analytic、cron、db.init
│   ├── routes/                  # 非 API 路由：!avatar、!thumbnail、!webp、feed、uploads、sitemap.xml
│   ├── services/               # 业务逻辑（每个实体一个文件 + settings/）
│   └── utils/                   # ai、auth、backup、cron、feishu、github、ip2region、tools/
├── shared/                     # 客户端与服务端共享
│   ├── schemas/                 # Zod 校验 Schema
│   └── types/                  # TypeScript 类型定义
├── i18n/                       # i18n 根目录（locales + config）
├── docs/                       # API 响应、产品介绍、角色
├── public/                     # 静态公开资源（logo、favicon、robots.txt）
├── scripts/                    # postbuild.js、update.sh
├── drizzle.config.ts          # Drizzle Kit 配置
├── nuxt.config.ts             # Nuxt 配置
└── package.json

完整的架构、数据库结构、模块参考与 API 文档请参见 docs/zh/01-overview.md。

配置

环境变量

变量	默认值	说明
`APP_BASE_URL`	`/`	子路径部署的基础 URL
`NODE_ENV`	`development`	构建模式
`ANALYZE`	`false`	设置为 `true` 时在构建期间生成 `bundle-analysis.html`

运行时机密（JWT 密钥、密码盐值、AI 密钥、SMTP 凭据、WebDAV 凭据、OAuth 密钥）存储在数据库并通过管理后台界面管理，而非环境变量：这样单次部署可在不重新部署的情况下重新配置。

`nuxt.config.ts` 中值得注意的选项

routeRules：所有内容 SSR，/api/routes 使用 SWR 缓存（1 小时）。
nitro.compressPublicAssets：gzip + brotli 预压缩。
nitro.experimental.websocket：已启用。
i18n.strategy：no_prefix（URL 中无 /en-US/）；detectBrowserLanguage: false。
dayjs：默认时区 Asia/Shanghai，带 utc 与 timezone 插件。
eslint.stylistic：2 空格缩进、单引号、分号、尾随逗号、1tbs 大括号。

开发

命令

BASH

pnpm dev          # 在 http://localhost:3000 启动开发服务器
pnpm build        # 生产构建
pnpm preview      # 预览生产构建
pnpm lint         # ESLint
pnpm typecheck    # vue-tsc 类型检查

代码风格

2 空格缩进、单引号、强制分号、多行尾随逗号、1tbs 大括号（由 ESLint Stylistic 强制）。
文件命名：Vue 组件使用 PascalCase，组合式函数与工具使用 camelCase，API 路由文件使用 kebab-case（例如 index.get.ts、[id].put.ts）。

扩展系统

新增 API 端点：在 server/api/ 下新增文件，用 shared/schemas/ 中的 Zod Schema 校验请求体，调用 server/services/ 中对应的服务，并通过 server/utils/response.ts 中的 success() / fail() 返回响应。
新增服务：创建导出 service 对象的 server/services/<entity>.ts；如需在 server/db/schema.ts 中新增 Drizzle 表；在 shared/types/ 中添加共享类型。
新增 AI 工具：在 server/utils/tools/ 下实现，并在 createPresetToolList（位于 server/utils/ai.ts）中注册；或无需编写代码：在管理后台 /admin/tools 注册远程 HTTP 工具。
新增主题：添加 app/themes/<name>/layout.vue 与 style.css；registerThemeLayouts 模块会自动发现并注册它们。

日志

服务端日志通过全局 logger（基于 pino）输出。直接使用 logger.info(...)、logger.warn(...)、logger.error(...)、logger.debug(...)。客户端日志使用 consola。

开发者工具

Nuxt DevTools 在非生产环境中已启用。使用 Ctrl+Shift+D（Windows/Linux）或 Cmd+Shift+D（macOS）打开，或点击浏览器中的 Nuxt 图标。

许可证

基于 MIT 许可证发布。

致谢

本项目站在开源社区的肩膀上：

Nuxt —— 直观的 Vue 框架
Vue —— 渐进式 JavaScript 框架
Drizzle ORM —— TypeScript 优先的 ORM
Vercel AI SDK —— AI 应用框架
Arco Design —— 企业级 UI 组件
markdown-it —— Markdown 解析器
sharp —— 高性能图片处理
node-cron —— 任务调度

Xiaodao Agent：AI 原生的内容与知识，完全自主托管。

小刀智能体

目录

项目概览

亮点

主要特性

AI 智能

内容管理

笔记本与知识工具

媒体中心

安全与访问

平台与 SEO

自动化

技术栈

前端

后端

开发

环境要求

快速开始

1. 克隆仓库

2. 安装依赖

3. 准备数据库

4. 启动开发服务器

5. 登录

生产部署

构建

使用 PM2 运行

反向代理（Nginx）

WebSocket 支持

子路径部署

Docker

更新

项目结构

配置

环境变量

nuxt.config.ts 中值得注意的选项

开发

命令

代码风格

扩展系统

日志

开发者工具

许可证

致谢

暂无评论

评论这篇文章

`nuxt.config.ts` 中值得注意的选项