企业官网建设流程全解析

• 后端
• 数据库
• 负载均衡

两阶段数据库发现（Two-Phase Database Discovery）将数据库 schema 认知拆解为「Phase 1 静态采集」与「Phase 2 LLM 语义分析」：前者由 ProxySQL 通过 MCP 端点确定性提取 INFORMATION_SCHEMA 元数据，后者由 LLM Agent 只读 catalog、产出语义资产。本文以仓库中的 系统提示词 为骨架，完整展开 Phase 2 Agent 的工具边界、分阶段工作流、质量规则与无文件 I/O 约束，并结合配套实现脚本与测试用例给出可落地的运行方式。读完你将掌握：如何在静态采集完成后，让 LLM Agent 在纯 MCP 工具约束下生成对象语义摘要、领域聚类、指标与问题模板，并安全地回写 catalog。

一、两阶段架构：为什么 Phase 2 只能依赖 catalog

整套发现架构由 C++ 端与 LLM 端协作完成。在 ProxySQL 的实现中，所有发现工具统一通过/mcp/query端点暴露，由 Query_Tool_Handler.cpp 承载：

• Phase 1（Static Harvest，C++ 确定性执行）：读取 MySQLINFORMATION_SCHEMA，产出 runs、schemas、objects、columns、indexes、foreign_keys、profiles 等确定性数据，并重建 FTS5 索引；完成后返回run_id、对象数、列数等统计。
• Phase 2（LLM Agent Discovery）：LLM 基于已入库的 catalog 数据做语义层加工，产出llm_object_summaries、llm_relationships、llm_domains、llm_metrics、llm_question_templates、llm_notes等资产。

因此，本系统提示词的第一条硬约束是：Phase 1 已完成，绝不调用discovery.run_static，也绝不使用任何 MySQL 查询工具（list_schemas、list_tables、describe_table、get_constraints、sample_rows、run_sql_readonly、explain_sql、table_profile、column_profile、sample_distinct、suggest_joins全部禁用）。Agent 的唯一数据来源是target_id与已完成采集的run_id所对应的 catalog。这一隔离保证了：LLM 阶段不触碰线上数据库、不重复消耗采集成本、所有结论可追溯。

二、可用工具清单：三类 16 个 MCP 工具

Phase 2 Agent 只能使用以下三类工具，每一类承担不同的读写职责。

1. Catalog Tools（只读静态数据，优先使用）

这些工具是 Agent「读」的窗口：对象详情携带列/索引/外键及 profile，get_relationships还能带出已有推断关系（含置信度阈值过滤）。

2. Agent Tracking Tools（会话追踪）

agent_events兼作 Agent 的「草稿本」——因为不允许写文件，任何中间计划、预算、决策都以事件形式持久化，保证全程可审计。

3. LLM Memory Tools（写入语义资产）

其中llm.question_template_add有一条强制规则：必须从example_sql或template_json中提取表/视图名，作为 JSON 数组传给related_objects。例如 SQL 为SELECT * FROM Customer JOIN Invoice...时，related_objects应写["Customer", "Invoice"]。该字段让模板被检索命中时可高效预取对象详情，避免二次全量扫描。

三、分阶段发现流程（六阶段强制协议）

系统提示词规定 Agent 必须按固定阶段推进，并在每个阶段通过agent.event_append留下轨迹。

Stage 0 — 启动与计划

1. 使用来自静态采集上下文的target_id与run_id；
2. 调用agent.run_start（携带target_id、run_id、模型名），获得agent_run_id；
3. 通过agent.event_append记录发现计划；
4. 用catalog.list_objects/catalog.search确定作用域；
5. 定义分批处理的「工作集」（working sets）。

这一阶段的意义在于：数据库规模未知，必须先量级评估、分批规划，防止单次处理溢出上下文。

Stage 1 — 分类与优先级排序

构建优先级 backlog，排序依据（按序）：

• (a) 关系图中的中心性（FK / 关系图）；
• (b) 可能的业务重要性（orders、invoice、payment、user、customer、product 等命名）；
• (c) 是否存在时间列；
• (d) 视图（常承载业务语义）；
• (e) 预估行数小的优先（先低成本学习模式）。

将排序标准与 Top 20 候选以agent.event_append事件记录。

Stage 2 — 逐对象语义摘要（批量循环）

对当前批次的每个对象：

1. catalog.get_object（开启include_profiles）获取对象详情；
2. catalog.get_relationships获取关系；
3. 生成结构化摘要并通过llm.summary_upsert保存。

summary_json必须包含的字段：

同时必须写sources_json，说明使用了哪些信号（列、注释、索引、关系、profiles、命名启发式），保证每条结论有出处。

Stage 3 — 关系增强

当外键缺失或连接不清晰时，推断候选连接并用llm.relationship_upsert落库。只有存在至少两个独立信号时才存储推断关系，例如「名称匹配 + 索引存在」「名称匹配 + 类型匹配」等组合，并保存confidence与evidence_json。这一门槛显著降低误报。

Stage 4 — 领域聚类与综合

创建 3–10 个领域（如 billing、sales、auth、analytics、observability），依实际数据而定。每个领域：

1. 先llm.domain_upsert，再llm.domain_set_members写入成员及角色（entity/fact/dimension/log/bridge/lookup）与置信度；
2. 用llm.note_add追加领域级笔记，描述核心实体、关键连接与时间粒度。

Stage 5 — "可回答性"（Answerability）资产

产出两类可复用资产：

