AI Helper 文档中心

主题

RepoWiki 文档站点规划 ​

本文引用的源码文件

本文引用的文件

更新摘要 ​

所做更改

  • 新增“文档中心”导航入口点，提供对 /ai-helper/wiki/ 技术文档站点的直接访问
  • 添加国际化支持（nav-docsite key），支持中英文切换显示"Doc Center"/"文档中心"
  • 增强 VitePress 主题搜索功能，集成 Pagefind 离线搜索引擎和侧边栏导航
  • 更新项目结构总览，反映新的文档站点导航架构
  • 补充文档站点导航增强功能的详细说明

目录 ​

  1. 引言
  2. 项目结构总览
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与运行时约束
  8. 故障排查指南
  9. 结论
  10. 附录：VitePress 迁移实施方案

引言 ​

本项目是一个面向 Chromium 内核浏览器的开源 AI 助手扩展，同时包含一个可选的本地 Node.js Agent 服务。其核心目标是让大语言模型不仅能"聊天"，还能真正操作网页、读写本地文件、执行命令、管理长期记忆与知识库，并通过 MCP 协议和技能系统扩展能力。

从仓库根目录看，项目采用双进程架构：

维度Chrome 扩展端本地 Agent 端
入口manifest.json 声明 Service Worker，实际入口为 src/background/index.jsagent/src/server.js，CLI 入口为 agent/bin/agent.js
包名ai-helperai-helper-agent
版本2.4.0（仓库当前）2.4.0（仓库当前）
通信方式chrome.runtime.sendMessage、chrome.sidePanel、chrome.tabs.sendMessageHTTP REST + WebSocket，默认监听本机地址
主要职责UI、ReAct 推理循环、工具调度、上下文压缩、会话持久化、通知、定时任务文件读写、命令执行、MCP 工具、技能系统、长期记忆、RAG 知识库、安全沙箱

作者提示中强调：安装应以 GitHub Releases 自动构建产物为唯一官方渠道；扩展端与 Agent 端版本号应保持同步；Agent 源码修改后必须重启进程新接口才生效；MV3 Service Worker 存在空闲被终止的生命周期约束；主题使用 CSS Token 体系；i18n 覆盖扩展端 _locales/ 与 agent 端 agent/src/locales；测试体系分两套且不可混跑。

这些约束将直接决定 RepoWiki 文档站点的信息分层、导航结构和读者预期。

章节来源

项目结构总览 ​

仓库不是单一应用，而是"扩展工程 + 独立代理包 + 文档 + 脚本 + 测试"的组合体。最关键的顶层目录如下：

目录或文件作用对 RepoWiki 的意义
src/Chrome 扩展源码，按 background、content、side_panel、options、shared、storage 等职责划分文档应拆分为"侧边栏界面""后台逻辑""内容脚本""配置页""共享模块"
agent/Node.js Agent 包，含 HTTP/WebSocket 服务器、MCP、Skill、RAG、Memory、Security 等子系统文档应作为"本地代理服务"独立章节，并明确与扩展端的边界
docs/英文完整文档、产品宣传、设计规格、商店素材、部署脚本等RepoWiki 不应重复 README 式介绍，而应聚焦可维护的技术参考
scripts/构建、图标生成、主题审计、Pages 部署、Wiki 同步等脚本适合放在"开发与发布流程"或"运维脚本"小节
test/扩展端 vitest 单元测试、Playwright e2e 测试文档需说明测试边界，避免把 unit 和 e2e 混为一谈
agent/test/Agent 端单元测试、集成测试、冒烟测试文档应单独说明 Agent 测试运行方式
.docsite/VitePress 文档站主题和首页源新的文档站构建基础设施
scripts/docsite/RepoWiki 到 VitePress 的转换和脚手架脚本核心技术实现，需要重点文档化
manifest.jsonMV3 清单，声明权限、Service Worker、Side Panel、Content Script、快捷键等是理解扩展生命周期和权限的关键入口
package.json扩展端 npm 脚本、依赖、构建命令文档应引用统一构建入口 npm run build:silent
agent/package.jsonAgent 包元数据、bin 命令、ragDependencies、Node 引擎要求文档应明确 Agent 安装、启动、更新、停止、状态查询命令
graph TB
Root["仓库根目录"]
Src["src/ 扩展源码"]
Agent["agent/ 本地代理包"]
Docs["docs/ 文档与素材"]
Scripts["scripts/ 构建与运维脚本"]
Test["test/ 扩展端测试"]
AgentTest["agent/test/ Agent 端测试"]
Docsite[".docsite/ VitePress 主题"]
DocsiteScripts["scripts/docsite/ 转换脚本"]
Manifest["manifest.json"]
Package["package.json"]
AgentPackage["agent/package.json"]
Root --> Src
Root --> Agent
Root --> Docs
Root --> Scripts
Root --> Test
Root --> AgentTest
Root --> Docsite
Root --> DocsiteScripts
Root --> Manifest
Root --> Package
Root --> AgentPackage

