AI Helper 文档中心

主题

配置管理系统 ​

本文引用的源码文件

本文引用的文件

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与并发特性
  8. 国际化与区域设置
  9. 安全与敏感信息管理
  10. 配置加载流程与优先级
  11. 热重载、版本兼容与迁移
  12. 备份、恢复与审计追踪
  13. 模板与最佳实践
  14. 故障排除指南
  15. 结论

简介 ​

本文件面向“AI Helper”双进程架构（Chrome 扩展端 + 本地 Agent 端）的配置管理系统，覆盖以下主题：

  • 配置文件结构与字段含义
  • 环境变量注入与运行时参数处理
  • 配置验证机制、默认值合并与动态更新
  • 国际化配置、语言检测与区域设置管理
  • 配置加载流程图、环境变量映射表与优先级规则
  • 配置热重载、版本兼容性与迁移脚本机制
  • 敏感信息加密、配置备份恢复与审计追踪
  • 配置模板、最佳实践与故障排除

本项目为 MV3 扩展（src/）与独立 Node.js Agent（agent/src/server.js）组成，两端版本号同步为 2.3.1。扩展侧通过本地 HTTP/WebSocket 调用 Agent 能力；Agent 源码修改后需重启进程以生效。

项目结构 ​

配置相关代码主要分布在以下位置：

  • 扩展选项页与状态管理：src/options/config-manager.js、src/options/profile-manager.js
  • 扩展后台配置读取：src/background/config.js
  • Agent 端配置持久化与缓存：agent/src/config.js
  • 密钥混淆工具：src/shared/secret.js
  • 厂商配置模型与 Profile 管理：src/shared/model-profiles.js
  • 国际化：agent/src/i18n.js、src/shared/i18n.js
  • 导入导出：src/options/config-io.js、src/side_panel/export-import.js
graph TB
subgraph "扩展端"
OM["options/config-manager.js<br/>模型/API Base/UI 配置"]
PM["options/profile-manager.js<br/>厂商配置切换"]
BG["background/config.js<br/>后台配置读取"]
MP["shared/model-profiles.js<br/>Profile 数据模型"]
SI["shared/i18n.js<br/>扩展端 i18n"]
SS["shared/secret.js<br/>密钥混淆"]
end
subgraph "Agent 端"
AC["agent/config.js<br/>config.json 读写/缓存/加锁"]
AS["agent/server.js<br/>HTTP 入口/路由"]
AI["agent/i18n.js<br/>Agent 端 i18n"]
end
OM --> BG
PM --> MP
BG --> SS
OM --> SS
AS --> AC
AC --> AI
OM --> SI

图表来源

章节来源

核心组件 ​

  • 扩展端配置管理器（options/config-manager.js）
    • 负责模型下拉列表、上下文窗口设置、API Base URL 管理、图片识别模型管理等 UI 层配置交互与存储同步。
    • 使用 chrome.storage.local 持久化 customModels、imageModels、customApiBases、deletedPresetApiBases 等键。
  • 扩展后台配置读取（background/config.js）
    • 从 chrome.storage.local 聚合默认值与用户配置，返回 ReAct、流式输出、网络访问白名单、完成度校验等结构化配置对象。
    • 对 apiKey 进行解密后再暴露给上层逻辑。
  • Agent 端配置（agent/src/config.js）
    • 基于 ~/.ai-helper-agent/config.json 的 JSON 配置，提供内存缓存、mtime 失效、写互斥锁、字段白名单校验、单字段更新、配对 token 加密落盘等能力。
    • 内置 DEFAULTS 默认值，支持 memoryEmbedding、ragUrlIngest 等高级开关。
  • 密钥混淆（src/shared/secret.js）
    • 统一采用 enc: 前缀 + Base64 的轻量混淆方案，兼容旧明文，写入自动升级。
  • 厂商配置与 Profile（src/options/profile-manager.js、src/shared/model-profiles.js）
    • 提供新建/复制/重命名/删除/切换 Profile 的能力，并联动刷新基础表单字段与下拉列表。

章节来源

架构总览 ​

扩展端通过 options 页面编辑配置，保存到 chrome.storage.local；background 在需要时读取并合并默认值，必要时解密敏感字段。Agent 端通过 HTTP 接口接收请求，按当前语言解析错误消息，并从 config.json 加载配置（带缓存与写锁）。

