histrategy 0.2.1__tar.gz

histrategy-0.2.1/.agent/skills/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Agent Contribution Guide — 三國志略
+
+Short-form guide for AI coding agents (Hermes, Claude Code, etc.) working on this project. See root `CONTRIBUTING.md` for the human version.
+
+## Quick-Start for Agents
+
+```bash
+# Install
+pip install -e .
+
+# Run tests (must pass before submitting)
+pytest tests/ -v
+
+# Play-test dev mode
+histrategy --dev
+```
+
+## What Goes Where
+
+| Concern | Location |
+|---|---|
+| LLM integration (prompts, API calls, Game Master) | `histrategy/llm/` |
+| Game engine (turn logic, Plan/Command modes) | `histrategy/engine/` |
+| State management (WorldState, persistence) | `histrategy/state/` |
+| Terminal UI (Rich TUI, dev CLI) | `histrategy/cli/` |
+| Historical knowledge (characters, factions, events) | `histrategy/knowledge/data/` |
+| Tests | `tests/` |
+
+## Code Conventions
+
+- Python 3.10+, type hints on all public functions
+- Google-style docstrings on public API only
+- No comments unless the WHY is non-obvious
+- Imports: stdlib → third-party → first-party, blank line between groups
+- Use `ruff` for linting
+- Use `dict[str, int]` not `Dict[str, int]`
+
+## Architecture Constraints
+
+**DO NOT:**
+- Write Python string templates for advisor speeches, suggestions, consequences, or NPC actions — those come from the LLM
+- Hardcode game data in Python — it lives in `histrategy/knowledge/data/*.json`
+- Skip tests — `pytest tests/` must pass before every commit
+
+**DO:**
+- Use `WorldState` dataclass for all state, with `to_dict()` / `from_dict()` for persistence
+- Keep Plan Mode (council/what-to-do) and Command Mode (execution/how-it-goes) separate
+- Reference `schema.json` before editing any data file
+- Validate data changes: `python histrategy/knowledge/scripts/validate_data.py`
+
+## Data File Editing
+
+When adding to `histrategy/knowledge/data/`:
+
+1. Read `histrategy/knowledge/data/schema.json` first — it defines required fields, types, and allowed values
+2. Use snake_case IDs (e.g. `cao_cao`, `guan_yu`)
+3. Ensure cross-file references are consistent: `characters.faction` → `factions.id`, `factions.ruler_id` → `characters.id`, `regions.neighbors` → `regions.id`
+
+## Key Files to Read Before Starting
+
+- `CLAUDE.md` — project context and architecture requirements
+- `docs/PRD.md` — product vision
+- `docs/tech-design.md` — architecture and data flow
+- `histrategy/llm/game_master.py` — LLM-powered Game Master
+- `histrategy/state/world_state.py` — state data structures
+- `README.md` — overview and quick-start

histrategy-0.2.1/.agent/skills/SKILL.md

@@ -0,0 +1,75 @@
+# SKILL.md — Agent Instructions for 三國志略
+
+Instructions for AI coding agents (Claude Code, Hermes, Cursor, etc.) contributing to this project.
+
+## Project Identity
+
+**三國志略 (Histrategy)** — An open-source, AI-powered text-based Three Kingdoms strategy game. The LLM is the game engine, not a narrator over pre-computed results.
+
+## Agent Workflow
+
+### Before Writing Code
+
+1. Read `CLAUDE.md` for critical architecture context and current priorities
+2. Read `docs/PRD.md` and `docs/tech-design.md` for product vision and architecture
+3. Understand the Plan/Command two-tier architecture before touching engine code
+4. Check `histrategy/knowledge/data/schema.json` before editing any JSON data file
+
+### While Writing Code
+
+- **Test-first**: Write or update tests alongside code changes
+- **LLM-first**: All advisor speeches, suggestions, consequences, and NPC actions come from the LLM layer — never write Python string templates for game content
+- **State-first**: Use `WorldState` dataclasses. All state is serializable via `to_dict()` / `from_dict()`
+- **Minimal changes**: Don't refactor or add abstractions beyond what the task requires. No half-finished implementations.
+
+### Before Submitting
+
+```bash
+# 1. Run full test suite
+pytest tests/ -v
+
+# 2. Validate knowledge base (if data files changed)
+python histrategy/knowledge/scripts/validate_data.py
+
+# 3. Smoke test dev mode
+histrategy --dev --new
+```
+
+## What to Avoid
+
+- **DO NOT** write hardcoded template functions (`_generate_*`, `_format_*`, `_compute_*`) for game narrative
+- **DO NOT** add comments explaining what code does — well-named identifiers do that
+- **DO NOT** add error handling for scenarios that can't happen — trust internal code and framework guarantees
+- **DO NOT** create documentation files unless explicitly requested
+- **DO NOT** use backwards-compatibility shims or keep unused code — delete it
+
+## Project Layout (Quick Reference)
+
+```
+histrategy/engine/       # Game engine (game.py, advisors.py, command.py)
+histrategy/llm/          # LLM layer (game_master.py, adapter.py, prompts.py)
+histrategy/state/        # Game state (world_state.py)
+histrategy/cli/          # Terminal UI (app.py for Rich TUI, dev_cli.py for --dev)
+histrategy/knowledge/    # Historical data (data/*.json, scripts/validate_data.py)
+docs/                    # Design docs (PRD.md, tech-design.md)
+tests/                   # Pytest suite (test_engine.py, test_e2e.py)
+```
+
+## Module Purposes
+
+| Module | Purpose |
+|---|---|
+| `engine/game.py` | Game orchestrator — turn loop, Plan/Command mode dispatch |
+| `engine/advisors.py` | Plan Mode: advisor generation, 4 strategic suggestions |
+| `engine/command.py` | Command Mode: bureaucracy execution, seed system |
+| `engine/offline_sim.py` | Rule-based fallback when no LLM API key |
+| `llm/game_master.py` | LLM-powered Game Master — generates plan mode, command mode, NPC moves |
+| `llm/adapter.py` | Multi-provider LLM client (DeepSeek, OpenAI, Tongyi, OpenRouter) |
+| `llm/prompts.py` | System prompt templates for LLM calls |
+| `state/world_state.py` | `WorldState` / `FactionState` dataclasses with JSON persistence |
+| `cli/app.py` | Rich terminal UI (colors, panels, layout) |
+| `cli/dev_cli.py` | Plain-text dev mode for testing (--dev flag) |
+
+## Commit Style
+
+Follow the existing commit convention: short Chinese + English prefix describing the change (e.g. `H24a: Rich TUI refactor — unified LLM GameMaster display`). Commits are co-authored with the AI agent that produced them.

