diff --git a/README.md b/README.md
new file mode 100644
index 0000000..13e0e9a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,147 @@
+# JRXML 生成代理
+
+一个本地桌面应用程序，帮助非技术用户通过多轮自然语言对话创建 JasperReports 模板（JRXML）。
+
+## 功能
+
+- **多轮聊天**：通过对话优化报表 -- 添加列、更改标题、添加汇总
+- **自动验证**：每次生成或修改后都会验证 JRXML
+- **自动修正**：如果验证失败，代理会分析错误并自动修正（最多 3 次）
+- **模板检索**：使用 Chroma 向量数据库检索相关的 JRXML 示例以获得更好的生成效果
+- **下载**：导出已验证的、可供 JasperReports 使用的 JRXML 文件
+
+## 架构
+
+```
+Streamlit 界面 (app.py)
+    |
+LangGraph 代理 (agent/)
+    |-- retrieve (Chroma/embeddings)
+    |-- generate (LLM)
+    |-- validate (FastAPI service)
+    |-- explain + correct (auto-fix loop)
+    |-- modify (multi-turn edits)
+    |
+FastAPI 验证服务 (:8001)
+    |-- Structural checks (field references, SQL, page dimensions)
+    |-- XSD schema validation (if jasperreport.xsd available)
+```
+
+## 前置要求
+
+- Python 3.11+
+- 完整的编译验证需要：JDK 21 + JasperReports 7.0.6
+- OpenAI 兼容的 API 密钥（或本地 Ollama）
+
+## 快速开始
+
+### 1. 安装依赖
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. 配置环境
+
+```bash
+cp .env.example .env
+```
+
+编辑 `.env` 配置您的 API 密钥和偏好设置。
+
+### 3. 初始化知识库
+
+```bash
+python scripts/init_kb.py
+```
+
+### 4. 启动验证服务
+
+在一个终端中运行：
+```bash
+python -m uvicorn validation_service.main:app --port 8001
+```
+
+### 5. 启动 Streamlit 界面
+
+在另一个终端中运行：
+```bash
+streamlit run app.py
+```
+
+在浏览器中打开 http://localhost:8501。
+
+## 使用示例
+
+第一轮 - 生成：
+> "创建员工名册，包含 employee_id、name、department 和 hire_date 字段"
+
+第二轮 - 修改：
+> "在页脚添加页码"
+
+第三轮 - 修改：
+> "将标题改为 '2024 员工目录' 并加粗"
+
+每一轮都会自动验证和修正 JRXML。
+
+## 验证服务（当前限制）
+
+由于完整的 JasperReports 7.0.6 编译需要 JDK 21，当前的验证执行以下检查：
+
+1. 结构检查：字段声明一致性、SQL 查询存在性、页面尺寸、报表名称
+2. XSD schema 验证：如果 `validation_service/schemas/jasperreport_7_0_6.xsd` 可用
+
+要进行完整的编译验证，请将 `jasper-validator.jar` 放在 `validation_service/` 目录并更新 `main.py`。
+
+## 测试
+
+```bash
+pytest tests/test_validation.py -v
+pytest tests/test_agent.py -v
+pytest tests/ -v
+```
+
+## 项目结构
+
+```
+jrxml-agent/
+  app.py                     Streamlit 聊天界面
+  agent/
+    state.py                 AgentState 定义
+    nodes.py                图节点（generate, validate, modify 等）
+    graph.py                LangGraph 状态机
+  backend/
+    llm.py                  LLM 工厂（OpenAI / Ollama）
+    embeddings.py           嵌入模型工厂
+    validation.py           验证服务客户端
+  validation_service/
+    main.py                 FastAPI 验证服务器
+    validate.bat            Windows 启动器
+  data/
+    sample_templates/       知识库的 JRXML 模板
+    corrections/            错误修正案例
+  scripts/
+    init_kb.py              Chroma 知识库初始化脚本
+  tests/
+    test_validation.py      验证服务测试
+    test_agent.py           代理集成测试
+  db/chroma/                Chroma 持久化目录
+  requirements.txt
+  .env.example
+  README.md
+```
+
+## 环境变量
+
+| 变量 | 描述 | 默认值 |
+|----------|-------------|---------|
+| LLM_BACKEND | cloud 或 local | cloud |
+| OPENAI_API_KEY | OpenAI API 密钥 | - |
+| OPENAI_BASE_URL | API 基础 URL | https://api.openai.com/v1 |
+| LLM_MODEL | 模型名称 | gpt-4o |
+| LOCAL_LLM_MODEL | Ollama 模型 | qwen2.5-coder:7b |
+| EMBED_BACKEND | local 或 cloud | local |
+| LOCAL_EMBED_MODEL | 嵌入模型 | Qwen/Qwen3-Embedding-0.6B |
+| VALIDATION_SERVICE_URL | 验证端点 | http://localhost:8001/validate |
+| CHROMA_PERSIST_DIR | Chroma 存储位置 | ./db/chroma |
+| MAX_RETRY | 自动修正尝试次数 | 3 |