EvoX 文档
  • 产品
  • 价格
  • 文档
  • 能力市场
返回 EvoMap
登录注册
概览
实践案例
功能
配置
开发者
GEP 数据结构蒸馏 Gene、Skill 与 RecipeRecipe 与经验复用Evolver Proxy 与 MCP同步、导入与导出A2A 与任务网络接入
架构与源码仓库
安全
管理
概览
实践案例
功能
配置
开发者
GEP 数据结构蒸馏 Gene、Skill 与 RecipeRecipe 与经验复用Evolver Proxy 与 MCP同步、导入与导出A2A 与任务网络接入
架构与源码仓库
安全
管理
EvoX 文档/使用 EvoX 开发/GEP 数据结构

GEP 数据结构

GEP 用结构化对象表达方法、执行结果与过程记录。开发集成时,先选对对象,再校验字段、内容标识与引用关系。本页使用 @evomap/gep-sdk 提供的正式 schema 和哈希函数;对象的存储、执行和发布由 Evolver 与 Hub 分别处理。

选择对象

对象表达什么不能替代什么
Gene触发信号、前提、策略、限制与验证要求某一次真实执行的成功证据
Capsule一次结果、所用 Gene、影响范围和结果声明其他项目的复验证据
EvolutionEvent一次尝试的意图、信号、资产关联和结果可直接执行的技能正文
Recipe按顺序引用 Gene/Capsule 的编排记录新的 Gene 内容哈希

ValidationReport 承接验证环境、命令与证据;Memory 承接本地关系与召回记录。它们有各自的存储和运行时契约,不能套用 Gene schema。

Gene 字段

字段类型与作用
type、schema_version固定对象类型和协议结构版本
id对象标识,与内容寻址的 asset_id 分开
categoryrepair、optimize、innovate 或 explore
signals_match非空触发信号数组
preconditions执行前必须成立的前提
strategy非空、有顺序的方法步骤
constraints包含正整数 max_files 与非空 forbidden_paths
validation非空验证要求数组,不会因存在该字段而自动执行
asset_id对规范化内容计算的 sha256: 标识

构造或导出资产前,从自由文本字段与关联产物中移除 node_secret、访问令牌、签名密钥、生产凭证、个人信息和私有路径。schema 与内容哈希校验不检查秘密,也不授予发布权限。单独授权发布前,使用 evolver_asset_validate 做本地脱敏、质量与安全检查,并审阅结果。

构造并校验一个 Gene

在独立示例目录安装校验依赖,保存下面代码为 validate-gene.mjs:

bash
npm init -y
npm install @evomap/gep-sdk ajv
javascript
import Ajv from "ajv";
import { SCHEMA_VERSION, computeAssetId, verifyAssetId } from "@evomap/gep-sdk";
import geneSchema from "@evomap/gep-sdk/schemas/gene.schema.json" with { type: "json" };

const gene = {
  type: "Gene",
  schema_version: SCHEMA_VERSION,
  id: "gene_fix_horizontal_overflow",
  category: "repair",
  signals_match: ["horizontal_overflow"],
  preconditions: ["A browser reproduction and editable source are available."],
  strategy: [
    "Reproduce the overflowing layout at the reported viewport.",
    "Identify the element and the width constraint causing overflow.",
    "Fix that constraint and verify menu interaction and desktop layout."
  ],
  constraints: { max_files: 3, forbidden_paths: [".git", ".env"] },
  validation: ["Run the project checks and exercise the affected menu at both phone widths."],
  asset_id: ""
};
gene.asset_id = computeAssetId(gene);
const validate = new Ajv({ allErrors: true }).compile(geneSchema);
if (!validate(gene) || !verifyAssetId(gene)) throw new Error("Invalid Gene");
console.log(JSON.stringify(gene, null, 2));

运行 node validate-gene.mjs,完成结构与哈希校验并输出包含内容哈希的 Gene。此命令只在本地构造和校验对象,不执行策略、写入 Evolver 资产库或对外发布。

使用 SDK 的 SCHEMA_VERSION 生成结构版本,不把 npm 包版本或 Desktop 版本写入该字段。内容修改后重新计算 asset_id;不能沿用修改前的哈希或验证绑定。

Capsule 与过程记录的关联

Capsule 使用 gene 关联 Gene,并通过 trigger、summary、blast_radius 和 outcome 表达这次结果。confidence 在 0–1 之间,但置信度高不等于已有执行证据。引用的 Gene 必须可解析,结果声明与实际产物、验证记录对应。

EvolutionEvent 使用 genes_used、mutation_id 和 capsule_id 追踪尝试,保留信号、来源与结果。区分事件标识、资产内容标识和远端操作 ID,不用一个字符串承担所有关联。

校验一组关联对象

先执行上一个示例,将 Gene 保存为 gene.json:

bash
node --input-type=module -e 'import { execFileSync } from "node:child_process"; import { writeFileSync } from "node:fs"; const output = execFileSync(process.execPath, ["validate-gene.mjs"]); writeFileSync("gene.json", output, { flag: "wx" });'

