Khoj Web 客户端全解：浏览器内聊天、搜索、文档上传与手机 PWA 安装
【免费下载链接】khoj Your AI second brain. Self-hostable. Get answers from the web or your docs. Build custom agents, schedule automations, do deep research. Turn any online or local LLM into your personal, autonomous AI (gpt, claude, gemini, llama, qwen, mistral). Get started – free. 
项目地址: https://gitcode.com/GitHub_Trending/kh/khoj
本篇指南基于 Khoj 官方文档 Web 客户端章节，系统讲解 Khoj 的 Web 浏览器客户端：它是 Khoj 的默认客户端，无需任何安装即可在浏览器中完成聊天问答、自然语言搜索和文档上传。文中进一步结合 Web 前端源码 的聊天流式响应、增量搜索去抖、上传文件类型校验和 PWA 清单实现，帮助读者在掌握操作方式的同时理解其底层机制，并能亲手在手机上将 Khoj 安装为 PWA。
一、Web 客户端定位：无需安装的默认客户端
Khoj 的 Web 应用是官方文档中明确指出的默认客户端（"The Khoj web app is the default Khoj client"），使用上不需要任何配置，任何现代浏览器访问即可开始使用，官方托管版本即 Khoj Cloud 服务；自托管部署的用户则直接访问自己的服务器地址。
有一点需要注意：仅靠 Web 客户端可以聊天和问答，但要把本地文件、Obsidian、Notion 等数据源与 Khoj 做共享和同步，仍需要一个桌面端客户端（如 Emacs/Obsidian 插件等，见 客户端总览）。Web 端更适合作为"移动访问 + 轻量问答 + 单文件上传"的入口。
从前端工程结构看，Web 应用是一个独立的 Next.js 工程，位于 src/interface/web，核心依赖在 package.json 中：Next.js 15 + React 18，配合 Tailwind CSS、shadcn/ui 组件库、react-use-websocket（流式聊天）等。构建产物通过 package.json 中的 export 脚本执行 next build 并拷贝到 khoj/interface/built 目录，最终由后端的 Django 应用静态托管——这也是"无需额外安装"的工程原因：前后端部署为同一个服务。
二、核心功能一：Chat（聊天问答）
官方文档将 Chat 能力归纳为三点：
- 更快的答案（Faster answers）：答案可来自你的私有笔记，也可来自公开互联网；
- 辅助创作（Assisted creativity）：在"检索答案"与"生成内容"之间平滑切换；
- 迭代式发现（Iterative discovery）：对笔记进行反复追问、迭代式再探索。
从源码实现看（chat 页面），聊天并非普通 HTTP 请求，而是一套完整的流式会话链路：
会话结束后，前端还会调用 generateNewTitle 基于对话内容自动生成会话标题，便于在历史列表中识别。
三、核心功能二：Search（自然语言搜索）
文档将 Search 能力归纳为两点，均可在源码中得到印证：
- 自然（Natural）：基于 Transformer 类 ML 模型的高级自然语言理解，支持用自然语言提问而非关键词精确匹配；
- 增量（Incremental）：边输入边搜索的 search-as-you-type 体验。
搜索页面 的实现细节：
- 增量去抖：handleSearchInputChange 中，每次输入都会先清除上一个定时器，并以 750 毫秒的 debounce 间隔才真正发起请求，兼顾响应速度与请求开销；
- 请求端点：GET /api/search?q=<query>&client=web，返回结构化结果 { type, additional: {file, source, compiled, heading}, entry, score, "corpus-id" }，其中 source 字段区分结果来自 notion、github 还是本地文件，界面上会渲染对应的来源图标；
- file: 过滤器：搜索框支持 file:"文件名" 语法将结果限定在某个文件内，页面通过正则 file:([^"\\s]*|"[^"]*")? 解析该过滤器，并提供一个文件选择下拉框（文件清单来自 GET /api/content/computer）帮你补全文件名；
- 文件管理：搜索页同时是知识库管理入口，可对已索引文件进行分页浏览（/api/content/files?page=N）、查看全文、下载为纯文本、删除（DELETE /api/content/file）。
四、上传文档：拖拽与回形针两种方式
文档中给出了 Web 端上传文档的两种操作方式（适合在手机上逐份上传）：
两种入口在 chatInputArea 组件 中都有对应实现：
-
输入区容器绑定了 onDragOver / onDragLeave / onDrop 事件处理拖放，拖拽悬停时输入框会呈现高亮动效；
-
回形针按钮点击后触发一个隐藏的 <input type="file" multiple>，其 accept 白名单为：
.pdf,.doc,.docx,.txt,.md,.org,.jpg,.jpeg,.png,.webp,.py,.tsx,.js,.json,.html,.css,.ipynb
即除文本类文档外，图片、代码文件和 Notebook 也可以作为聊天附件随查询一起提交（图片会走视觉理解，文本文件会在发送前读取内容作为上下文）。
选中文件后统一进入 chatFunctions.ts 的 uploadDataForIndexing 函数，该函数定义了可入库索引的文件类型白名单：
| text/org | .org |
| text/markdown | .md |
| text/plain | .txt |
| text/html | .html |
| application/pdf | |
| application/vnd.openxmlformats-officedocument.wordprocessingml.document | .docx |
处理逻辑是：按 MIME 类型或扩展名双重校验，不支持的文件会收集进 badFiles 并提示"以下文件暂不支持"；若全部不支持则提示"No supported files found"；通过校验的文件通过 FormData 逐份读取并提交给后端做解析与向量化。对于浏览器无法给出 MIME 的 .org、.md 等文件，代码会根据扩展名回填正确的 file.type，避免误判。
搜索页中的 "Add Documents" 对话框（同文件中的 UploadFiles 组件）是同一套上传逻辑的另一入口：支持拖放与点击选文件，上传期间显示进度条，完成后自动刷新文件列表。
五、在手机上安装：PWA 流程
Web 文档给出了可选的手机端安装方式——将 Khoj 作为**渐进式 Web 应用（PWA）**安装，获得接近原生 App 的快捷访问体验。官方文档的三步流程如下：
官方文档配了三张分步截图：
 |
 |
 |
该 PWA 行为由 Web 清单文件 驱动，其中与安装体验直接相关的字段包括：
- "display": "standalone"：安装后以独立窗口运行，不显示浏览器地址栏；
- "start_url": "/" 与 "scope": "/"：启动时直接进入应用首页；
- "launch_handler": { "client_mode": ["navigate-existing", "auto"] }：再次点击图标时优先复用已有会话；
- 图标集覆盖 128px 到 1200px 多种尺寸，且包含 purpose: "maskable" 的蒙版图标，保证在安卓不同厂商的负一屏/桌面适配中显示正常；
- screenshots 字段声明了窄屏（手机，419×900）与宽屏（桌面，1260×742）两组安装页预览图，对应"Remember and Plan""Browse and Draw"两个功能场景。
应用的整体页面元数据（标题、图标、manifest 指向 /static/khoj.webmanifest）则定义在 根布局文件 的 metadata 导出中。
六、小结与延伸阅读
| 聊天问答 | 首页输入框，WebSocket 流式输出 | app/chat/page.tsx |
| 自然语言搜索 | Search 页，750ms 增量搜索 + file: 过滤 | app/search/page.tsx |
| 文档上传 | 聊天输入框拖拽 / 回形针 / "Add Documents" | chatInputArea.tsx、chatFunctions.ts |
| 手机 PWA 安装 | 浏览器"添加到主屏幕" | khoj.webmanifest |
Web 客户端是 Khoj 使用门槛最低、部署成本为零的入口：聊天、搜索、上传、PWA 安装全部开箱即用。如需将本地知识库完整同步给 Khoj，请配合桌面端客户端使用；更多数据源接入方式可参考 共享你的数据。
【免费下载链接】khoj Your AI second brain. Self-hostable. Get answers from the web or your docs. Build custom agents, schedule automations, do deep research. Turn any online or local LLM into your personal, autonomous AI (gpt, claude, gemini, llama, qwen, mistral). Get started – free. 项目地址: https://gitcode.com/GitHub_Trending/kh/khoj
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
