Edict Lang

Edict

专为 AI Agent 设计的编程语言。 无需解析器，无需语法。Agent 直接以 JSON 形式生成 AST。

Edict 是一种静态类型、追踪副作用的编程语言，其规范程序格式为 JSON AST。它专为 AI Agent 打造，让 Agent 能够通过结构化流程编写、验证和执行程序——无需解析文本、无需人类可读的语法，也没有歧义。

Agent (LLM)
  │  produces JSON AST via MCP tool call
  ↓
Schema Validator ─── invalid? → StructuredError → Agent retries
  ↓
Name Resolver ────── undefined? → StructuredError + candidates → Agent retries
  ↓
Type Checker ─────── mismatch? → StructuredError + expected type → Agent retries
  ↓
Effect Checker ───── violation? → StructuredError + propagation chain → Agent retries
  ↓
Contract Verifier ── unproven? → StructuredError + counterexample → Agent retries
  (Z3/SMT)            ↓
                  Code Generator (pure-JS WASM encoder) → WASM → Execute

特性

• JSON AST — 程序是 JSON 对象，而非文本文件。无需词法分析器或解析器。
• 结构化错误 — 每个错误都是带类型的 JSON 对象，包含足够的上下文，供 Agent 自行修复。
• 类型系统 — Int、Float、String、Bool、Array<T>、Option<T>、Result<T,E>、记录、枚举、细化类型。
• 副作用追踪 — 函数声明 pure、reads、writes、io、fails。编译器会验证其一致性。
• 合约验证 — 使用 Z3（通过 SMT）在编译时验证前置条件和后置条件。未通过验证的合约会返回具体反例。
• WASM 编译 — 经过验证的程序通过纯 JS 编码器编译为 WebAssembly，并在 Node.js 中运行。
• MCP 接口 — 所有工具都通过 Model Context Protocol 提供，便于 Agent 直接集成。
• 模式迁移 — 旧模式版本的 AST 会自动迁移。语言演进时不会造成破坏。

执行模型

Edict 编译为 WebAssembly，并在沙箱虚拟机中运行。这是经过深思熟虑的安全决策，而非限制：

• 无隐式权限 — 编译后的 WASM 无法访问文件系统、网络或操作系统，除非宿主通过可插拔的 EdictHostAdapter 接口显式提供这些能力
• 编译时能力声明 — 副作用系统（io、reads、writes、fails）让宿主能在运行程序_之前_检查程序所需的能力
• 运行时强制执行 — RunLimits 控制执行超时、内存上限和文件系统沙箱
• 纵深防御 — 立即运行的 Agent 生成代码需要比经人工审核的代码更强的隔离。副作用系统 + WASM 沙箱 + 宿主适配器模式恰好提供了这种隔离

通过适配器提供的宿主能力：文件系统（沙箱化）、HTTP、加密（SHA-256、MD5、HMAC）、环境变量、CLI 参数。扩展 EdictHostAdapter 即可添加新能力。

快速开始

面向 AI Agent（MCP）

使用 Edict 最快的方式是通过 MCP 服务——它将整个编译器流程作为工具调用提供：

npx edict-lang          # start MCP server (stdio transport, no install needed)

或者在本地安装：

npm install edict-lang
npx edict-lang          # start MCP server

只需两次调用即可开始：edict_schema（了解 AST 格式）→ edict_check（提交程序）。完整工具列表请参阅 MCP 工具。

面向开发

npm install
npm test          # 2675 tests across 136 files
npm run mcp       # start MCP server (stdio transport)

Docker

在容器中运行 Edict MCP 服务——无需本地安装 Node.js：

# stdio transport (default — for local MCP clients)
docker run -i ghcr.io/sowiedu/edict

# HTTP transport (for remote/networked MCP clients)
docker run -p 3000:3000 -e EDICT_TRANSPORT=http ghcr.io/sowiedu/edict

支持的平台：linux/amd64、linux/arm64。

浏览器

完全在浏览器中运行 Edict 编译器——无需服务端：

Bundle	大小	阶段	用例
edict-lang/browser	318 KB	1–3（验证、解析、类型检查、效果检查、lint、补丁）	轻量检查
edict-lang/browser-full	~14 MB	1–5（+ WASM 代码生成、Z3 合约、WASM 执行）	完整编译与运行

import { compileBrowser, runBrowserDirect } from 'edict-lang/browser-full';

