Liyuan

Name: Liyuan
Author: weidu12123

by weidu12123

Warning

梨园 Liyuan — 以 rp agent为主体的ai角色扮演应用

287stars

43forks

TypeScript

Added 7/28/2026

Installation

# Add to your Claude Code skills
git clone https://github.com/weidu12123/Liyuan

Getting Started

Guides for using ai agents skills like Liyuan.

Caveman: Cut Claude Token Use by 65%
How agent-side prompt compression works, when to use it, and when not to.
What is an AI Skills Marketplace?
Definitions, how marketplaces work, and how to choose between them in 2026.
Getting Started with AI Skills

Security ReportWarning

Last scanned: 7/29/2026

{
  "issues": [
    {
      "type": "npm-audit",
      "message": "@hono/node-server: Node.js Adapter for Hono: Path traversal in `serve-static` on Windows via encoded backslash (`%5C`)",
      "severity": "medium"
    },
    {
      "type": "npm-audit",
      "message": "@modelcontextprotocol/sdk: Vulnerability found",
      "severity": "medium"
    },
    {
      "type": "npm-audit",
      "message": "brace-expansion: brace-expansion: DoS via unbounded expansion length causing an out-of-memory process crash",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "fast-uri: fast-uri vulnerable to host confusion via literal backslash authority delimiter",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "playwright: Playwright downloads and installs browsers without verifying the authenticity of the SSL certificate",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "postcss: PostCSS: Path Traversal in Previous Source Map Auto-Loading (sourceMappingURL) leads to Arbitrary .map File Disclosure",
      "severity": "high"
    },
    {
      "file": "README.md",
      "line": 100,
      "type": "remote-install",
      "message": "Install command (remote install script piped to a shell — review the source before running): \"curl -fsSL https://raw.githubusercontent.com/weidu12123/Liyuan/v1.0.0/deploy/ins\"",
      "severity": "low"
    }
  ],
  "status": "WARNING",
  "scannedAt": "2026-07-29T06:31:05.079Z",
  "npmAuditRan": true,
  "pipAuditRan": true,
  "promptInjectionRan": true
}

Compare with similar skills

See how Liyuan compares with popular alternatives.

Liyuan vs hermes agent

See comparison

Liyuan vs rea

See comparison

Liyuan vs ecc

See comparison

README.md

Frequently Asked Questions

What is Liyuan?

Liyuan is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by weidu12123. 梨园 Liyuan — 以 rp agent为主体的ai角色扮演应用. It has 287 GitHub stars.

Is Liyuan safe to use?

Liyuan returned warnings in SkillsLLM's automated security scan. It has no critical vulnerabilities, but review the flagged issues in the Security Report section before adding it to your workflow.

How do I install Liyuan?

Clone the repository with "git clone https://github.com/weidu12123/Liyuan" and add it to your Claude Code skills directory (see the Installation section above).

What programming language is Liyuan written in?

Liyuan is primarily written in TypeScript. It is open-source under weidu12123 on GitHub, so you can review or fork the full source.

Are there alternatives to Liyuan?

Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh Liyuan against similar tools.

AI Courses · Agentic AI, LLM Engineering & MCP

Beginner to professional · First lesson free · Lifetime access

20% off

Comments (0)

to leave a comment.

No comments yet. Be the first to share your thoughts!

Related Skills

rea

by morluto

Reverse engineer anything with agents, from app behavior down to native binaries.

386,883

anyclaude UnityAgentClient

English · 简体中文

Liyuan (梨园)

An RP Agent built on pi, bringing coding agent superpowers to role-playing.

📖 Documentation · 🚀 Releases · 🌐 Website

Liyuan Main Interface

What is Liyuan?

Liyuan (梨园) is a next-generation Role-Play Agent built on top of pi. By reimagining coding agent primitives for creative storytelling and roleplay, Liyuan tackles the chronic limitations of traditional RP frontends—such as context bloat, setting drift, ungrounded hallucination, prompt clutter, and vendor lock-in—delivering an immersive, transparent, and deterministic role-playing experience.

The RP Paradigm: Coding Agent Primitives Reimagined

Liyuan's core architecture translates proven software engineering agent paradigms directly into roleplay mechanics:

