轻捷 – 客户端核心模块项目细节设计文档(更新)

技术栈概览

1. 架构总览

轻捷采用五层递进式架构处理用户输入，从客户端到云端依次为：L1 契约层、L2 语义层、L3 记忆层、L4 路由层、L5 数据层。核心设计思想是能在近端解决的绝不远端请求——每一层都尝试拦截并解决当前查询，只有本层无法满足时才向下一层流转。这样既保证了响应速度（确定性查询毫秒级返回），又保留了处理复杂查询的能力（通过云端服务兜底）。

数据流向为单向递进：用户输入 → L1 → L2 → L3 → L4 → L5，结果沿原路返回。每一层都可能直接产出最终结果并终止流转，也可能对查询做增强处理后继续向下传递。

2. L1 契约层

L1 运行在客户端主进程中，是用户输入进入系统后的第一道关卡。它遵循纯符号主义，只看字符本身，不做任何语义理解。

• 职责：L1 的工作是通过符号前缀和正则表达式做快速分流。用户输入以 = 开头则标记为计算意图，以 > 开头则标记为系统指令意图，输入内容为纯英文字母则标记为翻译意图，匹配本地文件路径格式则标记为路径意图。以上均未命中时，标记为 UNKNOWN，表示 L1 无法判定，需要交给 L2 做进一步分析。

• 设计原则：L1 的判定必须是确定性的：要么百分百确定意图，要么坦诚地说”我不知道”。它不做概率猜测，不做模糊匹配。这保证了 L1 的判定结果完全可信—— 只要 L1 说这是计算，那就一定是计算，后续层级可以无条件信任这个标签。

当前实现：

= 前缀分流和纯英文正则判定已实现

> 系统指令的框架已搭建但具体指令处理尚未完成，PATH（路径识别）和 APPS（本地应用匹配）的正则规则已设计但暂未启用。

L1 完成意图标记后，将意图标签和处理后的载荷统一传递给 L2。

3. L2 语义层

L2 同样运行在客户端主进程中，是端侧的核心处理引擎。它接收 L1 传来的意图标签和载荷，负责实际的计算执行和语义理解。

职责：对于 L1 已确定的意图，L2 执行对应的处理逻辑。例如收到 CALC意图时调用本地计算引擎求值，收到 SYST 意图时执行系统命令。对于 L1 标记为 UNKNOWN 的输入，L2 尝试通过 NLP 能力做语义分析，识别出更细粒度的意图：天气查询、日期时间、官网直达、下载直达、教育数据、单位换算、翻译等。

每条处理分支执行完毕后，L2 会做一个关键决策：是否需要云端请求。如果本地已经产出了完整结果（如数学计算），则将 remoteEnabled 标记为 false，结果直接返回给渲染进程，整个流程在客户端闭环完成。如果本地无法满足（如翻译需要在线词典、天气需要实时数据），则将 remoteEnabled 标记为 true，附带意图标签和提取到的槽位信息，准备向 L3 流转。

当前实现

L2 目前已实现 CALC 分支的完整处理链路：调用基于 mathjs 的计算引擎，内置多层安全沙箱（函数禁用、字符白名单、关键词黑名单、结构验证、结果校验），计算成功后生成候选项并注册执行动作到 ActionStore，拦截云端请求。SYST、TRAN、UNKNOWN 分支的基础框架已搭建。

L2 尚未实现的是真正的 NLP 能力。当前 L2 本质上是一个 switch-case 分发器，依赖 L1 传来的意图标签做路由。它还不能从”帮我算一加一”中提取数学表达式，也不能从”北京明天天气”中识别出天气意图并提取城市和日期槽位。后续计划接入轻量级 NLP 模型或基于规则的意图分类器，使 L2 能够处理自然语言形式的查询请求，在端侧拦截更多场景。

4. L3 记忆层

L3 运行在客户端本地，位于 L2 和云端之间，是整个架构的缓冲与个性化层。目前处于设计阶段，尚未完全编码实现。

本地缓存引擎

