docs: add .env.example template and ADK architecture optimization guide

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Gemini CLI

data_agent/.env.example

@@ -0,0 +1,133 @@
+# ============================================================
+# GIS Data Agent v4.0 — Environment Configuration Template
+# ============================================================
+# Copy this file to .env and fill in your values:
+#   cp .env.example .env
+#
+# IMPORTANT:
+#   - Do NOT use 'export' prefix (python-dotenv handles bare KEY=VALUE)
+#   - Use forward slashes in Windows paths (D:/path/to/file)
+#   - Do NOT commit .env to version control
+# ============================================================
+
+# ==========================
+# REQUIRED: Database
+# ==========================
+POSTGRES_HOST=localhost
+POSTGRES_PORT=5432
+POSTGRES_DATABASE=gis_agent
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=your_password
+
+# ==========================
+# REQUIRED: AI Model
+# ==========================
+# Option A: Vertex AI (recommended for production)
+GOOGLE_GENAI_USE_VERTEXAI=TRUE
+GOOGLE_CLOUD_PROJECT=your-gcp-project-id
+GOOGLE_CLOUD_LOCATION=us-central1
+
+# Option B: Google AI Studio API Key (simpler setup)
+# GOOGLE_GENAI_USE_VERTEXAI=0
+# GOOGLE_API_KEY=AIzaSy...your_api_key
+
+# ==========================
+# REQUIRED: Authentication
+# ==========================
+# Generate with: chainlit create-secret
+CHAINLIT_AUTH_SECRET=your_random_secret_key_here
+
+# ==========================
+# OPTIONAL: OAuth2 Login
+# ==========================
+# Uncomment to enable "Sign in with Google" button
+# OAUTH_GOOGLE_CLIENT_ID=your_google_client_id
+# OAUTH_GOOGLE_CLIENT_SECRET=your_google_client_secret
+
+# ==========================
+# OPTIONAL: Agent Behavior
+# ==========================
+# Dynamic planner uses transfer_to_agent; false = fixed SequentialAgent pipelines
+DYNAMIC_PLANNER=true
+
+# ==========================
+# OPTIONAL: Map Services
+# ==========================
+# Gaode Maps (高德) — geocoding & reverse geocoding
+# GAODE_API_KEY=your_gaode_api_key
+
+# Tianditu (天地图) — basemap tiles (Vec + Img)
+# TIANDITU_TOKEN=your_tianditu_token
+
+# ==========================
+# OPTIONAL: Cloud Storage
+# ==========================
+# Huawei Cloud OBS (S3-compatible)
+# HUAWEI_OBS_AK=your_access_key
+# HUAWEI_OBS_SK=your_secret_key
+# HUAWEI_OBS_SERVER=https://obs.cn-north-4.myhuaweicloud.com
+# HUAWEI_OBS_BUCKET=your_bucket_name
+
+# AWS S3
+# AWS_ACCESS_KEY_ID=your_access_key
+# AWS_SECRET_ACCESS_KEY=your_secret_key
+# AWS_REGION=us-east-1
+# AWS_S3_BUCKET=your_bucket_name
+
+# Google Cloud Storage
+# GCS_BUCKET=your_bucket_name
+
+# ==========================
+# OPTIONAL: Enterprise Bots
+# ==========================
+# WeChat Work (企业微信)
+# WECOM_CORP_ID=your_corp_id
+# WECOM_APP_SECRET=your_app_secret
+# WECOM_TOKEN=your_callback_token
+# WECOM_ENCODING_AES_KEY=your_aes_key
+# WECOM_AGENT_ID=1000002
+# WECOM_SHARE_BASE_URL=https://your-domain.com
+
+# DingTalk (钉钉)
+# DINGTALK_APP_KEY=your_app_key
+# DINGTALK_APP_SECRET=your_app_secret
+# DINGTALK_ROBOT_CODE=your_robot_code
+# DINGTALK_SHARE_BASE_URL=https://your-domain.com
+
+# Feishu / Lark (飞书)
+# FEISHU_APP_ID=your_app_id
+# FEISHU_APP_SECRET=your_app_secret
+# FEISHU_VERIFICATION_TOKEN=your_verification_token
+# FEISHU_ENCRYPT_KEY=your_encrypt_key
+# FEISHU_SHARE_BASE_URL=https://your-domain.com
+
+# ==========================
+# OPTIONAL: Redis (Real-time Streams)
+# ==========================
+# Falls back to in-memory if not configured
+# REDIS_URL=redis://localhost:6379/0
+
+# ==========================
+# OPTIONAL: Observability
+# ==========================
+# LOG_LEVEL=INFO
+# LOG_FORMAT=text
+# AUDIT_LOG_RETENTION_DAYS=90
+
+# ==========================
+# OPTIONAL: Usage Limits
+# ==========================
+# DAILY_ANALYSIS_LIMIT=20
+# MONTHLY_TOKEN_LIMIT=0
+
+# ==========================
+# OPTIONAL: Extensions
+# ==========================
+# ArcPy Integration (use forward slashes!)
+# ARCPY_PYTHON_EXE=D:/path/to/arcgis/python.exe
+
+# MCP Toolbox
+# MCP_TOOLBOX_URL=http://localhost:8080
+
+# Google Earth Engine
+# GEE_SERVICE_ACCOUNT_KEY=path/to/key.json

docs/adk-architecture-optimization.md

