本地知识库 扩展 · 用户操作手册
本扩展是 本地知识库（扩展包标识 error-kb）的客户端，通过 HTTP 连接 FastAPI 服务。从 VSIX 安装 时，后端源码已内置在扩展目录的 bundled/server，通常 不必再单独克隆 Git 仓库；扩展会优先使用内置代码，并在本机全局存储目录创建 Python 虚拟环境（体积较大，首次 pip 与模型下载需时间与磁盘空间）。若你打开了本地的 error-kb 仓库文件夹，则会改为使用工作区内的代码（便于开发）。
一、环境要求（本机需要已具备）
| 用途 |
要求 |
| PostgreSQL（pgvector） |
已安装 Docker Desktop（Windows / macOS）或兼容的 Docker 引擎（Linux），且 docker compose 可用。 |
| API 与嵌入模型 |
已安装 Python 3.10+（Windows 下建议安装后可在终端执行 python）。 |
| 可选：已有现成后端 |
若 API 已由他人部署在局域网/云端，则你 无需 Docker/Python，只需把 Base Url 指到该地址即可。 |
| 编辑器 |
VS Code 或 Cursor，版本不低于扩展声明的 engines.vscode。 |
| 网络 |
首次启动 API 时会从 Hugging Face 等下载嵌入模型（体积约百兆级），需能访问外网（视你环境而定）。 |
更细的架构说明见仓库根目录 DEPLOY.md。
二、本机部署 error-kb（扩展命令）
一般用户（仅安装 VSIX）： 无需克隆仓库，直接执行下方 一键启动 即可（扩展使用内置 bundled/server）。
开发者： 若从源码打开 error-kb 仓库根目录，扩展会优先使用工作区里的 app.py 等。
下列命令在 已解析到服务目录 时可用（内置副本 或 工作区 error-kb 根目录）。
推荐：一键启动（无需逐步点命令）
命令面板执行 本地知识库: 一键启动本地服务（自动：venv + 数据库 + API）。
扩展会在后台依次：若无 .venv 则创建并 pip install、执行 docker compose up -d --build、在后台启动 uvicorn。日志在输出通道 「本地知识库 · 本地服务」，无需再手动开终端保活。
若提示成功或「API 已就绪」，浏览器访问 http://127.0.0.1:9686（若改了端口见下）。在设置中将 Base Url 与 Api Port 保持一致（默认均为 9686）。
停止由扩展启动的 API：本地知识库: 停止扩展启动的 API 进程（若你曾在本机用别的方式启动 uvicorn，需自行在终端结束对应进程）。
可选：打开工作区即自动一键启动
在设置中开启 本地知识库: Auto Start Local Stack（默认开）。开启后，当工作区根目录为知识库后端项目且存在 docker-compose.yml 时，扩展加载后会自动执行与上面相同的一键流程。
分步命令（与一键等价，便于排错）
- 本地知识库: 初始化 Python 环境（venv + pip）
- 本地知识库: 启动本地数据库（Docker Compose）
- 本地知识库: 启动 API 服务（uvicorn）（在终端中运行，需保持终端不关；一键启动则无此限制）
命令行等价方式（不通过扩展也可）：
- macOS / Linux：
bash scripts/setup-venv.sh → bash scripts/start-db.sh → bash scripts/start-api.sh
- Windows：在 PowerShell 中
.\scripts\setup-venv.ps1 → .\scripts\start-db.ps1 → .\scripts\start-api.ps1
若数据库端口 5432 已被占用，需先停止冲突服务或修改 docker-compose.yml 与 app.py 中的数据库连接（进阶，见 DEPLOY.md）。
三、如何安装扩展
方式 A：从 VSIX 安装（常见）
- 取得扩展包文件：
error-kb-x.x.x.vsix（由开发者用 vsce package 生成）。
- 在 VS Code 中打开命令面板（macOS：
Cmd+Shift+P，Windows / Linux：Ctrl+Shift+P）。
- 输入并选择：Extensions: Install from VSIX...（扩展：从 VSIX 安装…）。
- 选中上述
.vsix 文件，按提示重载窗口（Reload）使扩展生效。
方式 B：仅本地开发时使用
从源码 F5 调试的方式见同目录 README.md，面向开发者，终端用户可忽略。
四、首次必做：配置服务地址
打开 设置（Cmd+, / Ctrl+,），搜索 本地知识库。
配置项说明：
- 本地知识库: Base Url
后端根地址，不要末尾多写路径。默认一般为：http://127.0.0.1:9686
若后端在其它机器或端口，改为例如：http://192.168.1.10:9686。
- 本地知识库: Default Project（可选）
录入案例时默认填写的「项目标识」。留空时，扩展会尝试用 当前工作区文件夹名称 作为项目名。
确认后端已启动：在浏览器访问 你的 Base Url（例如 http://127.0.0.1:9686），应能看到 Web 页面或接口响应；若无法打开，请先按 DEPLOY.md 排查数据库与 uvicorn。
五、日常使用：如何打开命令
- 打开命令面板：
Cmd+Shift+P / Ctrl+Shift+P。
- 输入
本地知识库，下方会出现以 本地知识库: 开头的命令。
- 用方向键选择后回车执行。
建议在 VS Code 里给常用命令绑定快捷键：文件 → 首选项 → 键盘快捷方式，搜索 errorKb 自行绑定。
六、各功能操作说明
1. 本地知识库: 录入案例
用于把当前案例记入知识库（后端会生成向量并入库）。
- （可选）在编辑器中 选中一段文字（如报错摘要、堆栈片段），作为默认「摘要」。
- 执行命令 本地知识库: 录入案例。
- 按提示依次输入或确认：
- 项目标识：与检索、筛选时使用的
project 一致。
- 错误类型：如
TypeError、HTTP 500 等。
- 摘要：未选中文本时需手动填写。
- 根因、解决方案：如实填写；可暂填占位，日后在 Web 端再改（若后端支持）。
- 标签：英文逗号或中文逗号分隔，可留空。
- 成功后会提示已保存；若提示连接失败，检查 Base Url 与后端是否运行。
2. 本地知识库: 语义检索相似案例
根据自然语言描述，在后端做向量相似检索。
- （可选）选中编辑器中的 查询文本（如错误信息），作为默认检索内容。
- 执行 本地知识库: 语义检索相似案例。
- 输入 检索 query（描述问题现象或关键词）。
- 输入 项目（可选）：与某条录入案例时的
project 一致可缩小范围；留空 表示不按项目过滤（具体行为以后端 /match 逻辑为准）。
- 在列表中选择一条结果，扩展会在 系统浏览器 中打开该条目的详情页（
/p/{id}）。
若无匹配，可尝试降低心理预期、改写 query，或请管理员调整后端 threshold 等参数。
3. 本地知识库: 在浏览器中打开 Web 界面
一键用浏览器打开 Base Url 根路径，便于浏览列表、看排版更好的详情页。
4. 本地知识库: 最近记录（JSON）
从后端拉取最近若干条记录的 JSON，显示在 「本地知识库」输出通道。
- 执行该命令。
- 若提示查看输出：菜单 查看 → 输出，右上角通道选 本地知识库。
适合快速确认库里是否有数据、字段结构是否正确。
5. 本地知识库: 清理数据（清空全部案例）
删除当前 Base Url 对应服务中 全部 案例记录（error_records 表），不可恢复。须 API 与数据库已启动。命令面板执行后，在弹窗中选择 确认清空 才会执行。
6. 本地知识库: 卸载数据库（删除 Docker 数据卷）
停止 PostgreSQL 容器并删除 Docker 命名卷（库文件一并删除），不可恢复；与上一节仅清空表记录不同。须本机 Docker 可用。执行前会停止扩展启动的 uvicorn；完成后下次「一键启动」会重新 up 空库。
7. 本机部署相关命令（与第二节对应）
| 命令 |
作用 |
| 本地知识库: 一键启动本地服务 |
自动：venv（若缺）→ Docker → 后台 uvicorn；日志见「本地知识库 · 本地服务」。 |
| 本地知识库: 停止扩展启动的 API 进程 |
结束由扩展拉起的 uvicorn，不影响其他方式启动的进程。 |
| 本地知识库: 初始化 Python 环境（venv + pip） |
仅创建 .venv 并安装依赖。 |
| 本地知识库: 启动本地数据库（Docker Compose） |
若 pgvector 容器已在运行则跳过；否则先 up -d 复用卷，必要时再构建镜像。 |
| 本地知识库: 启动 API 服务（uvicorn） |
在终端中启动 API；需保持终端运行。 |
| 本地知识库: 清理数据（清空全部案例） |
清空库内全部案例记录；不删 Docker 卷与 venv。 |
| 本地知识库: 卸载数据库（删除 Docker 数据卷） |
docker compose down -v；删除数据卷与容器内数据。 |
七、常见问题
| 现象 |
建议 |
| 卸载/重装扩展后数据还在吗？ |
在。 数据库在 Docker 数据卷里（compose 项目 error-kb-vscode），与 VSIX 无关。扩展会检测容器是否已在运行，已运行则不再执行 compose，避免重复安装。只有执行 docker compose down -v 或删卷才会清空库。 |
| 提示「当前工作区不是 error-kb 仓库根目录」 |
仅在使用工作区源码模式时需要；仅用内置 bundled 时可忽略。若需工作区模式，请用 打开文件夹 打开仓库根目录。 |
| Docker 报错、无法启动容器 |
确认 Docker Desktop 已启动；端口 5432 未被占用；必要时 docker compose ps / 查看终端完整日志。 |
| 初始化 Python 失败 |
确认已安装 Python 3；Windows 可尝试 py -3 安装路径；或手动在终端按 DEPLOY.md 创建 venv。 |
| 提示无法连接、超时 |
确认本机（或网络）能访问 Base Url；启动 API 的终端是否仍在运行；防火墙是否放行 9686 端口。 |
| 录入案例或检索返回 4xx/5xx |
看提示中的错误信息；对照浏览器直接访问同一 API 是否成功；检查数据库是否已初始化（init.sql）。 |
| 检索永远没有结果 |
知识库可能为空，先 录入案例；或 query 与库内内容差异过大；联系管理员调阈值与模型。 |
| 浏览器打不开详情页 |
检查 Base Url 是否与浏览器一致；记录 id 是否有效。 |
八、隐私与安全说明
- 录入案例与检索内容会发送到 你所配置的 Base Url 对应的服务器，请确保该服务位于可信环境（内网或已做访问控制）。
- 勿在 Base Url 中硬编码密码；若需鉴权，应由后端统一实现，扩展侧当前以匿名 HTTP 调用为主（以实际后端为准）。
若部署方式与本手册假设不一致（例如 HTTPS、反向代理、路径前缀），请将 Base Url 设为浏览器能访问到的 API 根地址；若仍无法使用，请向提供扩展与后端的维护者索取专用说明。
