Upload 93 files

.gitattributes

@@ -35,3 +35,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
 app/api/__pycache__/simulation.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text
 app/services/__pycache__/report_agent.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text
+app/app/api/__pycache__/simulation.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text
+app/app/services/__pycache__/report_agent.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text

app/.dockerignore

@@ -0,0 +1,12 @@
+__pycache__
+*.py[cod]
+*.egg-info
+.eggs
+.env
+.venv
+venv
+uploads
+*.log
+.git
+.gitignore
+.pytest_cache

app/.python-version

@@ -0,0 +1 @@
+3.11.9

app/.python-version.txt

@@ -0,0 +1 @@
+3.11.9

app/Dockerfile

@@ -0,0 +1,20 @@
+# MiroFish API — Docker (Hugging Face Spaces, Fly, etc.)
+# Build context must be this backend/ directory (contains app/, wsgi.py, requirements.txt).
+
+FROM python:3.11-slim-bookworm
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+ENV PYTHONUNBUFFERED=1
+EXPOSE 7860
+
+CMD gunicorn --bind "0.0.0.0:${PORT:-7860}" --workers 1 --threads 4 --timeout 600 --worker-tmp-dir /dev/shm wsgi:app

app/HUGGINGFACE_SPACE.md

@@ -0,0 +1,50 @@
+# Hugging Face Spaces — MiroFish API (Docker)
+
+## Create the Space
+
+1. [huggingface.co/spaces](https://huggingface.co/spaces) → **Create new Space**
+2. **SDK**: **Docker**
+3. **Hardware**: CPU (free) — long simulations may OOM or time out; upgrade if needed.
+4. Connect this repo and set the Docker **app directory** to **`backend`** (or copy only `backend/` into a dedicated repo).
+
+### Visibility must be **Public** (important)
+
+If the Space is **Private**, browsers and your static site get **`401` with body `unauthorized`** (plain text) **before** the request reaches Flask.  
+Open **Space → Settings → Visibility** and set **Public** so `https://YOUR-SPACE.hf.space/api/...` works without a Hugging Face login cookie.
+
+Build context = folder that contains `Dockerfile`, `requirements.txt`, `app/`, `wsgi.py`.
+
+## Secrets (Space → Settings → Variables and secrets)
+
+| Variable | Notes |
+|----------|--------|
+| `SECRET_KEY` | Long random string (Flask). |
+| `LLM_API_KEY`, `LLM_BASE_URL`, `LLM_MODEL_NAME` | Your LLM. |
+| `ZEP_API_KEY` | Zep. |
+| `SUPABASE_URL` | `https://xxx.supabase.co` |
+| `SUPABASE_SERVICE_ROLE_KEY` | Service role (never expose to browser). |
+| `PIPELINE_CLIENT_SECRET` | **Same** as website `VITE_PIPELINE_CLIENT_SECRET`. |
+| `SUPABASE_REPORTS_BUCKET` | Default `reports`. |
+| `PIPELINE_MAX_ROUNDS` | Optional integer cap. |
+
+Optional: `SUPABASE_JWT_SECRET` if you use Supabase Auth JWT on the pipeline.
+
+## Website (`website/.env`)
+
+```env
+VITE_API_BASE_URLS=https://YOUR-SPACE.hf.space
+VITE_PIPELINE_CLIENT_SECRET=same-as-PIPELINE_CLIENT_SECRET
+VITE_SUPABASE_URL=https://xxx.supabase.co
+VITE_SUPABASE_ANON_KEY=your_anon_key
+```
+
+Login/sign-up use **Supabase** on `public."User"` — run `supabase/grants_public_user.sql` in the SQL editor.
+
+## Free tier notes
+
+- Space **sleeps** when idle; first request is a cold start.
+- Proxies may **time out** on very long HTTP requests; heavy pipelines may need paid hardware or another host.
+
+## Health check
+
+`GET /health` → `{"status":"ok",...}`

app/Procfile

@@ -0,0 +1 @@
+web: gunicorn --bind 0.0.0.0:$PORT --workers 1 --threads 8 --timeout 600 wsgi:app

app/app/__init__.py

@@ -0,0 +1,108 @@
+"""
+MiroFish Backend - Flask应用工厂
+"""
+
+import os
+import warnings
+
+# 抑制 multiprocessing resource_tracker 的警告（来自第三方库如 transformers）
+# 需要在所有其他导入之前设置
+warnings.filterwarnings("ignore", message=".*resource_tracker.*")
+
+from flask import Flask, request
+from flask_cors import CORS
+
+from .config import Config
+from .services.supabase_jobs import sync_enabled as supabase_sync_enabled
+from .utils.logger import setup_logger, get_logger
+
+
+def create_app(config_class=Config):
+    """Flask应用工厂函数"""
+    app = Flask(__name__)
+    app.config.from_object(config_class)
+    
+    # 设置JSON编码：确保中文直接显示（而不是 \uXXXX 格式）
+    # Flask >= 2.3 使用 app.json.ensure_ascii，旧版本使用 JSON_AS_ASCII 配置
+    if hasattr(app, 'json') and hasattr(app.json, 'ensure_ascii'):
+        app.json.ensure_ascii = False
+    
+    # 设置日志
+    logger = setup_logger('mirofish')
+    
+    # 只在 reloader 子进程中打印启动信息（避免 debug 模式下打印两次）
+    is_reloader_process = os.environ.get('WERKZEUG_RUN_MAIN') == 'true'
+    debug_mode = app.config.get('DEBUG', False)
+    should_log_startup = not debug_mode or is_reloader_process
+    
+    if should_log_startup:
+        logger.info("=" * 50)
+        logger.info("MiroFish Backend 启动中...")
+        logger.info("=" * 50)
+    
+    # CORS: allow custom pipeline auth headers from static sites / other origins
+    CORS(
+        app,
+        resources={
+            r"/api/*": {
+                "origins": "*",
+                "allow_headers": [
+                    "Content-Type",
+                    "Authorization",
+                    "X-Mirofish-User-Id",
+                    "X-Pipeline-Client-Secret",
+                ],
+            }
+        },
+    )
+    
+    # 注册模拟进程清理函数（确保服务器关闭时终止所有模拟进程）
+    from .services.simulation_runner import SimulationRunner
+    SimulationRunner.register_cleanup()
+    if should_log_startup:
+        logger.info("已注册模拟进程清理函数")
+    
+    # 请求日志中间件
+    @app.before_request
+    def log_request():
+        logger = get_logger('mirofish.request')
+        logger.debug(f"请求: {request.method} {request.path}")
+        if request.content_type and 'json' in request.content_type:
+            logger.debug(f"请求体: {request.get_json(silent=True)}")
+    
+    @app.after_request
+    def log_response(response):
+        logger = get_logger('mirofish.request')
+        logger.debug(f"响应: {response.status_code}")
+        return response
+    
+    # 注册蓝图
+    from .api import graph_bp, simulation_bp, report_bp, pipeline_bp, billing_bp
+    app.register_blueprint(graph_bp, url_prefix='/api/graph')
+    app.register_blueprint(simulation_bp, url_prefix='/api/simulation')
+    app.register_blueprint(report_bp, url_prefix='/api/report')
+    app.register_blueprint(pipeline_bp, url_prefix='/api/pipeline')
+    app.register_blueprint(billing_bp, url_prefix='/api/billing')
+    
+    # 健康检查
+    @app.route('/health')
+    def health():
+        return {
+            'status': 'ok',
+            'service': 'MiroFish Backend',
+            'supabase_sync': supabase_sync_enabled(),
+            'pipeline_client_secret_configured': bool((Config.PIPELINE_CLIENT_SECRET or '').strip()),
+        }
+    
+    if should_log_startup:
+        if supabase_sync_enabled():
+            logger.info("Supabase cloud sync: ENABLED (simulation_runs + reports)")
+        else:
+            logger.warning(
+                "Supabase cloud sync: DISABLED — set SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY "
+                "so runs appear in Past simulations and in the database."
+            )
+        logger.info("MiroFish Backend 启动完成")
+    
+    return app
+

app/app/api/__init__.py

@@ -0,0 +1,18 @@
+"""
+API路由模块
+"""
+
+from flask import Blueprint
+
+graph_bp = Blueprint('graph', __name__)
+simulation_bp = Blueprint('simulation', __name__)
+report_bp = Blueprint('report', __name__)
+pipeline_bp = Blueprint('pipeline', __name__)
+billing_bp = Blueprint('billing', __name__)
+
+from . import graph  # noqa: E402, F401
+from . import simulation  # noqa: E402, F401
+from . import report  # noqa: E402, F401
+from . import pipeline  # noqa: E402, F401
+from . import billing  # noqa: E402, F401
+

app/app/api/__pycache__/simulation.cpython-311.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9dce4de5fc345cab32a0ca7867868edae47884de3c0f667c0268cba30c6364d3
+size 108767

app/app/api/billing.py

@@ -0,0 +1,82 @@
+"""Razorpay + coupon unlock for /api/pipeline/start."""
+
+from flask import request, jsonify
+
+from . import billing_bp
+from ..config import Config
+from ..services import billing_service
+from ..utils.logger import get_logger
+
+logger = get_logger("mirofish.api.billing")
+
+
+@billing_bp.route("/status", methods=["GET"])
+def billing_status():
+    if not Config.billing_enabled():
+        return jsonify(
+            {
+                "success": True,
+                "data": {
+                    "enabled": False,
+                    "key_id": None,
+                    "amount": None,
+                    "currency": None,
+                },
+            }
+        )
+    data = {
+        "enabled": True,
+        "key_id": Config.RAZORPAY_KEY_ID or None,
+        "amount": Config.RAZORPAY_AMOUNT_PAISE if Config.RAZORPAY_KEY_SECRET else None,
+        "currency": Config.RAZORPAY_CURRENCY if Config.RAZORPAY_KEY_SECRET else None,
+        "coupons_enabled": bool(Config.payment_coupon_set()),
+    }
+    return jsonify({"success": True, "data": data})
+
+
+@billing_bp.route("/create-order", methods=["POST"])
+def billing_create_order():
+    try:
+        if not (Config.RAZORPAY_KEY_ID and Config.RAZORPAY_KEY_SECRET):
+            return jsonify({"success": False, "error": "Razorpay is not configured"}), 503
+        order = billing_service.create_razorpay_order()
+        return jsonify({"success": True, "data": order})
+    except Exception as e:
+        logger.error("create-order: %s", e)
+        return jsonify({"success": False, "error": str(e)}), 500
+
+
+@billing_bp.route("/verify-payment", methods=["POST"])
+def billing_verify_payment():
+    try:
+        if not (Config.RAZORPAY_KEY_ID and Config.RAZORPAY_KEY_SECRET):
+            return jsonify({"success": False, "error": "Razorpay is not configured"}), 503
+        body = request.get_json(silent=True) or {}
+        oid = (body.get("razorpay_order_id") or "").strip()
+        pid = (body.get("razorpay_payment_id") or "").strip()
+        sig = (body.get("razorpay_signature") or "").strip()
+        if not oid or not pid or not sig:
+            return jsonify({"success": False, "error": "Missing payment fields"}), 400
+        if not billing_service.verify_razorpay_payment_signature(oid, pid, sig):
+            return jsonify({"success": False, "error": "Invalid payment signature"}), 400
+        token = billing_service.issue_simulation_payment_token(via="razorpay")
+        return jsonify({"success": True, "data": {"simulation_payment_token": token}})
+    except Exception as e:
+        logger.error("verify-payment: %s", e)
+        return jsonify({"success": False, "error": str(e)}), 500
+
+
+@billing_bp.route("/apply-coupon", methods=["POST"])
+def billing_apply_coupon():
+    try:
+        if not Config.payment_coupon_set():
+            return jsonify({"success": False, "error": "Coupons are not configured"}), 503
+        body = request.get_json(silent=True) or {}
+        code = body.get("code") or body.get("coupon") or ""
+        if not billing_service.coupon_valid(str(code)):
+            return jsonify({"success": False, "error": "Invalid coupon code"}), 400
+        token = billing_service.issue_simulation_payment_token(via="coupon")
+        return jsonify({"success": True, "data": {"simulation_payment_token": token}})
+    except Exception as e:
+        logger.error("apply-coupon: %s", e)
+        return jsonify({"success": False, "error": str(e)}), 500

app/app/api/graph.py

@@ -0,0 +1,617 @@
+"""
+图谱相关API路由
+采用项目上下文机制，服务端持久化状态
+"""
+
+import os
+import traceback
+import threading
+from flask import request, jsonify
+
+from . import graph_bp
+from ..config import Config
+from ..services.ontology_generator import OntologyGenerator
+from ..services.graph_builder import GraphBuilderService
+from ..services.text_processor import TextProcessor
+from ..utils.file_parser import FileParser
+from ..utils.logger import get_logger
+from ..models.task import TaskManager, TaskStatus
+from ..models.project import ProjectManager, ProjectStatus
+
+# 获取日志器
+logger = get_logger('mirofish.api')
+
+
+def allowed_file(filename: str) -> bool:
+    """检查文件扩展名是否允许"""
+    if not filename or '.' not in filename:
+        return False
+    ext = os.path.splitext(filename)[1].lower().lstrip('.')
+    return ext in Config.ALLOWED_EXTENSIONS
+
+
+# ============== 项目管理接口 ==============
+
+@graph_bp.route('/project/<project_id>', methods=['GET'])
+def get_project(project_id: str):
+    """
+    获取项目详情
+    """
+    project = ProjectManager.get_project(project_id)
+    
+    if not project:
+        return jsonify({
+            "success": False,
+            "error": f"项目不存在: {project_id}"
+        }), 404
+    
+    return jsonify({
+        "success": True,
+        "data": project.to_dict()
+    })
+
+
+@graph_bp.route('/project/list', methods=['GET'])
+def list_projects():
+    """
+    列出所有项目
+    """
+    limit = request.args.get('limit', 50, type=int)
+    projects = ProjectManager.list_projects(limit=limit)
+    
+    return jsonify({
+        "success": True,
+        "data": [p.to_dict() for p in projects],
+        "count": len(projects)
+    })
+
+
+@graph_bp.route('/project/<project_id>', methods=['DELETE'])
+def delete_project(project_id: str):
+    """
+    删除项目
+    """
+    success = ProjectManager.delete_project(project_id)
+    
+    if not success:
+        return jsonify({
+            "success": False,
+            "error": f"项目不存在或删除失败: {project_id}"
+        }), 404
+    
+    return jsonify({
+        "success": True,
+        "message": f"项目已删除: {project_id}"
+    })
+
+
+@graph_bp.route('/project/<project_id>/reset', methods=['POST'])
+def reset_project(project_id: str):
+    """
+    重置项目状态（用于重新构建图谱）
+    """
+    project = ProjectManager.get_project(project_id)
+    
+    if not project:
+        return jsonify({
+            "success": False,
+            "error": f"项目不存在: {project_id}"
+        }), 404
+    
+    # 重置到本体已生成状态
+    if project.ontology:
+        project.status = ProjectStatus.ONTOLOGY_GENERATED
+    else:
+        project.status = ProjectStatus.CREATED
+    
+    project.graph_id = None
+    project.graph_build_task_id = None
+    project.error = None
+    ProjectManager.save_project(project)
+    
+    return jsonify({
+        "success": True,
+        "message": f"项目已重置: {project_id}",
+        "data": project.to_dict()
+    })
+
+
+# ============== 接口1：上传文件并生成本体 ==============
+
+@graph_bp.route('/ontology/generate', methods=['POST'])
+def generate_ontology():
+    """
+    接口1：上传文件，分析生成本体定义
+    
+    请求方式：multipart/form-data
+    
+    参数：
+        files: 上传的文件（PDF/MD/TXT），可多个
+        simulation_requirement: 模拟需求描述（必填）
+        project_name: 项目名称（可选）
+        additional_context: 额外说明（可选）
+        
+    返回：
+        {
+            "success": true,
+            "data": {
+                "project_id": "proj_xxxx",
+                "ontology": {
+                    "entity_types": [...],
+                    "edge_types": [...],
+                    "analysis_summary": "..."
+                },
+                "files": [...],
+                "total_text_length": 12345
+            }
+        }
+    """
+    try:
+        logger.info("=== 开始生成本体定义 ===")
+        
+        # 获取参数
+        simulation_requirement = request.form.get('simulation_requirement', '')
+        project_name = request.form.get('project_name', 'Unnamed Project')
+        additional_context = request.form.get('additional_context', '')
+        
+        logger.debug(f"项目名称: {project_name}")
+        logger.debug(f"模拟需求: {simulation_requirement[:100]}...")
+        
+        if not simulation_requirement:
+            return jsonify({
+                "success": False,
+                "error": "请提供模拟需求描述 (simulation_requirement)"
+            }), 400
+        
+        # 获取上传的文件
+        uploaded_files = request.files.getlist('files')
+        if not uploaded_files or all(not f.filename for f in uploaded_files):
+            return jsonify({
+                "success": False,
+                "error": "请至少上传一个文档文件"
+            }), 400
+        
+        # 创建项目
+        project = ProjectManager.create_project(name=project_name)
+        project.simulation_requirement = simulation_requirement
+        logger.info(f"创建项目: {project.project_id}")
+        
+        # 保存文件并提取文本
+        document_texts = []
+        all_text = ""
+        
+        for file in uploaded_files:
+            if file and file.filename and allowed_file(file.filename):
+                # 保存文件到项目目录
+                file_info = ProjectManager.save_file_to_project(
+                    project.project_id, 
+                    file, 
+                    file.filename
+                )
+                project.files.append({
+                    "filename": file_info["original_filename"],
+                    "size": file_info["size"]
+                })
+                
+                # 提取文本
+                text = FileParser.extract_text(file_info["path"])
+                text = TextProcessor.preprocess_text(text)
+                document_texts.append(text)
+                all_text += f"\n\n=== {file_info['original_filename']} ===\n{text}"
+        
+        if not document_texts:
+            ProjectManager.delete_project(project.project_id)
+            return jsonify({
+                "success": False,
+                "error": "没有成功处理任何文档，请检查文件格式"
+            }), 400
+        
+        # 保存提取的文本
+        project.total_text_length = len(all_text)
+        ProjectManager.save_extracted_text(project.project_id, all_text)
+        logger.info(f"文本提取完成，共 {len(all_text)} 字符")
+        
+        # 生成本体
+        logger.info("调用 LLM 生成本体定义...")
+        generator = OntologyGenerator()
+        ontology = generator.generate(
+            document_texts=document_texts,
+            simulation_requirement=simulation_requirement,
+            additional_context=additional_context if additional_context else None
+        )
+        
+        # 保存本体到项目
+        entity_count = len(ontology.get("entity_types", []))
+        edge_count = len(ontology.get("edge_types", []))
+        logger.info(f"本体生成完成: {entity_count} 个实体类型, {edge_count} 个关系类型")
+        
+        project.ontology = {
+            "entity_types": ontology.get("entity_types", []),
+            "edge_types": ontology.get("edge_types", [])
+        }
+        project.analysis_summary = ontology.get("analysis_summary", "")
+        project.status = ProjectStatus.ONTOLOGY_GENERATED
+        ProjectManager.save_project(project)
+        logger.info(f"=== 本体生成完成 === 项目ID: {project.project_id}")
+        
+        return jsonify({
+            "success": True,
+            "data": {
+                "project_id": project.project_id,
+                "project_name": project.name,
+                "ontology": project.ontology,
+                "analysis_summary": project.analysis_summary,
+                "files": project.files,
+                "total_text_length": project.total_text_length
+            }
+        })
+        
+    except Exception as e:
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+# ============== 接口2：构建图谱 ==============
+
+@graph_bp.route('/build', methods=['POST'])
+def build_graph():
+    """
+    接口2：根据project_id构建图谱
+    
+    请求（JSON）：
+        {
+            "project_id": "proj_xxxx",  // 必填，来自接口1
+            "graph_name": "图谱名称",    // 可选
+            "chunk_size": 500,          // 可选，默认500
+            "chunk_overlap": 50         // 可选，默认50
+        }
+        
+    返回：
+        {
+            "success": true,
+            "data": {
+                "project_id": "proj_xxxx",
+                "task_id": "task_xxxx",
+                "message": "图谱构建任务已启动"
+            }
+        }
+    """
+    try:
+        logger.info("=== 开始构建图谱 ===")
+        
+        # 检查配置
+        errors = []
+        if not Config.ZEP_API_KEY:
+            errors.append("ZEP_API_KEY未配置")
+        if errors:
+            logger.error(f"配置错误: {errors}")
+            return jsonify({
+                "success": False,
+                "error": "配置错误: " + "; ".join(errors)
+            }), 500
+        
+        # 解析请求
+        data = request.get_json() or {}
+        project_id = data.get('project_id')
+        logger.debug(f"请求参数: project_id={project_id}")
+        
+        if not project_id:
+            return jsonify({
+                "success": False,
+                "error": "请提供 project_id"
+            }), 400
+        
+        # 获取项目
+        project = ProjectManager.get_project(project_id)
+        if not project:
+            return jsonify({
+                "success": False,
+                "error": f"项目不存在: {project_id}"
+            }), 404
+        
+        # 检查项目状态
+        force = data.get('force', False)  # 强制重新构建
+        
+        if project.status == ProjectStatus.CREATED:
+            return jsonify({
+                "success": False,
+                "error": "项目尚未生成本体，请先调用 /ontology/generate"
+            }), 400
+        
+        if project.status == ProjectStatus.GRAPH_BUILDING and not force:
+            return jsonify({
+                "success": False,
+                "error": "图谱正在构建中，请勿重复提交。如需强制重建，请添加 force: true",
+                "task_id": project.graph_build_task_id
+            }), 400
+        
+        # 如果强制重建，重置状态
+        if force and project.status in [ProjectStatus.GRAPH_BUILDING, ProjectStatus.FAILED, ProjectStatus.GRAPH_COMPLETED]:
+            project.status = ProjectStatus.ONTOLOGY_GENERATED
+            project.graph_id = None
+            project.graph_build_task_id = None
+            project.error = None
+        
+        # 获取配置
+        graph_name = data.get('graph_name', project.name or 'MiroFish Graph')
+        chunk_size = data.get('chunk_size', project.chunk_size or Config.DEFAULT_CHUNK_SIZE)
+        chunk_overlap = data.get('chunk_overlap', project.chunk_overlap or Config.DEFAULT_CHUNK_OVERLAP)
+        
+        # 更新项目配置
+        project.chunk_size = chunk_size
+        project.chunk_overlap = chunk_overlap
+        
+        # 获取提取的文本
+        text = ProjectManager.get_extracted_text(project_id)
+        if not text:
+            return jsonify({
+                "success": False,
+                "error": "未找到提取的文本内容"
+            }), 400
+        
+        # 获取本体
+        ontology = project.ontology
+        if not ontology:
+            return jsonify({
+                "success": False,
+                "error": "未找到本体定义"
+            }), 400
+        
+        # 创建异步任务
+        task_manager = TaskManager()
+        task_id = task_manager.create_task(f"构建图谱: {graph_name}")
+        logger.info(f"创建图谱构建任务: task_id={task_id}, project_id={project_id}")
+        
+        # 更新项目状态
+        project.status = ProjectStatus.GRAPH_BUILDING
+        project.graph_build_task_id = task_id
+        ProjectManager.save_project(project)
+        
+        # 启动后台任务
+        def build_task():
+            build_logger = get_logger('mirofish.build')
+            try:
+                build_logger.info(f"[{task_id}] 开始构建图谱...")
+                task_manager.update_task(
+                    task_id, 
+                    status=TaskStatus.PROCESSING,
+                    message="初始化图谱构建服务..."
+                )
+                
+                # 创建图谱构建服务
+                builder = GraphBuilderService(api_key=Config.ZEP_API_KEY)
+                
+                # 分块
+                task_manager.update_task(
+                    task_id,
+                    message="文本分块中...",
+                    progress=5
+                )
+                chunks = TextProcessor.split_text(
+                    text, 
+                    chunk_size=chunk_size, 
+                    overlap=chunk_overlap
+                )
+                total_chunks = len(chunks)
+                
+                # 创建图谱
+                task_manager.update_task(
+                    task_id,
+                    message="创建Zep图谱...",
+                    progress=10
+                )
+                graph_id = builder.create_graph(name=graph_name)
+                
+                # 更新项目的graph_id
+                project.graph_id = graph_id
+                ProjectManager.save_project(project)
+                
+                # 设置本体
+                task_manager.update_task(
+                    task_id,
+                    message="设置本体定义...",
+                    progress=15
+                )
+                builder.set_ontology(graph_id, ontology)
+                
+                # 添加文本（progress_callback 签名是 (msg, progress_ratio)）
+                def add_progress_callback(msg, progress_ratio):
+                    progress = 15 + int(progress_ratio * 40)  # 15% - 55%
+                    task_manager.update_task(
+                        task_id,
+                        message=msg,
+                        progress=progress
+                    )
+                
+                task_manager.update_task(
+                    task_id,
+                    message=f"开始添加 {total_chunks} 个文本块...",
+                    progress=15
+                )
+                
+                episode_uuids = builder.add_text_batches(
+                    graph_id, 
+                    chunks,
+                    batch_size=3,
+                    progress_callback=add_progress_callback
+                )
+                
+                # 等待Zep处理完成（查询每个episode的processed状态）
+                task_manager.update_task(
+                    task_id,
+                    message="等待Zep处理数据...",
+                    progress=55
+                )
+                
+                def wait_progress_callback(msg, progress_ratio):
+                    progress = 55 + int(progress_ratio * 35)  # 55% - 90%
+                    task_manager.update_task(
+                        task_id,
+                        message=msg,
+                        progress=progress
+                    )
+                
+                builder._wait_for_episodes(episode_uuids, wait_progress_callback)
+                
+                # 获取图谱数据
+                task_manager.update_task(
+                    task_id,
+                    message="获取图谱数据...",
+                    progress=95
+                )
+                graph_data = builder.get_graph_data(graph_id)
+                
+                # 更新项目状态
+                project.status = ProjectStatus.GRAPH_COMPLETED
+                ProjectManager.save_project(project)
+                
+                node_count = graph_data.get("node_count", 0)
+                edge_count = graph_data.get("edge_count", 0)
+                build_logger.info(f"[{task_id}] 图谱构建完成: graph_id={graph_id}, 节点={node_count}, 边={edge_count}")
+                
+                # 完成
+                task_manager.update_task(
+                    task_id,
+                    status=TaskStatus.COMPLETED,
+                    message="图谱构建完成",
+                    progress=100,
+                    result={
+                        "project_id": project_id,
+                        "graph_id": graph_id,
+                        "node_count": node_count,
+                        "edge_count": edge_count,
+                        "chunk_count": total_chunks
+                    }
+                )
+                
+            except Exception as e:
+                # 更新项目状态为失败
+                build_logger.error(f"[{task_id}] 图谱构建失败: {str(e)}")
+                build_logger.debug(traceback.format_exc())
+                
+                project.status = ProjectStatus.FAILED
+                project.error = str(e)
+                ProjectManager.save_project(project)
+                
+                task_manager.update_task(
+                    task_id,
+                    status=TaskStatus.FAILED,
+                    message=f"构建失败: {str(e)}",
+                    error=traceback.format_exc()
+                )
+        
+        # 启动后台线程
+        thread = threading.Thread(target=build_task, daemon=True)
+        thread.start()
+        
+        return jsonify({
+            "success": True,
+            "data": {
+                "project_id": project_id,
+                "task_id": task_id,
+                "message": "图谱构建任务已启动，请通过 /task/{task_id} 查询进度"
+            }
+        })
+        
+    except Exception as e:
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+# ============== 任务查询接口 ==============
+
+@graph_bp.route('/task/<task_id>', methods=['GET'])
+def get_task(task_id: str):
+    """
+    查询任务状态
+    """
+    task = TaskManager().get_task(task_id)
+    
+    if not task:
+        return jsonify({
+            "success": False,
+            "error": f"任务不存在: {task_id}"
+        }), 404
+    
+    return jsonify({
+        "success": True,
+        "data": task.to_dict()
+    })
+
+
+@graph_bp.route('/tasks', methods=['GET'])
+def list_tasks():
+    """
+    列出所有任务
+    """
+    tasks = TaskManager().list_tasks()
+    
+    return jsonify({
+        "success": True,
+        "data": [t.to_dict() for t in tasks],
+        "count": len(tasks)
+    })
+
+
+# ============== 图谱数据接口 ==============
+
+@graph_bp.route('/data/<graph_id>', methods=['GET'])
+def get_graph_data(graph_id: str):
+    """
+    获取图谱数据（节点和边）
+    """
+    try:
+        if not Config.ZEP_API_KEY:
+            return jsonify({
+                "success": False,
+                "error": "ZEP_API_KEY未配置"
+            }), 500
+        
+        builder = GraphBuilderService(api_key=Config.ZEP_API_KEY)
+        graph_data = builder.get_graph_data(graph_id)
+        
+        return jsonify({
+            "success": True,
+            "data": graph_data
+        })
+        
+    except Exception as e:
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@graph_bp.route('/delete/<graph_id>', methods=['DELETE'])
+def delete_graph(graph_id: str):
+    """
+    删除Zep图谱
+    """
+    try:
+        if not Config.ZEP_API_KEY:
+            return jsonify({
+                "success": False,
+                "error": "ZEP_API_KEY未配置"
+            }), 500
+        
+        builder = GraphBuilderService(api_key=Config.ZEP_API_KEY)
+        builder.delete_graph(graph_id)
+        
+        return jsonify({
+            "success": True,
+            "message": f"图谱已删除: {graph_id}"
+        })
+        
+    except Exception as e:
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500

app/app/api/pipeline.py

@@ -0,0 +1,230 @@
+"""
+One-shot pipeline API for the website: upload text + requirement → full automation → report.
+
+When Supabase sync is configured (URL + service role), records runs + reports.
+Identify users: Bearer JWT (Mirofish / Supabase Auth) or X-Mirofish-User-Id + X-Pipeline-Client-Secret.
+"""
+
+import threading
+import traceback
+import uuid
+
+from flask import request, jsonify
+
+from . import pipeline_bp
+from ..models.task import TaskManager, TaskStatus
+from ..services.pipeline_orchestrator import run_full_pipeline
+from ..services.supabase_jobs import (
+    get_run_row_for_user,
+    insert_pending_run,
+    list_simulation_runs_for_user,
+    signed_url_for_storage_path,
+    sync_enabled,
+)
+from ..config import Config
+from ..services.billing_service import verify_simulation_payment_token
+from ..utils.logger import get_logger
+from ..utils.supabase_auth import resolve_pipeline_user_id
+
+logger = get_logger("mirofish.api.pipeline")
+
+ALLOWED = {"txt", "md", "text"}
+
+
+def _allowed(name: str) -> bool:
+    if not name or "." not in name:
+        return False
+    ext = name.rsplit(".", 1)[-1].lower()
+    return ext in ALLOWED
+
+
+@pipeline_bp.route("/start", methods=["POST"])
+def pipeline_start():
+    """
+    multipart/form-data:
+      - file: .txt (or .md) reality seed
+      - simulation_requirement: string
+
+    When Supabase sync is enabled: Bearer JWT (optional) or headers
+    X-Mirofish-User-Id + X-Pipeline-Client-Secret (same secret as PIPELINE_CLIENT_SECRET).
+
+    Returns { task_id, simulation_run_id? }.
+    """
+    try:
+        simulation_requirement = ""
+        document_text = ""
+        filename = "seed.txt"
+
+        if request.content_type and "multipart/form-data" in request.content_type:
+            simulation_requirement = (request.form.get("simulation_requirement") or "").strip()
+            f = request.files.get("file")
+            if not f or not f.filename:
+                return jsonify({"success": False, "error": "Missing file"}), 400
+            if not _allowed(f.filename):
+                return jsonify(
+                    {"success": False, "error": "Only .txt or .md files are allowed for this endpoint"}
+                ), 400
+            filename = f.filename
+            raw = f.read()
+            try:
+                document_text = raw.decode("utf-8")
+            except UnicodeDecodeError:
+                document_text = raw.decode("utf-8", errors="replace")
+        else:
+            data = request.get_json(silent=True) or {}
+            simulation_requirement = (data.get("simulation_requirement") or "").strip()
+            document_text = (data.get("document_text") or "").strip()
+            filename = (data.get("filename") or "seed.txt").strip() or "seed.txt"
+            if not document_text:
+                return jsonify({"success": False, "error": "document_text is required"}), 400
+
+        if not simulation_requirement:
+            return jsonify({"success": False, "error": "simulation_requirement is required"}), 400
+        if len(document_text.strip()) < 10:
+            return jsonify({"success": False, "error": "Document text is too short"}), 400
+
+        if Config.billing_enabled():
+            if request.content_type and "multipart/form-data" in request.content_type:
+                pay_tok = (request.form.get("simulation_payment_token") or "").strip()
+            else:
+                _jd = request.get_json(silent=True) or {}
+                pay_tok = (_jd.get("simulation_payment_token") or "").strip()
+            if not verify_simulation_payment_token(pay_tok):
+                return jsonify(
+                    {
+                        "success": False,
+                        "error": "Complete payment or apply a valid coupon before starting a simulation.",
+                    }
+                ), 402
+
+        user_id = None
+        simulation_run_id = None
+        if sync_enabled():
+            uid, err = resolve_pipeline_user_id()
+            if err or not uid:
+                return jsonify({"success": False, "error": err or "Unauthorized"}), 401
+            user_id = uid
+            simulation_run_id = str(uuid.uuid4())
+
+        tm = TaskManager()
+        task_id = tm.create_task(
+            task_type="full_pipeline",
+            metadata={
+                "filename": filename,
+                "simulation_run_id": simulation_run_id,
+                "user_id": user_id,
+            },
+        )
+        tm.update_task(
+            task_id,
+            status=TaskStatus.PROCESSING,
+            progress=1,
+            message="Pipeline queued…",
+        )
+
+        if sync_enabled() and simulation_run_id and user_id:
+            try:
+                insert_pending_run(
+                    simulation_run_id=simulation_run_id,
+                    user_id=user_id,
+                    backend_task_id=task_id,
+                    requirement_preview=simulation_requirement,
+                )
+            except Exception as e:
+                logger.error("Supabase insert_pending_run: %s", e)
+                tm.fail_task(task_id, f"Could not record run: {e}")
+                return jsonify({"success": False, "error": str(e)}), 500
+
+        def worker():
+            run_full_pipeline(
+                simulation_requirement=simulation_requirement,
+                document_text=document_text,
+                source_filename=filename,
+                task_id=task_id,
+                task_manager=tm,
+                simulation_run_id=simulation_run_id,
+                user_id=user_id,
+            )
+
+        threading.Thread(target=worker, daemon=True).start()
+
+        sync = sync_enabled()
+        payload = {
+            "task_id": task_id,
+            "supabase_sync": sync,
+            "message": (
+                "Simulation started. Runs are saved to Supabase when cloud sync is enabled."
+                if sync
+                else "Simulation started. Cloud sync is OFF — add SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY on the server to record runs in Past simulations."
+            ),
+        }
+        if simulation_run_id:
+            payload["simulation_run_id"] = simulation_run_id
+
+        if sync:
+            logger.info(
+                "pipeline/start task=%s simulation_run_id=%s user_id=%s",
+                task_id,
+                simulation_run_id,
+                user_id,
+            )
+        else:
+            logger.warning(
+                "pipeline/start task=%s without Supabase sync — no simulation_runs row (set SUPABASE_* env)",
+                task_id,
+            )
+
+        return jsonify({"success": True, "data": payload})
+    except Exception as e:
+        logger.error(traceback.format_exc())
+        return jsonify({"success": False, "error": str(e)}), 500
+
+
+@pipeline_bp.route("/status/<task_id>", methods=["GET"])
+def pipeline_status(task_id: str):
+    tm = TaskManager()
+    task = tm.get_task(task_id)
+    if not task:
+        return jsonify({"success": False, "error": "Unknown task_id"}), 404
+    out = task.to_dict()
+    return jsonify({"success": True, "data": out})
+
+
+@pipeline_bp.route("/runs", methods=["GET"])
+def pipeline_list_runs():
+    """List simulation_runs for the authenticated user (service role query on server)."""
+    try:
+        if not sync_enabled():
+            return jsonify({"success": True, "data": {"runs": [], "supabase_sync": False}})
+        uid, err = resolve_pipeline_user_id()
+        if err or not uid:
+            return jsonify({"success": False, "error": err or "Unauthorized"}), 401
+        runs = list_simulation_runs_for_user(user_id=uid)
+        return jsonify({"success": True, "data": {"runs": runs, "supabase_sync": True}})
+    except Exception as e:
+        logger.error(traceback.format_exc())
+        return jsonify({"success": False, "error": str(e)}), 500
+
+
+@pipeline_bp.route("/runs/<run_id>/signed-download", methods=["GET"])
+def pipeline_signed_report_download(run_id: str):
+    """Return a time-limited signed URL for the report object in Storage."""
+    try:
+        if not sync_enabled():
+            return jsonify({"success": False, "error": "Sync not configured"}), 503
+        uid, err = resolve_pipeline_user_id()
+        if err or not uid:
+            return jsonify({"success": False, "error": err or "Unauthorized"}), 401
+        row = get_run_row_for_user(run_id=run_id, user_id=uid)
+        if not row:
+            return jsonify({"success": False, "error": "Run not found"}), 404
+        path = row.get("report_storage_path") or ""
+        if not path:
+            return jsonify({"success": False, "error": "Report not ready"}), 400
+        url = signed_url_for_storage_path(storage_path=path, expires_sec=3600)
+        if not url:
+            return jsonify({"success": False, "error": "Could not create download link"}), 500
+        return jsonify({"success": True, "data": {"signed_url": url}})
+    except Exception as e:
+        logger.error(traceback.format_exc())
+        return jsonify({"success": False, "error": str(e)}), 500

app/app/api/report.py

@@ -0,0 +1,1015 @@
+"""
+Report API路由
+提供模拟报告生成、获取、对话等接口
+"""
+
+import os
+import traceback
+import threading
+from flask import request, jsonify, send_file
+
+from . import report_bp
+from ..config import Config
+from ..services.report_agent import ReportAgent, ReportManager, ReportStatus
+from ..services.simulation_manager import SimulationManager
+from ..models.project import ProjectManager
+from ..models.task import TaskManager, TaskStatus
+from ..utils.logger import get_logger
+
+logger = get_logger('mirofish.api.report')
+
+
+# ============== 报告生成接口 ==============
+
+@report_bp.route('/generate', methods=['POST'])
+def generate_report():
+    """
+    生成模拟分析报告（异步任务）
+    
+    这是一个耗时操作，接口会立即返回task_id，
+    使用 GET /api/report/generate/status 查询进度
+    
+    请求（JSON）：
+        {
+            "simulation_id": "sim_xxxx",    // 必填，模拟ID
+            "force_regenerate": false        // 可选，强制重新生成
+        }
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "simulation_id": "sim_xxxx",
+                "task_id": "task_xxxx",
+                "status": "generating",
+                "message": "报告生成任务已启动"
+            }
+        }
+    """
+    try:
+        data = request.get_json() or {}
+        
+        simulation_id = data.get('simulation_id')
+        if not simulation_id:
+            return jsonify({
+                "success": False,
+                "error": "请提供 simulation_id"
+            }), 400
+        
+        force_regenerate = data.get('force_regenerate', False)
+        
+        # 获取模拟信息
+        manager = SimulationManager()
+        state = manager.get_simulation(simulation_id)
+        
+        if not state:
+            return jsonify({
+                "success": False,
+                "error": f"模拟不存在: {simulation_id}"
+            }), 404
+        
+        # 检查是否已有报告
+        if not force_regenerate:
+            existing_report = ReportManager.get_report_by_simulation(simulation_id)
+            if existing_report and existing_report.status == ReportStatus.COMPLETED:
+                return jsonify({
+                    "success": True,
+                    "data": {
+                        "simulation_id": simulation_id,
+                        "report_id": existing_report.report_id,
+                        "status": "completed",
+                        "message": "报告已存在",
+                        "already_generated": True
+                    }
+                })
+        
+        # 获取项目信息
+        project = ProjectManager.get_project(state.project_id)
+        if not project:
+            return jsonify({
+                "success": False,
+                "error": f"项目不存在: {state.project_id}"
+            }), 404
+        
+        graph_id = state.graph_id or project.graph_id
+        if not graph_id:
+            return jsonify({
+                "success": False,
+                "error": "缺少图谱ID，请确保已构建图谱"
+            }), 400
+        
+        simulation_requirement = project.simulation_requirement
+        if not simulation_requirement:
+            return jsonify({
+                "success": False,
+                "error": "缺少模拟需求描述"
+            }), 400
+        
+        # 提前生成 report_id，以便立即返回给前端
+        import uuid
+        report_id = f"report_{uuid.uuid4().hex[:12]}"
+        
+        # 创建异步任务
+        task_manager = TaskManager()
+        task_id = task_manager.create_task(
+            task_type="report_generate",
+            metadata={
+                "simulation_id": simulation_id,
+                "graph_id": graph_id,
+                "report_id": report_id
+            }
+        )
+        
+        # 定义后台任务
+        def run_generate():
+            try:
+                task_manager.update_task(
+                    task_id,
+                    status=TaskStatus.PROCESSING,
+                    progress=0,
+                    message="初始化Report Agent..."
+                )
+                
+                # 创建Report Agent
+                agent = ReportAgent(
+                    graph_id=graph_id,
+                    simulation_id=simulation_id,
+                    simulation_requirement=simulation_requirement
+                )
+                
+                # 进度回调
+                def progress_callback(stage, progress, message):
+                    task_manager.update_task(
+                        task_id,
+                        progress=progress,
+                        message=f"[{stage}] {message}"
+                    )
+                
+                # 生成报告（传入预先生成的 report_id）
+                report = agent.generate_report(
+                    progress_callback=progress_callback,
+                    report_id=report_id
+                )
+                
+                # 保存报告
+                ReportManager.save_report(report)
+                
+                if report.status == ReportStatus.COMPLETED:
+                    task_manager.complete_task(
+                        task_id,
+                        result={
+                            "report_id": report.report_id,
+                            "simulation_id": simulation_id,
+                            "status": "completed"
+                        }
+                    )
+                else:
+                    task_manager.fail_task(task_id, report.error or "报告生成失败")
+                
+            except Exception as e:
+                logger.error(f"报告生成失败: {str(e)}")
+                task_manager.fail_task(task_id, str(e))
+        
+        # 启动后台线程
+        thread = threading.Thread(target=run_generate, daemon=True)
+        thread.start()
+        
+        return jsonify({
+            "success": True,
+            "data": {
+                "simulation_id": simulation_id,
+                "report_id": report_id,
+                "task_id": task_id,
+                "status": "generating",
+                "message": "报告生成任务已启动，请通过 /api/report/generate/status 查询进度",
+                "already_generated": False
+            }
+        })
+        
+    except Exception as e:
+        logger.error(f"启动报告生成任务失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@report_bp.route('/generate/status', methods=['POST'])
+def get_generate_status():
+    """
+    查询报告生成任务进度
+    
+    请求（JSON）：
+        {
+            "task_id": "task_xxxx",         // 可选，generate返回的task_id
+            "simulation_id": "sim_xxxx"     // 可选，模拟ID
+        }
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "task_id": "task_xxxx",
+                "status": "processing|completed|failed",
+                "progress": 45,
+                "message": "..."
+            }
+        }
+    """
+    try:
+        data = request.get_json() or {}
+        
+        task_id = data.get('task_id')
+        simulation_id = data.get('simulation_id')
+        
+        # 如果提供了simulation_id，先检查是否已有完成的报告
+        if simulation_id:
+            existing_report = ReportManager.get_report_by_simulation(simulation_id)
+            if existing_report and existing_report.status == ReportStatus.COMPLETED:
+                return jsonify({
+                    "success": True,
+                    "data": {
+                        "simulation_id": simulation_id,
+                        "report_id": existing_report.report_id,
+                        "status": "completed",
+                        "progress": 100,
+                        "message": "报告已生成",
+                        "already_completed": True
+                    }
+                })
+        
+        if not task_id:
+            return jsonify({
+                "success": False,
+                "error": "请提供 task_id 或 simulation_id"
+            }), 400
+        
+        task_manager = TaskManager()
+        task = task_manager.get_task(task_id)
+        
+        if not task:
+            return jsonify({
+                "success": False,
+                "error": f"任务不存在: {task_id}"
+            }), 404
+        
+        return jsonify({
+            "success": True,
+            "data": task.to_dict()
+        })
+        
+    except Exception as e:
+        logger.error(f"查询任务状态失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e)
+        }), 500
+
+
+# ============== 报告获取接口 ==============
+
+@report_bp.route('/<report_id>', methods=['GET'])
+def get_report(report_id: str):
+    """
+    获取报告详情
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "report_id": "report_xxxx",
+                "simulation_id": "sim_xxxx",
+                "status": "completed",
+                "outline": {...},
+                "markdown_content": "...",
+                "created_at": "...",
+                "completed_at": "..."
+            }
+        }
+    """
+    try:
+        report = ReportManager.get_report(report_id)
+        
+        if not report:
+            return jsonify({
+                "success": False,
+                "error": f"报告不存在: {report_id}"
+            }), 404
+        
+        return jsonify({
+            "success": True,
+            "data": report.to_dict()
+        })
+        
+    except Exception as e:
+        logger.error(f"获取报告失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@report_bp.route('/by-simulation/<simulation_id>', methods=['GET'])
+def get_report_by_simulation(simulation_id: str):
+    """
+    根据模拟ID获取报告
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "report_id": "report_xxxx",
+                ...
+            }
+        }
+    """
+    try:
+        report = ReportManager.get_report_by_simulation(simulation_id)
+        
+        if not report:
+            return jsonify({
+                "success": False,
+                "error": f"该模拟暂无报告: {simulation_id}",
+                "has_report": False
+            }), 404
+        
+        return jsonify({
+            "success": True,
+            "data": report.to_dict(),
+            "has_report": True
+        })
+        
+    except Exception as e:
+        logger.error(f"获取报告失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@report_bp.route('/list', methods=['GET'])
+def list_reports():
+    """
+    列出所有报告
+    
+    Query参数：
+        simulation_id: 按模拟ID过滤（可选）
+        limit: 返回数量限制（默认50）
+    
+    返回：
+        {
+            "success": true,
+            "data": [...],
+            "count": 10
+        }
+    """
+    try:
+        simulation_id = request.args.get('simulation_id')
+        limit = request.args.get('limit', 50, type=int)
+        
+        reports = ReportManager.list_reports(
+            simulation_id=simulation_id,
+            limit=limit
+        )
+        
+        return jsonify({
+            "success": True,
+            "data": [r.to_dict() for r in reports],
+            "count": len(reports)
+        })
+        
+    except Exception as e:
+        logger.error(f"列出报告失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@report_bp.route('/<report_id>/download', methods=['GET'])
+def download_report(report_id: str):
+    """
+    下载报告（Markdown格式）
+    
+    返回Markdown文件
+    """
+    try:
+        report = ReportManager.get_report(report_id)
+        
+        if not report:
+            return jsonify({
+                "success": False,
+                "error": f"报告不存在: {report_id}"
+            }), 404
+        
+        md_path = ReportManager._get_report_markdown_path(report_id)
+        
+        if not os.path.exists(md_path):
+            # 如果MD文件不存在，生成一个临时文件
+            import tempfile
+            with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f:
+                f.write(report.markdown_content)
+                temp_path = f.name
+            
+            return send_file(
+                temp_path,
+                as_attachment=True,
+                download_name=f"{report_id}.md"
+            )
+        
+        return send_file(
+            md_path,
+            as_attachment=True,
+            download_name=f"{report_id}.md"
+        )
+        
+    except Exception as e:
+        logger.error(f"下载报告失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@report_bp.route('/<report_id>', methods=['DELETE'])
+def delete_report(report_id: str):
+    """删除报告"""
+    try:
+        success = ReportManager.delete_report(report_id)
+        
+        if not success:
+            return jsonify({
+                "success": False,
+                "error": f"报告不存在: {report_id}"
+            }), 404
+        
+        return jsonify({
+            "success": True,
+            "message": f"报告已删除: {report_id}"
+        })
+        
+    except Exception as e:
+        logger.error(f"删除报告失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+# ============== Report Agent对话接口 ==============
+
+@report_bp.route('/chat', methods=['POST'])
+def chat_with_report_agent():
+    """
+    与Report Agent对话
+    
+    Report Agent可以在对话中自主调用检索工具来回答问题
+    
+    请求（JSON）：
+        {
+            "simulation_id": "sim_xxxx",        // 必填，模拟ID
+            "message": "请解释一下舆情走向",    // 必填，用户消息
+            "chat_history": [                   // 可选，对话历史
+                {"role": "user", "content": "..."},
+                {"role": "assistant", "content": "..."}
+            ]
+        }
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "response": "Agent回复...",
+                "tool_calls": [调用的工具列表],
+                "sources": [信息来源]
+            }
+        }
+    """
+    try:
+        data = request.get_json() or {}
+        
+        simulation_id = data.get('simulation_id')
+        message = data.get('message')
+        chat_history = data.get('chat_history', [])
+        
+        if not simulation_id:
+            return jsonify({
+                "success": False,
+                "error": "请提供 simulation_id"
+            }), 400
+        
+        if not message:
+            return jsonify({
+                "success": False,
+                "error": "请提供 message"
+            }), 400
+        
+        # 获取模拟和项目信息
+        manager = SimulationManager()
+        state = manager.get_simulation(simulation_id)
+        
+        if not state:
+            return jsonify({
+                "success": False,
+                "error": f"模拟不存在: {simulation_id}"
+            }), 404
+        
+        project = ProjectManager.get_project(state.project_id)
+        if not project:
+            return jsonify({
+                "success": False,
+                "error": f"项目不存在: {state.project_id}"
+            }), 404
+        
+        graph_id = state.graph_id or project.graph_id
+        if not graph_id:
+            return jsonify({
+                "success": False,
+                "error": "缺少图谱ID"
+            }), 400
+        
+        simulation_requirement = project.simulation_requirement or ""
+        
+        # 创建Agent并进行对话
+        agent = ReportAgent(
+            graph_id=graph_id,
+            simulation_id=simulation_id,
+            simulation_requirement=simulation_requirement
+        )
+        
+        result = agent.chat(message=message, chat_history=chat_history)
+        
+        return jsonify({
+            "success": True,
+            "data": result
+        })
+        
+    except Exception as e:
+        logger.error(f"对话失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+# ============== 报告进度与分章节接口 ==============
+
+@report_bp.route('/<report_id>/progress', methods=['GET'])
+def get_report_progress(report_id: str):
+    """
+    获取报告生成进度（实时）
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "status": "generating",
+                "progress": 45,
+                "message": "正在生成章节: 关键发现",
+                "current_section": "关键发现",
+                "completed_sections": ["执行摘要", "模拟背景"],
+                "updated_at": "2025-12-09T..."
+            }
+        }
+    """
+    try:
+        progress = ReportManager.get_progress(report_id)
+        
+        if not progress:
+            return jsonify({
+                "success": False,
+                "error": f"报告不存在或进度信息不可用: {report_id}"
+            }), 404
+        
+        return jsonify({
+            "success": True,
+            "data": progress
+        })
+        
+    except Exception as e:
+        logger.error(f"获取报告进度失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@report_bp.route('/<report_id>/sections', methods=['GET'])
+def get_report_sections(report_id: str):
+    """
+    获取已生成的章节列表（分章节输出）
+    
+    前端可以轮询此接口获取已生成的章节内容，无需等待整个报告完成
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "report_id": "report_xxxx",
+                "sections": [
+                    {
+                        "filename": "section_01.md",
+                        "section_index": 1,
+                        "content": "## 执行摘要\\n\\n..."
+                    },
+                    ...
+                ],
+                "total_sections": 3,
+                "is_complete": false
+            }
+        }
+    """
+    try:
+        sections = ReportManager.get_generated_sections(report_id)
+        
+        # 获取报告状态
+        report = ReportManager.get_report(report_id)
+        is_complete = report is not None and report.status == ReportStatus.COMPLETED
+        
+        return jsonify({
+            "success": True,
+            "data": {
+                "report_id": report_id,
+                "sections": sections,
+                "total_sections": len(sections),
+                "is_complete": is_complete
+            }
+        })
+        
+    except Exception as e:
+        logger.error(f"获取章节列表失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@report_bp.route('/<report_id>/section/<int:section_index>', methods=['GET'])
+def get_single_section(report_id: str, section_index: int):
+    """
+    获取单个章节内容
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "filename": "section_01.md",
+                "content": "## 执行摘要\\n\\n..."
+            }
+        }
+    """
+    try:
+        section_path = ReportManager._get_section_path(report_id, section_index)
+        
+        if not os.path.exists(section_path):
+            return jsonify({
+                "success": False,
+                "error": f"章节不存在: section_{section_index:02d}.md"
+            }), 404
+        
+        with open(section_path, 'r', encoding='utf-8') as f:
+            content = f.read()
+        
+        return jsonify({
+            "success": True,
+            "data": {
+                "filename": f"section_{section_index:02d}.md",
+                "section_index": section_index,
+                "content": content
+            }
+        })
+        
+    except Exception as e:
+        logger.error(f"获取章节内容失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+# ============== 报告状态检查接口 ==============
+
+@report_bp.route('/check/<simulation_id>', methods=['GET'])
+def check_report_status(simulation_id: str):
+    """
+    检查模拟是否有报告，以及报告状态
+    
+    用于前端判断是否解锁Interview功能
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "simulation_id": "sim_xxxx",
+                "has_report": true,
+                "report_status": "completed",
+                "report_id": "report_xxxx",
+                "interview_unlocked": true
+            }
+        }
+    """
+    try:
+        report = ReportManager.get_report_by_simulation(simulation_id)
+        
+        has_report = report is not None
+        report_status = report.status.value if report else None
+        report_id = report.report_id if report else None
+        
+        # 只有报告完成后才解锁interview
+        interview_unlocked = has_report and report.status == ReportStatus.COMPLETED
+        
+        return jsonify({
+            "success": True,
+            "data": {
+                "simulation_id": simulation_id,
+                "has_report": has_report,
+                "report_status": report_status,
+                "report_id": report_id,
+                "interview_unlocked": interview_unlocked
+            }
+        })
+        
+    except Exception as e:
+        logger.error(f"检查报告状态失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+# ============== Agent 日志接口 ==============
+
+@report_bp.route('/<report_id>/agent-log', methods=['GET'])
+def get_agent_log(report_id: str):
+    """
+    获取 Report Agent 的详细执行日志
+    
+    实时获取报告生成过程中的每一步动作，包括：
+    - 报告开始、规划开始/完成
+    - 每个章节的开始、工具调用、LLM响应、完成
+    - 报告完成或失败
+    
+    Query参数：
+        from_line: 从第几行开始读取（可选，默认0，用于增量获取）
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "logs": [
+                    {
+                        "timestamp": "2025-12-13T...",
+                        "elapsed_seconds": 12.5,
+                        "report_id": "report_xxxx",
+                        "action": "tool_call",
+                        "stage": "generating",
+                        "section_title": "执行摘要",
+                        "section_index": 1,
+                        "details": {
+                            "tool_name": "insight_forge",
+                            "parameters": {...},
+                            ...
+                        }
+                    },
+                    ...
+                ],
+                "total_lines": 25,
+                "from_line": 0,
+                "has_more": false
+            }
+        }
+    """
+    try:
+        from_line = request.args.get('from_line', 0, type=int)
+        
+        log_data = ReportManager.get_agent_log(report_id, from_line=from_line)
+        
+        return jsonify({
+            "success": True,
+            "data": log_data
+        })
+        
+    except Exception as e:
+        logger.error(f"获取Agent日志失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@report_bp.route('/<report_id>/agent-log/stream', methods=['GET'])
+def stream_agent_log(report_id: str):
+    """
+    获取完整的 Agent 日志（一次性获取全部）
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "logs": [...],
+                "count": 25
+            }
+        }
+    """
+    try:
+        logs = ReportManager.get_agent_log_stream(report_id)
+        
+        return jsonify({
+            "success": True,
+            "data": {
+                "logs": logs,
+                "count": len(logs)
+            }
+        })
+        
+    except Exception as e:
+        logger.error(f"获取Agent日志失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+# ============== 控制台日志接口 ==============
+
+@report_bp.route('/<report_id>/console-log', methods=['GET'])
+def get_console_log(report_id: str):
+    """
+    获取 Report Agent 的控制台输出日志
+    
+    实时获取报告生成过程中的控制台输出（INFO、WARNING等），
+    这与 agent-log 接口返回的结构化 JSON 日志不同，
+    是纯文本格式的控制台风格日志。
+    
+    Query参数：
+        from_line: 从第几行开始读取（可选，默认0，用于增量获取）
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "logs": [
+                    "[19:46:14] INFO: 搜索完成: 找到 15 条相关事实",
+                    "[19:46:14] INFO: 图谱搜索: graph_id=xxx, query=...",
+                    ...
+                ],
+                "total_lines": 100,
+                "from_line": 0,
+                "has_more": false
+            }
+        }
+    """
+    try:
+        from_line = request.args.get('from_line', 0, type=int)
+        
+        log_data = ReportManager.get_console_log(report_id, from_line=from_line)
+        
+        return jsonify({
+            "success": True,
+            "data": log_data
+        })
+        
+    except Exception as e:
+        logger.error(f"获取控制台日志失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@report_bp.route('/<report_id>/console-log/stream', methods=['GET'])
+def stream_console_log(report_id: str):
+    """
+    获取完整的控制台日志（一次性获取全部）
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "logs": [...],
+                "count": 100
+            }
+        }
+    """
+    try:
+        logs = ReportManager.get_console_log_stream(report_id)
+        
+        return jsonify({
+            "success": True,
+            "data": {
+                "logs": logs,
+                "count": len(logs)
+            }
+        })
+        
+    except Exception as e:
+        logger.error(f"获取控制台日志失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+# ============== 工具调用接口（供调试使用）==============
+
+@report_bp.route('/tools/search', methods=['POST'])
+def search_graph_tool():
+    """
+    图谱搜索工具接口（供调试使用）
+    
+    请求（JSON）：
+        {
+            "graph_id": "mirofish_xxxx",
+            "query": "搜索查询",
+            "limit": 10
+        }
+    """
+    try:
+        data = request.get_json() or {}
+        
+        graph_id = data.get('graph_id')
+        query = data.get('query')
+        limit = data.get('limit', 10)
+        
+        if not graph_id or not query:
+            return jsonify({
+                "success": False,
+                "error": "请提供 graph_id 和 query"
+            }), 400
+        
+        from ..services.zep_tools import ZepToolsService
+        
+        tools = ZepToolsService()
+        result = tools.search_graph(
+            graph_id=graph_id,
+            query=query,
+            limit=limit
+        )
+        
+        return jsonify({
+            "success": True,
+            "data": result.to_dict()
+        })
+        
+    except Exception as e:
+        logger.error(f"图谱搜索失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@report_bp.route('/tools/statistics', methods=['POST'])
+def get_graph_statistics_tool():
+    """
+    图谱统计工具接口（供调试使用）
+    
+    请求（JSON）：
+        {
+            "graph_id": "mirofish_xxxx"
+        }
+    """
+    try:
+        data = request.get_json() or {}
+        
+        graph_id = data.get('graph_id')
+        
+        if not graph_id:
+            return jsonify({
+                "success": False,
+                "error": "请提供 graph_id"
+            }), 400
+        
+        from ..services.zep_tools import ZepToolsService
+        
+        tools = ZepToolsService()
+        result = tools.get_graph_statistics(graph_id)
+        
+        return jsonify({
+            "success": True,
+            "data": result
+        })
+        
+    except Exception as e:
+        logger.error(f"获取图谱统计失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500

app/app/api/simulation.py

@@ -0,0 +1,2718 @@
+"""
+模拟相关API路由
+Step2: Zep实体读取与过滤、OASIS模拟准备与运行（全程自动化）
+"""
+
+import os
+import traceback
+from flask import request, jsonify, send_file
+
+from . import simulation_bp
+from ..config import Config
+from ..services.zep_entity_reader import ZepEntityReader
+from ..services.oasis_profile_generator import OasisProfileGenerator
+from ..services.simulation_manager import SimulationManager, SimulationStatus
+from ..services.simulation_runner import SimulationRunner, RunnerStatus
+from ..utils.logger import get_logger
+from ..models.project import ProjectManager
+
+logger = get_logger('mirofish.api.simulation')
+
+
+# Interview prompt 优化前缀
+# 添加此前缀可以避免Agent调用工具，直接用文本回复。
+# Startup validation: agents stay in persona (investor, founder, customer, skeptic, etc.).
+INTERVIEW_PROMPT_PREFIX = (
+    "Stay in character using your persona, memories, and past actions. Do not call any tools—reply in plain text only. "
+    "You are in a startup idea validation simulation: respond in character only "
+    "(e.g. VC, angel, YC-style partner, picky investor, peer founder, buyer, undecided user). "
+    "Ground answers in your persona and the simulated discussion, not generic advice.\n\n"
+    "Question: "
+)
+
+
+def optimize_interview_prompt(prompt: str) -> str:
+    """
+    优化Interview提问，添加前缀避免Agent调用工具
+    
+    Args:
+        prompt: 原始提问
+        
+    Returns:
+        优化后的提问
+    """
+    if not prompt:
+        return prompt
+    # 避免重复添加前缀
+    if prompt.startswith(INTERVIEW_PROMPT_PREFIX):
+        return prompt
+    return f"{INTERVIEW_PROMPT_PREFIX}{prompt}"
+
+
+# ============== 实体读取接口 ==============
+
+@simulation_bp.route('/entities/<graph_id>', methods=['GET'])
+def get_graph_entities(graph_id: str):
+    """
+    获取图谱中的所有实体（已过滤）
+    
+    只返回符合预定义实体类型的节点（Labels不只是Entity的节点）
+    
+    Query参数：
+        entity_types: 逗号分隔的实体类型列表（可选，用于进一步过滤）
+        enrich: 是否获取相关边信息（默认true）
+    """
+    try:
+        if not Config.ZEP_API_KEY:
+            return jsonify({
+                "success": False,
+                "error": "ZEP_API_KEY未配置"
+            }), 500
+        
+        entity_types_str = request.args.get('entity_types', '')
+        entity_types = [t.strip() for t in entity_types_str.split(',') if t.strip()] if entity_types_str else None
+        enrich = request.args.get('enrich', 'true').lower() == 'true'
+        
+        logger.info(f"获取图谱实体: graph_id={graph_id}, entity_types={entity_types}, enrich={enrich}")
+        
+        reader = ZepEntityReader()
+        result = reader.filter_defined_entities(
+            graph_id=graph_id,
+            defined_entity_types=entity_types,
+            enrich_with_edges=enrich
+        )
+        
+        return jsonify({
+            "success": True,
+            "data": result.to_dict()
+        })
+        
+    except Exception as e:
+        logger.error(f"获取图谱实体失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/entities/<graph_id>/<entity_uuid>', methods=['GET'])
+def get_entity_detail(graph_id: str, entity_uuid: str):
+    """获取单个实体的详细信息"""
+    try:
+        if not Config.ZEP_API_KEY:
+            return jsonify({
+                "success": False,
+                "error": "ZEP_API_KEY未配置"
+            }), 500
+        
+        reader = ZepEntityReader()
+        entity = reader.get_entity_with_context(graph_id, entity_uuid)
+        
+        if not entity:
+            return jsonify({
+                "success": False,
+                "error": f"实体不存在: {entity_uuid}"
+            }), 404
+        
+        return jsonify({
+            "success": True,
+            "data": entity.to_dict()
+        })
+        
+    except Exception as e:
+        logger.error(f"获取实体详情失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/entities/<graph_id>/by-type/<entity_type>', methods=['GET'])
+def get_entities_by_type(graph_id: str, entity_type: str):
+    """获取指定类型的所有实体"""
+    try:
+        if not Config.ZEP_API_KEY:
+            return jsonify({
+                "success": False,
+                "error": "ZEP_API_KEY未配置"
+            }), 500
+        
+        enrich = request.args.get('enrich', 'true').lower() == 'true'
+        
+        reader = ZepEntityReader()
+        entities = reader.get_entities_by_type(
+            graph_id=graph_id,
+            entity_type=entity_type,
+            enrich_with_edges=enrich
+        )
+        
+        return jsonify({
+            "success": True,
+            "data": {
+                "entity_type": entity_type,
+                "count": len(entities),
+                "entities": [e.to_dict() for e in entities]
+            }
+        })
+        
+    except Exception as e:
+        logger.error(f"获取实体失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+# ============== 模拟管理接口 ==============
+
+@simulation_bp.route('/create', methods=['POST'])
+def create_simulation():
+    """
+    创建新的模拟
+    
+    注意：max_rounds等参数由LLM智能生成，无需手动设置
+    
+    请求（JSON）：
+        {
+            "project_id": "proj_xxxx",      // 必填
+            "graph_id": "mirofish_xxxx",    // 可选，如不提供则从project获取
+            "enable_twitter": true,          // 可选，默认true
+            "enable_reddit": true            // 可选，默认true
+        }
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "simulation_id": "sim_xxxx",
+                "project_id": "proj_xxxx",
+                "graph_id": "mirofish_xxxx",
+                "status": "created",
+                "enable_twitter": true,
+                "enable_reddit": true,
+                "created_at": "2025-12-01T10:00:00"
+            }
+        }
+    """
+    try:
+        data = request.get_json() or {}
+        
+        project_id = data.get('project_id')
+        if not project_id:
+            return jsonify({
+                "success": False,
+                "error": "请提供 project_id"
+            }), 400
+        
+        project = ProjectManager.get_project(project_id)
+        if not project:
+            return jsonify({
+                "success": False,
+                "error": f"项目不存在: {project_id}"
+            }), 404
+        
+        graph_id = data.get('graph_id') or project.graph_id
+        if not graph_id:
+            return jsonify({
+                "success": False,
+                "error": "项目尚未构建图谱，请先调用 /api/graph/build"
+            }), 400
+        
+        manager = SimulationManager()
+        state = manager.create_simulation(
+            project_id=project_id,
+            graph_id=graph_id,
+            enable_twitter=data.get('enable_twitter', True),
+            enable_reddit=data.get('enable_reddit', True),
+        )
+        
+        return jsonify({
+            "success": True,
+            "data": state.to_dict()
+        })
+        
+    except Exception as e:
+        logger.error(f"创建模拟失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+def _check_simulation_prepared(simulation_id: str) -> tuple:
+    """
+    检查模拟是否已经准备完成
+    
+    检查条件：
+    1. state.json 存在且 status 为 "ready"
+    2. 必要文件存在：reddit_profiles.json, twitter_profiles.csv, simulation_config.json
+    
+    注意：运行脚本(run_*.py)保留在 backend/scripts/ 目录，不再复制到模拟目录
+    
+    Args:
+        simulation_id: 模拟ID
+        
+    Returns:
+        (is_prepared: bool, info: dict)
+    """
+    import os
+    from ..config import Config
+    
+    simulation_dir = os.path.join(Config.OASIS_SIMULATION_DATA_DIR, simulation_id)
+    
+    # 检查目录是否存在
+    if not os.path.exists(simulation_dir):
+        return False, {"reason": "模拟目录不存在"}
+    
+    # 必要文件列表（不包括脚本，脚本位于 backend/scripts/）
+    required_files = [
+        "state.json",
+        "simulation_config.json",
+        "reddit_profiles.json",
+        "twitter_profiles.csv"
+    ]
+    
+    # 检查文件是否存在
+    existing_files = []
+    missing_files = []
+    for f in required_files:
+        file_path = os.path.join(simulation_dir, f)
+        if os.path.exists(file_path):
+            existing_files.append(f)
+        else:
+            missing_files.append(f)
+    
+    if missing_files:
+        return False, {
+            "reason": "缺少必要文件",
+            "missing_files": missing_files,
+            "existing_files": existing_files
+        }
+    
+    # 检查state.json中的状态
+    state_file = os.path.join(simulation_dir, "state.json")
+    try:
+        import json
+        with open(state_file, 'r', encoding='utf-8') as f:
+            state_data = json.load(f)
+        
+        status = state_data.get("status", "")
+        config_generated = state_data.get("config_generated", False)
+        
+        # 详细日志
+        logger.debug(f"检测模拟准备状态: {simulation_id}, status={status}, config_generated={config_generated}")
+        
+        # 如果 config_generated=True 且文件存在，认为准备完成
+        # 以下���态都说明准备工作已完成：
+        # - ready: 准备完成，可以运行
+        # - preparing: 如果 config_generated=True 说明已完成
+        # - running: 正在运行，说明准备早就完成了
+        # - completed: 运行完成，说明准备早就完成了
+        # - stopped: 已停止，说明准备早就完成了
+        # - failed: 运行失败（但准备是完成的）
+        prepared_statuses = ["ready", "preparing", "running", "completed", "stopped", "failed"]
+        if status in prepared_statuses and config_generated:
+            # 获取文件统计信息
+            profiles_file = os.path.join(simulation_dir, "reddit_profiles.json")
+            config_file = os.path.join(simulation_dir, "simulation_config.json")
+            
+            profiles_count = 0
+            if os.path.exists(profiles_file):
+                with open(profiles_file, 'r', encoding='utf-8') as f:
+                    profiles_data = json.load(f)
+                    profiles_count = len(profiles_data) if isinstance(profiles_data, list) else 0
+            
+            # 如果状态是preparing但文件已完成，自动更新状态为ready
+            if status == "preparing":
+                try:
+                    state_data["status"] = "ready"
+                    from datetime import datetime
+                    state_data["updated_at"] = datetime.now().isoformat()
+                    with open(state_file, 'w', encoding='utf-8') as f:
+                        json.dump(state_data, f, ensure_ascii=False, indent=2)
+                    logger.info(f"自动更新模拟状态: {simulation_id} preparing -> ready")
+                    status = "ready"
+                except Exception as e:
+                    logger.warning(f"自动更新状态失败: {e}")
+            
+            logger.info(f"模拟 {simulation_id} 检测结果: 已准备完成 (status={status}, config_generated={config_generated})")
+            return True, {
+                "status": status,
+                "entities_count": state_data.get("entities_count", 0),
+                "profiles_count": profiles_count,
+                "entity_types": state_data.get("entity_types", []),
+                "config_generated": config_generated,
+                "created_at": state_data.get("created_at"),
+                "updated_at": state_data.get("updated_at"),
+                "existing_files": existing_files
+            }
+        else:
+            logger.warning(f"模拟 {simulation_id} 检测结果: 未准备完成 (status={status}, config_generated={config_generated})")
+            return False, {
+                "reason": f"状态不在已准备列表中或config_generated为false: status={status}, config_generated={config_generated}",
+                "status": status,
+                "config_generated": config_generated
+            }
+            
+    except Exception as e:
+        return False, {"reason": f"读取状态文件失败: {str(e)}"}
+
+
+@simulation_bp.route('/prepare', methods=['POST'])
+def prepare_simulation():
+    """
+    准备模拟环境（异步任务，LLM智能生成所有参数）
+    
+    这是一个耗时操作，接口会立即返回task_id，
+    使用 GET /api/simulation/prepare/status 查询进度
+    
+    特性：
+    - 自动检测已完成的准备工作，避免重复生成
+    - 如果已准备完成，直接返回已有结果
+    - 支持强制重新生成（force_regenerate=true）
+    
+    步骤：
+    1. 检查是否已有完成的准备工作
+    2. 从Zep图谱读取并过滤实体
+    3. 为每个实体生成OASIS Agent Profile（带重试机制）
+    4. LLM智能生成模拟配置（带重试机制）
+    5. 保存配置文件和预设脚本
+    
+    请求（JSON）：
+        {
+            "simulation_id": "sim_xxxx",                   // 必填，模拟ID
+            "entity_types": ["Student", "PublicFigure"],  // 可选，指定实体类型
+            "use_llm_for_profiles": true,                 // 可选，是否用LLM生成人设
+            "parallel_profile_count": 5,                  // 可选，并行生成人设数量，默认5
+            "force_regenerate": false                     // 可选，强制重新生成，默认false
+        }
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "simulation_id": "sim_xxxx",
+                "task_id": "task_xxxx",           // 新任务时返回
+                "status": "preparing|ready",
+                "message": "准备任务已启动|已有完成的准备工作",
+                "already_prepared": true|false    // 是否已准备完成
+            }
+        }
+    """
+    import threading
+    import os
+    from ..models.task import TaskManager, TaskStatus
+    from ..config import Config
+    
+    try:
+        data = request.get_json() or {}
+        
+        simulation_id = data.get('simulation_id')
+        if not simulation_id:
+            return jsonify({
+                "success": False,
+                "error": "请提供 simulation_id"
+            }), 400
+        
+        manager = SimulationManager()
+        state = manager.get_simulation(simulation_id)
+        
+        if not state:
+            return jsonify({
+                "success": False,
+                "error": f"模拟不存在: {simulation_id}"
+            }), 404
+        
+        # 检查是否强制重新生成
+        force_regenerate = data.get('force_regenerate', False)
+        logger.info(f"开始处理 /prepare 请求: simulation_id={simulation_id}, force_regenerate={force_regenerate}")
+        
+        # 检查是否已经准备完成（避免重复生成）
+        if not force_regenerate:
+            logger.debug(f"检查模拟 {simulation_id} 是否已准备完成...")
+            is_prepared, prepare_info = _check_simulation_prepared(simulation_id)
+            logger.debug(f"检查结果: is_prepared={is_prepared}, prepare_info={prepare_info}")
+            if is_prepared:
+                logger.info(f"模拟 {simulation_id} 已准备完成，跳过重复生成")
+                return jsonify({
+                    "success": True,
+                    "data": {
+                        "simulation_id": simulation_id,
+                        "status": "ready",
+                        "message": "已有完成的准备工作，无需重复生成",
+                        "already_prepared": True,
+                        "prepare_info": prepare_info
+                    }
+                })
+            else:
+                logger.info(f"模拟 {simulation_id} 未准备完成，将启动准备任务")
+        
+        # 从项目获取必要信息
+        project = ProjectManager.get_project(state.project_id)
+        if not project:
+            return jsonify({
+                "success": False,
+                "error": f"项目不存在: {state.project_id}"
+            }), 404
+        
+        # 获取模拟需求
+        simulation_requirement = project.simulation_requirement or ""
+        if not simulation_requirement:
+            return jsonify({
+                "success": False,
+                "error": "项目缺少模拟需求描述 (simulation_requirement)"
+            }), 400
+        
+        # 获取文档文本
+        document_text = ProjectManager.get_extracted_text(state.project_id) or ""
+        
+        entity_types_list = data.get('entity_types')
+        use_llm_for_profiles = data.get('use_llm_for_profiles', True)
+        parallel_profile_count = data.get('parallel_profile_count', 5)
+        
+        # ========== 同步获取实体数量（在后台任务启动前） ==========
+        # 这样前端在调用prepare后立即就能获取到预期Agent总数
+        try:
+            logger.info(f"同步获取实体数量: graph_id={state.graph_id}")
+            reader = ZepEntityReader()
+            # 快速读取实体（不需要边信息，只统计数量）
+            filtered_preview = reader.filter_defined_entities(
+                graph_id=state.graph_id,
+                defined_entity_types=entity_types_list,
+                enrich_with_edges=False  # 不获取边信息，加快速度
+            )
+            # 保存实体数量到状态（供前端立即获取）
+            state.entities_count = filtered_preview.filtered_count
+            state.entity_types = list(filtered_preview.entity_types)
+            logger.info(f"预期实体数量: {filtered_preview.filtered_count}, 类型: {filtered_preview.entity_types}")
+        except Exception as e:
+            logger.warning(f"同步获取实体数量失败（将在后台任务中重试）: {e}")
+            # 失败不影响后续流程，后台任务会重新获取
+        
+        # 创建异步任务
+        task_manager = TaskManager()
+        task_id = task_manager.create_task(
+            task_type="simulation_prepare",
+            metadata={
+                "simulation_id": simulation_id,
+                "project_id": state.project_id
+            }
+        )
+        
+        # 更新模拟状态（包含预先获取的实体数量）
+        state.status = SimulationStatus.PREPARING
+        manager._save_simulation_state(state)
+        
+        # 定义后台任务
+        def run_prepare():
+            try:
+                task_manager.update_task(
+                    task_id,
+                    status=TaskStatus.PROCESSING,
+                    progress=0,
+                    message="开始准备模拟环境..."
+                )
+                
+                # 准备模拟（带进度回调）
+                # 存储阶段进度详情
+                stage_details = {}
+                
+                def progress_callback(stage, progress, message, **kwargs):
+                    # 计算总进度
+                    stage_weights = {
+                        "reading": (0, 20),           # 0-20%
+                        "generating_profiles": (20, 70),  # 20-70%
+                        "generating_config": (70, 90),    # 70-90%
+                        "copying_scripts": (90, 100)       # 90-100%
+                    }
+                    
+                    start, end = stage_weights.get(stage, (0, 100))
+                    current_progress = int(start + (end - start) * progress / 100)
+                    
+                    # 构建详细进度信息
+                    stage_names = {
+                        "reading": "读取图谱实体",
+                        "generating_profiles": "生成Agent人设",
+                        "generating_config": "生成模拟配置",
+                        "copying_scripts": "准备模拟脚本"
+                    }
+                    
+                    stage_index = list(stage_weights.keys()).index(stage) + 1 if stage in stage_weights else 1
+                    total_stages = len(stage_weights)
+                    
+                    # 更新阶段详情
+                    stage_details[stage] = {
+                        "stage_name": stage_names.get(stage, stage),
+                        "stage_progress": progress,
+                        "current": kwargs.get("current", 0),
+                        "total": kwargs.get("total", 0),
+                        "item_name": kwargs.get("item_name", "")
+                    }
+                    
+                    # 构建详细进度信息
+                    detail = stage_details[stage]
+                    progress_detail_data = {
+                        "current_stage": stage,
+                        "current_stage_name": stage_names.get(stage, stage),
+                        "stage_index": stage_index,
+                        "total_stages": total_stages,
+                        "stage_progress": progress,
+                        "current_item": detail["current"],
+                        "total_items": detail["total"],
+                        "item_description": message
+                    }
+                    
+                    # 构建简洁消息
+                    if detail["total"] > 0:
+                        detailed_message = (
+                            f"[{stage_index}/{total_stages}] {stage_names.get(stage, stage)}: "
+                            f"{detail['current']}/{detail['total']} - {message}"
+                        )
+                    else:
+                        detailed_message = f"[{stage_index}/{total_stages}] {stage_names.get(stage, stage)}: {message}"
+                    
+                    task_manager.update_task(
+                        task_id,
+                        progress=current_progress,
+                        message=detailed_message,
+                        progress_detail=progress_detail_data
+                    )
+                
+                result_state = manager.prepare_simulation(
+                    simulation_id=simulation_id,
+                    simulation_requirement=simulation_requirement,
+                    document_text=document_text,
+                    defined_entity_types=entity_types_list,
+                    use_llm_for_profiles=use_llm_for_profiles,
+                    progress_callback=progress_callback,
+                    parallel_profile_count=parallel_profile_count
+                )
+                
+                # 任务完成
+                task_manager.complete_task(
+                    task_id,
+                    result=result_state.to_simple_dict()
+                )
+                
+            except Exception as e:
+                logger.error(f"准备模拟失败: {str(e)}")
+                task_manager.fail_task(task_id, str(e))
+                
+                # 更新模拟状态为失败
+                state = manager.get_simulation(simulation_id)
+                if state:
+                    state.status = SimulationStatus.FAILED
+                    state.error = str(e)
+                    manager._save_simulation_state(state)
+        
+        # 启动后台线程
+        thread = threading.Thread(target=run_prepare, daemon=True)
+        thread.start()
+        
+        return jsonify({
+            "success": True,
+            "data": {
+                "simulation_id": simulation_id,
+                "task_id": task_id,
+                "status": "preparing",
+                "message": "准备任务已启动，请通过 /api/simulation/prepare/status 查询进度",
+                "already_prepared": False,
+                "expected_entities_count": state.entities_count,  # 预期的Agent总数
+                "entity_types": state.entity_types  # 实体类型列表
+            }
+        })
+        
+    except ValueError as e:
+        return jsonify({
+            "success": False,
+            "error": str(e)
+        }), 404
+        
+    except Exception as e:
+        logger.error(f"启动准备任务失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/prepare/status', methods=['POST'])
+def get_prepare_status():
+    """
+    查询准备��务进度
+    
+    支持两种查询方式：
+    1. 通过task_id查询正在进行的任务进度
+    2. 通过simulation_id检查是否已有完成的准备工作
+    
+    请求（JSON）：
+        {
+            "task_id": "task_xxxx",          // 可选，prepare返回的task_id
+            "simulation_id": "sim_xxxx"      // 可选，模拟ID（用于检查已完成的准备）
+        }
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "task_id": "task_xxxx",
+                "status": "processing|completed|ready",
+                "progress": 45,
+                "message": "...",
+                "already_prepared": true|false,  // 是否已有完成的准备
+                "prepare_info": {...}            // 已准备完成时的详细信息
+            }
+        }
+    """
+    from ..models.task import TaskManager
+    
+    try:
+        data = request.get_json() or {}
+        
+        task_id = data.get('task_id')
+        simulation_id = data.get('simulation_id')
+        
+        # 如果提供了simulation_id，先检查是否已准备完成
+        if simulation_id:
+            is_prepared, prepare_info = _check_simulation_prepared(simulation_id)
+            if is_prepared:
+                return jsonify({
+                    "success": True,
+                    "data": {
+                        "simulation_id": simulation_id,
+                        "status": "ready",
+                        "progress": 100,
+                        "message": "已有完成的准备工作",
+                        "already_prepared": True,
+                        "prepare_info": prepare_info
+                    }
+                })
+        
+        # 如果没有task_id，返回错误
+        if not task_id:
+            if simulation_id:
+                # 有simulation_id但未准备完成
+                return jsonify({
+                    "success": True,
+                    "data": {
+                        "simulation_id": simulation_id,
+                        "status": "not_started",
+                        "progress": 0,
+                        "message": "尚未开始准备，请调用 /api/simulation/prepare 开始",
+                        "already_prepared": False
+                    }
+                })
+            return jsonify({
+                "success": False,
+                "error": "请提供 task_id 或 simulation_id"
+            }), 400
+        
+        task_manager = TaskManager()
+        task = task_manager.get_task(task_id)
+        
+        if not task:
+            # 任务不存在，但如果有simulation_id，检查是否已准备完成
+            if simulation_id:
+                is_prepared, prepare_info = _check_simulation_prepared(simulation_id)
+                if is_prepared:
+                    return jsonify({
+                        "success": True,
+                        "data": {
+                            "simulation_id": simulation_id,
+                            "task_id": task_id,
+                            "status": "ready",
+                            "progress": 100,
+                            "message": "任务已完成（准备工作已存在）",
+                            "already_prepared": True,
+                            "prepare_info": prepare_info
+                        }
+                    })
+            
+            return jsonify({
+                "success": False,
+                "error": f"任务不存在: {task_id}"
+            }), 404
+        
+        task_dict = task.to_dict()
+        task_dict["already_prepared"] = False
+        
+        return jsonify({
+            "success": True,
+            "data": task_dict
+        })
+        
+    except Exception as e:
+        logger.error(f"查询任务状态失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e)
+        }), 500
+
+
+@simulation_bp.route('/<simulation_id>', methods=['GET'])
+def get_simulation(simulation_id: str):
+    """获取模拟状态"""
+    try:
+        manager = SimulationManager()
+        state = manager.get_simulation(simulation_id)
+        
+        if not state:
+            return jsonify({
+                "success": False,
+                "error": f"模拟不存在: {simulation_id}"
+            }), 404
+        
+        result = state.to_dict()
+        
+        # 如果模拟已准备好，附加运行说明
+        if state.status == SimulationStatus.READY:
+            result["run_instructions"] = manager.get_run_instructions(simulation_id)
+        
+        return jsonify({
+            "success": True,
+            "data": result
+        })
+        
+    except Exception as e:
+        logger.error(f"获取模拟状态失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/list', methods=['GET'])
+def list_simulations():
+    """
+    列出所有模拟
+    
+    Query参数：
+        project_id: 按项目ID过滤（可选）
+    """
+    try:
+        project_id = request.args.get('project_id')
+        
+        manager = SimulationManager()
+        simulations = manager.list_simulations(project_id=project_id)
+        
+        return jsonify({
+            "success": True,
+            "data": [s.to_dict() for s in simulations],
+            "count": len(simulations)
+        })
+        
+    except Exception as e:
+        logger.error(f"列出模拟失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+def _get_report_id_for_simulation(simulation_id: str) -> str:
+    """
+    获取 simulation 对应的最新 report_id
+    
+    遍历 reports 目录，找出 simulation_id 匹配的 report，
+    如果有多个则返回最新的（按 created_at 排序）
+    
+    Args:
+        simulation_id: 模拟ID
+        
+    Returns:
+        report_id 或 None
+    """
+    import json
+    from datetime import datetime
+    
+    # reports 目录路径：backend/uploads/reports
+    # __file__ 是 app/api/simulation.py，需要向上两级到 backend/
+    reports_dir = os.path.join(os.path.dirname(__file__), '../../uploads/reports')
+    if not os.path.exists(reports_dir):
+        return None
+    
+    matching_reports = []
+    
+    try:
+        for report_folder in os.listdir(reports_dir):
+            report_path = os.path.join(reports_dir, report_folder)
+            if not os.path.isdir(report_path):
+                continue
+            
+            meta_file = os.path.join(report_path, "meta.json")
+            if not os.path.exists(meta_file):
+                continue
+            
+            try:
+                with open(meta_file, 'r', encoding='utf-8') as f:
+                    meta = json.load(f)
+                
+                if meta.get("simulation_id") == simulation_id:
+                    matching_reports.append({
+                        "report_id": meta.get("report_id"),
+                        "created_at": meta.get("created_at", ""),
+                        "status": meta.get("status", "")
+                    })
+            except Exception:
+                continue
+        
+        if not matching_reports:
+            return None
+        
+        # 按创建时间倒序排序，返回最新的
+        matching_reports.sort(key=lambda x: x.get("created_at", ""), reverse=True)
+        return matching_reports[0].get("report_id")
+        
+    except Exception as e:
+        logger.warning(f"查找 simulation {simulation_id} 的 report 失败: {e}")
+        return None
+
+
+@simulation_bp.route('/history', methods=['GET'])
+def get_simulation_history():
+    """
+    获取历史模拟列表（带项目详情）
+    
+    用于首页历史项目展示，返回包含项目名称、描述等丰富信息的模拟列表
+    
+    Query参数：
+        limit: 返回数量限制（默认20）
+    
+    返回：
+        {
+            "success": true,
+            "data": [
+                {
+                    "simulation_id": "sim_xxxx",
+                    "project_id": "proj_xxxx",
+                    "project_name": "武大舆情分析",
+                    "simulation_requirement": "如果武汉大学发布...",
+                    "status": "completed",
+                    "entities_count": 68,
+                    "profiles_count": 68,
+                    "entity_types": ["Student", "Professor", ...],
+                    "created_at": "2024-12-10",
+                    "updated_at": "2024-12-10",
+                    "total_rounds": 120,
+                    "current_round": 120,
+                    "report_id": "report_xxxx",
+                    "version": "v1.0.2"
+                },
+                ...
+            ],
+            "count": 7
+        }
+    """
+    try:
+        limit = request.args.get('limit', 20, type=int)
+        
+        manager = SimulationManager()
+        simulations = manager.list_simulations()[:limit]
+        
+        # 增强模拟数据，只从 Simulation 文件读取
+        enriched_simulations = []
+        for sim in simulations:
+            sim_dict = sim.to_dict()
+            
+            # 获取模拟配置信息（从 simulation_config.json 读取 simulation_requirement）
+            config = manager.get_simulation_config(sim.simulation_id)
+            if config:
+                sim_dict["simulation_requirement"] = config.get("simulation_requirement", "")
+                time_config = config.get("time_config", {})
+                sim_dict["total_simulation_hours"] = time_config.get("total_simulation_hours", 0)
+                # 推荐轮数（后备值）
+                recommended_rounds = int(
+                    time_config.get("total_simulation_hours", 0) * 60 / 
+                    max(time_config.get("minutes_per_round", 60), 1)
+                )
+            else:
+                sim_dict["simulation_requirement"] = ""
+                sim_dict["total_simulation_hours"] = 0
+                recommended_rounds = 0
+            
+            # 获取运行状态（从 run_state.json 读取用户设置的实际轮数）
+            run_state = SimulationRunner.get_run_state(sim.simulation_id)
+            if run_state:
+                sim_dict["current_round"] = run_state.current_round
+                sim_dict["runner_status"] = run_state.runner_status.value
+                # 使用用户设置的 total_rounds，若无则使用推荐轮数
+                sim_dict["total_rounds"] = run_state.total_rounds if run_state.total_rounds > 0 else recommended_rounds
+            else:
+                sim_dict["current_round"] = 0
+                sim_dict["runner_status"] = "idle"
+                sim_dict["total_rounds"] = recommended_rounds
+            
+            # 获取关联项目的文件列表（最多3个）
+            project = ProjectManager.get_project(sim.project_id)
+            if project and hasattr(project, 'files') and project.files:
+                sim_dict["files"] = [
+                    {"filename": f.get("filename", "未知文件")} 
+                    for f in project.files[:3]
+                ]
+            else:
+                sim_dict["files"] = []
+            
+            # 获取关联的 report_id（查找该 simulation 最新的 report）
+            sim_dict["report_id"] = _get_report_id_for_simulation(sim.simulation_id)
+            
+            # 添加版本号
+            sim_dict["version"] = "v1.0.2"
+            
+            # 格式化日期
+            try:
+                created_date = sim_dict.get("created_at", "")[:10]
+                sim_dict["created_date"] = created_date
+            except:
+                sim_dict["created_date"] = ""
+            
+            enriched_simulations.append(sim_dict)
+        
+        return jsonify({
+            "success": True,
+            "data": enriched_simulations,
+            "count": len(enriched_simulations)
+        })
+        
+    except Exception as e:
+        logger.error(f"获取历史模拟失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/<simulation_id>/profiles', methods=['GET'])
+def get_simulation_profiles(simulation_id: str):
+    """
+    获取模拟的Agent Profile
+    
+    Query参数：
+        platform: 平台类型（reddit/twitter，默认reddit）
+    """
+    try:
+        platform = request.args.get('platform', 'reddit')
+        
+        manager = SimulationManager()
+        profiles = manager.get_profiles(simulation_id, platform=platform)
+        
+        return jsonify({
+            "success": True,
+            "data": {
+                "platform": platform,
+                "count": len(profiles),
+                "profiles": profiles
+            }
+        })
+        
+    except ValueError as e:
+        return jsonify({
+            "success": False,
+            "error": str(e)
+        }), 404
+        
+    except Exception as e:
+        logger.error(f"获取Profile失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/<simulation_id>/profiles/realtime', methods=['GET'])
+def get_simulation_profiles_realtime(simulation_id: str):
+    """
+    实时获取模拟的Agent Profile（用于在生成过程中实时查看进度）
+    
+    与 /profiles 接口的区别：
+    - 直接读取文件，不经过 SimulationManager
+    - 适用于生成过程中的实时查看
+    - 返回额外的元数据（如文件修改时间、是否正在生成等）
+    
+    Query参数：
+        platform: 平台类型（reddit/twitter，默认reddit）
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "simulation_id": "sim_xxxx",
+                "platform": "reddit",
+                "count": 15,
+                "total_expected": 93,  // 预期总数（如果有）
+                "is_generating": true,  // 是否正在生成
+                "file_exists": true,
+                "file_modified_at": "2025-12-04T18:20:00",
+                "profiles": [...]
+            }
+        }
+    """
+    import json
+    import csv
+    from datetime import datetime
+    
+    try:
+        platform = request.args.get('platform', 'reddit')
+        
+        # 获取模拟目录
+        sim_dir = os.path.join(Config.OASIS_SIMULATION_DATA_DIR, simulation_id)
+        
+        if not os.path.exists(sim_dir):
+            return jsonify({
+                "success": False,
+                "error": f"模拟不存在: {simulation_id}"
+            }), 404
+        
+        # 确定文件路径
+        if platform == "reddit":
+            profiles_file = os.path.join(sim_dir, "reddit_profiles.json")
+        else:
+            profiles_file = os.path.join(sim_dir, "twitter_profiles.csv")
+        
+        # 检查文件是否存在
+        file_exists = os.path.exists(profiles_file)
+        profiles = []
+        file_modified_at = None
+        
+        if file_exists:
+            # 获取文件修改时间
+            file_stat = os.stat(profiles_file)
+            file_modified_at = datetime.fromtimestamp(file_stat.st_mtime).isoformat()
+            
+            try:
+                if platform == "reddit":
+                    with open(profiles_file, 'r', encoding='utf-8') as f:
+                        profiles = json.load(f)
+                else:
+                    with open(profiles_file, 'r', encoding='utf-8') as f:
+                        reader = csv.DictReader(f)
+                        profiles = list(reader)
+            except (json.JSONDecodeError, Exception) as e:
+                logger.warning(f"读取 profiles 文件失败（可能正在写入中）: {e}")
+                profiles = []
+        
+        # 检查是否正在生成（通过 state.json 判断）
+        is_generating = False
+        total_expected = None
+        
+        state_file = os.path.join(sim_dir, "state.json")
+        if os.path.exists(state_file):
+            try:
+                with open(state_file, 'r', encoding='utf-8') as f:
+                    state_data = json.load(f)
+                    status = state_data.get("status", "")
+                    is_generating = status == "preparing"
+                    total_expected = state_data.get("entities_count")
+            except Exception:
+                pass
+        
+        return jsonify({
+            "success": True,
+            "data": {
+                "simulation_id": simulation_id,
+                "platform": platform,
+                "count": len(profiles),
+                "total_expected": total_expected,
+                "is_generating": is_generating,
+                "file_exists": file_exists,
+                "file_modified_at": file_modified_at,
+                "profiles": profiles
+            }
+        })
+        
+    except Exception as e:
+        logger.error(f"实时获取Profile失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/<simulation_id>/config/realtime', methods=['GET'])
+def get_simulation_config_realtime(simulation_id: str):
+    """
+    实时获取模拟配置（用于在生成过程中实时查看进度）
+    
+    与 /config 接口的区别：
+    - 直接读取文件，不经过 SimulationManager
+    - 适用于生成过程中的实时查看
+    - 返回额外的元数据（如文件修改时间、是否正在生成等）
+    - 即使配置还没生成完也能返回部分信息
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "simulation_id": "sim_xxxx",
+                "file_exists": true,
+                "file_modified_at": "2025-12-04T18:20:00",
+                "is_generating": true,  // 是否正在生成
+                "generation_stage": "generating_config",  // 当前生成阶段
+                "config": {...}  // 配置内容（如果存在）
+            }
+        }
+    """
+    import json
+    from datetime import datetime
+    
+    try:
+        # 获取模拟目录
+        sim_dir = os.path.join(Config.OASIS_SIMULATION_DATA_DIR, simulation_id)
+        
+        if not os.path.exists(sim_dir):
+            return jsonify({
+                "success": False,
+                "error": f"模拟不存在: {simulation_id}"
+            }), 404
+        
+        # 配置文件路径
+        config_file = os.path.join(sim_dir, "simulation_config.json")
+        
+        # 检查文件是否存在
+        file_exists = os.path.exists(config_file)
+        config = None
+        file_modified_at = None
+        
+        if file_exists:
+            # 获取文件修改时间
+            file_stat = os.stat(config_file)
+            file_modified_at = datetime.fromtimestamp(file_stat.st_mtime).isoformat()
+            
+            try:
+                with open(config_file, 'r', encoding='utf-8') as f:
+                    config = json.load(f)
+            except (json.JSONDecodeError, Exception) as e:
+                logger.warning(f"读取 config 文件失败（可能正在写入中）: {e}")
+                config = None
+        
+        # 检查是否正在生成（通过 state.json 判断）
+        is_generating = False
+        generation_stage = None
+        config_generated = False
+        
+        state_file = os.path.join(sim_dir, "state.json")
+        if os.path.exists(state_file):
+            try:
+                with open(state_file, 'r', encoding='utf-8') as f:
+                    state_data = json.load(f)
+                    status = state_data.get("status", "")
+                    is_generating = status == "preparing"
+                    config_generated = state_data.get("config_generated", False)
+                    
+                    # 判断当前阶段
+                    if is_generating:
+                        if state_data.get("profiles_generated", False):
+                            generation_stage = "generating_config"
+                        else:
+                            generation_stage = "generating_profiles"
+                    elif status == "ready":
+                        generation_stage = "completed"
+            except Exception:
+                pass
+        
+        # 构建返回数据
+        response_data = {
+            "simulation_id": simulation_id,
+            "file_exists": file_exists,
+            "file_modified_at": file_modified_at,
+            "is_generating": is_generating,
+            "generation_stage": generation_stage,
+            "config_generated": config_generated,
+            "config": config
+        }
+        
+        # 如果配置存在，提取一些关键统计信息
+        if config:
+            response_data["summary"] = {
+                "total_agents": len(config.get("agent_configs", [])),
+                "simulation_hours": config.get("time_config", {}).get("total_simulation_hours"),
+                "initial_posts_count": len(config.get("event_config", {}).get("initial_posts", [])),
+                "hot_topics_count": len(config.get("event_config", {}).get("hot_topics", [])),
+                "has_twitter_config": "twitter_config" in config,
+                "has_reddit_config": "reddit_config" in config,
+                "generated_at": config.get("generated_at"),
+                "llm_model": config.get("llm_model")
+            }
+        
+        return jsonify({
+            "success": True,
+            "data": response_data
+        })
+        
+    except Exception as e:
+        logger.error(f"实时获取Config失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/<simulation_id>/config', methods=['GET'])
+def get_simulation_config(simulation_id: str):
+    """
+    获取模拟配置（LLM智能生成的完整配置）
+    
+    返回包含：
+        - time_config: 时间配置（模拟时长、轮次、高峰/低谷时段）
+        - agent_configs: 每个Agent的活动配置（活跃度、发言频率、立场等）
+        - event_config: 事件配置（初始帖子、热点话题）
+        - platform_configs: 平台配置
+        - generation_reasoning: LLM的配置推理说明
+    """
+    try:
+        manager = SimulationManager()
+        config = manager.get_simulation_config(simulation_id)
+        
+        if not config:
+            return jsonify({
+                "success": False,
+                "error": f"模拟配置不存在，请先调用 /prepare 接口"
+            }), 404
+        
+        return jsonify({
+            "success": True,
+            "data": config
+        })
+        
+    except Exception as e:
+        logger.error(f"获取配置失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/<simulation_id>/config/download', methods=['GET'])
+def download_simulation_config(simulation_id: str):
+    """下载模拟配置文件"""
+    try:
+        manager = SimulationManager()
+        sim_dir = manager._get_simulation_dir(simulation_id)
+        config_path = os.path.join(sim_dir, "simulation_config.json")
+        
+        if not os.path.exists(config_path):
+            return jsonify({
+                "success": False,
+                "error": "配置文件不存在，请先调用 /prepare 接口"
+            }), 404
+        
+        return send_file(
+            config_path,
+            as_attachment=True,
+            download_name="simulation_config.json"
+        )
+        
+    except Exception as e:
+        logger.error(f"下载配置失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/script/<script_name>/download', methods=['GET'])
+def download_simulation_script(script_name: str):
+    """
+    下载模拟运行脚本文件（通用脚本，位于 backend/scripts/）
+    
+    script_name可选值：
+        - run_twitter_simulation.py
+        - run_reddit_simulation.py
+        - run_parallel_simulation.py
+        - action_logger.py
+    """
+    try:
+        # 脚本位于 backend/scripts/ 目录
+        scripts_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), '../../scripts'))
+        
+        # 验证脚本名称
+        allowed_scripts = [
+            "run_twitter_simulation.py",
+            "run_reddit_simulation.py", 
+            "run_parallel_simulation.py",
+            "action_logger.py"
+        ]
+        
+        if script_name not in allowed_scripts:
+            return jsonify({
+                "success": False,
+                "error": f"未知脚本: {script_name}，可选: {allowed_scripts}"
+            }), 400
+        
+        script_path = os.path.join(scripts_dir, script_name)
+        
+        if not os.path.exists(script_path):
+            return jsonify({
+                "success": False,
+                "error": f"脚本文件不存在: {script_name}"
+            }), 404
+        
+        return send_file(
+            script_path,
+            as_attachment=True,
+            download_name=script_name
+        )
+        
+    except Exception as e:
+        logger.error(f"下载脚本失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+# ============== Profile生成接口（独立使用） ==============
+
+@simulation_bp.route('/generate-profiles', methods=['POST'])
+def generate_profiles():
+    """
+    直接从图谱生成OASIS Agent Profile（不创建模拟）
+    
+    请求（JSON）：
+        {
+            "graph_id": "mirofish_xxxx",     // 必填
+            "entity_types": ["Student"],      // 可选
+            "use_llm": true,                  // 可选
+            "platform": "reddit"              // 可选
+        }
+    """
+    try:
+        data = request.get_json() or {}
+        
+        graph_id = data.get('graph_id')
+        if not graph_id:
+            return jsonify({
+                "success": False,
+                "error": "请提供 graph_id"
+            }), 400
+        
+        entity_types = data.get('entity_types')
+        use_llm = data.get('use_llm', True)
+        platform = data.get('platform', 'reddit')
+        
+        reader = ZepEntityReader()
+        filtered = reader.filter_defined_entities(
+            graph_id=graph_id,
+            defined_entity_types=entity_types,
+            enrich_with_edges=True
+        )
+        
+        if filtered.filtered_count == 0:
+            return jsonify({
+                "success": False,
+                "error": "没有找到符合条件的实体"
+            }), 400
+        
+        generator = OasisProfileGenerator()
+        profiles = generator.generate_profiles_from_entities(
+            entities=filtered.entities,
+            use_llm=use_llm
+        )
+        
+        if platform == "reddit":
+            profiles_data = [p.to_reddit_format() for p in profiles]
+        elif platform == "twitter":
+            profiles_data = [p.to_twitter_format() for p in profiles]
+        else:
+            profiles_data = [p.to_dict() for p in profiles]
+        
+        return jsonify({
+            "success": True,
+            "data": {
+                "platform": platform,
+                "entity_types": list(filtered.entity_types),
+                "count": len(profiles_data),
+                "profiles": profiles_data
+            }
+        })
+        
+    except Exception as e:
+        logger.error(f"生成Profile失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+# ============== 模拟运行控制接口 ==============
+
+@simulation_bp.route('/start', methods=['POST'])
+def start_simulation():
+    """
+    开始运行模拟
+
+    请求（JSON）：
+        {
+            "simulation_id": "sim_xxxx",          // 必填，模拟ID
+            "platform": "parallel",                // 可选: twitter / reddit / parallel (默认)
+            "max_rounds": 100,                     // 可选: 最大模拟轮数，用于截断过长的模拟
+            "enable_graph_memory_update": false,   // 可选: 是否将Agent活动动态更新到Zep图谱记忆
+            "force": false                         // 可选: 强制重新开始（会停止运行中的模拟并清理日志）
+        }
+
+    关于 force 参数：
+        - 启用后，如果模拟正在运行或已完成，会先停止并清理运行日志
+        - 清理的内容包括：run_state.json, actions.jsonl, simulation.log 等
+        - 不会清理配置文件（simulation_config.json）和 profile 文件
+        - 适用于需要重新运行模拟的场景
+
+    关于 enable_graph_memory_update：
+        - 启用后，模拟中所有Agent的活动（发帖、评论、点赞等）都会实时更新到Zep图谱
+        - 这可以让图谱"记住"模拟过程，用于后续分析或AI对话
+        - 需要模拟关联的项目有有效的 graph_id
+        - 采用批量更新机制，减少API调用次数
+
+    返回：
+        {
+            "success": true,
+            "data": {
+                "simulation_id": "sim_xxxx",
+                "runner_status": "running",
+                "process_pid": 12345,
+                "twitter_running": true,
+                "reddit_running": true,
+                "started_at": "2025-12-01T10:00:00",
+                "graph_memory_update_enabled": true,  // 是否启用了图谱记忆更新
+                "force_restarted": true               // 是否是强制重新开始
+            }
+        }
+    """
+    try:
+        data = request.get_json() or {}
+
+        simulation_id = data.get('simulation_id')
+        if not simulation_id:
+            return jsonify({
+                "success": False,
+                "error": "请提供 simulation_id"
+            }), 400
+
+        platform = data.get('platform', 'parallel')
+        max_rounds = data.get('max_rounds')  # 可选：最大模拟轮数
+        enable_graph_memory_update = data.get('enable_graph_memory_update', False)  # 可选：是否启用图谱记忆更新
+        force = data.get('force', False)  # 可选：强制重新开始
+
+        # 验证 max_rounds 参数
+        if max_rounds is not None:
+            try:
+                max_rounds = int(max_rounds)
+                if max_rounds <= 0:
+                    return jsonify({
+                        "success": False,
+                        "error": "max_rounds 必须是正整数"
+                    }), 400
+            except (ValueError, TypeError):
+                return jsonify({
+                    "success": False,
+                    "error": "max_rounds 必须是有效的整数"
+                }), 400
+
+        if platform not in ['twitter', 'reddit', 'parallel']:
+            return jsonify({
+                "success": False,
+                "error": f"无效的平台类型: {platform}，可选: twitter/reddit/parallel"
+            }), 400
+
+        # 检查模拟是否已准备好
+        manager = SimulationManager()
+        state = manager.get_simulation(simulation_id)
+
+        if not state:
+            return jsonify({
+                "success": False,
+                "error": f"模拟不存在: {simulation_id}"
+            }), 404
+
+        force_restarted = False
+        
+        # 智能处理状态：如果准备工作已完成，允许重新启动
+        if state.status != SimulationStatus.READY:
+            # 检查准备工作是否已完成
+            is_prepared, prepare_info = _check_simulation_prepared(simulation_id)
+
+            if is_prepared:
+                # 准备工作已完成，检查是否有正在运行的进程
+                if state.status == SimulationStatus.RUNNING:
+                    # 检查模拟进程是否真的在运行
+                    run_state = SimulationRunner.get_run_state(simulation_id)
+                    if run_state and run_state.runner_status.value == "running":
+                        # 进程确实在运行
+                        if force:
+                            # 强制模式：停止运行中的模拟
+                            logger.info(f"强制模式：停止运行中的模拟 {simulation_id}")
+                            try:
+                                SimulationRunner.stop_simulation(simulation_id)
+                            except Exception as e:
+                                logger.warning(f"停止模拟时出现警告: {str(e)}")
+                        else:
+                            return jsonify({
+                                "success": False,
+                                "error": f"模拟正在运行中，请先调用 /stop 接口停止，或使用 force=true 强制重新开始"
+                            }), 400
+
+                # 如果是强制模式，清理运行日志
+                if force:
+                    logger.info(f"强制模式：清理模拟日志 {simulation_id}")
+                    cleanup_result = SimulationRunner.cleanup_simulation_logs(simulation_id)
+                    if not cleanup_result.get("success"):
+                        logger.warning(f"清理日志时出现警告: {cleanup_result.get('errors')}")
+                    force_restarted = True
+
+                # 进程不存在或已结束，重置状态为 ready
+                logger.info(f"模拟 {simulation_id} 准备工作已完成，重置状态为 ready（原状态: {state.status.value}）")
+                state.status = SimulationStatus.READY
+                manager._save_simulation_state(state)
+            else:
+                # 准备工作未完成
+                return jsonify({
+                    "success": False,
+                    "error": f"模拟未准备好，当前状态: {state.status.value}，请先调用 /prepare 接口"
+                }), 400
+        
+        # 获取图谱ID（用于图谱记忆更新）
+        graph_id = None
+        if enable_graph_memory_update:
+            # 从模拟状态或项目中获取 graph_id
+            graph_id = state.graph_id
+            if not graph_id:
+                # 尝试从项目中获取
+                project = ProjectManager.get_project(state.project_id)
+                if project:
+                    graph_id = project.graph_id
+            
+            if not graph_id:
+                return jsonify({
+                    "success": False,
+                    "error": "启用图谱记忆更新需要有效的 graph_id，请确保项目已构建图谱"
+                }), 400
+            
+            logger.info(f"启用图谱记忆更新: simulation_id={simulation_id}, graph_id={graph_id}")
+        
+        # 启动模拟
+        run_state = SimulationRunner.start_simulation(
+            simulation_id=simulation_id,
+            platform=platform,
+            max_rounds=max_rounds,
+            enable_graph_memory_update=enable_graph_memory_update,
+            graph_id=graph_id
+        )
+        
+        # 更新模拟状态
+        state.status = SimulationStatus.RUNNING
+        manager._save_simulation_state(state)
+        
+        response_data = run_state.to_dict()
+        if max_rounds:
+            response_data['max_rounds_applied'] = max_rounds
+        response_data['graph_memory_update_enabled'] = enable_graph_memory_update
+        response_data['force_restarted'] = force_restarted
+        if enable_graph_memory_update:
+            response_data['graph_id'] = graph_id
+        
+        return jsonify({
+            "success": True,
+            "data": response_data
+        })
+        
+    except ValueError as e:
+        return jsonify({
+            "success": False,
+            "error": str(e)
+        }), 400
+        
+    except Exception as e:
+        logger.error(f"启动模拟失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/stop', methods=['POST'])
+def stop_simulation():
+    """
+    停止模拟
+    
+    请求（JSON）：
+        {
+            "simulation_id": "sim_xxxx"  // 必填，模拟ID
+        }
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "simulation_id": "sim_xxxx",
+                "runner_status": "stopped",
+                "completed_at": "2025-12-01T12:00:00"
+            }
+        }
+    """
+    try:
+        data = request.get_json() or {}
+        
+        simulation_id = data.get('simulation_id')
+        if not simulation_id:
+            return jsonify({
+                "success": False,
+                "error": "请提供 simulation_id"
+            }), 400
+        
+        run_state = SimulationRunner.stop_simulation(simulation_id)
+        
+        # 更新模拟状态
+        manager = SimulationManager()
+        state = manager.get_simulation(simulation_id)
+        if state:
+            state.status = SimulationStatus.PAUSED
+            manager._save_simulation_state(state)
+        
+        return jsonify({
+            "success": True,
+            "data": run_state.to_dict()
+        })
+        
+    except ValueError as e:
+        return jsonify({
+            "success": False,
+            "error": str(e)
+        }), 400
+        
+    except Exception as e:
+        logger.error(f"停止模拟失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+# ============== 实时状态监控接口 ==============
+
+@simulation_bp.route('/<simulation_id>/run-status', methods=['GET'])
+def get_run_status(simulation_id: str):
+    """
+    获取模拟运行实时状态（用于前端轮询）
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "simulation_id": "sim_xxxx",
+                "runner_status": "running",
+                "current_round": 5,
+                "total_rounds": 144,
+                "progress_percent": 3.5,
+                "simulated_hours": 2,
+                "total_simulation_hours": 72,
+                "twitter_running": true,
+                "reddit_running": true,
+                "twitter_actions_count": 150,
+                "reddit_actions_count": 200,
+                "total_actions_count": 350,
+                "started_at": "2025-12-01T10:00:00",
+                "updated_at": "2025-12-01T10:30:00"
+            }
+        }
+    """
+    try:
+        run_state = SimulationRunner.get_run_state(simulation_id)
+        
+        if not run_state:
+            return jsonify({
+                "success": True,
+                "data": {
+                    "simulation_id": simulation_id,
+                    "runner_status": "idle",
+                    "current_round": 0,
+                    "total_rounds": 0,
+                    "progress_percent": 0,
+                    "twitter_actions_count": 0,
+                    "reddit_actions_count": 0,
+                    "total_actions_count": 0,
+                }
+            })
+        
+        return jsonify({
+            "success": True,
+            "data": run_state.to_dict()
+        })
+        
+    except Exception as e:
+        logger.error(f"获取运行状态失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/<simulation_id>/run-status/detail', methods=['GET'])
+def get_run_status_detail(simulation_id: str):
+    """
+    获取模拟运行详细状态（包含所有动作）
+    
+    用于前端展示实时动态
+    
+    Query参数：
+        platform: 过滤平台（twitter/reddit，可选）
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "simulation_id": "sim_xxxx",
+                "runner_status": "running",
+                "current_round": 5,
+                ...
+                "all_actions": [
+                    {
+                        "round_num": 5,
+                        "timestamp": "2025-12-01T10:30:00",
+                        "platform": "twitter",
+                        "agent_id": 3,
+                        "agent_name": "Agent Name",
+                        "action_type": "CREATE_POST",
+                        "action_args": {"content": "..."},
+                        "result": null,
+                        "success": true
+                    },
+                    ...
+                ],
+                "twitter_actions": [...],  # Twitter 平台的所有动作
+                "reddit_actions": [...]    # Reddit 平台的所有动作
+            }
+        }
+    """
+    try:
+        run_state = SimulationRunner.get_run_state(simulation_id)
+        platform_filter = request.args.get('platform')
+        
+        if not run_state:
+            return jsonify({
+                "success": True,
+                "data": {
+                    "simulation_id": simulation_id,
+                    "runner_status": "idle",
+                    "all_actions": [],
+                    "twitter_actions": [],
+                    "reddit_actions": []
+                }
+            })
+        
+        # 获取完整的动作列表
+        all_actions = SimulationRunner.get_all_actions(
+            simulation_id=simulation_id,
+            platform=platform_filter
+        )
+        
+        # 分平台获取动作
+        twitter_actions = SimulationRunner.get_all_actions(
+            simulation_id=simulation_id,
+            platform="twitter"
+        ) if not platform_filter or platform_filter == "twitter" else []
+        
+        reddit_actions = SimulationRunner.get_all_actions(
+            simulation_id=simulation_id,
+            platform="reddit"
+        ) if not platform_filter or platform_filter == "reddit" else []
+        
+        # 获取当前轮次的动作（recent_actions 只展示最新一轮）
+        current_round = run_state.current_round
+        recent_actions = SimulationRunner.get_all_actions(
+            simulation_id=simulation_id,
+            platform=platform_filter,
+            round_num=current_round
+        ) if current_round > 0 else []
+        
+        # 获取基础状态信息
+        result = run_state.to_dict()
+        result["all_actions"] = [a.to_dict() for a in all_actions]
+        result["twitter_actions"] = [a.to_dict() for a in twitter_actions]
+        result["reddit_actions"] = [a.to_dict() for a in reddit_actions]
+        result["rounds_count"] = len(run_state.rounds)
+        # recent_actions 只展示当前最新一轮两个平台的内容
+        result["recent_actions"] = [a.to_dict() for a in recent_actions]
+        
+        return jsonify({
+            "success": True,
+            "data": result
+        })
+        
+    except Exception as e:
+        logger.error(f"获取详细状态失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/<simulation_id>/actions', methods=['GET'])
+def get_simulation_actions(simulation_id: str):
+    """
+    获取模拟中的Agent动作历史
+    
+    Query参数：
+        limit: 返回数量（默认100）
+        offset: 偏移量（默认0）
+        platform: 过滤平台（twitter/reddit）
+        agent_id: 过滤Agent ID
+        round_num: 过滤轮次
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "count": 100,
+                "actions": [...]
+            }
+        }
+    """
+    try:
+        limit = request.args.get('limit', 100, type=int)
+        offset = request.args.get('offset', 0, type=int)
+        platform = request.args.get('platform')
+        agent_id = request.args.get('agent_id', type=int)
+        round_num = request.args.get('round_num', type=int)
+        
+        actions = SimulationRunner.get_actions(
+            simulation_id=simulation_id,
+            limit=limit,
+            offset=offset,
+            platform=platform,
+            agent_id=agent_id,
+            round_num=round_num
+        )
+        
+        return jsonify({
+            "success": True,
+            "data": {
+                "count": len(actions),
+                "actions": [a.to_dict() for a in actions]
+            }
+        })
+        
+    except Exception as e:
+        logger.error(f"获取动作历史失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/<simulation_id>/timeline', methods=['GET'])
+def get_simulation_timeline(simulation_id: str):
+    """
+    获取模拟时间线（按轮次汇总）
+    
+    用于前端展示进度条和时间线视图
+    
+    Query参数：
+        start_round: 起始轮次（默认0）
+        end_round: 结束轮次（默认全部）
+    
+    返回每轮的汇总信息
+    """
+    try:
+        start_round = request.args.get('start_round', 0, type=int)
+        end_round = request.args.get('end_round', type=int)
+        
+        timeline = SimulationRunner.get_timeline(
+            simulation_id=simulation_id,
+            start_round=start_round,
+            end_round=end_round
+        )
+        
+        return jsonify({
+            "success": True,
+            "data": {
+                "rounds_count": len(timeline),
+                "timeline": timeline
+            }
+        })
+        
+    except Exception as e:
+        logger.error(f"获取时间线失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/<simulation_id>/agent-stats', methods=['GET'])
+def get_agent_stats(simulation_id: str):
+    """
+    获取每个Agent的统计信息
+    
+    用于前端展示Agent活跃度排行、动作分布等
+    """
+    try:
+        stats = SimulationRunner.get_agent_stats(simulation_id)
+        
+        return jsonify({
+            "success": True,
+            "data": {
+                "agents_count": len(stats),
+                "stats": stats
+            }
+        })
+        
+    except Exception as e:
+        logger.error(f"获取Agent统计失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+# ============== 数据库查询接口 ==============
+
+@simulation_bp.route('/<simulation_id>/posts', methods=['GET'])
+def get_simulation_posts(simulation_id: str):
+    """
+    获取模拟中的帖子
+    
+    Query参数：
+        platform: 平台类型（twitter/reddit）
+        limit: 返回数量（默认50）
+        offset: 偏移量
+    
+    返回帖子列表（从SQLite数据库读取）
+    """
+    try:
+        platform = request.args.get('platform', 'reddit')
+        limit = request.args.get('limit', 50, type=int)
+        offset = request.args.get('offset', 0, type=int)
+        
+        sim_dir = os.path.join(
+            os.path.dirname(__file__),
+            f'../../uploads/simulations/{simulation_id}'
+        )
+        
+        db_file = f"{platform}_simulation.db"
+        db_path = os.path.join(sim_dir, db_file)
+        
+        if not os.path.exists(db_path):
+            return jsonify({
+                "success": True,
+                "data": {
+                    "platform": platform,
+                    "count": 0,
+                    "posts": [],
+                    "message": "数据库不存在，模拟可能尚未运行"
+                }
+            })
+        
+        import sqlite3
+        conn = sqlite3.connect(db_path)
+        conn.row_factory = sqlite3.Row
+        cursor = conn.cursor()
+        
+        try:
+            cursor.execute("""
+                SELECT * FROM post 
+                ORDER BY created_at DESC 
+                LIMIT ? OFFSET ?
+            """, (limit, offset))
+            
+            posts = [dict(row) for row in cursor.fetchall()]
+            
+            cursor.execute("SELECT COUNT(*) FROM post")
+            total = cursor.fetchone()[0]
+            
+        except sqlite3.OperationalError:
+            posts = []
+            total = 0
+        
+        conn.close()
+        
+        return jsonify({
+            "success": True,
+            "data": {
+                "platform": platform,
+                "total": total,
+                "count": len(posts),
+                "posts": posts
+            }
+        })
+        
+    except Exception as e:
+        logger.error(f"获取帖子失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/<simulation_id>/comments', methods=['GET'])
+def get_simulation_comments(simulation_id: str):
+    """
+    获取模拟中的评论（仅Reddit）
+    
+    Query参数：
+        post_id: 过滤帖子ID（可选）
+        limit: 返回数量
+        offset: 偏移量
+    """
+    try:
+        post_id = request.args.get('post_id')
+        limit = request.args.get('limit', 50, type=int)
+        offset = request.args.get('offset', 0, type=int)
+        
+        sim_dir = os.path.join(
+            os.path.dirname(__file__),
+            f'../../uploads/simulations/{simulation_id}'
+        )
+        
+        db_path = os.path.join(sim_dir, "reddit_simulation.db")
+        
+        if not os.path.exists(db_path):
+            return jsonify({
+                "success": True,
+                "data": {
+                    "count": 0,
+                    "comments": []
+                }
+            })
+        
+        import sqlite3
+        conn = sqlite3.connect(db_path)
+        conn.row_factory = sqlite3.Row
+        cursor = conn.cursor()
+        
+        try:
+            if post_id:
+                cursor.execute("""
+                    SELECT * FROM comment 
+                    WHERE post_id = ?
+                    ORDER BY created_at DESC 
+                    LIMIT ? OFFSET ?
+                """, (post_id, limit, offset))
+            else:
+                cursor.execute("""
+                    SELECT * FROM comment 
+                    ORDER BY created_at DESC 
+                    LIMIT ? OFFSET ?
+                """, (limit, offset))
+            
+            comments = [dict(row) for row in cursor.fetchall()]
+            
+        except sqlite3.OperationalError:
+            comments = []
+        
+        conn.close()
+        
+        return jsonify({
+            "success": True,
+            "data": {
+                "count": len(comments),
+                "comments": comments
+            }
+        })
+        
+    except Exception as e:
+        logger.error(f"获取评论失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+# ============== Interview 采访接口 ==============
+
+@simulation_bp.route('/interview', methods=['POST'])
+def interview_agent():
+    """
+    采访单个Agent
+
+    注意：此功能需要模拟环境处于运行状态（完成模拟循环后进入等待命令模式）
+
+    请求（JSON）：
+        {
+            "simulation_id": "sim_xxxx",       // 必填，模拟ID
+            "agent_id": 0,                     // 必填，Agent ID
+            "prompt": "你对这件事有什么看法？",  // 必填，采访问题
+            "platform": "twitter",             // 可选，指定平台（twitter/reddit）
+                                               // 不指定时：双平台模拟同时采访两个平台
+            "timeout": 60                      // 可选，超时时间（秒），默认60
+        }
+
+    返回（不指定platform，双平台模式）：
+        {
+            "success": true,
+            "data": {
+                "agent_id": 0,
+                "prompt": "你对这件事有什么看法？",
+                "result": {
+                    "agent_id": 0,
+                    "prompt": "...",
+                    "platforms": {
+                        "twitter": {"agent_id": 0, "response": "...", "platform": "twitter"},
+                        "reddit": {"agent_id": 0, "response": "...", "platform": "reddit"}
+                    }
+                },
+                "timestamp": "2025-12-08T10:00:01"
+            }
+        }
+
+    返回（指定platform）：
+        {
+            "success": true,
+            "data": {
+                "agent_id": 0,
+                "prompt": "你对这件事有什么看法？",
+                "result": {
+                    "agent_id": 0,
+                    "response": "我认为...",
+                    "platform": "twitter",
+                    "timestamp": "2025-12-08T10:00:00"
+                },
+                "timestamp": "2025-12-08T10:00:01"
+            }
+        }
+    """
+    try:
+        data = request.get_json() or {}
+        
+        simulation_id = data.get('simulation_id')
+        agent_id = data.get('agent_id')
+        prompt = data.get('prompt')
+        platform = data.get('platform')  # 可选：twitter/reddit/None
+        timeout = data.get('timeout', 60)
+        
+        if not simulation_id:
+            return jsonify({
+                "success": False,
+                "error": "请提供 simulation_id"
+            }), 400
+        
+        if agent_id is None:
+            return jsonify({
+                "success": False,
+                "error": "请提供 agent_id"
+            }), 400
+        
+        if not prompt:
+            return jsonify({
+                "success": False,
+                "error": "请提供 prompt（采访问题）"
+            }), 400
+        
+        # 验证platform参数
+        if platform and platform not in ("twitter", "reddit"):
+            return jsonify({
+                "success": False,
+                "error": "platform 参数只能是 'twitter' 或 'reddit'"
+            }), 400
+        
+        # 检查环境状态
+        if not SimulationRunner.check_env_alive(simulation_id):
+            return jsonify({
+                "success": False,
+                "error": "模拟环境未运行或已关闭。请确保模拟已完成并进入等待命令���式。"
+            }), 400
+        
+        # 优化prompt，添加前缀避免Agent调用工具
+        optimized_prompt = optimize_interview_prompt(prompt)
+        
+        result = SimulationRunner.interview_agent(
+            simulation_id=simulation_id,
+            agent_id=agent_id,
+            prompt=optimized_prompt,
+            platform=platform,
+            timeout=timeout
+        )
+
+        return jsonify({
+            "success": result.get("success", False),
+            "data": result
+        })
+        
+    except ValueError as e:
+        return jsonify({
+            "success": False,
+            "error": str(e)
+        }), 400
+        
+    except TimeoutError as e:
+        return jsonify({
+            "success": False,
+            "error": f"等待Interview响应超时: {str(e)}"
+        }), 504
+        
+    except Exception as e:
+        logger.error(f"Interview失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/interview/batch', methods=['POST'])
+def interview_agents_batch():
+    """
+    批量采访多个Agent
+
+    注意：此功能需要模拟环境处于运行状态
+
+    请求（JSON）：
+        {
+            "simulation_id": "sim_xxxx",       // 必填，模拟ID
+            "interviews": [                    // 必填，采访列表
+                {
+                    "agent_id": 0,
+                    "prompt": "你对A有什么看法？",
+                    "platform": "twitter"      // 可选，指定该Agent的采访平台
+                },
+                {
+                    "agent_id": 1,
+                    "prompt": "你对B有什么看法？"  // 不指定platform则使用默认值
+                }
+            ],
+            "platform": "reddit",              // 可选，默认平台（被每项的platform覆盖）
+                                               // 不指定时：双平台模拟每个Agent同时采访两个平台
+            "timeout": 120                     // 可选，超时时间（秒），默认120
+        }
+
+    返回：
+        {
+            "success": true,
+            "data": {
+                "interviews_count": 2,
+                "result": {
+                    "interviews_count": 4,
+                    "results": {
+                        "twitter_0": {"agent_id": 0, "response": "...", "platform": "twitter"},
+                        "reddit_0": {"agent_id": 0, "response": "...", "platform": "reddit"},
+                        "twitter_1": {"agent_id": 1, "response": "...", "platform": "twitter"},
+                        "reddit_1": {"agent_id": 1, "response": "...", "platform": "reddit"}
+                    }
+                },
+                "timestamp": "2025-12-08T10:00:01"
+            }
+        }
+    """
+    try:
+        data = request.get_json() or {}
+
+        simulation_id = data.get('simulation_id')
+        interviews = data.get('interviews')
+        platform = data.get('platform')  # 可选：twitter/reddit/None
+        timeout = data.get('timeout', 120)
+
+        if not simulation_id:
+            return jsonify({
+                "success": False,
+                "error": "请提供 simulation_id"
+            }), 400
+
+        if not interviews or not isinstance(interviews, list):
+            return jsonify({
+                "success": False,
+                "error": "请提供 interviews（采访列表）"
+            }), 400
+
+        # 验证platform参数
+        if platform and platform not in ("twitter", "reddit"):
+            return jsonify({
+                "success": False,
+                "error": "platform 参数只能是 'twitter' 或 'reddit'"
+            }), 400
+
+        # 验证每个采访项
+        for i, interview in enumerate(interviews):
+            if 'agent_id' not in interview:
+                return jsonify({
+                    "success": False,
+                    "error": f"采访列表第{i+1}项缺少 agent_id"
+                }), 400
+            if 'prompt' not in interview:
+                return jsonify({
+                    "success": False,
+                    "error": f"采访列表第{i+1}项缺少 prompt"
+                }), 400
+            # 验证每项的platform（如果有）
+            item_platform = interview.get('platform')
+            if item_platform and item_platform not in ("twitter", "reddit"):
+                return jsonify({
+                    "success": False,
+                    "error": f"采访列表第{i+1}项的platform只能是 'twitter' 或 'reddit'"
+                }), 400
+
+        # 检查环境状态
+        if not SimulationRunner.check_env_alive(simulation_id):
+            return jsonify({
+                "success": False,
+                "error": "模拟环境未运行或已关闭。请确保模拟已完成并进入等待命令模式。"
+            }), 400
+
+        # 优化每个采访项的prompt，添��前缀避免Agent调用工具
+        optimized_interviews = []
+        for interview in interviews:
+            optimized_interview = interview.copy()
+            optimized_interview['prompt'] = optimize_interview_prompt(interview.get('prompt', ''))
+            optimized_interviews.append(optimized_interview)
+
+        result = SimulationRunner.interview_agents_batch(
+            simulation_id=simulation_id,
+            interviews=optimized_interviews,
+            platform=platform,
+            timeout=timeout
+        )
+
+        return jsonify({
+            "success": result.get("success", False),
+            "data": result
+        })
+
+    except ValueError as e:
+        return jsonify({
+            "success": False,
+            "error": str(e)
+        }), 400
+
+    except TimeoutError as e:
+        return jsonify({
+            "success": False,
+            "error": f"等待批量Interview响应超时: {str(e)}"
+        }), 504
+
+    except Exception as e:
+        logger.error(f"批量Interview失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/interview/all', methods=['POST'])
+def interview_all_agents():
+    """
+    全局采访 - 使用相同问题采访所有Agent
+
+    注意：此功能需要模拟环境处于运行状态
+
+    请求（JSON）：
+        {
+            "simulation_id": "sim_xxxx",            // 必填，模拟ID
+            "prompt": "你对这件事整体有什么看法？",  // 必填，采访问题（所有Agent使用相同问题）
+            "platform": "reddit",                   // 可选，指定平台（twitter/reddit）
+                                                    // 不指定时：双平台模拟每个Agent同时采访两个平台
+            "timeout": 180                          // 可选，超时时间（秒），默认180
+        }
+
+    返回：
+        {
+            "success": true,
+            "data": {
+                "interviews_count": 50,
+                "result": {
+                    "interviews_count": 100,
+                    "results": {
+                        "twitter_0": {"agent_id": 0, "response": "...", "platform": "twitter"},
+                        "reddit_0": {"agent_id": 0, "response": "...", "platform": "reddit"},
+                        ...
+                    }
+                },
+                "timestamp": "2025-12-08T10:00:01"
+            }
+        }
+    """
+    try:
+        data = request.get_json() or {}
+
+        simulation_id = data.get('simulation_id')
+        prompt = data.get('prompt')
+        platform = data.get('platform')  # 可选：twitter/reddit/None
+        timeout = data.get('timeout', 180)
+
+        if not simulation_id:
+            return jsonify({
+                "success": False,
+                "error": "请提供 simulation_id"
+            }), 400
+
+        if not prompt:
+            return jsonify({
+                "success": False,
+                "error": "请提供 prompt（采访问题）"
+            }), 400
+
+        # 验证platform参数
+        if platform and platform not in ("twitter", "reddit"):
+            return jsonify({
+                "success": False,
+                "error": "platform 参数只能是 'twitter' 或 'reddit'"
+            }), 400
+
+        # 检查环境状态
+        if not SimulationRunner.check_env_alive(simulation_id):
+            return jsonify({
+                "success": False,
+                "error": "模拟环境未运行或已关闭。请确保模拟已完成并进入等待命令模式。"
+            }), 400
+
+        # 优化prompt，添加前缀避免Agent调用工具
+        optimized_prompt = optimize_interview_prompt(prompt)
+
+        result = SimulationRunner.interview_all_agents(
+            simulation_id=simulation_id,
+            prompt=optimized_prompt,
+            platform=platform,
+            timeout=timeout
+        )
+
+        return jsonify({
+            "success": result.get("success", False),
+            "data": result
+        })
+
+    except ValueError as e:
+        return jsonify({
+            "success": False,
+            "error": str(e)
+        }), 400
+
+    except TimeoutError as e:
+        return jsonify({
+            "success": False,
+            "error": f"等待全局Interview响应超时: {str(e)}"
+        }), 504
+
+    except Exception as e:
+        logger.error(f"全局Interview失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/interview/history', methods=['POST'])
+def get_interview_history():
+    """
+    获取Interview历史记录
+
+    从模拟数据库中读取所有Interview记录
+
+    请求（JSON）：
+        {
+            "simulation_id": "sim_xxxx",  // 必填，模拟ID
+            "platform": "reddit",          // 可选，平台类��（reddit/twitter）
+                                           // 不指定则返回两个平台的所有历史
+            "agent_id": 0,                 // 可选，只获取该Agent的采访历史
+            "limit": 100                   // 可选，返回数量，默认100
+        }
+
+    返回：
+        {
+            "success": true,
+            "data": {
+                "count": 10,
+                "history": [
+                    {
+                        "agent_id": 0,
+                        "response": "我认为...",
+                        "prompt": "你对这件事有什么看法？",
+                        "timestamp": "2025-12-08T10:00:00",
+                        "platform": "reddit"
+                    },
+                    ...
+                ]
+            }
+        }
+    """
+    try:
+        data = request.get_json() or {}
+        
+        simulation_id = data.get('simulation_id')
+        platform = data.get('platform')  # 不指定则返回两个平台的历史
+        agent_id = data.get('agent_id')
+        limit = data.get('limit', 100)
+        
+        if not simulation_id:
+            return jsonify({
+                "success": False,
+                "error": "请提供 simulation_id"
+            }), 400
+
+        history = SimulationRunner.get_interview_history(
+            simulation_id=simulation_id,
+            platform=platform,
+            agent_id=agent_id,
+            limit=limit
+        )
+
+        return jsonify({
+            "success": True,
+            "data": {
+                "count": len(history),
+                "history": history
+            }
+        })
+
+    except Exception as e:
+        logger.error(f"获取Interview历史失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/env-status', methods=['POST'])
+def get_env_status():
+    """
+    获取模拟环境状态
+
+    检查模拟环境是否存活（可以接收Interview命令）
+
+    请求（JSON）：
+        {
+            "simulation_id": "sim_xxxx"  // 必填，模拟ID
+        }
+
+    返回：
+        {
+            "success": true,
+            "data": {
+                "simulation_id": "sim_xxxx",
+                "env_alive": true,
+                "twitter_available": true,
+                "reddit_available": true,
+                "message": "环境正在运行，可以接收Interview命令"
+            }
+        }
+    """
+    try:
+        data = request.get_json() or {}
+        
+        simulation_id = data.get('simulation_id')
+        
+        if not simulation_id:
+            return jsonify({
+                "success": False,
+                "error": "请提供 simulation_id"
+            }), 400
+
+        env_alive = SimulationRunner.check_env_alive(simulation_id)
+        
+        # 获取更详细的状态信息
+        env_status = SimulationRunner.get_env_status_detail(simulation_id)
+
+        if env_alive:
+            message = "环境正在运行，可以接收Interview命令"
+        else:
+            message = "环境未运行或已关闭"
+
+        return jsonify({
+            "success": True,
+            "data": {
+                "simulation_id": simulation_id,
+                "env_alive": env_alive,
+                "twitter_available": env_status.get("twitter_available", False),
+                "reddit_available": env_status.get("reddit_available", False),
+                "message": message
+            }
+        })
+
+    except Exception as e:
+        logger.error(f"获取环境状态失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500
+
+
+@simulation_bp.route('/close-env', methods=['POST'])
+def close_simulation_env():
+    """
+    关闭模拟环境
+    
+    向模拟发送关闭环境命令，使其优雅退出等待命令模式。
+    
+    注意：这不同于 /stop 接口，/stop 会强制终止进程，
+    而此接口会让模拟优雅地关闭环境并退出。
+    
+    请求（JSON）：
+        {
+            "simulation_id": "sim_xxxx",  // 必填，模拟ID
+            "timeout": 30                  // 可选，超时时间（秒），默认30
+        }
+    
+    返回：
+        {
+            "success": true,
+            "data": {
+                "message": "环境关闭命令已发送",
+                "result": {...},
+                "timestamp": "2025-12-08T10:00:01"
+            }
+        }
+    """
+    try:
+        data = request.get_json() or {}
+        
+        simulation_id = data.get('simulation_id')
+        timeout = data.get('timeout', 30)
+        
+        if not simulation_id:
+            return jsonify({
+                "success": False,
+                "error": "请提供 simulation_id"
+            }), 400
+        
+        result = SimulationRunner.close_simulation_env(
+            simulation_id=simulation_id,
+            timeout=timeout
+        )
+        
+        # 更新模拟状态
+        manager = SimulationManager()
+        state = manager.get_simulation(simulation_id)
+        if state:
+            state.status = SimulationStatus.COMPLETED
+            manager._save_simulation_state(state)
+        
+        return jsonify({
+            "success": result.get("success", False),
+            "data": result
+        })
+        
+    except ValueError as e:
+        return jsonify({
+            "success": False,
+            "error": str(e)
+        }), 400
+        
+    except Exception as e:
+        logger.error(f"关闭环境失败: {str(e)}")
+        return jsonify({
+            "success": False,
+            "error": str(e),
+            "traceback": traceback.format_exc()
+        }), 500

app/app/config.py

@@ -0,0 +1,129 @@
+"""
+配置管理
+统一从项目根目录的 .env 文件加载配置
+"""
+
+import os
+from dotenv import load_dotenv
+
+# 加载项目根目录的 .env 文件
+# 路径: MiroFish/.env (相对于 backend/app/config.py)
+project_root_env = os.path.join(os.path.dirname(__file__), '../../.env')
+
+if os.path.exists(project_root_env):
+    load_dotenv(project_root_env, override=True)
+else:
+    # 如果根目录没有 .env，尝试加载环境变量（用于生产环境）
+    load_dotenv(override=True)
+
+
+class Config:
+    """Flask配置类"""
+    
+    # Flask配置
+    SECRET_KEY = os.environ.get('SECRET_KEY', 'mirofish-secret-key')
+    DEBUG = os.environ.get('FLASK_DEBUG', 'True').lower() == 'true'
+    
+    # JSON配置 - 禁用ASCII转义，让中文直接显示（而不是 \uXXXX 格式）
+    JSON_AS_ASCII = False
+    
+    # LLM配置（统一使用OpenAI格式）
+    LLM_API_KEY = os.environ.get('LLM_API_KEY')
+    LLM_BASE_URL = os.environ.get('LLM_BASE_URL', 'https://api.openai.com/v1')
+    LLM_MODEL_NAME = os.environ.get('LLM_MODEL_NAME', 'gpt-4o-mini')
+    
+    # Zep配置
+    ZEP_API_KEY = os.environ.get('ZEP_API_KEY')
+
+    @classmethod
+    def get_zep_api_keys(cls):
+        """Non-empty Zep API keys: single ZEP_API_KEY or comma-separated list (first used by default)."""
+        raw = (cls.ZEP_API_KEY or "").strip()
+        if not raw:
+            return []
+        return [k.strip() for k in raw.split(",") if k.strip()]
+
+    @classmethod
+    def get_llm_api_keys(cls):
+        """Non-empty LLM keys: single LLM_API_KEY or comma-separated list (paired slot with Zep)."""
+        raw = (cls.LLM_API_KEY or "").strip()
+        if not raw:
+            return []
+        return [k.strip() for k in raw.split(",") if k.strip()]
+
+    # Razorpay + simulation unlock (website)
+    RAZORPAY_KEY_ID = os.environ.get("RAZORPAY_KEY_ID", "").strip()
+    RAZORPAY_KEY_SECRET = os.environ.get("RAZORPAY_KEY_SECRET", "").strip()
+    RAZORPAY_AMOUNT_PAISE = int(os.environ.get("RAZORPAY_AMOUNT_PAISE", "49900"))
+    RAZORPAY_CURRENCY = os.environ.get("RAZORPAY_CURRENCY", "INR").strip() or "INR"
+    PAYMENT_COUPON_CODES = os.environ.get("PAYMENT_COUPON_CODES", "").strip()
+    PAYMENT_JWT_SECRET = os.environ.get("PAYMENT_JWT_SECRET", "").strip()
+
+    @classmethod
+    def payment_coupon_set(cls):
+        if not cls.PAYMENT_COUPON_CODES:
+            return set()
+        return {c.strip().lower() for c in cls.PAYMENT_COUPON_CODES.split(",") if c.strip()}
+
+    @classmethod
+    def billing_enabled(cls) -> bool:
+        razorpay_ok = bool(cls.RAZORPAY_KEY_ID and cls.RAZORPAY_KEY_SECRET)
+        return razorpay_ok or bool(cls.payment_coupon_set())
+
+    @classmethod
+    def payment_signing_secret(cls) -> str:
+        return (cls.PAYMENT_JWT_SECRET or cls.PIPELINE_CLIENT_SECRET or cls.SECRET_KEY or "mirofish-pay").strip()
+    
+    # 文件上传配置
+    MAX_CONTENT_LENGTH = 50 * 1024 * 1024  # 50MB
+    UPLOAD_FOLDER = os.path.join(os.path.dirname(__file__), '../uploads')
+    ALLOWED_EXTENSIONS = {'pdf', 'md', 'txt', 'markdown'}
+    
+    # 文本处理配置
+    DEFAULT_CHUNK_SIZE = 500  # 默认切块大小
+    DEFAULT_CHUNK_OVERLAP = 50  # 默认重叠大小
+    
+    # OASIS模拟配置
+    OASIS_DEFAULT_MAX_ROUNDS = int(os.environ.get('OASIS_DEFAULT_MAX_ROUNDS', '10'))
+    OASIS_SIMULATION_DATA_DIR = os.path.join(os.path.dirname(__file__), '../uploads/simulations')
+    
+    # OASIS平台可用动作配置
+    OASIS_TWITTER_ACTIONS = [
+        'CREATE_POST', 'LIKE_POST', 'REPOST', 'FOLLOW', 'DO_NOTHING', 'QUOTE_POST'
+    ]
+    OASIS_REDDIT_ACTIONS = [
+        'LIKE_POST', 'DISLIKE_POST', 'CREATE_POST', 'CREATE_COMMENT',
+        'LIKE_COMMENT', 'DISLIKE_COMMENT', 'SEARCH_POSTS', 'SEARCH_USER',
+        'TREND', 'REFRESH', 'DO_NOTHING', 'FOLLOW', 'MUTE'
+    ]
+    
+    # 全自动流水线（website → /api/pipeline/start）
+    PIPELINE_MAX_ROUNDS = os.environ.get('PIPELINE_MAX_ROUNDS')  # optional cap on OASIS rounds
+    PIPELINE_PARALLEL_PROFILES = int(os.environ.get('PIPELINE_PARALLEL_PROFILES', '5'))
+    
+    # Supabase: report storage + simulation_runs table (free tier friendly)
+    SUPABASE_URL = os.environ.get('SUPABASE_URL', '').rstrip('/')
+    SUPABASE_SERVICE_ROLE_KEY = os.environ.get('SUPABASE_SERVICE_ROLE_KEY', '')
+    # Project Settings → API → JWT Secret (verify user access tokens from the website)
+    SUPABASE_JWT_SECRET = os.environ.get('SUPABASE_JWT_SECRET', '')
+    SUPABASE_REPORTS_BUCKET = os.environ.get('SUPABASE_REPORTS_BUCKET', 'reports')
+    # Optional: signing secret for legacy MiroFish Bearer JWTs. Defaults to SECRET_KEY.
+    MIROFISH_SESSION_JWT_SECRET = os.environ.get('MIROFISH_SESSION_JWT_SECRET', '').strip()
+    # Same value as website VITE_PIPELINE_CLIENT_SECRET (browser sends X-Mirofish-User-Id + X-Pipeline-Client-Secret).
+    PIPELINE_CLIENT_SECRET = os.environ.get('PIPELINE_CLIENT_SECRET', '').strip()
+    
+    # Report Agent配置
+    REPORT_AGENT_MAX_TOOL_CALLS = int(os.environ.get('REPORT_AGENT_MAX_TOOL_CALLS', '5'))
+    REPORT_AGENT_MAX_REFLECTION_ROUNDS = int(os.environ.get('REPORT_AGENT_MAX_REFLECTION_ROUNDS', '2'))
+    REPORT_AGENT_TEMPERATURE = float(os.environ.get('REPORT_AGENT_TEMPERATURE', '0.5'))
+    
+    @classmethod
+    def validate(cls):
+        """验证必要配置"""
+        errors = []
+        if not cls.get_llm_api_keys():
+            errors.append("LLM_API_KEY 未配置")
+        if not cls.get_zep_api_keys():
+            errors.append("ZEP_API_KEY 未配置")
+        return errors
+

app/app/models/__init__.py

@@ -0,0 +1,9 @@
+"""
+数据模型模块
+"""
+
+from .task import TaskManager, TaskStatus
+from .project import Project, ProjectStatus, ProjectManager
+
+__all__ = ['TaskManager', 'TaskStatus', 'Project', 'ProjectStatus', 'ProjectManager']
+

app/app/models/project.py

@@ -0,0 +1,305 @@
+"""
+项目上下文管理
+用于在服务端持久化项目状态，避免前端在接口间传递大量数据
+"""
+
+import os
+import json
+import uuid
+import shutil
+from datetime import datetime
+from typing import Dict, Any, List, Optional
+from enum import Enum
+from dataclasses import dataclass, field, asdict
+from ..config import Config
+
+
+class ProjectStatus(str, Enum):
+    """项目状态"""
+    CREATED = "created"              # 刚创建，文件已上传
+    ONTOLOGY_GENERATED = "ontology_generated"  # 本体已生成
+    GRAPH_BUILDING = "graph_building"    # 图谱构建中
+    GRAPH_COMPLETED = "graph_completed"  # 图谱构建完成
+    FAILED = "failed"                # 失败
+
+
+@dataclass
+class Project:
+    """项目数据模型"""
+    project_id: str
+    name: str
+    status: ProjectStatus
+    created_at: str
+    updated_at: str
+    
+    # 文件信息
+    files: List[Dict[str, str]] = field(default_factory=list)  # [{filename, path, size}]
+    total_text_length: int = 0
+    
+    # 本体信息（接口1生成后填充）
+    ontology: Optional[Dict[str, Any]] = None
+    analysis_summary: Optional[str] = None
+    
+    # 图谱信息（接口2完成后填充）
+    graph_id: Optional[str] = None
+    graph_build_task_id: Optional[str] = None
+    
+    # 配置
+    simulation_requirement: Optional[str] = None
+    chunk_size: int = 500
+    chunk_overlap: int = 50
+    
+    # 错误信息
+    error: Optional[str] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """转换为字典"""
+        return {
+            "project_id": self.project_id,
+            "name": self.name,
+            "status": self.status.value if isinstance(self.status, ProjectStatus) else self.status,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "files": self.files,
+            "total_text_length": self.total_text_length,
+            "ontology": self.ontology,
+            "analysis_summary": self.analysis_summary,
+            "graph_id": self.graph_id,
+            "graph_build_task_id": self.graph_build_task_id,
+            "simulation_requirement": self.simulation_requirement,
+            "chunk_size": self.chunk_size,
+            "chunk_overlap": self.chunk_overlap,
+            "error": self.error
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'Project':
+        """从字典创建"""
+        status = data.get('status', 'created')
+        if isinstance(status, str):
+            status = ProjectStatus(status)
+        
+        return cls(
+            project_id=data['project_id'],
+            name=data.get('name', 'Unnamed Project'),
+            status=status,
+            created_at=data.get('created_at', ''),
+            updated_at=data.get('updated_at', ''),
+            files=data.get('files', []),
+            total_text_length=data.get('total_text_length', 0),
+            ontology=data.get('ontology'),
+            analysis_summary=data.get('analysis_summary'),
+            graph_id=data.get('graph_id'),
+            graph_build_task_id=data.get('graph_build_task_id'),
+            simulation_requirement=data.get('simulation_requirement'),
+            chunk_size=data.get('chunk_size', 500),
+            chunk_overlap=data.get('chunk_overlap', 50),
+            error=data.get('error')
+        )
+
+
+class ProjectManager:
+    """项目管理器 - 负责项目的持久化存储和检索"""
+    
+    # 项目存储根目录
+    PROJECTS_DIR = os.path.join(Config.UPLOAD_FOLDER, 'projects')
+    
+    @classmethod
+    def _ensure_projects_dir(cls):
+        """确保项目目录存在"""
+        os.makedirs(cls.PROJECTS_DIR, exist_ok=True)
+    
+    @classmethod
+    def _get_project_dir(cls, project_id: str) -> str:
+        """获取项目目录路径"""
+        return os.path.join(cls.PROJECTS_DIR, project_id)
+    
+    @classmethod
+    def _get_project_meta_path(cls, project_id: str) -> str:
+        """获取项目元数据文件路径"""
+        return os.path.join(cls._get_project_dir(project_id), 'project.json')
+    
+    @classmethod
+    def _get_project_files_dir(cls, project_id: str) -> str:
+        """获取项目文件存储目录"""
+        return os.path.join(cls._get_project_dir(project_id), 'files')
+    
+    @classmethod
+    def _get_project_text_path(cls, project_id: str) -> str:
+        """获取项目提取文本存储路径"""
+        return os.path.join(cls._get_project_dir(project_id), 'extracted_text.txt')
+    
+    @classmethod
+    def create_project(cls, name: str = "Unnamed Project") -> Project:
+        """
+        创建新项目
+        
+        Args:
+            name: 项目名称
+            
+        Returns:
+            新创建的Project对象
+        """
+        cls._ensure_projects_dir()
+        
+        project_id = f"proj_{uuid.uuid4().hex[:12]}"
+        now = datetime.now().isoformat()
+        
+        project = Project(
+            project_id=project_id,
+            name=name,
+            status=ProjectStatus.CREATED,
+            created_at=now,
+            updated_at=now
+        )
+        
+        # 创建项目目录结构
+        project_dir = cls._get_project_dir(project_id)
+        files_dir = cls._get_project_files_dir(project_id)
+        os.makedirs(project_dir, exist_ok=True)
+        os.makedirs(files_dir, exist_ok=True)
+        
+        # 保存项目元数据
+        cls.save_project(project)
+        
+        return project
+    
+    @classmethod
+    def save_project(cls, project: Project) -> None:
+        """保存项目元数据"""
+        project.updated_at = datetime.now().isoformat()
+        meta_path = cls._get_project_meta_path(project.project_id)
+        
+        with open(meta_path, 'w', encoding='utf-8') as f:
+            json.dump(project.to_dict(), f, ensure_ascii=False, indent=2)
+    
+    @classmethod
+    def get_project(cls, project_id: str) -> Optional[Project]:
+        """
+        获取项目
+        
+        Args:
+            project_id: 项目ID
+            
+        Returns:
+            Project对象，如果不存在返回None
+        """
+        meta_path = cls._get_project_meta_path(project_id)
+        
+        if not os.path.exists(meta_path):
+            return None
+        
+        with open(meta_path, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+        
+        return Project.from_dict(data)
+    
+    @classmethod
+    def list_projects(cls, limit: int = 50) -> List[Project]:
+        """
+        列出所有项目
+        
+        Args:
+            limit: 返回数量限制
+            
+        Returns:
+            项目列表，按创建时间倒序
+        """
+        cls._ensure_projects_dir()
+        
+        projects = []
+        for project_id in os.listdir(cls.PROJECTS_DIR):
+            project = cls.get_project(project_id)
+            if project:
+                projects.append(project)
+        
+        # 按创建时间倒序排序
+        projects.sort(key=lambda p: p.created_at, reverse=True)
+        
+        return projects[:limit]
+    
+    @classmethod
+    def delete_project(cls, project_id: str) -> bool:
+        """
+        删除项目及其所有文件
+        
+        Args:
+            project_id: 项目ID
+            
+        Returns:
+            是否删除成功
+        """
+        project_dir = cls._get_project_dir(project_id)
+        
+        if not os.path.exists(project_dir):
+            return False
+        
+        shutil.rmtree(project_dir)
+        return True
+    
+    @classmethod
+    def save_file_to_project(cls, project_id: str, file_storage, original_filename: str) -> Dict[str, str]:
+        """
+        保存上传的文件到项目目录
+        
+        Args:
+            project_id: 项目ID
+            file_storage: Flask的FileStorage对象
+            original_filename: 原始文件名
+            
+        Returns:
+            文件信息字典 {filename, path, size}
+        """
+        files_dir = cls._get_project_files_dir(project_id)
+        os.makedirs(files_dir, exist_ok=True)
+        
+        # 生成安全的文件名
+        ext = os.path.splitext(original_filename)[1].lower()
+        safe_filename = f"{uuid.uuid4().hex[:8]}{ext}"
+        file_path = os.path.join(files_dir, safe_filename)
+        
+        # 保存文件
+        file_storage.save(file_path)
+        
+        # 获取文件大小
+        file_size = os.path.getsize(file_path)
+        
+        return {
+            "original_filename": original_filename,
+            "saved_filename": safe_filename,
+            "path": file_path,
+            "size": file_size
+        }
+    
+    @classmethod
+    def save_extracted_text(cls, project_id: str, text: str) -> None:
+        """保存提取的文本"""
+        text_path = cls._get_project_text_path(project_id)
+        with open(text_path, 'w', encoding='utf-8') as f:
+            f.write(text)
+    
+    @classmethod
+    def get_extracted_text(cls, project_id: str) -> Optional[str]:
+        """获取提取的文本"""
+        text_path = cls._get_project_text_path(project_id)
+        
+        if not os.path.exists(text_path):
+            return None
+        
+        with open(text_path, 'r', encoding='utf-8') as f:
+            return f.read()
+    
+    @classmethod
+    def get_project_files(cls, project_id: str) -> List[str]:
+        """获取项目的所有文件路径"""
+        files_dir = cls._get_project_files_dir(project_id)
+        
+        if not os.path.exists(files_dir):
+            return []
+        
+        return [
+            os.path.join(files_dir, f) 
+            for f in os.listdir(files_dir) 
+            if os.path.isfile(os.path.join(files_dir, f))
+        ]
+

app/app/models/task.py

@@ -0,0 +1,184 @@
+"""
+任务状态管理
+用于跟踪长时间运行的任务（如图谱构建）
+"""
+
+import uuid
+import threading
+from datetime import datetime
+from enum import Enum
+from typing import Dict, Any, Optional
+from dataclasses import dataclass, field
+
+
+class TaskStatus(str, Enum):
+    """任务状态枚举"""
+    PENDING = "pending"          # 等待中
+    PROCESSING = "processing"    # 处理中
+    COMPLETED = "completed"      # 已完成
+    FAILED = "failed"            # 失败
+
+
+@dataclass
+class Task:
+    """任务数据类"""
+    task_id: str
+    task_type: str
+    status: TaskStatus
+    created_at: datetime
+    updated_at: datetime
+    progress: int = 0              # 总进度百分比 0-100
+    message: str = ""              # 状态消息
+    result: Optional[Dict] = None  # 任务结果
+    error: Optional[str] = None    # 错误信息
+    metadata: Dict = field(default_factory=dict)  # 额外元数据
+    progress_detail: Dict = field(default_factory=dict)  # 详细进度信息
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """转换为字典"""
+        return {
+            "task_id": self.task_id,
+            "task_type": self.task_type,
+            "status": self.status.value,
+            "created_at": self.created_at.isoformat(),
+            "updated_at": self.updated_at.isoformat(),
+            "progress": self.progress,
+            "message": self.message,
+            "progress_detail": self.progress_detail,
+            "result": self.result,
+            "error": self.error,
+            "metadata": self.metadata,
+        }
+
+
+class TaskManager:
+    """
+    任务管理器
+    线程安全的任务状态管理
+    """
+    
+    _instance = None
+    _lock = threading.Lock()
+    
+    def __new__(cls):
+        """单例模式"""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+                    cls._instance._tasks: Dict[str, Task] = {}
+                    cls._instance._task_lock = threading.Lock()
+        return cls._instance
+    
+    def create_task(self, task_type: str, metadata: Optional[Dict] = None) -> str:
+        """
+        创建新任务
+        
+        Args:
+            task_type: 任务类型
+            metadata: 额外元数据
+            
+        Returns:
+            任务ID
+        """
+        task_id = str(uuid.uuid4())
+        now = datetime.now()
+        
+        task = Task(
+            task_id=task_id,
+            task_type=task_type,
+            status=TaskStatus.PENDING,
+            created_at=now,
+            updated_at=now,
+            metadata=metadata or {}
+        )
+        
+        with self._task_lock:
+            self._tasks[task_id] = task
+        
+        return task_id
+    
+    def get_task(self, task_id: str) -> Optional[Task]:
+        """获取任务"""
+        with self._task_lock:
+            return self._tasks.get(task_id)
+    
+    def update_task(
+        self,
+        task_id: str,
+        status: Optional[TaskStatus] = None,
+        progress: Optional[int] = None,
+        message: Optional[str] = None,
+        result: Optional[Dict] = None,
+        error: Optional[str] = None,
+        progress_detail: Optional[Dict] = None
+    ):
+        """
+        更新任务状态
+        
+        Args:
+            task_id: 任务ID
+            status: 新状态
+            progress: 进度
+            message: 消息
+            result: 结果
+            error: 错误信息
+            progress_detail: 详细进度信息
+        """
+        with self._task_lock:
+            task = self._tasks.get(task_id)
+            if task:
+                task.updated_at = datetime.now()
+                if status is not None:
+                    task.status = status
+                if progress is not None:
+                    task.progress = progress
+                if message is not None:
+                    task.message = message
+                if result is not None:
+                    task.result = result
+                if error is not None:
+                    task.error = error
+                if progress_detail is not None:
+                    task.progress_detail = progress_detail
+    
+    def complete_task(self, task_id: str, result: Dict):
+        """标记任务完成"""
+        self.update_task(
+            task_id,
+            status=TaskStatus.COMPLETED,
+            progress=100,
+            message="任务完成",
+            result=result
+        )
+    
+    def fail_task(self, task_id: str, error: str):
+        """标记任务失败"""
+        self.update_task(
+            task_id,
+            status=TaskStatus.FAILED,
+            message="任务失败",
+            error=error
+        )
+    
+    def list_tasks(self, task_type: Optional[str] = None) -> list:
+        """列出任务"""
+        with self._task_lock:
+            tasks = list(self._tasks.values())
+            if task_type:
+                tasks = [t for t in tasks if t.task_type == task_type]
+            return [t.to_dict() for t in sorted(tasks, key=lambda x: x.created_at, reverse=True)]
+    
+    def cleanup_old_tasks(self, max_age_hours: int = 24):
+        """清理旧任务"""
+        from datetime import timedelta
+        cutoff = datetime.now() - timedelta(hours=max_age_hours)
+        
+        with self._task_lock:
+            old_ids = [
+                tid for tid, task in self._tasks.items()
+                if task.created_at < cutoff and task.status in [TaskStatus.COMPLETED, TaskStatus.FAILED]
+            ]
+            for tid in old_ids:
+                del self._tasks[tid]
+

app/app/services/__init__.py

@@ -0,0 +1,73 @@
+"""
+业务服务模块
+"""
+
+from .ontology_generator import OntologyGenerator
+from .graph_builder import GraphBuilderService
+from .text_processor import TextProcessor
+from .zep_entity_reader import ZepEntityReader, EntityNode, FilteredEntities
+from .oasis_profile_generator import OasisProfileGenerator, OasisAgentProfile
+from .simulation_manager import SimulationManager, SimulationState, SimulationStatus
+from .simulation_config_generator import (
+    SimulationConfigGenerator, 
+    SimulationParameters,
+    AgentActivityConfig,
+    TimeSimulationConfig,
+    EventConfig,
+    PlatformConfig
+)
+from .simulation_runner import (
+    SimulationRunner,
+    SimulationRunState,
+    RunnerStatus,
+    AgentAction,
+    RoundSummary
+)
+from .zep_graph_memory_updater import (
+    ZepGraphMemoryUpdater,
+    ZepGraphMemoryManager,
+    AgentActivity
+)
+from .simulation_ipc import (
+    SimulationIPCClient,
+    SimulationIPCServer,
+    IPCCommand,
+    IPCResponse,
+    CommandType,
+    CommandStatus
+)
+
+__all__ = [
+    'OntologyGenerator', 
+    'GraphBuilderService', 
+    'TextProcessor',
+    'ZepEntityReader',
+    'EntityNode',
+    'FilteredEntities',
+    'OasisProfileGenerator',
+    'OasisAgentProfile',
+    'SimulationManager',
+    'SimulationState',
+    'SimulationStatus',
+    'SimulationConfigGenerator',
+    'SimulationParameters',
+    'AgentActivityConfig',
+    'TimeSimulationConfig',
+    'EventConfig',
+    'PlatformConfig',
+    'SimulationRunner',
+    'SimulationRunState',
+    'RunnerStatus',
+    'AgentAction',
+    'RoundSummary',
+    'ZepGraphMemoryUpdater',
+    'ZepGraphMemoryManager',
+    'AgentActivity',
+    'SimulationIPCClient',
+    'SimulationIPCServer',
+    'IPCCommand',
+    'IPCResponse',
+    'CommandType',
+    'CommandStatus',
+]
+

app/app/services/__pycache__/report_agent.cpython-311.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e0abd3c1a2d5a1d6fb13ad578076ad09dfa74c527e44a79114bcfb8c101ea788
+size 108041

app/app/services/billing_service.py

@@ -0,0 +1,85 @@
+"""Razorpay orders, signature verification, coupon checks, and simulation payment JWTs."""
+
+from __future__ import annotations
+
+import time
+import uuid
+
+import jwt
+
+from ..config import Config
+
+
+def issue_simulation_payment_token(*, via: str) -> str:
+    """via: 'razorpay' | 'coupon'"""
+    now = int(time.time())
+    payload = {
+        "typ": "sim_pay",
+        "via": via,
+        "iat": now,
+        "exp": now + 3600,
+        "jti": uuid.uuid4().hex,
+    }
+    return jwt.encode(payload, Config.payment_signing_secret(), algorithm="HS256")
+
+
+def verify_simulation_payment_token(token: str | None) -> bool:
+    if not token or not str(token).strip():
+        return False
+    try:
+        payload = jwt.decode(
+            str(token).strip(),
+            Config.payment_signing_secret(),
+            algorithms=["HS256"],
+        )
+        return payload.get("typ") == "sim_pay"
+    except jwt.PyJWTError:
+        return False
+
+
+def create_razorpay_order() -> dict:
+    import razorpay
+
+    client = razorpay.Client(auth=(Config.RAZORPAY_KEY_ID, Config.RAZORPAY_KEY_SECRET))
+    receipt = f"mf_{uuid.uuid4().hex[:24]}"
+    order = client.order.create(
+        {
+            "amount": Config.RAZORPAY_AMOUNT_PAISE,
+            "currency": Config.RAZORPAY_CURRENCY,
+            "receipt": receipt,
+        }
+    )
+    return {
+        "order_id": order["id"],
+        "amount": order["amount"],
+        "currency": order["currency"],
+        "key_id": Config.RAZORPAY_KEY_ID,
+    }
+
+
+def verify_razorpay_payment_signature(
+    razorpay_order_id: str,
+    razorpay_payment_id: str,
+    razorpay_signature: str,
+) -> bool:
+    import razorpay
+
+    client = razorpay.Client(auth=(Config.RAZORPAY_KEY_ID, Config.RAZORPAY_KEY_SECRET))
+    try:
+        client.utility.verify_payment_signature(
+            {
+                "razorpay_order_id": razorpay_order_id,
+                "razorpay_payment_id": razorpay_payment_id,
+                "razorpay_signature": razorpay_signature,
+            }
+        )
+        return True
+    except Exception:
+        return False
+
+
+def coupon_valid(code: str | None) -> bool:
+    if not code:
+        return False
+    normalized = code.strip().lower()
+    return normalized in Config.payment_coupon_set()

app/app/services/graph_builder.py

@@ -0,0 +1,532 @@
+"""
+图谱构建服务
+接口2：使用Zep API构建Standalone Graph
+"""
+
+import os
+import uuid
+import time
+import threading
+from typing import Dict, Any, List, Optional, Callable
+from dataclasses import dataclass
+
+from zep_cloud.client import Zep
+from zep_cloud import EpisodeData, EntityEdgeSourceTarget
+
+from ..config import Config
+from ..models.task import TaskManager, TaskStatus
+from ..utils.api_key_runtime import call_with_limit_rotation, get_zep_key
+from ..utils.zep_paging import fetch_all_nodes, fetch_all_edges
+from .text_processor import TextProcessor
+
+
+@dataclass
+class GraphInfo:
+    """图谱信息"""
+    graph_id: str
+    node_count: int
+    edge_count: int
+    entity_types: List[str]
+    
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "graph_id": self.graph_id,
+            "node_count": self.node_count,
+            "edge_count": self.edge_count,
+            "entity_types": self.entity_types,
+        }
+
+
+class GraphBuilderService:
+    """
+    图谱构建服务
+    负责调用Zep API构建知识图谱
+    """
+    
+    def __init__(self, api_key: Optional[str] = None):
+        self._fixed_api_key = (api_key or "").strip() or None
+        if self._fixed_api_key:
+            self.api_key = self._fixed_api_key
+        else:
+            self.api_key = get_zep_key() or (Config.get_zep_api_keys()[0] if Config.get_zep_api_keys() else None)
+        if not self.api_key and not Config.get_zep_api_keys():
+            raise ValueError("ZEP_API_KEY 未配置")
+
+        self.client = Zep(api_key=self.api_key) if self._fixed_api_key else None  # noqa: SLF001
+        self.task_manager = TaskManager()
+
+    def _zep_call(self, fn):
+        """Zep API call with shared LLM/Zep rate-limit rotation (pipeline uses runtime keys)."""
+        if self._fixed_api_key:
+            return fn(Zep(api_key=self._fixed_api_key))
+
+        def run():
+            k = get_zep_key()
+            if not k:
+                raise ValueError("ZEP_API_KEY 未配置")
+            return fn(Zep(api_key=k))
+
+        return call_with_limit_rotation(run)
+    
+    def build_graph_async(
+        self,
+        text: str,
+        ontology: Dict[str, Any],
+        graph_name: str = "MiroFish Graph",
+        chunk_size: int = 500,
+        chunk_overlap: int = 50,
+        batch_size: int = 3
+    ) -> str:
+        """
+        异步构建图谱
+        
+        Args:
+            text: 输入文本
+            ontology: 本体定义（来自接口1的输出）
+            graph_name: 图谱名称
+            chunk_size: 文本块大小
+            chunk_overlap: 块重叠大小
+            batch_size: 每批发送的块数量
+            
+        Returns:
+            任务ID
+        """
+        # 创建任务
+        task_id = self.task_manager.create_task(
+            task_type="graph_build",
+            metadata={
+                "graph_name": graph_name,
+                "chunk_size": chunk_size,
+                "text_length": len(text),
+            }
+        )
+        
+        # 在后台线程中执行构建
+        thread = threading.Thread(
+            target=self._build_graph_worker,
+            args=(task_id, text, ontology, graph_name, chunk_size, chunk_overlap, batch_size)
+        )
+        thread.daemon = True
+        thread.start()
+        
+        return task_id
+    
+    def _build_graph_worker(
+        self,
+        task_id: str,
+        text: str,
+        ontology: Dict[str, Any],
+        graph_name: str,
+        chunk_size: int,
+        chunk_overlap: int,
+        batch_size: int
+    ):
+        """图谱构建工作线程"""
+        try:
+            self.task_manager.update_task(
+                task_id,
+                status=TaskStatus.PROCESSING,
+                progress=5,
+                message="开始构建图谱..."
+            )
+            
+            # 1. 创建图谱
+            graph_id = self.create_graph(graph_name)
+            self.task_manager.update_task(
+                task_id,
+                progress=10,
+                message=f"图谱已创建: {graph_id}"
+            )
+            
+            # 2. 设置本体
+            self.set_ontology(graph_id, ontology)
+            self.task_manager.update_task(
+                task_id,
+                progress=15,
+                message="本体已设置"
+            )
+            
+            # 3. 文本分块
+            chunks = TextProcessor.split_text(text, chunk_size, chunk_overlap)
+            total_chunks = len(chunks)
+            self.task_manager.update_task(
+                task_id,
+                progress=20,
+                message=f"文本已分割为 {total_chunks} 个块"
+            )
+            
+            # 4. 分批发送数据
+            episode_uuids = self.add_text_batches(
+                graph_id, chunks, batch_size,
+                lambda msg, prog: self.task_manager.update_task(
+                    task_id,
+                    progress=20 + int(prog * 0.4),  # 20-60%
+                    message=msg
+                )
+            )
+            
+            # 5. 等待Zep处理完成
+            self.task_manager.update_task(
+                task_id,
+                progress=60,
+                message="等待Zep处理数据..."
+            )
+            
+            self._wait_for_episodes(
+                episode_uuids,
+                lambda msg, prog: self.task_manager.update_task(
+                    task_id,
+                    progress=60 + int(prog * 0.3),  # 60-90%
+                    message=msg
+                )
+            )
+            
+            # 6. 获取图谱信息
+            self.task_manager.update_task(
+                task_id,
+                progress=90,
+                message="获取图谱信息..."
+            )
+            
+            graph_info = self._get_graph_info(graph_id)
+            
+            # 完成
+            self.task_manager.complete_task(task_id, {
+                "graph_id": graph_id,
+                "graph_info": graph_info.to_dict(),
+                "chunks_processed": total_chunks,
+            })
+            
+        except Exception as e:
+            import traceback
+            error_msg = f"{str(e)}\n{traceback.format_exc()}"
+            self.task_manager.fail_task(task_id, error_msg)
+    
+    def create_graph(self, name: str) -> str:
+        """创建Zep图谱（公开方法）"""
+        graph_id = f"mirofish_{uuid.uuid4().hex[:16]}"
+
+        def op(c: Zep):
+            c.graph.create(
+                graph_id=graph_id,
+                name=name,
+                description="MiroFish Social Simulation Graph",
+            )
+
+        self._zep_call(op)
+        return graph_id
+    
+    def set_ontology(self, graph_id: str, ontology: Dict[str, Any]):
+        """设置图谱本体（公开方法）"""
+        import warnings
+        from typing import Optional
+        from pydantic import Field
+        from zep_cloud.external_clients.ontology import EntityModel, EntityText, EdgeModel
+        
+        # 抑制 Pydantic v2 关于 Field(default=None) 的警告
+        # 这是 Zep SDK 要求的用法，警告来自动态类创建，可以安全忽略
+        warnings.filterwarnings('ignore', category=UserWarning, module='pydantic')
+        
+        # Zep 保留名称，不能作为属性名
+        RESERVED_NAMES = {'uuid', 'name', 'group_id', 'name_embedding', 'summary', 'created_at'}
+        
+        def safe_attr_name(attr_name: str) -> str:
+            """将保留名称转换为安全名称"""
+            if attr_name.lower() in RESERVED_NAMES:
+                return f"entity_{attr_name}"
+            return attr_name
+        
+        # 动态创建实体类型
+        entity_types = {}
+        for entity_def in ontology.get("entity_types", []):
+            name = entity_def["name"]
+            description = entity_def.get("description", f"A {name} entity.")
+            
+            # 创建属性字典和类型注解（Pydantic v2 需要）
+            attrs = {"__doc__": description}
+            annotations = {}
+            
+            for attr_def in entity_def.get("attributes", []):
+                attr_name = safe_attr_name(attr_def["name"])  # 使用安全名称
+                attr_desc = attr_def.get("description", attr_name)
+                # Zep API 需要 Field 的 description，这是必需的
+                attrs[attr_name] = Field(description=attr_desc, default=None)
+                annotations[attr_name] = Optional[EntityText]  # 类型注解
+            
+            attrs["__annotations__"] = annotations
+            
+            # 动态创建类
+            entity_class = type(name, (EntityModel,), attrs)
+            entity_class.__doc__ = description
+            entity_types[name] = entity_class
+        
+        # 动态创建边类型
+        edge_definitions = {}
+        for edge_def in ontology.get("edge_types", []):
+            name = edge_def["name"]
+            description = edge_def.get("description", f"A {name} relationship.")
+            
+            # 创建属性字典和类型注解
+            attrs = {"__doc__": description}
+            annotations = {}
+            
+            for attr_def in edge_def.get("attributes", []):
+                attr_name = safe_attr_name(attr_def["name"])  # 使用安全名称
+                attr_desc = attr_def.get("description", attr_name)
+                # Zep API 需要 Field 的 description，这是必需的
+                attrs[attr_name] = Field(description=attr_desc, default=None)
+                annotations[attr_name] = Optional[str]  # 边属性用str类型
+            
+            attrs["__annotations__"] = annotations
+            
+            # 动态创建类
+            class_name = ''.join(word.capitalize() for word in name.split('_'))
+            edge_class = type(class_name, (EdgeModel,), attrs)
+            edge_class.__doc__ = description
+            
+            # 构建source_targets
+            source_targets = []
+            for st in edge_def.get("source_targets", []):
+                source_targets.append(
+                    EntityEdgeSourceTarget(
+                        source=st.get("source", "Entity"),
+                        target=st.get("target", "Entity")
+                    )
+                )
+            
+            if source_targets:
+                edge_definitions[name] = (edge_class, source_targets)
+        
+        # 调用Zep API设置本体
+        if entity_types or edge_definitions:
+            def op(c: Zep):
+                c.graph.set_ontology(
+                    graph_ids=[graph_id],
+                    entities=entity_types if entity_types else None,
+                    edges=edge_definitions if edge_definitions else None,
+                )
+
+            self._zep_call(op)
+    
+    def add_text_batches(
+        self,
+        graph_id: str,
+        chunks: List[str],
+        batch_size: int = 3,
+        progress_callback: Optional[Callable] = None
+    ) -> List[str]:
+        """分批添加文本到图谱，返回所有 episode 的 uuid 列表"""
+        episode_uuids = []
+        total_chunks = len(chunks)
+        
+        for i in range(0, total_chunks, batch_size):
+            batch_chunks = chunks[i:i + batch_size]
+            batch_num = i // batch_size + 1
+            total_batches = (total_chunks + batch_size - 1) // batch_size
+            
+            if progress_callback:
+                progress = (i + len(batch_chunks)) / total_chunks
+                progress_callback(
+                    f"发送第 {batch_num}/{total_batches} 批数据 ({len(batch_chunks)} 块)...",
+                    progress
+                )
+            
+            # 构建episode数据
+            episodes = [
+                EpisodeData(data=chunk, type="text")
+                for chunk in batch_chunks
+            ]
+            
+            # 发送到Zep
+            try:
+                def op(c: Zep):
+                    return c.graph.add_batch(graph_id=graph_id, episodes=episodes)
+
+                batch_result = self._zep_call(op)
+                
+                # 收集返回的 episode uuid
+                if batch_result and isinstance(batch_result, list):
+                    for ep in batch_result:
+                        ep_uuid = getattr(ep, 'uuid_', None) or getattr(ep, 'uuid', None)
+                        if ep_uuid:
+                            episode_uuids.append(ep_uuid)
+                
+                # 避免请求过快
+                time.sleep(1)
+                
+            except Exception as e:
+                if progress_callback:
+                    progress_callback(f"批次 {batch_num} 发送失败: {str(e)}", 0)
+                raise
+        
+        return episode_uuids
+    
+    def _wait_for_episodes(
+        self,
+        episode_uuids: List[str],
+        progress_callback: Optional[Callable] = None,
+        timeout: int = 600
+    ):
+        """等待所有 episode 处理完成（通过查询每个 episode 的 processed 状态）"""
+        if not episode_uuids:
+            if progress_callback:
+                progress_callback("无需等待（没有 episode）", 1.0)
+            return
+        
+        start_time = time.time()
+        pending_episodes = set(episode_uuids)
+        completed_count = 0
+        total_episodes = len(episode_uuids)
+        
+        if progress_callback:
+            progress_callback(f"开始等待 {total_episodes} 个文本块处理...", 0)
+        
+        while pending_episodes:
+            if time.time() - start_time > timeout:
+                if progress_callback:
+                    progress_callback(
+                        f"部分文本块超时，已完成 {completed_count}/{total_episodes}",
+                        completed_count / total_episodes
+                    )
+                break
+            
+            # 检查每个 episode 的处理状态
+            for ep_uuid in list(pending_episodes):
+                try:
+                    def op(c: Zep):
+                        return c.graph.episode.get(uuid_=ep_uuid)
+
+                    episode = self._zep_call(op)
+                    is_processed = getattr(episode, 'processed', False)
+                    
+                    if is_processed:
+                        pending_episodes.remove(ep_uuid)
+                        completed_count += 1
+                        
+                except Exception as e:
+                    # 忽略单个查询错误，继续
+                    pass
+            
+            elapsed = int(time.time() - start_time)
+            if progress_callback:
+                progress_callback(
+                    f"Zep处理中... {completed_count}/{total_episodes} 完成, {len(pending_episodes)} 待处理 ({elapsed}秒)",
+                    completed_count / total_episodes if total_episodes > 0 else 0
+                )
+            
+            if pending_episodes:
+                time.sleep(3)  # 每3秒检查一次
+        
+        if progress_callback:
+            progress_callback(f"处理完成: {completed_count}/{total_episodes}", 1.0)
+    
+    def _get_graph_info(self, graph_id: str) -> GraphInfo:
+        """获取图谱信息"""
+
+        def fetch_pair(c: Zep):
+            return fetch_all_nodes(c, graph_id), fetch_all_edges(c, graph_id)
+
+        nodes, edges = self._zep_call(fetch_pair)
+
+        # 统计实体类型
+        entity_types = set()
+        for node in nodes:
+            if node.labels:
+                for label in node.labels:
+                    if label not in ["Entity", "Node"]:
+                        entity_types.add(label)
+
+        return GraphInfo(
+            graph_id=graph_id,
+            node_count=len(nodes),
+            edge_count=len(edges),
+            entity_types=list(entity_types)
+        )
+    
+    def get_graph_data(self, graph_id: str) -> Dict[str, Any]:
+        """
+        获取完整图谱数据（包含详细信息）
+        
+        Args:
+            graph_id: 图谱ID
+            
+        Returns:
+            包含nodes和edges的字典，包括时间信息、属性等详细数据
+        """
+        def fetch_pair(c: Zep):
+            return fetch_all_nodes(c, graph_id), fetch_all_edges(c, graph_id)
+
+        nodes, edges = self._zep_call(fetch_pair)
+
+        # 创建节点映射用于获取节点名称
+        node_map = {}
+        for node in nodes:
+            node_map[node.uuid_] = node.name or ""
+        
+        nodes_data = []
+        for node in nodes:
+            # 获取创建时间
+            created_at = getattr(node, 'created_at', None)
+            if created_at:
+                created_at = str(created_at)
+            
+            nodes_data.append({
+                "uuid": node.uuid_,
+                "name": node.name,
+                "labels": node.labels or [],
+                "summary": node.summary or "",
+                "attributes": node.attributes or {},
+                "created_at": created_at,
+            })
+        
+        edges_data = []
+        for edge in edges:
+            # 获取时间信息
+            created_at = getattr(edge, 'created_at', None)
+            valid_at = getattr(edge, 'valid_at', None)
+            invalid_at = getattr(edge, 'invalid_at', None)
+            expired_at = getattr(edge, 'expired_at', None)
+            
+            # 获取 episodes
+            episodes = getattr(edge, 'episodes', None) or getattr(edge, 'episode_ids', None)
+            if episodes and not isinstance(episodes, list):
+                episodes = [str(episodes)]
+            elif episodes:
+                episodes = [str(e) for e in episodes]
+            
+            # 获取 fact_type
+            fact_type = getattr(edge, 'fact_type', None) or edge.name or ""
+            
+            edges_data.append({
+                "uuid": edge.uuid_,
+                "name": edge.name or "",
+                "fact": edge.fact or "",
+                "fact_type": fact_type,
+                "source_node_uuid": edge.source_node_uuid,
+                "target_node_uuid": edge.target_node_uuid,
+                "source_node_name": node_map.get(edge.source_node_uuid, ""),
+                "target_node_name": node_map.get(edge.target_node_uuid, ""),
+                "attributes": edge.attributes or {},
+                "created_at": str(created_at) if created_at else None,
+                "valid_at": str(valid_at) if valid_at else None,
+                "invalid_at": str(invalid_at) if invalid_at else None,
+                "expired_at": str(expired_at) if expired_at else None,
+                "episodes": episodes or [],
+            })
+        
+        return {
+            "graph_id": graph_id,
+            "nodes": nodes_data,
+            "edges": edges_data,
+            "node_count": len(nodes_data),
+            "edge_count": len(edges_data),
+        }
+    
+    def delete_graph(self, graph_id: str):
+        """删除图谱"""
+
+        def op(c: Zep):
+            c.graph.delete(graph_id=graph_id)
+
+        self._zep_call(op)
+

app/app/services/oasis_profile_generator.py

@@ -0,0 +1,1339 @@
+"""
+OASIS Agent Profile生成器
+将Zep图谱中的实体转换为OASIS模拟平台所需的Agent Profile格式
+
+优化改进：
+1. 调用Zep检索功能二次丰富节点信息
+2. 优化提示词生成非常详细的人设
+3. 区分个人实体和抽象群体实体
+"""
+
+import json
+import random
+import time
+from typing import Dict, Any, List, Optional
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from openai import OpenAI
+from zep_cloud.client import Zep
+
+from ..config import Config
+from ..utils.api_key_runtime import call_with_limit_rotation, get_llm_key, get_zep_key
+from ..utils.logger import get_logger
+from .zep_entity_reader import EntityNode, ZepEntityReader
+
+logger = get_logger('mirofish.oasis_profile')
+
+
+@dataclass
+class OasisAgentProfile:
+    """OASIS Agent Profile数据结构"""
+    # 通用字段
+    user_id: int
+    user_name: str
+    name: str
+    bio: str
+    persona: str
+    
+    # 可选字段 - Reddit风格
+    karma: int = 1000
+    
+    # 可选字段 - Twitter风格
+    friend_count: int = 100
+    follower_count: int = 150
+    statuses_count: int = 500
+    
+    # 额外人设信息
+    age: Optional[int] = None
+    gender: Optional[str] = None
+    mbti: Optional[str] = None
+    country: Optional[str] = None
+    profession: Optional[str] = None
+    interested_topics: List[str] = field(default_factory=list)
+    
+    # 来源实体信息
+    source_entity_uuid: Optional[str] = None
+    source_entity_type: Optional[str] = None
+    
+    created_at: str = field(default_factory=lambda: datetime.now().strftime("%Y-%m-%d"))
+    
+    def to_reddit_format(self) -> Dict[str, Any]:
+        """转换为Reddit平台格式"""
+        profile = {
+            "user_id": self.user_id,
+            "username": self.user_name,  # OASIS 库要求字段名为 username（无下划线）
+            "name": self.name,
+            "bio": self.bio,
+            "persona": self.persona,
+            "karma": self.karma,
+            "created_at": self.created_at,
+        }
+        
+        # 添加额外人设信息（如果有）
+        if self.age:
+            profile["age"] = self.age
+        if self.gender:
+            profile["gender"] = self.gender
+        if self.mbti:
+            profile["mbti"] = self.mbti
+        if self.country:
+            profile["country"] = self.country
+        if self.profession:
+            profile["profession"] = self.profession
+        if self.interested_topics:
+            profile["interested_topics"] = self.interested_topics
+        
+        return profile
+    
+    def to_twitter_format(self) -> Dict[str, Any]:
+        """转换为Twitter平台格式"""
+        profile = {
+            "user_id": self.user_id,
+            "username": self.user_name,  # OASIS 库要求字段名为 username（无下划线）
+            "name": self.name,
+            "bio": self.bio,
+            "persona": self.persona,
+            "friend_count": self.friend_count,
+            "follower_count": self.follower_count,
+            "statuses_count": self.statuses_count,
+            "created_at": self.created_at,
+        }
+        
+        # 添加额外人设信息
+        if self.age:
+            profile["age"] = self.age
+        if self.gender:
+            profile["gender"] = self.gender
+        if self.mbti:
+            profile["mbti"] = self.mbti
+        if self.country:
+            profile["country"] = self.country
+        if self.profession:
+            profile["profession"] = self.profession
+        if self.interested_topics:
+            profile["interested_topics"] = self.interested_topics
+        
+        return profile
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """转换为完整字典格式"""
+        return {
+            "user_id": self.user_id,
+            "user_name": self.user_name,
+            "name": self.name,
+            "bio": self.bio,
+            "persona": self.persona,
+            "karma": self.karma,
+            "friend_count": self.friend_count,
+            "follower_count": self.follower_count,
+            "statuses_count": self.statuses_count,
+            "age": self.age,
+            "gender": self.gender,
+            "mbti": self.mbti,
+            "country": self.country,
+            "profession": self.profession,
+            "interested_topics": self.interested_topics,
+            "source_entity_uuid": self.source_entity_uuid,
+            "source_entity_type": self.source_entity_type,
+            "created_at": self.created_at,
+        }
+
+
+class OasisProfileGenerator:
+    """
+    OASIS Profile生成器
+    
+    将Zep图谱中的实体转换为OASIS模拟所需的Agent Profile
+    
+    优化特性：
+    1. 调用Zep图谱检索功能获取更丰富的上下文
+    2. 生成非常详细的人设（包括基本信息、职业经历、性格特征、社交媒体行为等）
+    3. 区分个人实体和抽象群体实体
+    """
+    
+    # MBTI类型列表
+    MBTI_TYPES = [
+        "INTJ", "INTP", "ENTJ", "ENTP",
+        "INFJ", "INFP", "ENFJ", "ENFP",
+        "ISTJ", "ISFJ", "ESTJ", "ESFJ",
+        "ISTP", "ISFP", "ESTP", "ESFP"
+    ]
+    
+    # 常见国家列表
+    COUNTRIES = [
+        "China", "US", "UK", "Japan", "Germany", "France", 
+        "Canada", "Australia", "Brazil", "India", "South Korea"
+    ]
+    
+    # 个人类型实体（需要生成具体人设）
+    INDIVIDUAL_ENTITY_TYPES = [
+        "student", "alumni", "professor", "person", "publicfigure", 
+        "expert", "faculty", "official", "journalist", "activist"
+    ]
+    
+    # 群体/机构类型实体（需要生成群体代表人设）
+    GROUP_ENTITY_TYPES = [
+        "university", "governmentagency", "organization", "ngo", 
+        "mediaoutlet", "company", "institution", "group", "community"
+    ]
+    
+    def __init__(
+        self, 
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        model_name: Optional[str] = None,
+        zep_api_key: Optional[str] = None,
+        graph_id: Optional[str] = None
+    ):
+        self._fixed_llm_key = (api_key or "").strip() or None
+        self.base_url = base_url or Config.LLM_BASE_URL
+        self.model_name = model_name or Config.LLM_MODEL_NAME
+
+        if self._fixed_llm_key:
+            self.api_key = self._fixed_llm_key
+            self.client = OpenAI(api_key=self.api_key, base_url=self.base_url)
+        else:
+            if not Config.get_llm_api_keys():
+                raise ValueError("LLM_API_KEY 未配置")
+            self.api_key = Config.get_llm_api_keys()[0]
+            self.client = None
+
+        # Zep客户端用于检索丰富上下文（运行时与 pipeline 共用 key slot）
+        self._fixed_zep_key = (zep_api_key or "").strip() or None
+        self.zep_api_key = self._fixed_zep_key or (
+            Config.get_zep_api_keys()[0] if Config.get_zep_api_keys() else None
+        )
+        self.zep_client = None
+        self.graph_id = graph_id
+
+        if self._fixed_zep_key:
+            try:
+                self.zep_client = Zep(api_key=self._fixed_zep_key)
+            except Exception as e:
+                logger.warning(f"Zep客户端初始化失败: {e}")
+    
+    def generate_profile_from_entity(
+        self, 
+        entity: EntityNode, 
+        user_id: int,
+        use_llm: bool = True
+    ) -> OasisAgentProfile:
+        """
+        从Zep实体生成OASIS Agent Profile
+        
+        Args:
+            entity: Zep实体节点
+            user_id: 用户ID（用于OASIS）
+            use_llm: 是否使用LLM生成详细人设
+            
+        Returns:
+            OasisAgentProfile
+        """
+        entity_type = entity.get_entity_type() or "Entity"
+        
+        # 基础信息
+        name = entity.name
+        user_name = self._generate_username(name)
+        
+        # 构建上下文信息
+        context = self._build_entity_context(entity)
+        
+        if use_llm:
+            # 使用LLM生成详细人设
+            profile_data = self._generate_profile_with_llm(
+                entity_name=name,
+                entity_type=entity_type,
+                entity_summary=entity.summary,
+                entity_attributes=entity.attributes,
+                context=context
+            )
+        else:
+            # 使用规则生成基础人设
+            profile_data = self._generate_profile_rule_based(
+                entity_name=name,
+                entity_type=entity_type,
+                entity_summary=entity.summary,
+                entity_attributes=entity.attributes
+            )
+        
+        return OasisAgentProfile(
+            user_id=user_id,
+            user_name=user_name,
+            name=name,
+            bio=profile_data.get("bio", f"{entity_type}: {name}"),
+            persona=profile_data.get("persona", entity.summary or f"A {entity_type} named {name}."),
+            karma=profile_data.get("karma", random.randint(500, 5000)),
+            friend_count=profile_data.get("friend_count", random.randint(50, 500)),
+            follower_count=profile_data.get("follower_count", random.randint(100, 1000)),
+            statuses_count=profile_data.get("statuses_count", random.randint(100, 2000)),
+            age=profile_data.get("age"),
+            gender=profile_data.get("gender"),
+            mbti=profile_data.get("mbti"),
+            country=profile_data.get("country"),
+            profession=profile_data.get("profession"),
+            interested_topics=profile_data.get("interested_topics", []),
+            source_entity_uuid=entity.uuid,
+            source_entity_type=entity_type,
+        )
+    
+    def _generate_username(self, name: str) -> str:
+        """生成用户名"""
+        # 移除特殊字符，转换为小写
+        username = name.lower().replace(" ", "_")
+        username = ''.join(c for c in username if c.isalnum() or c == '_')
+        
+        # 添加随机后缀避免重复
+        suffix = random.randint(100, 999)
+        return f"{username}_{suffix}"
+    
+    def _search_zep_for_entity(self, entity: EntityNode) -> Dict[str, Any]:
+        """
+        使用Zep图谱混合搜索功能获取实体相关的丰富信息
+        
+        Zep没有内置混合搜索接口，需要分别搜索edges和nodes然后合并结果。
+        使用并行请求同时搜索，提高效率。
+        
+        Args:
+            entity: 实体节点对象
+            
+        Returns:
+            包含facts, node_summaries, context的字典
+        """
+        import concurrent.futures
+        
+        if not self.graph_id:
+            return {"facts": [], "node_summaries": [], "context": ""}
+        if self._fixed_zep_key and not self.zep_client:
+            return {"facts": [], "node_summaries": [], "context": ""}
+        
+        entity_name = entity.name
+        
+        results = {
+            "facts": [],
+            "node_summaries": [],
+            "context": ""
+        }
+
+        comprehensive_query = f"关于{entity_name}的所有信息、活动、事件、关系和背景"
+        
+        def search_edges():
+            """搜索边（事实/关系）- 带重试机制"""
+            max_retries = 3
+            last_exception = None
+            delay = 2.0
+            
+            for attempt in range(max_retries):
+                try:
+                    def _edges():
+                        k = self._fixed_zep_key or get_zep_key()
+                        if not k:
+                            raise ValueError("ZEP_API_KEY 未配置")
+                        return Zep(api_key=k).graph.search(
+                            query=comprehensive_query,
+                            graph_id=self.graph_id,
+                            limit=30,
+                            scope="edges",
+                            reranker="rrf",
+                        )
+
+                    if self._fixed_zep_key:
+                        r = self.zep_client.graph.search(
+                            query=comprehensive_query,
+                            graph_id=self.graph_id,
+                            limit=30,
+                            scope="edges",
+                            reranker="rrf",
+                        )
+                    else:
+                        r = call_with_limit_rotation(_edges)
+                    return r
+                except Exception as e:
+                    last_exception = e
+                    if attempt < max_retries - 1:
+                        logger.debug(f"Zep边搜索第 {attempt + 1} 次失败: {str(e)[:80]}, 重试中...")
+                        time.sleep(delay)
+                        delay *= 2
+                    else:
+                        logger.debug(f"Zep边搜索在 {max_retries} 次尝试后仍失败: {e}")
+            return None
+        
+        def search_nodes():
+            """搜索节点（实体摘要）- 带重试机制"""
+            max_retries = 3
+            last_exception = None
+            delay = 2.0
+            
+            for attempt in range(max_retries):
+                try:
+                    def _nodes():
+                        k = self._fixed_zep_key or get_zep_key()
+                        if not k:
+                            raise ValueError("ZEP_API_KEY 未配置")
+                        return Zep(api_key=k).graph.search(
+                            query=comprehensive_query,
+                            graph_id=self.graph_id,
+                            limit=20,
+                            scope="nodes",
+                            reranker="rrf",
+                        )
+
+                    if self._fixed_zep_key:
+                        r = self.zep_client.graph.search(
+                            query=comprehensive_query,
+                            graph_id=self.graph_id,
+                            limit=20,
+                            scope="nodes",
+                            reranker="rrf",
+                        )
+                    else:
+                        r = call_with_limit_rotation(_nodes)
+                    return r
+                except Exception as e:
+                    last_exception = e
+                    if attempt < max_retries - 1:
+                        logger.debug(f"Zep节点搜索第 {attempt + 1} 次失败: {str(e)[:80]}, 重试中...")
+                        time.sleep(delay)
+                        delay *= 2
+                    else:
+                        logger.debug(f"Zep节点搜索在 {max_retries} 次尝试后仍失败: {e}")
+            return None
+        
+        try:
+            # 并行执行edges和nodes搜索
+            with concurrent.futures.ThreadPoolExecutor(max_workers=2) as executor:
+                edge_future = executor.submit(search_edges)
+                node_future = executor.submit(search_nodes)
+                
+                # 获取结果
+                edge_result = edge_future.result(timeout=30)
+                node_result = node_future.result(timeout=30)
+            
+            # 处理边搜索结果
+            all_facts = set()
+            if edge_result and hasattr(edge_result, 'edges') and edge_result.edges:
+                for edge in edge_result.edges:
+                    if hasattr(edge, 'fact') and edge.fact:
+                        all_facts.add(edge.fact)
+            results["facts"] = list(all_facts)
+            
+            # 处理节点搜索结果
+            all_summaries = set()
+            if node_result and hasattr(node_result, 'nodes') and node_result.nodes:
+                for node in node_result.nodes:
+                    if hasattr(node, 'summary') and node.summary:
+                        all_summaries.add(node.summary)
+                    if hasattr(node, 'name') and node.name and node.name != entity_name:
+                        all_summaries.add(f"相关实体: {node.name}")
+            results["node_summaries"] = list(all_summaries)
+            
+            # 构建综合上下文
+            context_parts = []
+            if results["facts"]:
+                context_parts.append("事实信息:\n" + "\n".join(f"- {f}" for f in results["facts"][:20]))
+            if results["node_summaries"]:
+                context_parts.append("相关实体:\n" + "\n".join(f"- {s}" for s in results["node_summaries"][:10]))
+            results["context"] = "\n\n".join(context_parts)
+            
+            logger.info(f"Zep混合检索完成: {entity_name}, 获取 {len(results['facts'])} 条事实, {len(results['node_summaries'])} 个相关节点")
+            
+        except concurrent.futures.TimeoutError:
+            logger.warning(f"Zep检索超时 ({entity_name})")
+        except Exception as e:
+            logger.warning(f"Zep检索失败 ({entity_name}): {e}")
+        
+        return results
+    
+    def _build_entity_context(self, entity: EntityNode) -> str:
+        """
+        构建实体的完整上下文信息
+        
+        包括：
+        1. 实体本身的边信息（事实）
+        2. 关联节点的详细信息
+        3. Zep混合检索到的丰富信息
+        """
+        context_parts = []
+        
+        # 1. 添加实体属性信息
+        if entity.attributes:
+            attrs = []
+            for key, value in entity.attributes.items():
+                if value and str(value).strip():
+                    attrs.append(f"- {key}: {value}")
+            if attrs:
+                context_parts.append("### 实体属性\n" + "\n".join(attrs))
+        
+        # 2. 添加相关边信息（事实/关系）
+        existing_facts = set()
+        if entity.related_edges:
+            relationships = []
+            for edge in entity.related_edges:  # 不限制数量
+                fact = edge.get("fact", "")
+                edge_name = edge.get("edge_name", "")
+                direction = edge.get("direction", "")
+                
+                if fact:
+                    relationships.append(f"- {fact}")
+                    existing_facts.add(fact)
+                elif edge_name:
+                    if direction == "outgoing":
+                        relationships.append(f"- {entity.name} --[{edge_name}]--> (相关实体)")
+                    else:
+                        relationships.append(f"- (相关实体) --[{edge_name}]--> {entity.name}")
+            
+            if relationships:
+                context_parts.append("### 相关事实和关系\n" + "\n".join(relationships))
+        
+        # 3. 添加关联节点的详细信息
+        if entity.related_nodes:
+            related_info = []
+            for node in entity.related_nodes:  # 不限制数量
+                node_name = node.get("name", "")
+                node_labels = node.get("labels", [])
+                node_summary = node.get("summary", "")
+                
+                # 过滤掉默认标签
+                custom_labels = [l for l in node_labels if l not in ["Entity", "Node"]]
+                label_str = f" ({', '.join(custom_labels)})" if custom_labels else ""
+                
+                if node_summary:
+                    related_info.append(f"- **{node_name}**{label_str}: {node_summary}")
+                else:
+                    related_info.append(f"- **{node_name}**{label_str}")
+            
+            if related_info:
+                context_parts.append("### 关联实体信息\n" + "\n".join(related_info))
+        
+        # 4. 使用Zep混合检索获取更丰富的信息
+        zep_results = self._search_zep_for_entity(entity)
+        
+        if zep_results.get("facts"):
+            # 去重：排除已存在的事实
+            new_facts = [f for f in zep_results["facts"] if f not in existing_facts]
+            if new_facts:
+                context_parts.append("### Zep检索到的事实信息\n" + "\n".join(f"- {f}" for f in new_facts[:15]))
+        
+        if zep_results.get("node_summaries"):
+            context_parts.append("### Zep检索到的相关节点\n" + "\n".join(f"- {s}" for s in zep_results["node_summaries"][:10]))
+        
+        return "\n\n".join(context_parts)
+    
+    def _is_individual_entity(self, entity_type: str) -> bool:
+        """判断是否是个人类型实体"""
+        return entity_type.lower() in self.INDIVIDUAL_ENTITY_TYPES
+    
+    def _is_group_entity(self, entity_type: str) -> bool:
+        """判断是否是群体/机构类型实体"""
+        return entity_type.lower() in self.GROUP_ENTITY_TYPES
+    
+    def _generate_profile_with_llm(
+        self,
+        entity_name: str,
+        entity_type: str,
+        entity_summary: str,
+        entity_attributes: Dict[str, Any],
+        context: str
+    ) -> Dict[str, Any]:
+        """
+        使用LLM生成非常详细的人设
+        
+        根据实体类型区分：
+        - 个人实体：生成具体的人物设定
+        - 群体/机构实体：生成代表性账号设定
+        """
+        
+        is_individual = self._is_individual_entity(entity_type)
+        
+        if is_individual:
+            prompt = self._build_individual_persona_prompt(
+                entity_name, entity_type, entity_summary, entity_attributes, context
+            )
+        else:
+            prompt = self._build_group_persona_prompt(
+                entity_name, entity_type, entity_summary, entity_attributes, context
+            )
+
+        # 尝试多次生成，直到成功或达到最大重试次数
+        max_attempts = 3
+        last_error = None
+        
+        for attempt in range(max_attempts):
+            try:
+                def _create():
+                    if self._fixed_llm_key:
+                        return self.client.chat.completions.create(
+                            model=self.model_name,
+                            messages=[
+                                {"role": "system", "content": self._get_system_prompt(is_individual)},
+                                {"role": "user", "content": prompt},
+                            ],
+                            response_format={"type": "json_object"},
+                            temperature=0.7 - (attempt * 0.1),
+                        )
+                    key = get_llm_key()
+                    if not key:
+                        raise ValueError("LLM_API_KEY 未配置")
+                    cl = OpenAI(api_key=key, base_url=self.base_url)
+                    return cl.chat.completions.create(
+                        model=self.model_name,
+                        messages=[
+                            {"role": "system", "content": self._get_system_prompt(is_individual)},
+                            {"role": "user", "content": prompt},
+                        ],
+                        response_format={"type": "json_object"},
+                        temperature=0.7 - (attempt * 0.1),
+                    )
+
+                response = (
+                    self.client.chat.completions.create(
+                        model=self.model_name,
+                        messages=[
+                            {"role": "system", "content": self._get_system_prompt(is_individual)},
+                            {"role": "user", "content": prompt},
+                        ],
+                        response_format={"type": "json_object"},
+                        temperature=0.7 - (attempt * 0.1),
+                    )
+                    if self._fixed_llm_key
+                    else call_with_limit_rotation(_create)
+                )
+                
+                content = response.choices[0].message.content
+                
+                # 检查是否被截断（finish_reason不是'stop'）
+                finish_reason = response.choices[0].finish_reason
+                if finish_reason == 'length':
+                    logger.warning(f"LLM输出被截断 (attempt {attempt+1}), 尝试修复...")
+                    content = self._fix_truncated_json(content)
+                
+                # 尝试解析JSON
+                try:
+                    result = json.loads(content)
+                    
+                    # 验证必需字段
+                    if "bio" not in result or not result["bio"]:
+                        result["bio"] = entity_summary[:200] if entity_summary else f"{entity_type}: {entity_name}"
+                    if "persona" not in result or not result["persona"]:
+                        result["persona"] = entity_summary or f"{entity_name}是一个{entity_type}。"
+                    
+                    return result
+                    
+                except json.JSONDecodeError as je:
+                    logger.warning(f"JSON解析失败 (attempt {attempt+1}): {str(je)[:80]}")
+                    
+                    # 尝试修复JSON
+                    result = self._try_fix_json(content, entity_name, entity_type, entity_summary)
+                    if result.get("_fixed"):
+                        del result["_fixed"]
+                        return result
+                    
+                    last_error = je
+                    
+            except Exception as e:
+                logger.warning(f"LLM调用失败 (attempt {attempt+1}): {str(e)[:80]}")
+                last_error = e
+                import time
+                time.sleep(1 * (attempt + 1))  # 指数退避
+        
+        logger.warning(f"LLM生成人设失败（{max_attempts}次尝试）: {last_error}, 使用规则生成")
+        return self._generate_profile_rule_based(
+            entity_name, entity_type, entity_summary, entity_attributes
+        )
+    
+    def _fix_truncated_json(self, content: str) -> str:
+        """修复被截断的JSON（输出被max_tokens限制截断）"""
+        import re
+        
+        # 如果JSON被截断，尝试闭合它
+        content = content.strip()
+        
+        # 计算未闭合的括号
+        open_braces = content.count('{') - content.count('}')
+        open_brackets = content.count('[') - content.count(']')
+        
+        # 检查是否有未闭合的字符串
+        # 简单检查：如果最后一个引号后没有逗号或闭合括号，可能是字符串被截断
+        if content and content[-1] not in '",}]':
+            # 尝试闭合字符串
+            content += '"'
+        
+        # 闭合括号
+        content += ']' * open_brackets
+        content += '}' * open_braces
+        
+        return content
+    
+    def _try_fix_json(self, content: str, entity_name: str, entity_type: str, entity_summary: str = "") -> Dict[str, Any]:
+        """尝试修复损坏的JSON"""
+        import re
+        
+        # 1. 首先尝试修复被截断的情况
+        content = self._fix_truncated_json(content)
+        
+        # 2. 尝试提取JSON部分
+        json_match = re.search(r'\{[\s\S]*\}', content)
+        if json_match:
+            json_str = json_match.group()
+            
+            # 3. 处理字符串中的换行符问题
+            # 找到所有字符串值并替换其中的换行符
+            def fix_string_newlines(match):
+                s = match.group(0)
+                # 替换字符串内的实际换行符为空格
+                s = s.replace('\n', ' ').replace('\r', ' ')
+                # 替换多余空格
+                s = re.sub(r'\s+', ' ', s)
+                return s
+            
+            # 匹配JSON字符串值
+            json_str = re.sub(r'"[^"\\]*(?:\\.[^"\\]*)*"', fix_string_newlines, json_str)
+            
+            # 4. 尝试解析
+            try:
+                result = json.loads(json_str)
+                result["_fixed"] = True
+                return result
+            except json.JSONDecodeError as e:
+                # 5. 如果还是失败，尝试更激进的修复
+                try:
+                    # 移除所有控制字符
+                    json_str = re.sub(r'[\x00-\x1f\x7f-\x9f]', ' ', json_str)
+                    # 替换所有连续空白
+                    json_str = re.sub(r'\s+', ' ', json_str)
+                    result = json.loads(json_str)
+                    result["_fixed"] = True
+                    return result
+                except:
+                    pass
+        
+        # 6. 尝试从内容中提取部分信息
+        bio_match = re.search(r'"bio"\s*:\s*"([^"]*)"', content)
+        persona_match = re.search(r'"persona"\s*:\s*"([^"]*)', content)  # 可能被截断
+        
+        bio = bio_match.group(1) if bio_match else (entity_summary[:200] if entity_summary else f"{entity_type}: {entity_name}")
+        persona = persona_match.group(1) if persona_match else (entity_summary or f"{entity_name}是一个{entity_type}。")
+        
+        # 如果提取到了有意义的内容，标记为已修复
+        if bio_match or persona_match:
+            logger.info(f"从损坏的JSON中提取了部分信息")
+            return {
+                "bio": bio,
+                "persona": persona,
+                "_fixed": True
+            }
+        
+        # 7. 完全失败，返回基础结构
+        logger.warning(f"JSON修复失败，返回基础结构")
+        return {
+            "bio": entity_summary[:200] if entity_summary else f"{entity_type}: {entity_name}",
+            "persona": entity_summary or f"{entity_name}是一个{entity_type}。"
+        }
+    
+    def _get_system_prompt(self, is_individual: bool) -> str:
+        """获取系统提示词"""
+        base_prompt = (
+            "你是社交媒体用户画像生成专家。生成详细、真实的人设用于「创业想法验证」舆论模拟："
+            "实体可能为硅谷风格 VC、YC 式合伙人、难取悦的天使、同行创始人、目标付费客户、犹豫用户等。"
+            "人设须体现其对该类想法的典型评判标准（ traction、差异化、团队、风险等）。"
+            "必须返回有效的JSON格式，所有字符串值不能包含未转义的换行符。使用中文。"
+        )
+        return base_prompt
+    
+    def _build_individual_persona_prompt(
+        self,
+        entity_name: str,
+        entity_type: str,
+        entity_summary: str,
+        entity_attributes: Dict[str, Any],
+        context: str
+    ) -> str:
+        """构建个人实体的详细人设提示词"""
+        
+        attrs_str = json.dumps(entity_attributes, ensure_ascii=False) if entity_attributes else "无"
+        context_str = context[:3000] if context else "无额外上下文"
+        
+        return f"""为实体生成详细的社交媒体用户人设,最大程度还原已有现实情况。
+
+实体名称: {entity_name}
+实体类型: {entity_type}
+实体摘要: {entity_summary}
+实体属性: {attrs_str}
+
+上下文信息:
+{context_str}
+
+请生成JSON，包含以下字段:
+
+1. bio: 社交媒体简介，200字
+2. persona: 详细人设描述（2000字的纯文本），需包含:
+   - 基本信息（年龄、职业、教育背景、所在地）
+   - 人物背景（重要经历、与事件的关联、社会关系）
+   - 性格特征（MBTI类型、核心性格、情绪表达方式）
+   - 社交媒体行为（发帖频率、内容偏好、互动风格、语言特点）
+   - 立场观点（对话题的态度；若是投资人需体现投资偏好与挑剔点；若是客户需体现付费阈值与痛点）
+   - 独特特征（口头禅、特殊经历、个人爱好）
+   - 个人记忆（人设的重要部分：该个体与材料中创业想法/事件的关系，以及已有动作与反应）
+3. age: 年龄数字（必须是整数）
+4. gender: 性别，必须是英文: "male" 或 "female"
+5. mbti: MBTI类型（如INTJ、ENFP等）
+6. country: 国家（使用中文，如"中国"）
+7. profession: 职业
+8. interested_topics: 感兴趣话题数组
+
+重要:
+- 所有字段值必须是字符串或数字，不要使用换行符
+- persona必须是一段连贯的文字描述
+- 使用中文（除了gender字段必须用英文male/female）
+- 内容要与实体信息保持一致
+- age必须是有效的整数，gender必须是"male"或"female"
+"""
+
+    def _build_group_persona_prompt(
+        self,
+        entity_name: str,
+        entity_type: str,
+        entity_summary: str,
+        entity_attributes: Dict[str, Any],
+        context: str
+    ) -> str:
+        """构建群体/机构实体的详细人设提示词"""
+        
+        attrs_str = json.dumps(entity_attributes, ensure_ascii=False) if entity_attributes else "无"
+        context_str = context[:3000] if context else "无额外上下文"
+        
+        return f"""为机构/群体实体生成详细的社交媒体账号设定,最大程度还原已有现实情况。
+
+实体名称: {entity_name}
+实体类型: {entity_type}
+实体摘要: {entity_summary}
+实体属性: {attrs_str}
+
+上下文信息:
+{context_str}
+
+请生成JSON，包含以下字段:
+
+1. bio: 官方账号简介，200字，专业得体
+2. persona: 详细账号设定描述（2000字的纯文本），需包含:
+   - 机构基本信息（正式名称、机构性质、成立背景、主要职能）
+   - 账号定位（账号类型、目标受众、核心功能）
+   - 发言风格（语言特点、常用表达、禁忌话题）
+   - 发布内容特点（内容类型、发布频率、活跃时间段）
+   - 立场态度（对核心话题的官方立场、面对争议的处理方式；若是投资机构/媒体需体现对该赛道的公开态度）
+   - 特殊说明（代表的群体画像、运营习惯）
+   - 机构记忆（机构与材料中创业想法/事件的关系，以及已有动作与反应）
+3. age: 固定填30（机构账号的虚拟年龄）
+4. gender: 固定填"other"（机构账号使用other表示非个人）
+5. mbti: MBTI类型，用于描述账号风格，如ISTJ代表严谨保守
+6. country: 国家（使用中文，如"中国"）
+7. profession: 机构职能描述
+8. interested_topics: 关注领域数组
+
+重要:
+- 所有字段值必须是字符串或数字，不允许null值
+- persona必须是一段连贯的文字描述，不要使用换行符
+- 使用中文（除了gender字段必须用英文"other"）
+- age必须是整数30，gender必须是字符串"other"
+- 机构账号发言要符合其身份定位"""
+    
+    def _generate_profile_rule_based(
+        self,
+        entity_name: str,
+        entity_type: str,
+        entity_summary: str,
+        entity_attributes: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """使用规则生成基础人设"""
+        
+        # 根据实体类型生成不同的人设
+        entity_type_lower = entity_type.lower()
+        
+        if entity_type_lower in ["student", "alumni"]:
+            return {
+                "bio": f"{entity_type} with interests in academics and social issues.",
+                "persona": f"{entity_name} is a {entity_type.lower()} who is actively engaged in academic and social discussions. They enjoy sharing perspectives and connecting with peers.",
+                "age": random.randint(18, 30),
+                "gender": random.choice(["male", "female"]),
+                "mbti": random.choice(self.MBTI_TYPES),
+                "country": random.choice(self.COUNTRIES),
+                "profession": "Student",
+                "interested_topics": ["Education", "Social Issues", "Technology"],
+            }
+        
+        elif entity_type_lower in ["publicfigure", "expert", "faculty"]:
+            return {
+                "bio": f"Expert and thought leader in their field.",
+                "persona": f"{entity_name} is a recognized {entity_type.lower()} who shares insights and opinions on important matters. They are known for their expertise and influence in public discourse.",
+                "age": random.randint(35, 60),
+                "gender": random.choice(["male", "female"]),
+                "mbti": random.choice(["ENTJ", "INTJ", "ENTP", "INTP"]),
+                "country": random.choice(self.COUNTRIES),
+                "profession": entity_attributes.get("occupation", "Expert"),
+                "interested_topics": ["Politics", "Economics", "Culture & Society"],
+            }
+        
+        elif entity_type_lower in ["mediaoutlet", "socialmediaplatform"]:
+            return {
+                "bio": f"Official account for {entity_name}. News and updates.",
+                "persona": f"{entity_name} is a media entity that reports news and facilitates public discourse. The account shares timely updates and engages with the audience on current events.",
+                "age": 30,  # 机构虚拟年龄
+                "gender": "other",  # 机构使用other
+                "mbti": "ISTJ",  # 机构风格：严谨保守
+                "country": "中国",
+                "profession": "Media",
+                "interested_topics": ["General News", "Current Events", "Public Affairs"],
+            }
+        
+        elif entity_type_lower in ["university", "governmentagency", "ngo", "organization"]:
+            return {
+                "bio": f"Official account of {entity_name}.",
+                "persona": f"{entity_name} is an institutional entity that communicates official positions, announcements, and engages with stakeholders on relevant matters.",
+                "age": 30,  # 机构虚拟年龄
+                "gender": "other",  # 机构使用other
+                "mbti": "ISTJ",  # 机构风格：严谨保守
+                "country": "中国",
+                "profession": entity_type,
+                "interested_topics": ["Public Policy", "Community", "Official Announcements"],
+            }
+        
+        elif entity_type_lower in ["ventureinvestor", "venturecapitalfirm"]:
+            return {
+                "bio": "VC partner; focuses on traction, moat, and team.",
+                "persona": f"{entity_name} is a Silicon Valley-style VC who is hard to impress, asks about TAM and defensibility, and rarely commits without signal.",
+                "age": random.randint(32, 55),
+                "gender": random.choice(["male", "female"]),
+                "mbti": random.choice(["ENTJ", "INTJ", "ESTJ"]),
+                "country": "美国",
+                "profession": "Venture Investor",
+                "interested_topics": ["Startups", "B2B SaaS", "Fundraising"],
+            }
+        
+        elif entity_type_lower in ["angelinvestor"]:
+            return {
+                "bio": "Angel investor; skeptical, pattern-matches on founders.",
+                "persona": f"{entity_name} is a picky angel who has seen many pitches and pushes back on vague metrics and hype.",
+                "age": random.randint(38, 62),
+                "gender": random.choice(["male", "female"]),
+                "mbti": random.choice(["INTJ", "ISTP", "ENTP"]),
+                "country": random.choice(self.COUNTRIES),
+                "profession": "Angel Investor",
+                "interested_topics": ["Early-stage", "Angel deals", "Product-market fit"],
+            }
+        
+        elif entity_type_lower in ["acceleratorpartner"]:
+            return {
+                "bio": "Accelerator partner; YC-style fast feedback and clarity.",
+                "persona": f"{entity_name} is an accelerator partner who demands clear one-liners, weekly growth, and ruthless focus—friendly but intense.",
+                "age": random.randint(30, 48),
+                "gender": random.choice(["male", "female"]),
+                "mbti": random.choice(["ENTJ", "ENFP", "ENTP"]),
+                "country": "美国",
+                "profession": "Accelerator Partner",
+                "interested_topics": ["Demo day", "Batch companies", "Mentorship"],
+            }
+        
+        elif entity_type_lower in ["startupfounder"]:
+            return {
+                "bio": "Peer founder building in the same space.",
+                "persona": f"{entity_name} is another founder who compares ideas to their own roadmap, shares war stories, and may collaborate or compete.",
+                "age": random.randint(26, 45),
+                "gender": random.choice(["male", "female"]),
+                "mbti": random.choice(self.MBTI_TYPES),
+                "country": random.choice(self.COUNTRIES),
+                "profession": "Startup Founder",
+                "interested_topics": ["Product", "Growth", "Fundraising"],
+            }
+        
+        elif entity_type_lower in ["targetcustomer"]:
+            return {
+                "bio": "Potential buyer / adopter in the ICP.",
+                "persona": f"{entity_name} is a target customer who cares about price, workflow fit, and whether the product solves a real daily pain.",
+                "age": random.randint(25, 52),
+                "gender": random.choice(["male", "female"]),
+                "mbti": random.choice(["ISFJ", "ESTJ", "ENFP", "ISTJ"]),
+                "country": random.choice(self.COUNTRIES),
+                "profession": "Buyer / User",
+                "interested_topics": ["ROI", "Usability", "Support"],
+            }
+        
+        elif entity_type_lower in ["skepticaluser"]:
+            return {
+                "bio": "On-the-fence or negative potential user.",
+                "persona": f"{entity_name} is skeptical about new tools—worried about switching cost, privacy, or whether the idea beats incumbents.",
+                "age": random.randint(22, 55),
+                "gender": random.choice(["male", "female"]),
+                "mbti": random.choice(["ISTP", "INTP", "ISTJ"]),
+                "country": random.choice(self.COUNTRIES),
+                "profession": "Skeptical User",
+                "interested_topics": ["Trust", "Alternatives", "Risk"],
+            }
+        
+        else:
+            # 默认人设
+            return {
+                "bio": entity_summary[:150] if entity_summary else f"{entity_type}: {entity_name}",
+                "persona": entity_summary or f"{entity_name} is a {entity_type.lower()} participating in social discussions.",
+                "age": random.randint(25, 50),
+                "gender": random.choice(["male", "female"]),
+                "mbti": random.choice(self.MBTI_TYPES),
+                "country": random.choice(self.COUNTRIES),
+                "profession": entity_type,
+                "interested_topics": ["General", "Social Issues"],
+            }
+    
+    def set_graph_id(self, graph_id: str):
+        """设置图谱ID用于Zep检索"""
+        self.graph_id = graph_id
+    
+    def generate_profiles_from_entities(
+        self,
+        entities: List[EntityNode],
+        use_llm: bool = True,
+        progress_callback: Optional[callable] = None,
+        graph_id: Optional[str] = None,
+        parallel_count: int = 5,
+        realtime_output_path: Optional[str] = None,
+        output_platform: str = "reddit"
+    ) -> List[OasisAgentProfile]:
+        """
+        批量从实体生成Agent Profile（支持并行生成）
+        
+        Args:
+            entities: 实体列表
+            use_llm: 是否使用LLM生成详细人设
+            progress_callback: 进度回调函数 (current, total, message)
+            graph_id: 图谱ID，用于Zep检索获取更丰富上下文
+            parallel_count: 并行生成数量，默认5
+            realtime_output_path: 实时写入的文件路径（如果提供，每生成一个就写入一次）
+            output_platform: 输出平台格式 ("reddit" 或 "twitter")
+            
+        Returns:
+            Agent Profile列表
+        """
+        import concurrent.futures
+        from threading import Lock
+        
+        # 设置graph_id用于Zep检索
+        if graph_id:
+            self.graph_id = graph_id
+        
+        total = len(entities)
+        profiles = [None] * total  # 预分配列表保持顺序
+        completed_count = [0]  # 使用列表以便在闭包中修改
+        lock = Lock()
+        
+        # 实时写入文件的辅助函数
+        def save_profiles_realtime():
+            """实时保存已生成的 profiles 到文件"""
+            if not realtime_output_path:
+                return
+            
+            with lock:
+                # 过滤出已生成的 profiles
+                existing_profiles = [p for p in profiles if p is not None]
+                if not existing_profiles:
+                    return
+                
+                try:
+                    if output_platform == "reddit":
+                        # Reddit JSON 格式
+                        profiles_data = [p.to_reddit_format() for p in existing_profiles]
+                        with open(realtime_output_path, 'w', encoding='utf-8') as f:
+                            json.dump(profiles_data, f, ensure_ascii=False, indent=2)
+                    else:
+                        # Twitter CSV 格式
+                        import csv
+                        profiles_data = [p.to_twitter_format() for p in existing_profiles]
+                        if profiles_data:
+                            fieldnames = list(profiles_data[0].keys())
+                            with open(realtime_output_path, 'w', encoding='utf-8', newline='') as f:
+                                writer = csv.DictWriter(f, fieldnames=fieldnames)
+                                writer.writeheader()
+                                writer.writerows(profiles_data)
+                except Exception as e:
+                    logger.warning(f"实时保存 profiles 失败: {e}")
+        
+        def generate_single_profile(idx: int, entity: EntityNode) -> tuple:
+            """生成单个profile的工作函数"""
+            entity_type = entity.get_entity_type() or "Entity"
+            
+            try:
+                profile = self.generate_profile_from_entity(
+                    entity=entity,
+                    user_id=idx,
+                    use_llm=use_llm
+                )
+                
+                # 实时输出生成的人设到控制台和日志
+                self._print_generated_profile(entity.name, entity_type, profile)
+                
+                return idx, profile, None
+                
+            except Exception as e:
+                logger.error(f"生成实体 {entity.name} 的人设失败: {str(e)}")
+                # 创建一个基础profile
+                fallback_profile = OasisAgentProfile(
+                    user_id=idx,
+                    user_name=self._generate_username(entity.name),
+                    name=entity.name,
+                    bio=f"{entity_type}: {entity.name}",
+                    persona=entity.summary or f"A participant in social discussions.",
+                    source_entity_uuid=entity.uuid,
+                    source_entity_type=entity_type,
+                )
+                return idx, fallback_profile, str(e)
+        
+        logger.info(f"开始并行生成 {total} 个Agent人设（并行数: {parallel_count}）...")
+        print(f"\n{'='*60}")
+        print(f"开始生成Agent人设 - 共 {total} 个实体，并行数: {parallel_count}")
+        print(f"{'='*60}\n")
+        
+        # 使用线程池并行执行
+        with concurrent.futures.ThreadPoolExecutor(max_workers=parallel_count) as executor:
+            # 提交所有任务
+            future_to_entity = {
+                executor.submit(generate_single_profile, idx, entity): (idx, entity)
+                for idx, entity in enumerate(entities)
+            }
+            
+            # 收集结果
+            for future in concurrent.futures.as_completed(future_to_entity):
+                idx, entity = future_to_entity[future]
+                entity_type = entity.get_entity_type() or "Entity"
+                
+                try:
+                    result_idx, profile, error = future.result()
+                    profiles[result_idx] = profile
+                    
+                    with lock:
+                        completed_count[0] += 1
+                        current = completed_count[0]
+                    
+                    # 实时写入文件
+                    save_profiles_realtime()
+                    
+                    if progress_callback:
+                        progress_callback(
+                            current, 
+                            total, 
+                            f"已完成 {current}/{total}: {entity.name}（{entity_type}）"
+                        )
+                    
+                    if error:
+                        logger.warning(f"[{current}/{total}] {entity.name} 使用备用人设: {error}")
+                    else:
+                        logger.info(f"[{current}/{total}] 成功生成人设: {entity.name} ({entity_type})")
+                        
+                except Exception as e:
+                    logger.error(f"处理实体 {entity.name} 时发生异常: {str(e)}")
+                    with lock:
+                        completed_count[0] += 1
+                    profiles[idx] = OasisAgentProfile(
+                        user_id=idx,
+                        user_name=self._generate_username(entity.name),
+                        name=entity.name,
+                        bio=f"{entity_type}: {entity.name}",
+                        persona=entity.summary or "A participant in social discussions.",
+                        source_entity_uuid=entity.uuid,
+                        source_entity_type=entity_type,
+                    )
+                    # 实时写入文件（即使是备用人设）
+                    save_profiles_realtime()
+        
+        print(f"\n{'='*60}")
+        print(f"人设生成完成！共生成 {len([p for p in profiles if p])} 个Agent")
+        print(f"{'='*60}\n")
+        
+        return profiles
+    
+    def _print_generated_profile(self, entity_name: str, entity_type: str, profile: OasisAgentProfile):
+        """实时输出生成的人设到控制台（完整内容，不截断）"""
+        separator = "-" * 70
+        
+        # 构建完整输出内容（不截断）
+        topics_str = ', '.join(profile.interested_topics) if profile.interested_topics else '无'
+        
+        output_lines = [
+            f"\n{separator}",
+            f"[已生成] {entity_name} ({entity_type})",
+            f"{separator}",
+            f"用户名: {profile.user_name}",
+            f"",
+            f"【简介】",
+            f"{profile.bio}",
+            f"",
+            f"【详细人设】",
+            f"{profile.persona}",
+            f"",
+            f"【基本属性】",
+            f"年龄: {profile.age} | 性别: {profile.gender} | MBTI: {profile.mbti}",
+            f"职业: {profile.profession} | 国家: {profile.country}",
+            f"兴趣话题: {topics_str}",
+            separator
+        ]
+        
+        output = "\n".join(output_lines)
+        
+        # 只输出到控制台（避免重复，logger不再输出完整内容）
+        print(output)
+    
+    def save_profiles(
+        self,
+        profiles: List[OasisAgentProfile],
+        file_path: str,
+        platform: str = "reddit"
+    ):
+        """
+        保存Profile到文件（根据平台选择正确格式）
+        
+        OASIS平台格式要求：
+        - Twitter: CSV格式
+        - Reddit: JSON格式
+        
+        Args:
+            profiles: Profile列表
+            file_path: 文件路径
+            platform: 平台类型 ("reddit" 或 "twitter")
+        """
+        if platform == "twitter":
+            self._save_twitter_csv(profiles, file_path)
+        else:
+            self._save_reddit_json(profiles, file_path)
+    
+    def _save_twitter_csv(self, profiles: List[OasisAgentProfile], file_path: str):
+        """
+        保存Twitter Profile为CSV格式（符合OASIS官方要求）
+        
+        OASIS Twitter要求的CSV字段：
+        - user_id: 用户ID（根据CSV顺序从0开始）
+        - name: 用户真实姓名
+        - username: 系统中的用户名
+        - user_char: 详细人设描述（注入到LLM系统提示中，指导Agent行为）
+        - description: 简短的公开简介（显示在用户资料页面）
+        
+        user_char vs description 区别：
+        - user_char: 内部使用，LLM系统提示，决定Agent如何思考和行动
+        - description: 外部显示，其他用户可见的简介
+        """
+        import csv
+        
+        # 确保文件扩展名是.csv
+        if not file_path.endswith('.csv'):
+            file_path = file_path.replace('.json', '.csv')
+        
+        with open(file_path, 'w', newline='', encoding='utf-8') as f:
+            writer = csv.writer(f)
+            
+            # 写入OASIS要求的表头
+            headers = ['user_id', 'name', 'username', 'user_char', 'description']
+            writer.writerow(headers)
+            
+            # 写入数据行
+            for idx, profile in enumerate(profiles):
+                # user_char: 完整人设（bio + persona），用于LLM系统提示
+                user_char = profile.bio
+                if profile.persona and profile.persona != profile.bio:
+                    user_char = f"{profile.bio} {profile.persona}"
+                # 处理换行符（CSV中用空格替代）
+                user_char = user_char.replace('\n', ' ').replace('\r', ' ')
+                
+                # description: 简短简介，用于外部显示
+                description = profile.bio.replace('\n', ' ').replace('\r', ' ')
+                
+                row = [
+                    idx,                    # user_id: 从0开始的顺序ID
+                    profile.name,           # name: 真实姓名
+                    profile.user_name,      # username: 用户名
+                    user_char,              # user_char: 完整人设（内部LLM使用）
+                    description             # description: 简短简介（外部显示）
+                ]
+                writer.writerow(row)
+        
+        logger.info(f"已保存 {len(profiles)} 个Twitter Profile到 {file_path} (OASIS CSV格式)")
+    
+    def _normalize_gender(self, gender: Optional[str]) -> str:
+        """
+        标准化gender字段为OASIS要求的英文格式
+        
+        OASIS要求: male, female, other
+        """
+        if not gender:
+            return "other"
+        
+        gender_lower = gender.lower().strip()
+        
+        # 中文映射
+        gender_map = {
+            "男": "male",
+            "女": "female",
+            "机构": "other",
+            "其他": "other",
+            # 英文已有
+            "male": "male",
+            "female": "female",
+            "other": "other",
+        }
+        
+        return gender_map.get(gender_lower, "other")
+    
+    def _save_reddit_json(self, profiles: List[OasisAgentProfile], file_path: str):
+        """
+        保存Reddit Profile为JSON格式
+        
+        使用与 to_reddit_format() 一致的格式，确保 OASIS 能正确读取。
+        必须包含 user_id 字段，这是 OASIS agent_graph.get_agent() 匹配的关键！
+        
+        必需字段：
+        - user_id: 用户ID（整数，用于匹配 initial_posts 中的 poster_agent_id）
+        - username: 用户名
+        - name: 显示名称
+        - bio: 简介
+        - persona: 详细人设
+        - age: 年龄（整数）
+        - gender: "male", "female", 或 "other"
+        - mbti: MBTI类型
+        - country: 国家
+        """
+        data = []
+        for idx, profile in enumerate(profiles):
+            # 使用与 to_reddit_format() 一致的格式
+            item = {
+                "user_id": profile.user_id if profile.user_id is not None else idx,  # 关键：必须包含 user_id
+                "username": profile.user_name,
+                "name": profile.name,
+                "bio": profile.bio[:150] if profile.bio else f"{profile.name}",
+                "persona": profile.persona or f"{profile.name} is a participant in social discussions.",
+                "karma": profile.karma if profile.karma else 1000,
+                "created_at": profile.created_at,
+                # OASIS必需字段 - 确保都有默认值
+                "age": profile.age if profile.age else 30,
+                "gender": self._normalize_gender(profile.gender),
+                "mbti": profile.mbti if profile.mbti else "ISTJ",
+                "country": profile.country if profile.country else "中国",
+            }
+            
+            # 可选字段
+            if profile.profession:
+                item["profession"] = profile.profession
+            if profile.interested_topics:
+                item["interested_topics"] = profile.interested_topics
+            
+            data.append(item)
+        
+        with open(file_path, 'w', encoding='utf-8') as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+        
+        logger.info(f"已保存 {len(profiles)} 个Reddit Profile到 {file_path} (JSON格式，包含user_id字段)")
+    
+    # 保留旧方法名作为别名，保持向后兼容
+    def save_profiles_to_json(
+        self,
+        profiles: List[OasisAgentProfile],
+        file_path: str,
+        platform: str = "reddit"
+    ):
+        """[已废弃] 请使用 save_profiles() 方法"""
+        logger.warning("save_profiles_to_json已废弃，请使用save_profiles方法")
+        self.save_profiles(profiles, file_path, platform)
+

app/app/services/ontology_generator.py

@@ -0,0 +1,507 @@
+"""
+本体生成服务
+接口1：分析文本内容，生成适合社会模拟的实体和关系类型定义
+"""
+
+import json
+import logging
+import re
+from typing import Dict, Any, List, Optional
+from ..utils.llm_client import LLMClient
+
+logger = logging.getLogger(__name__)
+
+
+def _to_pascal_case(name: str) -> str:
+    """将任意格式的名称转换为 PascalCase（如 'works_for' -> 'WorksFor', 'person' -> 'Person'）"""
+    # 按非字母数字字符分割
+    parts = re.split(r'[^a-zA-Z0-9]+', name)
+    # 再按 camelCase 边界分割（如 'camelCase' -> ['camel', 'Case']）
+    words = []
+    for part in parts:
+        words.extend(re.sub(r'([a-z])([A-Z])', r'\1_\2', part).split('_'))
+    # 每个词首字母大写，过滤空串
+    result = ''.join(word.capitalize() for word in words if word)
+    return result if result else 'Unknown'
+
+
+# 本体生成的系统提示词
+ONTOLOGY_SYSTEM_PROMPT = """你是一个专业的知识图谱本体设计专家。你的任务是分析给定的文本内容和模拟需求，设计适合**社交媒体上的创业想法验证模拟**的实体类型和关系类型（在保留原「舆论/讨论」能力的同时，优先服务想法验证）。
+
+**重要：你必须输出有效的JSON格式数据，不要输出任何其他内容。**
+
+## 核心任务背景
+
+我们正在构建一个**社交媒体模拟系统**，典型用途是**用多角色 Agent 压力测试用户的创业想法**：投资人（可体现硅谷 VC、YC 风格、难取悦的天使等不同挑剔程度）、同行创始人、目标客户与潜在买家（含果断、犹豫、拒绝）、媒体或意见领袖等会在平台上讨论、质疑或支持该想法。
+- 每个实体都是一个可以在社交媒体上发声、互动、传播信息的"账号"或"主体"
+- 实体之间会相互影响、转发、评论、回应
+- 我们需要模拟围绕「该产品/商业模式」的讨论、投资兴趣与购买意愿等信息路径
+
+因此，**实体必须是现实中真实存在的、可以在社媒上发声和互动的主体**：
+
+**可以是**：
+- 具体的个人（公众人物、当事人、意见领袖、专家学者、普通人）
+- 公司、企业（包括其官方账号）
+- 组织机构（大学、协会、NGO、工会等）
+- 政府部门、监管机构
+- 媒体机构（报纸、电视台、自媒体、网站）
+- 社交媒体平台本身
+- 特定群体代表（如校友会、粉丝团、维权群体等）
+
+**不可以是**：
+- 抽象概念（如"舆论"、"情绪"、"趋势"）
+- 主题/话题（如"学术诚信"、"教育改革"）
+- 观点/态度（如"支持方"、"反对方"）
+
+## 输出格式
+
+请输出JSON格式，包含以下结构：
+
+```json
+{
+    "entity_types": [
+        {
+            "name": "实体类型名称（英文，PascalCase）",
+            "description": "简短描述（英文，不超过100字符）",
+            "attributes": [
+                {
+                    "name": "属性名（英文，snake_case）",
+                    "type": "text",
+                    "description": "属性描述"
+                }
+            ],
+            "examples": ["示例实体1", "示例实体2"]
+        }
+    ],
+    "edge_types": [
+        {
+            "name": "关系类型名称（英文，UPPER_SNAKE_CASE）",
+            "description": "简短描述（英文，不超过100字符）",
+            "source_targets": [
+                {"source": "源实体类型", "target": "目标实体类型"}
+            ],
+            "attributes": []
+        }
+    ],
+    "analysis_summary": "对文本内容的简要分析说明（中文）"
+}
+```
+
+## 设计指南（极其重要！）
+
+### 1. 实体类型设计 - 必须严格遵守
+
+**数量要求：必须正好10个实体类型**
+
+**层次结构要求（必须同时包含具体类型和兜底类型）**：
+
+你的10个实体类型必须包含以下层次：
+
+A. **兜底类型（必须包含，放在列表最后2个）**：
+   - `Person`: 任何自然人个体的兜底类型。当一个人不属于其他更具体的人物类型时，归入此类。
+   - `Organization`: 任何组织机构的兜底类型。当一个组织不属于其他更具体的组织类型时，归入此类。
+
+B. **具体类型（8个，根据文本内容设计）**：
+   - 针对文本中出现的主要角色，设计更具体的类型
+   - 例如：如果文本涉及学术事件，可以有 `Student`, `Professor`, `University`
+   - 例如：如果文本涉及商业事件，可以有 `Company`, `CEO`, `Employee`
+
+**为什么需要兜底类型**：
+- 文本中会出现各种人物，如"中小学教师"、"路人甲"、"某位网友"
+- 如果没有专门的类型匹配，他们应该被归入 `Person`
+- 同理，小型组织、临时团体等应该归入 `Organization`
+
+**具体类型的设计原则**：
+- 从文本中识别出高频出现或关键的角色类型
+- 每个具体类型应该有明确的边界，避免重叠
+- description 必须清晰说明这个类型和兜底类型的区别
+
+### 2. 关系类型设计
+
+- 数量：6-10个
+- 关系应该反映社媒互动中的真实联系
+- 确保关系的 source_targets 涵盖你定义的实体类型
+
+### 3. 属性设计
+
+- 每个实体类型1-3个关键属性
+- **注意**：属性名不能使用 `name`、`uuid`、`group_id`、`created_at`、`summary`（这些是系统保留字）
+- 推荐使用：`full_name`, `title`, `role`, `position`, `location`, `description` 等
+
+## 实体类型参考
+
+**个人类（具体）** — 若文本与「创业/产品」相关，请优先包含以下类型中的若干（名称用 PascalCase，可微调命名）：
+- VentureInvestor: 风险投资人（可偏硅谷风格大型基金）
+- AngelInvestor: 天使/个人投资人（可设定为极难取悦）
+- AcceleratorPartner: 加速器合伙人（可体现 YC 式 fast iteration 提问风格）
+- StartupFounder: 同行创始人
+- TargetCustomer: 目标付费用户或核心采用者
+- SkepticalUser: 犹豫或反对的潜在用户
+- IndustryExpert: 行业专家/KOL（可质疑技术或商业假设）
+- Journalist: 科技/商业记者
+
+其他常见具体类型（若文本需要可替换其中部分）：
+- Student, Professor, Executive, Official, Lawyer, Doctor, Celebrity 等
+
+**个人类（兜底）**：
+- Person: 任何自然人（不属于上述具体类型时使用）
+
+**组织类（具体）**：
+- StartupCompany: 初创公司
+- VentureCapitalFirm: VC 机构
+- University: 高校
+- Company: 公司企业
+- MediaOutlet: 媒体机构
+- NGO: 非政府组织
+（可按文本选用 GovernmentAgency、Hospital、School 等）
+
+**组织类（兜底）**：
+- Organization: 任何组织机构（不属于上述具体类型时使用）
+
+## 关系类型参考
+
+- INVESTS_IN: 投资关系
+- COMPETES_WITH: 竞争
+- WORKS_FOR: 工作于
+- STUDIES_AT: 就读于
+- AFFILIATED_WITH: 隶属于
+- REPRESENTS: 代表
+- REPORTS_ON: 报道
+- COMMENTS_ON: 评论
+- RESPONDS_TO: 回应
+- SUPPORTS: 支持
+- OPPOSES: 反对
+- COLLABORATES_WITH: 合作
+- PURCHASES_FROM / USES_PRODUCT: 可在描述中体现客户与产品关系（命名保持英文 PascalCase / UPPER_SNAKE_CASE）
+"""
+
+
+class OntologyGenerator:
+    """
+    本体生成器
+    分析文本内容，生成实体和关系类型定义
+    """
+    
+    def __init__(self, llm_client: Optional[LLMClient] = None):
+        self.llm_client = llm_client or LLMClient()
+    
+    def generate(
+        self,
+        document_texts: List[str],
+        simulation_requirement: str,
+        additional_context: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        生成本体定义
+        
+        Args:
+            document_texts: 文档文本列表
+            simulation_requirement: 模拟需求描述
+            additional_context: 额外上下文
+            
+        Returns:
+            本体定义（entity_types, edge_types等）
+        """
+        # 构建用户消息
+        user_message = self._build_user_message(
+            document_texts, 
+            simulation_requirement,
+            additional_context
+        )
+        
+        messages = [
+            {"role": "system", "content": ONTOLOGY_SYSTEM_PROMPT},
+            {"role": "user", "content": user_message}
+        ]
+        
+        # 调用LLM
+        result = self.llm_client.chat_json(
+            messages=messages,
+            temperature=0.3,
+            max_tokens=4096
+        )
+        
+        # 验证和后处理
+        result = self._validate_and_process(result)
+        
+        return result
+    
+    # 传给 LLM 的文本最大长度（5万字）
+    MAX_TEXT_LENGTH_FOR_LLM = 50000
+    
+    def _build_user_message(
+        self,
+        document_texts: List[str],
+        simulation_requirement: str,
+        additional_context: Optional[str]
+    ) -> str:
+        """构建用户消息"""
+        
+        # 合并文本
+        combined_text = "\n\n---\n\n".join(document_texts)
+        original_length = len(combined_text)
+        
+        # 如果文本超过5万字，截断（仅影响传给LLM的内容，不影响图谱构建）
+        if len(combined_text) > self.MAX_TEXT_LENGTH_FOR_LLM:
+            combined_text = combined_text[:self.MAX_TEXT_LENGTH_FOR_LLM]
+            combined_text += f"\n\n...(原文共{original_length}字，已截取前{self.MAX_TEXT_LENGTH_FOR_LLM}字用于本体分析)..."
+        
+        message = f"""## 模拟需求
+
+{simulation_requirement}
+
+## 文档内容
+
+{combined_text}
+"""
+        
+        if additional_context:
+            message += f"""
+## 额外说明
+
+{additional_context}
+"""
+        
+        message += """
+请根据以上内容，设计适合「创业想法验证」场景下社交媒体讨论的实���类型和关系类型。
+
+**必须遵守的规则**：
+1. 必须正好输出10个实体类型
+2. 最后2个必须是兜底类型：Person（个人兜底）和 Organization（组织兜底）
+3. 前8个是根据文本内容设计的具体类型（若材料涉及创业/产品，应包含投资人、创始人、客户等可验证角色中的多类）
+4. 所有实体类型必须是现实中可以发声的主体，不能是抽象概念
+5. 属性名不能使用 name、uuid、group_id 等保留字，用 full_name、org_name 等替代
+"""
+        
+        return message
+    
+    def _validate_and_process(self, result: Dict[str, Any]) -> Dict[str, Any]:
+        """验证和后处理结果"""
+        
+        # 确保必要字段存在
+        if "entity_types" not in result:
+            result["entity_types"] = []
+        if "edge_types" not in result:
+            result["edge_types"] = []
+        if "analysis_summary" not in result:
+            result["analysis_summary"] = ""
+        
+        # 验证实体类型
+        # 记录原始名称到 PascalCase 的映射，用于后续修正 edge 的 source_targets 引用
+        entity_name_map = {}
+        for entity in result["entity_types"]:
+            # 强制将 entity name 转为 PascalCase（Zep API 要求）
+            if "name" in entity:
+                original_name = entity["name"]
+                entity["name"] = _to_pascal_case(original_name)
+                if entity["name"] != original_name:
+                    logger.warning(f"Entity type name '{original_name}' auto-converted to '{entity['name']}'")
+                entity_name_map[original_name] = entity["name"]
+            if "attributes" not in entity:
+                entity["attributes"] = []
+            if "examples" not in entity:
+                entity["examples"] = []
+            # 确保description不超过100字符
+            if len(entity.get("description", "")) > 100:
+                entity["description"] = entity["description"][:97] + "..."
+        
+        # 验证关系类型
+        for edge in result["edge_types"]:
+            # 强制将 edge name 转为 SCREAMING_SNAKE_CASE（Zep API 要求）
+            if "name" in edge:
+                original_name = edge["name"]
+                edge["name"] = original_name.upper()
+                if edge["name"] != original_name:
+                    logger.warning(f"Edge type name '{original_name}' auto-converted to '{edge['name']}'")
+            # 修正 source_targets 中的实体名称引用，与转换后的 PascalCase 保持一致
+            for st in edge.get("source_targets", []):
+                if st.get("source") in entity_name_map:
+                    st["source"] = entity_name_map[st["source"]]
+                if st.get("target") in entity_name_map:
+                    st["target"] = entity_name_map[st["target"]]
+            if "source_targets" not in edge:
+                edge["source_targets"] = []
+            if "attributes" not in edge:
+                edge["attributes"] = []
+            if len(edge.get("description", "")) > 100:
+                edge["description"] = edge["description"][:97] + "..."
+        
+        # Zep API 限制：最多 10 个自定义实体类型，最多 10 个自定义边类型
+        MAX_ENTITY_TYPES = 10
+        MAX_EDGE_TYPES = 10
+
+        # 去重：按 name 去重，保留首次出现的
+        seen_names = set()
+        deduped = []
+        for entity in result["entity_types"]:
+            name = entity.get("name", "")
+            if name and name not in seen_names:
+                seen_names.add(name)
+                deduped.append(entity)
+            elif name in seen_names:
+                logger.warning(f"Duplicate entity type '{name}' removed during validation")
+        result["entity_types"] = deduped
+
+        # 兜底类型定义
+        person_fallback = {
+            "name": "Person",
+            "description": "Any individual person not fitting other specific person types.",
+            "attributes": [
+                {"name": "full_name", "type": "text", "description": "Full name of the person"},
+                {"name": "role", "type": "text", "description": "Role or occupation"}
+            ],
+            "examples": ["ordinary citizen", "anonymous netizen"]
+        }
+        
+        organization_fallback = {
+            "name": "Organization",
+            "description": "Any organization not fitting other specific organization types.",
+            "attributes": [
+                {"name": "org_name", "type": "text", "description": "Name of the organization"},
+                {"name": "org_type", "type": "text", "description": "Type of organization"}
+            ],
+            "examples": ["small business", "community group"]
+        }
+        
+        # 检查是否已有兜底类型
+        entity_names = {e["name"] for e in result["entity_types"]}
+        has_person = "Person" in entity_names
+        has_organization = "Organization" in entity_names
+        
+        # 需要添加的兜底类型
+        fallbacks_to_add = []
+        if not has_person:
+            fallbacks_to_add.append(person_fallback)
+        if not has_organization:
+            fallbacks_to_add.append(organization_fallback)
+        
+        if fallbacks_to_add:
+            current_count = len(result["entity_types"])
+            needed_slots = len(fallbacks_to_add)
+            
+            # 如果添加后会超过 10 个，需要移除一些现有类型
+            if current_count + needed_slots > MAX_ENTITY_TYPES:
+                # 计算需要移除多少个
+                to_remove = current_count + needed_slots - MAX_ENTITY_TYPES
+                # 从末尾移除（保留前面更重要的具体类型）
+                result["entity_types"] = result["entity_types"][:-to_remove]
+            
+            # 添加兜底类型
+            result["entity_types"].extend(fallbacks_to_add)
+        
+        # 最终确保不超过限制（防御性编程）
+        if len(result["entity_types"]) > MAX_ENTITY_TYPES:
+            result["entity_types"] = result["entity_types"][:MAX_ENTITY_TYPES]
+        
+        if len(result["edge_types"]) > MAX_EDGE_TYPES:
+            result["edge_types"] = result["edge_types"][:MAX_EDGE_TYPES]
+        
+        return result
+    
+    def generate_python_code(self, ontology: Dict[str, Any]) -> str:
+        """
+        将本体定义转换为Python代码（类似ontology.py）
+        
+        Args:
+            ontology: 本体定义
+            
+        Returns:
+            Python代码字符串
+        """
+        code_lines = [
+            '"""',
+            '自定义实体类型定义',
+            '由MiroFish自动生成，用于创业想法验证与社交媒体模拟',
+            '"""',
+            '',
+            'from pydantic import Field',
+            'from zep_cloud.external_clients.ontology import EntityModel, EntityText, EdgeModel',
+            '',
+            '',
+            '# ============== 实体类型定义 ==============',
+            '',
+        ]
+        
+        # 生成实体类型
+        for entity in ontology.get("entity_types", []):
+            name = entity["name"]
+            desc = entity.get("description", f"A {name} entity.")
+            
+            code_lines.append(f'class {name}(EntityModel):')
+            code_lines.append(f'    """{desc}"""')
+            
+            attrs = entity.get("attributes", [])
+            if attrs:
+                for attr in attrs:
+                    attr_name = attr["name"]
+                    attr_desc = attr.get("description", attr_name)
+                    code_lines.append(f'    {attr_name}: EntityText = Field(')
+                    code_lines.append(f'        description="{attr_desc}",')
+                    code_lines.append(f'        default=None')
+                    code_lines.append(f'    )')
+            else:
+                code_lines.append('    pass')
+            
+            code_lines.append('')
+            code_lines.append('')
+        
+        code_lines.append('# ============== 关系类型定义 ==============')
+        code_lines.append('')
+        
+        # 生成关系类型
+        for edge in ontology.get("edge_types", []):
+            name = edge["name"]
+            # 转换为PascalCase类名
+            class_name = ''.join(word.capitalize() for word in name.split('_'))
+            desc = edge.get("description", f"A {name} relationship.")
+            
+            code_lines.append(f'class {class_name}(EdgeModel):')
+            code_lines.append(f'    """{desc}"""')
+            
+            attrs = edge.get("attributes", [])
+            if attrs:
+                for attr in attrs:
+                    attr_name = attr["name"]
+                    attr_desc = attr.get("description", attr_name)
+                    code_lines.append(f'    {attr_name}: EntityText = Field(')
+                    code_lines.append(f'        description="{attr_desc}",')
+                    code_lines.append(f'        default=None')
+                    code_lines.append(f'    )')
+            else:
+                code_lines.append('    pass')
+            
+            code_lines.append('')
+            code_lines.append('')
+        
+        # 生成类型字典
+        code_lines.append('# ============== 类型配置 ==============')
+        code_lines.append('')
+        code_lines.append('ENTITY_TYPES = {')
+        for entity in ontology.get("entity_types", []):
+            name = entity["name"]
+            code_lines.append(f'    "{name}": {name},')
+        code_lines.append('}')
+        code_lines.append('')
+        code_lines.append('EDGE_TYPES = {')
+        for edge in ontology.get("edge_types", []):
+            name = edge["name"]
+            class_name = ''.join(word.capitalize() for word in name.split('_'))
+            code_lines.append(f'    "{name}": {class_name},')
+        code_lines.append('}')
+        code_lines.append('')
+        
+        # 生成边的source_targets映射
+        code_lines.append('EDGE_SOURCE_TARGETS = {')
+        for edge in ontology.get("edge_types", []):
+            name = edge["name"]
+            source_targets = edge.get("source_targets", [])
+            if source_targets:
+                st_list = ', '.join([
+                    f'{{"source": "{st.get("source", "Entity")}", "target": "{st.get("target", "Entity")}"}}'
+                    for st in source_targets
+                ])
+                code_lines.append(f'    "{name}": [{st_list}],')
+        code_lines.append('}')
+        
+        return '\n'.join(code_lines)
+

app/app/services/pipeline_orchestrator.py

@@ -0,0 +1,368 @@
+"""
+End-to-end pipeline: ontology → graph → simulation create → prepare → run → report.
+Executes inside a worker thread (see api/pipeline.py).
+"""
+
+from __future__ import annotations
+
+import time
+import traceback
+import uuid
+from typing import Any, Dict, Optional
+
+from ..config import Config
+from ..models.project import ProjectManager, ProjectStatus
+from ..models.task import TaskManager, TaskStatus
+from ..services.graph_builder import GraphBuilderService
+from ..services.ontology_generator import OntologyGenerator
+from ..services.report_agent import ReportAgent, ReportManager, ReportStatus
+from ..services.simulation_manager import SimulationManager, SimulationStatus
+from ..services.simulation_runner import SimulationRunner, RunnerStatus
+from ..services.text_processor import TextProcessor
+from ..utils.api_key_runtime import reset_pipeline_api_keys
+from ..utils.logger import get_logger
+
+logger = get_logger("mirofish.pipeline")
+
+
+def _update(
+    tm: TaskManager,
+    task_id: str,
+    progress: int,
+    message: str,
+    *,
+    stage: str,
+    extra: Optional[Dict[str, Any]] = None,
+) -> None:
+    detail: Dict[str, Any] = {"stage": stage}
+    if extra:
+        detail.update(extra)
+    tm.update_task(
+        task_id,
+        status=TaskStatus.PROCESSING,
+        progress=max(0, min(100, progress)),
+        message=message,
+        progress_detail=detail,
+    )
+
+
+def _run_graph_build_sync(
+    project_id: str,
+    tm: TaskManager,
+    pipeline_task_id: str,
+) -> str:
+    project = ProjectManager.get_project(project_id)
+    if not project or not project.ontology:
+        raise RuntimeError("Project missing ontology")
+
+    text = ProjectManager.get_extracted_text(project_id)
+    if not text:
+        raise RuntimeError("No extracted text for project")
+
+    if not Config.get_zep_api_keys():
+        raise RuntimeError("ZEP_API_KEY is not configured")
+
+    graph_name = project.name or "MiroFish Graph"
+    chunk_size = project.chunk_size or Config.DEFAULT_CHUNK_SIZE
+    chunk_overlap = project.chunk_overlap or Config.DEFAULT_CHUNK_OVERLAP
+
+    project.status = ProjectStatus.GRAPH_BUILDING
+    ProjectManager.save_project(project)
+
+    builder = GraphBuilderService()
+
+    _update(tm, pipeline_task_id, 16, "Chunking document…", stage="graph")
+    chunks = TextProcessor.split_text(text, chunk_size=chunk_size, overlap=chunk_overlap)
+    total_chunks = len(chunks)
+
+    _update(
+        tm,
+        pipeline_task_id,
+        18,
+        f"Creating Zep graph ({total_chunks} chunks)…",
+        stage="graph",
+    )
+    graph_id = builder.create_graph(name=graph_name)
+    project.graph_id = graph_id
+    ProjectManager.save_project(project)
+
+    _update(tm, pipeline_task_id, 20, "Applying ontology to graph…", stage="graph", extra={"graph_id": graph_id})
+    builder.set_ontology(graph_id, project.ontology)
+
+    def add_progress(msg: str, ratio: float) -> None:
+        p = 20 + int(ratio * 22)  # 20–42
+        _update(tm, pipeline_task_id, p, msg, stage="graph", extra={"graph_id": graph_id})
+
+    episode_uuids = builder.add_text_batches(
+        graph_id, chunks, batch_size=3, progress_callback=add_progress
+    )
+
+    _update(tm, pipeline_task_id, 43, "Waiting for Zep to process episodes…", stage="graph")
+
+    def wait_progress(msg: str, ratio: float) -> None:
+        p = 43 + int(ratio * 12)  # 43–55
+        _update(tm, pipeline_task_id, p, msg, stage="graph", extra={"graph_id": graph_id})
+
+    builder._wait_for_episodes(episode_uuids, wait_progress, timeout=900)
+
+    project.status = ProjectStatus.GRAPH_COMPLETED
+    ProjectManager.save_project(project)
+
+    _update(tm, pipeline_task_id, 55, "Graph build complete.", stage="graph", extra={"graph_id": graph_id})
+    return graph_id
+
+
+def run_full_pipeline(
+    *,
+    simulation_requirement: str,
+    document_text: str,
+    source_filename: str,
+    task_id: str,
+    task_manager: TaskManager,
+    simulation_run_id: Optional[str] = None,
+    user_id: Optional[str] = None,
+) -> None:
+    """
+    Full automated run. Updates task_manager task_id; on success completes with result dict.
+    Optional simulation_run_id + user_id sync status and report to Supabase.
+    """
+    tm = task_manager
+    project_id: Optional[str] = None
+    simulation_id: Optional[str] = None
+    report_id = f"report_{uuid.uuid4().hex[:12]}"
+
+    max_rounds: Optional[int] = None
+    if Config.PIPELINE_MAX_ROUNDS:
+        try:
+            max_rounds = int(Config.PIPELINE_MAX_ROUNDS)
+        except ValueError:
+            max_rounds = None
+
+    parallel_profiles = Config.PIPELINE_PARALLEL_PROFILES
+
+    try:
+        reset_pipeline_api_keys()
+        _update(tm, task_id, 2, "Creating project…", stage="ontology")
+
+        project = ProjectManager.create_project(name=f"Pipeline {source_filename[:40]}")
+        project_id = project.project_id
+        project.simulation_requirement = simulation_requirement
+        project.files.append({"filename": source_filename, "size": len(document_text.encode("utf-8"))})
+        ProjectManager.save_extracted_text(project_id, document_text)
+        project.total_text_length = len(document_text)
+        ProjectManager.save_project(project)
+
+        _update(
+            tm,
+            task_id,
+            5,
+            "Generating ontology (LLM)…",
+            stage="ontology",
+            extra={"project_id": project_id},
+        )
+        generator = OntologyGenerator()
+        ontology = generator.generate(
+            document_texts=[document_text],
+            simulation_requirement=simulation_requirement,
+            additional_context=None,
+        )
+        project.ontology = {
+            "entity_types": ontology.get("entity_types", []),
+            "edge_types": ontology.get("edge_types", []),
+        }
+        project.analysis_summary = ontology.get("analysis_summary", "")
+        project.status = ProjectStatus.ONTOLOGY_GENERATED
+        ProjectManager.save_project(project)
+
+        graph_id = _run_graph_build_sync(project_id, tm, task_id)
+
+        _update(
+            tm,
+            task_id,
+            56,
+            "Creating simulation instance…",
+            stage="simulation_create",
+            extra={"project_id": project_id, "graph_id": graph_id},
+        )
+        manager = SimulationManager()
+        state = manager.create_simulation(
+            project_id=project_id,
+            graph_id=graph_id,
+            enable_twitter=True,
+            enable_reddit=True,
+        )
+        simulation_id = state.simulation_id
+
+        document_text_full = ProjectManager.get_extracted_text(project_id) or document_text
+
+        def prepare_progress(stage: str, prog: int, message: str, **kwargs: Any) -> None:
+            weights = {
+                "reading": (56, 60),
+                "generating_profiles": (60, 68),
+                "generating_config": (68, 71),
+                "copying_scripts": (71, 72),
+            }
+            lo, hi = weights.get(stage, (56, 72))
+            pct = int(lo + (hi - lo) * (prog / 100.0))
+            _update(
+                tm,
+                task_id,
+                pct,
+                message,
+                stage="prepare",
+                extra={"project_id": project_id, "simulation_id": simulation_id, "graph_id": graph_id},
+            )
+
+        _update(
+            tm,
+            task_id,
+            57,
+            "Preparing agents and simulation config (may take a long time)…",
+            stage="prepare",
+            extra={"project_id": project_id, "simulation_id": simulation_id},
+        )
+        prepared = manager.prepare_simulation(
+            simulation_id=simulation_id,
+            simulation_requirement=simulation_requirement,
+            document_text=document_text_full,
+            defined_entity_types=None,
+            use_llm_for_profiles=True,
+            progress_callback=prepare_progress,
+            parallel_profile_count=parallel_profiles,
+        )
+        if prepared.status == SimulationStatus.FAILED:
+            raise RuntimeError(prepared.error or "Simulation prepare failed (no entities or setup error)")
+
+        _update(
+            tm,
+            task_id,
+            73,
+            "Starting OASIS simulation (parallel platforms)…",
+            stage="run",
+            extra={"project_id": project_id, "simulation_id": simulation_id},
+        )
+        SimulationRunner.start_simulation(
+            simulation_id=simulation_id,
+            platform="parallel",
+            max_rounds=max_rounds,
+            enable_graph_memory_update=False,
+            graph_id=None,
+        )
+
+        last_prog = 73
+        # Wait until the simulation finishes — no wall-clock deadline (can run as long as OASIS needs).
+        while True:
+            rs = SimulationRunner.get_run_state(simulation_id)
+            if not rs:
+                time.sleep(3)
+                continue
+            status = rs.runner_status
+            if status == RunnerStatus.COMPLETED:
+                break
+            if status in (RunnerStatus.FAILED, RunnerStatus.STOPPED):
+                raise RuntimeError(rs.error or f"Simulation ended with status {status.value}")
+            last_prog = min(88, last_prog + 1)
+            _update(
+                tm,
+                task_id,
+                last_prog,
+                f"Simulation running: round ~{rs.twitter_current_round or rs.reddit_current_round or rs.current_round}…",
+                stage="run",
+                extra={"project_id": project_id, "simulation_id": simulation_id},
+            )
+            time.sleep(5)
+
+        _update(
+            tm,
+            task_id,
+            90,
+            "Generating English validation report (LLM)…",
+            stage="report",
+            extra={
+                "project_id": project_id,
+                "simulation_id": simulation_id,
+                "report_id": report_id,
+            },
+        )
+
+        agent = ReportAgent(
+            graph_id=graph_id,
+            simulation_id=simulation_id,
+            simulation_requirement=simulation_requirement,
+        )
+
+        def report_progress(stage: str, progress: int, message: str) -> None:
+            p = 90 + int(progress * 0.09)  # 90–99
+            _update(
+                tm,
+                task_id,
+                min(99, p),
+                f"[{stage}] {message}",
+                stage="report",
+                extra={
+                    "project_id": project_id,
+                    "simulation_id": simulation_id,
+                    "report_id": report_id,
+                },
+            )
+
+        report = agent.generate_report(
+            progress_callback=report_progress,
+            report_id=report_id,
+        )
+        ReportManager.save_report(report)
+
+        if report.status != ReportStatus.COMPLETED:
+            raise RuntimeError(report.error or "Report generation failed")
+
+        if simulation_run_id and user_id:
+            from ..services.supabase_jobs import mark_run_completed
+
+            try:
+                mark_run_completed(
+                    simulation_run_id=simulation_run_id,
+                    user_id=user_id,
+                    report_id=report.report_id,
+                    markdown_content=report.markdown_content or "",
+                    simulation_id=simulation_id,
+                    project_id=project_id,
+                )
+            except Exception:
+                logger.exception("Supabase mark_run_completed failed (report saved on disk)")
+
+        tm.update_task(
+            task_id,
+            status=TaskStatus.COMPLETED,
+            progress=100,
+            message="Pipeline complete — report ready.",
+            result={
+                "project_id": project_id,
+                "graph_id": graph_id,
+                "simulation_id": simulation_id,
+                "report_id": report.report_id,
+            },
+            progress_detail={
+                "stage": "completed",
+                "project_id": project_id,
+                "graph_id": graph_id,
+                "simulation_id": simulation_id,
+                "report_id": report.report_id,
+            },
+        )
+        logger.info(
+            "Pipeline finished: project=%s sim=%s report=%s",
+            project_id,
+            simulation_id,
+            report.report_id,
+        )
+
+    except Exception as e:
+        logger.error("Pipeline failed: %s", traceback.format_exc())
+        if simulation_run_id:
+            from ..services.supabase_jobs import mark_run_failed
+
+            try:
+                mark_run_failed(simulation_run_id=simulation_run_id, error_message=str(e))
+            except Exception:
+                logger.exception("Supabase mark_run_failed failed")
+        tm.fail_task(task_id, str(e))