AI Helper 文档中心

主题

通用工具函数库 ​

本文引用的源码文件

本文引用的文件

目录 ​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录：常用函数速查与最佳实践

引言 ​

本文件聚焦“通用工具函数库”的体系化说明，覆盖日期时间处理、字符串处理、DOM 操作封装、数据结构工具、错误处理机制、性能优化策略以及测试覆盖情况。该工具能力并非单一模块，而是分布在共享层、侧边栏、内容脚本与 Agent 测试辅助中，分别承担不同运行环境的通用职责：

  • 共享层提供跨环境的基础工具（节流/防抖、基础格式化、HTML 转义、深拷贝、扩展通信）。
  • 侧边栏工具侧重 UI 展示与交互（时长/Token/聊天时间格式化、属性转义、剪贴板、弹窗定位等）。
  • 内容脚本工具专注页面 DOM 操作（唯一选择器生成、文本高亮、自动等待、富文本填充等）。
  • Agent 测试辅助提供示例级时间格式化与本地化输出，用于验证 MCP 工具行为。

项目结构 ​

下图从“工具能力”视角梳理关键文件及其职责边界：

graph TB
subgraph "共享层"
shared_utils["shared/utils.js<br/>节流/防抖/基础格式化/HTML转义/深拷贝/扩展通信"]
i18n["shared/i18n.js<br/>国际化与翻译注册"]
end
subgraph "侧边栏"
panel_utils["side_panel/utils.js<br/>UI 格式化/转义/弹窗/剪贴板/系统提示词拼接"]
workspace_fmt["side_panel/workspace-manager.js<br/>文件大小/时间格式化/预览类型判断"]
end
subgraph "内容脚本"
page_utils["content/page-utils.js<br/>元素选择器/文本高亮/自动等待/富文本输入"]
end
subgraph "Agent 测试辅助"
mcp_test["agent/test/mcp-test-server.cjs<br/>时间格式化工具示例"]
end
shared_utils --> panel_utils
shared_utils --> page_utils
i18n --> panel_utils
panel_utils --> workspace_fmt
mcp_test -. 示例 .-> shared_utils

图表来源

章节来源

核心组件 ​

本节按能力域归纳工具函数，并给出使用要点与注意事项。

日期时间处理 ​

  • 基础格式化

    • 共享层提供 formatDate，基于浏览器本地化输出中文时间。
    • 侧边栏提供 formatDuration（时长）、formatChatTime（聊天短格式）、formatChatTimeFull（完整格式），均结合语言设置进行本地化。
    • 工作区管理器提供 formatFileSize 与 formatTime，用于文件列表展示。
    • 选项页提供 CPU 时间与运行时长格式化，面向进程监控场景。
    • Agent 测试辅助提供 get_time 工具示例，演示 ISO/Unix/本地化三种输出。

  • 时区与本地化

    • 侧边栏时间格式化通过 getLanguage() 切换中英文显示；共享层 formatDate 固定中文区域。
    • Agent 测试示例显式指定 Asia/Shanghai 时区，体现本地化输出可配置性。

  • 最佳实践

    • 对外展示统一走侧边栏格式化函数，避免散落的 toLocaleString 调用。
    • 对需要稳定解析的时间戳，先校验 isNaN(Date.parse(...)) 再格式化。
    • 对长对话时间，优先使用 formatChatTime，仅在 hover 或详情中使用 formatChatTimeFull。

章节来源

字符串处理 ​

  • 文本截断

    • 共享层提供 truncateText，简单长度截断并追加省略号。
    • 审计日志调试用例中存在更复杂的截断语义（带被截字符数提示），体现业务侧对截断信息的增强需求。

  • HTML 转义与属性转义

    • 共享层与侧边栏均实现 escapeHtml，通过创建临时 div 安全转义。
    • 侧边栏额外提供 escapeAttr，对属性值做更严格的特殊字符替换。

  • 正则表达式封装

    • 内容脚本提供 highlightTextMatches，基于 TreeWalker 仅包裹命中文本节点，避免破坏框架虚拟 DOM 与事件绑定。
    • Markdown 渲染与导出逻辑中包含行内 Markdown 解析的正则链，注意先转义再解析，防止 XSS。

  • 编码解码

    • 共享层未直接提供编解码工具；Agent 端存在轻量加密/解密工具（不在本仓库前端工具集范围内），侧边栏在查询余额时通过共享密钥解密 API Key。

  • 最佳实践

    • 所有用户输入进入 DOM 前必须经过 escapeHtml 或 escapeAttr。
    • 正则匹配需限制最大结果数，避免整页大量包裹导致重排。
    • 对富文本编辑器，优先使用原生 setter 或 insertText，再触发 input/change 事件。

