大模型API实战：构建无尽冬日科技研究规划助手

如果你是 SLG 玩家，大概率经历过《无尽冬日》里这种选择困难：科技研究队列排不下，到底是先点资源产出，还是先提速建造？前置科技没解锁，辛辛苦苦囤的资源又不能乱花。与其靠感觉硬点科技树，不如直接用 AI 做一个“无尽冬日科技研究规划助手”。

这期我们看的是一个偏实战的 AI 应用开发项目：以清源AI 作为开发平台，从零搭建一个能根据玩家当前科技进度、资源存量和阶段目标，自动输出科技研究路线规划的工具。项目本身不是用来做自动点击、自动操作这类违规脚本的，而是把“科技树数据 + 玩家目标 + AI 推理”结合起来，生成可参考的研究优先级建议和分阶段执行计划。

先给结论：如果你有 Python 或 Node.js 基础，熟悉基本的接口调用，跟着这篇文章可以完整跑通一个“AI 开发 + 游戏资料整理 + 批量规划”的小型应用。没有现成的清源AI 平台账号，也可以用其他兼容大模型 API 的平台替换，核心逻辑是一样的。

1. 开发目标与核心能力速览

这套架构本质上是一个典型的“大模型 API + 结构化数据 + 业务逻辑”应用。你不需要训练模型，也不需要部署大模型，重点是把科技树数据整理成模型能理解的结构，再用 Prompt 控制它输出稳定、可执行的规划结果。

2. 需求拆解：无尽冬日科技研究到底要解决什么问题

《无尽冬日》这类 SLG 游戏的科技系统通常有多个研发方向，比如城市发展、资源产出、军事作战、首领成长等。每个科技项一般包含等级上限、前置科技、研究时间、资源消耗、生效效果。玩家的核心诉求是：在有限的时间和资源里，选择当前收益最高的研究路线。

这里要明确一点：清源AI 并不能直接读取你游戏里的实时数据，也不应该去抓取游戏的非公开接口。它的价值在于“基于已知的科技树规则”，做路线规划和优先级分析。

所以我们把需求拆成三个模块。

2.1 科技树数据结构化

第一步是把游戏内的科技项整理成结构化数据。科技项之间有关联关系，比如“前置科技 A 到达 5 级后才能研发 B”。如果这一层数据是散的，AI 推荐时就会出现“推荐了一个根本还没解锁的科技”的尴尬结果。

2.2 目标与约束匹配

玩家目标可以是“前期快速开荒”“中期提升采集效率”“偏向 PVP 打架”等。不同目标对应的科技优先级差异很大。约束条件包括：当前已研究科技、可用资源量、时间预算、研究队列数量。

2.3 AI 规划生成

清源AI 在这里承担的是“策略推理 + 自然语言输出”的能力。它根据结构化的科技树和玩家状态，输出一个带有优先级排序的研究计划，并解释为什么这样推荐。

一句话总结：清源AI 负责智力部分，我们负责把数据喂给它，再把结果包装成可用的工具。

3. 科技树数据建模

规划类 AI 应用最容易翻车的地方，是数据结构设计得不够清晰。模型不是人类，它不会自动理解“城市发展”这个字符串的含义。建议先把科技树整理成 JSON 结构。

下面是一份示例数据模型，字段可以按你的项目需要调整：

{ "tech_id": "city_development_building_1", "name": "基础建设", "branch": "city_development", "max_level": 10, "prerequisites": [], "cost_per_level": { "wood": [500, 800, 1200, 1800, 2600], "coal": [0, 0, 200, 400, 800] }, "duration_per_level": [ "00:30:00", "01:00:00", "02:00:00", "04:00:00", "08:00:00" ], "effects": [ { "type": "build_speed_up", "value_per_level": 0.02 } ] }

字段说明：

• tech_id：唯一标识，用于程序处理。
• branch：所属科技分支，分组筛选时用。
• prerequisites：前置科技列表，每一项可以写成"基础建设:5"，表示该科技到 5 级。
• cost_per_level：每一级消耗的资源。这里用数组表示每一级的消耗量。
• duration_per_level：每一级研究时长。
• effects：该科技带来的效果，方便 AI 判断收益。

实际开发时，这个 JSON 文件会有点大。建议拆成多个文件，按分支存放，然后通过一个加载脚本合并。

