[English](./README.md) | 简体中文

<p align="center">
  <img src="./assets/logo.svg" width="120" alt="Cell logo">
</p>

<h1 align="center">Cell</h1>

<p align="center">
  <strong>一次构建、随处运行的 TypeScript 应用框架，为开发者与 Coding Agent 共同设计。</strong>
</p>

<p align="center">
  <a href="https://github.com/cellbang/cell/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
  <a href="https://www.npmjs.com/org/celljs"><img src="https://img.shields.io/npm/v/@celljs/core.svg?style=flat" alt="npm version"></a>
  <a href="https://www.npmjs.com/org/celljs"><img src="https://img.shields.io/npm/dm/@celljs/core.svg?style=flat" alt="npm downloads"></a>
  <a href="https://github.com/cellbang/cell/actions/workflows/ci.yml?query=branch%3Amain"><img src="https://github.com/cellbang/cell/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
  <a href="https://gitee.com/cellbang/malagu"><img src="https://gitee.com/cellbang/malagu/badge/star.svg?theme=dark" alt="Gitee stars"></a>
  <a href="https://gitcode.com/cellbang/cell"><img src="https://gitcode.com/cellbang/cell/star/badge.svg" alt="GitCode stars"></a>
</p>

<p align="center">
  <a href="#快速开始">快速开始</a> ·
  <a href="#随处部署">随处部署</a> ·
  <a href="#为-coding-agent-而设计">Coding Agent</a> ·
  <a href="#原生-ai-能力">AI</a> ·
  <a href="./examples">示例</a> ·
  <a href="./dev-packages/cli/README.md">CLI 文档</a>
</p>

---

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](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) 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 一次用对（[设计原则](./docs/design/agent-first.md)）。

- **一切皆可机读**：所有命令加 `--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`](./examples/tui-app)）。

## 更多示例

<details>
<summary><strong>依赖注入</strong></summary>

```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;
}
```

</details>

<details>
<summary><strong>数据库访问与声明式事务</strong></summary>

```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);
    }
}
```

</details>

<details>
<summary><strong>前端、后端与服务之间的 RPC</strong></summary>

```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;
}
```

</details>

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

## 生态

所有包都以 [`@celljs`](https://www.npmjs.com/org/celljs) 作用域发布，同时提供 CommonJS 与 ES Module 两种格式。

| 领域 | 包 |
| --- | --- |
| 核心（[`packages/`](./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-packages)） | `cloud`、`faas-adapter`、`lambda-adapter`、`fc-adapter`、`scf-adapter`、`vercel-adapter`、`oss`、`cos` |
| AI（[`ai-packages/`](./ai-packages)） | `ai-core`、`ai-pi`、`ai-agent`、`ai-coding-agent` |
| UI（[`ui-packages/`](./ui-packages)） | `react`、`widget`、`tui` |
| 工具链（[`dev-packages/`](./dev-packages)） | `cli`、`vite`、`kit` |

## 文档

- [`cell` 命令行文档](./dev-packages/cli/README.md)：命令、preset、部署器、`cell.config.ts`
- [从 Cell 3.x 迁移](./docs/migration-4.md)（Cell 3.x 见标签 `v3.9.0`）
- 设计文档：[架构](./docs/design/architecture.md)、[模块](./docs/design/modules.md)、[Agent 优先原则](./docs/design/agent-first.md)
- [API 参考](https://cellbang.github.io/cell/docs/next/)（TypeDoc 生成）
- [更新日志](./CHANGELOG.md)

## 参与贡献

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

环境要求：[Bun](https://bun.sh)（版本见 `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](https://repobeats.axiom.co/api/embed/59b39c98717cf1ae18b57f24d2efe91617e3a6f1.svg "Repobeats analytics image")

## 许可证

[MIT](./LICENSE)