校验完成后才创建文件。命令拒绝覆盖已有的 gene.json;保留原文件,并在另一个独立示例目录中生成新的对象。

将下列代码保存为 validate-related.mjs。它在本地构造一个没有执行修复的失败分支示例,避免用虚构的成功结果演示证据。对象不写入 Evolver 运行历史,也不发送到 Hub。

javascript
import { readFileSync, writeFileSync } from "node:fs";
import Ajv from "ajv";
import { SCHEMA_VERSION, computeAssetId, verifyAssetId } from "@evomap/gep-sdk";
import capsuleSchema from "@evomap/gep-sdk/schemas/capsule.schema.json" with { type: "json" };
import eventSchema from "@evomap/gep-sdk/schemas/evolution-event.schema.json" with { type: "json" };
import recipeSchema from "@evomap/gep-sdk/schemas/recipe.schema.json" with { type: "json" };

const gene = JSON.parse(readFileSync("gene.json", "utf8"));
if (gene.type !== "Gene" || !verifyAssetId(gene)) throw new Error("Invalid source Gene");
const capsule = {
  type: "Capsule", schema_version: SCHEMA_VERSION, id: "capsule_schema_example",
  trigger: ["horizontal_overflow"], gene: gene.id,
  summary: "Schema example only; no project repair was executed.",
  confidence: 0, blast_radius: { files: 0, lines: 0 },
  outcome: { status: "failed", score: 0 }, asset_id: ""
};
capsule.asset_id = computeAssetId(capsule);
const event = {
  type: "EvolutionEvent", schema_version: SCHEMA_VERSION, id: "event_schema_example",
  intent: "repair", signals: ["horizontal_overflow"], genes_used: [gene.id],
  mutation_id: "", capsule_id: capsule.id, blast_radius: capsule.blast_radius,
  outcome: capsule.outcome, source_type: "user_authored", asset_id: ""
};
event.asset_id = computeAssetId(event);
const recipe = {
  title: "Inspect horizontal overflow",
  description: "A local create-payload example; no Hub record is created.",
  steps: [{ asset_id: gene.asset_id, asset_type: "Gene", position: 0 }]
};
const ajv = new Ajv({ allErrors: true });
for (const [schema, object] of [[capsuleSchema, capsule], [eventSchema, event], [recipeSchema, recipe]]) {
  const validate = ajv.compile(schema);
  if (!validate(object)) throw new Error(JSON.stringify(validate.errors));
}
if (!verifyAssetId(capsule) || !verifyAssetId(event)) throw new Error("Hash mismatch");
if (capsule.gene !== gene.id || !event.genes_used.includes(gene.id) || event.capsule_id !== capsule.id) {
  throw new Error("Broken local references");
}
writeFileSync("related-objects.json", JSON.stringify({ capsule, event, recipe }, null, 2), { flag: "wx" });
console.log("Capsule, EvolutionEvent, and Recipe structure and local references validated");

运行 node validate-related.mjs。通过后新建 related-objects.json,包含三个经过正式 schema 校验的对象;文件已存在时保留原文件并报错,不覆盖内容。这里 gene、genes_used 与 capsule_id 关联本地逻辑 ID,Recipe 步骤关联内容 asset_id;不能混用。

mutation_id 留空表示本示例没有引用实际变更。记录真实执行时,使用运行器产生的变更、验证报告和产物关联。成功记录的 outcome、影响范围和证据必须来自那次执行;不能把这份结构示例改成 success 后充作成功历史。

对结果做三个负例检查:修改 Capsule 的 summary 后不更新哈希,应拒绝;把 confidence 改成 2,应拒绝;将 capsule_id 指向未加载的对象,应判定引用缺失。schema 只检查字符串类型,引用解析必须单独完成。

Recipe 的结构区别

Recipe 创建数据至少包含 title 和非空 steps。每一步指定 asset_id 与 asset_type(Gene 或 Capsule),可附条件、参数与可选步骤设置。引用的资产必须已经存在于目标 Hub,且类型相符。

Recipe 由 Hub 分配记录 ID,不按 Gene/Capsule 的方式生成内容寻址 ID。 步骤顺序、输入输出契约和执行状态见Recipe 与经验复用。制作流程见蒸馏 Gene、Skill 与 Recipe。

对失败进行分层处理

失败处理
category 不在枚举中、signals 为空或字段类型错误修正结构,不自动转换类型
内容改动但 asset_id 没变重新计算并校验哈希
Capsule 的 Gene 引用缺失取得对应对象并验证关系,再继续导入
schema 通过但缺少真实执行证据保留候选或参考属性,不声明已验证成功
发布要求的本机绑定不满足按发布流程处理,结构检查不能代替绑定

本地资产池、事件与物化视图的目录见资产路径。未知结构停止写入;不要通过删除未知字段或重新编造结果来制造兼容。

上一篇Hooks下一篇蒸馏 Gene、Skill 与 Recipe