# 技术规格全案：定魂神珠 • 多模型 AI 神念托管系统 (MULTI-LLM AGENT ORB DELEGATION)
# 自由流放 (FREEEXILE)：2.5D 暗黑古武星宿 ARPG

> **主管责任部门**：系统架构师 (`lead_systems_designer`)、服务器分布式总架构师 (`server_systems_architect`)、文档总架构师 (`lead_documentation_architect`)、安全与反作弊总监 (`security_anticheat_lead`)。  
> **文档版本**：1.0.0-RELEASE  
> **实施状态**：已完整部署落地 (100% 自动化测试通过，126/126 测试全绿)。  
> **适用平台**：服务端权威闭环 (Server-Authoritative Loop)、移动端 WebApp 模拟器、iOS Metal 引擎、多模型 LLM API 网关。

---

## 1. 设计哲学与世界观背景 (DESIGN PHILOSOPHY & LORE)

在 `FreeExile` 的暗黑古武星宿大世界中，修真修士境界高深时可将自身神识淬炼凝结为**神念分身** (Astral Avatar)。当玩家因日常现实生活、学业工作繁忙或需要离线休眠时，可借助秘宝法器**定魂神珠 (Agent Orb)**，将一缕纯粹神念寄附于角色本体之中。

```
                  ┌────────────────────────────────────────┐
                  │          玩家繁忙 / 离线休眠           │
                  └───────────────────┬────────────────────┘
                                      │ 祭出激活
                                      ▼
                        🔮 [法宝：定魂神珠 (Agent Orb)]
                                      │
            ┌─────────────────────────┴─────────────────────────┐
            ▼                                                   ▼
┌───────────────────────┐                           ┌───────────────────────┐
│ 本地毫秒级战术反射层  │                           │ 云端大模型多源战略脑  │
│ (30Hz 逻辑 Tick 循环) │                           │ (3 ~ 5 秒战略决策周期)│
├───────────────────────┤                           ├───────────────────────┤
│ • 气血 <25% 瞬发幻影步│◄──── 实时战术目标指引 ────│ • DeepSeek V3 / R1    │
│ • 自动拾取高阶灵石    │     (优先目标、五行站位、 │ • OpenRouter 全球路由 │
│ • 五行相克最优连招    │      回城补给、避险路线)  │ • OpenAI GPT-4o       │
│ • 濒危自动吞服灵丹    │                           │ • Anthropic Claude 3.5│
└───────────┬───────────┘                           │ • Google Gemini 1.5   │
            │                                       │ • Moonshot AI Kimi    │
            ▼                                       └───────────────────────┘
┌───────────────────────────────────────────────────────────────────────────┐
│               服务端权威引擎与位移仲裁 (SERVER-AUTHORITATIVE)              │
│       (100% 绝对防作弊、位移合法性检验、五行伤害判定、防刷物机制)         │
└───────────────────────────────────────────────────────────────────────────┘
```

### 核心革新与差异化亮点：
1. **非简单低级外挂/自动挂机脚本 (Not a Dull Auto-Clicker)**：角色受到全球顶级大语言模型 (DeepSeek, OpenAI, Claude, Gemini, Kimi, OpenRouter) 的战术思维指引，结合 0ms 本地启发式反应内核 (`LOCAL_TACTICAL`) 智能索敌。
2. **服务端权威验证 100% (Strict Server Authority)**：所有移动路径、出招冷却、灵石拾取均推入服务端校验队列 (`MovementAuthorityEngine`, `CombatEngine`, `ConsignmentVault`)。彻底杜绝内存劫持与数据篡改。
3. **真实离线持久化 (True Offline Persistence)**：即使玩家手机锁屏、退至后台或网络断开，服务端分身仍平稳持续运转。重新上线即可一键查阅《分身神念修炼结算卷轴》（收获经验、灵石详单、斩杀首领数）。
4. **灵石本位闭环制造 (In-Game Crafting Free Loop)**：定魂神珠完全可通过游戏内打怪产出的灵石自行淬炼（开灵石 + 混元石），不搞强制氪金捆绑。

---

## 2. 定魂神珠阶位体系 (AGENT ORB TIERS)