sequenceDiagram
participant UI as "选项页 UI"
participant CM as "config-manager.js"
participant BG as "background/config.js"
participant ST as "chrome.storage.local"
participant AG as "agent/server.js"
participant AC as "agent/config.js"
UI->>CM : 编辑模型/API Base/上下文窗口
CM->>ST : 保存 customModels/imageModels/customApiBases
BG->>ST : getStoredConfig()
ST-->>BG : 原始配置
BG->>BG : 合并默认值/解密 apiKey
AG->>AC : loadConfig()/updateConfigField()
AC-->>AG : 返回配置对象内存缓存

图表来源

详细组件分析 ​

扩展端配置管理器（options/config-manager.js） ​

  • 功能要点
    • 模型下拉列表增删改查、排序、搜索过滤、上下文窗口 badge 显示与滑杆设置。
    • API Base URL 预设与自定义项管理，记录被删除的预设项以便恢复。
    • 图片识别模型管理与主模型管理类似，但允许删除预设模型。
    • 所有变更均立即持久化到 chrome.storage.local，并同步到当前厂商配置的 models 字段。
  • 关键数据结构
    • customModels: Array<{name, contextWindow}>
    • imageModels: Array<{name, contextWindow}>
    • customApiBases: Array<{url, label}>
    • deletedPresetApiBases: string[]
  • 复杂度与性能
    • 渲染采用全量重建 + 排序，适合中小规模模型列表；若未来增长较大可考虑虚拟滚动或增量更新。
  • 错误处理
    • DOM 元素不存在时提前返回；旧格式数据兼容迁移；清空选中项时回退到首个可用项。
flowchart TD
Start(["打开选项页"]) --> Load["加载 customModels/imageModels/customApiBases"]
Load --> Render["渲染下拉列表/徽标/按钮"]
Render --> UserOp{"用户操作？"}
UserOp --> |添加/删除/修改| Persist["持久化到 storage"]
Persist --> Sync["同步到当前厂商配置 models"]
Sync --> UpdateUI["刷新选中态/徽标"]
UserOp --> |无| End(["等待输入"])

图表来源

章节来源

扩展后台配置读取（background/config.js） ​

  • 功能要点
    • 聚合 ReAct、流式输出、网络访问控制、完成度校验等配置。
    • 对 apiKey 进行解密；对布尔型与数值型字段做缺省值保护。
    • 提供 getChatConfig() 供 side_panel 使用，包含自动压缩阈值等对话行为配置。
  • 默认值合并策略
    • 对 reflection、completionVerification 等嵌套对象采用深合并打底，避免部分覆盖导致字段缺失。
  • 环境变量注入
    • 当前实现未直接读取系统环境变量；如需注入，可在 getStoredConfig 中增加环境变量读取与合并步骤。
flowchart TD
Entry(["getStoredConfig"]) --> Read["读取 chrome.storage.local 键集合"]
Read --> Merge["合并默认值/类型校验/布尔默认"]
Merge --> Decrypt["解密 apiKey"]
Decrypt --> Return(["返回结构化配置对象"])

图表来源

章节来源

Agent 端配置（agent/src/config.js） ​

  • 功能要点
    • 基于 ~/.ai-helper-agent/config.json 的 JSON 配置，提供内存缓存、mtime 失效、写互斥锁、字段白名单校验、单字段更新、配对 token 加密落盘。
    • 内置 DEFAULTS 默认值，支持 memoryEmbedding、ragUrlIngest 等高级开关。
    • 自动将 skills/workspace 目录加入 allowedPaths。
  • 配置加载流程
    • 首次启动创建默认配置；存在则根据 mtime 判断是否重新读取；解析失败回退默认值。
    • 磁盘密文 → 内存明文（兼容旧版无 enc: 前缀的明文），落盘前再混淆。
  • 并发与一致性
    • withWriteLock 串行化写操作，防止 TOCTOU 竞态；writeConfigBody 先写后读确保缓存一致。
flowchart TD
LStart(["loadConfig"]) --> Ensure["ensureAgentDir()"]
Ensure --> Exists{"config.json 存在？"}
Exists --> |否| CreateDefault["写入默认配置并缓存"]
Exists --> |是| CheckMtime["检查 mtime 是否变化"]
CheckMtime --> |未变| ReturnCache["返回缓存"]
CheckMtime --> |已变| Parse["读取并解析 JSON"]
Parse --> DecodeSecret["解码 memoryEmbedding.apiKey"]
DecodeSecret --> MergeDefaults["DEFAULTS 与 userConfig 合并"]
MergeDefaults --> AutoAllow["自动追加 skills/workspace 到 allowedPaths"]
AutoAllow --> ReturnCfg["返回配置对象"]

