内容
# 艾瑞尔图表
## 当前架构
该仓库现已包含第二阶段 + 第三阶段的实现基准：
- `apps/web` — Next.js 15 应用，具有：
- 创建或加入会话的登陆页面
- `/s/[id]` 会话路由，带有路由验证
- CodeMirror 6 + Yjs 协同编辑器
- Mermaid 预览，在解析错误时回退到上一个有效的 SVG
- 存在条带、活动订阅、分享 URL 和连接状态 UI
- 通过 `NEXT_PUBLIC_SERVER_URL` 和 `NEXT_PUBLIC_WS_URL` 配置服务器/websocket 端点
- `apps/server` — Node.js TypeScript 服务器，具有：
- `POST /mcp` MCP HTTP 端点，用于 `read_diagram`、`write_diagram` 和 `list_sessions`
- `OPTIONS /mcp` 预检处理和 CORS 响应头，用于浏览器来源的 MCP 请求
- `/health` 健康检查端点
- `/ws/:roomId` Yjs 兼容的 websocket 房间
- 基于 LevelDB 的会话持久性和清理计时器
- 通过 `ALLOWED_ORIGINS` 进行源地址允许列表
- `packages/shared` — 两个应用都使用的共享合约和类型
## 工作空间布局
- `apps/web`
- `apps/server`
- `packages/shared`
- `docs` — 阶段计划和共享合约
- `reports` — 验证和计划笔记
## 先决条件
- Node.js 24+
- pnpm 10+
## 环境设置
### 网页
将 `apps/web/.env.example` 复制到 `apps/web/.env.local` 并根据需要调整：
```bash
cp apps/web/.env.example apps/web/.env.local
```
默认本地值：
- `NEXT_PUBLIC_SERVER_URL=http://localhost:4000`
- `NEXT_PUBLIC_WS_URL=ws://localhost:4000`
### 服务器
服务器从环境变量中读取配置，本地开发具有合理的默认值。`pnpm dev` 不需要 `.env` 文件。要覆盖值，请在 shell 中导出它们或使用 `dotenv-cli` 等工具。
`apps/server/src/lib/env.ts` 使用的运行时变量：
- `PORT` — HTTP 端口，默认为 `4000`
- `DATA_DIR` — LevelDB/会话存储目录，默认为 `.data/arielcharts`
- `CLEANUP_INTERVAL_MS` — 清理计时器间隔
- `SESSION_TTL_MS` — 会话超时时间，在清理前
- `ALLOWED_ORIGINS` — 以逗号分隔的浏览器/websocket 源地址允许列表
对于本地开发，`ALLOWED_ORIGINS=http://localhost:3000` 足以应对默认的 Next.js 开发服务器。
## 本地开发
一次性安装依赖：
```bash
pnpm install
```
从仓库根目录同时运行两个应用：
```bash
pnpm dev
```
这将启动：
- 网页应用，位于 `http://localhost:3000`
- 服务器，位于 `http://localhost:4000`
您也可以分别运行每个工作空间：
```bash
pnpm --filter @arielcharts/server dev
pnpm --filter @arielcharts/web dev
```
## 构建、类型检查和测试
从仓库根目录运行整个工作空间的检查：
```bash
pnpm build
pnpm typecheck
pnpm test
```
运行仅服务器的检查：
```bash
pnpm --filter @arielcharts/server build
pnpm --filter @arielcharts/server typecheck
pnpm --filter @arielcharts/server test
```
运行仅网页的检查：
```bash
pnpm --filter @arielcharts/web build
pnpm --filter @arielcharts/web typecheck
pnpm --filter @arielcharts/web test
```
## 核心 HTTP 和 Websocket 合约
- `POST /mcp` 接受 `{ tool, input }` JSON 并返回 `{ result }`
- `OPTIONS /mcp` 支持部署的 web 到服务器请求的浏览器预检
- `/health` 返回简单的就绪负载
- `/ws/:roomId` 托管 Yjs 协作室
详细的合约源位于 `docs/shared-contracts.md` 和 `packages/shared/src/types.ts`。
## 当前状态
- 第一阶段脚手架：完成
- 第二阶段实时服务器 + MCP 基础：已实现
- 第三阶段协作前端 MVP：已实现
- 第四阶段部署/E2E 强化：进行中
