ClaudeCode-Custom-Skills/skills/wiki-vector-chat/SKILL.md

---
name: wiki-vector-chat
description: Use this skill when the user asks to "setup wiki chat", "deploy vector chat", "add AI provider to wiki", "configure RAG pipeline", "wiki chat backend", "fix wiki chat", "update zportal chat", "multi-provider AI chat", "add chat to wiki", "VectorDB chat", or mentions the Zportal Wiki AI chat system.
version: 2.0.0
---

# Wiki VectorDB Chat Skill

Deploy and manage the **Zportal Wiki VectorDB Chat** — a multi-provider AI chat system with RAG (Wiki KB + VectorDB) integrated into the Z.ai portal.

## Architecture Overview

```
┌─────────────────────────────────────────────────────────┐
│                   ZPORTAL CHAT SYSTEM                    │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Browser → /zportal/chat → zportal-chat.html           │
│       ↓ SSE                                             │
│  Nginx → /zportal/wiki/api/chat/ → :8770               │
│       ↓                                                 │
│  wiki-vector-chat.py (FastAPI)                          │
│       ├── RAG Pipeline:                                 │
│       │   ├── wiki-api (:8097) → KB keyword search     │
│       │   └── vector-db (:8099) → TF-IDF vector search │
│       └── LLM Providers:                                │
│           ├── Z.ai Coding Plan (OpenAI format)          │
│           ├── OpenAdapter (OpenAI format)               │
│           ├── OpenRouter (OpenRouter format)            │
│           ├── Crof.AI (OpenAI format)                   │
│           └── Custom providers (any format)             │
│                                                         │
│  VPS: claw.rommark.dev (95.216.124.247)                 │
│  User: uroma2                                           │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

## Key Files

| File | Location | Purpose |
|------|----------|---------|
| `wiki-vector-chat.py` | `/opt/blog/wiki-vector-chat.py` | FastAPI backend (port 8770) |
| `zportal-chat.html` | `/opt/zportal/chat.html` | Odysseus-style frontend |
| `wiki-api.py` | `/opt/blog/wiki-api.py` | KB search service (port 8097) |
| `vector-db-service.py` | `/opt/blog/vector-db-service.py` | Vector search service (port 8099) |
| `.wiki-api-token` | `/opt/blog/.wiki-api-token` | Shared auth token |
| `wiki-chat-providers.json` | `/opt/blog/wiki-chat-providers.json` | Custom provider storage |
| `wiki-kb.json` | `/opt/blog/wiki-kb.json` | 1,301 Q&A knowledge base |

## Repository

**https://github.rommark.dev/admin/Zportal-Wiki-VectorDB-Chat**

## Common Operations

### Deploy/Update

```bash
# Upload latest backend
scp wiki-vector-chat.py uroma2@95.216.124.247:/opt/blog/
scp zportal-chat.html uroma2@95.216.124.247:/opt/zportal/chat.html

# Restart service
ssh uroma2@95.216.124.247 "sudo systemctl restart wiki-vector-chat"
```

### Health Check

```bash
ssh uroma2@95.216.124.247 "curl -s http://127.0.0.1:8770/health"
# Expected: {"status":"ok","providers":6}
```

### Debug

```bash
# Check service status
ssh uroma2@95.216.124.247 "sudo systemctl status wiki-vector-chat"

# View logs
ssh uroma2@95.216.124.247 "sudo journalctl -u wiki-vector-chat -n 50"

# Test providers endpoint
ssh uroma2@95.216.124.247 "curl -s http://127.0.0.1:8770/providers"
```

### Add/Edit Provider

Providers are managed via the UI. Backend endpoints:
- `GET /providers` — List all
- `POST /providers/save` — Create/update
- `DELETE /providers/{id}` — Remove custom

Preset providers get forked as `custom-*` when edited (with API key).

## Features

| Feature | Status | Details |
|---------|--------|---------|
| Multi-provider LLM | ✅ | OpenAI, Anthropic, Ollama, OpenRouter, Groq |
| RAG pipeline | ✅ | Wiki KB + VectorDB with per-session toggles |
| Chat modes | ✅ | Chat, Code, Brainstorm |
| Session history | ✅ | localStorage, up to 50 sessions |
| Save to Wiki | ✅ | Save AI answers as new KB entries |
| Message actions | ✅ | Copy, Redo, Save-to-Wiki |
| Markdown rendering | ✅ | Bold, italic, code blocks, lists |
| SSE streaming | ✅ | OpenAI + Anthropic format support |
| Provider management | ✅ | CRUD, preset forking, API keys |
| Odysseus UI | ✅ | Tokyo Night palette, sidebar, bubbles |

## Known Issues (Fixed)

### VectorDB field mismatch (FIXED v2.0.0)
The vector-db API returns message content in a top-level `content` field with `author`/`channel` also top-level (not nested under `metadata`). The backend must read `content` not `text`, and `author` directly not from `metadata`.

### Missing API key error (FIXED v2.0.0)
Preset providers without API keys returned cryptic HTTP 401. Now shows clear guidance to add a key via the UI.

## Nginx Config

Located at `/etc/nginx/sites-enabled/claw.rommark.dev`:

```nginx
location = /zportal/chat {
    default_type text/html;
    alias /opt/zportal/chat.html;
}
location ^~ /zportal/wiki/api/chat/ {
    proxy_pass http://127.0.0.1:8770/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 120s;
}
```

## Systemd Service

`/etc/systemd/system/wiki-vector-chat.service`

```ini
[Unit]
Description=Wiki VectorDB Chat - Multi-Provider AI
After=network-online.target wiki-api.service
Wants=network-online.target

[Service]
Type=simple
User=uroma2
WorkingDirectory=/opt/blog
EnvironmentFile=-/home/uroma2/.config/zai-monitor/zai-monitor.env
ExecStart=/usr/bin/python3 /opt/blog/wiki-vector-chat.py --port 8770
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```