三國志略 (Histrategy) — Agent 游戏技能

AI 驱动的三国策略游戏。LLM 扮演谋士、将领、NPC 君主， 玩家用自然语言下达指令，运筹帷幄，逐鹿中原。

触发条件

当用户在 IM 中触发以下任一关键词时加载本技能：

明确命令：

• /histrategy — 查看游戏状态或开始新游戏
• /new \x3C势力> — 开始新游戏（shu/cao/wu）
• /do \x3C决策> — 执行回合
• /plan — 获取谋士建议
• /status — 查看当前资源

三国话题关键词（自动检测用户意图）：

• 三国、建安、赤壁、官渡、荆州、汉中、许昌、成都、建业、洛阳
• 曹操、刘备、孙权、诸葛亮、关羽、张飞、赵云、司马懿、周瑜、吕布
• 魏、蜀、吴、曹魏、蜀汉、东吴
• 下一回合、出兵、发展、外交、招兵、买粮、进攻、结盟

安装

从 PyPI（推荐）

pip install histrategy-sdk

从 GitHub 源码

git clone https://github.com/emergencescience/histrategy
cd histrategy
pip install -e .

配置 LLM API Key

export DEEPSEEK_API_KEY="sk-..."   # 推荐，性价比最高
# 或
export OPENAI_API_KEY="sk-..."
# 或
export TONGYI_API_KEY="sk-..."

不配置 Key 则自动使用离线规则模式（无 LLM 叙事，但可正常游玩）。

核心设计：纯文件存储

游戏状态完全基于文件，不使用内存，不依赖网络：

~/.histrategy/rooms/
  \x3C房间名>/
    world_state.json    # 完整游戏世界状态
    turns.jsonl         # 追加式回合日志
    metadata.json       # 元数据

每次回合流程：

1. 从 world_state.json 读取游戏状态
2. 执行玩家决策（LLM 生成叙事 + 规则引擎计算结果）
3. 将新状态写回 world_state.json
4. 追加回合记录到 turns.jsonl

这意味着即使 Agent 的 context 每天被清空，游戏进度也不会丢失。 下次加载时只需 Room.load(房间名) 即可恢复。

IM 机器人实现

基本模式

from histrategy_sdk import Room

# 用平台前缀 + 聊天 ID 生成唯一房间名
def get_room_name(platform: str, chat_id: str) -> str:
    return f"{platform}-{chat_id}"

def handle_message(platform: str, chat_id: str, text: str) -> str | None:
    """处理用户消息，返回游戏回复。返回 None 表示不处理。"""

    # 开始新游戏
    if text.startswith("/new"):
        faction = text.split()[1]  # shu / cao / wu
        room = Room.create(get_room_name(platform, chat_id), faction=faction)
        intro = room.intro()
        return intro["narrative"]

    # 执行回合
    elif text.startswith("/do"):
        decision = text[4:]  # 玩家的自然语言决策
        room = Room.load(get_room_name(platform, chat_id))
        result = room.play(decision)
        return format_turn(result)

    # 谋士建议
    elif text == "/plan":
        room = Room.load(get_room_name(platform, chat_id))
        plan = room.plan()
        suggestions = "\
".join(f"• {s}" for s in plan["suggestions"])
        return f"**谋士献策**\
{suggestions}"

    # 查看状态
    elif text == "/status":
        room = Room.load(get_room_name(platform, chat_id))
        s = room.status()
        return f"⚔️兵力:{s['strength']} 🍚粮草:{s['food']} 💰库金:{s['treasury']} ❤️士气:{s['morale']}"

    return None

格式化回合结果

def format_turn(result: dict) -> str:
    """将 TurnResult 格式化为 IM 消息。"""
    fs = result["faction_status"]
    lines = [
        f"## {result['year']}年{result['season']} · 第{result['turn']}回合",
        result["narrative"],
        f"\
⚔️兵力:{fs['strength']} 🍚粮草:{fs['food']} 💰库金:{fs['treasury']} ❤️士气:{fs['morale']}",
    ]
    # 谋士建议
    if result.get("new_suggestions"):
        lines.append("\
**谋士献策**:")
        for s in result["new_suggestions"][:3]:
            title = s.split("—")[0].strip()[:60]
            lines.append(f"  • {title}")
    # NPC 动向
    if result.get("npc_actions"):
        lines.append("\
**天下大势**:")
        for action in result["npc_actions"][:5]:
            lines.append(f"  • {action}")
    return "\
".join(lines)

多人模式

# 三人群聊，各选一势力
shu = Room.create("lobby-xxx/shu", faction="shu")
cao = Room.create("lobby-xxx/cao", faction="cao")
wu  = Room.create("lobby-xxx/wu",  faction="wu")

# 蜀汉玩家
result = shu.play("联吴抗曹，派诸葛亮出使东吴")

# 曹魏玩家
result = cao.play("先发制人，南下攻打荆州")

可用势力

注意： faction 参数只能是 shu、cao、wu。不要用 wei、liubei、sunquan。

API 参考

Room 类

TurnResult 字段

游戏规则要点

• 回合制：每回合 = 一个季节。春→夏→秋→冬
• 资源：兵力、粮草、库金、士气。粮草不足则兵力下降
• 内政：发展商业（增收入）、开垦农田（增粮产）、招募乡勇（增兵力）
• 军事：出征、防守、奇袭
• 外交：结盟、离间、劝降
• NPC 势力：AI 控制的其他势力会自主行动，相互征战

常见问题

源码与社区

• GitHub: https://github.com/emergencescience/histrategy
• PyPI: https://pypi.org/project/histrategy-sdk/
• Web 版: https://emergence.science/play/histrategy