const result = compileBrowser(astJson);
if (result.ok) {
    const run = await runBrowserDirect(result.wasm);
    console.log(run.output);  // "Hello, World!"
}

注意：ESM 模块需要通过 HTTP 提供服务。使用 npx serve . 或任意静态服务器——file:// 无法运行。

参见 examples/browser/index.html 中的可运行示例。

QuickJS（沙盒环境）

Edict 编译器也可在 QuickJS WASM 中运行——适用于沙盒运行时、边缘 Worker，或嵌入其他 WASM 应用：

Bundle	大小	阶段	相较 Node.js 的减速比
dist/edict-quickjs-check.js	373 KB	1–3（验证、解析、类型检查、效果检查）	~3.7x
dist/edict-quickjs-full.js	932 KB	1–5（检查 + WASM 编译）	~3.7x

import { EdictQuickJS } from "edict-lang/quickjs";

const edict = await EdictQuickJS.createFull();  // phases 1-5
const result = edict.compile(ast);
if (result.ok) {
    console.log(result.wasm);  // Uint8Array of valid WASM
}
edict.dispose();

注意：quickjs-emscripten 是可选的 peer dependency——要使用 EdictQuickJS，请将它与 edict-lang 一同安装。对于不支持 fs 的环境，请直接传入 bundleSource，而不是从磁盘加载。

完整基准测试和建议请参见 docs/quickjs-feasibility-report.md。

MCP 工具

工具	描述
edict_schema	返回完整的 AST JSON Schema——编写程序的规范
edict_version	返回编译器版本和能力信息
edict_examples	以 JSON AST 形式返回 41 个示例程序（包含 Schema 片段）
edict_validate	验证 AST 结构（字段名称、类型、节点种类）
edict_check	完整流水线：验证 → 解析名称 → 类型检查 → 效果检查 → 验证合约
edict_compile	将经过检查的 AST 编译为 WASM（返回 base64 编码的二进制文件）
edict_run	执行已编译的 WASM 二进制文件，返回输出和退出代码
edict_patch	按 nodeId 应用定向 AST 补丁并重新检查
edict_errors	返回所有错误类型的机器可读目录
edict_lint	运行非阻断式质量分析并返回警告
edict_debug	执行跟踪和崩溃诊断
edict_compose	将可组合的程序片段合并为一个模块
edict_explain	解释 AST 节点、错误或编译器行为
edict_export	将程序打包为 UASF 可移植技能
edict_import_skill	导入并执行 UASF 技能包
edict_generate_tests	根据 Z3 验证的合约生成测试
edict_replay	记录并回放确定性执行跟踪
edict_deploy	将 Edict 程序编译并部署到边缘运行时（Cloudflare Workers）
edict_invoke	通过 HTTP 调用已部署的 Edict WASM 服务
edict_invoke_skill	直接调用 UASF 技能包
edict_package	将已编译的程序打包为可部署的技能包
edict_support	返回用于故障排查的诊断信息和环境信息

MCP 资源

URI	描述
edict://schema	完整的 AST JSON Schema
edict://schema/minimal	适用于节省令牌的快速引导的最小 Schema 变体
edict://examples	所有示例程序
edict://errors	机器可读的错误目录
edict://schema/patch	AST 补丁协议的 JSON Schema
edict://guide	面向 MCP 优先上手流程的 Agent 引导指南
edict://support	诊断信息和环境信息

示例程序

Edict 的 JSON AST 中的“Hello, World!”：

{
  "kind": "module",
  "id": "mod-hello-001",
  "name": "hello",
  "imports": [],
  "definitions": [
    {
      "kind": "fn",
      "id": "fn-main-001",
      "name": "main",
      "params": [],
      "effects": ["io"],
      "returnType": { "kind": "basic", "name": "Int" },
      "contracts": [],
      "body": [
        {
          "kind": "call",
          "id": "call-print-001",
          "fn": { "kind": "ident", "id": "ident-print-001", "name": "print" },
          "args": [
            { "kind": "literal", "id": "lit-msg-001", "value": "Hello, World!" }
          ]
        },
        { "kind": "literal", "id": "lit-ret-001", "value": 0 }
      ]
    }
  ]
}

Agent 循环

核心设计：Agent 提交 AST → 编译器验证 → 如果有误，则返回包含足够上下文的 StructuredError，让 Agent 能够自行修复 → Agent 修正 → 重新提交。

// 1. Agent reads the schema to learn the AST format
const schema = edict_schema();

