Sora (空)

面向 AI 代理从日本 Web 获取数据的 Self-hosted MCP / REST 集成服务器
All-in-One, Zero-Middleware Web Scraping & Japanese Life Infrastructure Engine for AI Agents

Sora 是一个 All-in-One MCP / REST 服务器，让 LLM 和 AI 代理（Claude Desktop、Cursor、Cline、OpenCodeInterpreter、Dify 等）能够自由、安全地探索和操作 日本 Web 空间与日常基础设施。

它完全不需要外部数据库（Redis / PostgreSQL）或消息队列，仅凭一个包含无头 Chromium 和日语 CJK 字体的单一容器 / 单一二进制文件，即可从每月 800 日元的 VPS 上立即运行。

flowchart LR
    subgraph Clients["AI Clients / Agents"]
        Claude["Claude Desktop / Cursor"]
        Agents["LangChain / AutoGen / Dify"]
    end

    subgraph Sora["Sora All-in-One (Distroless / Bun)"]
        direction TB
        MCP["MCP Server (Streamable HTTP / SSE)"]
        REST["Hono REST API (OpenAPI 3.0)"]
        Auth["Timing-Safe Auth & SSRF Guard"]
        LRU["True LRU In-Memory Cache"]
        
        subgraph Engine["Dual Scrape Engine"]
            Fast["Static Fetch + Readability + AI Chunker"]
            Browser["Stealth Chromium + Browser DSL (Tabs/Clicks)"]
        end

        subgraph JP["Japan Life Infrastructure"]
            JMA["気象庁 1,805自治体 天気予報"]
            Transit["Yahoo! 路線乗換・IC運賃"]
            Yahoo["Yahoo! リアルタイム(X)/知恵袋/ニュース/画像/動画"]
        end
    end

    subgraph Web["Public Internet"]
        Sites["Web Sites / PDFs / SPAs"]
        PublicData["気象庁 / Yahoo / X"]
    end

    Clients <-->|MCP / REST| Sora
    Fast --> Sites
    Browser --> Sites
    JP --> PublicData

⚡ 5 秒连接的 Quickstart (Claude Desktop / Cursor / Cline)

只需在您使用的 AI 代理的配置文件（claude_desktop_config.json 等）中添加以下内容，即可立即启用 16 种强大的工具集。

① Remote MCP (HTTP / SSE) 连接

在 Sora 容器启动的状态下指定 URL：

{
  "mcpServers": {
    "sora": {
      "url": "http://localhost:3016/mcp"
    }
  }
}

② 使用 Docker / Podman 一键启动

docker run -d -p 3016:8000 --name sora ghcr.io/ikenokazuki/sora:latest

Related MCP server: Agent Toolbox

🌟 主要特点与优势 (Why Sora?)

1. 🗾 日本日常基础设施 & Web 探索的全面覆盖:

   • 提供海外工具（Firecrawl / Tavily）无法支持的「Yahoo! 知恵袋」「X (Twitter) 实时速报」「气象厅官方开放数据直连（全国 1,805 个市区町村自动选定）」「电车换乘指南」，全部整合在单一 MCP 中。

2. ⚡ 压倒性的毫秒级响应 & 超低内存消耗:

   • 通过 Bun 原生编译，API 响应 1.5ms，常驻内存 JS 堆 ~32MB / 总计 ~140MB。将 AI 代理的等待时间缩短到极致。

3. 📦 完全 All-in-One & 零中间件:

   • 完全不需要 Redis、PostgreSQL、外部工作队列等。仅凭单一二进制文件 / 单一容器即可立即完成。

4. 🛡️ Distroless（无 Shell）& 严格的安全机制:

   • 基础镜像采用 gcr.io/distroless/cc-debian12。容器内不存在 /bin/sh、bash、curl 等，使 RCE（任意代码执行）攻击失效。

   • 标准配备 SSRF / DNS Rebinding 阻断、通过常数时间比较防止 Timing Attack、浏览器会话所有权隔离、DoS 防御（Body Limit 10MB）。

5. 🕹️ 有状态的浏览器操作 DSL:

   • 可通过 API / MCP 直接控制 open → fill → click → screenshot → evaluate 的多轮交互式浏览器会话。

📊 性能 & 架构对比

⏱️ 各端点的实测响应速度 (Measured Latency: Cold vs Cached)

以下是在实际本地服务器上「首次获取（非缓存时）」与「缓存命中时」的实测延迟一览。与 AI 代理思考、生成的时间（1〜3 秒）相比，响应速度极为迅速。