图表来源

章节来源

核心组件 ​

Chrome 扩展端核心组件 ​

扩展端基于 Manifest V3，核心由以下部分组成：

组件路径职责
Service Worker 入口src/background/index.js消息路由、侧边栏控制、保活连接、自动续跑、定时任务恢复、国际化初始化、Agent 客户端接入
ReAct 推理循环src/background/react-loop.js调用 LLM、处理 tool_calls、子任务分解、反思与完成度校验
工具执行器src/background/tool-executor.js内置工具注册、MCP 工具动态注入、RAG 工具注入、命令执行转发
工具预筛选src/background/tool-preselector.js轻量 API 预过滤，减少主模型调用时的工具定义体积
流式控制器src/background/stream-controller.js流式响应、中断、完成信号
通知中心src/background/notifier.js桌面通知、多实例去重
面板可见性判断src/background/panel-visibility.js判断是否需要弹出通知
定时任务src/background/scheduler.jsCron、间隔、一次性任务
本地 Agent 客户端src/background/local-agent-client.js封装 HTTP/WebSocket 调用
存储层src/storage/db.js、src/storage/session-store.js、src/storage/token-store.jsIndexedDB、Session Storage、Token 统计持久化
共享模块src/shared/i18n、日志、主题、模型配置、工具常量等
侧边栏 UIsrc/side_panel/对话、工作区、技能选择、MCP 管理、RAG 管理、导出、搜索等
内容脚本src/content/页面注入、DOM 操作、划词工具栏、Shadow DOM 穿透
Offscreen 文档src/offscreen/MV3 剪贴板兼容实现

章节来源

Agent 端核心组件 ​

Agent 端是一个独立的 Node.js 进程，提供 HTTP REST 与 WebSocket 接口，核心子系统包括：

子系统路径职责
HTTP/WebSocket 服务器agent/src/server.js路由、认证、CORS、请求体解析、文件上传、命令执行、日志、RAG、Skill、MCP、Memory 路由挂载
命令执行引擎agent/src/executor.js异步/同步命令执行、WebSocket 输出流、进程树管理
安全沙箱agent/src/security.js路径白名单、命令分级、平台 Shell 检测
认证agent/src/auth.js配对码、Bearer Token、扩展 ID 绑定
文件回收站agent/src/trash.js软删除、恢复、定期清理
搜索agent/src/search.jsfd / rg 加速的文件与内容搜索
长期记忆agent/src/memory/事实与摘要存储、召回、注入、标签、层级、向量配置
RAG 知识库agent/src/rag/文档解析、嵌入、向量存储、混合检索、依赖安装与恢复
技能系统agent/src/skill/SKILL.md、JSON/YAML 技能加载、工作流执行、模板
MCP 协议agent/src/mcp/MCP Server 注册、Client 管理、JSON-RPC 2.0 转发
日志agent/src/logger.js结构化日志、分类输出、查询
国际化agent/src/i18n.js、agent/src/locales/根据 Accept-Language 选择文案

章节来源

VitePress 文档站核心组件 ​

更新 VitePress 文档站已从计划实施阶段升级为完整实现，包含完整的构建脚本、转换逻辑、主题系统和测试覆盖。

组件路径职责
转换函数scripts/docsite/transform.mjs纯函数转换 repowiki MD（file:// → GitHub blob 链接、目录树 → 侧边栏、文件名空格→-、注入 frontmatter）
脚手架脚本scripts/docsite/scaffold.mjs把转换结果落盘为 VitePress srcDir（复制/改写 config/theme/index.md）
编排脚本scripts/build-docsite.mjs串联四步构建管线：转换 → VitePress 构建 → Pagefind 索引 → 硬校验
主题入口.docsite/theme/index.jsVitePress 主题入口（extends DefaultTheme + mermaid 生命周期）
布局组件.docsite/theme/Layout.vue覆写 nav-searchbar slot 挂搜索按钮
搜索组件.docsite/theme/DocSearch.vuePagefind UI 覆盖层组件（懒加载 pagefind-ui.js/css）
首页源.docsite/home.md文档站首页源（hero + 特性卡片，占位符 由 scaffold 注入）
样式覆盖.docsite/theme/custom.css覆盖层样式微调

章节来源

架构总览 ​

项目的整体架构可以理解为"浏览器扩展 + 本地代理"的双端协作模式。扩展端负责用户交互、推理编排和工具调度；Agent 端负责需要操作系统能力的本地资源访问。