// 2. Agent writes a program (may contain errors)
const program = agentWritesProgram(schema);

// 3. Compile — returns structured errors or WASM
const result = edict_compile(program);

if (!result.ok) {
  // 4. Agent reads errors and fixes the program
  //    Errors include: nodeId, expected type, candidates, counterexamples
  const fixed = agentFixesProgram(program, result.errors);
  // 5. Resubmit
  return edict_compile(fixed);
}

// 6. Run the WASM
const output = edict_run(result.wasm);

架构

src/
├── ast/           # TypeScript interfaces for every AST node
├── validator/     # Schema validation (structural correctness)
├── resolver/      # Name resolution (scope-aware, with Levenshtein suggestions)
├── checker/       # Type checking (bidirectional, with unit types)
├── effects/       # Effect checking (call-graph propagation)
├── contracts/     # Contract verification (Z3/SMT integration)
├── codegen/       # WASM code generation (pure-JS encoder)
│   ├── codegen.ts       # IR → WASM module orchestration
│   ├── compile-ir-expr.ts  # IR expression compilation
│   ├── compile-ir-*.ts  # Specialized IR compilers (calls, data, match, scalars)
│   ├── runner.ts        # WASM execution (Node.js WebAssembly API)
│   ├── host-adapter.ts  # EdictHostAdapter interface + platform adapters
│   ├── closures.ts      # Closure capture and compilation
│   ├── hof-generators.ts # Higher-order function WASM generators
│   ├── wasm-encoder.ts  # Pure-JS WASM binary encoder (replaced binaryen)
│   ├── wasm-interpreter.ts # Pure-JS WASM interpreter (no WebAssembly API needed)
│   ├── recording-adapter.ts # Execution recording for replay
│   ├── replay-adapter.ts  # Deterministic replay from recorded traces
│   └── string-table.ts  # String interning for WASM memory
├── ir/            # Mid-level IR (lowering, optimization)
├── builtins/      # Builtin registry and domain-specific builtins
├── compact/       # Compact AST format (token-efficient for agents)
├── compose/       # Composable program fragments
├── deploy/        # Edge deployment scaffolding (Cloudflare Workers)
├── incremental/   # Incremental checking (dependency graph + diff)
├── lint/          # Non-blocking quality warnings
├── patch/         # Surgical AST patching by nodeId
├── migration/     # Schema version migration (auto-upgrade older ASTs)
├── skills/        # Skill packaging and invocation
├── mcp/           # MCP server (tools + resources + prompts)
└── errors/        # Structured error types

tests/             # 2675 tests across 136 files
examples/          # 41 example programs (⭐→⭐⭐⭐ difficulty in README)
schema/            # Auto-generated JSON Schema

类型系统

类型	示例
基本类型	Int、Int64、Float、String、Bool
数组	Array<Int>
可选类型	Option<String>
结果	Result<String, String>
记录	Point { x: Float, y: Float }
枚举	Shape = Circle { radius: Float } | Rectangle { w: Float, h: Float }
精化类型	{ i: Int | i > 0 } — 由 Z3 验证的谓词
函数	(Int, Int) -> Int

效果系统

函数会声明其效果。编译器会强制执行以下规则：

• pure 函数不能调用 io 函数
• 效果会沿调用图传播
• 会检测并报告缺失的效果

效果：pure、reads、writes、io、fails

契约验证

使用 Z3 在编译时验证前置条件和后置条件：

{
  "kind": "post",
  "id": "post-001",
  "condition": {
    "kind": "binop", "id": "binop-001", "op": ">",
    "left": { "kind": "ident", "id": "ident-result-001", "name": "result" },
    "right": { "kind": "ident", "id": "ident-x-001", "name": "x" }
  }
}

Z3 要么证明 unsat（契约成立 ✅），要么返回 sat，并提供一个具体的反例供 Agent 推理。

贡献

我们欢迎 Agent 和人类贡献者参与。有关设置说明、编码规范和 PR 工作流，请参阅 CONTRIBUTING.md。

想找一个入门任务？ 查看标记为 good first issue 的问题。

路线图

完整的开发计划请参阅 ROADMAP.md，语言规范请参阅 FEATURE_SPEC.md，有关 Agent 如何存储和复用经过验证的 WASM 技能，请参阅 结晶化智能。

支持

Edict 基于 MIT 许可证免费开源。如果你的 Agent 认为它很有价值，可以考虑赞助其开发。

许可证

MIT