添加可选的代理引擎 / 无 API 密钥模式，同时保留旧有的 API 密钥工作流。

.env.example

@@ -1,16 +1,37 @@
-# LLM API配置（支持 OpenAI SDK 格式的任意 LLM API）
-# 推荐使用阿里百炼平台qwen-plus模型：https://bailian.console.aliyun.com/
-# 注意消耗较大，可先进行小于40轮的模拟尝试
-LLM_API_KEY=your_api_key_here
+# ===== MiroFish Agent Engine 默认配置 =====
+MIROFISH_MODE=agent
+MIROFISH_LLM_PROVIDER=agent_queue
+MIROFISH_GRAPH_PROVIDER=graphiti
+MIROFISH_RUNS_DIR=./runs
+
+# ===== Graphiti / Neo4j 图谱配置 =====
+NEO4J_URI=bolt://localhost:7687
+NEO4J_USER=neo4j
+NEO4J_PASSWORD=password
+NEO4J_DATABASE=neo4j
+
+# ===== Embedding 配置（可选）=====
+# GraphitiCompatibilityStore 的 no-LLM 主路径不需要 embedding。
+# fulltext 不需要 Ollama；仅 semantic/hybrid + ollama 时 doctor 会强制检查 Ollama。
+MIROFISH_GRAPH_SEARCH_MODE=fulltext
+MIROFISH_EMBEDDING_PROVIDER=none
+OLLAMA_BASE_URL=http://localhost:11434
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+
+# ===== Legacy OpenAI-compatible LLM provider（可选）=====
+# 仅当 MIROFISH_LLM_PROVIDER=openai_compatible 时需要。
+LLM_API_KEY=
 LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
 LLM_MODEL_NAME=qwen-plus
 
-# ===== ZEP记忆图谱配置 =====
-# 每月免费额度即可支撑简单使用：https://app.getzep.com/
-ZEP_API_KEY=your_zep_api_key_here
+# ===== Legacy Zep Cloud graph provider（可选）=====
+# 仅当 MIROFISH_GRAPH_PROVIDER=zep 时需要。
+ZEP_API_KEY=
+
+# ===== 加速 LLM 配置（legacy 可选）=====
+LLM_BOOST_API_KEY=
+LLM_BOOST_BASE_URL=
+LLM_BOOST_MODEL_NAME=
 
-# ===== 加速 LLM 配置（可选）=====
-# 注意如果不使用加速配置，env文件中就不要出现下面的配置项
-LLM_BOOST_API_KEY=your_api_key_here
-LLM_BOOST_BASE_URL=your_base_url_here
-LLM_BOOST_MODEL_NAME=your_model_name_here
+# ===== Legacy UI / simulation behavior =====
+MIROFISH_PRESERVE_SIMULATIONS_ON_RELOAD=true

AGENT_KIT.md

