@sema-agent/core/README.zh-CN.md

Stateless, task-oriented AI agent core

# @sema-agent/core

> **Claude Code 级 agent 引擎,以库的形态交付——模型你自己带。**

`@sema-agent/core` 是一个**无状态、任务化**的 TypeScript/Node AI agent 引擎。LLM 由你提供
(任意 OpenAI 兼容网关,或 Anthropic Messages API);引擎负责完整的 agent 循环——模型轮次、
原生工具调用、MCP 服务器、会话记忆、自动上下文压缩、多 agent 委派——并返回机器可读的结果。

```ts
const res = await runner.runTask({ objective: "...", model: "main" });
```

## 它是什么 / 不是什么

**它是:**

- **一个库**(`npm install @sema-agent/core`),嵌进你自己的服务、CLI 或产品里。
  一个 `Runner` 实例、普通函数调用、带类型的事件流。
- **模型无关。**"大脑"是注入的流式补全函数。内置两类适配器:OpenAI 兼容的
  `/v1/chat/completions` 端点(vLLM、Ollama、OpenRouter、DeepSeek、OpenAI)与
  Anthropic Messages API。路由、故障转移、模型角色都是配置项。
- **设计上无状态。**一个任务自带全套配置(模型、提示词、工具、MCP、skill、限额),
  跑完返回一个 `TaskResult`。持久化——会话、检查点、长期记忆、workflow 日志——全部
  藏在存储接口后面,可用文件或 Postgres 落地。

**它不是:**

- 不是聊天应用、CLI 产品或托管服务。没有 UI,也没有必须部署的服务端
  (可选提供一个可嵌入的 HTTP/SSE 服务器 `createTaskServer`)。
- 不绑定任何模型厂商。不带 API key、没有默认模型、不回传数据。
- 不是提示词模板或"链式"框架。它是完整的 agent 运行时:循环、工具挂载、
  安全闸门、持久化层,一个不少。

## 核心亮点

- **Claude Code 对齐的工具面。**内置 agent 工具集(文件读/写/编辑、支持后台执行的 shell、
  grep/glob 搜索、子 agent 委派、todo/plan 面……)对齐 Claude Code 的工具契约,
  并持续用活体探针验证。
- **持久化检查点与人在环。**任务可以在审批闸、预算上限或显式检查点处挂起,稍后恢复——
  甚至在另一个进程或机器上——背后是可插拔的 `CheckpointStore`(内存/文件/Postgres)。
  任务状态语义明确:`completed | blocked | failed | timeout | suspended | needs_review`。
- **记忆引擎。**带作用域的长期记忆,`MemoryBackend` 可插拔(文件或 Postgres);
  配合自动压缩,长任务不会撑爆上下文窗口,也不会丢线索。
- **多 agent。**子 agent 委派、team 讨论、确定性的 `runWorkflow` 编排(带可恢复日志),
  以及可选启用的 observer agent(旁观并引导正在运行的 agent)。
- **流式优先。**每个任务发出带类型的 `TaskEvent` 流(推理增量、文本增量、工具生命周期、
  进度、诊断),经 `createTaskServer` 可直接接 SSE。
- **内建安全模型。**工具策略的 allow/ask/deny 语义、按 principal 的授权、shell 闸门、
  可持久化的审批挂起——不是事后补丁。
- **小而诚实。**运行时依赖只有两个(`typebox`、`@modelcontextprotocol/sdk`)。
  5400+ 条确定性 vitest 测试完全离线可跑(`npm test`),其中包括一个真实的 stdio MCP 服务器。
