Logos

# Tool List > **A local intelligent writing agent for game narrative creators** | Python + React + Electron > Skill-driven · Multi-paradigm Agent · Fusion Retrieval · MCP Scalable [](https://www.python.org/) [](https://www.typescriptlang.org/) []() [](LICENSE) ## Project Positioning Logos is a local intelligent writing assistant for **game narrative creators** (copywriters, narrative planners). Unlike general AI chat tools, Logos's core assumption is that the writer's **narrative setting knowledge base (KSFS)** is the only source of truth, and the Agent's capabilities are organized through a **skill list** - users select a capability from the panel, complete the task with a fixed wizard, and do not open a blank, versatile chat box by default. > This is also a technical job search work, showcasing the complete ability from **product architecture to engineering implementation**. ## System Architecture ``` ┌─────────────────────────────────────────────────────────┐ │ GUI / Electron │ │ Skill Panel · Task Wizard · Multi-tab Session · Archive Cache │ └──────────────────────────┬──────────────────────────────┘ │ HTTP + SSE (Server-Sent Events) ┌──────────────────────────▼──────────────────────────────┐ │ Platform Layer (Support Layer) │ │ API_v1 · Combined Root Assembly · S&G Whitelist · Obs Observability · Configuration │ └──────────────────────────┬──────────────────────────────┘ │ ┌──────────────────────────▼──────────────────────────────┐ │ Agent Layer (Decision Layer) │ │ Shell Scheduler · CB Context Construction · PR Paradigm Routing │ │ ┌────────┐ ┌───────┐ ┌────────┐ ┌──────────┐ │ │ │dialogue│ │ react │ │ plan │ │ pipeline │ │ │ └────────┘ └───────┘ └────────┘ └──────────┘ │ └──────┬─────────────────────────────────┬────────────────┘ │ │ ┌──────▼──────┐ ┌───────▼─────────────────┐ │ MCP Skills │ │ Infrastructure Layer │ │ (Pluggable) │ │ Retrieval · LLM Adaptation · Vector │ └─────────────┘ └──────┬──────────────────┘ │ ┌────────▼──────────────────┐ │ HDL: Knowledge Storage │ │ KSFS · HSI · SVS · FTS5 │ │ (Single Source of Truth + Three-layer Index) │ └───────────────────────────┘ ``` ## Core Technology Highlights ### 🧠 Paradigm Router Not all Agent scenarios are suitable for ReAct. Logos defines **4 execution paradigms**, each Skill declares in advance in the manifest, and the routing layer confirms and schedules: | Paradigm | Applicable Scenario | Protocol | |------|----------|------| | **dialogue** | Free Text Multi-turn (Chat-inspired) | Natural Language, non-JSON | | **react** | Tool Loop (Retrieval Q&A, Error Checking) | JSON-only ReAct | | **plan** | Plan and then Execute (Outline Planning) | Phase A Structured Plan | | **pipeline** | Deterministic Pipeline (Setting Import) | Phase SSE Events | **Design Trade-offs**: No runtime "intelligent guessing paradigm" - Skill authors set boundaries in the manifest, and PR only does routing confirmation. Developers can experiment with `paradigm_override`, but not as a default path. ### 🔍 Three-way Fusion Retrieval Narrative writing retrieval is different from general RAG - users often search for **proper nouns** (person/place/thing names), requiring precise hits rather than semantic approximations. Logos adopts **three-way recall + simple fusion**: | Route | Technology | Responsibility | |----|------|------| | **HSI** | SQLite Metadata Index | Path/title Weak Matching | | **SVS** | Chroma Vector Database (bge-small-zh) | Semantic Approximation | | **Sparse** | SQLite FTS5 Full-text Index | Proper Noun Precise Hit | The three routes are deduplicated by path, sorted by max score, and the Agent gets `Citation[]` through the `retrieve` tool, then calls `read_ksfs` to read the full text to verify - **chunk snippet is "bait", and the truth is in the full text**. ### 🛡️ MCP Governance As the entry point of the plugin system, MCP's management is more complex than simply mounting scripts: - **Discovery Cache**: Under the same configuration, `tools/list` is only executed once to avoid repeated sub-processes for each conversation - **Process Leak Protection**: `psutil` repeated pressure test + `call_mcp_tool_sync` each call to start and stop a stdio process, timeout kill - **Tool Whitelist**: Each Skill declares `allowed_tools` in the manifest, constructing a scoped registry, not exposing the full directory to LLM - **Fail-fast Configuration Verification**: `mcp_servers` error writing as a non-list throws `ValueError`, not silently degrading ### 📋 Engineering Discipline | Practice | Implementation | |------|------| | **API Contract Synchronization** | `.githooks/commit-msg` + `pre-commit` script - modify `api_v1.py` must temporarily save `API-V0.2.md` and contract test | | **Hierarchical Testing** | L1 Unit → L2 Integration (no HTTP) → L3 Contract (SSE Event Name Verification) → L4 Slow Test (real embedder) | | **Retrieval Benchmark** | 30-50 Chinese narrative query benchmark set, `Recall@k` / `MRR` / component isolation analysis | | **Observability** | Tool call chain `logos_tool_chain_v1` writes maintenance track logs, 4-level `log_profile` (minimal to audit) | ## Capability Overview ### ✅ Implemented - **Skill-driven GUI**: Skill Panel → Task Three-step Wizard → SSE Streaming Execution → Archive (Electron + React) - **KSFS Narrative Knowledge Base**: `.md` file tree as the single source of truth, containing front matter metadata - **Setting Import Pipeline**: Paste structured text → LLM render as draft → human review and promote to KSFS - **Three-way Fusion Retrieval**: HSI + SVS (Chroma) + Sparse (FTS5), incremental synchronization - **MCP Pluggable Tools**: echo example + Gaode weather, with governance and leak testing - **Dialogue / ReAct / Pipeline Three Paradigms** (Plan as Phase A preview) - **Obs Observability**: Tool call chain landing, 4-level log profile, GUI optional log root display - **Single-instance Electron Shell**: health door, backend hosting, exit cleanup, Windows portable packaging ### 🧊 Planned or Limited - Knowledge Graph Fusion Retrieval (data layer implemented, fusion not connected) - RRF Hybrid Sorting (current three-way max enough) - Outline Planning Skill Product Finalization (Phase A code ready, but panel hidden) - Installation package/signature/automatic update (portable version enough, postponed) ## Quick Start ### 🐳 Method A: Docker One-click Experience (Recommended Quick Try) > No need to install Python/Node.js, just **Docker Desktop**. Suitable for demonstrating to interviewers, colleagues. ```bash # Windows — Double-click the start.cmd in the root directory start.cmd # macOS / Linux — Execute in terminal: chmod +x start.sh && ./start.sh ``` The script automatically completes: **generate default configuration → build image → start backend + frontend → open browser**. ``` Frontend Interface → http://localhost:3000 (Nginx + React) Backend API → http://localhost:8000 (FastAPI, /api automatic proxy) ``` Stop: Stop the container in Docker Desktop, or execute `docker compose down` in the terminal. ### 🛠️ Method B: Development Environment Start (Suitable for Code Debugging) > Requires local installation of **Python 3.11+** and **Node.js 18+**. Supports Vite hot reload + Electron shell. **Double-click `scripts\start_logos.cmd` (Windows)** to start three windows at once: | Window | Port | Technology | |------|------|------| | Logos Backend | :8000 | Python FastAPI | | Logos Vite | :5173 | React + Vite (hot reload) | | Logos Electron | Load Vite | Desktop Shell | **Or manually start step by step (macOS/Linux universal):** ```bash python -m venv .venv source .venv/bin/activate # Windows: .\.venv\Scripts\activate pip install -e ".[dev]" cp config/local.example.yaml config/local.yaml python scripts/run_dev_backend.py # Terminal 1: Backend :8000 cd src/gui && npm install && npm run dev # Terminal 2: GUI :5173 ``` Open the browser to `http://localhost:5173`, or `cd src/electron && npm run electron:dev` to start the desktop shell. ## Technology Stack | Layer | Technology | |----|------| | Backend | **Python 3.11+** · FastAPI · httpx · PyYAML · jsonschema | | Frontend | **TypeScript** · **React** · **Vite** | | Desktop Shell | **Electron** (contextIsolation + preload narrow IPC) | | Vector Retrieval | **Chroma** · **sentence-transformers** (bge-small-zh) | | Keyword Retrieval | **SQLite FTS5** | | Knowledge Graph | **CozoDB** + Datalog (data completed, fusion pending) | | MCP Protocol | **mcp** 1.2+ (stdio transmission) | | LLM Protocol | OpenAI compatible API (DeepSeek / OpenAI / any compatible service) | | Testing | **pytest** · Playwright (E2E) | ## Repository Structure ``` Logos/ ├── src/ │ ├── logos/ # Python core │ │ ├── agent/ # Agent decision layer: Shell, PR, CB, paradigm executor │ │ ├── platform/ # Support layer: HTTP API, S&G, Obs, configuration, combined root │ │ ├── infrastructure/ # Infrastructure: retrieval, LLM adaptation, vector database │ │ ├── persistence/ # Persistence layer: KSFS, HSI, SVS, Sparse, KG, promotion │ │ └── ports/ # Port abstraction: retrieval, metadata, vector, sparse index │ ├── gui/ # React + Vite frontend │ └── electron/ # Electron desktop shell ├── skills/manifests/ # Product Skill YAML declaration (7) ├── resources/prompts/ # Prompt template assets (paradigm/skill/persistence gear) ├── resources/pipelines/ # Pipeline phase configuration ├── resources/entity_template/ # Entity template and rendering specification ├── config/ # defaults.yaml + local.yaml (local) ├── tests/ # Hierarchical test suite (including retrieval benchmark set) ├── scripts/ # Development and operation scripts └── docs/ # External introduction document ``` ## Related Documents | If you are… | Recommended Reading | |-----------|----------| | Want to quickly understand design ideas | [docs/project-overview.md](docs/project-overview.md) → [docs/architecture-overview.md](docs/architecture-overview.md) | | Want to run | [docs/quick-start.md](docs/quick-start.md) | | Want to understand how retrieval is done | [docs/subsystem-documents/KSFS-and-narrative-knowledge-base.md](docs/subsystem-documents/KSFS-and-narrative-knowledge-base.md) | | Want to understand Agent paradigm | [docs/subsystem-documents/Agent-and-paradigm-routing.md](docs/subsystem-documents/Agent-and-paradigm-routing.md) | | Want to understand Skill system | [docs/subsystem-documents/Task-and-Skill-interface.md](docs/subsystem-documents/Task-and-Skill-interface.md) | | Want to understand MCP integration | [docs/subsystem-documents/Skills-and-MCP-extension.md](docs/subsystem-documents/Skills-and-MCP-extension.md) | | Want to see API contract | [docs/subsystem-documents/HTTP-API-overview.md](docs/subsystem-documents/HTTP-API-overview.md) | | Complete document index | [docs/README.md](docs/README.md) | ## License [MIT License](LICENSE)