EdgeChains · 智能体框架与编排

引言：从"调 API"到"写工厂"——GenAI 应用开发的范式转变

想象一个场景：你是一家电商公司的 AI 工程师，产品经理提出了一个需求——"用户上传商品 PDF 手册，我们用 AI 提取参数，回答用户关于这个商品的任何问题"。你会怎么做？

最朴素的做法是直接调用 OpenAI API，把 PDF 内容塞进 prompt。但当你真正动手时会发现：这涉及到多个环节——PDF 解析、文本分块、向量化存储、相似度检索、上下文注入、prompt 链式组装……每一步都需要精心设计。更要命的是，当你想在另一个场景（比如客服对话）复用这套逻辑时，发现 Prompt 已经"写死"在代码里了，改动成本极高。

EdgeChains.js 正是为解决这个痛点而生。它的核心主张是：GenAI 应用不是"调 API"，而是"工厂流水线"——需要用工业级配置管理思维来管理 Prompt 和 Chain。

背景：Prompt 工程界的"Kubernetes ConfigMap"

EdgeChains 由 Arakoo 团队开发，核心作者 Prakash（GitHub @arakoodev）是一个在云原生基础设施领域有深厚背景的开发者。EdgeChains 的设计灵感来源于 Google 内部管理 Borg 配置文件的经验——Google 用 Jsonnet 来管理海量的基础设施配置，而 EdgeChains 把这套方法论迁移到了 Prompt 工程领域。

这个选择绝非偶然。Prompt 工程有三个天然的"工程化难题"：

Prompt 膨胀（Prompt Explosion）：REACT、CoT、HygE 等不同的 Prompt 技术，对不同模型（GPT-3.5 vs Llama2）的效果差异巨大，导致 Prompt 数量爆炸式增长。
Prompt 漂移（Prompt Drift）：ChatGPT 的行为会随时间变化（已有研究证实），生产环境的 Prompt 需要持续追踪和版本管理。
Prompt 可测试性：传统框架把 Prompt 封装在类/函数里，测试和迭代极不方便。

EdgeChains 的答案是：让 Prompt 活在代码之外。

核心技术：Jsonnet 驱动的声明式 Chain 编排

EdgeChains 的技术架构可以类比为"给 GenAI 应用装上了配置管理层"。它基于两个成熟的基础设施库构建：

Hono.js（Cloudflare 出品）：轻量级高性能 Web 框架，作为 HTTP 服务层
Jsonnet（Google 出品）：带变量和函数的 JSON 超集，专门用于配置管理

声明式 Prompt 管理

在 EdgeChains 中，一个完整的 AI Chain 只需要两个文件：

// main.jsonnet
local OPENAI_API_KEY = import "secrets.jsonnet".openai_api_key;

{
  chain: {
    steps: [
      { type: "prompt", template: "请总结以下内容：{input}" },
      { type: "llm", provider: "openai", model: "gpt-4", api_key: OPENAI_API_KEY }
    ]
  }
}

所有 Chain 逻辑以 Jsonnet 文件形式存在，具备：

版本控制：直接用 Git 管理，和普通代码无异
差异化（Diffable）：每次改动都能看到具体差异
外部化：可以放在 S3 或远程 API，运行时动态加载
Token 计量：内置 Token 消耗统计，方便成本管控

多模态文档处理

EdgeChains 提供了完整的文档处理链路：

模块	功能
`document-loader`	解析 PDF、网页、Markdown 等多格式文档
`splitter`	智能文本分块，保持语义完整性
`vector-db`	集成 Supabase 向量数据库，支持语义检索
`arakooserver`	内置 Hono HTTP 服务，暴露 REST API
`scraper`	网页内容抓取，构建实时知识库

以 PDF 问答为例（chat-with-pdf 示例），完整流程是：

PDF上传 → cheerio/pdf-parse解析 → 1536维OpenAI Embedding → Supabase向量存储
    ↓
用户提问 → Embedding检索 → 上下文组装 → GPT-4生成回答

函数调用（Function Calling）自动化

EdgeChains 内置了函数调用（Tool Use）的能力，支持将外部 API（如天气查询、数据库查询）无缝集成到 Chain 中。例如 getWeather-or-time-function-calling 示例，展示了如何让 LLM 自主决定调用哪个工具：

// 声明工具
const tools = [
  { name: "get_weather", description: "获取城市天气", params: { city: "string" } },
  { name: "get_time", description: "获取当前时间", params: { timezone: "string" } }
];
// EdgeChains 自动处理 Tool Selection、调用和结果回填

研究型 Agent 框架

research-agent 示例是 EdgeChains 最复杂的应用场景之一：让 AI 自主规划研究路径、搜索信息、整合结论。用户只需要描述研究目标，系统自动完成多轮信息检索与分析，最终输出结构化报告。这个模式特别适合竞品分析、市场调研、学术综述等场景。