import json import pathlib DATA_DIR = pathlib.Path("./data/tech_trees") def load_all_techs(): techs = [] for path in DATA_DIR.glob("*.json"): with open(path, "r", encoding="utf-8") as f: techs.extend(json.load(f)) return techs tech_list = load_all_techs() print(f"已加载科技项数量: {len(tech_list)}")

这里有一个坑：如果你从网上找科技树资料，不能直接用来做结构化数据，必须逐项核对是否是最新版本。游戏版本更新后，科技数值和前置条件可能变化。稳妥的做法是保留一份data_version字段。

4. Prompt 设计方案

Prompt 是这个 AI 规划工具的核心。同样的清源AI 模型，Prompt 写得好不好，输出质量差距非常大。

设计思路是：先给模型设定角色，再给它具体的科技树数据，最后要求它按照固定格式输出规划结果。

SYSTEM_PROMPT = """你是一名《无尽冬日》科技研究规划助手。 你的任务是根据玩家当前的科技进度、资源存量和阶段目标，推荐合理的科技研究方向。 规则： 1. 只能推荐本次提供的科技列表中的科技。 2. 必须考虑前置科技是否满足。 3. 必须结合玩家目标和资源约束。 4. 输出使用 Markdown 列表，包含：优先级、科技名称、目标等级、研究预估时长、理由。 5. 如果玩家资源不足，需要给出资源缺口提示。 6. 如果玩家目标信息不明确，先让玩家补充目标，不要直接给出推荐。 """ USER_PROMPT_TEMPLATE = """玩家当前科技进度：{current_tech} 玩家可用资源：{resources} 玩家阶段目标：{goal} 玩家可投入时间：{time_budget} 科技树数据： {tech_tree_data} """

这里有几个细节需要注意。

第一，{tech_tree_data}不能把整个 JSON 塞进去，会超过上下文长度。建议只传入相关分支的科技项，或者压缩字段，只保留名称、等级上限、前置、时间和主要消耗。

第二，输出格式一定要固定。如果模型偶尔不听话，可以在代码里做一次解析校验，解析失败就自动重试一次。

第三，清源AI 如果支持 agent 模式，你可以把“查询科技树”“计算资源缺口”“生成规划”拆成多个工具函数，让模型自主调用。这样比一次性大 Prompt 更稳定。

5. 开发环境准备

开始写代码之前，先把环境准备干净。下面是通用检查清单。

5.1 基础软件

• Python 3.10 或更高版本。
• Node.js 18 或更高版本，如果前端用。
• Git，用于代码管理。
• 一个支持 Markdown 的编辑器，VS Code 或任意习惯的编辑器均可。

python --version node -v npm -v git --version

5.2 Python 依赖

根据实际使用情况安装。

pip install fastapi uvicorn pydantic requests python-dotenv

如果前端使用 Streamlit，再装：

pip install streamlit

5.3 环境变量

清源AI 的 API Key 不要硬编码在代码里。用环境变量或.env文件管理。

# .env 示例，实际值要自己申请和配置 QINGYUAN_API_KEY=your_api_key_here QINGYUAN_BASE_URL=https://your_qingyuan_api_endpoint QINGYUAN_MODEL=your_model_name

然后在代码里加载：

import os from dotenv import load_dotenv load_dotenv() API_KEY = os.getenv("QINGYUAN_API_KEY") BASE_URL = os.getenv("QINGYUAN_BASE_URL") MODEL = os.getenv("QINGYUAN_MODEL")

这里要特别说明：不同平台的接口地址、模型名称、鉴权方式可能不一样。上面的字段是通用命名，实际开发时一定要以你所使用的清源AI 平台的官方文档为准，不要照搬。

5.4 初始化项目目录

qingyuan-endless-winter/ ├── app/ │ ├── __init__.py │ ├── main.py # FastAPI 入口 │ ├── planner.py # 规划逻辑 │ ├── llm_client.py # 清源AI 接口封装 │ └── schemas.py # 请求和响应模型 ├── data/ │ ├── tech_trees/ # 科技树 JSON 文件 │ └── player_states/ # 玩家状态示例 ├── scripts/ │ └── batch_plan.py # 批量规划脚本 ├── .env └── requirements.txt

目录结构不用完全照抄，但“数据文件、业务逻辑、接口封装”三层分离是必要的，后期维护会轻松很多。

6. 后端服务搭建：核心规划接口

后端采用 FastAPI，主要是因为接口定义简单、自带文档页面，适合快速开发。

6.1 请求和响应数据结构