⚡ 内部增强・AI 优化处理的实测速度 (In-Memory Latency)

不经过外部 LLM API，全部通过 Bun 原生及优化算法在 1 毫秒以内（< 1ms） 完成。

🏛️ 设计思想 (Design Philosophy & Principles)

Sora 基于以下 4 项核心设计原则 构建：

1. ✂️ 奥卡姆剃刀（Occam's Razor & Zero-Middleware）:

   • 「如无必要，勿增实体。满足需求的最简单架构就是最佳架构。」

   • 彻底排除 Redis、PostgreSQL、外部队列、臃肿的微服务群。仅凭「单一容器・单一二进制文件」 即可运行，从每月 800 日元的 VPS 或 Raspberry Pi 到处理数万请求的云端，都能稳定常驻。

2. 🛡️ 隐身与生还率的帕累托最优（Stealth & Pareto Optimum）:

   • 如果只是「0ms 机械式访问」，会立即被对方服务器的 WAF 或 Cloudflare 封禁 IP，成功率将跌至 0%。

   • 对同一域名的连续访问会自动插入 150ms + Jitter（0〜100ms 随机波动），打字操作也会附加 15〜40ms 的人类化延迟。在不损害 AI 感知速度的前提下，优先确保 将数据可靠带回的生还率。

3. 🔒 基于 Distroless 的强健安全机制（Distroless by Design）:

   • 容器内不存在 /bin/sh、bash、curl、apt，因此即使存在未知漏洞，攻击者在原理上也没有夺取 Shell 的空间（RCE: 任意代码执行）。标准配备非 root 执行及严格的 SSRF 阻断。

4. 🗾 公共开放数据直连・可持续性（Sustainable & Autonomous）:

   • 天气预报直接访问气象厅官方开放数据 CDN（jma.go.jp）。通过全国 1,805 个市区町村名称的零毫秒自动解析和 30 分钟 LRU 缓存，在将对端服务器负载降至最低的同时永久自主运行。

1. 快速开始

1.1 容器启动 (Docker / Podman)

从 GitHub Container Registry (GHCR) 一键即可立即启动：

docker run -d \
  --name sora \
  -p 3016:8000 \
  -e API_KEY="your-secret-api-key" \
  -e ENABLED_MODULES="all" \
  ghcr.io/ikenokazuki/sora:latest

1.2 MCP 客户端配置（Claude Desktop / Cursor / Cline / Windsurf 等）

Streamable HTTP 连接（推荐・标准）

在配置文件（例如：claude_desktop_config.json 或 Cursor 的 MCP 设置）中添加以下内容：

{
  "mcpServers": {
    "sora": {
      "url": "http://localhost:3016/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-api-key"
      }
    }
  }
}

SSE 连接（面向旧版 SSE 客户端）

{
  "mcpServers": {
    "sora": {
      "url": "http://localhost:3016/sse",
      "headers": {
        "Authorization": "Bearer your-secret-api-key"
      }
    }
  }
}

(※ 未设置 API 密钥时，可省略 headers)

2. 提供的 MCP 工具列表 (共 16 个工具 / 4 个模块)

Sora 根据用途由 4 个逻辑模块 构成。可通过环境变量 ENABLED_MODULES（默认：all，或 web,browser,yahoo,life）自由自定义启用的类别。

┌──────────────────────────────────────────────────────────────────────────┐
│                         Sora - Modular MCP                               │
├─────────────────┬───────────────────┬──────────────────┬─────────────────┤
│ 🌐 Core Web     │ 🤖 Browser Action │ 🇯🇵 Yahoo Services │ 🗾 Daily Life   │
│ (`web`)         │ (`browser`)       │ (`yahoo`)        │ (`life`)        │
│ ・search_web    │ ・browser_action  │ ・search_image   │ ・search_route  │
│ ・scrape        │   (クリック/入力/ │ ・search_video   │   (乗換案内)    │
│ ・scrape_batch  │    スクショ/JS実行│ ・search_news    │ ・get_weather   │
│ ・search_deep   │    セッション保持)│ ・search_chiebukuro│ (気象庁天気)  │
│ ・map_site      │                   │ ・search_realtime│                 │
│ ・crawl_site    │                   │ ・search_trend   │                 │
│                 │                   │ ・suggest_keywords│                │
└─────────────────┴───────────────────┴──────────────────┴─────────────────┘

🌐 Module 1: Core Web & Crawling (ENABLED_MODULES=web)

Web 搜索与正文抓取、批量并行获取、深度集成搜索、站点地图解析、递归爬取。

💡 LLM / Agent 集成时的最佳实践 & limit 调整指南