React 前端集成

react-chain 示例展示了如何将 EdgeChains 后端与 React 前端结合。React 组件通过 /src/routes/react-chain.ts 暴露的 API 与后端通信，前端只需几行代码即可接入复杂的 AI Chain：

// React 组件调用示例
const response = await fetch('/react-chain', {
  method: 'POST',
  body: JSON.stringify({ query: userInput })
});
const result = await response.json();

部署方式：从 npm 到 WASM 边缘计算

EdgeChains 提供三种部署路径：

方案一：npm 包（推荐入门）

cd JS/edgechains/examples/chat-with-llm
npm install
npm run start   # 启动 Hono 服务

这是最简单的上手方式，适合快速验证和本地开发。Hono 作为底层框架，服务启动极快（冷启动 <10ms）。

方案二：Docker 容器

仓库中包含一个多阶段 Dockerfile，将应用打包为生产镜像：

FROM node:20 as builder
RUN npm install && npm run build

FROM tanjim/wasmjs:latest
COPY --from=builder /app/bin /app
ENTRYPOINT [ "wasmjs-runtime", "/app" ]

需要注意的是，Docker 镜像依赖自定义的 wasmjs-runtime 基础镜像，需要先确保该镜像可用。

方案三：WASM 边缘编译

这是 EdgeChains 最有特色的能力——将 JavaScript 写的 AI 应用编译为 WebAssembly，运行在边缘设备上：

用 Hono 编写 API（仅支持 Hono 3.9.x）
用 esbuild 打包为单文件
用定制的 javy 编译器编译为 WASM
用 EdgeChains 提供的 arakoo 运行时执行

编译后的 WASM 二进制文件体积小、启动快、天然沙箱化，适合部署到 Cloudflare Workers、Fastly Compute@Edge 等边缘计算平台。

技术栈全景

EdgeChains 是一个真正的全栈 TypeScript 库，底层技术选型：

层级	技术选型
HTTP 框架	Hono.js 3.9.x（Cloudflare Workers 兼容）
配置语言	Jsonnet（Google 出品）
AI 集成	OpenAI API、Retell SDK
向量数据库	Supabase（PostgreSQL + pgvector）
文档处理	cheerio、pdf-parse、node-html-parser
ORM	TypeORM
测试	Vitest + Playwright
编译工具	esbuild、TypeScript
WASM 运行时	javy（Rust 实现）、wasmtime

值得注意的是，EdgeChains 的 Rust 部分（JS/wasm/crates/）负责 WASM 编译工具链，使用 Rust 的 wasmtime 作为 WASM 运行时，与 JavaScript 部分形成了一个完整的工具链闭环。

争议与局限

EdgeChains 并非没有争议：

学习曲线陡峭：Jsonnet 本身有一定的学习成本，对没有 Kubernetes 配置管理经验的开发者不太友好。
Hono 版本锁定：WASM 编译目前仅支持 Hono 3.9.x，限制了框架升级的灵活性。
生产成熟度存疑：虽然底层依赖（Hono、Jsonnet）稳定，但 EdgeChains 自身作为相对新的项目，生产环境案例披露较少。
License 限制：采用 AGPL-3.0 许可证，商业使用需要注意合规成本。

行业意义

EdgeChains 代表了 GenAI 应用开发的一个新兴流派——配置优先（Configuration-First）。传统 LangChain 的思路是"用代码表达逻辑"，而 EdgeChains 的思路是"用配置表达逻辑，代码只负责执行"。

这种思路的价值在于：当 Prompt 需要频繁迭代时，配置文件比代码更容易管理、测试和部署。随着大模型能力持续提升（更长的上下文窗口、更好的指令遵循），EdgeChains 这类"轻代码、重配置"的框架可能会越来越受欢迎。

项目增长情况：当前 424 stars、208 forks，活跃在 Discord 社区，整体处于早期但稳定发展阶段。

引言：从"调 API"到"写工厂"——GenAI 应用开发的范式转变

背景：Prompt 工程界的"Kubernetes ConfigMap"

这个选择绝非偶然。Prompt 工程有三个天然的"工程化难题"：

Prompt 膨胀（Prompt Explosion）：REACT、CoT、HygE 等不同的 Prompt 技术，对不同模型（GPT-3.5 vs Llama2）的效果差异巨大，导致 Prompt 数量爆炸式增长。
Prompt 漂移（Prompt Drift）：ChatGPT 的行为会随时间变化（已有研究证实），生产环境的 Prompt 需要持续追踪和版本管理。
Prompt 可测试性：传统框架把 Prompt 封装在类/函数里，测试和迭代极不方便。

EdgeChains 的答案是：让 Prompt 活在代码之外。

核心技术：Jsonnet 驱动的声明式 Chain 编排

EdgeChains 的技术架构可以类比为"给 GenAI 应用装上了配置管理层"。它基于两个成熟的基础设施库构建：