histrategy-0.2.1/.dockerignore

@@ -0,0 +1,54 @@
+# Python cache
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Game saves
+.histrategy/
+.histrategy-playtest/
+
+# Environment
+.env
+.env.local
+
+# Logs and temp
+logs/
+scratch/
+*.log
+
+# Tests (not needed in production)
+.pytest_cache/
+tests/
+histrategy-engine/tests/
+**/test_*.py
+
+# Git
+.git/
+.gitignore
+
+# Misc
+rooms/
+references/
+publications/
+sprints/
+scripts/
+docs/
+CLAUDE.md
+CONTRIBUTING.md
+README.md
+LICENSE
+.pre-commit-config.yaml
+.ruff_cache/

histrategy-0.2.1/.env.example

@@ -0,0 +1,46 @@
+# ─── LLM Provider Configuration ───────────────────────────────
+# Three-path design — pick ONE of the following approaches:
+#
+# Path 1 (zero-config): Set a provider-specific API key.
+#   The URL and model are auto-configured for you.
+#   Pick ONE:
+DEEPSEEK_API_KEY='sk-...'
+# OPENAI_API_KEY='sk-...'
+# TONGYI_API_KEY='sk-...'
+# OPENROUTER_API_KEY='sk-...'
+#
+#   Optionally override auto-detected settings:
+# LLM_MODEL='deepseek-v4-pro'
+# OPENAI_API_BASE='https://api.deepseek.com'   # override a provider's base URL
+#
+# Path 2 (full control): Set a generic OpenAI-compatible endpoint.
+#   No provider auto-detection — you supply everything.
+# LLM_API_BASE='https://api.openai.com/v1'
+# LLM_API_KEY='sk-...'
+# LLM_MODEL='gpt-4o-mini'
+#
+# Path 3 (legacy): OPENAI_API_BASE + OPENAI_API_KEY
+#   Still supported but Path 2 (LLM_API_BASE + LLM_API_KEY) is preferred.
+
+# ─── Engine Version ────────────────────────────────────────────
+# v1 = original (legacy), v3 = new hybrid engine (recommended)
+HISTRATEGY_ENGINE=v3
+
+# ─── Scenario ──────────────────────────────────────────────────
+# Default scenario ID. Available scenarios:
+#   three-kingdoms  — 三國志略 (AD 207, Cao/Shu/Wu/LiuBiao)
+#   caesar-44bc     — 凯撒余烬 Ashes of Caesar (44 BC, Octavian/Antony/Cleopatra/Senate)
+#   shanhe-dingge   — 山河鼎革 (AD 1644, Ming/Qing transition)
+# HISTRATEGY_SCENARIO=caesar-44bc
+
+# ─── Data Directory ────────────────────────────────────────────
+# Game saves and state (default: ~/.histrategy/)
+# HISTRATEGY_DATA_DIR=~/.histrategy
+
+# ─── Server ────────────────────────────────────────────────────
+# Start the Web UI multiplayer server:
+#   python3 -c "from histrategy.server.api import run_server; run_server(host='0.0.0.0', port=8080)"
+# Then open: http://localhost:8080/mp?scenario=caesar-44bc
+# Or use the CLI:
+#   histrategy
+#   histrategy --dev --faction 2 --new

histrategy-0.2.1/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Game saves
+.histrategy/
+.histrategy-playtest/
+
+# Environment
+.env
+.env.local
+logs
+scratch
+publications
+histrategy.db

