docs: update doc and ci/cd

Author: leslieo2

.github/workflows/pr-tests-and-format.yml

@@ -4,23 +4,48 @@ on:
   pull_request:
 
 jobs:
-  lint-and-test:
+  test-backend:
     runs-on: ubuntu-latest
-
     steps:
       - uses: actions/checkout@v4
-
       - name: Set up uv
         uses: astral-sh/setup-uv@v2
         with:
           python-version: "3.12"
-          cache: true
-
       - name: Install dependencies
         run: uv sync --frozen
+      - name: Run pytest
+        run: uv run pytest
 
+  lint-backend:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v2
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: uv sync --frozen
       - name: Check formatting with Black
         run: uv run black . --check
 
-      - name: Run pytest
-        run: uv run pytest
+  build-frontend:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '16'
+      - name: Cache Node.js modules
+        uses: actions/cache@v4
+        with:
+          path: ui-web/frontend/node_modules
+          key: ${{ runner.os }}-node-${{ hashFiles('ui-web/frontend/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+      - name: Install frontend dependencies
+        run: npm install --prefix ui-web/frontend
+      - name: Build frontend
+        run: npm run build --prefix ui-web/frontend

ARCHITECTURE.md

@@ -37,6 +37,10 @@ LieGraph follows a **state machine architecture** built on LangGraph, with clear
 │  │  Identity       │  │  Speech         │  │   Voting    │  │
 │  │  Inference      │  │  Generation     │  │   Logic     │  │
 │  └─────────────────┘  └─────────────────┘  └─────────────┘  │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐  │
+│  │  Strategy       │  │   Speech        │  │   Vote      │  │
+│  │  Coordination   │  │    Tools        │  │   Tools     │  │
+│  └─────────────────┘  └─────────────────┘  └─────────────┘  │
 ├─────────────────────────────────────────────────────────────┤
 │                 Configuration Layer                         │
 │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐  │
@@ -77,9 +81,18 @@ LieGraph follows a **state machine architecture** built on LangGraph, with clear
 - `merge_private_states`: Incremental mindset updates
 - `add`: Append-only operations for immutable records
 
-### 3. AI Strategy (`src/game/llm_strategy.py`)
+### 3. AI Strategy System (`src/game/strategy/`)
+
+**Purpose**: Implements intelligent agent behavior through LLM reasoning with structured tools.
+
+**Core Components**:
+- **Strategy Core (`strategy_core.py`)**: Main coordination for LLM-powered game intelligence
+- **Prompt Builders (`builders/`)**: Context and prompt builders for different game phases
+- **LLM Schemas (`llm_schemas.py`)**: Pydantic models for structured LLM outputs
 
-**Purpose**: Implements intelligent agent behavior through LLM reasoning.
+**Agent Tools (`src/game/agent_tools/`)**:
+- **Speech Tools (`speech_tools.py`)**: Structured reasoning for tone, clarity, and tactical focus
+- **Vote Tools (`vote_tools.py`)**: Evidence-based voting decisions with structured reasoning
 
 **Core Intelligence Systems**:
 - **Dynamic Identity Inference**: Real-time role analysis through conversation patterns
@@ -191,4 +204,21 @@ Next Round or Game End
 ### Reliability
 - **Immutable State**: Append-only records for critical game actions
 - **Error Recovery**: Checkpoint-based state recovery
-- **Validation**: Configuration and state validation at runtime
+- **Validation**: Configuration and state validation at runtime
+
+## Recent Architectural Improvements
+
+### Enhanced Strategy System
+- **Modular Strategy Coordination**: Separated core coordination from prompt builders and LLM schemas
+- **Structured Agent Tools**: Dedicated tools for speech planning and voting decisions with structured reasoning
+- **Improved Serialization**: Enhanced serialization support across strategy modules
+
+### Metrics and Analysis
+- **Historical Aggregation**: CLI tools for aggregating and analyzing game metrics summaries
+- **Quality Scoring**: Deterministic and LLM-based quality evaluation methods
+- **Comprehensive Tracking**: Enhanced metrics collection with detailed game progression analysis
+
+### Development Experience
+- **Test Coverage**: Comprehensive test suite covering game rules, state management, nodes, and agent tools
+- **Code Organization**: Better separation between workflow orchestration and AI intelligence
+- **Error Handling**: Enhanced fallback mechanisms and error recovery strategies

README.md

@@ -14,7 +14,9 @@ LieGraph is a multi-agent implementation of the popular social deduction game "W
 - **Natural Language Interaction:** Agents communicate and reason in natural language throughout the game
 - **Probabilistic Belief System:** Sophisticated belief tracking with self-belief confidence and suspicions matrix
 - **Strategic Reasoning:** Advanced bluff detection, alliance formation, and long-term planning
+- **LLM-driven Strategy:** Structured tools for speech planning and voting decisions
 - **Built-in Metrics:** Automatic quality tracking for win balance, identification accuracy, and speech diversity with JSON reports for prompt evaluation workflows
+- **Historical Analysis:** CLI tools for aggregating and analyzing game metrics summaries
 
 ## 🚀 Quick Start
 
@@ -200,7 +202,9 @@ LieGraph/
 │   │   ├── state.py          # Game state definitions
 │   │   ├── nodes/            # Graph node implementations
 │   │   ├── rules.py          # Game logic and win conditions
-│   │   └── llm_strategy.py   # AI reasoning and speech generation
+│   │   ├── strategy/         # AI strategy coordination and builders
+│   │   ├── agent_tools/      # Structured tools for speech and voting
+│   │   └── metrics.py        # Game metrics and quality scoring
 ├── tests/                    # Pytest test suite
 ├── ui-web/frontend/          # React web interface
 └── config.yaml               # Game configuration

README_zh.md

@@ -15,7 +15,9 @@ LieGraph 是基于 LangGraph 构建的流行社交推理游戏 "谁是卧底" 
 - **自然语言交互:** 智能体在整个游戏中以自然语言进行交流和推理
 - **概率信念系统:** 具有自我信念置信度和怀疑矩阵的复杂信念追踪系统
 - **战略推理:** 高级的虚张声势检测、联盟形成和长期规划
+- **LLM 驱动策略:** 用于发言规划和投票决策的结构化工具
 - **内建指标:** 自动追踪胜率平衡、身份识别准确率与发言多样性，并生成 JSON 报告以供后续提示词评估使用
+- **历史分析:** 用于聚合和分析游戏指标摘要的 CLI 工具
 
 ## 🚀 快速开始
 
@@ -201,7 +203,9 @@ LieGraph/
 │   │   ├── state.py          # 游戏状态定义
 │   │   ├── nodes/            # 图节点实现
 │   │   ├── rules.py          # 游戏逻辑和胜利条件
-│   │   └── llm_strategy.py   # AI 推理和发言生成
+│   │   ├── strategy/         # AI 策略协调和构建器
+│   │   ├── agent_tools/      # 用于发言和投票的结构化工具
+│   │   └── metrics.py        # 游戏指标和质量评分
 ├── tests/                    # Pytest 测试套件
 ├── ui-web/frontend/          # React 网页界面
 └── config.yaml               # 游戏配置