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）与精度；优化需定义目标函数与约束条件；机器学习需映射特征输入与训练轮次（epochs）。

步骤 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 提供的量子随机数生成器；在 API 中暴露随机比特流或采样次数（shots）。
• 安全 / 密钥材料：crypto —— 实现密钥生成或抗量子密码学原语；密钥仅保留在后端，禁止泄露至前端。

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

• 演示用途：仅允许使用合成数据或去标识化数据。严禁将真实受保护健康信息（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。