@@ -0,0 +1,107 @@
+# MiroFish Agent Kit
+
+MiroFish now includes a full agent engine for desktop tools such as Codex, Claude Code, Cursor, and opencode.
+
+Default agent mode:
+
+```bash
+export MIROFISH_MODE=agent
+export MIROFISH_LLM_PROVIDER=agent_queue
+export MIROFISH_GRAPH_PROVIDER=graphiti
+export MIROFISH_RUNS_DIR=./runs
+```
+
+Agent mode does not require `LLM_API_KEY`, `OPENAI_API_KEY`, or `ZEP_API_KEY`. Model work is written to `runs/<run_id>/requests/*.json`; a desktop agent writes matching response JSON into `runs/<run_id>/responses/*.json`; MiroFish validates the response and resumes the run.
+
+Local graph service setup:
+
+```bash
+cd /Users/leaf/Documents/future/MiroFish
+bash scripts/setup_agent_deps.sh --neo4j desktop
+```
+
+Agent dependencies are installed through the backend `agent` optional extra. Legacy OpenAI-compatible and Zep Cloud SDKs are not part of the default agent path; install them only when explicitly using `MIROFISH_LLM_PROVIDER=openai_compatible` or `MIROFISH_GRAPH_PROVIDER=zep`:
+
+```bash
+cd /Users/leaf/Documents/future/MiroFish/backend
+uv sync --extra legacy
+```
+
+Neo4j Desktop, Homebrew/native Neo4j, and existing Neo4j instances are supported. Docker Compose is optional only. `mirofish-agent doctor --json` does not fail because Docker is missing; it fails when required Graphiti/Neo4j dependencies, Neo4j connectivity, or Neo4j `5.26+` are unavailable. Ollama checks are required only when `MIROFISH_GRAPH_SEARCH_MODE=semantic` or `hybrid` and `MIROFISH_EMBEDDING_PROVIDER=ollama`; `fulltext` search with `MIROFISH_EMBEDDING_PROVIDER=none` does not require Ollama.
+
+Minimal demo:
+
+```bash
+cd /Users/leaf/Documents/future/MiroFish/backend
+uv run mirofish-agent init --seed /path/to/seed.md --requirement "预测未来10年全球芯片能力格局变化" --output ../runs/chip-2036
+uv run mirofish-agent run --run ../runs/chip-2036 --json
+uv run mirofish-agent requests show --run ../runs/chip-2036 --request-id req_000001 --json
+uv run mirofish-agent responses validate --run ../runs/chip-2036 --response ../runs/chip-2036/responses/req_000001.json --json
+uv run mirofish-agent resume --run ../runs/chip-2036 --json
+```
+
+Follow-up questions also use the same provider boundary and queue:
+
+```bash
+uv run mirofish-agent followup ask --run ../runs/chip-2036 --question "先进AI芯片出口限制有什么影响?" --json
+uv run mirofish-agent followup show --run ../runs/chip-2036 --request-id req_000007 --json
+```
+
+Supported agent queue task types:
+
+```text
+extract_triples
+generate_ontology
+generate_oasis_profiles
+generate_simulation_config
+simulate_agent_action
+summarize_round
+update_memory
+generate_report
+answer_followup_question
+answer_agent_question
+answer_agent_questionnaire
+summarize_questionnaire
+ask_report_question
+validate_json_output
+repair_invalid_json
+```
+
+Web Console and interaction commands:
+
+```bash
+# Generate the interactive Web Console
+uv run mirofish-agent web generate --run ../runs/chip-2036 --json
+
+# List agents and ask questions
+uv run mirofish-agent agents list --run ../runs/chip-2036 --json
+uv run mirofish-agent agents ask --run ../runs/chip-2036 --agent-id agent_1 --question "What is the biggest risk?" --json
+uv run mirofish-agent agents answer --run ../runs/chip-2036 --request-id req_XXXX --json
+
+# Send questionnaires
+uv run mirofish-agent questionnaire send --run ../runs/chip-2036 --questions questions.json --json
+uv run mirofish-agent questionnaire show --run ../runs/chip-2036 --questionnaire-id q_XXXX --json
+
+# Ask questions about the report
+uv run mirofish-agent report-question ask --run ../runs/chip-2036 --question "Summarize key risks" --json
+uv run mirofish-agent report-question answer --run ../runs/chip-2036 --request-id req_XXXX --json
+```
+
+Full smoke:
+
+```bash
+cd /Users/leaf/Documents/future/MiroFish
+bash scripts/smoke_agent_queue_full.sh
+bash scripts/smoke_mcp_full.sh
+python scripts/check_provider_boundaries.py
+```
+
+Tool-specific guides:
+
+- [Codex](./docs/agent-usage/codex.md)
+- [Claude Code](./docs/agent-usage/claude-code.md)
+- [Cursor](./docs/agent-usage/cursor.md)
+- [opencode](./docs/agent-usage/opencode.md)
+- [MCP](./docs/agent-usage/mcp.md)
+
+The Flask/Vue UI is preserved as the legacy interactive interface. Legacy API calls that hit `agent_queue` return a structured HTTP 202 `need_agent_response` payload instead of a 500, but full checkpointed agent-mode orchestration remains CLI/MCP-first.