113 lines
3.6 KiB
Markdown
113 lines
3.6 KiB
Markdown
# Worldshaper KB Scaffold
|
|
|
|
This folder is the first pass of an internal knowledge base for Worldshaper.
|
|
|
|
It is meant to support three jobs:
|
|
|
|
1. Human onboarding.
|
|
2. Faster request triage.
|
|
3. Grounded local-LLM analysis for the Requests queue.
|
|
|
|
The goal is to give request-processing tools stable system summaries instead of asking a model to infer editor behavior from raw user text alone.
|
|
|
|
## Layout
|
|
|
|
- `systems.json`
|
|
- Machine-readable system index.
|
|
- `request-analysis-schema.json`
|
|
- JSON schema for structured request parsing output.
|
|
- `tags.json`
|
|
- Standardized request tags for queue analysis and admin review.
|
|
- `queue-workflow.md`
|
|
- First-pass automation and review flow.
|
|
- `editor-capabilities.md`
|
|
- Shorthand capability matrix for common request-analysis questions.
|
|
- `systems/*.md`
|
|
- Human-readable system notes, organized by editor subsystem.
|
|
|
|
## Current System Coverage
|
|
|
|
The scaffold currently covers:
|
|
|
|
- Launcher home and tabbed board
|
|
- Requests intake and request state handling
|
|
- Studio bootstrap and world loading
|
|
- Chunk storage and neighborhood streaming
|
|
- Layers and tile editing
|
|
- Graphics Painter
|
|
- Rendering and viewport behavior
|
|
- World Overview
|
|
- Persistence and save pipeline
|
|
- Floating windows and popout shell
|
|
- Content catalog and record APIs
|
|
|
|
## How To Use This For Request Analysis
|
|
|
|
Suggested queue flow:
|
|
|
|
1. Pull a raw request submission from the launcher request store.
|
|
2. Retrieve likely systems from `systems.json` using tags, aliases, and file names.
|
|
3. Provide the matching `systems/*.md` files to the local model as context.
|
|
4. Require the model to use only tags from `tags.json`.
|
|
5. Ask the model to split the submission into atomic requests.
|
|
6. Require output that matches `request-analysis-schema.json`.
|
|
7. Validate the JSON before storing anything back into the app.
|
|
8. Auto-promote only high-confidence items. Keep low-confidence items in review.
|
|
|
|
## Recommended Next Additions
|
|
|
|
- Add concrete file-level notes for major controllers as they evolve.
|
|
- Add a small extractor script that refreshes endpoint lists from `server.js`.
|
|
- Add examples of well-tagged historical requests for few-shot prompting.
|
|
- Add confidence thresholds and retry rules for malformed model output.
|
|
|
|
## Current Automation Entry Point
|
|
|
|
Use the queue worker with:
|
|
|
|
```bash
|
|
npm run analyze:requests
|
|
```
|
|
|
|
The worker expects:
|
|
|
|
- the Worldshaper API server to be running
|
|
- a model endpoint and API key
|
|
- KB files from this folder
|
|
|
|
### DeepSeek Setup
|
|
|
|
The worker now supports DeepSeek directly.
|
|
|
|
Recommended environment:
|
|
|
|
```powershell
|
|
$env:DEEPSEEK_API_KEY="your-key-here"
|
|
```
|
|
|
|
Defaults when `DEEPSEEK_API_KEY` is present:
|
|
|
|
- provider: `deepseek`
|
|
- base URL: `https://api.deepseek.com`
|
|
- model: `deepseek-v4-flash`
|
|
- JSON mode: enabled
|
|
- thinking: disabled
|
|
|
|
You can override the model if you want:
|
|
|
|
```powershell
|
|
$env:REQUEST_ANALYZER_MODEL="deepseek-v4-pro"
|
|
```
|
|
|
|
## Suggested Review Rules
|
|
|
|
- If the model produces multiple atomic requests from one submission, keep the original submission id on every derived item.
|
|
- If a request touches multiple systems, prefer one primary category and many tags.
|
|
- Review rationale should be short, structured, and safe to show in admin UI. Do not rely on hidden model chain-of-thought.
|
|
- If the request is really a bug report, preserve the problem statement and write the implementation note as a likely fix path, not a promise.
|
|
- If the model cannot confidently map a request, store it as `needs_review` instead of forcing a category.
|
|
|
|
## Notes
|
|
|
|
- This scaffold is grounded to the repo layout on 2026-06-26.
|
|
- It is intentionally incomplete. Treat it as a maintained map, not generated truth.
|