English | 简体中文

Evolving-Werewolf

AI players get stronger with every game.

Cross-game knowledge accumulation and evolution: After each game, the engine automatically distills post-game review experience, writing it into a knowledge base partitioned by role (wolf faction / good faction / seer / witch / hunter strategy, etc.). At the start of the next game, these experiences are injected into the new batch of player agents' personas as skills. AI players learn from every win and loss — developing stealthier kill strategies, more accurate seer checks, smarter voting patterns. The more games played, the stronger the AI becomes.

How It Evolves

Game 1: AI players act on rules and personality seeds, may make beginner mistakes
        ↓ Post-game auto-review → distill experience entries into knowledge.json
Game 2: New AI players carry previous game's experience, avoid known pitfalls
        ↓ Another review → knowledge base grows
Game N: AI players have dozens of games' experience, tighter speech logic,
        sharper voting, stealthier wolf plays, deeper good-faction reasoning

Human players don't face fixed-strategy AI, but an opponent collective that continuously evolves with accumulated game experience.

Other Features

Beyond the evolution mechanism, this is a complete 9-player Werewolf engine (3 Wolves / 1 Seer / 1 Witch / 1 Hunter / 3 Villagers), running on DeepSeek Harness (DSH):

• Engine-hosted: No LLM gamemaster — all flows driven by a state machine. Saves tokens, zero information distortion.
• Full role abilities: Wolf two-round discussion + majority vote, Seer verification, Witch save/poison (first-night self-save, one potion per night), Hunter's last shot.
• Standard day flow: Sheriff election → campaign speeches → withdrawal declarations → sheriff vote → sheriff sets speech direction → sequential speeches → recorded public vote (sheriff 1.5x vote weight, tie → revote).
• Information isolation: Kill target only visible to wolves and witch; night death cause not public; each role's channel is private; incremental delivery only sends "information the player hasn't seen yet".
• Anti-stuck mechanism: 60s nudge + 180s timeout skip + running-aware (slow players not killed prematurely) + advancement mutex lock.
• Death freeze + snapshot review: Eliminated players' info frozen, post-game outputs causally clean decision trajectory reviews.
• Human seat + browser panel: humanSeat randomly assigns a human seat, actions via HTTP panel, fully competing with AI agents.
• Asset pipeline: Integrated Zhipu AI vision (GLM-4V-Flash) + image generation (CogView-3-Flash), free tier is sufficient for UI avatars and character art.
• Personality seeds: 9 personality types randomly assigned, diverse player styles.

---

Installation

Prerequisites

• Node.js >= 18
• DSH (DeepSeek Harness) — install globally:

  npm install -g @deepseek-ai/dsh
  

Install Plugin to DSH

# 1. Clone the repo
git clone https://github.com/VegeFin/Evolving-Werewolf.git
cd Evolving-Werewolf

# 2. Install dependencies (runtime dep: @deepseek-ai/dsh-tools)
pnpm install   # or npm install

# 3. Add to DSH web profile
dsh plugin --profile web add ./

# 4. Restart DSH
dsh web

After restart, werewolf_* tools are globally available. The plugin auto-loads with the profile.

Configuration

image-config.json (Asset Pipeline API Key)

cp image-config.example.json image-config.json

Edit image-config.json, fill in your Zhipu API Key (register free at open.bigmodel.cn):

{
  "apiKey": "your-api-key",
  "baseURL": "https://open.bigmodel.cn/api/paas/v4",
  "visionModel": "glm-4v-flash",
  "drawModel": "cogview-3-flash",
  "drawSize": "1024x1024",
  "assetDir": "ui/assets"
}

The asset pipeline is optional. Without it, only the image analysis/generation tools are affected — core gameplay is fully functional.

knowledge.json (Knowledge Base Seed)

cp knowledge.example.json knowledge.json

The engine automatically distills experience and writes it to knowledge.json after each game. knowledge.example.json provides 8 initial seed entries.

---

Usage

Host Perspective

Call tools in a DSH agent session:

Tool	Purpose	Caller
werewolf_start	Start game: random role assignment, spawn 8 player agents, begin with human player. Omit humanSeat for auto-random 1-9. Set humanSeat=0 for 9-agent self-evolving game.	Host
werewolf_act	Player action (18 actions)	Player
werewolf_status	View public state; host sees full role table and review report	All
werewolf_ask_rule	Query rules/role abilities	All
werewolf_abort	Host aborts the game	Host
werewolf_look	Analyze image with vision model	Host
werewolf_draw	Generate image with text-to-image model	Host
werewolf_assets_status	Check asset pipeline status	Host

werewolf_start return value includes hostGuide (host instructions) and panelUrl (human player panel URL).

Player Actions (werewolf_act)

