Agent Vqe

关键约定速查

需求路由与指南分发

当用户提出需求时，根据以下分类使用文件读取工具加载对应子文档。不要一次性全部加载。

1. 安装与首次运行 (Quick Start)

适用场景： 用户第一次接触本项目，需要安装依赖、运行第一个实验、或理解输出产物。 行动指令： 读取 references/quickstart.md

2. 结构搜索与策略选择 (Structural Search)

适用场景： 用户想进行 Ansatz 结构搜索（GA、MultiDim、ADAPT、Qubit-ADAPT），需要了解各策略定位、搜索空间配置、或编排模式。 行动指令： 读取 references/structural-search.md

3. Agent 研究循环 (Research Loop)

适用场景： 用户需要启动可恢复的自主研究循环、调用 Agent API、理解 PolicyEngine 与失败归因机制、或查看结构化 Session 记录。 行动指令： 读取 references/agent-research-loop.md

4. 分子哈密顿量与数据生成 (Molecular Hamiltonian)

适用场景： 用户需要生成分子哈密顿量数据（H₂/LiH/BeH₂）、自定义几何扫描点、或理解数据格式。 行动指令： 读取 references/molecular-hamiltonian.md

5. 架构设计与扩展开发 (Architecture & Extension)

适用场景： 用户想添加新的物理体系、新的搜索策略、新的 FailureHandler，或需要理解分层架构与 Schema 关系。 行动指令： 读取 references/architecture-extension.md

6. 故障排除与常见问题 (Troubleshooting)

适用场景： 用户遇到安装错误、运行崩溃、实验恢复失败、输出异常等问题。 行动指令： 读取 references/troubleshooting.md

重要文档引用

以下仓库内文档包含更详细的协议与规范，可在需要时直接引用：

• doc/agent_architecture.md — Agent 架构设计图与模块接口
• doc/agent_runtime_guide.md — Agent 运行时使用手册
• doc/evaluation_protocol.md — 实验评估协议（预算、排名、审计）
• doc/logging_spec.md — 日志记录规范 (schema v1.2)
• doc/experiment_artifact_protocol.md — 实验产物保留协议
• doc/orchestration_protocol.md — 编排协议
• doc/parameter_mapping.md — Warm-start 参数映射规则
• doc/molecular_hamiltonian_guide.md — 分子哈密顿量完整指南
• program.md — 面向 Agent 的实验执行手册
• Plan.md — 项目主计划与路线图

给 AI 引擎的强制约束：

1. 按需加载：只读取与用户当前问题相关的 references 子文档，不要预加载全部 6 个文件
2. 命令优先：回答"怎么做"时，优先给出可直接执行的 uv run 或 just 命令
3. 不可变现实：绝不建议修改 core/foundation/base_env.py 或 experiments/*/env.py 中的物理环境定义
4. 结构优先：对于简单优化，推荐通过修改结构化 config（layers, gates, entanglement）来改进 Ansatz。
5. 标准参照：在评估新策略或新结构时，务必与 baselines/ 中的标准化学 Ansatz (如 Givens) 进行对比。
6. 引用真实路径：所有文件引用必须指向仓库中实际存在的文件。