在 Agent 或 RAG 应用中使用 Web 搜索、抓取和爬取时，获取数量（limit）的设置会显著影响延迟和回答质量。

1. 增加获取数量的优点和缺点

2. 实现高精度LLM应用的最佳实践

[!TIP] 更有效的方法：

1. 区分使用摘要和全文：搜索摘要（search_web）本身返回 10-20条 结果以广泛了解概况，而全文抓取目标（search_deep 的 limit）则 限制在排名前3-5条，这是最快且最精确的方法。

2. 结合使用高亮提取：启用 extractHighlights: true（query 指定）后，结构与邻近感知BM25+引擎（标题上下文继承、短语完全匹配、邻近度评分、KWIC摘要生成）能让LLM专注于阅读与查询最相关的关键段落和句子，而无需阅读整个长页面，从而在防止幻觉的同时，将Token消耗减少70-90%（无需外部LLM，本地运行仅需0.3ms）。

3. 所有端点通用的元数据 (Firecrawl / Tavily 兼容)：从 OGP / JSON-LD / HTML 元标签自动提取 publishedTime（发布日期/更新日期）、author（作者）、siteName（站点名称），并附加到 Frontmatter 和 JSON 响应中。LLM 可以即时判断信息的时效性（事实核查）。

4. GFM语法高亮语言保持：从 <pre><code class="language-python"> 等标签中准确识别编程语言名称，并在 Markdown 输出时以 ```python 形式重现。

5. 自动Token压缩与噪声去除：自动清理空链接、无效的 JavaScript 链接、不必要的重复空行（cleanMarkdownTokens），并完全清除 Cookie 同意横幅（OneTrust / Cookiebot 等），始终保持 LLM 上下文的清洁。

6. robots.txt 站点地图自动发现：从 /robots.txt 自动检测非常规配置的 Sitemap URL，并递归爬取最多 1,000 条 Sitemap Index。

7. 爬取时的流式传输：爬取多个页面时，利用 POST /crawl/stream（SSE）在每获取一个页面后立即进行流式接收和处理，无需等待所有页面完成即可即时向用户或LLM返回中间响应。

3. 实测基准测试与可扩展性特性（本地实测值）

🤖 模块 2：浏览器操作与自动化 (ENABLED_MODULES=browser)

支持表单输入、按钮点击、页面滚动、JavaScript 执行、截图拍摄、多轮对话会话。

🇯🇵 模块 3：Yahoo! JAPAN 服务 (ENABLED_MODULES=yahoo)

完全专注于日本媒体、问答、趋势和实时信息的搜索组。

🗾 模块 4：日本日常生活与交通 (ENABLED_MODULES=life)

直接连接日本公共交通和气象厅官方开放数据的生活基础设施功能。

3. REST API 规范

基础 URL: http://localhost:3016（或部署目标的域名 URL）

3.1 健康检查与指标

GET /health

{
  "status": "ok",
  "service": "sora",
  "cachedEntries": 0,
  "chromiumAvailable": true,
  "yahooMcpAvailable": true,
  "mcpConnected": true,
  "timestamp": "2026-08-21T05:54:26.782Z"
}

GET /metrics（运行统计、缓存命中率、资源使用量）

{
  "status": "ok",
  "service": "sora",
  "uptimeSeconds": 1420,
  "cache": {
    "size": 42,
    "maxSize": 3000,
    "hits": 156,
    "misses": 48,
    "hitRatio": 0.7647
  },
  "activeSessions": 2,
  "chromium": {
    "available": true,
    "sharedConnected": true
  },
  "memory": {
    "rssMb": 86,
    "heapUsedMb": 34,
    "heapTotalMb": 58
  },
  "timestamp": "2026-08-22T04:20:00.000Z"
}

GET /metrics?format=prometheus 或 Accept: text/plain（用于 Prometheus 监控的指标）

以 Grafana / Prometheus 监控栈可直接导入的标准文本格式输出。

# HELP sora_uptime_seconds Process uptime in seconds
# TYPE sora_uptime_seconds gauge
sora_uptime_seconds 1420
# HELP sora_memory_rss_bytes Resident set size in bytes
# TYPE sora_memory_rss_bytes gauge
sora_memory_rss_bytes 90177536
# HELP sora_cache_hits_total Total cache hits
# TYPE sora_cache_hits_total counter
sora_cache_hits_total 156
# HELP sora_cache_hit_rate Cache hit rate
# TYPE sora_cache_hit_rate gauge
sora_cache_hit_rate 0.7647
# HELP sora_active_browser_sessions Active browser sessions count
# TYPE sora_active_browser_sessions gauge
sora_active_browser_sessions 2

3.2 单 URL / PDF 抓取 (POST /scrape)

• 请求：

{
  "url": "https://example.com/article",
  "maxChars": 30000,
  "mode": "auto",
  "formats": ["markdown", "jsonLd", "images", "links"],
  "onlyMainContent": true,
  "selectors": {
    "productName": "h1.product-title",
    "price": ".price-value",
    "buyLink": "a.btn-buy@href",
    "thumbnail": "img.main-photo@src"
  },
  "extractHighlights": true,
  "query": "新機能 リリース"
}

• 响应示例：

{
  "url": "https://example.com/article",
  "title": "最新アップデートのお知らせ",
  "content": "---\ntitle: \"最新アップデートのお知らせ\"\nurl: \"https://example.com/article\"\npublishedTime: \"2026-08-22T10:00:00Z\"\nauthor: \"開発チーム\"\nsiteName: \"Tech Blog\"\n---\n\n...",
  "isTruncated": false,
  "contentType": "text/html",
  "source": "web",
  "renderedWithBrowser": false,
  "publishedTime": "2026-08-22T10:00:00Z",
  "author": "開発チーム",
  "siteName": "Tech Blog",
  "extracted": {
    "productName": "Sora プレミアムキーボード",
    "price": "¥24,800",
    "buyLink": "https://example.com/cart/add?id=123",
    "thumbnail": "https://example.com/images/feature.png"
  },
  "jsonLd": [
    {
      "@context": "https://schema.org",
      "@type": "NewsArticle",
      "headline": "最新アップデートのお知らせ"
    }
  ],
  "images": [
    {
      "url": "https://example.com/images/feature.png",
      "alt": "新機能の画面イメージ"
    }
  ],
  "highlights": [
    "本日より新機能の提供を開始いたします。"
  ]
}

[!TIP] 🇯🇵 日文旧版网站自动支持：Shift_JIS (CP932) 或 EUC-JP 编码的网站也能自动判定字符编码并解码。无需担心乱码问题。

📄 PDF 提取增强：多页 PDF 文档会以 <!-- Page 1 -->\n## Page 1 的形式按页码分隔输出为结构化 Markdown，同时自动提取 totalPages 及作者等元数据。

✂️ 语法安全裁剪 & Token 估算：即使通过 maxChars 限制了字符数，也会自动安全地修正并闭合未闭合的代码块（```）或表格。此外，响应中会附带估算的 LLM Token 数 estimatedTokens。