graph TB
subgraph "浏览器扩展"
SP["侧边栏<br/>side_panel.html + src/side_panel/*"]
BG["后台 Service Worker<br/>src/background/index.js"]
CS["内容脚本<br/>src/content/*"]
OS["Offscreen 文档<br/>src/offscreen/*"]
ST["存储层<br/>src/storage/*"]
end
subgraph "本地 Agent 进程"
AG_HTTP["HTTP 服务器<br/>agent/src/server.js"]
AG_WS["WebSocket 命令流"]
AG_SEC["安全沙箱<br/>security.js"]
AG_EXEC["命令执行<br/>executor.js"]
AG_MEM["长期记忆<br/>memory/*"]
AG_RAG["RAG 知识库<br/>rag/*"]
AG_SKILL["技能系统<br/>skill/*"]
AG_MCP["MCP 协议<br/>mcp/*"]
end
subgraph "文档站构建"
TRANS["转换脚本<br/>scripts/docsite/transform.mjs"]
Scaffold["脚手架<br/>scripts/docsite/scaffold.mjs"]
Build["构建编排<br/>scripts/build-docsite.mjs"]
VP["VitePress 站点<br/>docs/wiki/"]
PF["Pagefind 搜索<br/>pagefind/"]
end
SP --> |"chrome.runtime.sendMessage"| BG
BG --> |"chrome.tabs.sendMessage"| CS
BG --> |"Chrome API"| OS
BG --> |"IndexedDB/Storage"| ST
BG --> |"HTTP + WebSocket<br/>127.0.0.1:18910"| AG_HTTP
AG_HTTP --> AG_SEC
AG_HTTP --> AG_EXEC
AG_HTTP --> AG_MEM
AG_HTTP --> AG_RAG
AG_HTTP --> AG_SKILL
AG_HTTP --> AG_MCP
AG_HTTP --> AG_WS
Build --> TRANS
Build --> Scaffold
Scaffold --> VP
VP --> PF

图表来源

核心数据流 ​

用户输入在侧边栏发起后，会进入 Background 的 ReAct 推理循环；如果需要工具，则分发到背景 API、内容脚本、Agent 或 Offscreen 文档；最终结果回写侧边栏，并在必要时触发桌面通知。

sequenceDiagram
participant User as "用户"
participant SidePanel as "侧边栏"
participant Background as "Background Service Worker"
participant ToolExecutor as "工具执行器"
participant Agent as "本地 Agent"
participant ContentScript as "内容脚本"
participant Offscreen as "Offscreen 文档"
User->>SidePanel : "输入提示词"
SidePanel->>Background : "CALL_API"
Background->>ToolExecutor : "工具预筛选 + 注入"
ToolExecutor->>Background : "ReAct 推理循环"
Background->>Background : "LLM 调用 + 流式响应"
alt "需要工具"
Background->>ToolExecutor : "执行工具"
alt "本地文件/命令/MCP/RAG"
ToolExecutor->>Agent : "HTTP/WebSocket"
else "页面操作"
ToolExecutor->>ContentScript : "chrome.tabs.sendMessage"
else "剪贴板"
ToolExecutor->>Offscreen : "MV3 剪贴板桥接"
end
end
Background-->>SidePanel : "API_COMPLETE"
SidePanel-->>User : "渲染结果 + Token 统计"

图表来源

详细组件分析 ​

Service Worker 入口与侧边栏生命周期 ​

src/background/index.js 是扩展后台的核心入口，承担的职责远不止消息路由：

  1. 初始化国际化。
  2. 重建定时任务闹钟。
  3. 注册自动续跑闹钟处理器，用于 Service Worker 被系统回收后恢复长任务。
  4. 清理过期的 ReAct checkpoint，并做数据库自检。
  5. 维护 side panel 保活端口，防止 API 调用期间 SW 被判定空闲。
  6. 处理脱离窗口状态。
  7. 管理侧边栏作用域模式：全局模式与标签页绑定模式。
  8. 管理 AI Helper 标签分组。
  9. 处理插件图标点击、快捷键切换侧边栏。
  10. 维护活跃 tab 镜像、焦点状态、面板打开状态。
  11. 处理通知可见性判断。

特别需要注意的是，代码中对 chrome.* API 大量使用可选链保护，以应对 SW 终止瞬间 API 对象可能已被剥离的情况。这是 MV3 Service Worker 生命周期硬约束的直接体现。

flowchart TD
Start["Service Worker 启动"] --> InitI18n["初始化国际化"]
InitI18n --> RestoreAlarms["恢复定时任务闹钟"]
RestoreAlarms --> AutoResume["注册自动续跑处理器"]
AutoResume --> CleanupCheckpoint["清理过期 ReAct checkpoint"]
CleanupCheckpoint --> Keepalive["注册 keepalive 端口"]
Keepalive --> SidePanelScope["初始化侧边栏作用域"]
SidePanelScope --> TabGroup["初始化标签分组映射"]
TabGroup --> EventListeners["注册事件监听器"]
EventListeners --> Ready["等待用户交互"]

