Metadata-Version: 2.4
Name: unframed
Version: 0.1.1
Summary: An unframed AI-driven narrative game - AI builds the world, rules, characters and story from scratch.
Project-URL: Documentation, https://github.com/zaf-x/unframed#readme
Project-URL: Issues, https://github.com/zaf-x/unframed/issues
Project-URL: Source, https://github.com/zaf-x/unframed
Author-email: zaf-x <baoshuwen2013@outlook.com>
License-Expression: MIT
License-File: LICENSE.txt
Keywords: ai,game,llm,narrative,storytelling
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.8
Requires-Dist: colorama>=0.4.6
Requires-Dist: openai>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: textual>=0.41.0
Requires-Dist: zaf-ai-util>=0.4.1
Description-Content-Type: text/markdown

# unframed

[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)]()
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE.txt)
[![Version](https://img.shields.io/badge/version-0.1.0-blue)]()
[![GitHub](https://img.shields.io/badge/GitHub-zaf--x%2Funframed-181717?logo=github)](https://github.com/zaf-x/unframed)

**AI 自举叙事游戏** — AI 从零开始构建世界观、规则、角色与剧情。

## 核心设计

- **AI 是唯一的创世者**：没有硬编码的游戏机制，所有规则由 AI 在运行时自行定义。
- **状态即真相**：游戏世界的唯一状态存储在 `vars` 字典中，AI 通过工具调用显式读写。
- **记忆分层**：核心区 (Pinned) / 活跃区 (Active) / 目录区 (Catalog) 三层显示，防止上下文溢出。
- **元数据锁定**：变量语义 (`meta`) 一旦定义不可覆盖，确保概念一致性。
- **剧情规划**：AI 构建剧情树，提前规划走向，跳过的分支自动修剪。
- **子AI系统**：AI 可创建持久化的 NPC 角色，拥有独立记忆。

## 安装

Python 3.8+ 环境：

```bash
pip install git+https://github.com/zaf-x/unframed.git
```

或克隆后本地安装：

```bash
git clone https://github.com/zaf-x/unframed.git
cd unframed
pip install .
```

## 使用

```bash
# 需要设置 OPENAI_API_KEY 环境变量，或在 TUI 设置页填写
export OPENAI_API_KEY="sk-..."
unframed              # 默认启动 TUI

unframed --cli        # CLI 模式

# 指定模型（支持所有 OpenAI 兼容 API）
unframed --model deepseek-chat

# 自定义 API 地址
unframed --base-url https://api.example.com/v1

# 调整温度（越高越有创意，越低越稳定）
unframed --temperature 0.9

# 加载种子（剧本），自动使用 CLI 模式
unframed --seed seeds/cyberpunk.md

# 继续上次游戏，自动使用 CLI 模式
unframed --continue

# 显示帮助
unframed --help
```

> **注**：使用 `--seed`、`--continue` 或 `--debug` 时会自动切换到 CLI 模式。

## CLI 选项

```
unframed [--api-key API_KEY] [--base-url BASE_URL] [--model MODEL]
         [--temperature TEMP] [--seed SEED] [--continue] [--cli]
         [--debug] [--help]
```

| 选项 | 说明 |
|------|------|
| `--api-key KEY` | API Key（默认读 `OPENAI_API_KEY` 环境变量或配置文件） |
| `--base-url URL` | 自定义 API 地址（默认读 `OPENAI_BASE_URL` 或配置文件） |
| `--model NAME` | 模型名，默认 `gpt-4o`（优先级：参数 > `OPENAI_MODEL` > 配置） |
| `--temperature NUM` | 采样温度 0-2，默认 `0.7`（优先级：参数 > `OPENAI_TEMPERATURE` > 配置） |
| `--seed PATH` | 种子文件路径（Markdown），跳过菜单直接加载（自动 CLI） |
| `--continue` | 继续上次游戏（自动 CLI） |
| `--cli` | 使用 CLI 模式（默认 TUI） |
| `--debug` | 显示工具调用详情（自动 CLI） |
| `--help` | 显示玩家手册 |

设置保存在 `~/.unframed_config.json`（权限 0o600），TUI 中主菜单→"设置"即可修改。

### 环境变量

| 变量 | 说明 |
|------|------|
| `OPENAI_API_KEY` | API Key |
| `OPENAI_BASE_URL` | API 地址（如 `https://api.example.com/v1`） |
| `OPENAI_MODEL` | 模型名（默认 `gpt-4o`） |
| `OPENAI_TEMPERATURE` | 采样温度（默认 `0.7`） |

读取优先级：**CLI 参数 > 环境变量 > 配置文件 > 内置默认**

## TUI 模式

### TUI 界面布局

```
┌──────────────────────────────────────────────────┐
│  U N F R A M E D                      14:30:21   │
├────────────────────────────────┬─────────────────┤
│                                │ ## 角色状态      │
│  叙事区域                       │ - **生命值**: 85 │
│  （AI 的故事输出，Markdown 渲染） │ - **位置**: 断指  │
│                                │   酒吧           │
│                                │                  │
│                                │ ---              │
│                                │ 回合 12          │
├────────────────────────────────┴─────────────────┤
│  AI 正在构思剧情...                                │
├──────────────────────────────────────────────────┤
│  > 输入你的行动...                        [发送]  │
└──────────────────────────────────────────────────┘
```

- **左侧**：叙事输出区，AI 生成的故事以 Markdown 渲染
- **右侧**：角色状态面板 — AI 使用 `show_var` 工具标记为玩家可见的变量
- **底部**：输入框，输入你的行动或对话
- **状态栏**：AI 处理时显示当前操作（如"正在修改世界状态"）

### 启动菜单

| 选项 | 说明 |
|------|------|
| **新建存档** | 输入存档名 → 选择种子 → 开始新游戏 |
| **继续上一个存档** | 直接回到上次玩的存档（仅在有历史时显示） |
| **加载存档** | 从已有存档中选择一个加载 |
| **存档管理** | 查看/保存/删除/重命名所有存档 |
| **设置** | 配置 API Key、模型、温度等 |
| **文档** | 查看玩家手册 |
| **退出** | 退出游戏 |

### TUI 快捷键

| 快捷键 | 功能 |
|--------|------|
| `Enter` | 发送消息 |
| `Escape` | 返回主菜单（当前回合会先自动存档） |
| `Ctrl+S` | 打开存档管理器（Enter=保存，Delete=删除，R=重命名） |
| `Ctrl+L` | 打开读档列表 |
| `Ctrl+D` | 打开删档列表 |

## CLI 模式

### 启动菜单

| 选项 | 说明 |
|------|------|
| **新建存档** | 输入存档名 → 选择种子 → 开始新游戏 |
| **继续上一个存档** | 直接回到上次玩的存档 |
| **加载存档** | 从已有存档中选择一个加载 |
| **帮助文档** | 查看玩家手册 |

### 游戏中命令

| 命令 | 说明 |
|------|------|
| 直接输入 | 你的行动或对话，AI 会推进剧情 |
| `/save` | 打开存档菜单 |
| `/save 我的存档` | 快速存到指定名称（新建或覆盖） |
| `/save list` | 列出所有存档 |
| `/load` | 打开读档菜单 |
| `/load 我的存档` | 快速加载指定名称的存档 |
| `/delete` | 打开删档菜单 |
| `/quit` | 退出游戏 |

## 种子（Seed）

种子是游戏的"剧本文件"，定义了世界观、规则、角色和目标。每个种子由一对文件组成：`seeds/<名称>.json`（元数据）和 `seeds/<名称>.md`（剧本内容）。游戏启动时自动识别 `seeds/` 下所有 `.json` 索引文件。

内置种子：

- **赛博朋克：深渊回响** — 2087 年，永夜之城"新重庆"
- **潮汐监狱** — 2147 年，深海环形海上堡垒
- **锈蚀边境：绿洲协议** — 2147 年，核冬天后的废土求生
- **孤星：坠落日** — 2247 年，殖民船坠毁后的外星求生
- **霓虹裁决** — 2140 年，同步轨道升降梯内
- **循环日** — 无法逃脱的时间循环
- **sudo apt 求生记** — 当 Linux 系统故障出现在神秘世界
- **地下王座** — 地下王国的权力与阴谋

你也可以自己编写种子——参考 `docs/SEED_SPEC.md`。

## 子AI系统（NPC）

unframed 支持 AI 在游戏中创建和管理长期存在的子 AI 角色，作为游戏世界中的 NPC、同伴或组织：

| 工具 | 功能 |
|------|------|
| **创建角色** | AI 可创建拥有独立性格、知识范围和记忆的 NPC |
| **与角色对话** | AI 可与已有 NPC 对话，并根据其性格做出回应 |
| **移除角色** | NPC 死亡或离开时，AI 可终止该角色 |

子 AI 可以读取世界状态变量了解当前局势，但不能直接修改它们。它们拥有独立对话记忆，会记住每一次交流。玩家通过主 AI 的叙事感知子 AI 的行为，子 AI 不直接与玩家交互。

## 存档

存档文件存储在 `~/.unframed_saves/` 目录，每局一个 UUID 文件（`{uuid}.json`）。

- **自动保存**：每轮自动保存到当前存档
- **继续存档**：主菜单"继续上一个存档"可直接回到上次的游戏
- **存档管理**：TUI 中 `Ctrl+S` 可保存/重命名/删除/新建存档
- **存档内容**：回合数、变量数据库、对话历史、剧情树、子 AI 状态

## 开发

```bash
git clone https://github.com/zaf-x/unframed.git
cd unframed
pip install -e .
```

运行测试：

```bash
pip install pytest
python -m pytest tests/
```

## 架构

```text
src/unframed/
├── __about__.py   — 版本信息
├── __init__.py    — 公共 API
├── engine.py      — 核心引擎：状态管理、工具定义、Prompt 组装、游戏循环
├── cli.py         — 交互式 CLI 入口（启动菜单、命令行命令）
├── settings.py    — 持久化配置（~/.unframed_config.json）
├── render.py      — BBCode → ANSI 渲染器
└── tui/
    ├── __init__.py — TUI 模块声明
    └── app.py      — Textual TUI 前端（图形界面）
```

基于 [ai-util](https://github.com/zaf-x/ai-util) 框架。

## License

`unframed` 基于 MIT 协议开源。
