diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2609dce
--- /dev/null
+++ b/README.md
@@ -0,0 +1,89 @@
+# Next TJWater
+
+Next TJWater 是供水管网 WebGIS Agent 工作台的前端项目。界面以地图为主视图，集成供水管网图层、调度状态、事件处置、Agent 对话和受控前端动作。
+
+项目使用 Vite、React 19、TypeScript 和 Tailwind CSS 4。地图基于 MapLibre GL，流向效果使用 deck.gl，Agent 消息支持代码高亮、数学公式和 Mermaid 图表。
+
+## 主要功能
+
+- 供水管网地图、业务图层和设备状态展示
+- 地图缩放、测量、绘制、图层控制和视图导出
+- 异常工况列表、详情分析和调度任务跟踪
+- Agent 流式对话、推荐问题、会话管理和权限批准
+- 经过 Schema 校验的 UI Envelope 和前端动作执行
+- 运行时配置注入、MSW 本地模拟和开发面板
+
+## 开发环境
+
+需要安装 Node.js、Corepack 和 pnpm。项目声明的包管理器版本为 pnpm 11.8.0。
+
+```bash
+corepack enable
+pnpm install
+cp .env.example .env.local
+pnpm dev
+```
+
+开发服务器默认监听所有网络接口。打开终端中 Vite 输出的地址即可访问工作台。
+
+Agent 服务默认地址为 `http://127.0.0.1:8787`。需要完整对话能力时，请同时启动对应的 Agent 后端。
+
+## 运行时配置
+
+浏览器配置通过 `/runtime-config.js` 注入，不使用 `VITE_` 或 `NEXT_PUBLIC_` 前缀。可在 `.env.local` 中设置以下变量：
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `TJWATER_MAPBOX_ACCESS_TOKEN` | 空 | Mapbox 底图访问令牌 |
+| `TJWATER_MAP_URL` | `https://geoserver.waternetwork.cn/geoserver` | GeoServer 服务地址 |
+| `TJWATER_GEOSERVER_WORKSPACE` | `tjwater` | GeoServer 工作区 |
+| `TJWATER_AGENT_API_BASE_URL` | `http://127.0.0.1:8787` | 浏览器访问的 Agent API 地址 |
+| `TJWATER_ENABLE_DEV_PANEL` | `false` | 是否显示开发面板 |
+| `TJWATER_ENABLE_MSW` | `false` | 是否启用浏览器端 Mock Service Worker |
+| `AGENT_API_INTERNAL_BASE_URL` | `http://127.0.0.1:8787` | Vite 开发代理访问的 Agent 服务地址，仅开发环境使用 |
+
+`.env.local` 已被 Git 忽略，请勿提交令牌或生产环境配置。
+
+## 常用命令
+
+```bash
+pnpm dev          # 启动开发服务器
+pnpm build        # 类型检查并生成生产构建
+pnpm preview      # 预览生产构建
+pnpm typecheck    # 运行 TypeScript 检查
+pnpm lint         # 运行 ESLint
+pnpm format       # 使用 Prettier 格式化文件
+pnpm test         # 运行 Vitest 单元测试
+pnpm test:watch   # 监听模式运行单元测试
+pnpm test:browser # 运行 Playwright 浏览器测试
+```
+
+## Docker
+
+生产镜像使用 Node.js 构建静态文件，并通过 Caddy 提供服务。容器启动时会根据环境变量生成 `/runtime-config.js`。
+
+```bash
+docker build -t next-tjwater .
+docker run --rm -p 8080:80 --env-file .env.local next-tjwater
+```
+
+启动后访问 `http://localhost:8080`。
+
+## 项目结构
+
+```text
+src/
+├── app/                 应用入口、Provider 和浏览器回归测试
+├── features/
+│   ├── agent/           Agent 协议、会话、动作执行和界面组件
+│   ├── map/             地图核心控件
+│   └── workbench/       调度工作台、业务面板和地图编排
+├── mocks/               MSW handlers 和测试数据
+├── shared/              通用 UI、AI 元素、配置和工具
+├── test/                Vitest 测试环境
+└── styles.css           Tailwind CSS 入口和全局样式
+```
+
+## 构建说明
+
+生产构建可能提示 deck.gl 和 luma.gl 的第三方循环分块，以及 Shiki、Mermaid 语言包超过 Rollup 默认的 500 kB 阈值。当前构建和浏览器测试可以正常完成，这些提示不影响产物生成。