typedai

引言：从 LangChain 泥潭中挣脱的 TypeScript 工程师

当你第一次用 LangChain 构建一个 AI 代理时，是否有过这样的体验——一个简单的"先查天气再决定出门路线"的工作流，代码行数已经膨胀到 200 行，类型检查四处报错，调试全靠 console.log？LangChain 的过度抽象让很多 TypeScript 开发者苦不堪言：类型丢失、版本不兼容、API 改一次整个链都得重构。

TypedAI 正是为解决这个痛点而生。它是 TrafficGuard 公司内部孵化并于 2024 年开源的 TypeScript AI 开发平台，核心理念只有一个：让 TypeScript 原生开发者用自己熟悉的编程范式来构建 AI 应用，而不是被迫学习一套新的 DSL。项目明确不使用 LangChain，README 甚至用对比示例直接点名 LangChain 的设计缺陷，展示了等价的 TypedAI 实现如何用更少的代码和完整的类型安全来实现同样的功能。

开源不到两年，该项目已吸引超过 1100 个 GitHub Star，11 个贡献者持续活跃维护，涵盖 AI 对话、自主代理、代码编辑代理、PR 代码审查代理等完整能力矩阵。

背景：TrafficGuard 为何要做 TypedAI

TrafficGuard 是一家专注于流量安全和反作弊的技术公司，核心业务涉及大规模数据分析和机器学习。随着 LLM 浪潮到来，团队需要将 AI 能力深度嵌入内部工作流——从自动化代码审查到 AI 软件工程师，需求不断涌现。

团队在调研 LangChain 时发现，尽管 LangChain 生态丰富，但其过度封装的设计导致几个核心问题无法接受：

类型系统形同虚设。LangChain 的链（Chain）和提示（Prompt）对象大量依赖运行时反射，TypeScript 编译器无法在编译期捕获参数类型错误，导致生产环境中频繁出现"传错参数但测试通过"的 bug。

调试困难。当一个包含 5 个步骤的代理链出错时，LangChain 只会抛出一个笼统的 RuntimeError，无法定位到具体是哪个步骤的哪个 LLM 调用出了问题。

维护成本高企。LangChain 每次版本更新都会引入 Breaking Change，团队花在升级兼容上的时间甚至超过了写业务逻辑的时间。

因此 TrafficGuard 决定自己造轮子。TypedAI 从第一天起就确立了三个设计原则：TypeScript 优先（全链路类型安全）、可调试优先（每个 LLM 调用可追踪）、不依赖第三方抽象层（直接对接 LLM SDK）。

核心功能：不是另一个 LangChain，而是一个完整 AI 平台

1. 多 LLM 统一接入层

TypedAI 的 LLM 层是整个平台的基础。它直接集成了 @ai-sdk 系列包，实现了对 12+ 主流 LLM 服务的统一封装：

类别	支持服务商
闭源大厂	OpenAI (GPT-4o/o1/o3)、Anthropic (Claude 3.5/3.7)、Google Gemini
开源/自托管	Ollama（本地）、DeepSeek、Cerebras、SambaNova
中间层	Groq、Fireworks、Together.ai、OpenRouter、X.ai
医疗/企业	Google Vertex AI（企业级）

这种设计的精妙之处在于：平台在 src/llm/ 目录下实现了一个统一的 LLM Factory 模式，应用层代码只需声明"我要用 Claude"，无需关心具体的 API 调用、Token 计算、重试策略和错误处理。所有这些都由 TypedAI 的 llmCallService 模块统一管理。

更值得关注的是 src/llm/multi-agent/ 目录下的**扩展推理（Extend-Reasoning）**实现。该模块允许将多个 LLM 实例组合成推理网络，每个 LLM 负责不同的推理维度（如一个负责逻辑验证，一个负责创意发散），通过结构化协商得出最终答案。这一实现参考了 Google 的 Self-Discover 论文（arXiv:2402.03620），在代码中可以直接看到对应的引用。

2. 自主代理（Autonomous Agents）

TypedAI 的自主代理系统是整个平台最复杂的模块，位于 src/autonomous/ 目录。其核心是 autonomousAgentRunner.ts 提供的分层推理引擎：

第一层：任务分解（Task Decomposition）。代理接收用户目标后，先通过 LLM 将其拆解为可执行的任务树。这一步受到 Self-Discover 推理框架的启发，会先生成多个推理路径候选，再通过 LLM 评估选择最优路径。

第二层：沙箱执行（Sandboxed Execution）。代理生成的代码不会直接在宿主机执行，而是通过 Pyodide（浏览器 WebAssembly Python 运行时）或 Docker 沙箱环境执行。这意味着即使代理生成了恶意代码，也无法影响主机系统。

第三层：循环修正（Compile-Fix Loop）。代码编辑代理实现了"编译→报错的错误分析器→在线搜索解决方案→修复→再编译"的自动循环，直到代码编译通过或达到最大迭代次数。错误分析器甚至可以自动安装缺失的 npm 包。

