Whisperwynd-Forge

Whisperwynd

Whisperwynd_Illustration

快速导航

• 概述
• 主要特点
• 关键贡献

- 机器人配置 - 应用程序增强 - 人物角色检索 - Whisperwynd MCP服务器

• 安装
• 用法

- 基本设置 - 健康监测 - MCP集成

• API终点
• 配置
• 发展
• 未来方向
• 贡献
• 许可证

概述

Whisperwynd是一个交互式讲故事和角色驱动的世界构建应用程序。它融合了轻量级的FastAPI服务、自适应卡和模型上下文协议（MCP）服务器，以提供这两者 人性化 和 AI集成 接口。

本项目介绍 结构化配置、可观察性、安全身份验证、增强的角色处理和MCP互操作性--将Whisperwynd转变为一个有弹性和可扩展的AI就绪平台。

主要特点

• 人物角色驱动的故事讲述 -具有化身和元数据的丰富角色配置文件
• FastAPI后端 -轻量级的现代Python web框架
• 人工智能集成 -MCP服务器实现无缝AI工具集成
• 可观测性 -内置健康检查和运行时指标
• 安全认证 -基于环境的配置
• 自适应卡 -人物角色的动态UI组件
• 热重新加载 -开发过程中开发人员友好的自动重新加载

关键贡献

机器人配置(bot.xml)

• 已添加元数据：机器人名称、描述、作者、维护者、版本
• 身份验证外部化：敏感值(clientId, clientSecret)移动到环境变量：

export BOT_CLIENT_ID=your-client-id
export BOT_CLIENT_SECRET=your-client-secret

应用程序增强(app.py)

进口和依赖关系

• 删除了大量外部依赖项（Azure Blob、WeasyPrint、dotenv）
• 添加了轻量级模块(json, datetime, functools.wraps, defaultdict, deque)

配置处理

• 基于环境的配置（否 .env 依赖性）
• 启动验证以确保所需密钥存在

错误处理和记录

• 启动和运行时事件的结构化日志记录
• 具有清晰调试输出的集中错误响应

新端点

• /health → 应用程序就绪性检查
• /stats → 运行时指标（请求、失败、响应时间）

开发者体验

• 开发过程中自动重新加载（Werkzeug+监视器）
• 使用装饰器和助手进行更清晰的代码分离

人物角色检索(GetPersonas-*.json)

• 自适应卡现在包括 标题、描述、角色和头像图像
• 引入 健康检查范围 带有用户友好的错误消息
• 已更新的架构 更丰富的人物简介

Whisperwynd MCP服务器

两个互补的组成部分：

• mcp_server.py → 基于Stdio的人工智能工具MCP服务器（Claude、GPT）
• mcp_web_server.py → 用于人工调试和工作流验证的Web界面

功能修复

• 修正了JavaScript中的转义换行处理
• 修复了客户端通信中的UUID冲突
• 优化web服务器代码以提高稳定性

MCP优势

• 协议标准化（生态系统就绪）
• 自动发现工具/资源(list_tools, list_resources)
• 结构化错误处理和日志记录
• 与AI IDE（VS Code、Cursor）和AI代理无缝集成

安装

# Clone repository
https://github.com/MITHRADEVIK3009/Whisperwynd-Forge.git
cd whisperwynd

# Set environment variables
export BOT_CLIENT_ID=your-client-id
export BOT_CLIENT_SECRET=your-client-secret

# Install dependencies
pip install -r requirements.txt

# Run FastAPI app
uvicorn app:app --reload

用法

基本设置

1. 启动主应用程序：

   uvicorn app:app --reload

1. 访问应用程序：

- 应用程序： http://localhost:8000

健康监测

• 健康检查： 访问 /health → 检查准备情况
• 运行时指标： 访问 /stats → 查看运行时指标

MCP集成

1. 启动MCP服务器：

   python mcp_server.py

1. MCP调试的Web界面：

   python mcp_web_server.py

API终点

配置

环境变量

# Required
BOT_CLIENT_ID=your-client-id
BOT_CLIENT_SECRET=your-client-secret

# Optional
DEBUG=true
LOG_LEVEL=INFO

机器人配置(bot.xml)

机器人配置包括元数据和身份验证设置：

  
    Whisperwynd
    Interactive storytelling application
    1.0.0
  
  
    ${BOT_CLIENT_ID}
    ${BOT_CLIENT_SECRET}
  

发展

先决条件

• Python 3.8+
• 快速API
• Uvicorn
• 必需的依赖关系（请参见 requirements.txt)

发展模式

# Install development dependencies
pip install -r requirements-dev.txt

# Run with auto-reload
uvicorn app:app --reload --debug

# Run MCP server in development
python mcp_server.py --debug

编码结构

Whisperwynd-Forge-main/
├── app/
│   ├── static/
│   │   └── generated_images/
│   ├── templates/
│   └── __pycache__/
├── copilit-agent/
│   ├── Assets/
│   ├── botcomponents/
│   │   └── default components/
│   ├── bots/
│   │   └── Default_whisperwyndChatbot/
│   └── Workflows/
├── Images/
├── app.py                 # Main FastAPI application
├── bot.xml               # Bot configuration
├── mcp_server.py         # MCP stdio server
├── mcp_web_server.py     # MCP web interface
├── GetPersonas-*.json    # Persona Adaptive Cards
├── requirements.txt      # Dependencies
└── README.md            # This file

未来方向

• 展开人物角色元数据 有能力和背景故事
• 添加持久层 （Postgres或向量数据库）用于长期状态
• 扩展MCP工具 更丰富的讲故事工作流程
• 增强的用户界面 使用更多交互式自适应卡
• 高级搜索 并过滤人物角色
• 移动响应 设计改进
• 增强安全 使用OAuth2/JWT身份验证

贡献

1. 复刻仓库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

开发指南

• Python代码风格遵循PEP 8
• 为新功能添加测试
• 更新API变更文档
• 在提交PR之前，确保所有测试都通过

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

返回页首