Coding Agent Primitive	Liyuan RP Equivalent	Description
Workspace / cwd	Isolated Card Space	One directory per character card, isolating assets, sessions, memory, and state
Code	Story Prose	The narrative text treated as living creative output
Edit / Patch	In-Place Targeted Revisions	Surgical prose edits and adjustments without regenerating entire paragraphs
Grep / Search	Text & Lore Retrieval	On-demand search across lorebooks and past chapters without bloating context
Rewind / Checkpoint	Branch Rollback & Revision	Non-destructive story branching and checkpoint restore for alternate storylines
Context Compaction	Narrative Compaction (Story Recap)	Summarizing past chapters into faithful story recaps while keeping recent prose pristine
Cross-Session Memory	Card-Level Memory & Forgetting	Per-card consolidation across sessions with synchronized physical forgetting
Permission Gate	Narrative Fork Decision Cards	Interactive decision prompts (`ask` tool) at crucial plot junctures for user choice
SYSTEM.md / AGENTS.md	Engine Protocols & World Laws	Fully transparent, file-based prompt layers with modular toggles

Key Capabilities

1. Advanced Memory Architecture

Pristine Context & Narrative Compaction: The harness deterministically filters intermediate thought processes and noise, compiling lengthy dialogues into coherent story recaps.
Real-Time State Ledger & Cast Roster: A sidecar ledger automatically tracks in-universe time, locations, items, and character presence to prevent setting drift across turns.
On-Demand Lorebook Retrieval: Worldbooks and knowledge bases remain outside the active prompt window until the model explicitly queries them, keeping the context window light and focused.
Card-Level Cross-Session Memory & Physical Forgetting: Session debriefs automatically merge into persistent card memory; deleting a conversation physically triggers true forgetting of associated facts.

Character Profile & Cast Roster

2. High Customizability & Co-Creation

Layered Prompt Architecture: Exposes SYSTEM.md (engine protocol) and AGENTS.md (world rules and character lore) for transparent, file-level editing with entry-by-entry toggles.
Collaborative Card Workshop & Sandbox: Built-in card studio and work mode allow users and the Agent to co-author, debug, and preview character cards and custom front-end scripts in a secure sandbox.

Split-view Card Studio

3. Portability & Zero Vendor Lock-In

Physically Portable Card Spaces: Each card is an independent workspace containing its own sessions, state, and memory. Simply copy the card folder across machines and pick up right where you left off.
Universal Format Support: Full interoperability with standard Tavern / Character Card V2 & V3 formats, lorebooks, and chat histories without platform restrictions.
Transparent Local File Storage: All data is saved as plain text JSON and Markdown. Zero black-box databases—effortless backup, versioning, and inspection.

4. Deep User Immersion

Interactive Plot Junctions: At pivotal narrative moments, the Agent uses the ask tool to present branching choices and free-form inputs, co-authoring the story with you.
Intent-Driven Prose Editing: Request subtle adjustments or line replacements directly, eliminating the need to discard and regenerate entire paragraphs.

Quick Start

For complete visual guides and interface walkthroughs, see the Liyuan Documentation (docs.liyuan.pro).

Requirements

Node.js ≥ 22
Any OpenAI-compatible API key (e.g., DeepSeek, OpenAI, Claude via proxy, etc.)

Running Locally

# Copy example configuration files
cp liyuan.agent.example.json liyuan.agent.json
cp liyuan.config.example.json liyuan.config.json

# Edit liyuan.agent.json to set your apiKey, baseURL, and model ID

# Install dependencies and start
npm install
npm run web:build    # Build frontend (can be skipped if web/dist already exists)
npm run web          # Launch server

Windows: Double-click start.bat
Linux / macOS: Run chmod +x start.sh && ./start.sh
Open http://127.0.0.1:7620 in your browser.

Security Note: Port 7620 does not enforce authentication by default. Do not expose it directly to the public internet without a reverse proxy and authentication layer.

Deployment

Docker Compose

git clone --depth 1 https://github.com/weidu12123/Liyuan.git && cd Liyuan
docker compose up -d --build

Data and configurations persist in local mapped volumes.

You can also use prebuilt multi-arch images directly from GHCR without building from source:

mkdir -p liyuan && cd liyuan
curl -fsSL -o docker-compose.yml https://raw.githubusercontent.com/weidu12123/Liyuan/master/deploy/compose.ghcr.yml
docker compose up -d

Architecture & Development

Domain Layer    src/                        Character cards, lorebooks, staging, memory, timelines
Wiring Layer    .liyuan/extensions/roleplay.ts   pi extension hooks and tool registrations
Web Layer       server/ + web/             Backend orchestration, WebSocket/REST protocols, and Web UI
Core Layer      packages/@liyuan/*         Locally maintained pi agent core framework

Running unit tests:

node --test test/*.test.ts

License

The main project is licensed under the PolyForm Noncommercial 1.0.0 license: Free for personal and non-commercial use, modification, and distribution. Any commercial use requires prior authorization from the author.
Core agent modules are derived from pi (MIT License), maintaining all original copyright notices.

Community & Links

Documentation: docs.liyuan.pro
Community Forum: linux.do