第四层：人工介入（Human-in-the-Loop）。平台支持配置何时需要人工确认：代理遇到预算上限时、代理主动提问时、或发生错误超过阈值时，系统会通过 Web UI 或 Slack 向人工发送确认通知，只有获得批准后才会继续执行。

3. AI 软件工程师代理

TypedAI 提供了三种软件工程代理，覆盖了从"随手改代码"到"完整 ticket-to-PR"的全流程：

**代码编辑代理（Code Editing Agent）**是使用最频繁的代理，专门针对本地代码仓库工作。典型工作流：任务文件选择代理先分析用户需求，从仓库中找出最相关的 N 个文件；设计代理根据这些文件制定实现计划；代码编辑循环执行修改（编译/lint/测试/修复）；最后由审查代理做最终验收。整个过程完全自主，无需人工介入。

**软件工程师代理（Software Engineer Agent）**则更进一步，从 GitHub/GitLab 自动发现对应仓库，克隆并创建新分支，调用代码编辑代理完成任务，最终自动创建 Merge Request/PR。整个 ticket-to-PR 流程自动化，是目前 AI Coding 领域最前沿的探索方向之一。

**代码审查代理（Code Review Agent）**支持可配置的审查指南，能自动分析 MR/PR 的代码变更，在合适的行级别位置留下带建议修复方案的评论，并支持直接提交。这些代理已在 TrafficGuard 内部日常使用，帮助团队在代码合并前就发现潜在问题。

4. AI 对话与聊天

平台内置了完整的 AI 聊天界面（frontend/ Angular 应用），支持：

• 多会话管理
• 上下文历史
• 消息中嵌入代码块、图片和文件引用
• Slack 集成（src/slack/ 模块），允许在 Slack 频道直接与 AI 对话

5. 灵活的工具系统

TypedAI 的工具系统采用装饰器驱动的函数注册机制，与 LangChain 的 Zod Schema 方案形成鲜明对比：

@funcClass(__filename)
export class Jira {
    @func()
    async getJiraDescription(issueId: string): Promise<string> {
        // 实现
    }
}

只需在类方法上加 @func() 装饰器，TypedAI 自动从 TypeScript 类型签名和 JSDoc 注释生成 LLM function calling schema，无需手动维护 Zod schema 定义。这种方式确保了类型安全和文档的一致性——当你修改函数签名时，LLM 的工具描述会自动更新。

目前官方集成的工具覆盖：文件系统操作、Jira、Slack、Perplexity（实时搜索）、Google Cloud、GitLab、GitHub、PostgreSQL 等，基本覆盖了主流的开发协作场景。

6. 可观测性：OpenTelemetry 集成

在 src/fastify/trace-init/ 中，TypedAI 集成了 OpenTelemetry 标准。用户可以将追踪数据发送到 Google Cloud Trace、Jaeger 或任何兼容 OpenTelemetry Collector 的后端。每个 LLM 调用、每个函数执行、每个工具调用都有对应的 span，形成完整的分布式追踪链。README 中甚至展示了在 Google Cloud 上查看追踪数据的截图。

技术架构：从底层依赖看设计哲学

Monorepo 结构

项目采用 pnpm Workspace 的 Monorepo 架构，由以下核心部分组成：

• src/（后端核心）：Agent 逻辑、LLM 抽象、数据库 schema、路由定义
• frontend/（Angular 12+）：Web UI，独立的 pnpm workspace
• shared/：前后端共享的类型定义、API 规范（api-definitions.ts）、路由常量
• bin/：CLI 可执行脚本（ai、aid）
• scripts/：运维脚本（Terraform、Docker 相关）
• test/：端到端测试
• claude-plugins/：Claude Code 集成插件

这种分离确保了类型在前后端之间的严格一致性——Shared 模块中定义的 API schema 同时约束了后端路由和前端 HTTP 调用的类型。

后端技术栈

后端核心选型非常明确：

• Fastify：高性能 Node.js Web 框架，相比 Express 有更好的 TypeScript 支持和更高的吞吐量。TypedAI 在 src/server.ts 中初始化 Fastify 实例，注册了 JWT 认证、CORS、文件上传（multipart）、静态文件服务等插件。
• PostgreSQL：通过 src/agent/agentContextService/schema.sql 管理代理的上下文存储、会话历史和执行状态。使用 agentContextService.ts 提供代理上下文管理能力，支持跨会话记忆持久化。
• esbuild-register：生产环境不使用 tsc 编译，而是通过 esbuild-register 在运行时即时编译 TypeScript。Dockerfile 中的启动命令直接是 node -r esbuild-register src/index.ts，兼顾了开发效率和启动速度。

前端技术栈

前端采用 Angular 12+ 构建，这是一个相对"重"的选择，但带来了显著的结构化优势：强制的模块化（Module/Component/Service 分离）、RxJS 响应式编程、以及 Angular 本身的企业级特性（依赖注入、表单处理、路由守卫）都与平台的多用户、SSO 认证需求高度契合。

