agent-chat-backend

基于 Express、Socket.IO 与 Vercel AI SDK 的会话式 Agent 后端：管理模型配置与会话、流式对话、文件上传，并支持通过 MCP 调用外部工具。

功能概览

• HTTP API：配置读写、会话 CRUD、文件上传、模型列表探测、内置文档等（详见 docs/API.md）。
• Socket.IO（路径 /socket.io）：前端实时收发聊天流、中止生成等。
• MCP：可按配置连接 Streamable HTTP、SSE、Stdio 等传输方式的 MCP 服务。
• 静态资源：若存在 public/ 目录（通常为前端构建产物），会一并托管并支持 SPA 回退到 index.html。

环境要求

• Node.js 18+（推荐 20+；开发与 CI 中常用 22）。

本地运行

cd node/backend
npm install
npm start

默认监听 http://127.0.0.1:3333。修改端口：

# Linux / macOS
PORT=8080 npm start

# Windows PowerShell
$env:PORT=8080; npm start

指定数据目录（会话、上传、配置）：

# Linux / macOS
npm start -- --data-dir /data/agent-chat

# Windows PowerShell
npm start -- --data-dir D:\agent-chat-data

启动后控制台会打印 Socket.IO 与 HTTP 地址。

使用 npx（发布后）

npx -y -p agent-chat-backend agent-chat-backend

同样可通过 PORT 指定端口。 也支持通过程序参数传入数据目录：

npx -y -p agent-chat-backend agent-chat-backend --data-dir /data/agent-chat

仅在本地目录调试、不发布到 npm 时，可在本仓库内执行：

cd node/backend
npx .

数据与配置目录

运行时默认会在包根目录下维护 data/（与 src/ 同级）；可通过 --data-dir（优先）或 AGENT_CHAT_DATA_DIR 改为外部目录：

| 路径 | 说明 | |------|------| | data/config.json | 模型、MCP、快捷指令等配置（首次访问会自动写入默认模板） | | data/sessions/ | 当前会话 JSON | | data/sessions-archived/ | 已归档会话 | | data/uploads/ | 上传附件 |

通过 npm 全局或 npx 安装 时，若未指定 --data-dir，上述目录位于安装包目录内（例如 node_modules/agent-chat-backend/data）。

环境变量

| 变量 | 说明 | |------|------| | PORT | HTTP 端口，默认 3333。 | | AGENT_CHAT_DATA_DIR | 数据目录（会话/上传/配置）路径。优先级低于 --data-dir。 | | resource_api | 若本地尚无 data/config.json，启动时会尝试从 {resource_api}/config.json 拉取并写入（便于容器/编排注入）。 |

内置文档

服务运行时可访问（返回 Markdown 正文）：

• GET /api/docs → docs/API.md
• GET /api/docs/changelog → docs/CHANGELOG.md

前端构建产物

将前端构建输出放到本目录的 public/ 下（含 index.html），后端会自动启用静态托管与前端路由回退。无 public/ 时仍可单独作为 API + Socket 服务使用。

npm 发布说明

发布前可用 npm pack --dry-run 检查打进包的文件；package.json 中 files 字段已限制为运行所需内容（src、public、docs）。更详细的登录与发布步骤可参考同目录下的 npmjs.md。

许可证

ISC（见 package.json）。