# n-agent

**Repository Path**: alan_lw/n-agent

## Basic Information

- **Project Name**: n-agent
- **Description**: n-agent
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-21
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Agent Server

基于 LangChain 的本地 AI Agent，HTTP 后端 + Web/TUI 前端架构。

| 层 | 技术 |
|------|------|
| 后端 | Node.js + Express + TypeScript |
| Web 前端 | Vue 3 + Element Plus + Pinia + TypeScript |
| TUI | TypeScript（开发中）|
| TUI (Go) | Go + [Bubble Tea](https://github.com/charmbracelet/bubbletea)（兼容问题需单独启动）|
| AI | LangChain + LangGraph + OpenAI |
| 数据库 | SQLite |

## 目录结构

```
server/               # HTTP 后端（Node.js，Express）
├── index.ts          # 入口
├── http-server.ts
├── services/         # 业务逻辑层
├── tools/            # AI Agent 工具集
├── http/routes/      # API 路由
└── db/               # SQLite 数据库
web/                  # Web 前端（Vue 3 + Element Plus）
├── index.html
└── src/
    ├── api/
    ├── components/
    ├── stores/
    ├── types/
    ├── styles/
    ├── App.vue
    └── main.ts
tui/                  # TUI 终端界面（TypeScript，开发中）
├── index.ts          # 占位实现
tui-go/               # TUI 终端界面（Go + Bubble Tea，兼容问题需单独启动）
├── main.go
├── go.mod
└── go.sum
scripts/              # 开发工具脚本
├── run.mjs           # 统一启动器（dev / prod 通用）
├── build-sea.mjs     # SEA 单文件打包
└── ...
```

## 启动方式

所有启动都通过 `scripts/run.mjs` 统一管理，自动分配空闲端口并协调各子进程。

| 命令 | 说明 |
|------|------|
| `npm dev` | 仅启动 server（TUI 需另外启动） |
| `npm dev:all` | server + Web（自动分配端口） |
| `npm dev:web` | 仅 server + Web |
| `npm dev:server` | 启动 server（默认 3847，可选 `PORT`/`--port`） |
| `npm dev:web:client` | Vite 开发服务器，代理 `/api` 到后端（默认 `API_PORT=3847`） |
| `npm tui-ts` | 运行 TypeScript TUI（开发中） |
| `npm tui-go` | 运行 Go TUI（需已启动 server） |
| `npm start` | 生产模式：使用编译后的产物 |

端口由启动器自动分配，也可通过 `--port` 参数或 `PORT` 环境变量指定。

### 环境要求

| 工具 | 版本要求 |
|------|---------|
| Node.js | >= 18 |
| npm | >= 8 |
| Go | >= 1.21 |

## API

所有接口统一前缀 `/api`，后端启动后可访问：

| 端点 | 说明 |
|------|------|
| `GET /api/health` | 健康检查 |
| `POST /api/chat/stream` | AI 对话（SSE 流式） |
| `POST /api/agent/stream` | Agent 对话（带工具调用） |
| `GET/POST/DELETE /api/workspace` | 工作区管理 |
| `POST /api/terminal/exec` | 终端命令执行 |
| `GET /api/files/list` | 文件列表 |
| `GET /api/files/read` | 读取文件 |
| `POST /api/files/write` | 写入文件 |

## 生产构建

### 源码构建（开发者/服务端）

```bash
# 编译后端 + Web 前端
npm build:server     # → out/server/
npm build:web        # → out/web/

# 生产启动（自动分配端口）
npm start            # node scripts/run.mjs --prod
```

### 单文件分发（推荐）

打包为单个 exe，用户无需安装 Node.js / npm / Go：

```bash
# 一键构建（后端 + Web 打包为 exe）
npm build:sea        # → out/agent.exe
```

| 命令 | 产物 | 说明 |
|------|------|------|
| `agent.exe` | 直接启动 | HTTP 服务（浏览器访问） |
| `agent.exe web` | Web 模式 | HTTP 服务 + 浏览器访问 |

### 分发给别人使用

**方式一：单 exe 分发（推荐）**

构建产物（`out/` 目录下）：
```
agent.exe          ← 主程序（含后端运行时 + Web 前端 + SQLite WASM）
```

> WASM 已内嵌到 exe 中，用户只需这一个文件。

用户直接运行 `agent.exe`，然后浏览器访问。

**方式二：源码运行（开发者）**

```bash
git clone <repo-url>
cd ts-ai-agent-01
npm install
npm dev              # 仅启动 server（TUI 需另外启动）
# 或
npm dev:all          # server + Web
# 或
npm dev:web          # 仅 server + Web
# 或
npm tui-go           # 单独启动 Go TUI（需已启动 server）
```

要求：Node.js >= 18，npm >= 8，Go >= 1.21。

**方式三：Docker**

```dockerfile
FROM node:18-alpine AS backend
WORKDIR /app
COPY package.json npm-lock.yaml scripts/ ./
COPY out/server ./server
EXPOSE 3847
CMD ["node", "scripts/run.mjs", "--prod"]
```

```bash
docker build -t ai-agent-server .
docker run -p 3847:3847 ai-agent-server
```