图表来源

章节来源

Agent HTTP/WebSocket 服务器 ​

agent/src/server.js 是 Agent 端的核心，它同时暴露 HTTP REST 接口和 WebSocket 命令输出通道。关键行为包括：

  • 启动时读取配置、设置控制台输出、记录平台信息。
  • 异步初始化搜索工具和 RAG 能力检测。
  • 创建 HTTP 服务器，统一处理 CORS、请求体解析、multipart 文件上传。
  • 区分无需认证的接口（配对、健康检查、关闭）与需要 Bearer Token 认证的接口。
  • 提供 /api/status、/api/status/detail、/api/heartbeat。
  • 提供 /api/pair 配对流程。
  • 提供 /api/shutdown、/api/agent/restart、/api/agent/update。
  • 提供文件上传、流式上传、文件列表、下载、ZIP 打包等能力。
  • 挂载 Memory、Skill、MCP、RAG 等业务路由。
  • 建立 WebSocket 升级通道，用于命令执行输出流。
flowchart TD
Request["HTTP 请求到达"] --> ParseLang["解析 Accept-Language"]
ParseLang --> SetModules["同步语言到各子模块"]
SetModules --> CheckOptions{"OPTIONS 预检?"}
CheckOptions --> |是| AllowCORS["返回允许头"]
CheckOptions --> |否| ParseURL["解析 URL"]
ParseURL --> PublicRoutes{"公开接口?"}
PublicRoutes --> |是| HandlePairOrStatus["配对 / 状态 / 关闭"]
PublicRoutes --> |否| AuthCheck{"Bearer Token 有效?"}
AuthCheck --> |否| Return401["返回未认证"]
AuthCheck --> |是| RouteHandler["业务路由处理"]
RouteHandler --> Response["JSON 响应"]

图表来源

章节来源

工具执行与 MCP 动态注册 ​

扩展端的工具执行器不仅管理内置工具，还负责从 Agent 动态加载 MCP 工具、RAG 工具，并对 MCP schema 进行压缩，避免每次 LLM 调用都携带过多描述。

关键设计点：

  • 跟踪正在运行的 Agent 命令，以便用户取消时关闭 WebSocket。
  • 跟踪已取消会话，避免 onclose/onerror 竞态导致误判。
  • MCP 工具 ID 集合与元数据映射用于去重和服务级开关。
  • MCP description 最大长度、schema 嵌套深度、参数数量限制用于控制 prompt 体积。
  • MCP 加载过程有互斥锁，防止并发 load/unload。
classDiagram
class ToolExecutor {
+getTools()
+loadMcpTools()
+unloadMcpTools()
+executeCommand()
+createExecWebSocket()
+stopCommand()
}
class McpRegistry {
+initializeMcpRegistry()
+getMcpServersStatus()
+getMcpTools()
+callMcpTool()
+connectMcpServer()
+disconnectMcpServer()
}
class AgentClient {
+httpRequest()
+createExecWebSocket()
+isAgentPaired()
}
ToolExecutor --> McpRegistry : "动态注册 MCP 工具"
ToolExecutor --> AgentClient : "调用 Agent HTTP/WebSocket"

图表来源

章节来源

侧边栏与后台的消息传递机制 ​

侧边栏通过 chrome.runtime.connect 建立保活端口，向 Background 上报实例身份，并接收 SW 重启通知。Background 则维护 keepalive 端口映射，用于定向消息和面板断开提醒。

常见故障点包括：

  • SW 被系统回收后，长连接断开，但前端仍认为任务在执行。
  • 面板关闭与任务取消时序不一致，导致误报"面板断开"。
  • 冷启动时焦点镜像尚未补水，通知可见性判断保守弹通知。
  • 快捷键在 SW 刚唤醒时无法获取 active tab，只能降级处理。
sequenceDiagram
participant Panel as "侧边栏"
participant Port as "keepalive 端口"
participant BG as "Background"
participant State as "state.js"
Panel->>Port : "chrome.runtime.connect"
Port->>BG : "keepalive 连接"
BG->>State : "registerKeepalivePort(sessionId)"
Panel->>BG : "KEEPALIVE_IDENTITY"
BG->>State : "setKeepaliveIdentity(sessionId, identity)"
BG-->>Panel : "HOST_TAB_RESOLVED"
Note over BG,Panel : "SW 重启时发送 SW_RESTARTED"

图表来源

章节来源

VitePress 文档站转换管线 ​

更新 VitePress 文档站转换管线已完整实现，取代原有的概念规划。

转换函数 (scripts/docsite/transform.mjs) ​