图表来源

章节来源

密钥混淆（src/shared/secret.js） ​

  • 设计要点
    • 采用 enc: 前缀 + Base64 的轻量混淆，非密码学安全，仅防明文一眼可辨。
    • 读取时若无 enc: 前缀视为旧明文原样返回；下次写入自动升级。
  • 使用范围
    • 扩展端 background/config.js 对 apiKey 解密；Agent 端对 memoryEmbedding.apiKey 与 pairing token 进行加解密。

章节来源

厂商配置与 Profile（profile-manager.js、model-profiles.js） ​

  • 功能要点
    • 提供新建/复制/重命名/删除/切换 Profile 的能力，切换即生效。
    • 监听 modelProfiles 与 activeProfileId 变化，实时刷新下拉与基础表单字段。
    • 与 config-manager.js 联动，刷新模型下拉、API Base 选择与上下文窗口徽标。
  • 数据模型
    • profiles: Array<{id, name, apiBase, apiKey, modelName, models}>
    • activeProfileId: string
classDiagram
class ProfileManager {
+initProfileManager()
+refreshProfileDropdown()
+handleProfileSwitch(id)
+handleProfileNew()
+handleProfileDuplicate()
+handleProfileRename()
+handleProfileDelete()
}
class ConfigManager {
+renderModelDropdownFromList(models, selectedValue)
+collectModelsFromDropdown()
+updateApiBaseSelection(url)
+updateSelectedCtxBadge(inputId, badgeId, dropdownId)
}
class ModelProfiles {
+getState()
+applyProfile(id)
+createProfile(profile, opts)
+renameProfile(id, name)
+deleteProfile(id)
}
ProfileManager --> ModelProfiles : "CRUD/切换"
ProfileManager --> ConfigManager : "刷新 UI"

图表来源

章节来源

依赖关系分析 ​

  • 扩展端
    • options/config-manager.js 依赖 shared/secret.js 与 shared/model-profiles.js，用于模型与 API Base 管理及 Profile 同步。
    • background/config.js 依赖 shared/secret.js 进行密钥解密。
  • Agent 端
    • agent/config.js 依赖 agent/i18n.js 提供错误消息翻译，依赖 crypto-lite.js 进行密钥混淆。
    • agent/server.js 作为 HTTP 入口，调用 agent/config.js 获取配置。
graph LR
CM["options/config-manager.js"] --> SS["shared/secret.js"]
CM --> MP["shared/model-profiles.js"]
BG["background/config.js"] --> SS
AS["agent/server.js"] --> AC["agent/config.js"]
AC --> AI["agent/i18n.js"]

图表来源

章节来源

性能与并发特性 ​

  • Agent 端配置缓存
    • 使用内存缓存与 mtime 失效，避免频繁 IO；仅在文件变化时重新读取。
  • 写互斥锁
    • withWriteLock 串行化写操作，防止并发覆盖；saveConfig 与 updateConfigField 共用 writeConfigBody。
  • 扩展端渲染
    • 模型下拉全量重建，适合中小规模；若未来增长较大建议引入虚拟滚动或增量更新。

[本节为通用性能讨论，不直接分析具体文件]

国际化与区域设置 ​

  • 扩展端 i18n
    • src/shared/i18n.js 提供 t 函数与订阅机制，用于界面文案动态查询。
  • Agent 端 i18n
    • agent/src/i18n.js 提供 translate 函数，由 server.js 在请求入口处设置当前语言，用于错误消息翻译。
  • 语言检测与区域设置
    • 当前实现未包含浏览器语言检测逻辑；建议在 server.js 入口处根据请求头或扩展侧传入的语言码设置 currentLang。
sequenceDiagram
participant UI as "扩展端 UI"
participant SI as "shared/i18n.js"
participant AS as "agent/server.js"
participant AI as "agent/i18n.js"
UI->>SI : t('settings.xxx')
AS->>AI : setConfigLang(lang)
AS->>AI : translate(lang, 'error.invalidConfigKey', params)

图表来源

章节来源