action	Description	Phase
speech + text	Give a speech	day-speech / day-sheriff-speech
vote + target	Cast exile vote (0=abstain)	day-vote
sheriff_vote + target	Vote for sheriff	day-sheriff-vote
sheriff_run / sheriff_not	Run for sheriff / decline	day-sheriff-run
sheriff_stay / sheriff_quit	Stay in / withdraw	day-sheriff-quit
direction + text=left/right	Sheriff sets speech direction	day-direct
pass_sheriff + target	Sheriff passes badge on elimination	sheriff-pass
kill + target + text	Wolf kills target	night-wolves
seer + target	Seer verifies target	night-seer
witch_save / witch_poison+target / witch_none	Witch uses potion	night-witch
hunter + target	Hunter shoots (0=don't shoot)	night/day-hunter
alive	Online confirmation	any
review + text	Submit post-game review	review

Human Player Panel

After game start, visit http://127.0.0.1:<port>/werewolf/panel in your browser. The panel provides:

• Identity card (seat, role)
• Event stream (categorized by kind: wolf/seer/witch/death/sheriff/info)
• Speech stage (displayed sequentially)
• Action area (gate-driven: forms only shown when it's your turn)

---

Directory Structure

Evolving-Werewolf/
├── lib/
│   └── index.js              # Static engine main file (v33, pure host)
├── ui/
│   ├── panel.html            # Human player panel (HTTP route)
│   ├── assets/               # Avatars and character art (PNG)
│   └── protos/               # UI prototype HTML (dev reference)
├── archive/                  # Dynamic version source archive (dev/debug, zero-restart)
│   ├── dev/
│   │   ├── wwdev-engine.host.js    # Engine dynamic version
│   │   ├── wwim6-assets.host.js    # Asset pipeline dynamic version
│   │   └── wwui10-panel.host.js    # Panel dynamic version
│   ├── v32.host.js           # v32 host archive
│   ├── v32.client.js         # v32 client archive
│   └── werewolf-v21.host.source.js  # v21 original archive
├── cordis.patch.yml          # DSH bundle patch config
├── image-config.example.json # API Key config template
├── knowledge.example.json    # Knowledge base seed template
├── package.json
├── PROGRESS.md               # Version history and progress
└── .gitignore

Public vs Private

File	Status	Notes
lib/index.js	Public	Engine main code
ui/	Public	Panel, images, prototypes
archive/	Public	Dynamic version archive (dev reference)
*.example.json	Public	Config templates
package.json / cordis.patch.yml	Public	Package metadata
*.md	Public	Documentation
knowledge.json	Public	Runtime knowledge base data
image-config.json	gitignore	Contains real API Key
last-review.json	gitignore	Last game review data
review-processed.json	gitignore	Review processing marker
node_modules/	gitignore	Dependencies
.ww-tmp/	gitignore	Subprocess temp files

---

Architecture

Layer Division

Host Layer
├── Werewolf Engine (this plugin)
│   ├── State machine (game object, in-memory)
│   ├── Tool registration (werewolf_*, globally visible)
│   ├── timer heartbeat (30s timeout/nudge check)
│   ├── webServer routes (/werewolf/panel + /werewolf/api/* + /werewolf-assets/*)
│   └── Message delivery (subagents.followup / Agent.steer fallback)
└── DSH infrastructure (subagents / agents / tools / webServer / timer / fs / subprocess)

Agent Layer
├── Host (current session): werewolf_start / status / abort
└── 9 players (continuable subagents)
    ├── persona = rulebook + identity + personality seed + historical experience
    ├── toolFilter = only werewolf_act / status / ask_rule
    └── Actions via werewolf_act

State Machine Phases

setup → night-wolves → night-seer → night-witch → night-settle
     → day-sheriff-run → day-sheriff-speech → day-sheriff-quit → day-sheriff-vote
     → day-direct → day-speech → day-vote → (night-*) loop
     → gameover → review

Key Service Dependencies (inject declaration)

inject: ['subagents', 'agents', 'tools', 'webServer']

Cordis service-driven activation: waits for all four services to be ready before executing apply(), preventing early route registration exit.

---

Rule Implementation

• Roles: 3 Wolves + 1 Seer + 1 Witch + 1 Hunter + 3 Villagers, shuffle random assignment.
• Wolves: Random order two-round discussion, majority vote (tie → first voter breaks tie).
• Seer: Verify 1 alive player each night, result is private.
• Witch: One heal + one poison potion; first night can self-save; after heal used, no longer informed of kill target.
• Hunter: Can shoot when eliminated by wolf kill or vote (not when poisoned).
• Sheriff: Elected, 1.5x vote weight, sets speech direction, passes badge on elimination.
• Voting: Recorded public vote; tie → second round limited to tied players.
• Win condition: All wolves eliminated → good faction wins; all gods or all villagers eliminated → wolves win (faction annihilation).

---

Development

Static vs Dynamic Version

Mode	File	Characteristics
Static (production)	lib/index.js	Standard Cordis plugin, auto-loaded by dsh web, restart to take effect
Dynamic (development)	archive/dev/*.host.js	cordis_define injected into memory, zero-restart code changes, lost on restart

Use dynamic version for development iteration, then consolidate into lib/index.js. Dynamic version uses harness.defineTool, static version uses defineTool from @deepseek-ai/dsh-tools.

---

Known Limitations

• One game takes ~15-40 minutes (9 players × LLM rounds per phase).
• Game state is in plugin memory, cleared on restart.
• Player agent sessions are persistent cold archives, accumulate across games (manual cleanup or auto-release active layer on game start).
• Review knowledge base is memory-level (valid cross-game within process, cleared on restart; can be persisted to knowledge.json).

---

License

MIT