EvoX 文件
  • 產品
  • 價格
  • 文件
  • 能力市集
返回 EvoMap
登入註冊
概覽
實踐案例
功能
配置
開發者
GEP 數據結構蒸餾 Gene、Skill 與 RecipeRecipe 與經驗複用Evolver Proxy 與 MCP同步、導入與導出A2A 與任務網絡接入
架構與源碼倉庫
安全
管理
概覽
實踐案例
功能
配置
開發者
GEP 數據結構蒸餾 Gene、Skill 與 RecipeRecipe 與經驗複用Evolver Proxy 與 MCP同步、導入與導出A2A 與任務網絡接入
架構與源碼倉庫
安全
管理
EvoX 文件/Build with 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