转换函数是纯函数实现，负责将 repowiki Markdown 转换为 VitePress 格式：

函数功能输入输出
convertFileLinks将 file:// 链接转换为 GitHub blob 链接Markdown 文本转换后的 Markdown
wrapCiteBlock将 <cite> 块包裹为 VitePress details 容器Markdown 文本带折叠块的 Markdown
sanitizeName文件名空格转连字符字符串规范化名称
extractFrontmatter提取标题和描述Markdown 文本frontmatter 对象
injectFrontmatter注入 frontmatter 头部Markdown 文本 + frontmatter带 frontmatter 的 Markdown
planPage计算页面路径和源路径相对路径页面规划对象
buildTree构建目录树结构文件路径数组树形结构
buildSidebar生成 VitePress 侧边栏配置树结构 + 顶层顺序侧边栏数组
transformDocument全链路转换文档Markdown + 路径映射转换结果
flowchart TD
Input["Repowiki Markdown"] --> ConvertLinks["转换 file:// 链接"]
ConvertLinks --> WrapCite["包裹 cite 块"]
WrapCite --> RewriteMdLinks["重写 Markdown 内部链接"]
RewriteMdLinks --> ExtractFM["提取 frontmatter"]
ExtractFM --> InjectFM["注入 frontmatter"]
InjectFM --> PlanPath["规划页面路径"]
PlanPath --> Output["转换结果"]

图表来源

脚手架脚本 (scripts/docsite/scaffold.mjs) ​

脚手架脚本负责将转换结果布置为合法的 VitePress srcDir：

  1. 收集 repowiki 源文件（至少100篇）
  2. 清空并重建暂存目录 .docsite-src/
  3. 逐篇转换并落盘（含 srcRel 唯一性守卫）
  4. 注入首页版本号
  5. 生成 VitePress 配置和主题
  6. 生成侧边栏和导航
  7. 创建 public/.nojekyll 文件

构建编排脚本 (scripts/build-docsite.mjs) ​

构建编排脚本串联完整的四步构建管线：

  1. 转换阶段：调用 transform.mjs 处理所有 repowiki 文档
  2. 脚手架阶段：调用 scaffold.mjs 布置 VitePress 项目结构
  3. 构建阶段：执行 vitepress build 生成静态站点
  4. 搜索索引：运行 pagefind 生成离线搜索索引
  5. 质量校验：执行 6 项硬校验确保构建质量
  6. 预览模式：支持 --preview 参数启动本地预览

章节来源

文档站点导航增强功能 ​

新增 文档站点导航增强功能提供了统一的"文档中心"入口点，集成了国际化支持和离线搜索能力。

导航入口点 ​

在产品主页 docs/index.html 中新增了"文档中心"导航链接：

  • 导航链接：<a href="/ai-helper/wiki/" data-i18n="nav-docsite">Doc Center</a>
  • 国际化键值：nav-docsite，支持中英文切换
  • 目标地址：/ai-helper/wiki/，指向 VitePress 生成的技术文档站点

国际化支持 ​

导航文本支持中英文国际化：

语言显示文本
英文Doc Center
中文文档中心

搜索系统集成 ​

VitePress 主题集成了 Pagefind 离线搜索引擎：

  • 搜索按钮位于导航栏右侧
  • 支持实时搜索和结果高亮
  • 提供侧边栏导航和面包屑
  • 支持键盘快捷键（ESC 关闭搜索）
flowchart TD
User["用户"] --> Homepage["产品主页<br/>docs/index.html"]
Homepage --> NavLink["导航链接<br/>'文档中心'"]
NavLink --> WikiSite["技术文档站点<br/>/ai-helper/wiki/"]
WikiSite --> SearchBtn["搜索按钮<br/>🔍 搜索"]
SearchBtn --> PagefindUI["Pagefind UI<br/>离线搜索引擎"]
PagefindUI --> Results["搜索结果<br/>侧边栏导航"]

图表来源

章节来源

依赖关系分析 ​

扩展端依赖 ​

扩展端依赖 Chrome Extension API、Vite 构建、ESLint、vitest、Playwright，以及若干第三方库用于文档导出、Markdown 渲染、PDF 处理、Excel 处理等。

graph LR
Pkg["package.json"]
DevDeps["开发依赖"]
RuntimeDeps["运行时依赖"]
Vitest["vitest"]
Playwright["playwright"]
Vite["vite"]
CRXJS["@crxjs/vite-plugin"]
DomPurify["dompurify"]
Marked["marked.min.js"]
PDFJS["pdfjs-dist"]
XLSX["xlsx"]
Docx["docx"]
Pkg --> DevDeps
Pkg --> RuntimeDeps
DevDeps --> Vitest
DevDeps --> Playwright
DevDeps --> Vite
DevDeps --> CRXJS
RuntimeDeps --> DomPurify
RuntimeDeps --> PDFJS
RuntimeDeps --> XLSX
RuntimeDeps --> Docx

