Ankali-Aylina/code-rag#dsh-code-rag-index-panel

中文 | English

DeepSeek Harness 客户端插件：Code RAG 索引面板（索引状态条 + 设置页诊断与配置卡片）。

在会话输入框上方（conversation.input.dock 插槽）渲染一条索引状态条：

• 显示：当前根、索引状态、进行中任务的进度条（% / 文件 / 分块）、错误明细；
• 按钮：开始索引（增量）/ 全量重建 / 取消；
• 数据与按钮操作与 MCP 工具（mcp__code_rag__*）同源，直连 code-rag 服务器的 本地 HTTP 端点（GET /api/status、POST /api/index、POST /api/cancel， 端口 8756 起自动探测 31 个端口）。

功能

• 索引状态条：当前根 / 索引状态 / 实时进度（% + 文件 + 分块）/ 错误明细，按钮 开始索引 / 全量重建 / 取消；
• 设置诊断卡片：设置页「插件」区（新架构）与「Web 插件」区（兼容层）双位置出现，一键检测服务器 / Qdrant / Ollama / 预设 / 配置并列出问题清单，可编辑配置、执行索引动作；
• 显示范围开关：仅 Code RAG 模式会话（默认，严格）或所有会话；
• 选模式即现：选中 Code RAG 模式即出现索引条（不自动索引，服务器就绪后由你手动触发）；
• 中英双语：界面跟随页面语言（<html lang>）自动切换。

结构

dsh-code-rag-index-panel/
├── package.json        # dsh.client 声明 + dsh.bundle.patch + schemastery 依赖
├── cordis.patch.yml    # 注册插件行（id/name 与包名一致）
└── lib/
    ├── index.js        # host 半部：/api/code-rag/* 环回端点 + 设置命名空间注册
    └── client.js       # 浏览器半部（ModuleLoader 格式，React + slots）

环境依赖（本地免费，需先就绪）

索引依赖两个本机免费组件：Qdrant（向量库，端口 6333）与 Ollama（本地嵌入， 端口 11434）。二者缺一不可，首次索引前请确保就绪。

Qdrant（Docker）

一条命令启动容器：

docker run -d \
  --name qdrant \
  --restart unless-stopped \
  -p 6333:6333 \
  -v qdrant_data:/qdrant/storage \
  qdrant/qdrant

或用 Docker Compose（docker-compose.yml）：

services:
  qdrant:
    image: qdrant/qdrant
    ports:
      - "6333:6333"
    volumes:
      - qdrant_storage:/qdrant/storage
volumes:
  qdrant_storage:

Ollama（嵌入模型）

安装 Ollama 后拉取默认嵌入模型：

ollama pull bge-m3

设置卡片的「重新检测」会逐项核对：Qdrant 不可达/集合缺失、Ollama 不可达/模型未安装 都会列入问题清单；全部就绪后索引才能成功。

安装（随 code-rag 接入完成）

推荐：在 code-rag 仓库根目录运行 npm run setup（scripts/setup.mjs）—— 它会自动把本插件以 file: 依赖写入 web profile（~/.dsh/profiles/web）并同步 已安装副本，路径无需手工指定：

"dependencies": { "dsh-code-rag-index-panel": "file:<code-rag 仓库>/plugins/dsh-code-rag-index-panel" },
"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-code-rag-index-panel"] } }

若该包已发布到 npm，也可直接 npm install dsh-code-rag-index-panel（版本依赖）， 此时无需本地路径。仓库挪位置后重新运行 npm run setup 即可。

改完 profile 配置后重启 DSH 生效（dsh --profile web）。之后修改 lib/client.js 会被 client-hmr 轮询到并自动热更新（浏览器无需刷新）； 修改 lib/index.js（host 半部，如端点/命名空间注册）则需重启 DSH 生效。

使用

1. 在 DSH Web 模式选择器里选 Code RAG 模式 新建会话（保持其运行，索引服务器随之启动）；
2. 输入框上方出现索引条后，点 开始索引（增量）或 全量重建，进度实时显示（% / 文件 / 分块）；
3. 换工作区时让模型调用 mcp__code_rag__set_root 切换根后再索引（或直接在设置卡片里改 root）；
4. 需要调整 Qdrant / Ollama / 嵌入模型 / 分块等参数时，在设置卡片里修改并保存（写入 <root>/.code-rag/config.json，重启 Code RAG 模式会话后生效）。

配置（/.code-rag/config.json）

优先级（从低到高）：内置默认值 < 配置文件 < 环境变量（CODE_RAG_*）< 命令行参数。 设置卡片可编辑以下白名单键（保存即写入该文件）：

