使用说明
Whisperwynd
快速导航
概述
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
用法
基本设置
-
启动主应用程序：
uvicorn app:app --reload -
访问应用程序：
- 应用程序：
http://localhost:8000
- 应用程序：
健康监测
- 健康检查： 访问
/health→ 检查准备情况 - 运行时指标： 访问
/stats→ 查看运行时指标
MCP集成
-
启动MCP服务器：
python mcp_server.py -
MCP调试的Web界面：
python mcp_web_server.py
API终点
| 端点 | 方法 | 描述 |
|---|---|---|
/ |
GET | 根端点 |
/health |
GET | 应用程序健康检查 |
/stats |
GET | 运行时统计信息 |
/personas |
GET | 检索角色配置文件 |
配置
环境变量
# Required
BOT_CLIENT_ID=your-client-id
BOT_CLIENT_SECRET=your-client-secret
# Optional
DEBUG=true
LOG_LEVEL=INFO
机器人配置(bot.xml)
机器人配置包括元数据和身份验证设置：
<bot>
<metadata>
<n>Whisperwynd</n>
<description>Interactive storytelling application</description>
<version>1.0.0</version>
</metadata>
<auth>
<clientId>${BOT_CLIENT_ID}</clientId>
<clientSecret>${BOT_CLIENT_SECRET}</clientSecret>
</auth>
</bot>
发展
先决条件
- 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身份验证
贡献
- 复刻仓库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add some amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
开发指南
- Python代码风格遵循PEP 8
- 为新功能添加测试
- 更新API变更文档
- 在提交PR之前，确保所有测试都通过
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