🧩 RAG 优化语义分块 (chunkMarkdown: true)：在不破坏标题层级（H1〜H4）、段落或代码块的前提下，自动生成适当分割的 chunks: [{ index, heading, content, estimatedTokens }]，可立即用于向量搜索或 RAG。

🖼️ 图片元数据 & 标题提取 (formats: ["images"])：针对每张图片，除 URL 外，还会自动提取 <figcaption> 中的说明文字（caption）、width/height 以及主图判定（isMainImage）。

🔗 页内链接健康度与可达性判定 (validateLinks: true)：对页内链接执行轻量级并行验证，返回 HTTP 状态码和有效性 linksWithStatus: [{ url, status, ok }]。

📚 出处・引用链接结构化提取 (extractCitations: true)：将正文中的外部链接和参考文献连同上下文语句自动提取为 citations: [{ text, url, context }]。

⏱️ 阅读时间 & 字符・单词数统计：自动计算并附带正文的 characterCount、wordCount，以及根据语言特性估算的阅读时间 readingTimeMin（分钟数）。

🔔 异步 Webhook 回调 (webhookUrl)：在长时间批处理或大规模爬取完成时，将结果负载通过 HTTP POST 异步通知到指定端点。

🛡️ PII 自动掩码 (maskPii: true)：自动将邮箱地址、日本电话号码、信用卡号（Luhn 校验）等敏感信息替换为 [EMAIL]、[PHONE]、[CREDIT_CARD] 等掩码形式，保护发送至 LLM 的数据安全。

📡 进度实时 SSE 流式推送 (POST /scrape/stream)：可通过 Server-Sent Events 实时接收 start → fetch → render → enrich → done 各阶段进度事件。

🎬 YouTube / 视频媒体元数据 & 章节提取 (media)：从视频页面自动结构化提取播放时长、缩略图、章节列表（带时间戳的目录）。

🤖 LLM 优化提示词 XML 自动生成 (formatAsPrompt: true)：自动生成 Claude / GPT / Gemini 最容易理解的标准 <web_page url="..." title="...">...</web_page> 格式上下文包装器 promptContext。

