语言版本：中文 | English

IDL RAG Panel 是一个面向 ENVI/IDL 文档、代码和课程资料的本地优先 RAG 工作台。它把分散在本地的 PDF、Markdown、文本和 .pro / .idl 代码整理成可检索的知识库，并提供带引用的问答、检索调试、Agent 工具调用、.pro 文件生成、本地 IDL 运行和检索效果评测。

这个项目的重点不是做一个通用聊天界面，而是解决 ENVI/IDL 学习、实验和项目开发中常见的三个问题：资料难找、代码上下文难追踪、回答缺少可验证来源。

更多页面截图：

• 概览页
• 文档页
• 设置页

完整展示说明见 docs/project-showcase.md。

Chat 中的 Agent 模式不是单纯把问题交给大模型生成回答，而是围绕当前知识库、IDL 代码结构和本地运行环境组织一个可验证的代码工作流。

flowchart LR
  Ask[用户问题 / 代码需求] --> Agent[Chat Agent]
  Agent --> Search[知识库检索]
  Agent --> Tools[IDL 代码工具]
  Ask --> GEE[GEE 数据获取]
  GEE --> Data[数据 artifact]
  Tools --> Symbol[符号搜索]
  Tools --> Context[上下文读取]
  Tools --> Calls[调用关系分析]
  Search --> Pro[生成 .pro artifact]
  Context --> Pro
  Calls --> Pro
  Data --> Pro
  Pro --> Click[用户点击运行 IDL]
  Click --> Stage[暂存输入数据]
  Stage --> Batch[idlde.exe -batch]
  Batch --> Result[运行摘要 / 日志 / 输出图预览]

这条链路适合做 ENVI/IDL 学习资料问答、代码上下文追踪、脚本生成、运行验证和效果图展示。运行产物保存在 data/generated/chat/**/runs/，属于本地运行数据，不应提交到 Git。

flowchart LR
  Source[本地文档与 IDL 代码] --> Ingest[解析与分块]
  Ingest --> FTS[SQLite FTS5]
  Ingest --> Vector[LanceDB 向量索引]
  User[用户问题] --> Retrieve[混合检索]
  FTS --> Retrieve
  Vector --> Retrieve
  Retrieve --> Ground[引用与上下文]
  Ground --> Answer[回答 / Agent / .pro 生成]
  Answer --> Run[用户触发本地 IDL 运行]
  Run --> UI[日志、图片预览与评测]
  Answer --> UI

flowchart LR
  UI[React + Ant Design 前端] --> API[FastAPI 后端]
  API --> DB[(SQLite + SQLAlchemy)]
  API --> FTS[(SQLite FTS5)]
  API --> VEC[(LanceDB 向量索引)]
  API --> FS[本地运行文件]
  API --> IDL[idlde.exe -batch 本机 IDL]
  API --> LLM[OpenAI 兼容模型服务 / 向量模型]

完整架构说明见 ARCHITECTURE.md 和 docs/architecture.md。

适合：

• 本地 ENVI/IDL 资料整理和检索。
• 实验室或小团队内部知识库验证。
• 个人作品集和 RAG 工程能力展示。
• 需要引用来源、检索调试和效果评测的 RAG 场景。
• 希望保留本地数据控制权的私有知识库应用。

不适合直接作为：

• 面向公网的大规模多租户 SaaS。
• 海量文档集群检索系统。
• 无需人工审查即可公开上传私有资料的托管平台。
• 完全离线模型系统；当前仍依赖外部或本地 OpenAI 兼容模型服务提供生成和向量能力。

• 默认使用 SQLite，本地部署和小团队验证更方便；大规模并发需要进一步改造存储和任务队列。
• 向量检索质量依赖实际配置的 embedding provider。
• data/app.db 中的敏感字段会加密存储，但数据库文件本身仍属于本地运行数据。
• GEE 对接第一版只支持结构化参数的小范围数据获取，不接受任意 Earth Engine Python/JavaScript 代码；下载数据保存为 data/generated/chat/**/gee/ 下的本地 artifact，不应提交到 Git。
• 本地 IDL 运行只针对当前用户拥有的 Chat .pro artifact，由用户主动触发；后端生成 __idlrag_runner.pro 并通过 idlde.exe -batch 执行，运行日志和输出图保存在 data/generated/chat/**/runs/，不应提交到 Git。
• 截图和展示材料使用公开合成数据，不包含私人学习文件、真实 API Key、GEE 凭据或本地数据库。