L3 的首要职责是减少重复的云端请求。计划采用 LRU 策略，对云端返回的结果按查询文本做本地缓存。相同或高度相似的查询在 TTL 内直接命中缓存返回，不再发起网络请求。不同意图类型的缓存策略不同：天气类结果 TTL 较短（数据时效性强），教育数据类 TTL 较长（变动频率低），官网链接类可以长期缓存（几乎不变）。

本地用户画像

L3 记录用户的历史点击和使用行为，形成轻量级的偏好模型。例如某用户频繁使用翻译功能，后续翻译类候选项的排序权重自动上调；某用户常搜教育信息，教育类结果优先展示。画像数据仅存储在本地，不上传云端。

后期若一定要有边缘与云服务器之间信息的传动，实际上传至服务器的内容进行脱敏处理，即：只有本地实在理解不了的内容进行云端分析。

插件管理

L3 还承担本地插件的注册与调度职责。插件是可选的能力扩展模块，例如离线词典、本地应用索引等。当某个意图存在已注册的本地插件时，L3 优先调用插件获取结果。命中则直接返回，不请求云端；未命中则将请求继续向 L4 流转。

与上下游的关系

L3 从 L2 接收 SuggestResult。若 remoteEnabled 为 true，L3 先检查缓存和本地插件能否满足。能满足则补充候选项直接返回。不能满足则将请求透传至云端 L4。云端结果返回后，L3 负责写入缓存，并结合用户画像对候选项重新排序，最终通过 IPC 返回渲染进程。

5. L4 路由层

L4 运行在云端 Spring Boot 服务中，是服务端的入口层。目前处于设计阶段，尚未完全编码实现（部分请求接口已实现）。

请求接收

L4 接收客户端发来的请求，包含查询文本和 RemoteHint（意图类型、附加参数）。首先做基本校验：参数完整性检查、请求频率限制、身份认证等，过滤无效或恶意请求。

语义增强

对于部分查询，L4 在路由之前做语义再增强处理（尤其是对客户端程序处理不了的部分内容）。处理信息内容包括实体消歧——次要判断”苹果”在当前语境下是水果还是科技公司；主要是同义词扩展——将”高校”扩展为”大学”和”学院”以提高召回率；查询改写——将口语化的表达转换为结构化的查询条件，便于 L5 执行精确查询。

意图路由

根据 RemoteHint 中的意图字段，L4 将请求分发到对应的 L5 服务模块。TRAN 意图路由至翻译服务，WEATHER 路由至天气服务，EDUC 路由至教育数据服务，LJGW（链接官网） 和 LJXZ （链接下载）路由至链接数据库，OTHERS 路由至通用搜索聚合服务。

结果聚合

当一个查询涉及多个数据源时，L4 负责并行调用多个 L5 服务模块，将各方结果聚合、去重、格式化为统一的候选项结构化后返回客户端。

6. L5 数据层

L5 是系统最底层的数据执行层，负责与具体数据源交互。目前处于设计阶段，数据库表结构有规划，但服务模块尚未完全实现。

数据存储

核心业务数据存储在 MySQL 中，按领域分表：教育数据表存储大学基本信息、录取分数线、专业设置等；链接数据表存储各类官网地址和软件下载链接；翻译词典表存储常用词汇的中英对照。对于高频查询的热点数据，计划引入 Redis 做服务端缓存。

原子查询

L5 的每个服务模块职责单一：接收结构化的查询条件，执行数据库查询，返回原始数据。例如教育数据服务接收学校名称和查询维度（分数线、专业列表、学校简介），返回对应的数据记录。L5 不做排序、不做业务逻辑判断、不做展示格式化，这些职责属于上层。

外部 API 对接

部分实时性数据需要调用第三方 API：天气数据对接气象服务接口，汇率数据对接金融数据接口等。L5 负责封装这些外部调用，对上层屏蔽第三方接口的协议差异和数据格式差异，统一输出结构。

结果返回

L5 将原始数据返回给 L4。L4 聚合格式化后返回客户端。客户端侧由 L3 接收云端结果，写入缓存并结合用户画像重排序，经 L2 组装为最终的候选项列表，通过 L1 编码后经 IPC 发送至渲染进程更新界面。整个返回路径为 ( L5 → L4 → L3 → L2 → L1 )→ UI，与请求路径严格对称。