图表来源

Agent 端依赖 ​

Agent 端依赖 Node.js >= 18，核心运行时依赖包括 MCP SDK、archiver、ws、xlsx、zod；RAG 相关依赖通过 ragDependencies 字段声明，包括 vectra、transformers、pdf-parse、mammoth、officeparser、cheerio 等。

graph LR
AgentPkg["agent/package.json"]
CoreDeps["核心依赖"]
RagDeps["RAG 依赖"]
Ws["ws"]
Archiver["archiver"]
Zod["zod"]
Xlsx["xlsx"]
MCP["@modelcontextprotocol/sdk"]
Vectra["vectra"]
Transformers["@huggingface/transformers"]
PdfParse["pdf-parse"]
Cheerio["cheerio"]
AgentPkg --> CoreDeps
AgentPkg --> RagDeps
CoreDeps --> Ws
CoreDeps --> Archiver
CoreDeps --> Zod
CoreDeps --> Xlsx
CoreDeps --> MCP
RagDeps --> Vectra
RagDeps --> Transformers
RagDeps --> PdfParse
RagDeps --> Cheerio

图表来源

VitePress 文档站依赖 ​

更新 VitePress 文档站依赖已完整实现。

文档站构建依赖以下开发依赖：

依赖版本用途
vitepress^1.6.4静态站点生成器
pagefind^1.5.2离线全文搜索引擎
mermaid^12.2.0流程图和架构图渲染
vite^8.0.0构建工具
vitest^4.1.10单元测试框架
graph LR
DocsitePkg["文档站依赖"]
VP["vitepress"]
PF["pagefind"]
Mermaid["mermaid"]
Vite["vite"]
Vitest["vitest"]
DocsitePkg --> VP
DocsitePkg --> PF
DocsitePkg --> Mermaid
DocsitePkg --> Vite
DocsitePkg --> Vitest

图表来源

章节来源

性能与运行时约束 ​

Service Worker 生命周期约束 ​

Background Service Worker 可能被 Chrome 在空闲时终止，因此：

  • 长任务需要通过保活端口维持连接。
  • 定时任务和 ReAct checkpoint 需要持久化，以便 SW 重启后恢复。
  • 自动续跑逻辑会在闹钟唤醒 SW 后扫描残留 checkpoint。
  • 所有 chrome API 访问建议使用可选链，避免 SW 终止瞬间抛错。

Agent 进程重启约束 ​

Agent 端支持 /api/agent/restart、/api/agent/update 和 /api/shutdown，但这些操作有防重入和频率限制。更重要的是：Agent 源码修改后必须重启进程，新接口才会生效。这是因为 Node.js 进程已经加载了旧模块，不会热重载。

文件与命令安全 ​

Agent 端对路径和命令做了安全检查，包括：

  • 路径白名单与 realpath 规范化。
  • 命令分级策略。
  • 文件大小限制。
  • 文件回收站。
  • 进程树清理。

主题与 i18n ​

主题使用 CSS Token 体系，支持亮色、暗色、跟随系统三态；暗黑模式经过专项审计。i18n 覆盖两层：扩展端 _locales/ 与 agent 端 agent/src/locales。文档示例应避免缓存写法，确保 UI 名称在渲染时动态查询 i18n。

VitePress 构建约束 ​

更新 VitePress 文档站构建约束已完整实现。

文档站构建有以下约束：

  • Node.js 版本要求 ≥22（ESM 脚本）
  • 构建产物提交到 docs/wiki/ 目录
  • 使用 Pagefind 生成离线搜索索引
  • Mermaid 图表需要在 VitePress 主题中初始化
  • 转换函数必须是纯函数，无文件系统副作用
  • 构建过程包含 6 项硬校验确保质量
  • 最少需要100篇 repowiki 源文档

文档站点导航约束 ​

新增 文档站点导航功能有以下约束：

  • 导航链接必须使用 data-i18n="nav-docsite" 属性
  • 国际化键值必须在 HTML 和 JavaScript 词典中保持一致
  • 搜索功能依赖 Pagefind 资源正确部署到 /ai-helper/wiki/pagefind/
  • 主题组件需要在 VitePress 构建过程中正确编译
  • 移动端需要适配搜索弹窗的响应式布局

章节来源

故障排查指南 ​

侧边栏打不开或关不掉 ​

可能原因：

  • 快捷键未被绑定。
  • SW 冷启动时焦点镜像尚未补水。
  • 标签页绑定模式下 per-tab 启用状态异常。
  • 全局模式与标签页绑定模式切换后分组状态不一致。

