基于技能的自进化构图

#技能如何参与构图

自进化构图是 iGraph 图驱动分析中的图模式准备能力。当关系源数据需要转为可查询的图，或既有图模式需要针对固定查询优化时，构图智能体负责准备候选图模式并接受验收。Agent Runtime 的流程技能组织数据集状态检查、工具步骤与编辑审批；Graph Engine 的构图子智能体负责关系图模式、候选评估与领域经验。独立 SQL 参考执行器（SQL oracle）独立计算源数据答案，使图模式优化接受同一组业务查询的检验；已经可用的图仍可直接用于主智能体分析。

两层具有独立的存储边界：候选 SKILL.md 在批准前不会被 LocalSkills 加载；构图策略经验保存在默认工作区归属目录下的 SQLite 中。构图经验更新不会自动改写内置 SKILL.md，也不会自动晋升为已批准的用户技能。

流程技能与构图策略分别解决“任务怎样执行”和“当前数据采用什么图模式”。例如，graph_construction 先核对当前附件所属的数据集，再检查构图状态；已就绪时加载已有图，需要修改时先预览。进入构图子智能体后，选择路径物化还是属性实体化，则由当前输入结构、查询评测查询集和策略证据决定。外层步骤正确不等于内层候选有效，内层优化成功也不代表用户已经批准后续编辑。

当前 Agent Runtime 使用 Agno LocalSkills 加载内置技能与默认工作区的活动技能。候选目录不参加加载；批准操作将候选移入活动技能目录。构图子智能体只使用本次保留的数据源、构图专用工具和当前工作区的领域经验，不接收主会话消息、通用记忆或文件系统工具。

• 构图实验：Amazon、AVS、MAG、StackExchange 与 PK/FK 基线对比↗

#构图与进化闭环

自进化构图：方案比较与经验复用查看大图 ↗查看大图 ↗

圆环表示本轮构图的候选迭代：依据领域、查询热点与已有经验选择策略，在当前图副本上构造候选，经过独立验收后接受或拒绝，再根据反馈选择下一候选。接受会更新当前保留图，拒绝则保留原图继续探索。外侧虚线表示跨任务复用：结束探索并通过最终复验后，才保存有效策略证据，供后续构图调整候选优先级。

本节的固定评测查询集、独立 SQL 参考执行器、候选优化和领域经验适用于 SQL、CSV，以及按表格或逐行记录导入的 TXT。只有 txt_mode=entities 使用另一条路径：分块调用 LLM、核对关系两端是否出现在同一原文分块中、去重建图，再校验 construction_graph.v1 数据格式。该模式完成不代表关系含义已通过 SQL 对照验证。

• 关系型输入依据主键与外键建立属性图 G₀，保留记录标识、类型、NULL 和关系方向；语义 TXT 则进入独立的分块抽取路径。
• 读取领域描述与数据结构，生成业务查询或接收指定 queries；冻结评测查询集并记录 SHA-256。
• 分别运行源数据参考执行器和图执行器，测量当前图的正确率、索引准备成本与查询耗时。
• 按领域先验、图结构和历史证据选择策略；使用当前真实表名、字段和节点 ID 实例化候选。
• 在副本上变换，执行完整源数据完整性检查和全部冻结查询；采纳符合阈值的改进，否则保留当前图。
• 记录候选结果；最终独立复验后保存图和 evolution-report.json，并将结构化证据用于后续构图。

默认 llm 模式由模型生成评测查询并规划候选，模型请求使用独立的构图配置。rules 模式使用确定性查询和代码生成的候选，适合离线验证；当前会尝试 materialize_join、generate_entity_table 和 transform_batch，不会遍历所有变换。LLM 出错不会自动降级为 rules 后宣称成功。

评测查询生成默认最多请求模型 3 次。模型必须调用 set_workload，返回说明文字不会冻结查询。字段缺失、计划重复或覆盖类别减少时，工作进程返回结构化错误，模型可在剩余预算内修正。候选优化默认最多 12 次模型响应，每次最多包含 10 个工具调用；调用按顺序执行，与查询生成阶段共享默认 24 次工具调用的总预算。