histrategy-0.2.1/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.14
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest (unit tests)
+        entry: python -m pytest tests/ -q --tb=short
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-push]
+        minimum_pre_commit_version: 3.0.0

histrategy-0.2.1/CLAUDE.md

@@ -0,0 +1,90 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+三國志略 (Histrategy) is an AI-powered Three Kingdoms strategy game where the LLM acts as the game engine — generating advisor speeches, strategic suggestions, consequences, and NPC actions based on actual world state. Offline/fallback mode uses a rule-based simulation.
+
+## Commands
+
+```bash
+# Install in dev mode
+pip install -e .
+
+# Run the game (auto-detects API key, falls back to offline mode)
+histrategy
+histrategy --dev             # plain-text dev mode
+histrategy --dev --faction 2 --new  # skip faction select, force new game
+
+# Run all tests
+pytest tests/ -v
+
+# Run a specific test file or class
+pytest tests/test_engine.py -v
+pytest tests/test_engine.py::TestSimulation -v
+
+# Lint and format (ruff)
+ruff check .
+ruff format .
+
+# Validate knowledge base JSON data
+python histrategy/knowledge/scripts/validate_data.py
+
+# Pre-push hooks (ruff lint+format, then pytest unit tests)
+pre-commit run --hook-stage pre-push
+```
+
+## Architecture
+
+### Game Flow (Plan/Command two-phase)
+
+```
+Plan Mode (LLM)  →  Player decision (free text)  →  Command Mode (LLM)
+```
+
+- **Plan Mode** — `GameMaster.generate_plan_mode()` generates advisor court + 4 strategic suggestions from LLM
+- **Player** types free-text decision (or `plan` to re-enter plan, `state` to view world, `exit` to quit)
+- **Command Mode** — `GameMaster.generate_command_mode()` generates bureaucracy execution, consequences, NPC reactions, updated world state
+
+### Key Layers
+
+| Layer | Key Files | Responsibility |
+|-------|-----------|----------------|
+| **CLI** | `cli/app.py`, `cli/dev_cli.py` | Rich TUI / plain-text I/O, orchestrates game loop |
+| **Engine** | `engine/game.py`, `engine/offline_sim.py` | GameEngine orchestrator, offline fallback simulation |
+| **LLM** | `llm/game_master.py`, `llm/adapter.py` | GameMaster (Intro/Plan/Command), multi-provider API client |
+| **State** | `state/world_state.py` | `WorldState` dataclass with JSON persistence |
+| **Knowledge** | `knowledge/data/*.json` | Characters, factions, regions, events as structured JSON |
+
+### Two Game Engines
+
+- **`GameEngine`** (in `engine/game.py`) — the primary orchestrator. Uses `GameMaster` (LLM) when an API key is available, otherwise falls back to `offline_sim`.
+- **`GameWorld`** (in `engine/world.py`) — legacy class used only by `offline_sim`. Not used in LLM mode.
+
+### LLM Integration
+
+- **`GameMaster`** (in `llm/game_master.py`) — current unified implementation with game intro, Plan Mode, and Command Mode. Used by `cli/app.py` and `cli/dev_cli.py`.
+
+### LLM Provider Detection
+
+`LLMAdapter` in `llm/adapter.py` auto-detects the best available provider via a three-path design:
+
+1. **Provider-specific key** — Set ONE of `DEEPSEEK_API_KEY`, `OPENAI_API_KEY`, `TONGYI_API_KEY`, or `OPENROUTER_API_KEY`. URL and model are auto-configured.
+2. **Generic endpoint** — Set `LLM_API_BASE` + `LLM_API_KEY`. Use `LLM_MODEL` to override the model.
+3. **No key** → offline (rule-based) mode.
+
+### State Persistence
+
+`WorldState` dataclasses save to `~/.histrategy/` (or `$HISTRATEGY_DATA_DIR`) as JSON. Multiple files track world state, player memory, faction relationships, event history, and character profiles.
+
+### Key Design Rules
+
+- **LLM is the game engine** — advisor speeches, suggestions, consequences, NPC actions come from LLM, not Python templates. Templates only as offline fallback.
+- **State is serializable** — `WorldState` with `to_dict()`/`from_dict()` for persistence and LLM context building.
+- **Plan/Command separation** — Plan = council meeting (what to do). Command = execution (how it goes).
+- **Knowledge lives in JSON** — characters, factions, regions, events are data, not code.
+- **Tests use isolated save dirs** — `HISTRATEGY_DATA_DIR` is monkeypatched to `tmp_path` in tests.
+- **Rules-as-Data (rules in YAML)** — Formula configuration is externalized in YAML templates, parsed by the rules interpreter (supporting diverse era settings).
+- **Asymmetric NPC AI (Fog of War)** — NPCs evaluate threats and plan strategies using projected LocalWorldStates, Heuristics, and LLM Monarch Planners.
+- **AI Playtesting** — Automated multi-agent headless simulations verify game balance and tuning statistics.