键	默认值	说明
qdrantUrl	http://127.0.0.1:6333	Qdrant HTTP 地址
ollamaUrl	http://127.0.0.1:11434	Ollama HTTP 地址
embedModel	bge-m3	嵌入模型（未安装时 ollama pull bge-m3）
dimensions	1024	向量维度（bge-m3=1024，nomic-embed-text=768）
collection	code_rag	Qdrant 集合名
httpPort	8756	面板 HTTP 端口（被占用时自动上探）
chunkSize	150	分块目标行数
ignore	内置列表	忽略规则，每行一条；留空恢复默认

内置 ignore 默认覆盖：node_modules、.git、dist、build、out、target、 常见 IDE/构建目录（.idea、.vscode、x64、obj、cmake-build-* 等）与 *.min.js 等生成物（完整列表见 src/config.ts 的 DEFAULTS.ignore）。

动态版本

../index-panel.client.js 是该面板的轻量动态版（仅索引条，无设置卡片/严格模式 等常驻版功能）：随会话存在，交给 cordis_define 即用即弃，用于快速验证；功能完整 的常驻版以本包为准。

设置页卡片（v1.1.0+）

本包同时注册一张 Code RAG 设置与诊断卡片，在设置页两个位置出现（v1.4.0 起）： 「插件」区（settings.plugin.item 槽位，新设置架构的插件卡片页）与「Web 插件」区 （web-ui.plugin.item 槽位，兼容层，宿主为 @linxin666/dsh-client-ui-web-ui-settings）。 新架构下的「插件」区卡片依赖宿主半部注册的 dsh-code-rag-index-panel 设置命名空间 （settings 服务 + schemastery，缺一即静默降级到仅「Web 插件」区显示；宿主半部升级后 需重启 DSH 才会注册命名空间）。卡片数据由 host 半部的环回端点提供（仅本机来源可访问）：

端点	作用
GET /api/code-rag/diag	一键诊断：索引服务器（端口/pid/当前根/各根向量数）、Qdrant（可达/集合）、Ollama（可达/模型）、模式预设（路径/dist 产物）、配置文件，附问题清单
POST /api/code-rag/config	写 <root>/.code-rag/config.json（白名单键合并，原子写）
POST /api/code-rag/action	index / rebuild / cancel（代理到索引服务器）+ setup（在仓库执行 scripts/setup.mjs 重新生成预设）

卡片提供：重新检测按钮、状态绿灯/红灯、问题清单、配置表单（Qdrant/Ollama 地址、嵌入模型、维度、集合、端口、分块行数，root 可改）、开始索引 / 全量重建 / 取消 / 重新生成预设按钮。卡片外观与交互与家族其它插件（如「图像理解」）一致： 圆角卡片外壳（--dsw-alias-bg-layer-3，展开态 bg-layer-2）、可折叠头部 （chevron 旋转动画、aria-expanded 无障碍标注）、border-top 分隔的 body/footer、 主/次按钮样式。所有文件读写均容错，宿主端点缺失时卡片显示提示而非报错。

索引条显示范围开关（v1.2.0+）：卡片提供「索引条显示范围」二选一—— 仅 Code RAG 模式会话（默认，严格模式：索引条跟随 MCP 工具/检索能力，只在 Code RAG 模式会话出现）或所有会话（任意会话都能对当前工作区直接索引）。 选择写入 DSH 设置（settings.yaml 的 dsh-code-rag-index-panel 命名空间， strictIndexBar: false 即所有会话），立即生效，无需重启。

界面中英双语（v1.3.0+）：索引条与设置卡片跟随页面语言 （<html lang>）自动切换中英文。

选模式即现索引条（v1.4.0+）：索引条可见性以「会话预设是否为 Code RAG 模式」 为准（订阅会话列表，preset 落地即重渲染）—— 用户选了 Code RAG 模式、尚未发消息时索引条立即出现，显示「正在启动索引服务器…」， 绝不自动开始索引（开始/全量重建按钮在服务器就绪前禁用，就绪后由用户手动触发， 避免误选模式直接占用本机资源）。

显示范围严格按模式判定（v1.4.1）：严格模式（默认，仅 Code RAG 模式会话）下 索引条只按会话预设判定，服务器在线与否不影响显示范围——code-rag 服务器由某个 Code RAG 会话拉起后会常驻（切到其它模式会话时仍在运行），旧版「服务器在线兜底」 会让所有模式都显示索引条，现已移除；「所有会话」模式行为不变。

稳定性修复（v1.4.0）：settingsScope 命名空间未注册/尚未加载时 getSnapshot().value 为 undefined，旧代码直接读 .strictIndexBar 抛 TypeError，导致索引条/设置卡片槽位 崩溃后 abdicate（本轮起永久隐藏，直到刷新/重启）。现在 undefined 视为「未设置」→ 严格模式默认，同时命名空间注册后 value 走正式 schema，读写均校验。

host 半部自检：node scripts/selftest-panel.mjs（mock ctx 驱动，不依赖真实 服务器，不写用户目录）；client 半部加载自检：node scripts/selftest-client.mjs （mock 浏览器环境执行整个 bundle，验证槽位注册与 disposer）。