finish 是结束请求，不是发布指令。LLM 模式要求至少一个真正到达查询评估的候选，且当前图已通过全部冻结查询，才接受 finish；响应中的 final_validation_pending=true 表示最终验证仍未执行。达到演化轮数上限也会进入最终验证：如果至少评估过一个候选且保留图通过，任务仍可成功；如果始终只有无效调用，则以 no_evolution_candidate_evaluated 失败。

{
  "tool": "finish",
  "arguments": {
    "reason": "All frozen queries pass; no further candidate is justified."
  }
}

#源数据预览与字段说明

上传 SQL、CSV 或 TXT 后，构图面板即可读取原始数据预览，无需先运行构图。构图完成后仍可展开查看。SQL 和 CSV 可切换表，查看字段、声明类型、主外键、字段含义及示例行；TXT 展示原文开头的内容。读取预览不会启动构图，也不会修改已保存的图或会话活动图。

SQL 文本预览把 CREATE TABLE 和 INSERT ... VALUES 作为数据解析，不执行上传的 SQL；无法展示的语句或值会产生警告或占位内容。SQLite 镜像只读访问，虚拟表跳过，生成列等不受支持的结构会被拒绝。CSV 可随面板所选分隔符重新预览；TXT 始终显示原文摘录。大整数为避免浏览器精度丢失可能以字符串返回，二进制值不会原样显示。

GET /api/personal-datasets/{dataset_id}/construction/source-preview
GET /api/projects/{project_id}/datasets/{dataset_id}/construction/source-preview

# Optional CSV delimiter, URL-encoded when necessary
GET /api/personal-datasets/{dataset_id}/construction/source-preview?delimiter=%09

#输入与关系语义

• 每行成为节点；可靠 PK 决定稳定标识，完整复合键参与编码。
• FK 从子表行连接到实际引用的父表行；相同列名不会自动产生关系。
• 没有可靠 PK 时使用行位置，并记录警告；悬空引用不会创建虚假节点。
• SQL 不连接生产数据库，也不运行任意数据库脚本；不支持的视图、触发器等需预先转成普通表。

普通文本可以是连续段落，也可以一行描述一个或多个事实。entities 不要求表头，也不要求每行恰好对应一条边；必须设置 mode=llm，不能同时设置 delimiter、primary_key、foreign_keys 或 tables。系统按原文顺序将全文切成带有限重叠的分块，发送给构图模型。每条保留关系的两个端点都必须出现在同一原文分块中，否则丢弃该候选。如果某个分块在重试后仍未返回合法结果或明确的“无关系”结果，或者调用失败，整个任务失败，不保存不完整的图。这些检查不能证明模型对关系的解释正确，使用前仍需核对原文。

张三就职于星河公司。
李四向张三汇报。
星河公司位于合肥。

SQL 入口按 SQLite 文件头识别数据库镜像，其余内容按 UTF-8 SQL 文本解析。默认 bounded 配置将镜像或 SQL 文本导入内存 SQLite；显式 full_scale 配置下的 SQLite 镜像改为只读文件访问。系统从 sqlite_master、table_xinfo 和 foreign_key_list 读取表、列、主键顺序及外键分组。文本只接受普通表和索引定义、字面值 INSERT 及受支持的导出事务标记；SELECT、WITH、UPDATE、RETURNING 等入口会被拒绝。镜像也检查视图、触发器、虚拟表和生成列，不能绕过构图输入约束。

关系比较不仅取决于可见文本。SQL 入口保存列声明类型及 BINARY、NOCASE、RTRIM 比较规则，构建外键对应关系时把父列放在等式左侧，由 SQLite 使用父列的类型亲和性与排序规则。比如父键声明 TEXT COLLATE NOCASE 时，大小写不同的引用可能对应同一父记录；不能在图侧改成任意字符串比较。SQL 标识符可按 SQLite 的 ASCII 大小写规则解析，数据单元格本身不会统一转为小写。