🖍️ 搜索关键词正文自动高亮 (highlightMatches: true)：可将指定 query 的关键词在正文 Markdown 中以 <mark>关键词</mark> 形式高亮显示，并获取 highlightedContent。

📊 表格结构化 JSON 提取 (formats: ["tables"])：可将页面中的表格（<table>）直接获取为 { caption, headers, rows } 结构化 JSON 数组。

⚡ 超高速抽取式自动摘要 (extractSummary: true)：无需调用外部 LLM API，通过内部算法在毫秒级内自动生成重要语句（TL;DR 摘要）summary: string[]。

🎯 搜索结果去重 (dedup: true)：在新闻搜索或实时搜索中，通过相似度判定自动排除复制粘贴帖或转载文章，仅精选独特信息。

🔄 自动重试策略 (retries & retryDelayMs)：在连接失败或 429/503 错误时，以指数退避方式自动重试，提高容错能力。

📸 元素指定截图 (clipSelector)：通过指定特定元素（例如：clipSelector: "#stock-chart"），可获取仅裁剪该元素的 Base64 PNG 图片。

🍪 自定义请求头 & Cookie 注入 (headers / cookies)：可透明发送会员网站、语言指定（Accept-Language）、年龄验证 Cookie 等。

🧹 用户指定噪声选择器移除 (removeSelectors)：指定 removeSelectors: [".ad", ".comments", "#related-articles"]，可在 Markdown 转换前彻底清除特定区块。

📖 交互式 API 文档 (GET /docs)：从浏览器访问 http://localhost:3016/docs，即可通过 Swagger UI 直接测试执行（Try it out）所有 API。

3.2.1 多 URL 批量并行抓取 (POST /scrape/batch)

指定多个网页 URL，在保持按域名限流的同时，在服务器端高速并行抓取并批量获取。

• 请求 (POST):

{
  "urls": [
    "https://example.com/page1",
    "https://example.com/page2",
    "https://example.com/page3"
  ],
  "concurrency": 3,
  "maxChars": 10000,
  "mode": "auto",
  "formats": ["markdown", "jsonLd"]
}

• 响应示例:

{
  "total": 3,
  "successful": 3,
  "failed": 0,
  "results": [
    {
      "url": "https://example.com/page1",
      "title": "Page 1 Title",
      "content": "...",
      "estimatedTokens": 450
    }
  ],
  "errors": []
}

3.3 交互式浏览器自动操作 (POST /browser/action 或 POST /action)

打开网页后，依次执行点击、文本输入、滚动、等待、截图等一系列操作，并获取最终结果。同时支持一次性执行和在聊天中交互式操作的有状态多轮对话会话 (sessionId)。

① 一次性执行（单次完成）

• 请求 (POST):

{
  "url": "https://example.com/search",
  "actions": [
    { "type": "fill", "selector": "input[name='q']", "text": "Sora" },
    { "type": "click", "text": "検索" },
    { "type": "wait", "selector": ".results-container", "ms": 5000 },
    { "type": "scroll", "direction": "down", "distance": 1000 }
  ],
  "extract": {
    "markdown": true,
    "screenshot": true,
    "html": false
  },
  "timeout": 30000
}

• 响应示例:

{
  "source": "browser",
  "url": "https://example.com/search?q=Sora",
  "title": "検索結果 - Sora",
  "content": "---\ntitle: \"検索結果 - Sora\"\nurl: \"https://example.com/search?q=Sora\"\n---\n\n# 検索結果\n...",
  "screenshot": "iVBORw0KGgoAAAANSUhEUgA...",
  "actionLogs": [
    { "step": 1, "type": "fill", "target": "input[name='q']", "success": true, "elapsedMs": 42 },
    { "step": 2, "type": "click", "target": "検索", "success": true, "elapsedMs": 115 },
    { "step": 3, "type": "wait", "target": ".results-container", "success": true, "elapsedMs": 620 },
    { "step": 4, "type": "scroll", "target": undefined, "success": true, "elapsedMs": 510 }
  ],
  "renderedWithBrowser": true
}

② 有状态多轮对话会话（面向交互式聊天）

• 第 1 轮（创建会话 & 打开页面）:

{
  "url": "https://example.com/login",
  "createSession": true,
  "actions": [
    { "type": "fill", "selector": "#username", "text": "myuser" }
  ],
  "extract": { "screenshot": true }
}

（响应中会返回 "sessionId": "sess_a1b2c3d4"）