from pydantic import BaseModel, Field from typing import List, Dict, Optional class PlanRequest(BaseModel): goal: str = Field(..., description="玩家阶段目标，例如：前期开荒") current_tech: Dict[str, int] = Field( default_factory=dict, description="当前科技等级，格式：{'基础建设': 5}" ) resources: Dict[str, int] = Field( default_factory=dict, description="可用资源，格式：{'wood': 10000, 'coal': 5000}" ) time_budget_hours: int = Field(24, description="可投入研究时间，单位小时") branch: Optional[str] = Field(None, description="限定科技分支") class PlanAction(BaseModel): priority: int = Field(..., description="优先级，1 最高") tech_name: str target_level: int estimated_time: str reason: str class PlanResponse(BaseModel): status: str plan: List[PlanAction] resource_gaps: Dict[str, int] = {} raw_text: str = ""

6.2 接口实现

from fastapi import FastAPI from .planner import generate_plan from .schemas import PlanRequest, PlanResponse app = FastAPI(title="无尽冬日科技研究规划助手") @app.post("/api/tech/plan", response_model=PlanResponse) def create_plan(request: PlanRequest): result = generate_plan(request) return result

重点是generate_plan的逻辑：准备科技树数据，组装 Prompt，调用清源AI 模型接口，再解析输出。

from .llm_client import chat_with_qingyuan from .schemas import PlanRequest, PlanResponse def generate_plan(request: PlanRequest): tech_tree_data = load_tech_tree_by_branch(request.branch) user_prompt = USER_PROMPT_TEMPLATE.format( current_tech=request.current_tech, resources=request.resources, goal=request.goal, time_budget=request.time_budget_hours, tech_tree_data=tech_tree_data ) raw_text = chat_with_qingyuan(SYSTEM_PROMPT, user_prompt) actions = parse_plan_output(raw_text) resource_gaps = compute_resource_gaps(request, actions) return PlanResponse( status="ok", plan=actions, resource_gaps=resource_gaps, raw_text=raw_text )

parse_plan_output是工作量比较大的地方。模型输出 Markdown 列表时，需要正则或字符串解析把它转成结构化对象。如果你的 Prompt 控制得足够稳定，可以用 JSON 输出模式，让模型直接返回 JSON 数组。

7. 清源AI 接口调用封装

清源AI 的接入方式要严格按官方文档来。这里给一个通用的大模型 HTTP 调用模板，接口路径和参数需要替换为实际平台支持的格式。