Hono.js（Cloudflare 出品）：轻量级高性能 Web 框架，作为 HTTP 服务层
Jsonnet（Google 出品）：带变量和函数的 JSON 超集，专门用于配置管理

声明式 Prompt 管理

在 EdgeChains 中，一个完整的 AI Chain 只需要两个文件：

// main.jsonnet
local OPENAI_API_KEY = import "secrets.jsonnet".openai_api_key;

{
  chain: {
    steps: [
      { type: "prompt", template: "请总结以下内容：{input}" },
      { type: "llm", provider: "openai", model: "gpt-4", api_key: OPENAI_API_KEY }
    ]
  }
}

所有 Chain 逻辑以 Jsonnet 文件形式存在，具备：

版本控制：直接用 Git 管理，和普通代码无异
差异化（Diffable）：每次改动都能看到具体差异
外部化：可以放在 S3 或远程 API，运行时动态加载
Token 计量：内置 Token 消耗统计，方便成本管控

多模态文档处理

EdgeChains 提供了完整的文档处理链路：

模块	功能
`document-loader`	解析 PDF、网页、Markdown 等多格式文档
`splitter`	智能文本分块，保持语义完整性
`vector-db`	集成 Supabase 向量数据库，支持语义检索
`arakooserver`	内置 Hono HTTP 服务，暴露 REST API
`scraper`	网页内容抓取，构建实时知识库

以 PDF 问答为例（chat-with-pdf 示例），完整流程是：

PDF上传 → cheerio/pdf-parse解析 → 1536维OpenAI Embedding → Supabase向量存储
    ↓
用户提问 → Embedding检索 → 上下文组装 → GPT-4生成回答

函数调用（Function Calling）自动化

// 声明工具
const tools = [
  { name: "get_weather", description: "获取城市天气", params: { city: "string" } },
  { name: "get_time", description: "获取当前时间", params: { timezone: "string" } }
];
// EdgeChains 自动处理 Tool Selection、调用和结果回填

研究型 Agent 框架

React 前端集成

// React 组件调用示例
const response = await fetch('/react-chain', {
  method: 'POST',
  body: JSON.stringify({ query: userInput })
});
const result = await response.json();

部署方式：从 npm 到 WASM 边缘计算

EdgeChains 提供三种部署路径：

方案一：npm 包（推荐入门）

cd JS/edgechains/examples/chat-with-llm
npm install
npm run start   # 启动 Hono 服务

这是最简单的上手方式，适合快速验证和本地开发。Hono 作为底层框架，服务启动极快（冷启动 <10ms）。

方案二：Docker 容器

仓库中包含一个多阶段 Dockerfile，将应用打包为生产镜像：

FROM node:20 as builder
RUN npm install && npm run build

FROM tanjim/wasmjs:latest
COPY --from=builder /app/bin /app
ENTRYPOINT [ "wasmjs-runtime", "/app" ]

需要注意的是，Docker 镜像依赖自定义的 wasmjs-runtime 基础镜像，需要先确保该镜像可用。

方案三：WASM 边缘编译

这是 EdgeChains 最有特色的能力——将 JavaScript 写的 AI 应用编译为 WebAssembly，运行在边缘设备上：

用 Hono 编写 API（仅支持 Hono 3.9.x）
用 esbuild 打包为单文件
用定制的 javy 编译器编译为 WASM
用 EdgeChains 提供的 arakoo 运行时执行

编译后的 WASM 二进制文件体积小、启动快、天然沙箱化，适合部署到 Cloudflare Workers、Fastly Compute@Edge 等边缘计算平台。

技术栈全景

EdgeChains 是一个真正的全栈 TypeScript 库，底层技术选型：

层级	技术选型
HTTP 框架	Hono.js 3.9.x（Cloudflare Workers 兼容）
配置语言	Jsonnet（Google 出品）
AI 集成	OpenAI API、Retell SDK
向量数据库	Supabase（PostgreSQL + pgvector）
文档处理	cheerio、pdf-parse、node-html-parser
ORM	TypeORM
测试	Vitest + Playwright
编译工具	esbuild、TypeScript
WASM 运行时	javy（Rust 实现）、wasmtime

争议与局限

EdgeChains 并非没有争议：

学习曲线陡峭：Jsonnet 本身有一定的学习成本，对没有 Kubernetes 配置管理经验的开发者不太友好。
Hono 版本锁定：WASM 编译目前仅支持 Hono 3.9.x，限制了框架升级的灵活性。
生产成熟度存疑：虽然底层依赖（Hono、Jsonnet）稳定，但 EdgeChains 自身作为相对新的项目，生产环境案例披露较少。
License 限制：采用 AGPL-3.0 许可证，商业使用需要注意合规成本。

行业意义

项目增长情况：当前 424 stars、208 forks，活跃在 Discord 社区，整体处于早期但稳定发展阶段。