[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74288":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":33,"readmeContent":34,"aiSummary":35,"trendingCount":16,"starSnapshotCount":16,"syncStatus":36,"lastSyncTime":37,"discoverSource":38},74288,"MiroShark","aaronjmars\u002FMiroShark","aaronjmars","Simulate anything, for $1 & less than 10 min - Universal Swarm Intelligence Engine","https:\u002F\u002Fx.com\u002Fmiroshark_",null,"Python",1245,263,5,1,0,8,26,111,24,20.26,"GNU Affero General Public License v3.0",false,"main",true,[27,28,29,30,31,32],"ai-simulation","financial-forecasting","future-prediction","mirofish","swarm","swarm-intelligence","2026-06-12 02:03:25","\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fdocs\u002Fimages\u002Fmiroshark.jpg\" alt=\"MiroShark\" width=\"120\" \u002F>\n\u003C\u002Fp>\n\n\u003Ch1 align=\"center\">MiroShark\u003C\u002Fh1>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Faaronjmars\u002FMiroShark\u002Fstargazers\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Faaronjmars\u002FMiroShark?style=flat-square&logo=github\" alt=\"GitHub stars\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Faaronjmars\u002FMiroShark\u002Fnetwork\u002Fmembers\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fforks\u002Faaronjmars\u002FMiroShark?style=flat-square&logo=github\" alt=\"GitHub forks\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fx.com\u002Fmiroshark_\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FFollow-%40miroshark__-black?style=flat-square&logo=x&labelColor=000000\" alt=\"Follow on X\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fbankr.bot\u002Fdiscover\u002F0xd7bc6a05a56655fb2052f742b012d1dfd66e1ba3\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMiroShark%20on-Bankr-orange?style=flat-square&labelColor=1a1a2e\" alt=\"MiroShark on Bankr\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"#english\">English\u003C\u002Fa> · \u003Ca href=\"#中文\">中文\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fdocs\u002Fimages\u002Fmiroshark.gif\" alt=\"MiroShark Demo\" \u002F>\n\u003C\u002Fp>\n\n---\n\n\u003Ca id=\"english\">\u003C\u002Fa>\n\n## English\n\n> **Simulate anything, for $1 & less than 10 min — Universal Swarm Intelligence Engine**\n> Drop in anything — a press release, a news headline, a policy draft, a question you can't answer, a historical what-if — and MiroShark spawns hundreds of agents that react to it hour by hour. Posting, arguing, trading, changing their minds.\n\n### What it does\n\n- You bring a scenario. MiroShark builds the world around it.\n- Hundreds of grounded agents. Twitter, Reddit, and a prediction market. Hour by hour.\n- Chat with any of them. Drop breaking news mid-run. Fork the timeline.\n- Get a report on what happened, citing actual posts and trades.\n\n### Quick start\n\nThe recommended path: **one [OpenRouter](https:\u002F\u002Fopenrouter.ai\u002F) key + the `.\u002Fmiroshark` launcher.** First simulation in ~10 min, ~$1.\n\n**Prereqs** — Python 3.11+, Node 18+, Neo4j, and an [OpenRouter key](https:\u002F\u002Fopenrouter.ai\u002F).\n\nInstall Neo4j — the launcher starts it for you:\n\n- **macOS** — `brew install neo4j`\n- **Linux** — `sudo apt install neo4j` *(or your distro's equivalent)*\n- **Windows** — install [Neo4j Desktop](https:\u002F\u002Fneo4j.com\u002Fdownload\u002F) *(native, GUI — start the DB there, then run the launcher from WSL2 or Git Bash)*, or run the whole stack inside [WSL2](https:\u002F\u002Flearn.microsoft.com\u002Fwindows\u002Fwsl\u002Finstall) and follow the Linux steps\n- **Zero-install** — create a free [Neo4j Aura](https:\u002F\u002Fneo4j.com\u002Fcloud\u002Faura-free\u002F) cloud instance and point `NEO4J_URI` \u002F `NEO4J_PASSWORD` at it in `.env`\n\nThen:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Faaronjmars\u002FMiroShark.git && cd MiroShark\ncp .env.example .env\n# Paste your OpenRouter key into the LLM_API_KEY \u002F SMART_API_KEY \u002F\n# NER_API_KEY \u002F OPENAI_API_KEY \u002F EMBEDDING_API_KEY slots (same key,\n# 5 places). Default lineup is Mimo V2 Flash + Gemini 3 Flash.\n.\u002Fmiroshark\n```\n\nThe launcher checks dependencies, starts Neo4j, installs frontend + backend, and serves `:3000` + `:5001`. Ctrl+C stops everything. Open `http:\u002F\u002Flocalhost:3000` and drop in a document.\n\n**Other paths** — [one-click Railway \u002F Render deploy](docs\u002FINSTALL.md#one-click-cloud), [Docker + Ollama](docs\u002FINSTALL.md#option-b-docker--local-ollama), [manual Ollama](docs\u002FINSTALL.md#option-c-manual--local-ollama), [Claude Code CLI](docs\u002FINSTALL.md#option-d-claude-code-no-api-key) — all in **[docs\u002FINSTALL.md](docs\u002FINSTALL.md)**.\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fdocs\u002Fimages\u002Fmiroshark-overview.jpg\" alt=\"MiroShark Overview\" \u002F>\n\u003C\u002Fp>\n\n### Interface language\n\nAfter launching, click the **中 \u002F EN** toggle in the top-right of the navbar to switch between English and Chinese. Your choice is persisted in the browser, and the public gallery card titles + descriptions follow the active locale.\n\n### Features\n\n| Feature | What it does |\n|---|---|\n| **Smart Setup** | Drop in a doc → three auto-generated Bull \u002F Bear \u002F Neutral scenarios in ~2s |\n| **What's Trending** | Pick a live news item from RSS feeds; pre-fills the scenario in one click |\n| **Just Ask** | Type a question with no document — MiroShark researches and writes the seed briefing |\n| **Shareable Scenario Links** | Drop a `?scenario=...&url=...` URL into a tweet or blog post — readers land on the New Sim form already pre-filled. `?template=\u003Cslug>` auto-launches one of the preset templates. The un-run-scenario counterpart to \"Fork this scenario\" on `\u002Fwatch` and `\u002Fshare` |\n| **Counterfactual Branching** | Fork a running simulation with an injected event (\"what if the CEO resigns in round 24?\") |\n| **Director Mode** | Inject breaking news into the *current* timeline without forking |\n| **Preset Templates** | 6 benchmarked scenarios: crypto launch, corporate crisis, political debate, product announcement, campus controversy, historical what-if |\n| **Live Oracle Data** | Opt-in grounded seeds from the [FeedOracle](https:\u002F\u002Fmcp.feedoracle.io\u002Fmcp) MCP (484 tools) |\n| **Per-Agent MCP Tools** | Personas can invoke real MCP tools (web search, APIs) during simulation |\n| **Custom Wonderwall Endpoint** | Point the simulation loop at any OpenAI-compatible endpoint (self-hosted vLLM, Modal, fine-tunes…) without affecting Default\u002FSmart\u002FNER. Set `WONDERWALL_BASE_URL` + `WONDERWALL_API_KEY` |\n| **Embed & Publish** | Public\u002Fprivate toggle + embed URLs for sharing finished runs |\n| **Social Share Card** | 1200×630 PNG that auto-unfurls scenario, status, quality, and belief split on Twitter\u002FX, Discord, Slack, LinkedIn |\n| **Animated Belief Replay** | 1200×630 GIF — one frame per round, belief bars sliding to each round's distribution. Discord and Slack auto-play GIFs from the direct URL |\n| **Transcript Export** | Per-round agent posts + stance labels as Markdown (YAML front matter for Notion \u002F Obsidian \u002F Substack) or structured JSON (for SDKs and LLM-as-judge pipelines) |\n| **Trajectory Export** | One row per round as RFC 4180 CSV or JSONL — `pandas.read_csv(\"…\u002Ftrajectory.csv\")` lands ready for Pandas \u002F Excel \u002F Tableau \u002F R \u002F Observable. Same ±0.2 stance threshold as every other surface |\n| **Trajectory Chart SVG** | `GET \u002Fapi\u002Fsimulation\u002F\u003Cid>\u002Fchart.svg` — scalable-vector belief chart (bullish \u002F neutral \u002F bearish polylines, 800×400 viewBox, grid, legend, scenario title) for `\u003Cimg>` embeds in Notion \u002F Substack \u002F Ghost \u002F GitHub READMEs \u002F LaTeX. Same colour scheme as the share card; pure stdlib `xml.etree.ElementTree`, zero new deps |\n| **Tweet Thread Export** | `GET \u002Fapi\u002Fsimulation\u002F\u003Cid>\u002Fthread.txt` — auto-formatted X \u002F Twitter thread, intro tweet + one tweet per belief inflection point + close tweet (with watch + share URLs). Each tweet ≤280 chars; copy individual tweets or the whole thread. Pairs with the share card \u002F replay GIF \u002F transcript \u002F trajectory \u002F watch page as the sixth share format |\n| **Live Watch Page** | `\u002Fwatch\u002F\u003Csim_id>` — minimal full-viewport broadcast page with a vanilla-JS poller that refreshes the belief bar, round counter, and progress bar every 15 s while the simulation runs. Auto-unfurls as a 1200×630 image card when tweeted; the \"tweet a sim mid-run\" format alongside the finished-result share card |\n| **Public Gallery** | `\u002Fexplore` browses every published simulation as a card grid — preview the share card, consensus split, and quality health; click to open or one-click fork |\n| **Gallery Search & Filter** | Keyword search + bullish\u002Fneutral\u002Fbearish + excellent\u002Fgood\u002Ffair\u002Fpoor + sort by date\u002Frounds\u002Fagents\u002Ftrending on `\u002Fexplore` and `\u002Fverified`. `trending` ranks by cumulative share-surface serves so the most-distributed sims float to the top. URL-encoded so `?q=aave&consensus=bearish` is bookmarkable. Same ±0.2 stance threshold as every other surface |\n| **Verified Predictions** | Annotate any public sim with the real-world outcome (called it \u002F partial \u002F called wrong + URL). `\u002Fverified` is the dedicated hall of calls that landed |\n| **RSS \u002F Atom Feeds** | `\u002Fapi\u002Ffeed.atom` + `\u002Fapi\u002Ffeed.rss` — every newly published simulation lands in Feedly \u002F Readwise \u002F Inoreader \u002F NetNewsWire \u002F Obsidian RSS without anyone curating it. `?verified=1` for the verified-only stream |\n| **Search Engine Sitemap** | Auto-generated `\u002Fsitemap.xml` (sitemaps.org 0.9) lists every public sim's `\u002Fshare\u002F\u003Cid>` + `\u002Fwatch\u002F\u003Cid>` URLs; companion `\u002Frobots.txt` advertises it via the standard `Sitemap:` directive. Submit once to Google Search Console — every newly published sim becomes searchable. Pure stdlib `xml.etree.ElementTree`, opt-out via `ENABLE_SITEMAP=false` |\n| **Article Generation** | Substack-style write-up of what happened, grounded in actual posts and trades |\n| **Interaction Network** | Force-directed agent-to-agent graph with echo-chamber metrics |\n| **Demographics** | Archetype clustering (analyst \u002F influencer \u002F retail \u002F observer…) |\n| **Quality Diagnostics** | Health score per run — engagement, coherence, diversity, variance |\n| **History Database** | Search, clone, export, or delete any past simulation |\n| **Trace Interview** | See the full reasoning chain behind an agent's reply, not just the reply |\n| **Push Notifications** | Web-push alerts when long-running graph \u002F sim \u002F report jobs finish |\n| **Completion Webhook** | POST a JSON summary the moment a sim finishes — wires Slack, Discord, Zapier, Make, n8n, or any custom endpoint with one URL field |\n| **Discord Rich Embed** | Set `DISCORD_WEBHOOK_URL` and MiroShark POSTs a Discord-native embed alongside the generic webhook: consensus-coloured border, scenario title, belief percentage fields, share-card thumbnail, link. Operators no longer have to teach Discord how to render a raw JSON blob — pure stdlib, opt-in, fire-and-forget. See [docs\u002FNOTIFICATIONS.md](docs\u002FNOTIFICATIONS.md) |\n| **Slack Block Kit** | Set `SLACK_WEBHOOK_URL` and MiroShark POSTs a Slack-native Block Kit message: scenario header, Unicode block-bar belief percentages, Quality + Scale + Resolution fields, \"View simulation\" action button. Channel-native rendering instead of a JSON code-block dump — pure stdlib, opt-in, fire-and-forget |\n| **SMTP Completion Emails** | Set `SMTP_HOST` and `SMTP_TO` (comma-separated recipients) and every terminal-state transition ships a `multipart\u002Falternative` email — plain text with Unicode belief bars + HTML with inline-CSS swatches and a consensus-coloured \"View simulation →\" CTA. Subject `[MiroShark] Bullish: \u003Cscenario>` so inbox filters can triage on direction alone. `SMTP_USER`\u002F`SMTP_PASSWORD` optional (unauthenticated relays supported); STARTTLS attempted on port 587 with credential-leak refusal on STARTTLS failure. The one notification channel with zero platform dependency — every operator already has a mailbox. See [docs\u002FNOTIFICATIONS.md](docs\u002FNOTIFICATIONS.md) |\n| **Webhook Signature Verification** | Optional `WEBHOOK_SECRET` HMAC-signs every dispatched payload with an `X-MiroShark-Signature: sha256=\u003Chex>` header. Recipients verify in three lines of stdlib `hmac` — same scheme Stripe and GitHub use. Empty secret = no header, fully backward compatible |\n| **Webhook Delivery Log** | Per-sim `webhook-log.jsonl` records every dispatch attempt (status code, latency, error). Inspect from the EmbedDialog and re-fire any failed delivery with a \"Retry\" button — closes the operational blindspot every Zapier \u002F n8n integration eventually hits |\n| **Surface Usage Analytics** | `GET \u002Fapi\u002Fsimulation\u002F\u003Cid>\u002Fsurface-stats` — per-share-surface request counters (share card \u002F replay GIF \u002F transcript \u002F trajectory \u002F chart.svg \u002F thread \u002F watch page \u002F Atom \u002F RSS \u002F reproduce.json \u002F lineage \u002F notebook.ipynb) with a synthetic `total`. Inbound observability for the distribution loop the webhook log tracks on the outbound side |\n| **Reproducibility Config** | `GET \u002Fapi\u002Fsimulation\u002F\u003Cid>\u002Freproduce.json` — citation primitive for the share surfaces. A v1-schema JSON blob carrying every parameter another operator needs to re-run the same simulation: scenario, agent count, total rounds, platform toggles, time-config knobs, director events, and fork \u002F counterfactual lineage. Identical exports of a finished sim are bytewise-identical, so the file hash is a stable citation key |\n| **Jupyter Notebook Export** | `GET \u002Fapi\u002Fsimulation\u002F\u003Cid>\u002Fnotebook.ipynb` — analysis-ready companion to the reproducibility config. The trajectory CSV is embedded directly inside the notebook so it runs air-gapped; cells scaffold imports, the belief-evolution line chart, the final-consensus bar chart, and a quality summary DataFrame. Opens in JupyterLab, VS Code, or Google Colab in one click. Bytewise-stable, same citation-hash property as reproduce.json |\n| **Lineage Navigator** | `GET \u002Fapi\u002Fsimulation\u002F\u003Cid>\u002Flineage` — turn the `parent_simulation_id` pointer into a navigable graph. Surfaces the parent a sim was forked \u002F branched from plus every public child whose parent points back at it. Trace the intellectual ancestry of a result without remembering each child sim id |\n| **OriginTrail DKG Citation** | Opt-in: set `DKG_API_URL` + `DKG_AUTH_TOKEN` + `DKG_CONTEXT_GRAPH_ID` and the EmbedDialog grows a \"Publish to DKG\" button. Anchors the scenario, agent count, final consensus, quality, lineage, and `reproduce.json` SHA-256 on the OriginTrail Decentralized Knowledge Graph as a cryptographically verifiable Knowledge Asset. Returned UAL + Merkle root + transaction hash become a permanent, un-rewritable citation key — provenance property that survives the MiroShark host going away. Idempotent (one publish per sim) and stdlib-only. See [docs\u002FDKG.md](docs\u002FDKG.md) |\n\nEach feature is documented in **[docs\u002FFEATURES.md](docs\u002FFEATURES.md)**.\n\n### Use cases\n\n- **PR crisis testing** — simulate public reaction to a press release before publishing\n- **Market reaction** — feed financial news and observe simulated trader + investor sentiment\n- **Advertisement** — test a campaign, headline, or pitch against a simulated audience before spending\n- **Policy analysis** — test draft regulations against a simulated public\n- **Life decision** — frame a personal decision (job move, relocation, launch timing) as a scenario and watch diverse personas argue it out\n- **What-if history** — rewrite a historical event and see how a population of personas re-narrates the aftermath\n- **Creative experiments** — feed a novel with a lost ending; agents write a narratively consistent conclusion\n\n### Screenshots\n\n\u003Cdiv align=\"center\">\n\u003Ctable>\n\u003Ctr>\u003Ctd>\u003Cimg src=\".\u002Fdocs\u002Fimages\u002F1.jpg\" width=\"100%\"\u002F>\u003C\u002Ftd>\u003Ctd>\u003Cimg src=\".\u002Fdocs\u002Fimages\u002F2.jpg\" width=\"100%\"\u002F>\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Cimg src=\".\u002Fdocs\u002Fimages\u002F3.jpg\" width=\"100%\"\u002F>\u003C\u002Ftd>\u003Ctd>\u003Cimg src=\".\u002Fdocs\u002Fimages\u002F4.jpg\" width=\"100%\"\u002F>\u003C\u002Ftd>\u003C\u002Ftr>\n\u003Ctr>\u003Ctd>\u003Cimg src=\".\u002Fdocs\u002Fimages\u002F5.jpg\" width=\"100%\"\u002F>\u003C\u002Ftd>\u003Ctd>\u003Cimg src=\".\u002Fdocs\u002Fimages\u002F6.jpg\" width=\"100%\"\u002F>\u003C\u002Ftd>\u003C\u002Ftr>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\n\u003Cdiv align=\"center\">\n\u003Ctable>\n\u003Ctr>\n\u003Ctd>\u003Cimg src=\".\u002Fdocs\u002Fimages\u002Fdiagram1.jpg\" alt=\"Diagram 1\" width=\"100%\"\u002F>\u003C\u002Ftd>\n\u003Ctd>\u003Cimg src=\".\u002Fdocs\u002Fimages\u002Fdiagram2.jpg\" alt=\"Diagram 2\" width=\"100%\"\u002F>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\n### Documentation\n\n| | |\n|---|---|\n| [Install](docs\u002FINSTALL.md) | Every deployment path: cloud, Docker, Ollama, Claude Code |\n| [Configuration](docs\u002FCONFIGURATION.md) | Env vars, model routing, feature flags |\n| [Models](docs\u002FMODELS.md) | Cloud preset, local Ollama models, benchmark findings |\n| [Architecture](docs\u002FARCHITECTURE.md) | Simulation engine, memory pipeline, graph retrieval |\n| [Features](docs\u002FFEATURES.md) | Deep dive on every feature in the table above |\n| [HTTP API](docs\u002FAPI.md) | Every endpoint, grouped by concern — plus interactive Swagger UI at `\u002Fapi\u002Fdocs` and a spec at `\u002Fapi\u002Fopenapi.yaml` |\n| [CLI](docs\u002FCLI.md) | `miroshark-cli` reference |\n| [MCP](docs\u002FMCP.md) | Claude Desktop \u002F Cursor \u002F Windsurf \u002F Continue integration + report agent tools (auto-generated snippets in Settings → AI Integration) |\n| [Webhooks](docs\u002FWEBHOOKS.md) | Completion webhook payload, headers, delivery semantics, Slack\u002FDiscord\u002FZapier\u002Fn8n recipes |\n| [DKG citation](docs\u002FDKG.md) | OriginTrail DKG anchoring — UAL + Merkle root + on-chain citation key for any finished sim |\n| [Observability](docs\u002FOBSERVABILITY.md) | Debug panel, event stream, logging |\n| [Contributing](CONTRIBUTING.md) | Tests and development |\n\n---\n\n\u003Ca id=\"中文\">\u003C\u002Fa>\n\n## 中文\n\n> **一切皆可模拟,只需 $1、不到 10 分钟 — 通用群体智能引擎**\n> 投入任何素材 — 新闻稿、头条、政策草案、一个无解的问题、一段历史假设 — MiroShark 都会派出数百个智能体,每小时一轮地做出反应:发帖、辩论、交易、改变想法。\n\n### 它做什么\n\n- 你提供一个情景,MiroShark 围绕它构建世界。\n- 数百个有据可依的智能体在 Twitter、Reddit 与预测市场上每小时一轮地反应。\n- 与任意智能体对话。在运行中投入突发新闻。派生出反事实分支。\n- 生成一份引用真实发帖与交易的复盘报告。\n\n### 快速开始\n\n推荐路径:**一个 [OpenRouter](https:\u002F\u002Fopenrouter.ai\u002F) 密钥 + `.\u002Fmiroshark` 启动器**。首次模拟约 10 分钟、约 $1。\n\n**前置条件** — Python 3.11+、Node 18+、Neo4j,以及 [OpenRouter 密钥](https:\u002F\u002Fopenrouter.ai\u002F)。\n\n安装 Neo4j(启动器会自动启动它):\n\n- **macOS** — `brew install neo4j`\n- **Linux** — `sudo apt install neo4j` *(或所在发行版对应的命令)*\n- **Windows** — 安装 [Neo4j Desktop](https:\u002F\u002Fneo4j.com\u002Fdownload\u002F) *(原生 GUI,先在其中启动数据库,然后通过 WSL2 或 Git Bash 运行启动器)*,或在 [WSL2](https:\u002F\u002Flearn.microsoft.com\u002Fwindows\u002Fwsl\u002Finstall) 内运行整套环境并按 Linux 步骤操作\n- **零安装** — 创建免费的 [Neo4j Aura](https:\u002F\u002Fneo4j.com\u002Fcloud\u002Faura-free\u002F) 云实例,在 `.env` 中将 `NEO4J_URI` \u002F `NEO4J_PASSWORD` 指向它\n\n然后:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Faaronjmars\u002FMiroShark.git && cd MiroShark\ncp .env.example .env\n# 将你的 OpenRouter 密钥粘贴到 LLM_API_KEY \u002F SMART_API_KEY \u002F\n# NER_API_KEY \u002F OPENAI_API_KEY \u002F EMBEDDING_API_KEY 五个字段\n# (同一个密钥,粘 5 处)。默认组合是 Mimo V2 Flash + Gemini 3 Flash。\n.\u002Fmiroshark\n```\n\n启动器会检查依赖、启动 Neo4j、安装前后端,并在 `:3000` + `:5001` 提供服务。Ctrl+C 停止。打开 `http:\u002F\u002Flocalhost:3000` 投入文档即可。\n\n**界面语言** — 启动后,在导航栏右上角点击「中 \u002F EN」按钮即可切换中英文。语言选择会保存在浏览器中,下次访问时自动应用。模板画廊与公开模拟列表的卡片标题\u002F描述也会随之切换。\n\n**其他部署路径** — [一键 Railway \u002F Render](docs\u002FINSTALL.zh-CN.md)、[Docker + Ollama](docs\u002FINSTALL.zh-CN.md)、[手动 Ollama](docs\u002FINSTALL.zh-CN.md)、[Claude Code CLI](docs\u002FINSTALL.zh-CN.md) — 详见 **[docs\u002FINSTALL.zh-CN.md](docs\u002FINSTALL.zh-CN.md)**。\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fdocs\u002Fimages\u002Fmiroshark-cn.jpg\" alt=\"MiroShark 中文界面\" \u002F>\n\u003C\u002Fp>\n\n### 主要功能\n\n| 功能 | 说明 |\n|---|---|\n| **智能配置** | 投入文档 → 约 2 秒生成三套自动情景(看涨\u002F看跌\u002F中立) |\n| **热门追踪** | 从 RSS 中挑选实时新闻,一键预填情景 |\n| **直接提问** | 不用文档,直接打字提问 — MiroShark 自行调研并撰写种子简报 |\n| **可分享情景链接** | 在推文或博客文章中放入 `?scenario=...&url=...` 链接 — 读者一打开就会看到已预填的「新建模拟」表单。`?template=\u003Cslug>` 可自动启动任一预设模板。这是 `\u002Fwatch` 与 `\u002Fshare` 上「派生此情景」的「未运行情景」对应版本 |\n| **反事实分支** | 在运行中的模拟里派生分支并注入事件(「如果 24 轮时 CEO 辞职会怎样?」) |\n| **导演模式** | 在当前时间线中投入突发新闻,无需派生分支 |\n| **预设模板** | 6 套基准情景:加密代币发布、企业危机、政治辩论、产品发布、校园风波、历史假设 |\n| **现实预言机** | 可选地从 [FeedOracle](https:\u002F\u002Fmcp.feedoracle.io\u002Fmcp) MCP 中拉取实时数据(484 个工具) |\n| **每个智能体的 MCP 工具** | 人设可在模拟过程中调用真实 MCP 工具(网页搜索、API 等) |\n| **自定义 Wonderwall 端点** | 将模拟主循环指向任意 OpenAI 兼容端点(自部署 vLLM、Modal、微调模型……),不影响 Default\u002FSmart\u002FNER。设置 `WONDERWALL_BASE_URL` + `WONDERWALL_API_KEY` |\n| **嵌入与发布** | 公开\u002F私有切换 + 嵌入 URL,便于分享已完成的运行 |\n| **社交分享卡片** | 1200×630 PNG,自动展开情景、状态、质量与信念分布,适配 Twitter\u002FX、Discord、Slack、LinkedIn |\n| **信念回放动图** | 1200×630 GIF,每轮一帧,信念条动态滑向各轮分布。Discord 与 Slack 在直接 URL 上自动播放 |\n| **转录导出** | 每轮智能体发帖与立场标签,导出为 Markdown(YAML 头,适配 Notion \u002F Obsidian \u002F Substack)或结构化 JSON(适配 SDK 与 LLM 评审管线) |\n| **推文串导出** | `GET \u002Fapi\u002Fsimulation\u002F\u003Cid>\u002Fthread.txt` — 自动生成 X \u002F Twitter 推文串:介绍推文 + 每个信念转折点(主导立场翻转的轮次)一条推文 + 末尾推文(附观看与分享 URL)。每条推文 ≤280 字符,可单条复制或整串复制。与分享卡片 \u002F 回放 GIF \u002F 转录 \u002F 轨迹 \u002F 实时观看页一同构成第六种分享形式 |\n| **公开图库** | `\u002Fexplore` 以卡片网格浏览所有公开模拟 — 预览分享卡、共识分布与质量指标;一键打开或派生 |\n| **图库搜索与筛选** | 在 `\u002Fexplore` 与 `\u002Fverified` 上提供关键词搜索 + 看涨\u002F中立\u002F看跌 + 优秀\u002F良好\u002F一般\u002F较差 + 按日期\u002F轮次\u002F智能体\u002F热门排序。`trending` 按累计分享面服务次数排序,让被分发最广的模拟浮于顶部。URL 编码后 `?q=aave&consensus=bearish` 可作为书签分享。与其他所有表面共享同一 ±0.2 立场阈值 |\n| **已验证预言** | 为公开模拟标注真实结果(命中 \u002F 部分 \u002F 失误 + 链接)。`\u002Fverified` 是命中预言专属展厅 |\n| **RSS \u002F Atom 订阅源** | `\u002Fapi\u002Ffeed.atom` + `\u002Fapi\u002Ffeed.rss` — 每个新发布的模拟无需任何整理就会进入 Feedly \u002F Readwise \u002F Inoreader \u002F NetNewsWire \u002F Obsidian RSS。`?verified=1` 只看已验证内容 |\n| **搜索引擎站点地图** | 自动生成的 `\u002Fsitemap.xml`(sitemaps.org 0.9)列出每个公开模拟的 `\u002Fshare\u002F\u003Cid>` + `\u002Fwatch\u002F\u003Cid>` URL;配套的 `\u002Frobots.txt` 通过标准 `Sitemap:` 指令通告。在 Google Search Console 提交一次 — 每个新发布的模拟都将变得可被搜索。纯 stdlib `xml.etree.ElementTree`,可通过 `ENABLE_SITEMAP=false` 退出 |\n| **文章生成** | Substack 风格的复盘文章,基于真实发帖与交易数据 |\n| **互动网络** | 力导向智能体关系图,带回声室指标 |\n| **人口分布** | 原型聚类(分析师 \u002F 影响者 \u002F 散户 \u002F 旁观者……) |\n| **质量诊断** | 单次运行的健康评分 — 参与度、连贯性、多样性、方差 |\n| **历史数据库** | 搜索、克隆、导出或删除任一过往模拟 |\n| **轨迹访谈** | 查看智能体回复背后的完整推理链,而不止是回复本身 |\n| **推送通知** | 长耗时图谱 \u002F 模拟 \u002F 报告任务完成时的浏览器推送提醒 |\n| **完成 Webhook** | 模拟一结束即 POST 一份 JSON 摘要 — 一个 URL 字段即可连通 Slack、Discord、Zapier、Make、n8n 或任意自定义端点 |\n| **Discord 富嵌入** | 设置 `DISCORD_WEBHOOK_URL`,MiroShark 会在通用 Webhook 之外另行推送一份 Discord 原生 embed:按共识着色的边框、情景标题、信念百分比字段、分享卡缩略图、链接。运营者无需再为 Discord 写格式化代码 — 纯 stdlib,按需启用,fire-and-forget。详见 [docs\u002FNOTIFICATIONS.md](docs\u002FNOTIFICATIONS.md) |\n| **Slack Block Kit** | 设置 `SLACK_WEBHOOK_URL`,MiroShark 会推送 Slack 原生 Block Kit 消息:情景标题块、Unicode 块字符信念百分比、质量 \u002F 规模 \u002F 结局字段、「打开模拟」操作按钮。频道里的不是 JSON 代码块,而是真正的频道卡片 — 纯 stdlib,按需启用,fire-and-forget |\n| **SMTP 完成邮件通知** | 设置 `SMTP_HOST` 与 `SMTP_TO`(逗号分隔的收件人列表),每次模拟达到终止状态都会以 `multipart\u002Falternative` 发出一封邮件 — 纯文本部分带 Unicode 块字符信念条,HTML 部分配合 Discord 同色系内联色块和按共识着色的「View simulation →」CTA。主题为 `[MiroShark] Bullish: \u003C情景>`,邮箱过滤规则只看主题就能按方向分流。`SMTP_USER`\u002F`SMTP_PASSWORD` 可选(支持无认证 LAN 中继),587 端口尝试 STARTTLS,STARTTLS 失败时若设置了凭据会拒绝明文发送。这是唯一一个不需要任何平台账户的通知通道 — 每位运营者都已经有邮箱。详见 [docs\u002FNOTIFICATIONS.md](docs\u002FNOTIFICATIONS.md) |\n| **Webhook 签名验证** | 可选的 `WEBHOOK_SECRET` 会用 HMAC 对每次投递的载荷签名,并通过 `X-MiroShark-Signature: sha256=\u003Chex>` 头部送出。消费方用三行 stdlib `hmac` 即可校验 — Stripe 和 GitHub 用的就是这一套。留空即无签名头部,完全向后兼容 |\n| **Webhook 投递日志** | 每个模拟在 `webhook-log.jsonl` 记录每次投递尝试(HTTP 状态码、延迟、错误)。可在 EmbedDialog 中查看,并通过「重试」按钮重发任何失败的投递 — 弥补每个 Zapier \u002F n8n 集成最终都会遇到的运维盲点 |\n| **分发统计(分享面使用分析)** | `GET \u002Fapi\u002Fsimulation\u002F\u003Cid>\u002Fsurface-stats` — 每个分享面的请求计数器(分享卡 \u002F 回放 GIF \u002F 转录 \u002F 轨迹 \u002F 推文串 \u002F 观看页 \u002F Atom \u002F RSS \u002F `reproduce.json` \u002F `\u002Flineage`),以及合成的 `total`。Webhook 日志在出站侧跟踪分发回路,本面则负责入站可观测性 |\n| **可复现配置导出** | `GET \u002Fapi\u002Fsimulation\u002F\u003Cid>\u002Freproduce.json` — 分享面背后的引用基元。v1-schema 的 JSON 文档,携带另一位研究者复现同一次模拟所需的全部参数:情景、智能体数、轮次、平台切换、时序配置、导演事件、派生 \u002F 反事实谱系。已完成模拟的多次导出在字节级别完全一致 — 文件哈希可作为稳定的引用键 |\n| **谱系导航** | `GET \u002Fapi\u002Fsimulation\u002F\u003Cid>\u002Flineage` — 将 `parent_simulation_id` 指针转化为可导航的图。展示该模拟派生 \u002F 分支自的父模拟,以及每一个把父级指回此模拟的公开子模拟。无需记住每个子模拟 ID,即可追踪一项结果的思想脉络 |\n\n每项功能详见 **[docs\u002FFEATURES.zh-CN.md](docs\u002FFEATURES.zh-CN.md)**。\n\n### 应用场景\n\n- **公关危机演练** — 在新闻稿发布前模拟舆论反应\n- **市场反应** — 喂入财经新闻,观察模拟交易者与投资者情绪\n- **广告测试** — 在投放前用模拟受众检验文案、标题或卖点\n- **政策分析** — 用模拟公众检验法规草案\n- **人生抉择** — 把个人决定(换工作、搬家、上线时机)作为情景,看多元人设辩论\n- **历史假设** — 改写一段历史事件,看一群人设如何重写后续叙事\n- **创意实验** — 喂入失去结尾的小说,智能体续写出叙事自洽的结局\n\n### 文档\n\n| | |\n|---|---|\n| [安装](docs\u002FINSTALL.zh-CN.md) | 全部部署路径:云端、Docker、Ollama、Claude Code |\n| [配置](docs\u002FCONFIGURATION.zh-CN.md) | 环境变量、模型路由、特性开关 |\n| [模型](docs\u002FMODELS.zh-CN.md) | 云端预设、本地 Ollama 模型、基准发现 |\n| [架构](docs\u002FARCHITECTURE.zh-CN.md) | 模拟引擎、记忆管线、图谱检索 |\n| [功能](docs\u002FFEATURES.zh-CN.md) | 上述功能表的深入解析 |\n| [HTTP API](docs\u002FAPI.zh-CN.md) | 全部端点,按关注点分组 — 含 `\u002Fapi\u002Fdocs` 交互式 Swagger UI 与 `\u002Fapi\u002Fopenapi.yaml` 规范 |\n| [CLI](docs\u002FCLI.zh-CN.md) | `miroshark-cli` 参考 |\n| [MCP](docs\u002FMCP.zh-CN.md) | Claude Desktop \u002F Cursor \u002F Windsurf \u002F Continue 集成 + 报告智能体工具(可在「设置 → AI 集成」中获取自动生成的片段) |\n| [Webhook](docs\u002FWEBHOOKS.zh-CN.md) | 完成 Webhook 载荷、头部、投递语义、Slack\u002FDiscord\u002FZapier\u002Fn8n 食谱 |\n| [可观测性](docs\u002FOBSERVABILITY.zh-CN.md) | 调试面板、事件流、日志 |\n| [贡献](CONTRIBUTING.zh-CN.md) | 测试与开发 |\n\n---\n\n## License · 许可证\n\nAGPL-3.0. See [LICENSE](.\u002FLICENSE).\nAGPL-3.0,详见 [LICENSE](.\u002FLICENSE)。\n\nSupport the project · 支持本项目:`0xd7bc6a05a56655fb2052f742b012d1dfd66e1ba3`\n\n## Star History\n\n[![Star History Chart](https:\u002F\u002Fapi.star-history.com\u002Fsvg?repos=aaronjmars\u002Fmiroshark&type=Date)](https:\u002F\u002Fwww.star-history.com\u002F#aaronjmars\u002Fmiroshark&Date)\n","MiroShark 是一个通用的群体智能引擎，能够在10分钟内以不到1美元的成本模拟任何场景。其核心功能包括通过生成数百个基于现实世界的代理来响应用户输入的各种信息，如新闻、政策草案等，并在模拟过程中进行互动、讨论和交易。该工具使用Python开发，结合了Twitter、Reddit以及预测市场的模拟环境，支持与单个代理聊天或中途插入突发新闻改变模拟进程。此外，MiroShark 还能提供详细的报告，引用实际的帖子和交易记录。此项目适用于需要快速评估特定情境影响的领域，比如金融预测、未来趋势分析和社会动态研究等。",2,"2026-06-11 03:49:49","high_star"]