CSV 严格校验表头和列数，保留字符串值：0012 不会自动变成数字，空串也不会统一变成 NULL。CSV 外键中的空串表示缺少引用；SQL 空串则是实际文本值，可能匹配父表中的空串。直接上传单个 CSV 时，API 可通过 options.table_name、primary_key、foreign_keys 和内联 tables 补充结构；内联表只接收名称、列、行和键定义等数据，不读取外部文件路径。column_types 只是说明性标签，不会把 CSV 字符串转换为数值。工作台配置后上传的 CSV 表组使用随文件保存的结构定义，详见多表输入。

单元格必须是有限的 JSON 标量：字符串、数值、布尔值或 NULL。BLOB、嵌套数组、对象与非有限浮点数需要在导入前转换。CSV 的 amount="120.0" 仍是字符串，不能直接作为 SUM/AVG 的数值列；需要数值聚合时，应先准备具有明确数值类型的 SQL 数据，或使用数值标量的内联表。

以下说明性 CSV 配置假设上传表头为 order_id,customer_id,amount，并以内联表提供 customers，用于说明键声明与类型边界。

{
  "table_name": "orders",
  "primary_key": [
    "order_id"
  ],
  "foreign_keys": [
    {
      "columns": [
        "customer_id"
      ],
      "ref_table": "customers",
      "ref_columns": [
        "id"
      ]
    }
  ],
  "tables": [
    {
      "name": "customers",
      "columns": [
        "id",
        "name"
      ],
      "rows": [
        {
          "id": "C001",
          "name": "Alice"
        }
      ],
      "primary_key": [
        "id"
      ]
    }
  ]
}

行标识由表名、主键模式和完整键值列表生成 SHA-256 派生标识。复合主键不能只取第一列；调换源行顺序不会改变有主键记录的身份。无可靠主键时使用表名与行位置，因此重排行会改变身份，报告会给出警告。CSV 未显式提供主键时，只检查 id、表名_id、单数表名_id 这类明确名称并验证非空唯一，不会仅凭某一列偶然唯一就把它认作主键。

Keyed row:
row_id = "row_" + SHA256(JSON([table, "pk", [key_1, key_2, ...]]))[:40]

Keyless row:
row_id = "row_" + SHA256(JSON([table, "position", row_index]))[:40]

JSON is canonicalized; complete composite keys participate in identity.

构建初图时，所有源行先生成节点，再按声明外键的实际匹配添加边。外键目标的非空键必须唯一；重复目标会导致导入失败。含 NULL 的复合外键不产生关系，非空但找不到目标的悬空外键保留原行并记录警告。列类型与比较规则放在该表首条行记录的 relational_schema 中；后续图模式变换必须继续保留这份语义，而不是只保留业务值。

TXT 默认 auto 只自动识别列数一致、至少有一行数据的制表符表格；否则每一行成为 text 字段中的一条记录，包括空行。lines 强制逐行导入。显式 delimiter 可将 TXT 按指定分隔符作为严格表格读取，但不能和 lines 或 entities 同时使用。逐行导入不会凭空识别实体关系；需要语义关系时，在工作台明确选择“实体与关系”模式。

#多表 CSV 与键定义

工作台上传一个或多个 CSV 时，会打开表结构配置窗口。每个文件对应一张表；检查表名、表头、主键和外键后再上传。窗口按字段名提出键建议，建议不等于已验证的数据关系：仍需确认业务含义，构图时还会检查键的唯一性与实际引用。当前窗口按逗号读取 CSV 表头；不同分隔符的数据应先转换，或使用支持 delimiter 的 API 输入。

上传接口接收 files 与 csv_schema。csv_schema 使用 version="csv_bundle.v1"，tables 中逐一声明 file_name、name、columns、primary_key 和 foreign_keys。服务器将文件和定义保存为一个数据集，保留原始 CSV 内容。它不是任意 ZIP 上传入口，也不能在一次多文件请求中混合 CSV、SQL 和 TXT。表组至少一张、最多 128 张；文件名和表名必须满足唯一性要求。

