分布式AI工具平台

cd python-server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

#!/bin/bash
# Usage: source set_OPENROUTER.bat

export OPENROUTER_API_KEY="sk-or-v1-your-key-here"

echo "OPENROUTER_API_KEY has been set"

source venv/bin/activate
source set_OPENROUTER.bat
source set_ANTHROPIC.bat      # if using Anthropic models
source set_GOOGLE.bat         # if using Google APIs

python server.py  \
  --email=youremail@gmail.com  \             # email you use for flowcentral
  --api-key=foobar \                         # should change online
  --host=localhost \                         # npx MCP will be looking here to connect to remote (assumes there is at least one running locally)
  --port=8000  \
  --cloud-host=wss://flowcentral.ai  \   # points to cloud
  --cloud-port=443  \
  --service-name=home                        # remote name, can be anything but must be unique across all machines

   "mcpServers": {
      "atlantis": {
         "command": "npx",
         "args": [
            "atlantis-mcp",
            "--port",
            "8000"
            ]
      }
   }

dynamic_functions/
├── Home/                    # App: "Home"
│   └── atlas.py
├── Accounting/              # App: "Accounting"
│   ├── accounting.py
│   └── foo.py
└── FilmFromImage/          # App: "FilmFromImage"
    └── qwen_image_edit_local.py

dynamic_functions/
└── MyApp/
    └── SubModule/
        └── Feature/
            └── my_function.py

# If you have these functions:
# - dynamic_functions/Chat/send_message.py
# - dynamic_functions/Email/send_message.py
# - dynamic_functions/SMS/send_message.py

send_message              ❌ Ambiguous! Which one?
**Chat**send_message      ✅ Clear! The one in Chat
**Email**send_message     ✅ Clear! The one in Email

update_image                          → Simple call (only works if unique)
**MyApp**update_image                 → Specify app to disambiguate
**MyApp/SubModule**process_data       → Nested app path
alice*prod*Admin**restart             → Full routing: owner + remote + app + function
***office*print                       → Just location context

# File: dynamic_functions/ImageTools/process.py
@visible
async def update_image(image_path: str):
    """Update an image."""
    return "updated"

# If this is the ONLY update_image:
update_image                          ✅ Works fine!

# If Chat app ALSO has update_image:
**ImageTools**update_image            ✅ Now we need to specify the app

Games/FlowCentral/                   # Game definition
├── Bots/                            # Bot personas for this game
│   ├── Atlas/
│   │   ├── config.json              # Model, provider, greeting, handler references
│   │   ├── system_prompt.md         # Base system prompt (markdown)
│   │   ├── prompt.py                # System prompt builder with context injection
│   │   ├── main.py                  # Index placeholder
│   │   └── atlas_face.jpg           # Bot avatar
│   └── Celeste/                     # Executive concierge
│       ├── config.json
│       ├── system_prompt.md
│       ├── prompt.py
│       ├── main.py
│       └── celeste_face.jpg
├── Locations/                       # Rooms players can move between
│   ├── Lobby.json                   # Location metadata + adjacency
│   ├── Lobby.jpg                    # Background image
│   ├── Lounge.json
│   └── Lounge.jpg
└── Roles/                           # NPC role definitions
    ├── Greeter/                     # Atlas's role
    │   ├── system_prompt.md         # Role-specific system prompt
    │   └── prompt.py
    └── Concierge/                   # Celeste's role
        ├── system_prompt.md
        └── prompt.py

Home/                                # Shared bot + game runtime
├── main.py                          # Entry point: index(), show_tools()
├── game.py                          # Game state: game_set(), game_show(), game_list()
├── bot.py                           # Bot listing with thumbnails, bot_spawn()
├── character.py                     # Character CRUD, roles, role_list()
├── location.py                      # Locations, positions, movement: move_bot(), move_human(), go(), look()
├── camera.py                        # Per-game camera location tracking
├── map.py                           # Interactive visual map of locations
├── common.py                        # Shared helpers: bot config, thumbnails, game data I/O
├── chat.py                          # Bot chat runtime: BotChatContext, dispatch_chat, system prompt builder
├── chat_callback.py                 # Routes room chat to correct bot, interaction tracking
├── chat_common.py                   # Transcript fetch, tool discovery, pseudo-tools (search, dir, todo)
├── turn.py                          # Multi-turn LLM conversation loop with tool calls
├── todo.py                          # Per-session todo pseudo-tool for bot task tracking
├── GAME.md                          # ER diagram of the game data model
├── MULTIX.md                        # User-facing CLI documentation
└── README.py                        # Serves MULTIX.md and GAME.md via MCP

