玄枢子命理系统

玄枢子命理系统是一套完整的、可商业化运营的数字命理产品原型。它通过架构设计，完美解决了准确性与解读深度之间的矛盾，让AI在最擅长的领域发挥最大的价值。

🚀 最新更新

架构改进 (v1.1.0)

• ✅ 安全性提升：移除硬编码API密钥，强制使用环境变量
• ✅ 错误处理优化：完善的异常处理和用户友好的错误信息
• ✅ 配置管理改进：统一的配置管理和环境变量验证
• ✅ 测试覆盖：添加单元测试和集成测试框架
• ✅ 代码质量：改进模块导入方式，移除动态路径添加
• ✅ 日志管理：统一的日志配置和级别控制

系统架构

系统由三层架构组成：

1. 天机内核 (Tianji Core) - Python实现的精确命盘计算引擎
2. 解读宗师 (Interpretation Master) - 优化的提示词模板，指导AI进行命理解读
3. 完整工作流 (Complete Workflow) - 整合用户输入、计算和解读的业务流程

文件结构

├── tianji_core.py                    # 天机内核计算引擎
├── api_server.py                     # API服务器
├── start_server.py                   # 服务器启动脚本
├── config.py                         # 配置管理
├── 提示词最终版.txt                  # 玄枢子提示词模板
├── workflow.py                       # 系统工作流整合
├── improved-bazi-dayun-calculator/   # 改进的八字大运计算器
├── tests/                            # 测试目录
│   ├── test_tianji_core.py          # 天机内核测试
│   └── test_api_server.py           # API服务器测试
├── requirements.txt                  # Python依赖包
├── pytest.ini                       # 测试配置
├── env_example.txt                   # 环境变量示例
└── README.md                         # 系统说明文档

🔧 环境准备

1. 安装Python环境

确保已安装Python 3.7+环境

2. 安装依赖包

pip install -r requirements.txt

3. 配置API密钥

重要：必须设置环境变量才能运行系统

Windows系统：

set DEEPSEEK_API_KEY=your_actual_api_key_here

Linux/Mac系统：

export DEEPSEEK_API_KEY=your_actual_api_key_here

或者使用改进的启动脚本：

直接运行 start_fortune_telling_improved.bat，脚本会提示输入API密钥。

4. 可选配置

# 服务器端口（默认8000）
set SERVER_PORT=8000

# 调试模式（默认关闭）
set SERVER_DEBUG=False

# 日志级别（默认INFO）
set LOG_LEVEL=INFO

🚀 使用方法

方法一：使用改进的启动脚本（推荐）

# Windows
start_fortune_telling_improved.bat

# Linux/Mac
python start_server.py

方法二：手动启动

python start_server.py

方法三：命令行工作流

python workflow.py

🧪 测试

运行所有测试

pytest

运行特定测试

# 运行天机内核测试
pytest tests/test_tianji_core.py

# 运行API服务器测试
pytest tests/test_api_server.py

# 生成测试覆盖率报告
pytest --cov=. --cov-report=html

🔒 安全说明

环境变量配置

• DEEPSEEK_API_KEY：必需，DeepSeek API密钥
• DEEPSEEK_API_URL：可选，API端点（默认：https://api.deepseek.com/v1/chat/completions）
• SERVER_PORT：可选，服务器端口（默认：8000）
• SERVER_DEBUG：可选，调试模式（默认：False）
• LOG_LEVEL：可选，日志级别（默认：INFO）

安全最佳实践

1. 永远不要在代码中硬编码API密钥
2. 生产环境必须设置SERVER_DEBUG=False
3. 定期更新依赖包版本
4. 使用HTTPS进行API通信
5. 限制服务器访问范围

🐛 故障排除

常见问题

1. API密钥错误

   错误：配置验证失败，请检查环境变量设置
   

   解决：确保正确设置了DEEPSEEK_API_KEY环境变量

2. 依赖包缺失

   ModuleNotFoundError: No module named 'flask'
   

   解决：运行 pip install -r requirements.txt

3. 端口被占用

   OSError: [Errno 98] Address already in use
   

   解决：更改SERVER_PORT环境变量或关闭占用端口的程序

4. 城市不支持

   错误：不支持的城市 'xxx'
   

   解决：手动输入经度或添加城市到CITY_LONGITUDES字典

📊 功能说明

天机内核 (tianji_core.py)

• 精确计算八字命盘数据
• 支持真太阳时校正
• 计算胎元、命宫、大运等关键命理信息
• 生成标准化的JSON数据输出
• 完善的参数验证和错误处理

解读宗师 (提示词最终版.txt)

• 定义了玄枢子Agent的角色和解读策略
• 融合了多种经典命理典籍的解读方法
• 指导AI生成结构清晰、文采斐然的命理解读

API服务器 (api_server.py)

• RESTful API接口
• 完善的错误处理和重试机制
• 生产环境友好的日志配置
• 类型注解和文档字符串

工作流 (workflow.py)

• 处理用户输入
• 调用天机内核计算命盘数据
• 组装提示词并调用大模型API
• 展示和保存解读结果

🔄 大运计算实现对比

我们对两种大运计算实现进行了对比分析，详细内容请参见 dayun_calculator_comparison.md。

🚀 扩展建议

1. 城市数据库扩展：在tianji_core.py中添加更多城市的经度数据
2. 神煞计算扩展：根据sxtwl库的文档添加更多神煞计算
3. 前端界面开发：开发Web或App前端，提供更友好的用户体验
4. 结果可视化：将命盘数据和解读结果以图表形式展示
5. 数据库集成：添加用户管理和历史记录功能
6. API限流：实现API调用频率限制
7. 缓存机制：添加计算结果缓存

⚠️ 注意事项

1. 本系统仅供学习和研究使用，请勿用于非法用途
2. 命理解读结果仅供参考，不构成任何形式的决策建议
3. 请确保遵守相关法律法规和伦理规范
4. 使用前请确保已获得用户的知情同意
5. 重要：请妥善保管API密钥，不要提交到版本控制系统

📄 许可证

本项目采用MIT许可证，详见LICENSE文件。

🤝 贡献

欢迎提交Issue和Pull Request来改进这个项目。

📞 支持

如果您遇到问题或有建议，请通过以下方式联系：

• 提交GitHub Issue
• 发送邮件至项目维护者