章节来源

DOM 操作封装 ​

  • 元素查询与选择器

    • 内容脚本提供 generateUniqueSelector 与 getElementSelector，根据 id、class、层级生成稳定选择器。
    • 提供 getElementText 与 getElementValue，适配 INPUT/SELECT 等表单元素。

  • 事件绑定与交互

    • 内容脚本提供 autoWaitAfterAction，检测 URL 与 DOM 签名变化，自动等待页面稳定。
    • 侧边栏提供 Toast、输入框高度自适应、下拉弹出框定位、复制剪贴板等交互工具。

  • 样式操作与属性管理

    • 内容脚本提供 highlightTextMatches 与 removeHighlights，安全注入/清理高亮样式。
    • 侧边栏弹窗具备点击外部关闭、锚点状态标记、边界约束等属性管理逻辑。

  • 最佳实践

    • 高亮只包裹文本节点，不触碰元素标签与属性，确保框架可感知。
    • 自动等待采用最小等待 + 连续稳定计数，避免无谓阻塞。
    • 弹窗定位需考虑视口边界与锚点位置，避免溢出屏幕。

章节来源

数据结构工具 ​

  • 深拷贝

    • 共享层提供 deepClone，基于 JSON 序列化/反序列化实现浅兼容深拷贝。
    • 注意：不支持循环引用、函数、Symbol、undefined、Date、RegExp 等特殊对象。

  • 对象合并

    • 国际化模块内部实现 deepMerge，用于合并多语言翻译字典，支持嵌套对象合并与数组不合并。

  • 类型检查与数据验证

    • 共享层未提供通用类型检查工具；Agent 侧 RAG 与记忆服务包含入参校验（如集合 ID 正则、topK 上限、导入体积上限、记忆类型白名单等），可作为后端数据校验参考。

  • 最佳实践

    • 对复杂对象深拷贝，建议引入专用库或自定义结构化克隆方案。
    • 对外部输入一律校验类型与范围，失败快速返回，避免污染下游。

章节来源

错误处理机制 ​

  • 异常捕获

    • 内容脚本高亮包裹使用 try/catch 跳过失效节点，保证批量操作鲁棒性。
    • 侧边栏 DeepSeek 余额查询失败时隐藏余额区块，避免 UI 闪烁。
    • 共享层扩展消息发送封装 Promise，遇到 lastError 返回 null，调用方需判空。

  • 日志记录

    • 侧边栏复制失败通过 logger.error 输出错误；Agent 服务端启动时开启控制台日志输出。

  • 调试信息输出

    • 调试执行器将 CDP 异常描述、返回值过长截断等信息以可读方式返回给调用方。

  • 最佳实践

    • 所有异步网络/存储调用均需 catch 分支，降级或提示用户。
    • 对用户可见的错误信息应本地化，避免暴露原始堆栈。

章节来源

性能优化策略 ​

  • 函数节流与防抖

    • 共享层提供 throttle 与 debounce，适用于滚动、输入、窗口 resize 等高频事件。
    • 审计写入、统计落盘等场景应避免同步写 storage，改为内存聚合 + 定时落盘。

  • 内存优化

    • 避免在循环内重复计算 Token 估算或全量序列化工具定义。
    • 避免将大段 HTML/日志存入 element.dataset，改用内存 Map 缓存。
    • 监听器需成对移除，防止泄漏（如预览面板鼠标/滚轮监听）。

  • 最佳实践

    • 高频事件统一走节流/防抖包装。
    • 大对象缓存与 DOM 属性分离，减少重排重绘。
    • 定时器与轮询需有上限与清理逻辑。

章节来源

架构总览 ​

下图展示工具函数在扩展端与 Agent 端的协作关系，以及关键数据流：

sequenceDiagram
participant UI as "侧边栏界面"
participant PanelUtils as "侧边栏工具"
participant SharedUtils as "共享工具"
participant PageUtils as "内容脚本工具"
participant AgentTest as "Agent 测试辅助"
UI->>PanelUtils : 调用时间/Token/弹窗工具
PanelUtils->>SharedUtils : 复用节流/防抖/HTML转义
PanelUtils->>PageUtils : 必要时联动页面高亮/自动等待
AgentTest-->>PanelUtils : 示例时间格式输出MCP
SharedUtils-->>UI : 扩展通信封装sendMessageToBackground

图表来源

详细组件分析 ​