排查建议：

  1. 检查 chrome://extensions/shortcuts 是否绑定了快捷键。
  2. 查看 Background 控制台是否有 open sidePanel failed 警告。
  3. 确认当前作用域模式是全局还是标签页绑定。
  4. 如果是标签页绑定模式，尝试切换到全局模式再切回。

章节来源

Agent 连接失败或配对失败 ​

可能原因：

  • Agent 未启动。
  • 端口被占用。
  • 配对码过期。
  • Bearer Token 无效。
  • CORS 被浏览器拦截。

排查建议：

  1. 使用 aha status 或 node agent/bin/agent.js status 检查进程状态。
  2. 检查 /api/status 是否返回 200。
  3. 检查 /api/pair 是否成功。
  4. 确认扩展端已保存正确的 Agent 地址和 token。
  5. 查看 Agent 日志中是否有 auth_missing、auth_invalid、pair_failed。

章节来源

命令执行无输出或卡住 ​

可能原因：

  • WebSocket 连接断开。
  • 命令超时。
  • 命令被安全策略拒绝。
  • 进程树未正确清理。

排查建议：

  1. 检查 Agent 是否仍在运行。
  2. 查看命令执行日志。
  3. 检查命令是否在白名单或灰名单内。
  4. 使用 getRunningProcesses 或 Agent 状态接口查看残留进程。
  5. 重启 Agent 进程。

章节来源

RAG 或 MCP 功能不可用 ​

可能原因：

  • RAG 依赖未安装或 Node 版本不满足。
  • MCP Server 未启用或连接失败。
  • Skill 未加载或 SKILL.md 格式错误。

排查建议：

  1. 检查 /api/status 中 ragAvailable 字段。
  2. 查看 RAG 安装日志。
  3. 检查 MCP Server 配置和连接状态。
  4. 重新加载 Skill。
  5. 确认 Agent 已重启。

章节来源

VitePress 文档站构建失败 ​

更新 VitePress 文档站构建故障排查指南已完善。

可能原因：

  • Node.js 版本低于 22。
  • repowiki 源文件缺失或数量不足（少于100篇）。
  • 转换函数抛出异常。
  • VitePress 配置生成失败。
  • Pagefind 索引生成失败。
  • 构建校验失败（页面数不符、死链残留等）。

排查建议：

  1. 检查 Node.js 版本：node --version
  2. 验证 repowiki 源文件数量：ls -la .qoder/repowiki/zh/content/
  3. 单独运行转换步骤：node scripts/docsite/transform.mjs
  4. 检查构建日志中的具体错误信息
  5. 验证 VitePress 配置是否正确生成
  6. 检查 Pagefind 依赖是否正确安装
  7. 使用 --preview 参数启动本地预览调试

文档站点导航问题 ​

新增 文档站点导航功能故障排查：

可能原因：

  • 导航链接 nav-docsite 键值缺失或不一致
  • Pagefind 资源未正确部署
  • 主题组件编译失败
  • 国际化翻译文件缺失

排查建议：

  1. 检查 docs/index.html 中是否存在 nav-docsite 键值
  2. 验证导航链接是否正确指向 /ai-helper/wiki/
  3. 确认 Pagefind 资源文件存在于 /ai-helper/wiki/pagefind/
  4. 检查 VitePress 主题组件是否正确编译
  5. 查看浏览器控制台是否有 JavaScript 错误
  6. 验证国际化翻译是否正常工作

章节来源

结论 ​

这个项目不是一个简单的聊天侧边栏，而是一个围绕"浏览器自动化 + 本地代理能力"构建的 AI 助手平台。它的价值不仅在于能调用 LLM，更在于能把 LLM 的输出落到真实网页、真实文件系统、真实终端和本地知识库中。

对于 RepoWiki 文档站点来说，最重要的原则是：

  1. 不要重复 README：README 面向用户快速上手，RepoWiki 面向开发者和技术读者深入理解。
  2. 区分扩展端与 Agent 端：两者是独立进程，有独立生命周期、独立依赖、独立测试。
  3. 突出运行时约束：MV3 Service Worker、Agent 进程重启、CORS、配对认证、安全沙箱都是容易踩坑的地方。
  4. 以架构图和流程图为主：复杂系统更适合用 Mermaid 图表达，而不是纯文字。
  5. 保持版本一致性：文档应以仓库当前版本为准，并注明扩展端与 Agent 端版本应同步。
  6. 引导到权威文档：已有英文完整文档和中文文档链接，RepoWiki 应补充结构化的技术参考，而不是复制现有文档。

更新 VitePress 文档站现已完全实现，能够自动生成超过295个文档页面的静态站点，包含完整的构建脚本、转换逻辑、主题系统和测试覆盖。新增 文档站点导航增强功能提供了统一的"文档中心"入口点，集成了国际化支持和离线搜索能力，为用户提供了更好的文档访问体验。

