Liyuan

# Tool List **AI Agent-based Role-Playing Application**  ## What is Liyuan Liyuan is a role-playing application that features AI agents as the main characters. It optimizes the role-playing experience by incorporating various agent functions. ## Innovations of Liyuan 1. **Memory Optimization**: By modifying the harness, Liyuan improves memory limits from the source. Traditional AI role-playing stores all processes in context, which can be redundant and decrease model intelligence. Liyuan introduces harness to filter out unnecessary operations and re-encode context, reducing redundancy by 53%–63%. The complete memory structure consists of four layers: - Pure context (working memory) - Structured ledger (side model automatically accounts for items, favor, time, foreshadowing, snapshots, etc.) - Retrieval assets (world book + knowledge base, used as needed) - Narrative compression (generates previous summaries based on narrative logic) 2. **Agent Inquiry Mode**: Users can deeply participate in and decide the plot direction. In coding agents, most have a mode where the agent asks for confirmation before performing an action. Liyuan translates this into role-playing: when encountering important new characters, key settings, or significant plot twists, the agent will pause and present a choice card with several directions and a free input box. This feature solves the traditional RP problem of having to constantly try new things, hoping for a high-quality and satisfying plot. Liyuan lets users participate deeply and decide the direction. 3. **Panels**: AI-generated panels optimize the experience. Liyuan gives agents the ability to generate various panels and import them into the panel section. These panels can be updated in real-time as the role-playing progresses. 4. **Extensions**: Agent skills and MCP. As agents have classic skills and MCP, Liyuan allows for simple implementation of complex extension capabilities. 5. **World Line**: Includes saving, branching, and other features for experiencing different endings. Traditional AI role-playing requires restarting or rewriting old content to experience different endings. Liyuan provides game-level saving: `/store` saves, `/back` rolls back, `/line` views the world line panorama. Key points include rolling back the entire world—plot text, state ledgers, agent-built maps and equipment libraries, knowledge base mounts—and all consistent returns to that time point. 6. **Knowledge Base**: Customizable knowledge base that can be filled and mounted at any time. Users and agents can create a knowledge base together, and users can modify it or let agents write new settings from context into the knowledge base during role-playing. 7. **Material Library**: Stores various files, images, and other materials input by users and generated by AI. As agents have back-end capabilities, users can upload files and images, which are stored in a VPS folder instead of context. **Compatibility**: 1. **Character Cards**: PNG cards and JSON cards can be directly imported. 2. **World Book**: JSON can be directly imported, and blue lamp constant / green lamp keyword activation semantics are retained. 3. **Chat Records**: JSONL old files can be directly imported for continuation. ## Quick Start Prerequisites: **Node.js ≥ 22**, any OpenAI compatible API Key (e.g., DeepSeek). ```bash cd Liyuan # Skip if repository root is the current directory # Initial setup: generate local configuration from examples (do not submit files with API keys to git or share with others) cp liyuan.agent.example.json liyuan.agent.json cp liyuan.config.example.json liyuan.config.json # Edit liyuan.agent.json → fill in API key and model ID npm install npm run web:build # Initial or after front-end changes (if web/dist exists, skip) npm run web # Start service; npm run web:new starts a new session ``` - Windows: double-click `start.bat` - Linux / macOS: `chmod +x start.sh && ./start.sh` - Open the address printed in the console in a browser (default `http://127.0.0.1:7620`); the console also prints the LAN address for mobile devices connected to the same Wi-Fi. ### Server Deployment (Linux / VPS) Three deployment methods are available; see [deploy/README.md](deploy/README.md) for details: ```bash # Method A: One-click installation script (installs as a systemd service and automatically installs Node 22) curl -fsSL https://raw.githubusercontent.com/weidu12123/Liyuan/v1.0.0/deploy/install.sh | bash # Fill in API key after installation: nano /opt/liyuan/liyuan.agent.json, then systemctl restart liyuan # Method B: Docker Compose (data stored in named volumes, no data loss during upgrade and rebuild) git clone --depth 1 https://github.com/weidu12123/Liyuan.git && cd Liyuan docker compose up -d --build # Method C: Manual packaging and uploading (executed on Windows, produces a zip file without node_modules) powershell -File scripts/pack-for-linux.ps1 ``` **Do not expose port 7620 to the public internet**—the service itself has no authentication; use reverse proxy + authentication for external access. Configurations are split into two files: **`liyuan.config.json`** manages character cards, world books, and user identities (can also be modified in the panel); **`liyuan.agent.json`** manages models and API keys (**do not submit to repository**). Old `.rp-*` directories and `rp.config.json` are automatically migrated on startup. ## Advanced - **Slash Commands** (directly input in the web input box with completion): `/state` ledger · `/lore` setting retrieval · `/import` import old files · `/store` `/back` `/line` saving and world line · `/rewind` `/branch` rollback and branching · `/compact` manual compression, etc. - **MCP**: Automatically scans `~/.claude.json`, Cursor configuration, `~/.liyuan/mcp.json`, and project `.mcp.json` / `.liyuan-mcp.json` on startup. **All disabled by default**; enable in the "Extensions → MCP" panel. - **TTS (Text-to-Speech)**: Configure `LIYUAN_TTS_BASE_URL` + `LIYUAN_TTS_API_KEY` (or directly use `OPENAI_API_KEY`) to enable TTS; specify models and voices with `LIYUAN_TTS_MODEL` / `LIYUAN_TTS_VOICE`. - **Skills**: `.liyuan-skills/` markdown files are skills that agents can write themselves or be manually written and controlled in the "Extensions" panel. ## Known Limitations - Does not run character card-built regular scripts and independent HTML front-ends (old ecosystem-specific gameplay); - Requires visual models to view images; non-visual models will truthfully inform that they cannot see; - Preset effectiveness under the agent architecture needs testing (see "Migration" section); - Decision card "question extent", proactive panel building, and proactive entry enthusiasm are positively correlated with model intelligence—**stronger models make Liyuan stronger**; - Plot text is always the model's original output; Liyuan's code and auxiliary models only process input, structure accounting, and meta-information labeling, without rewriting or supplementing text. ## Developers ``` Domain layer src/ card / lorebook / state / director / retention / scribe / panels / codex / worldline / mcp … (pure TS, independently testable) Connection layer .liyuan/extensions/roleplay.ts Session hooks and all tool mounting points Web layer server/ WS + REST + static hosting; web/ Vite + React front-end Kernel packages/ @liyuan/* (agent runtime, pi fork frozen, file: local dependency) ``` ```bash node --test test/*.test.ts # Domain layer unit tests node scripts/smoke-web.mjs # Web smoke test ``` Product data directories: `.liyuan-state/` (ledger) · `.liyuan-artifacts/` (panels) · `.liyuan-codex/` (knowledge base) · `.liyuan-uploads/` (materials) · `.liyuan-skills/` (skills), all in pure JSON / files, can be backed up and migrated at any time. ## License - Main project uses **[PolyForm Noncommercial 1.0.0](LICENSE)**: open-source, free use, modification, and distribution for personal and non-commercial purposes; **any commercial use—including but not limited to reselling, charging for distribution, and paid hosting services—is not within the license scope**, and commercial authorization should be contacted with the author separately. - `packages/` agent kernel forked from [pi](https://github.com/earendil-works/pi) (MIT, Copyright Mario Zechner), retaining its original protocol and copyright statement (LICENSE in each package directory). ## Friends Link http://linux.do