构图使用已保存的表组定义，拒绝再用 options.tables、primary_key 或 foreign_keys 覆盖它。SQL 多表数据则由同一个 SQL 文件中的表与外键定义提供。直接单 CSV 的内联 tables 是另一种 API 输入方式，不能与已保存的表组混为一谈。

• 查看上传格式与数据集复用↗

#固定评测查询集与 DSL

set_workload 仅在查询生成阶段接收一次 queries，数量必须等于 query_count。期望答案由源数据独立参考执行器计算，模型不提交答案。冻结后不得修改问题或计划来提高得分；同一计划分别编译为 SQL 并交由 GraphExecutor 在当前图上执行。

GraphExecutor 只读取当前图，从记录节点、桥接边、属性实体和迁移字段恢复关系行。它不能读取源表或参考执行器答案。source_integrity_errors 还遍历所有源记录和声明 FK，校验记录标识、字段、关系与列语义，覆盖评测查询集没有访问的数据。

查询覆盖包含关系遍历、可选关系、多跳、值筛选、NULL、聚合、分组与排序。15/15 表示该固定评测查询集的全部查询通过；它不是任意自然语言问题的正确率承诺。

生成器先按表建立查询池，而不是让一张宽表占满整个测试集。每张表可贡献记录计数、明细、属性查找、排序、分组、空值检查等计划；status、category 等业务类别和 amount、price 等指标优先于纯标识符。主键或外键可以用于精确查找，但不会被当作金额去求和，也不会优先作为业务类别分组。筛选常量来自该列的实际样本，避免凭空构造永远无结果的测试条件。

关系查询沿源数据的外键匹配索引展开，最多三步。生成阶段避免立即折返同一外键和反复使用同一有向关系；有实际可达行时才加入多跳计数或路径明细。LEFT JOIN 另保留缺少关联的记录。选择最终集合时先均衡根表覆盖，再轮换查询类别；最多生成 2,000 个计划。如果无法凑齐 query_count 个不同的可执行计划，会明确失败，不用改写问题文字或重复计划补足数量。

评测查询集有三个来源。options.queries 直接提供固定计划；rules 模式使用生成器的结果；LLM 模式把合法种子计划、领域描述、输入结构、样本和必需覆盖类别交给模型，再由 set_workload 校验。覆盖约束是相对于当前种子计划，不要求无外键数据凭空出现关系查询。显式提供的 queries 仍进行结构与语义验证，但不执行种子覆盖类别的补齐要求。

冻结前会补齐空数组和 limit:null，对计划做语义去重并复制为规范 JSON；冻结后保存 workload_sha256，每次候选开始及最终返回前再次检查。下面的 COUNT 查询是说明性的可执行计划，可放入 queries 数组并设置 query_count=1；空值检查只统计缺失 amount，不把 NULL 当作零。

{
  "id": "missing_amount",
  "question": "How many orders have no amount?",
  "root": {
    "table": "orders",
    "alias": "t0"
  },
  "joins": [],
  "filters": [
    {
      "column": "t0.amount",
      "op": "is_null"
    }
  ],
  "projection": [],
  "group_by": [],
  "aggregations": [
    {
      "function": "count",
      "column": "*",
      "as": "missing_count"
    }
  ],
  "order_by": [],
  "limit": null
}

独立参考执行器对内存 SQL 数据复制原始连接，保留数据定义和比较规则；对于 full_scale 的只读 SQLite 文件，则核对文件身份后打开独立只读连接。CSV 与内联数据使用无额外 SQLite 类型转换的临时表，保留原有标量类型。同一 DSL 通过限定标识符与参数绑定编译为 SQL，筛选值不会拼成可执行语句。图侧独立执行同一逻辑，两侧只在比较结果时汇合。