1. 10–30 个指标（llm.metric_upsert）：含metric_key、描述、依赖关系；只有足够自信时才写sql_template；
2. 15–50 个问题模板（llm.question_template_add）：映射 NL → 结构化查询计划；同样只在自信时附example_sql。

强约束：指标与模板必须引用已摘要过的对象/列，不得凭空猜测；所有模板必须填充related_objects。这保证了生成的 NL2SQL 资产与真实 schema 严格对齐，可被检索后直接执行。

四、质量规则：置信度、稳定性与去重

系统提示词要求 Agent 对不确定性保持显式表达，采用三档置信度：

配套规则：

• 禁止降级覆盖：绝不用低置信度草稿覆盖稳定摘要；若更新，只有证据改善时才保持/提升置信度；
• 避免重复劳动：处理对象前先用llm.summary_get检查是否已有摘要，若已稳定则跳过，除非能改进。

五、子代理编排（推荐）

允许派生子代理并行工作，每类子代理职责单一：

• "Schema Triage" 子代理：构建 backlog、识别高价值表/视图；
• "Semantics Summarizer" 子代理：批量处理对象并写llm.summary_upsert；
• "Domain Synthesizer" 子代理：构建领域与成员关系、写笔记；
• "Metrics & Templates" 子代理：创建llm_metrics与llm_question_templates。

所有子代理必须遵守同一持久化规则：摘要/关系/领域/指标/模板一律通过 MCP 回写 catalog，禁止旁路写盘。

六、完成标准与收尾

满足以下条件才算完成：

• 至少 Top 50 个最重要对象具备llm_object_summaries；
• 领域存在且包含这些对象的成员关系；
• 已存储指标与问题模板的起步集；
• 已写入一条全局笔记，总结该数据库整体语义（数据库主题、关键实体、典型连接、可回答的核心问题）。

收尾阶段：先agent.event_append记录已完成、未完成与建议的下一步；再以agent.run_finish(status=success)（或failed附带错误信息）结束运行。从仓库的集成测试可见这一收尾路径的实际调用形态——test_mcp_llm_discovery_phaseb-t.sh 依次验证discovery.run_static返回run_id、agent.run_start返回agent_run_id、llm.summary_upsert写入摘要、llm.question_template_add写入带related_objects的模板，是 Phase B 全链路的最直接证据。

七、CRITICAL I/O 规则：禁止文件系统

系统提示词以最高优先级明确：

• 不得创建、读取或修改任何本地文件；
• 不得向磁盘写 markdown 报告、JSON 文件或日志；
• 所有输出只能通过 MCP 工具持久化（llm.summary_upsert、llm.relationship_upsert、llm.domain_upsert、llm.domain_set_members、llm.metric_upsert、llm.question_template_add、llm.note_add、agent.event_append）；
• 需要"草稿空间"时，使用agent_events或llm_notes；
• 任何文件系统 I/O 尝试均视为失败。

这一约束与编排脚本形成闭环：在 two_phase_discovery.py 中，Agent 通过--mcp-only（默认开启）传入--allowed-tools ""禁用 Bash/Edit/Write 等全部内置工具，从机制上强制「只经 MCP 读写」。此外该脚本会自动调用discovery.run_static获取最新run_id（或接受--run-id参数），加载两份 prompt 文件并替换<TARGET_ID>、<USE_THE_PROVIDED_RUN_ID>、<MODEL_NAME_HERE>、<SCHEMA_FILTER>占位符，然后以--print非交互模式启动 Claude Code；--dry-run可先预览两份 prompt 而不实际执行。

八、工作流总览

START: use provided target_id + run_id ↓ agent.run_start(target_id, run_id) → agent_run_id ↓ catalog.list_objects/search → understand scope ↓ [Stage 1] Triage → prioritize objects [Stage 2] Summarize → llm.summary_upsert (50+ objects) [Stage 3] Relationships → llm.relationship_upsert [Stage 4] Domains → llm.domain_upsert + llm.domain_set_members [Stage 5] Artifacts → llm.metric_upsert + llm.question_template_add ↓ agent.run_finish(success)

九、端到端运行方式（仓库现状）

Phase 2 的完整运行依赖 Phase 1 的输出，仓库提供了完整配套：

# Phase 1：静态采集（无需 Claude Code） cd scripts/mcp/DiscoveryAgent/ClaudeCode_Headless/ ./static_harvest.sh --target-id tap_mysql_default --schema test # Phase 2：LLM Agent 发现（需先配置 MCP） cp mcp_config.example.json mcp_config.json # 按需修改 PROXYSQL_MCP_ENDPOINT / TOKEN ./two_phase_discovery.py \ --mcp-config mcp_config.json \ --target-id tap_mysql_default \ --schema test \ --dry-run # 先预览，确认后再移除 --dry-run 执行

MCP 配置示例 通过 proxysql_mcp_stdio_bridge.py 桥接https://127.0.0.1:6071/mcp/query；test_catalog.sh 可直接对catalog.list_objects、catalog.get_object、llm.summary_upsert发起 JSON-RPC 请求做连通性验证。更完整的实现说明见 doc/Two_Phase_Discovery_Implementation.md，其中详列了确定性层（runs、objects、columns、indexes、foreign_keys、profiles、fts_objects）与 LLM 层（agent_runs、agent_events、llm_object_summaries、llm_relationships、llm_domains、llm_domain_members、llm_metrics、llm_question_templates、llm_notes、fts_llm）共 20+ 张表的职责划分。若在无 Claude Code 的环境下仅需确定性发现，Phase 1 独立可用；Phase 2 的语义资产是可选增强，二者互不阻塞。

• 后端
• 数据库
• 负载均衡