从零搭建 Neo4j 图数据库应用：8…

当你需要从零开始新建一个 Neo4j 项目（本地/Docker/Aura），完成建库、建模、生成合成数据、探索、查询库与可运行应用的完整入门流程时使用。

适用场景

解决思路

1. 按 0-prerequisites → 1-context → 2-provision → 3-model → 4-load → 5-explore → 6-query → 7-build 的顺序依次执行 8 个阶段，每个阶段开始时只读取并遵循 ${CLAUDE_SKILL_DIR}/references/<stage-name>.md 对应的参考文件，不要一次性全部加载。
2. 所有生成的代码、数据、脚本、查询和 notebook 都必须写入工作目录（而非只输出在对话里），并按固定布局组织：根目录放 .env、aura.env、progress.md、requirements.txt 以及应用产物（notebook.ipynb、app.py、main.py、graphrag_app.py）；子目录为 schema/（schema.json、schema.cypher、reset.cypher）、data/（generate.py、import.py、*.csv）、queries/（queries.cypher）、scripts/（provision_aura.py）。写文件前先创建子目录。
3. 用 progress.md 跟踪进度以支持断点续跑：启动时若文件存在，用 grep -B1 "^status: pending" progress.md | grep "^###" | head -1 找到第一个待执行阶段，读取其 key=value 上下文块恢复 DOMAIN、USE_CASE、NEO4J_URI 等变量，不要重复询问用户已记录的信息；对每个已完成阶段，先读取其 files= 行列出的所有文件（schema/schema.json 在 model/load/query/build 前重读，queries/queries.cypher 在 build 前重读，data/generate.py 在 import/reset 前重读）作为事实依据，不要凭记忆重建内容；若文件不存在则从 0-prerequisites 开始。
4. 每个阶段完成后更新 progress.md：若该阶段的 ### 段落已存在，把 status: pending 改为 status: done 并追加新的 key=value 行；若不存在则按指定格式追加新段落。
5. 每个阶段执行固定协议：1) 宣告阶段 "## Stage: <name> — <purpose>"；2) 读取 ${CLAUDE_SKILL_DIR}/references/<name>.md；3) 执行其中指令；4) 验证该阶段完成条件；5) 更新 progress.md 为 status: done 并写入阶段上下文；6) 进入下一阶段（HITL 模式下先暂停等待批准）。阶段失败时按该阶段参考文件中的错误指引恢复，除非跳过条件明确允许，否则不要跳过阶段。
6. 阶段 0 prerequisites：在一切之前验证并安装所需 CLI 工具；完成条件是 neo4j-mcp 二进制可达且 .gitignore 含 .env 条目；此阶段永不跳过。
7. 阶段 1 context：收集 domain、use-case、experience、infrastructure target、data source 和 output type，并检测 Cypher 执行的 EXEC_METHOD；完成条件是 DOMAIN、USE_CASE、EXPERIENCE、DB_TARGET、DATA_SOURCE、APP_TYPE、EXEC_METHOD 全部已知；若这些变量已在对话上下文中提供则跳过。
8. 阶段 2 provision：开通一个运行中的 Neo4j 数据库并把凭据保存到 .env；完成条件是 .env 含 NEO4J_URI/USERNAME/PASSWORD/DATABASE 且连通性已验证；若 DB_TARGET=existing 则跳过，改为用用户凭据写 .env 后直接进入 3-model。
9. 阶段 3 model：为用例设计或发现图数据模型；完成条件是写出 schema.json 和 schema.cypher；若 DATA_SOURCE=demo 则跳过自定义建模、使用 demo schema 直接进入 4-load；HITL 模式下在此展示模型草稿并等待批准（自主模式完全跳过该检查点）。
10. 阶段 4 load：先应用 schema 约束，再导入数据（demo、synthetic、CSV 或文档）；依赖 3-model（导入前约束必须已存在）；完成条件是节点数 ≥ 50、import/ 脚本已写出、reset.cypher 已写出。
11. 阶段 5 explore：交付一个图的可视化入口（"原来如此"的时刻）；完成条件是向用户打印浏览器 URL 或在 notebook 中加入可视化单元格；此阶段为硬性关卡，永不跳过。
12. 阶段 6 query：为用例生成并验证 Cypher 查询库；完成条件是 queries.cypher 含 ≥5 条查询、≥2 条遍历、≥3 条能返回结果；使用 ${CLAUDE_SKILL_DIR}/scripts/validate_queries.py 一次性批量验证所有查询。
13. 阶段 7 build：生成可运行的应用、仪表盘、notebook 或 agent 集成；完成条件是产物存在、通过语法检查、能返回非空的用例结果。
14. 跨阶段共享能力：Cypher 执行参考 ${CLAUDE_SKILL_DIR}/references/capabilities/execute-cypher.md（3 种方式，EXEC_METHOD 在 context 阶段选定）；Cypher 编写规则参考 ${CLAUDE_SKILL_DIR}/references/capabilities/cypher-authoring.md（或交给 neo4j-cypher-authoring-skill）；MCP 配置参考 ${CLAUDE_SKILL_DIR}/references/capabilities/mcp-config.md（用于 prerequisites 和 build 阶段）。
15. 满足全部 7 个成功关卡：db_running（provision 阶段 driver.verify_connectivity() 成功）、model_valid（model 阶段 DB 中 ≥2 个节点标签、≥1 个关系类型、≥1 个约束）、data_present（load 阶段 MATCH (n) RETURN count(n) ≥ 50）、queries_work（query 阶段 ≥5 条查询、≥2 条遍历、≥3 条返回 ≥1 结果）、graph_visible（explore 阶段向用户交付浏览器 URL 或 notebook 可视化）、app_generated（build 阶段产物存在、通过语法、返回非空结果）、integration_ready（build 阶段若被要求则存在 MCP 配置或 agent 框架代码）。
16. 使用快速路径：DB_TARGET=existing 时跳过 provision，用用户凭据写 .env 后进入 model；DATA_SOURCE=demo 时跳过自定义建模、用 demo schema 跳到 load；DB_TARGET=existing 且数据已存在时跳过 provision、model、load，内省 schema 后直接进入 explore。
17. 在阶段 1 开始时检测运行模式：若初始提示同时包含 DOMAIN、USE_CASE、EXPERIENCE、DB_TARGET、DATA_SOURCE、APP_TYPE（或等价措辞），或会话以 --auto-approve 等非交互标志启动，或所有上下文变量已记录在 progress.md 中（续跑自主运行），则为自主模式；否则为 HITL 模式。自主模式下自动跳过所有阶段参考文件中的每个 HITL 检查点，不请求批准、不问 "这样对吗"、不暂停，立即继续下一步，并把浏览器 URL 打印到 stdout，目标是从数据库运行起 ≤15 分钟完成。HITL 模式下在 model 后暂停审查模型、在 load 后暂停审查数据。
18. 全部关卡通过后，先向工作目录写出 README.md（用 progress.md 和实际生成文件填充模板中的每个 <placeholder>，这是必需产物），其中所有重跑命令必须使用 python3（绝不用 /opt/homebrew/bin/python3.14 这类绝对路径），并包含：图内容表格、Neo4j Browser 可视化入口与起始查询、文件清单表（含各文件用途与重跑命令）、运行应用的步骤（python3 -m venv .venv、source .venv/bin/activate、pip install -r requirements.txt、运行命令）、FastAPI 时加 http://localhost:8000/docs 说明、MCP 集成时加 Claude Code 与 Claude Desktop 的配置方法、重置与重载步骤、示例查询（Cypher 注释用 // 而非 --）、后续步骤。DATA_SOURCE=csv 时省略 data/generate.py 行，DATA_SOURCE=synthetic 时省略 data/import.py 行。
19. 随后在对话中打印最终总结：完成标记、数据库 NEO4J_URI、Browser 链接 https://browser.neo4j.io/?connectURL=<encoded>、生成文件清单（含各自重跑命令）、7 个关卡状态、后续步骤（探索、迭代、学习 GraphAcademy）；不适用的行省略（如 DATA_SOURCE=synthetic 时省略 data/import.py）。
20. 收尾检查清单：前置条件满足（Docker/Python/Java，云端则需 Aura API key）；DB 可达（cypher-shell 中 RETURN 1）；数据加载前约束与索引已 ONLINE；数据已加载（MATCH (n) RETURN count(n) > 0）；queries.cypher 所有查询返回预期结果；应用/notebook 端到端可运行；.env 已 gitignore 且凭据未硬编码。

适用边界 · 注意事项

• 不覆盖 Cypher 查询编写——请用 neo4j-cypher-skill。
• 不覆盖驱动升级或 Cypher 迁移——请用 neo4j-migration-skill。
• 不覆盖已有数据库上的 CLI/管理任务（备份、恢复、导入）——请用 neo4j-cli-tools-skill。