@@ -0,0 +1,42 @@
+# 架构设计优化建议：基于 Google ADK 多智能体最佳实践
+
+## 1. 现状评估与架构亮点
+当前项目（GIS Data Agent）的代码逻辑（主要位于 `data_agent/agent.py`）已经具备了相当成熟的架构思想，特别是非常出色地遵循了 Google Agent Developer Kit (ADK) 的核心设计模式：
+
+*   **分层的智能体组合 (Hierarchical Task Decomposition)**：
+    *   **静态工作流 (Workflow Agents)**：通过 `SequentialAgent` 定义了固定且严格的业务流水线（如 `DataPipeline` 的 Ingestion -> Analysis -> Viz -> Summary），确保了核心生产流程的可预测性。
+    *   **动态协调者模式 (Coordinator/Dispatcher Pattern)**：通过 `planner_agent` 作为枢纽，利用 LLM 的意图理解能力将任务派发给专业的 Explorer、Processor 等 Agent。这符合 ADK 推荐的 Hub-and-Spoke 路由架构。
+*   **状态解耦与通信 (Shared Session State)**：
+    *   系统完美遵循了 ADK 中通过 `output_key` 进行跨 Agent 通信的规范（上游输出状态，下游通过 `{}` 模板读取）。这种松耦合设计使得每个 Agent 可以被独立测试和复用。
+
+---
+
+## 2. 存在的不足与架构优化建议
+
+虽然系统具备良好的基础架构，但在处理复杂的 GIS 场景时，在并发管理、容错机制、路由效率和人为干预方面仍存在以下优化空间：
+
+### 2.1 隐患：并发流的时序依赖隐患 (Parallel Fan-Out 误用风险)
+*   **问题描述**：在开启 `PARALLEL_INGESTION` 时，系统使用 `ParallelAgent` 将 `knowledge_agent`（业务知识检索）与 `data_engineering_agent`（数据探查与处理）并行执行。因为这两个分支并发运行，如果 `data_processing_agent` 在进行空间特征处理时需要参考刚刚检索出来的领域规范或计算公式，它将无法获取到（并行状态在合并前互不可见）。
+*   **优化建议**：
+    *   **AgentTool 模式 (推荐)**：将 `knowledge_agent` 从并行的 Peer Agent 降级，使用 ADK 的 `AgentTool` 进行包装。把它作为一种“工具”放入 `data_processing_agent` 的 `tools` 列表里。这样，处理 Agent 在遇到不懂的领域规则时，可以**主动调用**知识 Agent 进行查询，而不是盲目并行。
+    *   或者，如果数据处理强依赖检索到的规范，应放弃这里的 `ParallelAgent`，改回串行架构。
+
+### 2.2 缺失：基于 LoopAgent 的迭代反馈与审查 (Generator-Critic Pattern)
+*   **问题描述**：代码中当前依赖 `after_tool_callback=_self_correction_after_tool` 进行工具报错时的自我修正。但这仅能处理**语法/系统级报错**。在复杂的 GIS 空间计算中，可能代码不报错但业务结果错误（如：多边形自交、指标不达标、破碎度 FFI 异常）。当前直线型的 Pipeline 无法“打回去重做”。
+*   **优化建议**：
+    *   引入 ADK 的 **`LoopAgent`** 结合 **Generator-Critic（生成器-批评家）模式**。
+    *   在 `data_analysis_agent`（生成器）之后增加一个 `quality_checker_agent`（批评家）。
+    *   将它们放入 `LoopAgent` 中：`Analysis` 生成空间布局 -> `Checker` 检验拓扑和约束 -> 如果不达标，`Checker` 触发事件并附带修改意见，循环回到 `Analysis` 修正，直到 `Checker` 判定达标（或达到 `max_iterations`）才跳出循环进入下一步。
+
+### 2.3 性能瓶颈：动态路由带来的 Token 损耗与延迟
+*   **问题描述**：在 `Dynamic Planner` 架构中，`planner_agent` 给所有子 Agent 设置了 `disallow_transfer_to_peers=True`。这意味着子 Agent 执行完毕后，必须将控制权交回给 Planner，由 Planner 的 LLM 决定下一步。这会导致极高的上下文传递开销，仅仅为了让 Planner 做出一个显而易见的决定（如“分析完了，转给 Visualization”）。
+*   **优化建议**：
+    *   **子工作流打包**：对于逻辑上高度粘合的连续动作，不要把它们作为平级的子节点挂在 Planner 下。
+    *   **架构重构**：使用 `SequentialAgent` 将它们组合成子工作流（例如 `Analysis_And_Viz_Workflow`），然后将这个整体挂载给 Planner。Planner 只需要做一次调度，子工作流内部自动串行跑完，大幅降低路由延迟和 Token 消耗。
+
+### 2.4 风险：高价值决策缺少 Human-in-the-Loop (HITL) 机制
+*   **问题描述**：整个数据治理或优化流程是一个“一按到底”的黑盒。GIS 选址或土地性质修改属于高风险业务决策，如果 Agent 执行了不符合现实条件的推演，或者即将向数据库执行破坏性的操作，目前系统缺乏拦截机制。
+*   **优化建议**：
+    *   **PolicyEngine 拦截**：利用 ADK 提供的 `PolicyEngine` 和 `SecurityPlugin` 机制。
+    *   在关键 Agent 或敏感 Tool（如 `commit_spatial_changes`）上设置拦截策略：当准备执行时，`SecurityPlugin` 挂起执行，向外抛出 `PolicyOutcome.CONFIRM` 事件。
+    *   **人工审批**：前端界面弹出一个审批框（例如展示优化前后的对比图），人类分析师点击“批准”后，系统发送 `FunctionResponse` 允许 Agent 继续执行。这不仅提升了系统安全性，也是企业级 AI Agent 的核心特性。