安全与敏感信息管理 ​

  • 密钥混淆
    • 扩展端与 Agent 端统一使用 enc: 前缀 + Base64 的轻量混淆方案，兼容旧明文，写入自动升级。
  • 文件权限
    • Agent 端 config.json 与 pairings.json 落盘时设置为 0o600，目录 0o700，仅当前用户可访问。
  • 脱敏提示
    • Agent 端 memoryEmbedding.hasApiKey 可用于前端提示“已配置”，对外响应一律经 mask 脱敏。

章节来源

配置加载流程与优先级 ​

  • 扩展端
    • 优先级：用户配置 > 默认值；apiKey 解密后使用；ReAct/流式/网络访问等嵌套对象采用深合并打底。
  • Agent 端
    • 优先级：DEFAULTS < userConfig；memoryEmbedding.apiKey 磁盘密文→内存明文；allowedPaths 自动追加 skills/workspace。
flowchart TD
A["扩展端 getStoredConfig"] --> B["读取 chrome.storage.local"]
B --> C["合并默认值/类型校验"]
C --> D["解密 apiKey"]
D --> E["返回结构化配置"]
F["Agent loadConfig"] --> G{"config.json 存在？"}
G --> |否| H["写入默认配置"]
G --> |是| I["读取并解析 JSON"]
I --> J["解码 memoryEmbedding.apiKey"]
J --> K["DEFAULTS 与 userConfig 合并"]
K --> L["自动追加 allowedPaths"]

图表来源

章节来源

热重载、版本兼容与迁移 ​

  • 热重载
    • Agent 端通过 mtime 检测 config.json 变化，下次 loadConfig 时自动重新读取；无需重启即可生效。
  • 版本兼容
    • 扩展端 imageModels 支持字符串旧格式与对象新格式，加载时自动迁移为新格式。
    • secret.js 兼容旧明文，写入自动升级为 enc: 前缀。
  • 迁移脚本
    • 当前迁移逻辑内嵌于加载流程（如 loadImageModels、decodeSecret），未提供独立迁移脚本；如需批量迁移，可在 build 或安装阶段新增脚本。

章节来源

备份、恢复与审计追踪 ​

  • 备份与恢复
    • 扩展端提供 config-io.js 与 side_panel/export-import.js 用于配置导入导出；可将 customModels、imageModels、customApiBases 等导出为 JSON 文件，便于备份与共享。
  • 审计追踪
    • 当前实现未内置配置变更审计日志；可在 saveConfig/savePairing 等处追加审计记录（如时间戳、操作者、变更字段），并考虑写入独立审计文件或远端服务。

章节来源

模板与最佳实践 ​

  • 配置模板
    • Agent 端 DEFAULTS 可作为最小可用模板；扩展端 PRESET_MODELS/PRESET_API_BASES 可作为预设模板。
  • 最佳实践
    • 始终通过 updateConfigField 更新单字段，避免覆盖其他字段。
    • 对敏感字段使用 encodeSecret/decodeSecret，避免明文落盘。
    • 在扩展端使用 normalizeCustomModels 与 formatContextWindow 保持上下文窗口一致性。
    • 在 Agent 端启用 ragUrlIngest.allowPrivateNetwork=false 且 allowedPrivateHosts 为空时拒绝内网访问，遵循最小权限原则。

[本节为通用指导，不直接分析具体文件]

故障排除指南 ​

  • 常见问题
    • 模型下拉不显示：检查 customModels 是否为空或格式不正确；确认 renderModelDropdownFromList 被调用。
    • API Base 无法选择：确认 addCustomApiBase/removeApiBase 正确调用并触发 saveApiBases。
    • Agent 配置未生效：确认 config.json 已更新且 mtime 变化；必要时重启 Agent 进程。
    • 密钥解密失败：检查 secret.js 的 enc: 前缀是否正确；确认 decodeSecret 未被异常捕获。
  • 调试建议
    • 在 background/config.js 中打印 getStoredConfig 返回值，确认默认值合并与密钥解密结果。
    • 在 agent/config.js 中打印 loadConfig 返回对象，确认 DEFAULTS 与 userConfig 合并结果。

章节来源

结论 ​

本配置管理系统在扩展端与 Agent 端分别实现了稳健的配置加载、默认值合并、敏感信息混淆与缓存机制。通过 Profile 管理、i18n 支持与导入导出能力，覆盖了多厂商配置、国际化与备份恢复场景。Agent 端的 mtime 热重载与写互斥锁提升了可靠性与并发安全性。未来可考虑增强环境变量注入、审计追踪与批量迁移脚本，以满足更复杂的运维需求。