共享工具模块（shared/utils.js） ​

  • 功能要点

    • 节流/防抖：封装高频事件回调，避免重复执行。
    • 基础格式化：formatDate 输出本地化时间。
    • 字符串工具：truncateText、escapeHtml。
    • 数据结构：deepClone。
    • 扩展通信：getExtensionId、getCurrentTabId、sendMessageToTab、sendMessageToBackground。

  • 复杂度与边界

    • deepClone 为 O(n) 序列化开销，不适用于含函数/Symbol/循环引用的对象。
    • 扩展通信封装 Promise，lastError 时返回 null，调用方需判空。

  • 优化建议

    • 对频繁调用的通信封装，可在上层加缓存或去重。
    • 对大对象深拷贝，建议按需字段拷贝或引入结构化克隆。
flowchart TD
Start(["调用 truncateText"]) --> CheckNull{"是否为空?"}
CheckNull --> |是| ReturnEmpty["返回空字符串"]
CheckNull --> |否| LenCheck{"是否超过最大长度?"}
LenCheck --> |否| ReturnOrig["返回原文本"]
LenCheck --> |是| Truncate["截取并追加省略号"]
Truncate --> End(["返回截断结果"])
ReturnEmpty --> End
ReturnOrig --> End

图表来源

章节来源

侧边栏工具模块（side_panel/utils.js） ​

  • 功能要点

    • UI 格式化：formatDuration、formatChatTime、formatChatTimeFull、formatTokenCount、formatTokenFull。
    • 转义：escapeHtml、escapeAttr。
    • 交互：Toast、输入框高度自适应、下拉定位、复制剪贴板、Token 弹窗。
    • 系统提示词拼接：动态注入命令环境、代理主机、术语定义、任务拆解、长期记忆规则等。

  • 本地化与时间

    • 时间格式依据当前语言（中文/英文）输出不同样式。
    • 弹窗文案通过 t() 获取，支持参数插值。

  • 最佳实践

    • 所有用户可见文案必须走 t()，禁止硬编码。
    • 弹窗定位需考虑视口边界与锚点位置，避免溢出。
    • 网络请求失败需隐藏相关区块，避免 UI 残留。
sequenceDiagram
participant User as "用户"
participant Popup as "Token 弹窗"
participant Utils as "侧边栏工具"
participant Storage as "chrome.storage"
participant API as "DeepSeek 余额接口"
User->>Popup : 点击查看 Token 明细
Popup->>Utils : showTokenPopup(tokenSummary, anchorEl)
Utils->>Storage : 读取 apiBase/apiKey/modelName
Utils->>API : GET /user/balance条件满足时
API-->>Utils : 余额数据或错误
Utils->>Popup : 更新余额区块或隐藏

图表来源

章节来源

内容脚本工具模块（content/page-utils.js） ​

  • 功能要点

    • 选择器生成：generateUniqueSelector、getElementSelector。
    • 文本/值读取：getElementText、getElementValue。
    • 高亮与清理：highlightTextMatches、removeHighlights。
    • 自动等待：getDomSignature、autoWaitAfterAction。
    • 富文本输入：isContentEditableElement、setNativeValue、fillContentEditable。

  • 安全与稳定性

    • 高亮仅包裹文本节点，不修改元素结构与属性，避免破坏框架虚拟 DOM。
    • 自动等待基于 URL 与 DOM 签名变化，兼顾导航与局部刷新。

  • 最佳实践

    • 高亮前清空旧高亮，避免累积。
    • 富文本输入后派发 input/change 事件，确保受控组件感知。
flowchart TD
Start(["调用 highlightTextMatches"]) --> Validate{"根节点与正则有效?"}
Validate --> |否| ReturnZero["返回 0"]
Validate --> |是| Walk["TreeWalker 遍历文本节点"]
Walk --> Match["正则匹配命中区间"]
Match --> Limit{"是否超过最大结果?"}
Limit --> |是| Stop["停止收集"]
Limit --> |否| Collect["收集命中区间"]
Collect --> Apply["反向包裹 span"]
Apply --> Count["统计应用数量"]
Count --> End(["返回实际高亮数"])

图表来源

章节来源

国际化模块（shared/i18n.js） ​

  • 功能要点

    • 翻译查找：t(key, params)，支持点分 key 与参数插值。
    • 语言切换：setLanguage、getLanguage、subscribe。
    • 翻译注册：registerTranslations，支持多模块增量注册。
    • 初始化：initI18n，从 storage 读取偏好并监听变更。
    • DOM 填充：applyI18n，批量填充 data-i18n* 属性。

  • 合并策略

    • deepMerge 递归合并对象，不合并数组，避免覆盖已有翻译。

  • 最佳实践

    • 所有 UI 文案通过 t() 获取，禁止硬编码。
    • 新增文案在对应语言文件中注册，并提供 fallback。

章节来源

