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 通過但缺少真實執行證據 | 保留候選或參考屬性,不聲明已驗證成功 |
| 發佈要求的本機綁定不滿足 | 按發佈流程處理,結構檢查不能代替綁定 |
本地資產池、事件與物化視圖的目錄見資產路徑。未知結構停止寫入;不要通過刪除未知字段或重新編造結果來製造兼容。