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

name, description, version

name	description	version
wiki-vector-chat	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.	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

# 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

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

Debug

# 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:

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

[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