# Optical Intelligent Agent Coordination Platform

**Repository Path**: rocheryu/optical-intelligent-agent-coordination-platform

## Basic Information

- **Project Name**: Optical Intelligent Agent Coordination Platform
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-22
- **Last Updated**: 2026-07-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 光学智能体协同平台

面向光学领域的 **大模型应用协同平台**：以 [Dify](https://github.com/langgenius/dify) 为智能体编排与知识库中枢，以自研 **Connect** 为统一对话前端，并串联两套本地仿真引擎——**几何光路（ray-optics）** 与 **光学分析实验（optics-analysis-lab）**。

> 仓库地址：[Gitee — optical-intelligent-agent-coordination-platform](https://gitee.com/rocheryu/optical-intelligent-agent-coordination-platform)

---

## 一、平台架构

```
┌─────────────────────────────────────────────────────────────────┐
│  用户浏览器                                                      │
│    Connect 协同前端 (:3000)  ←→  门户页 (:8080，可选)              │
└───────────────┬───────────────────────────────┬───────────────────┘
                │ SSE / REST                     │ iframe / fetch
                ▼                                ▼
┌───────────────────────────┐    ┌────────────────────────────────┐
│  Dify 控制台 + API (:18088)│    │  仿真平台（本机独立进程）         │
│  · 知识库检索              │    │  · ray-optics        (:8090)   │
│  · Chatflow / LLM        │    │  · optics-analysis-lab (:8765) │
│  · LaTeX 清洗代码节点      │    └────────────────────────────────┘
└───────────────────────────┘
```

### 三个协同能力

| 能力 | 触发方式 | 后端 |
|------|----------|------|
| **一般光学问答** | 普通对话 | Dify 知识库 + LLM |
| **几何光路 JSON 仿真** | 用户要光路图 / 仿真模式 | Dify 输出 ray-optics JSON → Connect iframe 载入 |
| **光学分析出图** | 用户要 PSF/MTF/点列图等 | Dify 输出 `<OPTICS_IMAGE_BRIDGE>` → Connect 调 lab API 拉图 |

### 仓库目录

```
.
├── connect/                 # 协同对话前端（React + Vite）
├── dify-main/               # Dify 平台（Docker 部署，含 Windows 适配 override）
├── ray-optics/              # 2D 几何光学仿真（webpack dev :8090）
├── optics-analysis-lab/     # 光学分析 FastAPI 服务 (:8765)
├── .trae/gallery-kb-chunks/ # Gallery 知识库分片（可导入 Dify）
├── prompt.md                # Dify 系统提示词（必同步）
├── deploy/                  # 一键启动脚本
├── portal/                  # 双入口导航页
└── docs/                    # 补充部署文档
```

**本仓库不包含**：论文稿件（docx/pdf 等）、`知识库/` 下的教材习题原文。知识库需自行准备光学资料后按下文导入 Dify。

---

## 二、环境要求

| 组件 | 版本要求 |
|------|----------|
| Docker Desktop | 最新稳定版（跑 Dify） |
| Node.js | 18+（Connect、ray-optics） |
| Python | 3.10+（optics-analysis-lab，建议用自带 `.venv`） |
| 操作系统 | Windows 10/11 或 Linux（脚本以 PowerShell 为主） |

**默认端口**（冲突时请自行修改对应 `.env`）：

| 服务 | 端口 |
|------|------|
| Dify 控制台 | 18088 |
| Connect | 3000 |
| 门户 | 8080 |
| ray-optics | 8090 |
| optics-analysis-lab | 8765 |

---

## 三、快速开始（本地全流程）

### 步骤 0：克隆仓库

```powershell
git clone https://gitee.com/rocheryu/optical-intelligent-agent-coordination-platform.git
cd optical-intelligent-agent-coordination-platform
```

### 步骤 1：启动 Dify

**完整步骤（启动、模型 API、应用编排、对接 Connect）见：**

→ **[`docs/Dify启动与API接入指南.md`](docs/Dify启动与API接入指南.md)**

简要命令：

```powershell
cd dify-main\docker
# 首次需准备 .env，并设置 EXPOSE_NGINX_PORT=18088
docker compose up -d
```

浏览器打开 **http://localhost:18088**，完成安装向导，注册管理员账号。

### 步骤 2：配置 Dify 知识库

#### 2.1 创建知识库

1. Dify 控制台 → **知识库** → **创建知识库**（如「光学专业知识库」）。
2. 建议至少建立两个数据集：
   - **光学教材/原理**（自行准备 markdown 或 pdf，勿使用本仓库未包含的 `知识库/` 原文）
   - **Ray Optics Gallery JSON**（使用本仓库预生成分片）

#### 2.2 导入 Gallery JSON（几何光路必做）

```powershell
cd connect
npm install
npm run gallery-kb:export
```

将生成的 **`.trae/gallery-kb-chunks/*.md`（约 72 个）** 全部上传到 Dify 知识库「光学仿真」数据集。

> 每个文件含：标题、作品 ID、**完整 JSON 代码块**。单文件即一整 chunk，避免切块把 JSON 拦腰截断。  
> 详细说明见 [`connect/docs/DIFY_Gallery知识库入库说明.md`](connect/docs/DIFY_Gallery知识库入库说明.md)。

#### 2.3 检索验收

在知识库 **检索测试** 中查询：`平凹共振腔 光路图`

- Top1 应命中 `resonator.md`（或同类条目）
- 片段内须含可 `JSON.parse` 的 `` ```json `` 块，且 `version === 5`

#### 2.4 切块参数（若自行上传大文档）

| 设置 | 建议值 |
|------|--------|
| 分段模式 | 按标题 / 自定义 |
| 分段标识 | `### ` |
| 最大分段长度 | ≥ 8000 |
| 重叠 | 0 |

**勿将**「入库说明」类文档与 Gallery JSON 混在同一高优先级数据集，以免检索噪声。

---

### 步骤 3：配置 Dify 应用（Chatflow）

#### 3.1 创建应用

1. **工作室** → **创建应用** → 类型选 **Chatflow（工作流）** 或带知识库检索的对话型应用。
2. 绑定上一步创建的知识库。

#### 3.2 开始节点 — 输入变量（必配）

在 **开始** 节点添加以下变量（名称须与 Connect 一致）：

| 变量名 | 类型 | 说明 |
|--------|------|------|
| `query` | 文本 | 用户输入（系统字段） |
| `professional_question` | 文本 | 与 query 相同，供提示词引用用户原话 |
| `optics_chat_mode` | 文本 | `normal` 或 `simulation`（Connect 仿真开关） |

#### 3.3 工作流拓扑

```
开始
  → 知识库检索（必须在 LLM 之前）
  → LLM
  → 代码节点：LaTeX 清洗（复制 connect/scripts/dify_latex_sanitize.py）
  → 直接回复（绑定代码节点输出的 text，不要绑 LLM 原始 text）
```

LaTeX 清洗配置详见 [`connect/docs/DIFY_禁止LaTeX编排指南.md`](connect/docs/DIFY_禁止LaTeX编排指南.md)。

#### 3.4 系统提示词

将仓库根目录 **`prompt.md`** 全文粘贴到 LLM 节点的系统提示词：

- **文首**「格式禁令正文」必须在最顶部
- **文末**「输出前终检」必须在最末尾
- 中间为三类能力（光路 JSON / 问答 / 分析出图）说明

在提示词中引用用户输入示例：

```
用户本轮问题：{{#professional_question#}}
当前模式：{{#optics_chat_mode#}}
```

（变量引用语法以你使用的 Dify 版本为准。）

#### 3.5 开场白

将 `prompt.md` 中「对话开场白」一节同步到：

- Dify 应用 **开场白**
- 前端 `connect/src/constants/openingStatement.js` 中 `DEFAULT_CHAT_OPENING`

#### 3.6 发布并获取 API Key

1. 保存并 **发布** 应用。
2. **访问 API** → 复制 **API Key**（形如 `app-xxxxxxxx`）。

---

### 步骤 4：配置 Connect 协同前端

```powershell
cd connect
copy .env.example .env
```

编辑 `connect/.env`：

```env
VITE_API_BASE_URL=http://localhost:18088/v1
VITE_API_KEY=app-你的Dify应用Key
VITE_APP_ID=app-你的Dify应用Key
VITE_RAY_OPTICS_SIM_URL=http://localhost:8090/simulator/index.html
```

**Docker 方式**（生产构建）在仓库根目录：

```powershell
copy .env.example .env
# 填入同上 VITE_* 变量
docker compose up -d --build
```

---

### 步骤 5：启动仿真平台

仿真服务**不会**随 `start.ps1` 自动启动，需单独执行：

```powershell
.\deploy\start-simulations.ps1
```

或手动：

```powershell
# 终端 A：几何光路 ray-optics
cd ray-optics
npm install
npx webpack serve --port 8090 --mode=development --host 0.0.0.0

# 终端 B：光学分析 lab
cd optics-analysis-lab
.\.venv\Scripts\python.exe -m uvicorn server:app --host 127.0.0.1 --port 8765
```

首次启动 ray-optics 前可执行 `npm run build-scenes && npm run build-pages`。

验收：

- http://localhost:8090/simulator/index.html → 200
- http://127.0.0.1:8765/api/health → OK

---

## 四、三者如何串联

### 4.1 Connect ↔ Dify

1. 用户在 Connect 输入问题，前端 `POST /v1/chat-messages`（流式 SSE）。
2. 请求体 `inputs` 携带：
   - `professional_question`：用户原话
   - `optics_chat_mode`：`normal` / `simulation`
   - `query`：同用户原话
3. Dify 检索知识库 → LLM 按 `prompt.md` 生成 → 代码节点清洗 LaTeX → 返回 `answer`。
4. Connect 解析回复中的：
   - `` ```json `` 块 → 几何光路仿真
   - `<OPTICS_IMAGE_BRIDGE>...</OPTICS_IMAGE_BRIDGE>` → 分析出图

### 4.2 Connect ↔ ray-optics（几何仿真）

1. 模型在正文输出 **完整 ray-optics JSON**（`version: 5`，`objs` 数组）。
2. Connect 解析 JSON，通过 iframe 加载 `VITE_RAY_OPTICS_SIM_URL`。
3. JSON 经 `postMessage` / localStorage 注入仿真器。
4. **关键**：JSON 须从知识库 chunk **原样复制**；Connect 不会替模型去磁盘拉取 Gallery 文件。

### 4.3 Connect ↔ optics-analysis-lab（分析出图）

1. 模型在仿真模式下输出 `<OPTICS_IMAGE_BRIDGE>` 包裹的 JSON，指明实验编号与参数。
2. Connect 解析后请求 `http://127.0.0.1:8765/api/lab/...`。
3. 返回 PNG（base64）嵌入对话；缺参时内嵌实验页 iframe 引导补参。
4. `prompt.md` 功能三与 `OPTICS_SIMULATION_GUIDE.md` 须与 lab 接口保持同步。

---

## 五、一键启动清单

按顺序执行（共 3 个终端，或 2 个终端 + Docker 后台）：

| 顺序 | 命令 | 访问地址 |
|------|------|----------|
| ① | `.\deploy\start.ps1` | Dify :18088，Connect :3000，门户 :8080 |
| ② | `.\deploy\start-simulations.ps1` | ray-optics :8090，lab :8765 |
| ③ | 浏览器打开 | http://localhost:3000 |

**仅开发 Connect（热更新）**：

```powershell
.\deploy\start.ps1 -SkipDify -DevConnect
```

**停止仿真**：

```powershell
.\deploy\start-simulations.ps1 -Stop
```

### 启动后自检

- [ ] Dify 控制台可登录
- [ ] Connect 可发消息并流式回复
- [ ] 问「平凹共振腔光路图」→ 回复含 JSON → 可点「仿真打开」
- [ ] 仿真模式问「库克三联镜 PSF」→ 可出分析图或缺参提示
- [ ] 回复正文无 `$`、`\frac` 等 LaTeX（或已被代码节点清洗）

---

## 六、常见问题

**Connect 401 / 连不上 Dify**  
检查 `VITE_API_BASE_URL` 是否含 `/v1`，API Key 是否为当前已发布应用的 Key。

**仿真 iframe 空白**  
确认 `start-simulations.ps1` 已运行；模型 JSON 是否为自造（坐标/字段错误）而非知识库原文。

**分析图一直转圈**  
确认 lab :8765 已启动；可在 `.env` 增大 `VITE_OPTICS_LAB_TIMEOUT_MS`（默认 120000）。

**流式中断**  
增大 Nginx `proxy_read_timeout`；见 `connect/src/services/api.js` 错误提示。

**Docker 构建 Connect 失败**  
在 `connect` 目录执行 `npm install` 重新生成 `package-lock.json` 后再 `docker compose up -d --build`。

---

## 七、公网部署

见 [`docs/公网域名部署指南.md`](docs/公网域名部署指南.md)（域名购买、DNS、Nginx、HTTPS）。

---

## 八、许可证与致谢

| 组件 | 许可证 |
|------|--------|
| Connect 及本仓库自研脚本/文档 | MIT（见 [LICENSE](LICENSE)） |
| dify-main | Dify 修改版 Apache 2.0 |
| ray-optics | Apache-2.0 |

- [Dify](https://github.com/langgenius/dify) — LLM 应用编排
- [ray-optics](https://github.com/ricktu288/ray-optics) — 浏览器几何光学仿真

---

## 九、相关文档索引

| 文档 | 内容 |
|------|------|
| [`docs/Dify启动与API接入指南.md`](docs/Dify启动与API接入指南.md) | **启动 Dify、配置大模型与应用 API、对接 Connect** |
| [`prompt.md`](prompt.md) | 完整系统提示词 |
| [`OPTICS_SIMULATION_GUIDE.md`](OPTICS_SIMULATION_GUIDE.md) | 仿真子系统 API 与参数 |
| [`connect/docs/DIFY_Gallery知识库入库说明.md`](connect/docs/DIFY_Gallery知识库入库说明.md) | Gallery 知识库导入 |
| [`connect/docs/DIFY_禁止LaTeX编排指南.md`](connect/docs/DIFY_禁止LaTeX编排指南.md) | LaTeX 硬清洗节点 |
| [`connect/README.md`](connect/README.md) | Connect 前端说明 |
| [`docs/开源部署指南.md`](docs/开源部署指南.md) | Docker 部署补充 |
| [`docs/公网域名部署指南.md`](docs/公网域名部署指南.md) | 域名与公网部署 |