免费开源的WPS AI插件 察元AI助手:globalSettings：文件与 localStorage 双读策略

摘要

注释说明 PluginStorage 不持久化，因此设置落盘在数据目录 settings.json，并辅以 localStorage 键 NdGlobalSettings。排查「重启丢配置」时应先确认 FileSystem API 是否可用。

关键词

settings.json;持久化;WPS FileSystem

扩展阅读与维护提示

本篇围绕「globalSettings：文件与 localStorage 双读策略」组织材料。仓库内与主题最直接相关的检索词包括：settings.json、持久化、WPS FileSystem。建议在阅读正文所列片段后，用 IDE 全局搜索这些符号，沿 import 与调用栈向上追问「谁在什么时机调用」，而不是只记住单文件路径。

摘要所概括的要点为：注释说明 PluginStorage 不持久化，因此设置落盘在数据目录 settings.json，并辅以 localStorage 键 NdGlobalSettings。排查「重启丢配置」时应先确认 FileSystem API 是否可用。落地到排障时，可把现象粗分为三类交叉验证：配置是否按预期写入持久化介质；WPS COM 上下文是否可用（例如是否缺少 ActiveDocument）；以及网络与证书策略是否拦截了 fetch。本篇涉及的模块通常只覆盖其中一两类，需要与相邻篇目拼成完整拼图。

教程文件名「30-quanshezhi-localStorage-yu-wenjian.md」仅用于导航与排序，不等价于源码模块名。若正文中的行号与本地分支不一致，多半因合并导致行偏移，此时应以函数名、导出名为锚重新检索；团队若维护了生成脚本，可在变更大段源码后重新运行以保持摘录大致对齐。

本文刻意避免对产品能力做营销式承诺：所述行为均以当前仓库可见实现为准。若组织策略要求离线或内网模型，应在网关、证书与代理层收口，而不是假设加载项能绕过浏览器安全模型。

若你同时阅读 docs/chayuan-llm-chain-series，可先对照其中的总体链路图理解「请求从 UI 到 chatApi」的次序，再回到本教程看数据结构、默认值与修改风险面；两者互补，不重复堆砌功能列表。

正文

1. 策略说明与路径

getSettingsPath 拼接数据根目录与 FILE_NAME。

阅读源码摘录时，请把它当作「定位入口」而非完整实现：同一函数可能在其他分支还有早退条件或 try/catch。修改默认行为前，建议用最小文档手工走一遍相关助手或对话框，并观察任务清单与日志中的字段是否与预期一致，再决定是否做数据迁移或配置重置。

// src/utils/globalSettings.js 第1-23行 /** * 全局设置 - 持久化存储 * 注意：WPS PluginStorage 在加载项关闭后不持久化，必须使用文件或 localStorage * 策略：优先文件（数据路径下 settings.json），备用 localStorage（跨会话持久化） */ import { getEffectiveDataDir, joinDataPath, ensureDir, getDefaultDataPath } from './dataPathSettings.js' const FILE_NAME = 'settings.json' const PLUGIN_STORAGE_KEY = 'NdGlobalSettings' const LOCAL_STORAGE_KEY = 'NdGlobalSettings' function getSettingsBaseDir() { return getEffectiveDataDir() || getDefaultDataPath() } function getSettingsPath() { const base = getSettingsBaseDir() if (!base) return null const sep = base.includes('\\') ? '\\' : '/' const part = (FILE_NAME || '').replace(/^[/\\]+/, '').replace(/[/\\]+/g, sep) return base + sep + part }

2. 从文件读取

readFileString 与 ReadFile 两种 API 兼容分支。

阅读源码摘录时，请把它当作「定位入口」而非完整实现：同一函数可能在其他分支还有早退条件或 try/catch。修改默认行为前，建议用最小文档手工走一遍相关助手或对话框，并观察任务清单与日志中的字段是否与预期一致，再决定是否做数据迁移或配置重置。

// src/utils/globalSettings.js 第25-36行 function loadFromFile() { try { const path = joinDataPath(FILE_NAME) || getSettingsPath() if (!path) return null const fs = window.Application?.FileSystem if (!fs?.readFileString && !fs?.ReadFile) return null const raw = fs.readFileString ? fs.readFileString(path) : fs.ReadFile(path) if (!raw) return null return JSON.parse(raw) } catch (e) { return null }