filters、projection、group_by 和聚合输入的 column 都引用源列，写成 t0.status、t1.amount 等 alias.column 形式。聚合产生的 cnt 等输出别名只能用于 order_by，不能放进 filters 充当源字段；当前 DSL 没有 HAVING。COUNT(*) 可用 *，但其他聚合需要有效列。若问题依赖聚合后筛选，不能靠把 cnt 改成某个源字段来冒充相同语义。

JOIN 的方向相对于外键声明。若 orders.customer_id → customers.id，forward 从订单别名进入 customers，reverse 从客户别名进入 orders；反向遍历时仍保留 foreign_key.table=orders、ref_table=customers，不能交换子表与父表。from 是已经存在的表别名，table 是本步新加入的表，alias 为它分配新的别名。两种方向都只能使用已声明的完整外键。

#构图技能与变换工具

私有构图子智能体跨阶段共有 12 个不同工具名：4 个读取或控制工具、7 个单步变换入口，以及 transform_batch 组合入口。optimize_graph 内含 6 类操作，单步入口合计覆盖 12 类变换策略；组合入口复用这些操作，不是第 13 类独立策略。这套工具与主智能体的公共 MCP 目录分开。

property 指 properties.data 内的业务字段，例如 status。data、table、row_index 等内部字段不能当作普通属性移动。非路径变换会使旧路径快捷边失效并先移除它们；重复图版本与相同参数的候选会被拒绝。

图模式可以改变，逻辑源行必须始终能从当前图恢复。resolve_rows 首先核对节点和边的 ID、真实端点以及 table、row_index、data 字段，然后读取三类当前存储：行节点自身的数据、承载桥接记录的行边、以及通过属性关联边或迁移字段记录指向的当前值。它返回独立副本供查询执行，不读历史图，也不从源表补回缺失字段。

例如把订单 status 提取为共享状态实体时，查询读的是该实体当前的 value。如果实体仍写 paid，而原节点上留下 pending，resolve_rows 会拒绝冲突，不能任选一份让测试通过。如果状态字段从节点删除、属性关系也被删除，完整性校验会报告源字段丢失。即使当前评测查询集没有筛选 status，也不能接受这种候选。

collapse_node 对源行有更严格条件：所属表不能被任何声明外键引用，当前行必须恰好连着两条属于该表的外键边，不能同时连着其他边，也不能折叠到自身。转换后的边仍保存原行数据与两个外键角色；重复购买分别成为不同的行边。这个约束针对桥接记录，不支持把任意高连接节点压成一条边。

materialize_join 也不只保存起点和终点。每条快捷边保留完整路径与中间节点序列；GraphExecutor 检查每一步是否对应当前外键邻接关系，再用路径计数核对该起点的快捷路径集合是否完整。缺少其中一条路径时，不启用这组不完整快捷边，而回到原始关系执行，避免把多跳连接的重复性悄悄压缩。

候选缓存绑定当前图版本，接受新图后才重新生成；失败候选不会改变当前图。重复检查使用“当前图内容＋工具名＋参数”的摘要，因此同一方案在同一图上不会反复消耗查询评估预算。非路径变换先移除旧快捷边，因为节点、字段或方向变化可能让旧路径失效；如需继续物化，应依据新图重新生成。

transform_batch 的每一步使用对应工具的原始参数结构：{tool, arguments}。只有完整组合后的图参与查询和成本验收，不要求各个中间状态先获得性能收益；任意一步失败则丢弃整个候选。连续路径物化可以保留不同快捷路径，但后续普通变换会使快捷路径失效，因此此类顺序直接被拒绝。

属性实体还可以成为实际查询入口。GraphExecutor 先根据当前图确认该表某列的全部非 NULL 行都被覆盖，且实体值与当前行值完全一致，再建立属性索引，用于 t0 根表筛选。覆盖不全、值已过期或拆词后的类别结构不能缩小扫描范围；执行器不会读取源表补全索引。报告用 physical_plan、source_rows_examined、attribute_index_hits 等字段记录是否使用该入口。

#正确性优先的成本验收