• 第 2 轮（在已打开的页面中继续操作）:

{
  "sessionId": "sess_a1b2c3d4",
  "actions": [
    { "type": "fill", "selector": "#password", "text": "mypassword" },
    { "type": "click", "text": "ログイン" },
    { "type": "wait", "selector": "#dashboard" }
  ],
  "extract": { "markdown": true }
}

• 第 3 轮（结束会话 & 清理资源）:

{
  "sessionId": "sess_a1b2c3d4",
  "closeSession": true
}

（※ 如果操作中断超过 5 分钟，也会通过自动超时安全释放内存）

3.4 集成深度搜索 (POST /search) & Web 搜索 (POST /search/web)

• 深度搜索请求 (POST /search):

{
  "query": "2026年 AI 最新トレンド",
  "limit": 5,
  "scrapeContent": true,
  "includeRealtime": true,
  "updated": "week",
  "formats": ["markdown"]
}

• 以 HTML 格式获取时:

{
  "query": "React 19 新機能",
  "formats": ["html"]
}

• 仅提取重要高亮时（Token 节省模式）:

{
  "query": "React 19 新機能 変更点",
  "extractHighlights": true
}

• Web 搜索请求 (POST /search/web):

{
  "query": "新商品 発売情報",
  "includeDomains": ["example.com", "news.example.org"],
  "excludeDomains": ["spam.example.com"],
  "updated": "week"
}

3.4.1 站点地图探索 (POST /map)

探索指定域名的 sitemap.xml 或内部链接，提取站点内的全部 URL 列表。

• 请求:

{
  "url": "https://example.com",
  "limit": 200,
  "includeSubdomains": false
}

3.4.2 子页面递归爬取 (POST /crawl & POST /crawl/stream)

从指定 URL 开始递归遍历下级页面，批量收集多个页面的 Markdown/HTML/图片/结构化数据。支持通过 includePatterns / excludePatterns 进行 Glob 通配符过滤。

• 请求（批量获取）:

{
  "url": "https://example.com/docs",
  "maxPages": 20,
  "maxDepth": 2,
  "includePatterns": ["/docs/**", "/guide/*"],
  "excludePatterns": ["/tag/**", "*.pdf"],
  "formats": ["markdown", "jsonLd", "images"]
}

• SSE 流式推送 (POST /crawl/stream)：每获取一个页面，即通过 Server-Sent Events 实时推送（start -> page -> done）。

3.5 图片・视频・新闻・知惠袋・联想搜索

• 图片搜索 (POST /search/image)：{ "query": "富士山", "limit": 10 }

• 视频搜索 (POST /search/video)：{ "query": "简单 菜谱", "limit": 10 }

• 新闻搜索 (POST /search/news)：{ "query": "AI 机器人", "limit": 10 }

• 知惠袋 Q&A (POST /search/chiebukuro)：{ "query": "编程 初学者", "limit": 10, "status": "solved" }

• 关键词补全 (POST /search/suggest)：{ "query": "天气", "limit": 10 }

3.6 电车换乘指南 (POST /transit/route)

• 请求:

{
  "from": "東京",
  "to": "新宿",
  "sortBy": "time"
}

• 响应示例:

{
  "source": "transit",
  "from": "東京",
  "to": "新宿",
  "count": 3,
  "routes": [
    {
      "rank": 1,
      "summary": {
        "departureTime": "09:30",
        "arrivalTime": "09:44",
        "durationMinutes": 14,
        "transferCount": 0,
        "fare": {
          "ic": 209,
          "ticket": 210
        },
        "flags": {
          "isFastest": true,
          "isCheapest": true,
          "isEasiest": true
        }
      },
      "sections": [
        {
          "type": "move",
          "line": "ＪＲ中央線快速・高尾行",
          "from": "東京",
          "departureTime": "09:30",
          "to": "新宿",
          "arrivalTime": "09:44"
        }
      ]
    }
  ]
}

3.7 日本全国 天气预报 (POST /weather / GET /weather / GET /weather/:city)

直接解析日本气象厅官方开放数据 API（以及 livedoor 天气兼容格式），完全自主获取日本全国今天・明天・后天的详细气象数据。

本功能优势 (Features & Advantages)

• 完全自主・官方直连（零依赖）：直接从气象厅官方 CDN（jma.go.jp）获取并解析气象数据。

• 全国 1,805 个市区町村的智能自动解析：内置气象厅官方区域定义（area.json）。可从「天童市」「轻井泽」「箱根」「浦安」「别府」等市区町村名或知名地名，以 0ms 速度自动选定负责的气象台地点 ID。也支持不带县名的输入。

