From 34bc140195a1c53107b59dc0905aef16f2101935 Mon Sep 17 00:00:00 2001 From: figmar Date: Mon, 10 Aug 2026 21:28:02 +0800 Subject: [PATCH] docs: add Chinese README as default (README.md), keep English as README.en.md --- README.en.md | 269 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 262 +++++++++++++++++++++++++------------------------ 2 files changed, 402 insertions(+), 129 deletions(-) create mode 100644 README.en.md diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..032abf1 --- /dev/null +++ b/README.en.md @@ -0,0 +1,269 @@ +
+ +# Forge + +**The open-source, self-hosted platform for visually building, testing, and shipping AI agents & workflows.** + +Wire agents, tools, knowledge, and logic on a canvas - ground them in your data, connect them to your systems, and deploy to email, an API, an MCP server, or an embeddable web widget. No framework code required. + +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) +[![Python](https://img.shields.io/badge/Python-3.11–3.13-3776AB?logo=python&logoColor=white)](apps/api/pyproject.toml) +[![Node](https://img.shields.io/badge/Node-22%20LTS-339933?logo=nodedotjs&logoColor=white)](apps/web/package.json) +[![FastAPI](https://img.shields.io/badge/FastAPI-009688?logo=fastapi&logoColor=white)](apps/api) +[![Next.js](https://img.shields.io/badge/Next.js-14-000000?logo=nextdotjs&logoColor=white)](apps/web) +[![Built with LangChain v1 + LangGraph v1](https://img.shields.io/badge/Built%20with-LangChain%20v1%20%2B%20LangGraph%20v1-1C3C3C)](https://github.com/langchain-ai/langchain) +[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing) + +
+ +--- + +Forge is built directly on the **MIT-licensed LangChain v1 + LangGraph v1** framework - and **never** depends on `langgraph-api` (Elastic 2.0) or LangSmith (commercial). Everything you orchestrate runs on your own infrastructure; nothing is sent to a third-party orchestration service. + +- **Fully open source (MIT).** No proprietary core, no usage caps, no vendor lock-in. +- **Zero-infra local dev.** Boots on SQLite + embedded Chroma + an in-process scheduler - no Docker, Postgres, or Redis required to start. +- **Production-ready.** Swap to Postgres + pgvector, Redis, and a real secret store with config only - a hardening guard refuses to boot with insecure defaults. +- **Observable by default.** Every run is a span waterfall with tokens, latency, and cost down to fractions of a cent. + +## Table of contents + +- [Features](#features) +- [Architecture](#architecture) +- [Quick start](#quick-start-local-zero-infra) +- [Run with Docker](#run-with-docker-production-shaped) +- [Documentation](#documentation) +- [Tech stack](#tech-stack) +- [Local modifications](#local-modifications) +- [Contributing](#contributing) +- [License](#license) + +## Features + +
+ +
+ +> **[Watch the demo](docs/media/Forge_demo.mp4)** - the in-product **Forge Assistant** builds and runs a workflow end to end. *(If the player doesn't load inline, click the link to play.)* + +### Analytics +
+ +
+ +### Tool Builder with Response Projection + +Register **REST, GraphQL, Code, SQL, MCP, or built-in** tools and test them live against real inputs. A **JMESPath response projection** trims bulky payloads *before* they reach the model - watch the raw → projected **token meter** shrink in real time to control cost. Every outbound call is screened by an **SSRF guard**, with optional retries, rate limits, and caching. Point a tool's endpoint at a **per-environment value** with `{{env.*}}` (from `FORGE_TOOL_VARS`) so the same tool row resolves to your dev / qa / prod host per deploy. The platform **built-ins** (time, calculator, web fetch/search, knowledge search, memory) are auto-provisioned into every project and protected from deletion. Organize tools into **tool sets** - reusable, many-to-many groups that double as folders on the screen, get granted to an agent in one click, and publish as MCP toolsets. + +
+ +
+The Tools screen groups everything by set (switchable between grid and list), with one-click **export / import** to move tools between projects: + +

Forge Tools screen: the tool grid grouped into reusable tool sets, with grid/list views and one-click export and import

+ +### Visual Agent Builder + +Compose an **Agent** or a **Deep Agent** (planning + subagents for long multi-step tasks) from a model, a system prompt, tools, knowledge, Q&A, and a reorderable **middleware stack** - all from friendly forms, no JSON. A live *"what the model sees"* panel shows the exact compiled prompt and middleware execution order before you ship. Build a **supervisor** visually: drag from a Deep Agent's **subagents** handle to any specialist agent node and it folds in as a callable sub-agent (an org-chart branch on the canvas) - each with its own model, tools, and prompt, dispatched via the `task` tool and shown as named sub-agent spans in the trace. + +
+ +
+ +### Visual Workflow Builder + +Wire an entire app on a **drag-and-drop canvas** (React Flow): drop nodes from the palette - **agents** & deep agents, model calls, classifiers, tools, transforms, retrieval, human input/handoff, routers, loops, parallel fan-out/join, subworkflows, and triggers - and connect them with **typed, validated** edges. A per-node inspector and a live **state schema** keep runs type-safe, while a minimap, undo/redo, and copy/paste keep big graphs manageable. **Save**, **Test**, or open the **Playground** to watch nodes light up as the run streams - then **Publish**. +
+ +
+

Forge visual workflow builder: a React Flow canvas wiring retrieval, router, agent, and end nodes, with a node palette, a state-schema inspector, and a minimap

+ +### Knowledge & RAG + +Ground agents in **your own data**. Add pasted text, URLs, crawled sites, or uploaded files (`.txt/.md/.csv/.json/.html/.pdf`); Forge chunks, embeds (**offline-capable by default**), and stores them as vectors organized in folders. Curated **Q&A pairs** deflect common questions, and a **search debugger** lets you inspect exactly what retrieval returns. + +

Forge knowledge screen showing document sources, folders, chunking status, and Q&A

+ +The built-in **search debugger** plots every chunk by semantic similarity and overlays a query - so you can see exactly which chunks a search retrieves, and why: + +

Forge knowledge search debugger: a PCA chunk map colored by source, with a query overlay marking the retrieved chunks

+ +### Generative UI Components + +Let agents render **rich, interactive UI** - tables, cards, forms - instead of plain text. Author an HTML/CSS component once with a live preview; the model emits a tiny payload while the markup renders in a **sandboxed iframe** and never bloats the token stream. Buttons can send structured actions straight back to the agent. + +

Forge component builder with HTML/CSS editor and a live sandboxed preview of a weather card

+ +### Embeddable Web Widget + +Drop your assistant onto **any website** with a one-line script - a floating chat bubble locked to the origins you allow. End users see only the conversation; operational details (steps, tokens, cost, node names) stay private in the dashboard. + +

Forge embed screen with widget toggle, allowed origins, and a copy-paste launcher snippet

+ +### Deploy anywhere - one run API, MCP & channels + +Ship the same workflow through many surfaces without rewriting it: call it server-to-server over a **single run API** (`POST /run` handles new turns, streaming, and human-in-the-loop resumes), expose it as an **MCP server**, deploy it to **email**, or drop in the **web widget**. Per-request caller context (`X-Forge-Context`) lets tools act on behalf of your end users - with secrets never in the request body. + +

Forge Connect screen showing the run API: the Forge API base URL, the POST /run endpoint, and a copy-paste curl example

+ +> [!NOTE] +> **Connectors are not yet fully implemented.** The prebuilt, one-click **connector library / marketplace** (Google, Slack, Notion, GitHub, Salesforce, …) is on the [roadmap](docs/ROADMAP.md#planned--exploring) — it is **not shipped yet**. Today you integrate an external system by hand: create a **REST / GraphQL / MCP tool** and pair it with an **Auth Provider** (Bearer / API key / Basic / OAuth2 / CSRF-session). *(Note: the `connector` **role** — a least-privileged MCP-only user — is a separate, shipped feature and unrelated to the connector library.)* + +### Observability & Traces + +Every run is captured as a **collapsible span tree** - model calls, tools, chains, sub-agents, latency, tokens, and **cost**, nested by real parent/child so you can see exactly what happened and what it cost. Deep-agent dispatches appear as named `subagent · ` spans, and the Playground streams a **live agent-activity** timeline (which sub-agent/tool ran, as it happens). Pair it with **Evaluations** to catch regressions before you publish, and export traces to any **OpenTelemetry** collector (e.g. Langfuse). + +

Forge traces screen showing a run's span waterfall with per-step latency, tokens, and cost

+ +### Guardrails, budgets & governance + +Run it like production. A project-level **Guardrails & Egress** policy (PII redaction, blocked terms, and a network allow/deny list) applies to every agent by default; **budgets & quotas** cap spend and tokens; **versioning** snapshots every change; and it all sits behind per-project **roles / RBAC** and an audit log - from one Settings surface. + +

Forge project Settings with a section sidebar: General, Members and Roles, API Keys, Model Pricing, Budgets and Quotas, Guardrails and Egress, Versioning, and more

+ +### And many more + +- **Channels** - deploy a workflow to **Email**. +- **Triggers** - webhooks, schedules (interval/cron), inbound email, and polling "app events". +- **Human-in-the-loop** - approve/reject pauses and live **handoff** to an Agent inbox, with the reply delivered back over the same channel. +- **Auth Providers** - Bearer, API key, Basic, OAuth2 (client-credentials **and** 3-legged user login with auto-refresh), and CSRF/session - backed by encrypted, reference-only secrets (`secret://…`). +- **MCP, both ways** - expose your tools as an **MCP server** over native Streamable-HTTP/SSE (Claude Desktop, Cursor, and VS Code connect directly - no bridge), authenticated by a project key, per-user **personal access tokens**, or optional **OAuth 2.1**, publishing tool sets, knowledge, Q&A, or a whole workflow; and consume tools from external MCP servers. +- **Guardrails & egress policy** - one project-level I/O policy (PII redaction, blocked terms, and a network allow/deny list) enforced on every agent by default; a project can only *tighten* it, never loosen it. +- **Import & export** - move tools, workflows, agents, and components between projects as portable JSON bundles (secret *values* never leave). +- **Evaluations** - datasets scored by `contains` / `exact` / `regex` / LLM-`judge` for a pass rate per workflow, **streamed live** (each case resolves in the UI as it finishes, with per-case latency + tokens). +- **Long-term memory**, response caching, retries with backoff, and per-tenant **budgets**. +- **Multi-tenant projects & roles** (owner/admin/editor/viewer/connector) with **per-project RBAC**, scoped revocable API keys, entity **version history**, and an **audit log**. +- **Provider-agnostic models** - OpenAI, Anthropic, Google, or any LangChain provider, plus an offline `fake:` model so you can build the plumbing without spending a cent. + +> See the full **[User Manual](docs/MANUAL.md)** for an end-to-end tour and worked examples. + +## Architecture + +A pnpm + Python monorepo with a shared schema contract that keeps the backend and frontend in lockstep: + +``` +forge/ +├── apps/ +│ ├── api/ FastAPI backend - the engine (compiler, registry, middleware), tools, +│ │ auth, knowledge, tracing, MCP server, build assistant. Dockerfile + +│ │ Alembic migrations live here. [Python] +│ └── web/ Next.js console - canvas, config panels, playground, traces. Dockerfile +│ lives here. [TS/React] +├── packages/ +│ └── schemas/ Shared JSON Schemas - the single source of truth, imported by the +│ backend validator/compiler AND the frontend . +├── docs/ User manual, roadmap, and media. +├── infra/ Production database swaps (Postgres row-level-security policies). +└── docker-compose.yml Production-shaped stack (Postgres · Redis · api · worker · web). +``` + +The **shared schemas** are the contract behind three consumers: the backend **validator** (rejects bad configs on save), the **compiler** (`compile_workflow`, `build_middleware`), and the frontend **``** (forms generated from the same files). + +## Quick start (local, zero-infra) + +### Prerequisites + +- **Python** 3.11–3.13 - the backend engine +- **Node** 22 LTS and **pnpm** 9+ - the web console +- Nothing else - the local stack runs on SQLite + embedded Chroma + an in-process scheduler, so **no Docker, Postgres, or Redis** is required to start. + +### 1. Configure environment + +```bash +cp .env.example .env # macOS/Linux +copy .env.example .env # Windows +``` + +Open `.env` and fill in what you need (e.g. an LLM provider key). Everything is optional to boot; agents that call a model need a provider key. **Never commit your `.env`** - it is already git-ignored. + +### 2. Backend (FastAPI engine) + +```bash +cd apps/api +python -m venv .venv && source .venv/bin/activate # .venv\Scripts\activate on Windows +pip install -e ".[dev,all]" # engine + tests + vectors/providers/knowledge/MCP +pytest # optional: validate the engine (offline) +uvicorn forge.main:app --reload --port 8000 # http://localhost:8000/docs +``` + +### 3. Frontend (Next.js console) + +In a second terminal, from the repo root: + +```bash +pnpm install +pnpm --filter web dev # http://localhost:3000 +``` + +Open **http://localhost:3000** for the console and **http://localhost:8000/docs** for the API. On first run, sign in with `you@forge.local` / `forge-admin`, or create a fresh workspace. + +## Run with Docker (production-shaped) + +The included [`docker-compose.yml`](docker-compose.yml) brings up a production-shaped stack - **Postgres** (app DB + durable checkpointer), **Redis** (shared rate-limit/idempotency + worker queue), the **API**, a **worker**, and the **web** console: + +```bash +# Set real secrets first (FORGE_JWT_SECRET, FORGE_BOOTSTRAP_ADMIN_PASSWORD, provider keys) +docker compose up --build +``` + +With `FORGE_ENVIRONMENT=production`, Forge enables a hardening guard and **refuses to boot** with default secrets, SQLite, or a non-durable checkpointer. See [`apps/api/README.md`](apps/api/README.md) and **[Manual §13 - Going to production](docs/MANUAL.md)** for the full, annotated configuration. + +## Documentation + +| Doc | What's inside | +|---|---| +| **[User Manual](docs/MANUAL.md)** | Full feature tour, the node catalog, and end-to-end use cases (no developer knowledge needed). | +| **[Backend README](apps/api/README.md)** | API layout, local-vs-production swaps, and dependency notes. | +| **[Tech stack & architecture](TECH_STACK.md)** | Every dependency and why it's there, plus request/run sequence diagrams. | +| **[Roadmap & status](docs/ROADMAP.md)** | What's shipped, what's in progress, and what's planned next (connectors, more channels, and more). | +| **[Changelog](CHANGELOG.md)** | Notable changes, following Keep a Changelog + SemVer. | +| **[Contributing](CONTRIBUTING.md)** | Local setup, the checks CI runs, and commit/PR conventions. | + +## Tech stack + +| Layer | Technology | +|---|---| +| **Engine** | LangChain v1 · LangGraph v1 · Deep Agents - MIT framework only | +| **Backend** | Python · FastAPI · SQLAlchemy 2 (async) · Pydantic v2 | +| **Frontend** | Next.js 14 (App Router) · React 18 · TypeScript · React Flow | +| **Data (local)** | SQLite · embedded Chroma · in-process cache/scheduler | +| **Data (prod)** | Postgres 16 + pgvector · Redis 7 · Fernet/Vault secrets | +| **Observability** | Built-in tracer + cost accounting · OpenTelemetry / Langfuse export | + +## Local modifications + +This repository is a **fork with local customizations** of the upstream [Forge](https://github.com/nihalashetty/Forge) project. It is hosted by the **Gitinbox** organization for internal AI-agent platform use. + +### Changes vs upstream ([`nihalashetty/Forge`](https://github.com/nihalashetty/Forge/tree/main)) + +| Area | Upstream | This fork | +|---|---|---| +| **Model catalog** (`apps/api/forge/model_catalog.py`) | OpenAI / Anthropic / Google / local fake models only | **Added DeepSeek** `deepseek-chat` (128k, $0.28/$0.42) and `deepseek-reasoner` (128k, $0.55/$2.19), registered as OpenAI-compatible endpoints | +| **DeepSeek runtime** | N/A | Base URL is injected at runtime via `OPENAI_BASE_URL` env (no engine change, `resolve_model` works end-to-end) | + +All other engine, frontend, and packaging code is identical to upstream. To stay in sync with upstream: + +```bash +git remote add upstream https://github.com/nihalashetty/Forge.git # once +git fetch upstream && git merge upstream/main +``` + +**Upstream repository:** + +## Contributing + +Contributions are welcome. Forge is MIT-licensed and built to be extended. + +1. Fork the repo and create a feature branch. +2. Backend changes: run `pytest` and `ruff check forge migrations` from `apps/api`. +3. Keep the **shared schemas** (`packages/schemas`) authoritative - the validator, compiler, and frontend forms all read from them. +4. Open a pull request describing the change and the reasoning. + +Found a bug or have an idea? Please [open an issue](https://github.com/nihalashetty/Forge/issues). + +## License + +Forge is released under the **[MIT License](LICENSE)** - free to use, modify, and distribute, including commercially. It builds only on the MIT-licensed LangChain/LangGraph ecosystem, with no Elastic-2.0 or commercial-license dependencies. + +
+Built on the open-source LangChain and LangGraph ecosystem. +
diff --git a/README.md b/README.md index 032abf1..ffa312e 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ # Forge -**The open-source, self-hosted platform for visually building, testing, and shipping AI agents & workflows.** +**开源、自托管的一站式平台：可视化构建、测试并交付 AI Agent 与工作流。** -Wire agents, tools, knowledge, and logic on a canvas - ground them in your data, connect them to your systems, and deploy to email, an API, an MCP server, or an embeddable web widget. No framework code required. +在画布上把 Agent、工具、知识与逻辑串联起来 —— 接入你的数据、连接你的系统，并一键部署到邮件、API、MCP 服务器或可嵌入的网页组件。无需编写框架代码。 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Python](https://img.shields.io/badge/Python-3.11–3.13-3776AB?logo=python&logoColor=white)](apps/api/pyproject.toml) @@ -18,252 +18,256 @@ Wire agents, tools, knowledge, and logic on a canvas - ground them in your data, --- -Forge is built directly on the **MIT-licensed LangChain v1 + LangGraph v1** framework - and **never** depends on `langgraph-api` (Elastic 2.0) or LangSmith (commercial). Everything you orchestrate runs on your own infrastructure; nothing is sent to a third-party orchestration service. +Forge 直接构建于 **MIT 许可的 LangChain v1 + LangGraph v1** 框架之上 —— **绝不**依赖 `langgraph-api`（Elastic 2.0）或 LangSmith（商业版）。你编排的一切都在自己的基础设施上运行，不会向任何第三方编排服务发送数据。 -- **Fully open source (MIT).** No proprietary core, no usage caps, no vendor lock-in. -- **Zero-infra local dev.** Boots on SQLite + embedded Chroma + an in-process scheduler - no Docker, Postgres, or Redis required to start. -- **Production-ready.** Swap to Postgres + pgvector, Redis, and a real secret store with config only - a hardening guard refuses to boot with insecure defaults. -- **Observable by default.** Every run is a span waterfall with tokens, latency, and cost down to fractions of a cent. +- **完全开源（MIT）。** 无专有内核、无用量上限、无厂商锁定。 +- **零基础设施本地开发。** 基于 SQLite + 内嵌 Chroma + 进程内调度器启动 —— 无需 Docker、Postgres 或 Redis。 +- **生产就绪。** 仅通过配置即可切换 Postgres + pgvector、Redis 与真实密钥存储；加固守卫在检测到不安全默认配置时会拒绝启动。 +- **默认可观测。** 每次运行都是一条 span 瀑布图，展示 token、延迟与成本（精确到美分）。 -## Table of contents +## 目录 -- [Features](#features) -- [Architecture](#architecture) -- [Quick start](#quick-start-local-zero-infra) -- [Run with Docker](#run-with-docker-production-shaped) -- [Documentation](#documentation) -- [Tech stack](#tech-stack) -- [Local modifications](#local-modifications) -- [Contributing](#contributing) -- [License](#license) +- [功能特性](#功能特性) +- [架构](#架构) +- [快速开始（本地、零基础设施）](#快速开始本地零基础设施) +- [使用 Docker 运行（生产形态）](#使用-docker-运行生产形态) +- [文档](#文档) +- [技术栈](#技术栈) +- [本地修改（与原仓库对比）](#本地修改与原仓库对比) +- [参与贡献](#参与贡献) +- [许可证](#许可证) -## Features +## 功能特性
-> **[Watch the demo](docs/media/Forge_demo.mp4)** - the in-product **Forge Assistant** builds and runs a workflow end to end. *(If the player doesn't load inline, click the link to play.)* +> **[观看演示](docs/media/Forge_demo.mp4)** —— 产品内置的 **Forge Assistant** 端到端构建并运行一个工作流。*(如果播放器未内联加载，请点击链接播放。)* + +### 数据分析 -### Analytics
-### Tool Builder with Response Projection +### 工具构建器与响应投影 -Register **REST, GraphQL, Code, SQL, MCP, or built-in** tools and test them live against real inputs. A **JMESPath response projection** trims bulky payloads *before* they reach the model - watch the raw → projected **token meter** shrink in real time to control cost. Every outbound call is screened by an **SSRF guard**, with optional retries, rate limits, and caching. Point a tool's endpoint at a **per-environment value** with `{{env.*}}` (from `FORGE_TOOL_VARS`) so the same tool row resolves to your dev / qa / prod host per deploy. The platform **built-ins** (time, calculator, web fetch/search, knowledge search, memory) are auto-provisioned into every project and protected from deletion. Organize tools into **tool sets** - reusable, many-to-many groups that double as folders on the screen, get granted to an agent in one click, and publish as MCP toolsets. +注册 **REST、GraphQL、Code、SQL、MCP 或内置** 工具，并针对真实输入进行在线测试。**JMESPath 响应投影** 在数据到达模型*之前*裁剪冗余负载 —— 实时观察原始 → 投影后的 **token 计量表** 收缩，以控制成本。每次出站调用都经过 **SSRF 防护** 筛查，并支持可选的重试、限流与缓存。通过 `{{env.*}}`（来自 `FORGE_TOOL_VARS`）将工具端点指向**按环境取值**的地址，同一工具行即可按部署解析到 dev / qa / prod 主机。平台**内置工具**（时间、计算器、网页抓取/搜索、知识检索、记忆）自动配置到每个项目并受保护不可删除。工具可组织成**工具集** —— 可复用、多对多的分组，在画布上充当文件夹，一键授权给 Agent，并可发布为 MCP 工具集。
-The Tools screen groups everything by set (switchable between grid and list), with one-click **export / import** to move tools between projects: +工具页面按集合分组显示（可在网格与列表之间切换），并支持一键**导出 / 导入**，在不同项目间迁移工具： -

Forge Tools screen: the tool grid grouped into reusable tool sets, with grid/list views and one-click export and import

+

Forge 工具页面：按可复用工具集分组的工具网格，支持网格/列表视图与一键导出导入

-### Visual Agent Builder +### 可视化 Agent 构建器 -Compose an **Agent** or a **Deep Agent** (planning + subagents for long multi-step tasks) from a model, a system prompt, tools, knowledge, Q&A, and a reorderable **middleware stack** - all from friendly forms, no JSON. A live *"what the model sees"* panel shows the exact compiled prompt and middleware execution order before you ship. Build a **supervisor** visually: drag from a Deep Agent's **subagents** handle to any specialist agent node and it folds in as a callable sub-agent (an org-chart branch on the canvas) - each with its own model, tools, and prompt, dispatched via the `task` tool and shown as named sub-agent spans in the trace. +通过模型、系统提示词、工具、知识、问答以及可排序的**中间件栈**，以友好的表单（无需 JSON）组合出 **Agent** 或 **Deep Agent**（面向长多步任务的规划 + 子 Agent）。实时的 *"模型所见"* 面板会在发布前展示编译后的提示词与中间件执行顺序。可视化构建 **supervisor**：从 Deep Agent 的 **subagents** 手柄拖拽到任意专家 Agent 节点，即可将其折叠为可调用的子 Agent（画布上的组织架构分支）—— 每个子 Agent 拥有自己的模型、工具与提示词，通过 `task` 工具调度，并在 trace 中显示为具名子 Agent span。
-### Visual Workflow Builder +### 可视化工作流构建器 + +在**拖拽画布**（React Flow）上串联整个应用：从面板拖入节点 —— **Agent** 与深度 Agent、模型调用、分类器、工具、变换、检索、人工输入/交接、路由器、循环、并行扇出/汇合、子工作流与触发器 —— 并用**类型化、经过校验**的连线连接。节点级检查器与实时**状态模式**保证运行类型安全，小地图、撤销/重做与复制/粘贴让大型图保持可控。**保存**、**测试**或打开 **Playground** 观看节点在流式运行中点亮 —— 然后**发布**。 -Wire an entire app on a **drag-and-drop canvas** (React Flow): drop nodes from the palette - **agents** & deep agents, model calls, classifiers, tools, transforms, retrieval, human input/handoff, routers, loops, parallel fan-out/join, subworkflows, and triggers - and connect them with **typed, validated** edges. A per-node inspector and a live **state schema** keep runs type-safe, while a minimap, undo/redo, and copy/paste keep big graphs manageable. **Save**, **Test**, or open the **Playground** to watch nodes light up as the run streams - then **Publish**.
-

Forge visual workflow builder: a React Flow canvas wiring retrieval, router, agent, and end nodes, with a node palette, a state-schema inspector, and a minimap

+

Forge 可视化工作流构建器：React Flow 画布串联检索、路由器、Agent 与结束节点，含节点面板、状态模式检查器与小地图

-### Knowledge & RAG +### 知识与 RAG -Ground agents in **your own data**. Add pasted text, URLs, crawled sites, or uploaded files (`.txt/.md/.csv/.json/.html/.pdf`); Forge chunks, embeds (**offline-capable by default**), and stores them as vectors organized in folders. Curated **Q&A pairs** deflect common questions, and a **search debugger** lets you inspect exactly what retrieval returns. +让 Agent 基于**你自己的数据**。添加粘贴文本、URL、爬取站点或上传文件（`.txt/.md/.csv/.json/.html/.pdf`）；Forge 负责分块、嵌入（**默认支持离线**）并按文件夹组织为向量存储。精选的**问答对**可拦截常见问题，**检索调试器**让你精确检查检索返回的内容。 -

Forge knowledge screen showing document sources, folders, chunking status, and Q&A

+

Forge 知识页面：文档来源、文件夹、分块状态与问答

-The built-in **search debugger** plots every chunk by semantic similarity and overlays a query - so you can see exactly which chunks a search retrieves, and why: +内置的**检索调试器**按语义相似度绘制每个分块并叠加查询 —— 让你清楚看到检索命中了哪些分块、以及为什么命中： -

Forge knowledge search debugger: a PCA chunk map colored by source, with a query overlay marking the retrieved chunks

+

Forge 知识检索调试器：按来源着色的 PCA 分块图，叠加查询标记检索命中的分块

-### Generative UI Components +### 生成式 UI 组件 -Let agents render **rich, interactive UI** - tables, cards, forms - instead of plain text. Author an HTML/CSS component once with a live preview; the model emits a tiny payload while the markup renders in a **sandboxed iframe** and never bloats the token stream. Buttons can send structured actions straight back to the agent. +让 Agent 渲染**丰富的交互式 UI** —— 表格、卡片、表单，而不仅是纯文本。用实时预览一次性编写 HTML/CSS 组件；模型只输出微小的载荷，标记在**沙箱 iframe** 中渲染，绝不膨胀 token 流。按钮可将结构化动作直接回传给 Agent。 -

Forge component builder with HTML/CSS editor and a live sandboxed preview of a weather card

+

Forge 组件构建器：HTML/CSS 编辑器与天气卡片实时沙箱预览

-### Embeddable Web Widget +### 可嵌入网页组件 -Drop your assistant onto **any website** with a one-line script - a floating chat bubble locked to the origins you allow. End users see only the conversation; operational details (steps, tokens, cost, node names) stay private in the dashboard. +通过一行脚本将你的助手嵌入**任何网站** —— 一个锁定你允许来源的悬浮聊天气泡。终端用户只看到对话；操作细节（步骤、token、成本、节点名）保留在仪表盘中，不外泄。 -

Forge embed screen with widget toggle, allowed origins, and a copy-paste launcher snippet

+

Forge 嵌入页面：组件开关、允许来源与可复制粘贴的启动脚本

-### Deploy anywhere - one run API, MCP & channels +### 随处部署 —— 单一 run API、MCP 与通道 -Ship the same workflow through many surfaces without rewriting it: call it server-to-server over a **single run API** (`POST /run` handles new turns, streaming, and human-in-the-loop resumes), expose it as an **MCP server**, deploy it to **email**, or drop in the **web widget**. Per-request caller context (`X-Forge-Context`) lets tools act on behalf of your end users - with secrets never in the request body. +无需重写即可通过多种表面交付同一工作流：通过**单一 run API**（`POST /run` 处理新轮次、流式与人工介入恢复）进行服务器到服务器调用，将其暴露为 **MCP 服务器**，部署到**邮件**，或嵌入**网页组件**。按请求的调用方上下文（`X-Forge-Context`）让工具代表终端用户行事 —— 密钥绝不进入请求体。 -

Forge Connect screen showing the run API: the Forge API base URL, the POST /run endpoint, and a copy-paste curl example

+

Forge Connect 页面：run API —— Forge API 基础 URL、POST /run 端点与可复制的 curl 示例

> [!NOTE] -> **Connectors are not yet fully implemented.** The prebuilt, one-click **connector library / marketplace** (Google, Slack, Notion, GitHub, Salesforce, …) is on the [roadmap](docs/ROADMAP.md#planned--exploring) — it is **not shipped yet**. Today you integrate an external system by hand: create a **REST / GraphQL / MCP tool** and pair it with an **Auth Provider** (Bearer / API key / Basic / OAuth2 / CSRF-session). *(Note: the `connector` **role** — a least-privileged MCP-only user — is a separate, shipped feature and unrelated to the connector library.)* +> **连接器尚未完整实现。** 预置的一键**连接器库 / 市场**（Google、Slack、Notion、GitHub、Salesforce 等）已列入[路线图](docs/ROADMAP.md#planned--exploring) —— **尚未发布**。目前集成外部系统需手工完成：创建 **REST / GraphQL / MCP 工具**并与 **Auth Provider**（Bearer / API key / Basic / OAuth2 / CSRF-session）配对使用。*(注意：`connector` **角色** —— 一种最小权限、仅 MCP 的用户 —— 是独立且已发布的功能，与连接器库无关。)* -### Observability & Traces +### 可观测性与追踪 -Every run is captured as a **collapsible span tree** - model calls, tools, chains, sub-agents, latency, tokens, and **cost**, nested by real parent/child so you can see exactly what happened and what it cost. Deep-agent dispatches appear as named `subagent · ` spans, and the Playground streams a **live agent-activity** timeline (which sub-agent/tool ran, as it happens). Pair it with **Evaluations** to catch regressions before you publish, and export traces to any **OpenTelemetry** collector (e.g. Langfuse). +每次运行都捕获为**可折叠的 span 树** —— 模型调用、工具、链、子 Agent、延迟、token 与**成本**，按真实父子关系嵌套，让你精确看到发生了什么、花了多少钱。Deep Agent 派发显示为具名的 `subagent · ` span，Playground 实时流式呈现**Agent 活动时间线**（哪个子 Agent/工具在运行）。可配合 **评估** 在发布前捕获回归，并将 trace 导出到任意 **OpenTelemetry** 收集器（如 Langfuse）。 -

Forge traces screen showing a run's span waterfall with per-step latency, tokens, and cost

+

Forge 追踪页面：一次运行的 span 瀑布图，含每步延迟、token 与成本

-### Guardrails, budgets & governance +### 护栏、预算与治理 -Run it like production. A project-level **Guardrails & Egress** policy (PII redaction, blocked terms, and a network allow/deny list) applies to every agent by default; **budgets & quotas** cap spend and tokens; **versioning** snapshots every change; and it all sits behind per-project **roles / RBAC** and an audit log - from one Settings surface. +像生产环境一样运行。项目级**护栏与出站策略**（PII 脱敏、屏蔽词、网络允许/拒绝列表）默认应用于每个 Agent；**预算与配额**封顶支出与 token；**版本管理**为每次变更快照；全部位于按项目的**角色 / RBAC** 与审计日志之后 —— 集中于一个 Settings 页面。 -

Forge project Settings with a section sidebar: General, Members and Roles, API Keys, Model Pricing, Budgets and Quotas, Guardrails and Egress, Versioning, and more

+

Forge 项目设置：General、Members and Roles、API Keys、Model Pricing、Budgets and Quotas、Guardrails and Egress、Versioning 等分区侧栏

-### And many more +### 更多功能 -- **Channels** - deploy a workflow to **Email**. -- **Triggers** - webhooks, schedules (interval/cron), inbound email, and polling "app events". -- **Human-in-the-loop** - approve/reject pauses and live **handoff** to an Agent inbox, with the reply delivered back over the same channel. -- **Auth Providers** - Bearer, API key, Basic, OAuth2 (client-credentials **and** 3-legged user login with auto-refresh), and CSRF/session - backed by encrypted, reference-only secrets (`secret://…`). -- **MCP, both ways** - expose your tools as an **MCP server** over native Streamable-HTTP/SSE (Claude Desktop, Cursor, and VS Code connect directly - no bridge), authenticated by a project key, per-user **personal access tokens**, or optional **OAuth 2.1**, publishing tool sets, knowledge, Q&A, or a whole workflow; and consume tools from external MCP servers. -- **Guardrails & egress policy** - one project-level I/O policy (PII redaction, blocked terms, and a network allow/deny list) enforced on every agent by default; a project can only *tighten* it, never loosen it. -- **Import & export** - move tools, workflows, agents, and components between projects as portable JSON bundles (secret *values* never leave). -- **Evaluations** - datasets scored by `contains` / `exact` / `regex` / LLM-`judge` for a pass rate per workflow, **streamed live** (each case resolves in the UI as it finishes, with per-case latency + tokens). -- **Long-term memory**, response caching, retries with backoff, and per-tenant **budgets**. -- **Multi-tenant projects & roles** (owner/admin/editor/viewer/connector) with **per-project RBAC**, scoped revocable API keys, entity **version history**, and an **audit log**. -- **Provider-agnostic models** - OpenAI, Anthropic, Google, or any LangChain provider, plus an offline `fake:` model so you can build the plumbing without spending a cent. +- **通道** —— 将工作流部署到**邮件**。 +- **触发器** —— Webhook、定时（interval/cron）、入站邮件与轮询"应用事件"。 +- **人工介入** —— 批准/拒绝暂停与到 Agent 收件箱的实时**交接**，回复经同一通道返回。 +- **Auth Providers** —— Bearer、API key、Basic、OAuth2（客户端凭证**与**三方用户登录并自动刷新）与 CSRF/session —— 由加密的、仅引用式密钥（`secret://…`）支撑。 +- **双向 MCP** —— 将你的工具暴露为原生 Streamable-HTTP/SSE 的 **MCP 服务器**（Claude Desktop、Cursor、VS Code 直接连接 —— 无需桥接），支持项目密钥、按用户**个人访问令牌**或可选 **OAuth 2.1** 认证，发布工具集、知识、问答或整个工作流；同时可消费外部 MCP 服务器的工具。 +- **护栏与出站策略** —— 一个项目级 I/O 策略（PII 脱敏、屏蔽词、网络允许/拒绝列表）默认对每个 Agent 强制执行；项目只能*收紧*，不能放松。 +- **导入与导出** —— 以可移植 JSON 包在项目间迁移工具、工作流、Agent 与组件（密钥*值*永不离库）。 +- **评估** —— 由 `contains` / `exact` / `regex` / LLM-`judge` 打分的数据集，按工作流给出通过率，**实时流式**呈现（每个用例完成后立即在 UI 中解析，含单例延迟 + token）。 +- **长期记忆**、响应缓存、带退避的重试与按租户**预算**。 +- **多租户项目与角色**（owner/admin/editor/viewer/connector），含**按项目 RBAC**、可撤销的限定作用域 API 密钥、实体**版本历史**与**审计日志**。 +- **模型无关** —— OpenAI、Anthropic、Google 或任意 LangChain provider，外加离线 `fake:` 模型，让你不花一分钱也能搭好管道。 -> See the full **[User Manual](docs/MANUAL.md)** for an end-to-end tour and worked examples. +> 完整功能详见 **[用户手册](docs/MANUAL.md)** 的端到端导览与实战示例。 -## Architecture +## 架构 -A pnpm + Python monorepo with a shared schema contract that keeps the backend and frontend in lockstep: +一个 pnpm + Python 单体仓库，通过共享模式契约让前后端保持同步： ``` forge/ ├── apps/ -│ ├── api/ FastAPI backend - the engine (compiler, registry, middleware), tools, -│ │ auth, knowledge, tracing, MCP server, build assistant. Dockerfile + -│ │ Alembic migrations live here. [Python] -│ └── web/ Next.js console - canvas, config panels, playground, traces. Dockerfile -│ lives here. [TS/React] +│ ├── api/ FastAPI 后端 —— 引擎（编译器、注册中心、中间件）、工具、 +│ │ 认证、知识、追踪、MCP 服务器、构建助手。Dockerfile 与 +│ │ Alembic 迁移在此。 [Python] +│ └── web/ Next.js 控制台 —— 画布、配置面板、playground、trace。Dockerfile +│ 在此。 [TS/React] ├── packages/ -│ └── schemas/ Shared JSON Schemas - the single source of truth, imported by the -│ backend validator/compiler AND the frontend . -├── docs/ User manual, roadmap, and media. -├── infra/ Production database swaps (Postgres row-level-security policies). -└── docker-compose.yml Production-shaped stack (Postgres · Redis · api · worker · web). +│ └── schemas/ 共享 JSON Schema —— 唯一事实来源，后端校验器/编译器 +│ 与前端 均引用它。 +├── docs/ 用户手册、路线图与媒体。 +├── infra/ 生产数据库切换（Postgres 行级安全策略）。 +└── docker-compose.yml 生产形态栈（Postgres · Redis · api · worker · web）。 ``` -The **shared schemas** are the contract behind three consumers: the backend **validator** (rejects bad configs on save), the **compiler** (`compile_workflow`, `build_middleware`), and the frontend **``** (forms generated from the same files). +**共享模式**是三个消费方的契约：后端**校验器**（保存时拒绝错误配置）、**编译器**（`compile_workflow`、`build_middleware`）与前端 **``**（由同一文件生成表单）。 -## Quick start (local, zero-infra) +## 快速开始（本地、零基础设施） -### Prerequisites +### 前置条件 -- **Python** 3.11–3.13 - the backend engine -- **Node** 22 LTS and **pnpm** 9+ - the web console -- Nothing else - the local stack runs on SQLite + embedded Chroma + an in-process scheduler, so **no Docker, Postgres, or Redis** is required to start. +- **Python** 3.11–3.13 —— 后端引擎 +- **Node** 22 LTS 与 **pnpm** 9+ —— Web 控制台 +- 无需其他 —— 本地栈运行于 SQLite + 内嵌 Chroma + 进程内调度器，**无需 Docker、Postgres 或 Redis** 即可启动。 -### 1. Configure environment +### 1. 配置环境 ```bash cp .env.example .env # macOS/Linux copy .env.example .env # Windows ``` -Open `.env` and fill in what you need (e.g. an LLM provider key). Everything is optional to boot; agents that call a model need a provider key. **Never commit your `.env`** - it is already git-ignored. +打开 `.env` 填入所需内容（如 LLM provider 密钥）。启动时一切均可选；调用模型的 Agent 需要 provider 密钥。**切勿提交你的 `.env`** —— 它已在 git-ignore 中。 -### 2. Backend (FastAPI engine) +### 2. 后端（FastAPI 引擎） ```bash cd apps/api -python -m venv .venv && source .venv/bin/activate # .venv\Scripts\activate on Windows -pip install -e ".[dev,all]" # engine + tests + vectors/providers/knowledge/MCP -pytest # optional: validate the engine (offline) +python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate +pip install -e ".[dev,all]" # 引擎 + 测试 + 向量/提供方/知识/MCP +pytest # 可选：离线校验引擎 uvicorn forge.main:app --reload --port 8000 # http://localhost:8000/docs ``` -### 3. Frontend (Next.js console) +### 3. 前端（Next.js 控制台） -In a second terminal, from the repo root: +在另一个终端中，从仓库根目录： ```bash pnpm install pnpm --filter web dev # http://localhost:3000 ``` -Open **http://localhost:3000** for the console and **http://localhost:8000/docs** for the API. On first run, sign in with `you@forge.local` / `forge-admin`, or create a fresh workspace. +打开 **http://localhost:3000** 使用控制台，**http://localhost:8000/docs** 查看 API。首次运行请使用 `you@forge.local` / `forge-admin` 登录，或创建一个新工作区。 -## Run with Docker (production-shaped) +## 使用 Docker 运行（生产形态） -The included [`docker-compose.yml`](docker-compose.yml) brings up a production-shaped stack - **Postgres** (app DB + durable checkpointer), **Redis** (shared rate-limit/idempotency + worker queue), the **API**, a **worker**, and the **web** console: +仓库内置的 [`docker-compose.yml`](docker-compose.yml) 可拉起生产形态栈 —— **Postgres**（应用数据库 + 持久化 checkpointer）、**Redis**（共享限流/幂等 + 工作队列）、**API**、**worker** 与 **web** 控制台： ```bash -# Set real secrets first (FORGE_JWT_SECRET, FORGE_BOOTSTRAP_ADMIN_PASSWORD, provider keys) +# 先设置真实密钥（FORGE_JWT_SECRET、FORGE_BOOTSTRAP_ADMIN_PASSWORD、provider 密钥） docker compose up --build ``` -With `FORGE_ENVIRONMENT=production`, Forge enables a hardening guard and **refuses to boot** with default secrets, SQLite, or a non-durable checkpointer. See [`apps/api/README.md`](apps/api/README.md) and **[Manual §13 - Going to production](docs/MANUAL.md)** for the full, annotated configuration. +设置 `FORGE_ENVIRONMENT=production` 后，Forge 会启用加固守卫，并在检测到默认密钥、SQLite 或非持久化 checkpointer 时**拒绝启动**。完整配置见 [`apps/api/README.md`](apps/api/README.md) 与 **[手册 §13 - 上线生产](docs/MANUAL.md)**。 -## Documentation +## 文档 -| Doc | What's inside | +| 文档 | 内容 | |---|---| -| **[User Manual](docs/MANUAL.md)** | Full feature tour, the node catalog, and end-to-end use cases (no developer knowledge needed). | -| **[Backend README](apps/api/README.md)** | API layout, local-vs-production swaps, and dependency notes. | -| **[Tech stack & architecture](TECH_STACK.md)** | Every dependency and why it's there, plus request/run sequence diagrams. | -| **[Roadmap & status](docs/ROADMAP.md)** | What's shipped, what's in progress, and what's planned next (connectors, more channels, and more). | -| **[Changelog](CHANGELOG.md)** | Notable changes, following Keep a Changelog + SemVer. | -| **[Contributing](CONTRIBUTING.md)** | Local setup, the checks CI runs, and commit/PR conventions. | +| **[用户手册](docs/MANUAL.md)** | 完整功能导览、节点目录与端到端用例（无需开发知识）。 | +| **[后端 README](apps/api/README.md)** | API 布局、本地与生产切换、依赖说明。 | +| **[技术栈与架构](TECH_STACK.md)** | 每个依赖及其用途，含请求/运行时序图。 | +| **[路线图与状态](docs/ROADMAP.md)** | 已发布、进行中与规划中的内容（连接器、更多通道等）。 | +| **[更新日志](CHANGELOG.md)** | 重要变更，遵循 Keep a Changelog + SemVer。 | +| **[参与贡献](CONTRIBUTING.md)** | 本地搭建、CI 检查与提交/PR 规范。 | -## Tech stack +## 技术栈 -| Layer | Technology | +| 层 | 技术 | |---|---| -| **Engine** | LangChain v1 · LangGraph v1 · Deep Agents - MIT framework only | -| **Backend** | Python · FastAPI · SQLAlchemy 2 (async) · Pydantic v2 | -| **Frontend** | Next.js 14 (App Router) · React 18 · TypeScript · React Flow | -| **Data (local)** | SQLite · embedded Chroma · in-process cache/scheduler | -| **Data (prod)** | Postgres 16 + pgvector · Redis 7 · Fernet/Vault secrets | -| **Observability** | Built-in tracer + cost accounting · OpenTelemetry / Langfuse export | +| **引擎** | LangChain v1 · LangGraph v1 · Deep Agents —— 仅 MIT 框架 | +| **后端** | Python · FastAPI · SQLAlchemy 2 (async) · Pydantic v2 | +| **前端** | Next.js 14 (App Router) · React 18 · TypeScript · React Flow | +| **数据（本地）** | SQLite · 内嵌 Chroma · 进程内缓存/调度器 | +| **数据（生产）** | Postgres 16 + pgvector · Redis 7 · Fernet/Vault 密钥 | +| **可观测性** | 内置 tracer + 成本核算 · OpenTelemetry / Langfuse 导出 | -## Local modifications +## 本地修改（与原仓库对比） -This repository is a **fork with local customizations** of the upstream [Forge](https://github.com/nihalashetty/Forge) project. It is hosted by the **Gitinbox** organization for internal AI-agent platform use. +本仓库是上游 [Forge](https://github.com/nihalashetty/Forge) 的**带本地定制化的分支**，由 **Gitinbox** 组织托管，用于内部 AI Agent 平台使用。 -### Changes vs upstream ([`nihalashetty/Forge`](https://github.com/nihalashetty/Forge/tree/main)) +### 与原仓库的差异（[`nihalashetty/Forge`](https://github.com/nihalashetty/Forge/tree/main)） -| Area | Upstream | This fork | +| 领域 | 原仓库 | 本分支 | |---|---|---| -| **Model catalog** (`apps/api/forge/model_catalog.py`) | OpenAI / Anthropic / Google / local fake models only | **Added DeepSeek** `deepseek-chat` (128k, $0.28/$0.42) and `deepseek-reasoner` (128k, $0.55/$2.19), registered as OpenAI-compatible endpoints | -| **DeepSeek runtime** | N/A | Base URL is injected at runtime via `OPENAI_BASE_URL` env (no engine change, `resolve_model` works end-to-end) | +| **模型目录**（`apps/api/forge/model_catalog.py`） | 仅 OpenAI / Anthropic / Google / 本地 fake 模型 | **新增 DeepSeek** `deepseek-chat`（128k，$0.28/$0.42）与 `deepseek-reasoner`（128k，$0.55/$2.19），注册为 OpenAI 兼容端点 | +| **DeepSeek 运行时** | 无 | 通过 `OPENAI_BASE_URL` 环境变量在运行时注入 Base URL（零引擎改动，`resolve_model` 端到端可用） | -All other engine, frontend, and packaging code is identical to upstream. To stay in sync with upstream: +其余引擎、前端与打包代码均与上游一致。与上游保持同步： ```bash -git remote add upstream https://github.com/nihalashetty/Forge.git # once +git remote add upstream https://github.com/nihalashetty/Forge.git # 仅首次 git fetch upstream && git merge upstream/main ``` -**Upstream repository:** +**上游仓库：** -## Contributing +> 英文版：请查看 [README.en.md](README.en.md) -Contributions are welcome. Forge is MIT-licensed and built to be extended. +## 参与贡献 -1. Fork the repo and create a feature branch. -2. Backend changes: run `pytest` and `ruff check forge migrations` from `apps/api`. -3. Keep the **shared schemas** (`packages/schemas`) authoritative - the validator, compiler, and frontend forms all read from them. -4. Open a pull request describing the change and the reasoning. +欢迎贡献。Forge 基于 MIT 许可，专为扩展而设计。 -Found a bug or have an idea? Please [open an issue](https://github.com/nihalashetty/Forge/issues). +1. Fork 本仓库并创建功能分支。 +2. 后端改动：在 `apps/api` 下运行 `pytest` 与 `ruff check forge migrations`。 +3. 保持**共享模式**（`packages/schemas`）的权威性 —— 校验器、编译器与前端表单都从它读取。 +4. 发起描述改动内容与理由的 Pull Request。 -## License +发现 Bug 或有想法？请[提交 issue](https://github.com/nihalashetty/Forge/issues)。 -Forge is released under the **[MIT License](LICENSE)** - free to use, modify, and distribute, including commercially. It builds only on the MIT-licensed LangChain/LangGraph ecosystem, with no Elastic-2.0 or commercial-license dependencies. +## 许可证 + +Forge 以 **[MIT 许可证](LICENSE)** 发布 —— 可免费使用、修改与分发（含商业用途）。它仅构建于 MIT 许可的 LangChain/LangGraph 生态之上，无 Elastic-2.0 或商业许可证依赖。
-Built on the open-source LangChain and LangGraph ecosystem. +构建于开源的 LangChain 与 LangGraph 生态。