UI 框架搭配 Tailwind CSS，状态管理使用 Angular 内置的 RxJS 响应式流。此外还集成了 Transloco（国际化），意味着平台从一开始就是为多语言用户设计的。

数据库设计

agentContextService 模块的 PostgreSQL schema 揭示了平台如何持久化代理状态。核心表包括：AgentExecution（记录每次代理运行）、FunctionCallHistory（每个工具调用）、AgentMessage（消息历史）、Checkpoint（用于从断点恢复长时间运行的代理）。这套设计确保了即使是数小时运行的代理，也能在系统崩溃后从上一个 Checkpoint 恢复。

Python 集成：Pyodide 沙箱

TypedAI 的一个独特设计是通过 Pyodide 在浏览器 WebAssembly 环境中执行 Python 代码。这意味着平台可以在不安装 Python 运行时的情况下，在前端沙箱中运行 Python 脚本（如数据处理、模型推理调用等）。

pythonCodeGenUtils.ts 和 pyodideDeepConversion.ts 两个文件处理 Python 代码生成和 Pyodide 深度对象转换（将 JS 对象映射为 Python 对象）。Docker 沙箱（Dockerfile.sandbox*）系列则提供了服务端更强的隔离执行能力，适用于不可信的代码生成场景。

部署体验：开箱即用的 Docker 方案

TypedAI 提供了可能是同类型项目中最完善的部署方案集：

单机 Docker 开发环境（推荐入门方案）

一行命令即可启动完整环境：

docker compose up --build

docker-compose.yml 定义了三个服务：

• typedai-dev（主服务）：使用 Dockerfile.dev，挂载本地源码目录，修改代码自动生效
• postgres（数据层）：PostgreSQL 16 Alpine，数据持久化到 postgres_data volume
• pgAdmin（可选）：数据库管理界面，用于调试数据库状态

这套方案特别适合开发者在本机快速体验完整功能，包括 Web UI、数据库持久化和代理执行能力。硬件需求仅需 4GB RAM，普通笔记本即可运行。

生产环境 Docker

Dockerfile（生产镜像）采用 Google Cloud SDK 作为基础镜像（适配 GCP 部署），多阶段构建最终产物。生产启动前会自动执行：

• pnpm install --frozen-lockfile（确定性依赖安装）
• npx puppeteer browsers install chrome（浏览器自动化依赖）
• pnpm run initTiktokenizer（下载 tiktoken 分词器模型）

启动命令使用 --max-old-space-size=6144 设置 6GB 堆内存限制，适合处理大规模上下文。

Google Cloud 部署

项目提供了完整的 GCP 部署方案：Scale-to-zero 的 Cloud Run + Cloud SQL（PostgreSQL）+ Cloud IAP（身份感知代理，实现多用户 SSO）。这是 TrafficGuard 自身在生产环境中使用的架构，成熟度较高。

部署难点与注意事项

• 首次构建耗时长：生产镜像需要下载 pnpm 依赖（pnpm-lock.yaml 达 594KB）和 Chromium 浏览器，建议使用 Docker Layer Caching 加速 CI 构建。
• 环境变量配置复杂：生产环境需要配置大量变量（LLM API keys、数据库连接、SSO 配置等），variables/ 目录下有环境变量模板。
• GCP 依赖：如需完整的 SSO 和规模扩展能力，需要 GCP 项目和相应权限配置。

行业意义：TypeScript AI 平台的新范式

TypedAI 的出现代表了 AI 开发框架领域的一个重要趋势：从"语言无关的通用抽象"向"特定语言的深度优化"转变。

LangChain 的教训告诉我们，用 Python 思维设计 TypeScript SDK 是行不通的。TypeScript 社区有大量无法接受"失去类型安全"的开发者，他们需要的是在他们熟悉的 TypeScript 编程范式下使用 LLM，而不是学习一套新的"链式调用"语法。

TypedAI 的成功证明了这一点：它用简单的 async/await 替代了 LangChain 的 Runnable 抽象，用 TypeScript 装饰器替代了 Zod Schema，用 Fastify 替代了 LangChain 的回调式处理器，用 PostgreSQL 直接替代了 LangChain 的内存存储。这一系列"替换"不是简化，而是更贴合 TypeScript 生态原本的设计哲学。

从市场定位看，TypedAI 介于"个人开发者的 AI 工具"和"企业级 AI 平台"之间——它有完整的 Web UI 支持多用户，又有足够的可配置性满足企业需求。随着 AI Coding 工具（如 Claude Code、Cursor）成为主流，能够承接这些 AI 代理工作流的开发平台将变得越来越重要，TypedAI 正是这一方向的早期探索者。

平台在 GitHub 上的增长趋势（创建于 2024 年 4 月，2 年内积累 1100+ Star）和活跃的维护状态（每月多次提交）表明，它已经度过了"概念验证"阶段，正在向成熟工具链演进。TrafficGuard 团队将其开源并持续投入，本身也说明了这套架构已经过内部生产环境的充分验证。