English | 简体中文

Cell

一次构建、随处运行的 TypeScript 应用框架，为开发者与 Coding Agent 共同设计。

快速开始 · 随处部署 · Coding Agent · AI · 示例 · CLI 文档

Cell 是一个 Serverless 优先、组件化、平台无关的 TypeScript 应用框架。你只需编写基于依赖注入的普通类，Cell 负责把它们组装成全栈应用，将后端打包为单个文件，并把同一份代码交付到 Node.js 服务器、容器、单个可执行文件、Cloudflare Workers、AWS Lambda、阿里云函数计算、腾讯云云函数或 Vercel。

Cell 4 基于 Vite 8 重写了工具链，并把 Coding Agent 视为一等用户：每条命令都能输出 JSON，每个错误都带错误码和修复建议，每个项目都自带 AGENTS.md 和 MCP 服务。

为什么选择 Cell


一套代码，所有运行时	构建时选择 preset：`node`、`cli`、`cloudflare`、`fc`、`scf`、`lambda`、`vercel`。业务代码不依赖任何云厂商 SDK，迁移平台无需改写。
单文件产物	后端是一个内联全部依赖的 `index.mjs`；加 `--single` 把前端也嵌进去，加 `--compile` 直接得到可执行文件（Bun、Deno 或 Node.js SEA）。
面向 Agent 的工具链	所有命令支持 `--json`，结构化的 `CellError` 错误码与修复提示，`cell check` 一次检查类型与 DI 装配，文档与依赖版本严格匹配，项目和开发服务器都提供 MCP 工具。
企业级架构	依赖注入与 AOP（`@Component`、`@Autowired`、`@Value`、`@Aspect`）、MVC、RPC、声明式事务、安全认证、JWT 与 OAuth2。
全栈一体	后端 MVC 搭配 React；开发时前后端共用一个端口，前端 HMR，后端热重载。
原生 AI 能力	与厂商无关的对话模型、提示词与流式响应；Agent 与 pi coding agent 会话，工具直接调用你的服务。
零配置	处处有合理默认值，只在需要时通过 `cell.yml`、`cell.config.ts` 或 `CELL_BACKEND__*` 环境变量覆盖。
轻量依赖	工具链几乎只依赖 Vite；云部署器自行完成请求签名，不引入庞大的厂商 SDK。

快速开始

环境要求：Node.js ^20.19.0 || >=22.12.0。

bash

npx @celljs/cli init backend my-app     # 或 fullstack（React 前端 + 后端，经 RPC 调用）
cd my-app
npm install
npx cell dev                            # http://127.0.0.1:3000，保存即热重载

一个完整的后端，只需要一个配置文件和一个类：

yaml

# cell.yml
backend:
  cell:
    greeting: Hello from my-app

typescript

// src/node/home-controller.ts
import { Value } from '@celljs/core';
import { Controller, Get, Text } from '@celljs/mvc/lib/node';

@Controller()
export class HomeController {
    @Value('cell.greeting')
    protected readonly greeting: string;

    @Get()
    @Text()
    home(): string {
        return this.greeting;
    }
}

在进程内测试，无需占用端口：

typescript

import { createTestApp } from '@celljs/cli';

const app = await createTestApp({ root: process.cwd() });
const res = await app.fetch('/');          // 200 "Hello from my-app"
await app.close();

常用命令：

命令	作用
`cell dev`	前后端同一端口；前端 HMR、后端热重载，配置变化自动重启
`cell build`	生产构建到 `.cell/output`（支持 `--single`、`--compile`、`--preset <name>`）
`cell preview`	按目标平台的方式运行构建产物
`cell deploy`	构建并通过 preset 的部署器发布；`--dry-run` 只输出部署计划
`cell check`	一次完成配置、TypeScript 类型、装饰器设置与 DI 绑定检查
`cell info`	查看 Cell 解析出的全部信息：preset、mode、组件、DI 模块、hooks、产物状态
`cell config get <key> --why`	某个配置项的最终值，以及设置它的每个文件和环境变量

随处部署