Agent 测试辅助（agent/test/mcp-test-server.cjs） ​

  • 功能要点

    • 提供 get_time 工具示例，支持 iso/unix/locale 三种格式。
    • 本地化输出显式指定 Asia/Shanghai 时区，便于验证本地化行为。

  • 最佳实践

    • 测试工具应明确输入参数与输出结构，便于契约测试。
    • 本地化输出需与前端一致，避免两端展示不一致。

章节来源

依赖关系分析 ​

  • 耦合度

    • 侧边栏工具依赖共享工具（节流/防抖/HTML 转义）与国际化模块。
    • 内容脚本工具独立于侧边栏，但可与侧边栏通过消息通道协作。
    • Agent 测试辅助与前端工具无直接依赖，但输出格式应与前端保持一致。

  • 潜在循环依赖

    • 共享工具与国际化模块相互独立，无循环依赖。
    • 侧边栏与内容脚本通过消息通信，避免直接 import 彼此。

  • 外部依赖

    • 扩展 API（chrome.*）在共享工具中被封装，调用方无需关心 lastError。
    • 国际化模块依赖 chrome.storage.local 持久化语言偏好。
graph LR
Shared["shared/utils.js"] --> Panel["side_panel/utils.js"]
I18n["shared/i18n.js"] --> Panel
Panel --> Content["content/page-utils.js"]
Panel -. 消息 .-> Background["background/*"]
AgentTest["agent/test/mcp-test-server.cjs"] -. 契约 .-> Panel

图表来源

章节来源

性能考虑 ​

  • 节流与防抖

    • 高频事件（滚动、输入、resize）统一使用 throttle/debounce。
    • 避免在事件回调中进行昂贵计算或 DOM 全量扫描。

  • 存储与 IO

    • 审计日志与统计写入应改为内存聚合 + 定时落盘，避免每次操作都读写 storage。
    • 大对象缓存与 DOM 属性分离，减少重排重绘。

  • 监听器与定时器

    • 监听器需成对移除，防止泄漏。
    • 定时器与轮询需有上限与清理逻辑，避免常驻内存占用。

  • 代码法优化

    • 循环内避免重复估算 Token 或序列化工具定义。
    • 使用增量扣减与缓存值，降低 CPU 消耗。

章节来源

故障排查指南 ​

  • 常见问题

    • 时间格式为空：检查输入是否为合法 ISO 字符串，先校验 isNaN。
    • 高亮不生效：确认根节点有效、正则已加 g 标志、命中区间非空。
    • 弹窗溢出屏幕：检查定位逻辑是否考虑视口边界与锚点位置。
    • 复制失败：检查 clipboard API 权限，回退到 execCommand 方案。
    • 扩展消息失败：检查 lastError，调用方需判空。

  • 调试建议

    • 使用调试执行器查看 CDP 异常描述与返回值截断信息。
    • 对网络请求失败，记录 HTTP 状态码与响应体摘要。
    • 对存储写入失败，保留脏标并在下一次落盘时重试。

章节来源

结论 ​

本工具函数库以共享层为核心，向上支撑侧边栏 UI 与内容脚本 DOM 操作，向下通过扩展通信与 Agent 端能力协同。其设计强调：

  • 本地化与安全性：所有文案走 i18n，所有用户输入经转义。
  • 性能与鲁棒性：节流/防抖、自动等待、高亮安全包裹、监听器清理。
  • 可扩展性：模块化注册翻译、工具函数职责清晰、契约测试对齐前后端。

建议在后续迭代中继续推进：

  • 引入结构化克隆替代 JSON 深拷贝。
  • 统一时间格式化入口，收敛区域设置。
  • 完善单元测试覆盖，尤其针对边界条件与异常路径。

附录：常用函数速查与最佳实践 ​

  • 日期时间

    • formatDate：基础本地化时间。
    • formatDuration：时长格式化。
    • formatChatTime / formatChatTimeFull：聊天时间短/完整格式。
    • formatFileSize / formatTime：文件列表展示。
    • get_time（Agent 测试）：ISO/Unix/本地化三种输出。

  • 字符串

    • truncateText：简单截断。
    • escapeHtml / escapeAttr：HTML/属性转义。
    • highlightTextMatches：安全高亮命中文本。

  • DOM

    • generateUniqueSelector / getElementSelector：选择器生成。
    • getElementText / getElementValue：表单值读取。
    • autoWaitAfterAction：自动等待页面稳定。
    • setNativeValue / fillContentEditable：富文本输入。

  • 数据结构

    • deepClone：JSON 深拷贝。
    • deepMerge：对象递归合并（i18n 内部）。

  • 错误处理

    • 所有异步调用 catch 分支处理。
    • 用户可见错误本地化，避免暴露堆栈。

  • 性能

    • 高频事件用 throttle/debounce。
    • 避免循环内重复计算与大对象序列化。
    • 监听器与定时器需清理。

章节来源