设 A 为通过查询数，L 为每题多次执行耗时中位数之和，P 为索引准备耗时，R 为预期查询执行次数。成本把索引准备分摊到预期使用量上，避免只测单次查询而忽略预处理。

Cost(G) = L(G) + P(G) / expected_query_runs
gain(round) = (Cost(current, round) - Cost(candidate, round)) / Cost(current, round)

performance_pass = all_rounds_correct
  AND median(gain) > min_speedup
  AND wins_over_threshold >= ceil(2 * comparison_rounds / 3)
  AND median_gain_when_current_first > min_speedup
  AND median_gain_when_candidate_first > min_speedup

accept = source_integrity_ok AND graph_growth_within_limit AND (
  A(candidate) > A(current)
  OR (A(candidate) = A(current) = query_count AND performance_pass)
)

默认 expected_query_runs=100、min_speedup=0.05、max_graph_growth=3.0。双方全部查询正确时，不直接拿候选与旧基线计时比较，而是执行 comparison_rounds 组成对测量，交替先测当前图或候选图。每组都必须保持查询正确，收益中位数及两种执行顺序各自的收益中位数都要严格超过阈值，且至少三分之二组超过阈值。最终还会独立复验保留下来的图。

运行报告记录源数据完整性错误、逐题差异、资源超限和 no_measured_improvement 等结果。最终图全部通过后，具备策略签名的有效候选才可写入 accepted、no_gain 或 unsafe 经验；no_change、graph_growth_budget_exceeded、comparison_query_failure 和无签名候选不写入策略观察。拒绝候选时继续保留当前图。

接受步骤在运行查询前设置多道检查。参数与图结构不合法时直接拒绝；候选与当前图相同时返回 no_change；节点与边总数超过初图规模乘以 max_graph_growth 时返回 graph_growth_budget_exceeded；完整源记录与外键核对失败时返回 source_fidelity_failed。只有通过这些检查，才运行完整冻结查询。source_fidelity_failed 是协议中的固定错误码，中文含义是源数据完整性检查失败。

正确率使用通过查询的数量，不用自然语言回答质量评分。即使一个候选更慢，只要比当前图通过更多查询，也能成为下一轮的当前图；这种中间接受不代表已经达到发布条件。只有双方全部查询正确时，才按 min_speedup 比较成本。最后一次验证会重新执行实际保留下来的图，避免把曾经通过的候选或模型的结束请求误当作最终结果。

每条查询先预热一次，再取 benchmark_repeats 个计时样本；每个样本自适应重复执行，目标至少运行 min_query_seconds，并受次数与总时间预算约束。报告将样本时间除以实际执行次数，再取中位数，各题相加得到 L。每轮索引准备单独计入 P，参考执行器耗时不计入图成本。结果预览最多 20 行，比较仍覆盖完整结果：无排序时保留重复行，有排序时检查次序和同分组。这里测量的是进程内 GraphExecutor，不是生产 NebulaGraph 的端到端延迟。

模型得到的逐题反馈包含是否正确、结果条数、错误与耗时，不包含 expected_preview 或 actual_preview 中的具体答案。完整答案预览保留在私有运行报告中。这样模型可以定位错误类型和慢查询，同时仍由执行器提供正确答案与最终判断。

history[].comparison 保留每轮顺序、双方成本、收益、超过阈值的次数及接受判据。逐题 timing_iterations、measured_query_runs、warmup_runs 解释实际执行次数，不能再把 benchmark_repeats 当作总查询调用数。materialized_path_hits 统计计时执行命中的物化路径，不是新增边数。

#领域经验如何改变策略

领域画像支持 finance、academic、commerce、healthcare、social、general。自动识别基于领域描述、表名和列名；描述命中权重为数据结构的 2 倍，最高得分必须达到 3；当第二类也达到 3 且最高分不足它的 1.75 倍时归入 general。显式指定类别的 confidence 为 1。

