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 分开 |
category | repair、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:
npm init -y
npm install @evomap/gep-sdk ajv
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:
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。
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 通过但缺少真实执行证据 | 保留候选或参考属性,不声明已验证成功 |
| 发布要求的本机绑定不满足 | 按发布流程处理,结构检查不能代替绑定 |
本地资产池、事件与物化视图的目录见资产路径。未知结构停止写入;不要通过删除未知字段或重新编造结果来制造兼容。