• AI 智能体友好的结构化数据：一次性获取 3 天的天气播报、风・浪、预计最高/最低气温（℃）、分时段降水概率（0-6时, 6-12时, 12-18时, 18-24时）、气象台发布的天气概况文（标题・正文）等干净 JSON 数据。

• LRU 缓存实现超高速响应：标准内置 30 分钟内存 LRU 缓存，自动防止对气象厅服务器的不必要重复访问。

• 请求 (POST):

{
  "city": "天童市",
  "days": 3
}

• GET 请求：GET /weather?city=轻井泽&days=2 或 GET /weather/箱根

• 响应示例:

{
  "source": "weather",
  "cityId": "060010",
  "title": "村山 の天気",
  "publishedTime": "2026-08-21T17:00:00+09:00",
  "publicTime": "2026-08-21T17:00:00+09:00",
  "publishingOffice": "山形地方気象台",
  "location": {
    "area": "東北",
    "prefecture": "山形県",
    "city": "天童市"
  },
  "overview": "前線が、日本海から東北地方を通って、日本の東にのびています。村山地方では、夜遅くにかけて雷を伴い激しい雨が降る所がある見込みです。",
  "description": {
    "headline": "",
    "body": "前線が、日本海から東北地方を通って、日本の東にのびています...",
    "text": "..."
  },
  "forecasts": [
    {
      "date": "2026-08-21",
      "dateLabel": "今日",
      "telop": "曇り",
      "detail": {
        "weather": "くもり　所により　夕方　雨　で　雷を伴い　激しく　降る",
        "wind": "北の風　後　南東の風",
        "wave": null
      },
      "temperature": {
        "min": "22℃",
        "max": "31℃"
      },
      "chanceOfRain": {
        "T00_06": "30%",
        "T06_12": "0%",
        "T12_18": "0%",
        "T18_24": "30%"
      },
      "image": "https://www.jma.go.jp/bosai/forecast/img/200.svg"
    }
  ]
}

3.8 Yahoo 实时搜索 & 趋势 (POST /search/realtime / POST /search/trend)

• 实时搜索 (POST /search/realtime)：{ "query": "活动名称", "sort": "popular", "limit": 20, "page": 1 }

  • sort："recent"（按最新排序，默认）或 "popular"（按热门排序 / 按互动量排序）

  • 每条帖子会自动附带统一格式的 publishedTime（ISO 8601 字符串）、author（用户名 + @账号名）、siteName: "X (Twitter)"。

• 飙升趋势 (POST /search/trend)：{ "limit": 20 }

3.9 站点地图 & 爬取 (POST /map / POST /crawl)

• 站点地图 (POST /map)：{ "url": "https://example.com", "limit": 200 }

• 递归爬取 (POST /crawl)：{ "url": "https://example.com/docs", "maxPages": 10 }

4. 安全 & 架构

4.1 Distroless 容器设计

• 基础镜像：gcr.io/distroless/cc-debian12

• 无 Shell・无包管理器：容器内不存在 /bin/sh、apt、curl 等任何组件，攻击者没有夺取 Shell 的余地。

• 最小权限设计：支持非 root 运行，可在 Docker / Podman / Kubernetes 等标准容器环境中安全隔离运行。

4.2 安全 & 性能功能

• 🛡️ 多重 SSRF & DNS Rebinding 防御：

  • 阻断对私有 IP（10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8 等）、CGNAT（100.64.0.0/10）、IPv6 特殊地址、云元数据 IP（169.254.169.254）的内部访问。

  • 通过 dns.promises.lookup 进行预先名称解析，在连接前即时阻断利用域名伪装发起的 DNS Rebinding 攻击。

• ⚡ Single-Flight 缓存（请求中去重）：

  • 当同一 URL 出现并发请求时，共享 Promise 并聚合为一次外部通信。防止惊群效应（缓存雪崩），保护外部服务器和本地资源。

• 🚦 浏览器并发限制 (Concurrency Control)：

  • 通过 SimpleSemaphore 安全控制 Chromium 进程的并发数量（MAX_CONCURRENT_BROWSERS，默认 5）。防止服务器 CPU/内存耗尽。

• 🔒 时间安全认证 & 浏览器会话所有权绑定：

  • API 密钥比对采用 crypto.timingSafeEqual + SHA-256（常数时间比较），防御时序攻击。

  • 将多轮浏览器会话（sessionId）与创建者令牌进行密码学绑定，防止他人劫持会话。