DomainExperienceStore 继续使用 users/<user>/construction-experience/strategies.sqlite3，其中 <user> 为默认工作区归属。经验保存策略类型、结构计数、查询组合、正确性和成本收益；原始数据行、SQL、提示词、表列名及完整工具参数不进入可迁移经验。经验通过数据结构与逻辑行生成逻辑源摘要来去重；报告中的 source_sha256 单独记录原始文件字节摘要。

policy_score = clip(
  (sum(reward_i * similarity_i) / (sum(similarity_i) + 2))
  * mean(similarity_i), -1, 1
)

priority = domain_and_structure_prior
         + evidence_weight * similarity * policy_score
         - safety_penalty

同一源、领域、策略与结构模式只保留最新证据，重复运行不会增加独立源数量。负反馈降低优先级而非永久禁用策略；相似结构也必须在新数据上重新验证。经验保留最多 2,048 条源模式证据与 256 个模式；写入回执保留最近 4,096 条及仍被证据引用的旧回执。

经验检索发生在评测查询集冻结并测量基线之后，因此上下文包含实际查询组合，而不只是“电商”这个领域标签。当前构图期间的候选反馈立即返回模型；持久策略库则只在最终图通过之后更新，供后续任务使用。重新执行相同输入会替换该源与模式的最新观察，而不会把重试次数当成新的来源数量。

策略摘要只识别可解释的结构特征。optimize_graph 若在同一批里混合多种 op，就不把整批效果归功于某一种策略；无法提取签名的候选仍可评估，只是不写可迁移证据。候选无变化、超过图增长上限也不记录策略观察。accepted 和 no_gain 必须附带全部查询通过的计数；不满足该条件的观察会归为 unsafe，收益归零。

经验服务是可选指导。experience_enabled=false 时不检索也不写入；没有配置存储实例时报告 no_store；读取失败记为 unavailable，写入失败记为 write_failed。只要当前图通过完整验证，经验库暂时不可用不会把一个有效构图结果变成失败。报告中的这些状态应与“经验为空”的冷启动区分。

候选最终排序还结合本轮实测热点：search_priority = measured_query_cost_share + 0.1 × priority。前一项是候选覆盖查询占当前总查询耗时的比例，后一项才是领域与经验优先级。transform_batch 当前没有独立策略签名，组合候选仍可验收并记入 history，但不会把整批收益归给单一策略并写入经验库。

#发起构图与检查结果

应用中先上传个人数据集，再从数据集面板启动构图。主智能体的 graph_construction 技能检查状态，并在 ready 后调用 load_constructed_graph。首次 build 使用 Backend 数据集接口；公共 MCP 目录没有同名的 build 工具。

curl -X POST http://localhost:21108/api/personal-datasets \

# Replace DATASET_ID with dataset.dataset_id from the upload response.
curl -X POST http://localhost:21108/api/personal-datasets/DATASET_ID/construction/build \
  -H "Content-Type: application/json" \
  -d '{"options":{"mode":"rules","query_count":15}}'

排查自己的数据时，先核对节点与外键边数量，再查看 workload_coverage 是否对应预期业务，检查 history 中的候选原因，最后比较 experience 的检索和写入状态。若所有查询通过但 accepted_candidates=0，应读取 no_measured_improvement 与成本，而不是直接判断构图失败。本页的小型配置与查询片段用于说明机制。

#构图状态与失败后处理

进度展示实际阶段和已有指标，不代表中间图已可发布。构图期间和恢复检查期间，图编辑会被拒绝；成功后再读取真实 revision 进行编辑。构图结果保存到数据集与加载到会话是两步，详见数据集与工作台操作说明。

• 从数据集进入分析↗
• 工作台操作↗

#预览、提交与版本冲突

构图文档采用 construction_graph.v1。编辑前读取最新 graph 和 revision；preview 验证候选操作，commit 持久化同一组操作。请求携带 base_revision，防止用旧图覆盖新版本。

自动构图的候选验收与保存后编辑是两个阶段。构图子智能体在隔离副本上探索，并以源数据完整性和冻结查询选择结果；保存图后的 preview/commit 是用户明确请求的版本化编辑流程。每次编辑先读取真实 ID 与 base_revision，预览成功后提交完全相同的操作。出现 revision_conflict 时必须重新读取和预览，不能只把请求中的版本号加一后重放。

