QuantinuumClaw – Quantum Guppy/Selene 技术栈

该技能提供构建生产级量子应用所需的全部能力，底层依托 Quantinuum（硬件/模拟器）、Guppy（量子编程语言）、Selene（基于 FastAPI 的后端）与 Fly.io（部署平台），并可选配 Lovable 前端。本栈专为 OpenClaw Clinical Hackathon 及通用量子 Web 应用优化设计。

适用场景

请在以下情况中使用：

• 面向 OpenClaw Clinical Hackathon 或任意临床/医疗健康类量子项目进行开发
• 构建使用量子计算能力的 Web 应用（涵盖优化、化学模拟、机器学习、随机数生成、密码学等方向）
• 将量子算法以 REST API 形式发布，或构建用于展示量子计算结果的交互式仪表盘
• 用户提及关键词：clinical（临床）、healthcare（医疗健康）、drug discovery（药物发现）、treatment optimization（治疗优化）、patient stratification（患者分层）、molecular simulation（分子模拟）、clinical trials（临床试验）、Guppy、Selene、Fly.io

典型请求示例： “构建一个带 Web 界面的量子投资组合优化器” · “将我的 Guppy 算法部署至云端” · “创建一个临床分子模拟演示应用” · “在 Fly.io 上搭建一个量子机器学习服务”

技术栈概览

快速启动（单命令）

在仓库根目录执行：

python3 scripts/create_quantum_app.py 
  --app-name "clinical-demo" 
  --use-case "chemistry" 
  --description "Clinical molecular simulation" 
  --deploy

随后在前端中设置 VITE_API_URL 为你的 Fly.io 应用地址（例如：https://clinical-demo.fly.dev）。

临床应用场景 → --use-case 映射关系：

通用场景（如投资组合、金融建模等）同样支持 optimization、chemistry、ml、random、crypto 或 finance。详细临床场景映射请参阅 references/clinical-use-cases.md。

完整工作流：构建量子应用

步骤 1：明确应用场景

识别待解决的问题类型（优化、模拟、机器学习、密码学、临床等）。

步骤 2：创建 Selene 后端

python3 scripts/setup_selene_service.py 
  --app-name "my-quantum-app" 
  --use-case "chemistry" 
  --description "Quantum chemistry simulator"

该命令将生成包含 FastAPI 框架、健康检查接口、Dockerfile 和 fly.toml 的后端目录。

步骤 3：实现 Guppy 量子电路

编辑 my-quantum-app/main.py 中的 QuantumService._run_real_quantum() 方法。语法参考 references/guppy_guide.md。针对临床场景：化学模拟需指定分子结构、采样次数（shots）和精度；优化问题需明确定义目标函数与约束条件；机器学习则需映射患者特征至模型输入。

步骤 4：部署至 Fly.io

python3 scripts/flyio_deploy.py --app-name "my-quantum-app" --service-dir "my-quantum-app" --region "lhr"

使用 fly secrets set 设置敏感配置；如仅用于演示，可启用模拟器模式。

步骤 5：前端集成

可直接使用 assets/lovable-template/，或运行：

python3 scripts/lovable_integrate.py 
  --app-name "my-frontend" 
  --backend-url "https://my-quantum-app.fly.dev" 
  --quantum-use-case "chemistry"

随后在前端目录中执行 npm install 和 npm run dev。

步骤 6：连接与测试

将前端的 VITE_API_URL 指向 Fly.io 后端地址；访问 /health 接口验证服务是否正常运行。

临床应用场景速查表

• 药物发现 / 分子模拟： 使用 chemistry —— 在 Guppy 中实现 VQE 风格的能量/物性计算；通过 API 暴露分子类型及参数配置。
• 治疗方案 / 资源优化： 使用 optimization —— 定义优化目标（如成本、等待时间）；在 Selene 中运行 QAOA；在 UI 中可视化结果。
• 患者分层 / 分类任务： 使用 ml —— 将患者特征映射为模型输入；返回风险等级、分层结果或分类标签。
• 随机化（如临床试验）： 使用 random —— 调用 Guppy 提供的量子随机数生成器（QRNG）；通过 API 暴露比特序列或采样次数（shots）。
• 安全机制 / 密钥材料： 使用 crypto —— 实现密钥生成或量子安全原语；密钥必须严格保留在后端，禁止泄露至前端。