章节来源

附录：VitePress 迁移实施方案 ​

目标 ​

VitePress 迁移方案的目标是将现有的 RepoWiki 文档（132 篇中文 Markdown）构建为 VitePress + Pagefind 静态文档站，产物提交到 docs/wiki/，经现有 GitHub Pages（main/docs）发布到 https://xiweicheng.github.io/ai-helper/wiki/。

技术栈：VitePress（devDep）、Pagefind（devDep，用其 pagefind-ui 现成搜索组件）、mermaid（devDep，ESM 包）、Node ≥22 ESM 脚本、Vitest（test/unit）。

架构：一条本地命令 npm run build:docsite 串联四步：① 纯函数转换 repowiki MD（file:// → GitHub blob 链接、目录树 → 侧边栏、文件名空格→-、注入 frontmatter）到 gitignore 暂存目录 .docsite-src/；② 生成 VitePress 配置与主题（mermaid fence、Pagefind 搜索覆盖层）；③ vitepress build 输出到 docs/wiki/；④ pagefind 生成索引并跑 6 项硬校验。部署完全复用现有 push 链路。

推荐站点结构 ​

graph TB
Home["RepoWiki 首页"]
QuickStart["快速开始"]
Architecture["架构总览"]
Extension["扩展端文档"]
AgentDoc["Agent 端文档"]
Tools["工具与能力"]
Config["配置参考"]
Tests["测试与构建"]
Troubleshoot["故障排查"]
Contributing["贡献指南"]
Home --> QuickStart
Home --> Architecture
Home --> Extension
Home --> AgentDoc
Home --> Tools
Home --> Config
Home --> Tests
Home --> Troubleshoot
Home --> Contributing
Extension --> Background
Extension --> SidePanel
Extension --> ContentScript
Extension --> OptionsPage
Extension --> SharedModules
AgentDoc --> ServerApi
AgentDoc --> Security
AgentDoc --> Executor
AgentDoc --> Memory
AgentDoc --> Rag
AgentDoc --> Skill
AgentDoc --> Mcp

页面职责划分 ​

页面内容范围不应包含的内容
首页项目定位、双进程架构概览、安装入口、文档导航具体代码实现细节
快速开始安装、打开侧边栏、添加 API Key、可选 Agent 安装完整 API 参考
架构总览五层/六层架构、核心数据流、扩展与 Agent 通信契约每个文件的逐行解释
扩展端文档Background、Side Panel、Content Script、Options、Shared、StorageAgent 内部实现
Agent 端文档HTTP/WebSocket API、Security、Executor、Memory、RAG、Skill、MCP扩展端 UI 细节
工具与能力内置工具、MCP 工具、Skill、RAG、长期记忆通用浏览器知识
配置参考manifest 权限、扩展配置、Agent 配置、环境变量用户教程
测试与构建vitest、Playwright、Agent 测试、构建脚本、发布流程业务逻辑实现
故障排查SW 生命周期、Agent 连接、命令执行、RAG/MCP、主题与 i18n抽象理论
贡献指南代码风格、提交流程、文档规范、版本同步用户安装步骤

与现有文档的关系 ​

现有英文完整文档已经覆盖了架构、功能、工具、Agent、配置、状态管理和 FAQ。RepoWiki 不应简单复制，而应：

  1. 将长文档拆解为可独立维护的小节。
  2. 增加更多架构图、流程图、类图和序列图。
  3. 明确哪些内容属于扩展端，哪些属于 Agent 端。
  4. 把"怎么做"和"为什么这样设计"分开。
  5. 把"用户操作"和"开发者实现"分开。
  6. 把"已知约束"和"最佳实践"单独列出。

当前实现状态 ​

更新 VitePress 迁移方案已完全实现：

  • ✅ 转换函数 scripts/docsite/transform.mjs 已完整实现
  • ✅ 单元测试 test/unit/docsite-transform.unit.test.js 已编写（205行测试用例）
  • ✅ 脚手架脚本 scripts/docsite/scaffold.mjs 已完整实现
  • ✅ 首页源 .docsite/home.md 已实现
  • ✅ 完整构建管线 scripts/build-docsite.mjs 已实现
  • ✅ VitePress 主题文件已创建（index.js、Layout.vue、DocSearch.vue、custom.css）
  • ✅ 能够自动生成超过295个文档页面的静态站点
  • ✅ 包含6项构建质量校验
  • ✅ 新增 文档站点导航增强功能，提供统一的"文档中心"入口点
  • ✅ 新增 国际化支持（nav-docsite key），支持中英文切换
  • ✅ 新增 Pagefind 离线搜索引擎集成，支持实时搜索和侧边栏导航

章节来源