graph TD
    Agent[Agent<br/>Reasonix/ClaudeCode] -->|MCP stdio| HS[HyperSpace Server]

    subgraph "Hybrid Engine (核心)"
        HR[HybridRouter] --> TA[TaskAnalyzer<br/>特征分析]
        HR --> HC[HealthChecker<br/>凭据探测]
        HR --> FB[FallbackManager<br/>降级管理]
        HR --> RP[ResultProcessor<br/>结果后处理]

        TA -->|规则匹配| DECISION{路由决策}
        DECISION -->|图片/搜索/规划/长文| DW[DeepSeek Web<br/>原生 Python 客户端]
        DECISION -->|代码/翻译/结构化| DA[DeepSeek API<br/>OpenAI Compat]
        DECISION -->|兜底| ZP[智谱 GLM-4.7-Flash]

        DW -->|PoW 求解 + 流式 SSE| WS[chat.deepseek.com]
        DA -->|API 调用| DS[api.deepseek.com]
        ZP -->|API 调用| ZS[open.bigmodel.cn]
    end

    subgraph "Auth 层"
        WA[web_auth.py<br/>Playwright CDP] -->|提取 Cookie + Bearer| AJ[deepseek_web_auth.json]
        AJ --> DW
    end

    HS -->|auto / force_web / force_api / force_zhipu| HR
    HS -->|legacy modes| LR[旧路由<br/>select_tier + Executor]
    LR --> LF[智谱/DeepSeek API]

# 1. 克隆项目
git clone https://github.com/freerunningkid/HyperSpace.git
cd HyperSpace

# 2. 安装依赖
pip install -e ".[dev]"

# 3. （可选）安装 Playwright + Chromium — 用于提取 DeepSeek Web 登录凭据
pip install playwright
playwright install chromium

# 4. 配置 API Key
cp .env.example .env
# 编辑 .env 填入 ZHIPU_API_KEY（必填）和 DEEPSEEK_API_KEY（推荐）

# 5. 提取 DeepSeek Web 凭据 (可选, 但启用后搜索/规划/识图/长文全部 ¥0)
#    以调试模式启动 Chrome:
#    chrome.exe --remote-debugging-port=9222
#    在 Chrome 中登录 https://chat.deepseek.com
#    然后运行:
python -m hyperspace.hybrid_engine.web_auth --extract

# 6. 验证就绪
python -c "from hyperspace.config import load_config; c=load_config(); print([t for t in c.providers if c.candidates_for(t)])"

{
  "mcpServers": {
    "hyperspace": {
      "command": "python",
      "args": ["path/to/HyperSpace/hyperspace/server.py"],
      "env": { "PYTHONIOENCODING": "utf-8" },
      "autoApprove": ["*"]
    }
  }
}

{
  "mcpServers": {
    "hyperspace": {
      "command": "python",
      "args": ["path/to/HyperSpace/hyperspace/server.py"],
      "env": { "PYTHONIOENCODING": "utf-8" },
      "autoApprove": ["*"]
    }
  }
}

---
[hyperspace] 引擎: deepseek_web/deepseek-chat  规划: (思维链摘要)

HyperSpace/
├── hyperspace/                          # 核心包
│   ├── server.py                        # MCP 服务端（双路径：混合引擎 + 旧路由）
│   ├── config.py                        # 配置加载（YAML + .env）
│   ├── router.py                        # 旧路由判定（保留兼容 legacy mode）
│   ├── executor.py                      # 旧执行引擎（保留兼容 legacy mode）
│   ├── cost.py                          # 成本追踪日志
│   ├── tiers.py                         # Tier 枚举
│   ├── hybrid_engine/                   # 🆕 混合推理引擎（核心创新）
│   │   ├── __init__.py
│   │   ├── task_analyzer.py             # 任务特征分析（关键词/正则）
│   │   ├── health_checker.py            # 服务健康探测（凭据检查 + API 探测）
│   │   ├── hybrid_router.py             # 核心路由决策（8 级优先级 + 降级链）
│   │   ├── deepseek_web_client.py       # 🆕 DeepSeek Web 原生客户端（PoW + SSE 流）
│   │   ├── web_auth.py                  # 🆕 浏览器凭据提取（Playwright CDP）
│   │   ├── result_processor.py          # 结果后处理（思维链提取）
│   │   └── fallback.py                  # 降级管理（指数退避重试）
│   ├── providers/                       # API 调用层
│   │   ├── base.py                      # 协议 + 异常类型
│   │   └── openai_compat.py             # OpenAI 兼容 client
│   └── experimental/                    # 个人实验（严格隔离）
├── config/
│   ├── providers.yaml                   # tier → provider 映射
│   ├── routing.yaml                     # 旧路由规则
│   └── hybrid_config.yaml               # 🆕 混合引擎配置
├── data/
│   ├── hyperspace_cost.log              # 成本日志（gitignored）
│   └── deepseek_web_auth.json           # 🆕 Web 凭据（gitignored）
├── tests/
│   ├── test_router.py                   # 旧路由规则测试（16 用例）
│   ├── test_providers.py                # Provider 异常 + 回退测试（9 用例）
│   └── test_hybrid_engine.py            # 🆕 混合引擎测试（39 用例）
├── docs/
│   └── architecture.md
├── pyproject.toml
├── README.md
└── LICENSE                              # MIT

{"ts":"2026-06-21T11:08:38","provider":"deepseek","model":"deepseek-chat",
 "requested_tier":"cheap_capable","actual_tier":"cheap_capable",
 "prompt_tokens":10,"completion_tokens":2,
 "actual_cost_usd":5e-06,"equivalent_premium_usd":6e-05,"saved_usd":5.5e-05}

python -m hyperspace.summary

# 提取 DeepSeek 登录凭据
# 先在调试模式启动 Chrome:
chrome.exe --remote-debugging-port=9222
# 登录 chat.deepseek.com 后运行:
python -m hyperspace.hybrid_engine.web_auth --extract

# 查看凭据状态:
python -m hyperspace.hybrid_engine.web_auth --status

# 运行全部测试 (202 单元测试, 零网络依赖)
pytest tests/ -v