Data/
├── main.py                          # Index placeholder, imports list_games from Home/common
└── {game_id}/                       # Per-game data (created at runtime)
    ├── characters.json              # Bot and human role assignments
    ├── positions.json               # Current location of each character
    ├── camera.json                  # Current camera location
    ├── bot_interactions.json        # Per-bot interaction history (timestamps, counts)
    └── api_payload.json             # Debug: last LLM API payload

tail -1000 python-server/runServer.log

Chat: session=X request=X game=X caller=admin        ← callback fired
Transcript fetched in 0.05s (12 raw, 8 filtered)      ← got conversation history
Game X: bot=atlas role=Greeter location=Lobby          ← found the bot
=== HANDING OFF TO Atlas (Greeter at Lobby) ===        ← dispatching to LLM
Sending to minimax/minimax-m2.7: 5 messages, 3 tools  ← API call
Stream opened in 0.8s                                  ← LLM responding
Stream done: turn=1 chunks=42 tool_calls=0             ← response complete

{
  "sid": "yourbot",
  "displayName": "YourBot",
  "image": "yourbot_face.jpg",
  "provider": "openrouter",
  "model": "minimax/minimax-m2.7",
  "baseUrl": "https://openrouter.ai/api/v1",
  "apiKeyEnv": "OPENROUTER_API_KEY",
  "chatHandler": "dynamic_functions.Home.chat.handle_chat_completions",
  "systemPrompt": "system_prompt.md",
  "greeting": "Hi, I'm YourBot."
}

You are YourBot, a [description of role and personality].

[Instructions for behavior, tone, tools, etc.]

import atlantis
import logging

logger = logging.getLogger("mcp_server")

@visible
async def index():
    """YourBot — [role description]."""
    pass

You are stationed at [location]. Your job is to [role description].

import atlantis
import logging

logger = logging.getLogger("mcp_server")

@visible
async def index():
    """YourRole — [description]."""
    pass

{
  "name": "YourLocation",
  "description": "A brief description of this location.",
  "image": "YourLocation.jpg",
  "connects_to": ["Lobby"]
}

character_bot("yourbot", "YourRole")

await game_move_bot("yourbot", "YourLocation")

await spawn_bot("yourbot")

await game_set("FlowCentral")           # Lock server to the game (once per server)
character_bot("yourbot", "YourRole")     # Assign bot to role
await game_move_bot("yourbot")           # Enter the default lobby
await spawn_bot("yourbot")               # Show face + greeting

await game_set("FlowCentral")
await bot_spawn("yourbot", "YourRole", "Lobby")

User types message
    │
    ▼
chat_callback.py  ← @chat decorator fires on any chat message
    │
    ├─ Fetches the transcript (raw + filtered)
    ├─ Finds the last speaker's SID
    ├─ Looks up their position (which room they're in)
    ├─ Queries who else is in that room
    ├─ Finds the first bot present with a valid config
    │
    ▼
chat.py  ← builds BotChatContext, calls dispatch_chat()
    │
    ├─ Loads the bot's config.json (model, provider, system prompt path)
    ├─ Loads the system prompt from the bot's folder
    ├─ If prompt.py exists, runs the prompt builder to inject interaction context
    │   (time of day, returning visitor detection, first name, interaction count)
    ├─ Builds the tool list (search, dir, todo pseudo-tools + any custom tools)
    ├─ Creates the OpenAI client using the bot's provider/API key
    │
    ▼
turn.py  ← runs the multi-turn LLM conversation loop
    │
    ├─ Sends system prompt + transcript + tools to the LLM
    ├─ Streams the response (thinking → text → tool calls)
    ├─ If the LLM calls a tool:
    │   ├─ search/dir/todo → handled as pseudo-tools (no MCP round-trip)
    │   └─ real tools → executed via atlantis.client_command()
    ├─ Appends tool results to transcript, loops back to LLM
    ├─ Repeats up to 10 turns until LLM responds with just text
    │
    ▼
chat_callback.py  ← records the interaction
    │
    ├─ Saves interaction count + timestamp to bot_interactions.json
    └─ Next time this user talks to this bot, the prompt builder
       knows it's a returning visitor and adjusts the greeting

# In your bot's module or anywhere importable
async def my_custom_handler(context: BotChatContext) -> Optional[str]:
    # context.transcript has the conversation history
    # context.bot_cfg has your config.json fields
    # context.caller is who's talking
    # Return the bot's response text, or None
    ...

{
  "chatHandler": "dynamic_functions.Games.FlowCentral.Bots.YourBot.handler.my_custom_handler"
}