| 物品唯一标识 ID | 法宝名称 | 持续托管时长 | 获取途径 | 特殊核心功效 |
| :--- | :--- | :--- | :--- | :--- |
| `item_agent_orb_tier1` | **定魂灵珠 • 初级** | 2 小时 (7,200s) | 灵石熔炼（5 开灵 + 1 混元）或 诸天宝阁 (200 金宝) | 自动巡航索敌、五行相克技能释放、拾取近身灵石。 |
| `item_agent_orb_tier2` | **定魂神珠 • 中级** | 8 小时 (28,800s) | 灵石熔炼（3 混元 + 1 天命）或 诸天宝阁 (600 金宝) | 气血低于 30% 智能服用灵药；危险时释放 0.25s 幻影步无敌帧。 |
| `item_agent_orb_tier3` | **太虚化身珠 • 无双** | 24 小时 (86,400s)| 灵石熔炼（1 太虚镜 + 5 天命）或 诸天宝阁 (1,500 金宝) | 自动将稀世奇珍存入万界奇珍阁寄售；最优击杀首领与躲避团灭机制。 |

---

## 3. 多模型 LLM 提供商架构 (MULTI-LLM PROVIDER ARCHITECTURE)

系统在 [`server/agent/llm_provider_client.py`](file:///c:/Projects/FreeExile/server/agent/llm_provider_client.py) 中原生提供异步 Python 3.11 强类型集成：

```mermaid
flowchart LR
    A[战场态势感知快照] --> B[LLMProviderClientRouter]
    B -->|模型路由: DEEPSEEK| C[DeepSeek API\ndeepseek-chat]
    B -->|模型路由: OPENROUTER| D[OpenRouter Gateway\nopenrouter.ai/api/v1]
    B -->|模型路由: OPENAI| E[OpenAI API\ngpt-4o-mini]
    B -->|模型路由: ANTHROPIC| F[Anthropic Messages\nclaude-3-5-haiku]
    B -->|模型路由: GEMINI| G[Google Gemini API\ngemini-1.5-flash]
    B -->|模型路由: KIMI| H[Moonshot Kimi API\nmoonshot-v1-8k]
    B -->|网络超时 >2s 或离线| I[本地毫秒级反应内核\n0ms Heuristic]
    C --> J[TacticalActionDecision 决策指令]
    D --> J
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J
```

### 3.1. 战场态势上下文 (Tactical Context Snapshot)
- `player_hp_pct`: 当前血量百分比 ($0.0 \sim 1.0$)。
- `player_mp_pct`: 当前内力百分比 ($0.0 \sim 1.0$)。
- `surrounding_monsters`: 视野九宫格内怪物列表（方位、五行属性、危险等级）。
- `ground_items`: 地面待拾取灵石及装备稀有度。
- `cooldowns`: 绝学技能与幻影步冷却剩余时间。

### 3.2. 结构化决策输出 (Structured Tactical Decision)
```json
{
  "recommended_target_id": 1042,
  "action_type": "SKILL_ATTACK",
  "skill_id": "skill_infernal_slash",
  "movement_vector": {"x": 12.5, "y": -4.2},
  "use_consumable": null,
  "thought_summary": "当前面对木系首领，我方火系绝学造成 1.5 倍克制真伤，立即发动炽炎狂斩。"
}
```

---

## 4. 离线神念收益结算 (DELEGATION HARVEST REPORT)

当玩家重回游戏，系统调用 [`DelegationHarvestReport`](file:///c:/Projects/FreeExile/server/world/agent_orb_service.py) 呈现清晰战报：

```
============================================================
              《分身神念修炼结算卷轴》
============================================================
* 托管法宝   : 太虚化身珠 • 无双 (24小时)
* 实际神行   : 6 小时 42 分 18 秒 (24,138 秒)
* 斩获修为   : +1,842,500 经验值 (EXP)
* 斩杀妖魔   : 1,420 只普通怪 | 18 只精英怪 | 3 位秘境首领
* 灵石收益   :
  - 混元石   : x14
  - 天命丹   : x3
  - 开灵珠   : x52
* 避险次数   : 触发幻影步 i-frame 89 次 | 服用生肌续骨丹 12 次
* 结转状态   : 灵石已归入万界储物袋，神念平安归窍！
============================================================
```

---

## 5. 客户端 UI/UX 呈现与交互规范 (iOS / WEBAPP)

1. **神念视界动效 (Astral Vision Overlay)**：
   - 托管状态激活时，屏幕四角浮现微弱星盘玄光 (`glow-gold`)，角色头顶悬浮一枚流转星宿微光的**定魂法印**。
2. **实时战术思维流 (Live Thought Stream)**：
   - 屏幕右上侧动态展现 AI 实时思考概要，如：`[AI思考: 侦测到木系首领，切火系狂刀进行五行压制]`。
3. **无缝紧急干预 (Zero-Latency Override)**：
   - 玩家触碰屏幕虚拟摇杆、键盘 WASD 或任意技能按键，系统立即暂停神念托管，瞬间移交 100% 手动控制权。