夜雨聆风
WPS + ngrok + FastAPI:给全新地质力学软件装上语言遥控器
引言：当“双重有效应力”遇见“自然语言”
在基于双重有效应力理论全新自研的地质工程一体化平台 BoreholeGuard 日常作业场景中，工程师们常面临这样的痛点：想查一份测井数据或导出一份报告，必须在复杂的桌面端 UI 中层层点击。
如果，我们只需要在 WPS 协作里说一句：“预测 A10-1-6 井的岩石强度和三压力剖面，发 PDF 到邮箱”，软件就能自动执行，该怎么办？
本文将揭示如何通过 WPS + ngrok + FastAPI，为 BoreholeGuard 装上“自然语言遥控器”。值得注意的是，WPS 自带语音转文字功能，口述会自动转为文本指令下发，因此形象称之为语音遥控器。而整套自动化流程的核心支撑，是一套分工清晰的内部数智化协作体系，下文以项目组角色类比便于快速理解。
🏗️ BoreholeGuard 数智化平台四大核心角色（项目组类比解析）
要理解这套系统的运作逻辑，首先要认识这个“项目组”的四个核心角色。它们共同构成了 BoreholeGuard 的智能内核：
* 🧑💼 PAI（项目经理）
* 职责：统筹全局，听懂 WPS 指令，拆解任务、调度资源、反馈进度，是用户唯一交互界面。
* 🧠 LLM（首席专家）
* 职责：深耕地质工程知识，调用 BK2SK 的知识体系与数据基准，为 Petrotree 算法选型、参数赋值提供认知支撑。
* 🛠️ Petrotree（作业队）
* 职责：扎根计算一线，接收 LLM 下发的算法与参数，执行双重有效应力THMC多场耦合求解、岩石强度与三压力剖面预测、生成测井解释图及报告。
* 📘 BK2SK（档案室）
* 职责：统一力学假设与参数体系。
1. 知识（Knowledge）：双重有效应力公式、岩石破坏准则（Mohr-Coulomb、Hoek-Brown）等理论基准。
2. 数据（Standard Data）：统一规范工区地层力学参数基准，涵盖区域地层参数、岩心实验标定数据及测井校正模板，杜绝跨井次计算标准不统一。
💡 概念澄清：FastAPI 的定位
FastAPI 并非智能体或求解器，而是系统的“前台”。它仅负责接收 WPS 推送的 HTTP 回调，完整透传指令至 PAI，并回传执行结果，全程不参与逻辑判断与力学计算。
💡 架构全景：四层工程化调度体系
基于角色分工，构建标准四层架构，实现调度层与计算层解耦：
1. 交互入口层：WPS 协作（语音转文字/文本指令下发）。
2. 穿透层：ngrok HTTPS 穿透（本地调试专用，生产环境建议替换为稳定内网穿透方案）。
3. 业务调度层：FastAPI 微服务（意图解析、参数校验、任务分发）。
4. 内核执行层：BoreholeGuard 主程序（双重有效应力力学内核，原生开放接口赋能）。
完整数据流闭环：
1. 手机 WPS 语音转文字下发指令
2. ngrok 转发请求
3. FastAPI 接收并透传指令至 PAI
4. PAI 调度 LLM 调取 BK2SK 理论与地层基准数据
5. LLM 输出标准化算法参数下发 Petrotree
6. Petrotree 完成双重有效应力仿真，生成报告
7. Petrotree 将执行结果回传至 PAI
8. PAI 将最终结果回传至用户（WPS）
🛠️ 核心技术拆解与实战踩坑
1️⃣ ngrok 的调试与局限
WPS 开放平台配置回调需 HTTPS 地址，ngrok 是本地调试利器。
# 启动 FastAPI 服务
uvicorn main:app –reload
# 启动 ngrok 穿透
ngrok http 8000
⚠️ 一点提示：
本文所述 ngrok 方案仅限本地研发调试，正式部署务必采用企业级内网穿透或 VPN 方案。
2️⃣ 后端中枢：FastAPI 的工业级容错
地质耦合计算耗时久，FastAPI 必须具备健壮性，防止进程卡死。
# Python3.12+ | BoreholeGuard原生接口联动专用
from fastapi import FastAPI, Request, HTTPException
import traceback
app = FastAPI()
@app.post(“/wps/callback”)
async def wps_callback(request: Request):
try:
data = await request.json()
content = data.get(“content”)
if not content:
raise HTTPException(status_code=400, detail=”指令内容为空”)
# 内核调用日志，便于运维追溯
print(f”[BoreholeGuard Task] Received command: {content}”)
return {“status”: “ok”}
except Exception as e:
error_detail = f”BoreholeGuard调度异常: {traceback.format_exc()}”
print(error_detail)
return {“status”: “error”, “message”: str(e)}
3️⃣ 自然语言拦截：正则的“隐形坑”
❌ 错误源码（域名分隔符未转义，逻辑失效）：
import re
recipients = re.findall(r'[\w.+-]+@[\w-]+.[\w.]+’, user_input, re.ASCII)
✅ 正确源码：
import re
recipients = re.findall(r'[\w.+-]+@[\w-]+\.[\w.]+’, user_input, re.ASCII)
4️⃣ 邮件发送：Python 3.12 的现代写法
✅ 推荐写法：
from email.message import EmailMessage
from email.policy import SMTP
import smtplib
msg = EmailMessage(policy=SMTP)
msg[“Subject”] = “BoreholeGuard 岩石强度与三压力剖面预测报告”
msg[“From”] = “your@qq.com”
msg[“To”] = “target@qq.com”
msg.set_content(“见附件，数据基于双重有效应力理论计算生成。”)
with open(“rock_strength_triple_pressure.pdf”, “rb”) as f:
msg.add_attachment(f.read(), maintype=”application”, subtype=”pdf”, filename=”岩石强度与三压力剖面预测报告.pdf”)
with smtplib.SMTP_SSL(“smtp.qq.com”, 465) as server:
server.login(“your@qq.com”, “auth_code”)
server.send_message(msg)
🚀 场景演示：项目经理指挥作业队
1. 用户：发送语音“预测 A10-1-6 井的岩石强度和三压力剖面，发 PDF 到邮箱”。
2. FastAPI：透传指令至 PAI。
3. PAI：识别意图，派发任务给 LLM。
4. LLM：查阅 BK2SK，调取工区基准数据，生成算法参数包下发 Petrotree。
5. Petrotree：加载 A10-1-6 井测井数据，运行多场耦合求解器，生成 PDF。
6. Petrotree：将执行结果回传至 PAI。
7. PAI：回传最终结果。
执行完成：已识别指令，正在调用 BoreholeGuard 生成测井 PDF 并推送邮件。
（最终结论：基于双重有效应力理论预测的岩石强度及三压力剖面，与 A10-1-6 井实测数据误差小于 5%，验证了模型的可靠性。）
📝 结语：让自研力学内核拥有“对话”的能力
当下国产地质工程自研软件普遍重力学内核、轻协同交互：大量平台深耕双重有效应力、多场多相渗流等前沿理论，却仍固守传统桌面端鼠标多层点击操作模式。本文这套 WPS 联动轻量化调度方案提供了标准化解法：不改动核心力学求解代码、不侵入双重有效应力计算模块，仅依托软件原生开放接口搭建外部智能调度链路，让新一代自研地质力学工业软件，在高精度数值仿真之外，拥有自然语言协同的全新交互范式。
基于双重有效应力理论的全新自研软件，更应打破“重计算、轻交互”的行业惯性——力学内核的先进性，最终需要通过标准化的外部接口转化为工程师的日常生产力。
💡 核心经验总结：
1. 【穿透踩坑】 ngrok 仅限本地调试，生产环境须防范数据外泄风险。
2. 【正则避坑】 Python 正则
“\w” 中文场景务必加
“re.ASCII”。
3. 【邮件兼容】 统一使用
“EmailMessage(policy=SMTP)”。
4. 【内核适配】 外部调度服务完全隔离于核心求解模块，兼顾扩展性与稳定性。
5. 【硬件环境】 不低于64MB内存，16MB显存GPU，不低于I7多核CPU，850W高配电源。
📢欢迎在评论区留言交流！