idl-rag/
  backend/
    app/
      api/              # FastAPI 路由与依赖
      core/             # 配置、认证 token、密码与密钥工具
      db/               # SQLAlchemy 模型与 SQLite/FTS 初始化
      services/         # 入库、检索、向量、模型、Agent、评测服务
      main.py           # FastAPI 应用与索引 worker 生命周期
    tests/              # 后端测试与 golden eval 数据
    pyproject.toml

  frontend/
    src/
      api/              # API 客户端与类型
      pages/            # 概览、知识库、文档、对话、检索测试、设置
      styles/           # 应用级样式
      App.tsx
      main.tsx
    package.json

  docs/
    architecture.md
    configuration.md
    demo.md
    project-showcase.md
    security-and-data-control.md

  .env.example          # 公开配置模板，不包含真实密钥
  .gitignore            # 排除本地数据、密钥、缓存和构建产物

默认运行数据生成在 data/ 目录下。data/app.db、data/indexes/、data/logs/、data/generated/、data/parsed/ 和源文档都属于本地运行产物。

Copy-Item .env.example .env

本地开发最重要的配置如下：

IDLRAG_AUTH_SECRET=replace-with-a-long-random-secret
IDLRAG_CORS_ORIGINS=http://127.0.0.1:5173,http://localhost:5173
IDLRAG_IDL_EXECUTABLE=idlde
VITE_API_BASE_URL=http://127.0.0.1:8000/api

Windows IDL 8.8 建议把 IDLRAG_IDL_EXECUTABLE 设置为 Workbench 启动器，例如 D:\envi5.6\ENVI56\IDL88\bin\bin.x86_64\idlde.exe。后端会使用 idlde.exe -batch <runner.pro> 执行，不使用 idl.exe -e。

如果需要使用 GEE 数据获取，需要先在 Google Cloud 项目中启用 Earth Engine API，并配置项目 ID 与认证方式。本地开发推荐 ADC 浏览器授权：

uv run --project backend python -c "import ee; ee.Authenticate(auth_mode='localhost')"

然后在 .env 中启用：

IDLRAG_GEE_ENABLED=true
IDLRAG_GEE_AUTH_MODE=adc
IDLRAG_GEE_PROJECT=your-google-cloud-project-id

如果未启用 Earth Engine API，初始化会提示该项目尚未使用或未启用 earthengine.googleapis.com。完整配置和 smoke test 见 docs/configuration.md。

uv sync --project backend

uv run --project backend uvicorn app.main:app --app-dir backend --reload

默认后端地址：

http://127.0.0.1:8000

npm install --prefix frontend

npm run dev --prefix frontend

默认前端地址：

http://127.0.0.1:5173

1. 打开前端页面并注册或登录。
2. 进入设置页面，配置 OpenAI 兼容模型服务、对话模型和向量模型。
3. 创建知识库。
4. 上传或导入公开、脱敏的 ENVI/IDL 文档。
5. 等待文档状态变为 ready。
6. 进入对话页面，选择知识库并提问。
7. 可选：配置 GEE 后，点击“获取 GEE 数据”，下载小范围遥感数据并作为 IDL 输入 artifact。
8. 开启 .pro 文件生成，让 Agent 基于检索资料和已选输入数据生成 IDL 脚本。
9. 点击“运行 IDL”查看执行摘要、stdout/stderr 日志和输出图片预览。
10. 查看回答中的引用来源、检索策略和行号范围。
11. 进入检索测试页面，对比不同检索策略的候选结果。
12. 在设置页面查看本地评测报告。

更完整的演示步骤见 docs/demo.md。

后端通过 backend/app/core/config.py 读取环境变量默认值。运行时模型设置和服务密钥由 backend/app/services/settings_service.py 管理；敏感值通过 backend/app/core/security.py 加密后写入本地数据库。

加密可以保护本地运行存储中的敏感字段，但 data/app.db 仍然属于本地应用数据。配置细节见 docs/configuration.md，数据控制规则见 docs/security-and-data-control.md。

运行后端重点测试：

uv run --project backend pytest backend/tests/test_retrieval_strategies.py backend/tests/test_agent_service.py
uv run --project backend pytest backend/tests/test_eval_golden_qa.py backend/tests/test_eval_metrics.py backend/tests/test_evaluation_api.py

构建前端：

npm run build --prefix frontend