代码保持不变，由 preset 决定产物形态和部署方式。

Preset	产物	部署
`node`（默认）	Node.js HTTP 服务，单个 `index.mjs`	任何能运行 Node.js 的环境：虚拟机、容器、PaaS
`cli`	基于 Cell DI 的命令行程序	以单文件或可执行文件分发
`cloudflare`	Worker + 静态资源 + `wrangler.json`	`cell deploy --preset cloudflare`
`fc`	阿里云函数计算（自定义运行时）	`cell deploy --preset fc`
`scf`	腾讯云云函数（Web 函数）	`cell deploy --preset scf`
`lambda`	AWS Lambda（Function URL / API Gateway）	`cell deploy --preset lambda`
`vercel`	Vercel Build Output API（`.vercel/output`）	`cell deploy --preset vercel`

bash

cell build --single                      # 整个全栈应用就是一个文件：node index.mjs
cell build --compile                     # 独立可执行文件，目标机器无需安装 Node.js
cell deploy --preset cloudflare --dry-run

为 Coding Agent 而设计

Cell 假定项目的下一位开发者可能是 AI Agent，因此让框架的每一处都能被 Agent 一次用对（设计原则）。

一切皆可机读：所有命令加 --json 只输出一条 JSON 结果；错误统一为 CellError，带稳定的 code、出错位置和 hint。
给上下文，而不是让它猜：cell init 生成 AGENTS.md、Cell 技能和 .mcp.json；cell agent sync 让它们与已安装的版本保持一致；cell docs <query> 检索与依赖版本完全匹配的随包文档。
内置 MCP：cell mcp 提供 info、check、config_get、docs_search、build、deploy_plan 工具；cell dev 在 /_cell/mcp 暴露运行中应用的路由、DI 绑定、最终配置、近期请求、日志与错误。
快速反馈：cell check 在运行之前发现类型错误、缺失的装饰器设置和断开的 DI 绑定；createTestApp() 提供进程内集成测试。

jsonc

// .mcp.json（Claude Code、Cursor、CodeBuddy 等）
{ "mcpServers": { "cell": { "command": "npx", "args": ["cell", "mcp"] } } }

原生 AI 能力

typescript

import { Component, Autowired } from '@celljs/core';
import { ChatModel, ProxyChatModel, PromptTemplate } from '@celljs/ai-core';

@Component()
export class Assistant {
    @Autowired(ProxyChatModel)
    protected chatModel: ChatModel;

    @Autowired(PromptTemplate)
    protected promptTemplate: PromptTemplate;

    async ask(question: string): Promise<string> {
        const prompt = await this.promptTemplate.create('Answer briefly: {question}', {
            variables: { question },
            // pi:<provider>/<model id>，由 ProxyChatModel 路由到 @celljs/ai-pi
            chatOptions: { model: 'pi:anthropic/claude-sonnet-4-5' }
        });
        const response = await this.chatModel.call(prompt);
        return response.result.output.content;
    }
}

模型：@celljs/ai-pi 通过 @celljs/ai-core 的 ChatModel 接口接入 20 多家模型服务商（Anthropic、OpenAI、Google、DeepSeek、Ollama 及其他 OpenAI 兼容端点），模型名写 pi:<provider>/<model>。
Agent：@celljs/ai-agent 构建可调用工具的 Agent，工具就是普通的 Cell 组件，事件通过 SSE 推送。
Coding Agent：@celljs/ai-coding-agent 在你的应用中托管 pi coding agent 会话，由 DI 统一管理。
终端界面：@celljs/tui 把 Agent 变成交互式命令行对话（见 examples/tui-app）。

更多示例

依赖注入

typescript

import { Component, Autowired, Value } from '@celljs/core';

@Component()
export class A {}

@Component()
export class B {
    @Autowired()
    protected a: A;                  // 类对象注入
}

@Component()
export class C {
    @Value('foo')                    // 配置属性注入：'obj.xxx'、'arr[1]' 等
    protected foo: string;
}

数据库访问与声明式事务

typescript

