mio-chat-backend: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目定位

Mio-Chat 的后端，自称 "Agent OS"：不只是 API 转发，而是带 Hook 拦截、三层插件体系、真实终端桥接的 Agent 运行环境。配套前端仓库 mio-chat-frontend（本机通常在 ../mio-chat-frontend）。

这是作者自用的个人项目，仍在开发阶段，没有外部用户。因此：

• 数据结构可以直接改到对的形态，不必为兼容旧数据写迁移分支（真需要迁移时走 lib/migration/，启动时自动检测执行）。
• CI 只构建 Docker 镜像，不卡合并。直接提交到 master，无 PR 流程。
• 有测试但覆盖不全，不要假设改动会被测试拦住。

命令

pnpm dev          # node --watch app.js，日志打到 stdout
pnpm start        # pm2 start ./config/pm2.json（生产）
pnpm lint         # oxlint
pnpm lint:fix     # oxlint --fix
pnpm format       # prettier --write .

pnpm test         # bash scripts/utils/run-tests.sh
pnpm test:unit    # node --test tests/**/*.test.js
node --test tests/adapters/openai.test.js    # 跑单个测试文件

pnpm db:push      # prisma db push（改完 schema 用这个，开发阶段够了）
pnpm db:migrate   # prisma migrate dev
pnpm db:studio    # 可视化查看 data/app.db

pnpm docker:up / docker:down / docker:logs

测试用 Node 内置的 node --test，无第三方框架。测试分布：tests/{adapters,integration,plugins,routes,unit}/。适配器测试最全（每个 provider 一个文件），业务逻辑覆盖较薄。

启动流程

app.js 是入口，所有依赖都是动态 import 的（await import(...)），因为初始化有严格顺序：

performFullInitialization()   # 确保 .env 存在、数据库目录存在、schema 已同步
  → prismaManager.initialize()
  → 各 Service.initialize()（Preset / SystemSettings / PluginConfig / Task）
  → initializeDefaults()
  → AutoMigrationDetector.checkAndMigrate()
  → config.reload()
  → statusCheck()               # lib/check.js，在这里创建 global.middleware
  → taskScheduler.initialize()
  → startServer()               # lib/server/http/index.js

app.js 还实现了优雅关闭（SIGINT/SIGTERM，10s 强制超时），改启动/关闭逻辑时注意别破坏这条链。

两个全局

• global.middleware — 在 lib/check.js 里创建，lib/middleware.js 定义。运行期访问 socket server、插件、LLM 适配器、OneBot 的统一入口。
• logger — utils/logger.js，全局可用无需 import。用 logger.info/warn/error/debug/mark/json。

架构

lib/
├── server/
│   ├── http/          Express 5：routes(index.js) + controllers/ + middleware/
│   └── socket.io/     实时层，与前端的主通道
├── chat/
│   ├── llm/           适配器、Skills、结晶服务、任务执行
│   ├── onebot/        OneBot v11（反向 WS 客户端）
│   └── acp/           Agent Client Protocol，带独立进程管理
├── hooks/             全局 Hook 架构（V3）
├── plugins/           内置插件
├── database/          Prisma 封装 + Service 层
├── initialization/    首次启动自愈
└── migration/         自动迁移检测
plugins/custom/        第三方插件（pnpm workspace）