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

中文文档 | English

Code RAG index panel & settings card for DeepSeek Harness — a live index status bar above the conversation input plus a diagnostics & configuration card in the settings (Settings → Plugins on current DSH builds, and the legacy Web Plugins section on older shells). Data flows through the companion @aylina_ankali/code-rag-mcp MCP server (Qdrant vectors + Ollama bge-m3 embeddings, Chinese/English queries both work).

Features

Index bar (above the composer, conversation.input.dock slot):

• Current root, index status, live progress bar (% / files / chunks), error details
• Buttons: Start index (incremental) / Full rebuild / Cancel
• Target root = current session workspace by default (any workspace can be indexed directly; falls back to the server root when the workspace is not a codebase)
• Port discovery: probes 8756-8786 and picks the newest server (avoids stale instances)
• All requests carry an 8s timeout — offline shows a hint instead of hanging forever
• Index bar scope switch (v1.3.0): show it in Code RAG mode sessions only (default) or in all sessions — stored in DSH settings (settings.yaml, namespace dsh-code-rag-index-panel), takes effect immediately
• Bar appears as soon as you pick the mode (v1.4.0): visibility keys off the session's agent preset (the dock subscribes to the session list, so it re-renders the moment the preset lands) instead of waiting for server-up timing. Select Code RAG mode without sending a message and the bar shows immediately with a "starting the index server…" hint — it never auto-indexes (start/rebuild buttons stay disabled until the server is ready, then you trigger them manually, so an accidental mode pick never burns local CPU/IO).
• Scope follows the session mode strictly (v1.4.1): in strict mode ("Code RAG mode sessions only") the bar is shown only by the session's agent preset — the server's online state no longer matters. A code-rag server started by one Code RAG session keeps running while you switch to other-mode sessions; the old "server-up fallback" made the bar appear in every mode and has been removed. The "all sessions" mode behaves as before.

Settings card (v1.4.0: both Settings → Plugins — the canonical plugin-card page, settings.plugin.item slot keyed by the namespace the host half registers via settings.register + schemastery — and Settings → Web Plugins → Code RAG, legacy web-ui.plugin.item compat slot; the new-plugins-page card degrades silently if the host half cannot register the namespace):

Endpoint (host half, loopback-only)	Purpose
GET /api/code-rag/diag	One-click diagnostics: index server (port/pid/current root/per-root vector counts), Qdrant (reachable/collection), Ollama (reachable/model), mode preset (path/dist artifacts), config file — plus an issue list (including orphan-vector consistency checks)
POST /api/code-rag/config	Write <root>/.code-rag/config.json (whitelisted keys, atomic write)
POST /api/code-rag/action	index / rebuild / cancel (proxied to the index server) + setup (re-runs scripts/setup.mjs to regenerate the preset)

The card offers: Re-check button, green/red status rows, issue list, config form (Qdrant/Ollama URLs, embedding model, dimensions, collection, port, chunk size, multi-line ignore rules, configurable root), and index / rebuild / cancel / regenerate-preset actions. All file I/O is fault-tolerant; if the host endpoint is missing the card shows a hint instead of failing. Bilingual UI: follows the page language (<html lang>) automatically — Chinese and English.

Stability fix (v1.4.0): when the settingsScope namespace is unregistered or still loading, getSnapshot().value is undefined; the old code read .strictIndexBar straight off it and threw a TypeError, which crashed the index-bar/settings-card entries (slots retire crashed entries until the bundle reloads — this is what made the bar and card vanish). undefined is now treated as "not set" → strict default, and the namespace is registered with a real boolean schema so the value round-trips validated.

Configuration (<root>/.code-rag/config.json)

Precedence (low → high): built-in defaults < config file < environment variables (CODE_RAG_*) < CLI arguments. The settings card can edit these whitelisted keys (saving writes the file; changes take effect after restarting the Code RAG session):

Key	Default	Description
qdrantUrl	http://127.0.0.1:6333	Qdrant HTTP URL
ollamaUrl	http://127.0.0.1:11434	Ollama HTTP URL
embedModel	bge-m3	Embedding model (ollama pull bge-m3 if missing)
dimensions	1024	Vector dimensions (bge-m3=1024, nomic-embed-text=768)
collection	code_rag	Qdrant collection name
httpPort	8756	Panel HTTP port (auto-probes upward when busy)
chunkSize	150	Target chunk size in lines
ignore	built-in list	Ignore rules, one per line; empty restores defaults

Built-in ignore defaults cover node_modules, .git, dist, build, out, target, common IDE/build dirs (.idea, .vscode, x64, obj, cmake-build-*, …) and generated artifacts like *.min.js (full list in src/config.ts → DEFAULTS.ignore).

Prerequisites (local, free)

Indexing depends on two local, free components: Qdrant (vector store, port 6333) and Ollama (local embeddings, port 11434). Both must be up before the first index.

Qdrant (Docker)

One-shot container:

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

Or Docker Compose (docker-compose.yml):

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

Ollama (embedding model)

Install Ollama and pull the default embedding model:

ollama pull bge-m3

The settings card's Re-check verifies each piece: an unreachable Qdrant or a missing collection, an unreachable Ollama or a missing model — all land in the issue list. Indexing only succeeds once everything is ready.

Install

cd code-rag          # the companion repo (Ankali-Aylina/code-rag)
npm install && npm run build
npm run setup        # generates the Code RAG mode preset + syncs this plugin into the web profile

Then restart DSH and pick Code RAG mode for a new session. If the package is published to npm you can also npm install dsh-code-rag-index-panel by name.

Note on applying updates: lib/client.js changes are picked up automatically by the web app's client HMR (no browser refresh needed); lib/index.js (host half — loopback endpoints, settings-namespace registration) requires a DSH restart, and the Settings → Plugins card appears only after that restart registers the namespace.

Usage

1. Pick Code RAG mode for a new session in the DSH web mode picker (keep it running — the index server starts with it);
2. Once the index bar appears above the input, click Start index (incremental) or Full rebuild — progress shows live (% / files / chunks);
3. When switching workspaces, ask the model to call mcp__code_rag__set_root first (or edit root in the settings card);
4. To tune Qdrant / Ollama / embedding model / chunking, edit and save in the settings card (writes <root>/.code-rag/config.json; restart the Code RAG session to apply).

Self-tests

• Host half: node scripts/selftest-panel.mjs (mock ctx, no live server, no writes to user dirs)
• Client half: node scripts/selftest-client.mjs (executes the whole bundle in a mocked browser, verifies slot registration)