• 🛡️ 任意 JavaScript 执行的安全控制开关 (ALLOW_BROWSER_EVALUATE)：

  • 通过环境变量 ALLOW_BROWSER_EVALUATE=false 或 SAFE_BROWSER_MODE=true，可立即禁用并锁定 /browser/action 中的 evaluate 脚本执行。

• 📐 统一 Zod 模式 & OpenAPI 3.0 完全自动生成：

  • REST / MCP 双方统一使用 Zod 模式进行输入验证。

  • /openapi.json 从代码侧的 Zod 模式 100% 动态自动生成 OpenAPI 3.0 规范，完全防止文档偏差。

  • 错误响应采用 { "error": "...", "code": "SSRF_BLOCKED", "status": 403, "retryable": false } 等结构，便于 AI 智能体自我修复和自主判断。

• ⏱️ Jitter 限流 & 真正的 LRU 缓存：

  • 对同一域名的过度连续访问，以 150ms + Jitter（0〜100ms 随机波动）自动抑制。

  • 通过 15〜30 分钟的真正 LRU（访问时更新）缓存和每 10 分钟一次的定期 TTL 清理，完全防止内存泄漏。

5. 致谢・鸣谢 (Acknowledgments)

Sora 的诞生离不开以下优秀的开源项目、公开服务、公共开放数据以及各库作者的卓越贡献。在此致以最诚挚的感谢。

🗾 数据来源 & 灵感来源 (Data Sources & Inspirations)

• 日本气象厅（JMA）开放数据：jma.go.jp

  • 衷心感谢其公开提供日本全国高精度气象预报・防灾数据以及全国 1,800 多个区域定义数据。

• 天气预报 API（livedoor 天气兼容）设计灵感：tsukumijima/weather-api / weather.tsukumijima.net

  • 感谢其 livedoor 天气兼容格式的清晰模式设计以及多年来的社区贡献。

• Yahoo Japan Search MCP：mouseos/Yahoo-Japan-Search-MCP

  • 感谢其 Yahoo! JAPAN 图片・视频・新闻・知惠袋・联想搜索的 MCP 实现。

• norikae-mcp：tysonwu/norikae-mcp

  • 感谢其基于 Yahoo! 路线信息抓取的换乘指南逻辑的设计与实现。

🛠️ 基础开源・库 (Core Libraries & Ecosystem)

• Hono (@yusukebe) — 超高速 Web API 框架 & MCP 集成

• Puppeteer (Google Chrome Team) — 无头 Chromium 控制・隐身操作

• Readability (Mozilla) — 阅读模式文章正文提取引擎

• Cheerio (cheeriojs team) — 高速 DOM 解析 & 元数据提取

• Turndown (Dom Christie) — HTML 转 Markdown 转换器

• LinkeDOM (Andrea Giammarchi) — 超轻量内存 DOM 引擎

• unpdf (UnJS Team) — 高速・轻量 PDF 文本提取

• Model Context Protocol SDK (Anthropic / MCP Team) — 下一代 AI 工具连接标准

6. 免责声明 (Disclaimer)

• 非官方第三方工具：

  • 本软件是为个人开发、学术研究、企业内部使用而开发的非官方（第三方）工具。

• 关于商标：

  • 「Yahoo!」「Yahoo! JAPAN」及各服务名称均为 LINE Yahoo 株式会社的商标或注册商标。本项目与 LINE Yahoo 株式会社无任何关联。

• 遵守使用条款・法律法规：

  • 在访问各外部服务（Yahoo! JAPAN、日本气象厅等）时，请遵守对方服务的使用条款、指南、robots.txt 以及适用法律法规，并由使用者自行负责，避免造成过度负载。

• 责任限制：

  • 因使用本软件而产生的任何损害（包括对方服务的访问限制、数据的完整性・准确性・时效性等），本项目开发者概不负责。

7. 许可证 (License)

本软件根据 Business Source License 1.1 (BSL 1.1 / BUSL-1.1) 发布。

• 可自由・免费使用的用途：

  • 个人开发、学术研究、非商业用途

  • 企业・组织内部面向自有系统的自托管使用（作为支撑自有产品或内部工具的内部后端运行）

  • 源代码的修改・分叉・内部共享

• 禁止事项 (Restriction)：

  • 将本软件（或其衍生作品）作为面向第三方的「付费云服务」「付费抓取 / 搜索 API 服务」「托管服务」提供或转售。

• Change Date（开源转换日期）：

  • 2030年8月1日（或更早）将自动转换为完整的 MIT License。

详情请参阅 LICENSE。

Copyright (c) 2026 ikeno