import { Controller, Get, Param, Delete, Put, Post, Body } from '@celljs/mvc/lib/node';
import { Transactional, OrmContext } from '@celljs/typeorm/lib/node';
import { User } from './entity';

@Controller('users')
export class UserController {

    @Get()
    @Transactional({ readOnly: true })
    list(): Promise<User[]> {
        return OrmContext.getRepository(User).find();
    }

    @Get(':id')
    @Transactional({ readOnly: true })
    get(@Param('id') id: number): Promise<User | null> {
        return OrmContext.getRepository(User).findOneBy({ id });
    }

    @Post()
    @Transactional()
    create(@Body() user: User): Promise<User> {
        return OrmContext.getRepository(User).save(user);
    }

    @Put()
    @Transactional()
    async modify(@Body() user: User): Promise<void> {
        await OrmContext.getRepository(User).update(user.id, user);
    }

    @Delete(':id')
    @Transactional()
    async remove(@Param('id') id: number): Promise<void> {
        await OrmContext.getRepository(User).delete(id);
    }
}

前端、后端与服务之间的 RPC

typescript

// 共享接口
export const UserService = 'UserService';
export interface UserService {
    hello(name: string): Promise<string>;
}

// 服务提供方
import { Rpc } from '@celljs/rpc';

@Rpc(UserService)
export class UserServiceImpl implements UserService {
    async hello(name: string): Promise<string> {
        return `Hello, ${name}`;
    }
}

// 调用方：注入带类型的远程代理
import { Component } from '@celljs/core';
import { Autorpc } from '@celljs/rpc';

@Component()
export class Greeter {
    @Autorpc(UserService)
    protected userService: UserService;
}

可运行的示例应用在 examples/：backend-app、sample-app（React）、security-app、jwt-app、schedule、prisma-app、docker-app、standalone-app、mycli、tui-app、coding-agent-app。

生态

所有包都以 @celljs 作用域发布，同时提供 CommonJS 与 ES Module 两种格式。

领域	包
核心（`packages/`）	`core`、`logger`、`web`、`mvc`、`http`、`express-adapter`、`serve-static`、`rpc`、`typeorm`、`cache`、`retry`、`schedule`、`security`、`jwt`、`oauth2-core`、`oauth2-client`、`oauth2-jose`
云（`cloud-packages/`）	`cloud`、`faas-adapter`、`lambda-adapter`、`fc-adapter`、`scf-adapter`、`vercel-adapter`、`oss`、`cos`
AI（`ai-packages/`）	`ai-core`、`ai-pi`、`ai-agent`、`ai-coding-agent`
UI（`ui-packages/`）	`react`、`widget`、`tui`
工具链（`dev-packages/`）	`cli`、`vite`、`kit`

文档

cell 命令行文档：命令、preset、部署器、cell.config.ts
从 Cell 3.x 迁移（Cell 3.x 见标签 v3.9.0）
设计文档：架构、模块、Agent 优先原则
API 参考（TypeDoc 生成）
更新日志

参与贡献

欢迎提交 Issue 和 Pull Request。仓库是 Bun workspace monorepo，使用 Turborepo 与 TypeScript 7 构建。

环境要求：Bun（版本见 package.json 的 packageManager）与 Node.js ^20.19.0 || >=22.12.0。

bash

bun install                                   # 安装依赖并同步 tsconfig references
bun run build                                 # 构建所有包
bun run test                                  # 运行全部测试
bunx turbo run test --filter=@celljs/core     # 测试单个包
bun run lint                                  # Biome 检查（bun run format 自动修复）
bun changeset                                 # 为下一次发布记录变更

动态

Repobeats analytics

许可证

MIT

Cell

为什么选择 Cell ​

快速开始 ​

随处部署 ​

为 Coding Agent 而设计 ​

原生 AI 能力 ​

更多示例 ​

生态 ​

文档 ​

参与贡献 ​

动态 ​

许可证 ​

为什么选择 Cell

快速开始

随处部署

为 Coding Agent 而设计

原生 AI 能力

更多示例

生态

文档

参与贡献

动态

许可证