import requests import os class QingyuanClient: def __init__(self): self.api_key = os.getenv("QINGYUAN_API_KEY") self.base_url = os.getenv("QINGYUAN_BASE_URL") self.model = os.getenv("QINGYUAN_MODEL") def chat(self, system_prompt: str, user_prompt: str) -> str: url = f"{self.base_url}/chat/completions" headers = { "Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json" } payload = { "model": self.model, "messages": [ {"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt} ], "temperature": 0.3 } response = requests.post(url, headers=headers, json=payload, timeout=120) response.raise_for_status() data = response.json() return data["choices"][0]["message"]["content"]

几点经验：

• temperature设置为 0.3 左右，让输出更稳定。规划类任务不需要太多创造性。
• 超时时间不要设置太短，长文本生成经常要 30 秒以上。建议 120 秒。
• 如果平台支持流式输出，也可以在长任务中开启流式，提升用户体验。
• 接口调用失败时，要做好重试。网络抖动很常见。

import time def chat_with_retry(client, system_prompt, user_prompt, retries=3): for attempt in range(retries): try: return client.chat(system_prompt, user_prompt) except Exception as e: if attempt == retries - 1: raise e time.sleep(2 * (attempt + 1))

8. 前端看板：把推荐结果可视化

命令行能跑通之后，可以加一个简单的 Web 界面。这里推荐 Streamlit，写起来最快，不需要复杂的前端工程。

import streamlit as st from app.planner import generate_plan from app.schemas import PlanRequest st.set_page_config(page_title="无尽冬日科技研究助手", page_icon="📋") st.title("无尽冬日科技研究规划") goal = st.text_input("阶段目标", value="前期开荒优先资源产出") time_budget = st.number_input("可投入时间（小时）", min_value=1, value=24) current_tech_text = st.text_area( "当前科技等级", value='基础建设:5, 资源采集:3' ) resources_text = st.text_area( "可用资源", value='木材:50000, 煤矿:20000' ) if st.button("生成研究规划"): current_tech = {} for item in current_tech_text.split(","): if ":" in item: name, level = item.split(":") current_tech[name.strip()] = int(level.strip()) resources = {} for item in resources_text.split(","): if ":" in item: name, amount = item.split(":") resources[name.strip()] = int(amount.strip()) request = PlanRequest( goal=goal, current_tech=current_tech, resources=resources, time_budget_hours=int(time_budget) ) result = generate_plan(request) st.markdown(result.raw_text)

启动方式：

streamlit run webapp.py

Streamlit 会在本地开一个端口，浏览器访问页面即可。这个界面只适合个人使用，如果要发布给其他玩家，还是建议用 FastAPI 提供接口，再做单独的前端工程。

这里也提一下，如果你有精力，可以把前后端工程化：

• 前端用 Vue 或 React，玩过前端开发的人可以顺手接上。
• 后端增加用户体系，保存多个玩家的科技进度。
• 设计一个任务队列，把批量规划任务异步化。

9. 批量任务：多账号、多目标同时规划

批量任务是这个项目比较实用的功能。比如你有多个游戏区服的存档，或者想一次性对比“开荒路线”“资源流路线”“战斗流路线”，可以用脚本批量生成。

import json import csv from app.planner import generate_plan from app.schemas import PlanRequest def build_batch_requests(): return [ PlanRequest( goal="前期开荒，优先采集和建造速度", current_tech={"基础建设": 3, "资源采集": 1}, resources={"wood": 30000, "coal": 10000}, time_budget_hours=24 ), PlanRequest( goal="中期资源流，提升采集效率和仓库容量", current_tech={"基础建设": 7, "资源采集": 5}, resources={"wood": 80000, "coal": 40000}, time_budget_hours=48 ), PlanRequest( goal="后期战斗，优先兵种属性和出征加成", current_tech={"基础建设": 10, "军事科技": 6}, resources={"wood": 200000, "coal": 150000}, time_budget_hours=72 ) ] def run_batch(): requests = build_batch_requests() results = [] for index, request in enumerate(requests, start=1): print(f"正在生成第 {index}/{len(requests)} 个规划...") result = generate_plan(request) results.append({ "index": index, "goal": request.goal, "status": result.status, "plan": [action.dict() for action in result.plan] }) with open("batch_results.json", "w", encoding="utf-8") as f: json.dump(results, f, ensure_ascii=False, indent=2) print("批量任务完成，结果已保存到 batch_results.json") if __name__ == "__main__": run_batch()

批量任务的核心是不要让单个失败中断整个流程。项目规模大了以后，建议：

• 把run_batch改成异步任务队列，后端慢慢消费。
• 每一条任务记录单独状态，比如pending、running、success、failed。
• 失败的任务自动重试，重试次数限制在 2 到 3 次。
• 输出结果按任务 ID 分开保存，不要全部塞到一个数组里。

import time def run_batch_with_retry(requests, max_retries=2): results = [] for index, request in enumerate(requests, start=1): for attempt in range(max_retries + 1): try: result = generate_plan(request) results.append({"index": index, "success": True, "data": result}) break except Exception as e: if attempt == max_retries: results.append({"index": index, "success": False, "error": str(e)}) else: time.sleep(3) return results

10. 资源占用与性能观察

这个项目不涉及本地大模型推理，所以没有显存压力，也不需要高端显卡。主要性能开销在网络请求和处理时间上。

需要关注三个点。

10.1 模型接口响应耗时

一次规划请求的耗时要看你用的模型复杂度和输入长度。科技树数据裁剪得越精简，响应越快。如果每次请求都要等 60 秒以上，检查是否传入了太多无用的上下文。

10.2 请求并发与速率限制

清源AI 平台一般会对 API 调用频率有限制。批量任务如果一次性发几十个请求，很容易触发频控。建议在批量脚本里加一个time.sleep(1)或使用信号量控制并发数。

import threading import time semaphore = threading.Semaphore(3) def limited_request(request): with semaphore: result = generate_plan(request) time.sleep(1) return result

10.3 进程与端口管理

FastAPI 默认端口是 8000，Streamlit 默认端口是 8501。如果端口被占用，启动时会报错。Windows 和 Linux 上分别可以用下面的命令排查。

# Windows netstat -ano | findstr :8000 # Linux/macOS lsof -i :8000

确认占用后，要么换端口，要么杀掉占用进程。

uvicorn app.main:app --host 127.0.0.1 --port 8001

11. 功能测试与效果验证

开发完成后，不要急着写一堆花哨功能，先把核心链路跑通，再逐步加场景。

11.1 最小可用测试

先测一个最简单的场景：没有前置科技，资源充足，目标是“提升建造速度”。

测试条件：

目标：前期开荒，优先提升建造速度 当前科技：基础建设 3 级 资源：木材 100000，煤矿 50000 时间预算：24 小时

判断标准：

• 返回结果是否给出 3 到 5 个推荐科技项。
• 每个推荐项是否前置条件满足。
• 输出格式是否可解析成结构化 JSON 或 Markdown 列表。
• 研究时长和资源消耗是否在玩家约束范围内。

11.2 边界测试

边界测试比正常测试更重要。

11.3 输出质量评估

AI 规划的输出质量不能只看一次结果。同一个输入多跑几次，看结果是否稳定。不稳定的话，优先调整temperature，或者给 Prompt 增加更明确的“必须输出 JSON 数组”的约束。

{ "plan": [ { "priority": 1, "tech_name": "基础建设", "target_level": 6, "estimated_time": "04:00:00", "reason": "提升建造速度，缩短后续建筑升级时间" } ] }

这里建议加一层解析校验：如果模型返回的不是 JSON，就尝试提取 Markdown 列表；如果两种都失败，就返回错误码，让调用方知道是解析失败而不是规划失败。

12. 常见问题与排查方法

实际开发中，最容易踩的坑不在 AI 本身，而在数据、解析和接口层。

排查的时候，先看日志，再看请求参数，最后看模型返回原文。很多问题不是模型不够强，而是前端把参数传错了。

另外，如果你在开发过程中发现某个科技数值和游戏实际不一致，直接改数据文件即可，不需要改代码。

13. 最佳实践与合规提示

13.1 工程化建议

第一，科技树数据要有版本标记。每次游戏版本更新后，对照官方公告核对这些数值。数据是规划工具的地基，地基错了，AI 推荐得再好也没用。

第二，Prompt 模板和业务代码分离。把 Prompt 放到单独的配置文件里，后续调优不用改代码。

# prompt_config.py PROMPTS = { "system": "...", "user_template": "..." }

第三，设置合理的temperature和max_tokens。规划类任务建议temperature: 0.3，max_tokens根据输出长度设置，避免生成到一半截断。

第四，接口服务要限制访问范围。如果后端部署在服务器上，只监听127.0.0.1，或者加一层简单的 API Key 校验，不要暴露到公网裸奔。

13.2 合规与版权提示

这个项目本质是“基于已知游戏资料做策略分析”，必须注意几点：

• 不要制作任何自动登录、自动点击、模拟操作类的脚本，这类工具违反游戏用户协议，且有封号风险。
• 不要抓取游戏的非公开接口数据，只使用公开可查的科技树资料。
• 科技树文案和数值如果来自其他作者的整理帖，要注意版权，最好自己重新整理或标明来源。
• AI 生成的规划建议仅供参考，最终是否采纳由玩家自己判断。
• 不要用这个项目批量注册、批量操控游戏账号。

简单来说，清源AI 在这里是一个“策略分析师”，不是“外挂执行器”。开发过程中保持这个边界，项目才安全。

14. 总结与下一步

清源AI 开发教程落到“无尽冬日科技研究”这个场景，本质上是一次典型的 AI 应用开发全流程：需求拆解、数据建模、Prompt 设计、后端接口、前端展示、批量任务、效果评测。跑通这个项目后，你可以把同一套架构复用到其他游戏攻略、文档问答、个性化推荐等场景。

最值得先验证的功能是“科技路线规划接口”。先准备好一份科技树 JSON，再写好 Prompt，最后用 FastAPI 接口接收游戏目标并返回规划列表。只要这条路通了，后面的批量任务和前端看板都只是包装层。

最容易踩的坑有两个：一是科技树数据不完整，导致 AI 推荐错科技；二是模型输出格式不稳定，导致下游解析失败。前者靠数据结构化解决，后者靠 Prompt 约束和解析重试解决。

后续可以继续扩展的方向包括：接入更多游戏数据源、增加玩家历史研究记录分析、把规划结果导出成图片或 PDF、支持多语言输出、甚至做成一个公开的攻略查询服务。

建议先把最小可用版本跑通，再逐步加功能。代码不难，难点在于数据整理和 Prompt 调优。如果你正准备入门 AI Agent 开发，这个项目是一个很好的练手题目。