数据与合规性要求（临床 / 黑客松）

• 演示用途： 仅允许使用合成数据或去标识化（de-identified）数据。严禁将真实受保护健康信息（PHI）发送至量子后端，或在未制定合规方案前存储于 Fly.io。
• API 密钥管理： 必须通过 Fly.io Secrets 存储（fly secrets set），严禁硬编码于源码或前端代码中。
• 生产环境： 需增加身份认证（auth）、速率限制（rate limiting）等机制，并评估 HIPAA/DPA 合规性；在 Selene 中限制 CORS 策略范围。

资源索引

scripts/

• create_quantum_app.py —— 一体化脚本：自动生成后端 + 部署 + 前端
• setup_selene_service.py —— 初始化 Selene 后端骨架
• flyio_deploy.py —— 执行 Fly.io 部署流程
• lovable_integrate.py —— 将前端与指定后端 URL 关联

references/

• guppy_guide.md —— Guppy 语法、量子门、电路构建与示例
• selene_api.md —— API 端点定义、请求/响应格式、错误处理、异步任务机制
• flyio_config.md —— Fly.io 扩展策略、区域选择、密钥管理、监控配置
• lovable_patterns.md —— 前端设计模式、仪表盘组件、API 客户端封装
• clinical-use-cases.md —— 详尽的临床应用场景映射及合规性注意事项

assets/

• selene-template/ —— 后端基础模板（含 main.py、Dockerfile、fly.toml、.env.example）
• lovable-template/ —— 基于 React/TS 的前端模板，内置 QuantumDashboard 组件与 API 客户端

进阶应用：多量子场景支持

• 优化型仪表盘： Selene 集成 QAOA/VQE；Lovable 提供交互式滑块控件；Fly.io 支持弹性扩缩容。
• 化学探索工具： Guppy 实现分子模拟；集成 3D 可视化模块；可选持久化存储支持。
• 量子机器学习 API： Selene 对外暴露量子神经网络（QNN）/量子支持向量机（QSVM）；Lovable 提供训练与预测界面；Fly.io 支持 GPU 加速（按需启用）。

性能、成本与安全性

• 任务队列： 对长时间运行的量子任务启用队列机制；前端通过 WebSocket 或轮询方式获取结果。
• 缓存策略： 对重复计算结果进行缓存，显著降低量子硬件调用成本。
• Fly.io 运维： 空闲时自动缩容至零实例（min_machines_running = 0）；VM 规格配置详见 references/flyio_config.md。
• 安全实践： 前端严禁嵌入 API 密钥；Selene 后端强制启用速率限制；生产环境必须启用 HTTPS；认证方案详见 references/selene_api.md。

故障排查

• Guppy 导入失败： 在后端环境中执行 pip install guppy；或演示阶段启用 mock 模式。
• Selene 启动异常： 检查 fly.toml 配置、fly logs 日志输出及环境变量设置。
• 前端无法连接后端： 核实 VITE_API_URL 地址、Selene 的 CORS 配置，并使用 curl .../health 测试连通性。
• Fly.io 部署失败： 执行 fly deploy --clean 清理缓存；使用 fly logs --phase build 查看构建日志；确认已执行 fly auth login 登录。
• 量子计算结果异常： 验证量子电路逻辑与测量方式；优先在模拟器上完成全流程测试。

后续建议

完成初始搭建后，请持续监控量子资源使用量与成本；若服务对外公开，应在 Selene 中添加身份认证；进一步完善错误处理与日志记录机制；考虑引入持久化存储以保存历史任务记录。

有关详细的临床应用场景规范与合规提醒，请查阅 references/clinical-use-cases.md。