提交成功后，数据集的图版本增加，但当前分析会话仍需要 load_constructed_graph 才会切换到该保存结果。由 get_graph_info 核对加载后的规模和状态，再执行分析工具。构图报告是当前构建过程的说明，不能作为后续手动编辑仍通过旧评测查询集的证明。

这三种“预览”用途不同：source-preview 查看上传内容；schema 展示已保存图的类型结构和字段统计；POST preview 验证版本化编辑的影响。个人与项目数据集均提供对应 construction 系列接口，项目路径前缀为 /api/projects/{project_id}/datasets/{id}，并按归属校验访问。

#资源预算与运行报告

关系构图默认还包括 max_tool_calls=24、benchmark_repeats=5、comparison_rounds=3、min_query_seconds=0.003、llm_timeout_seconds=120；bounded 配置下单次图查询最多 10 秒与 200,000 条中间记录。语义 TXT 每个分块最多尝试 3 次，并与整个任务共享 max_seconds；字符数、分块数、调用数或图规模超限会使整个构图失败。两条路径都不会把截断数据生成的图当作完整成功结果。

上述源解析默认值属于 resource_profile="bounded"。API/CLI 可显式选择 full_scale，将源文件、源行、SQL 导入时间上限分别提高到 8 GiB、10,000,000 行和 7,200 秒，并提高图规模及内部查询预算。它不是自动流式处理承诺：CSV 和文本仍会装入内存，只有 SQLite 镜像改为只读文件访问。HTTP 构图仍将 max_seconds 限在 1–3,600 秒，整体截止时间优先于较长的内部预算；CLI 的 full_scale 范围另行处理。部署资源和入口限制也可能先达到上限。

evolution-report.json 使用 tabular_evolution.v1 描述一次构图。上表中的固定评测查询、基线、候选历史与策略经验适用于关系构图路径；语义 TXT 使用 construction_kind=text_entities 和 semantic_extraction 记录分块抽取情况，不执行同一套 SQL 对照评测。图版本与报告由 Graph Engine 保存，领域经验按执行路径记录；用户另行选择何时把保存结果加载到分析会话。

显式 options 优先于对应 GRAPH_CONSTRUCTION_<字段大写> 环境变量，最后使用默认值。query_count 等计数必须为真正的整数，布尔值不能冒充 1；超时和比例要求有限数值并落在允许区间。mode 只能为 llm 或 rules；domain_category 支持 auto 与六个领域类别。源文件大小、行数和 SQL 导入时间属于单独的源解析选项，不要把任意配置名称都推导成可用环境变量。

总时间预算通过上下文局部的 deadline 向下传递。嵌套解析、变换和查询使用更早的截止时间；长序列扫描在进入、每 1,024 项和结束时检查。单次模型请求的超时为 llm_timeout_seconds 与剩余总时间中的较小值；SQL 导入和单题执行也受自己的上限及总剩余时间双重约束。服务模式还有进程监督，用于处理无法在 Python 检查点及时返回的本地代码或网络调用。

运行报告的 source_sha256 是输入文件字节摘要，workload_sha256 是规范查询集合摘要，final_graph_sha256 是规范图内容摘要；它们各自验证不同对象。跨构图来源去重另用逻辑源摘要，工作进程回执的 sha256 则针对实际 graph.json 文件字节。不要把这些字段互相替换，尤其不要用“文件摘要变化”推断出现了一个新的逻辑数据来源。

工作台展示构图状态、进度与保存结果，目前没有完整 evolution-report.json 的专用下载按钮。CLI 报告位于 --output 指定目录；服务部署的报告位于 Graph Engine 数据根目录下 users/<user_id>/datasets/<dataset_id>/construction/evolution-report.json。排查时由有权访问该部署的人员读取对应文件，不应把页面进度摘要当作完整报告。