- **源码可得。**BUSL-1.1:个人/教育/研究/非商用生产免费;2030-07-13 自动转 Apache-2.0。
  见[许可](#许可)。

## 60 秒上手

要求:Node ≥ 20,以及一个 OpenAI 兼容网关(流式 + function calling)。

```bash
npm install @sema-agent/core
```

```ts
import { Runner, createOpenAIBrain, type Model } from "@sema-agent/core";

// 1) 描述模型(指向你自己的网关)
const model: Model = {
  id: "qwen-3.5-35b", name: "Qwen3.5-35B",
  api: "openai-completions", provider: "vllm",
  baseUrl: "http://localhost:8000/v1",          // 你的网关,结尾不带 /chat/completions
  reasoning: true, input: ["text", "image"],
  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
  contextWindow: 262144, maxTokens: 4096,
};

// 2) 建 Runner(brain = 外部 LLM;models = 你的模型目录)
const runner = new Runner({
  brain: createOpenAIBrain(),
  models: { main: model },
});

// 3) 跑一个任务
const res = await runner.runTask({
  objective: "用三个要点总结 SSE 与 WebSocket 的取舍。",
  model: "main",
  sessionId: "chat-42",   // 传同一个 id 即继续对话;不传则开新会话
});

console.log(res.status);  // "completed" | "blocked" | "failed" | "timeout" | "suspended" | "needs_review"
console.log(res.result);  // 最终回复文本
```

接下来:挂工具(`defineTool`、内置 SQL 工具、任务级 MCP)、逐 token 消费事件流、
或把 Runner 暴露成 HTTP + SSE 服务——[SDK 指南](docs/sdk/README.md)按主题分章覆盖,
从 [01 – Getting Started](docs/sdk/01-getting-started.md) 读起。

## 文档导航

| 文档 | 内容 |
|------|------|
| [SDK 指南(目录)](docs/sdk/README.md) | 完整 SDK 文档入口,按主题分 10 章 |
| [01 – Getting Started](docs/sdk/01-getting-started.md) | 安装、60 秒集成、核心概念、可运行示例 |
| [02 – Runner and Tasks](docs/sdk/02-runner-and-tasks.md) | `Runner`、`RunnerDeps`、`TaskSpec`、`TaskResult`、任务状态语义 |
| [03 – Brains and Models](docs/sdk/03-brains-and-models.md) | Brain 契约、OpenAI/Anthropic 适配器、故障转移、模型角色、推理强度 |
| [04 – Tools and MCP](docs/sdk/04-tools-and-mcp.md) | `defineTool`、SQL 工具、issue 工具、MCP 集成 |
| [05 – Streaming and the HTTP Server](docs/sdk/05-streaming-and-http-server.md) | `TaskEvent` 协议、SSE、`createTaskServer` |
| [06 – Sessions, Memory, and Compaction](docs/sdk/06-sessions-memory-and-compaction.md) | 会话存储、自动压缩、长期记忆后端 |
| [07 – Multi-Agent](docs/sdk/07-multi-agent.md) | 子 agent、team 讨论、teacher 模式 |
| [08 – Workflows](docs/sdk/08-workflows.md) | 确定性 `runWorkflow` 编排与可观测性 |
| [09 – Security and Policies](docs/sdk/09-security-and-policies.md) | 工具策略、审批、shell 闸门、人在环监督 |
| [10 – Extension Points](docs/sdk/10-extension-points.md) | 自定义 brain、会话存储、执行环境、Postgres 适配器 |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 引擎内部结构 |
| [docs/TESTING.md](docs/TESTING.md) | 测试体系与运行方式 |
| [docs/REFERENCES.md](docs/REFERENCES.md) | 设计脉络与外部参考 |
| [docs/ROADMAP.md](docs/ROADMAP.md) | 项目方向 |
| [CONTRIBUTING.md](CONTRIBUTING.md) | 如何参与贡献 |
| [SECURITY.md](SECURITY.md) | 漏洞报告 |

## 本地开发

```bash
npm install
npx tsc --noEmit     # 类型检查(应为 0 错误)
npm test             # vitest:全量确定性套件,离线,无需网关
npm run smoke        # mock brain 端到端冒烟
```

需要真实网关的活体示例在 `src/examples/`。

## 许可

[BUSL-1.1](LICENSE)(Business Source License)。

- 个人、教育、研究及非商用生产环境**免费**。
- **商用生产环境需向许可方取得授权**。
- **2030-07-13** 自动转为 **Apache-2.0**。

准确条款以 [LICENSE](LICENSE) 文件为准。