# @runappsai/agent 中文文档

规范地址：https://npmcn.com/package/%40runappsai/agent/

版本：0\.1\.4
npm 元数据更新时间：2026-11-02T08:40:07.558Z
中文译文更新时间：2026-11-02T09:03:42.625Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40runappsai/agent
原文对照：https://npmcn.com/package/%40runappsai/agent/?lang=original
项目主页：https://github.com/runapps/agent
源码仓库：https://github.com/runapps/agent

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.8 MB，84 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-11-01T14:04:55.828Z
- 最新版本发布：2026-11-02T08:40:07.364Z
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

Agent harness：有工作区、技能、会话、压缩、沙盒和聊天UI的模型↔工具循环。带来任何兼容openai的模型提供商（包括RunApps）；没有运行时依赖项。

## 安装

```sh
npm install @runappsai/agent
```

也可以使用：`pnpm add @runappsai/agent`、`yarn add @runappsai/agent`、`bun add @runappsai/agent`

## README

# @runappsai /代理

agent harness：模型↔工具循环、带技能的文件工作区、保存的会话、上下文压缩、JavaScript沙箱——另外还有一个用于网页的完整聊天UI和用于命令行工具的助手。它可以与任何openai兼容的模型API ([RunApps](https://www.runapps.ai/)， OpenAI, DeepSeek, OpenRouter，你自己的代理)，没有运行时依赖。

| 进口 | 什么 | 运行在 |
| --- | --- | --- |
| `@runappsai/agent` | 核心: `createAgent`， `openWorkspace`、供应商、工具、技能 | 浏览器、Node、Deno、worker |
| `@runappsai/agent/ui` | 聊天界面： `renderChat`，下拉菜单，主题 | 吃嫩叶的动物 |
| `@runappsai/agent/node` | 一个文件夹作为工作空间，存储在磁盘上，终端对话框 | 节点18 + |

模仿 [π](https://pi.dev/) （MIT）：压缩提示，编辑匹配，模板参数和技能措辞都来自它。

**状态：测试阶段** - API仍有可能改变。

## 安装

```sh
npm i @runappsai/agent
```

```js
import { createAgent, openWorkspace, defineTool, openAIProvider } from "@runappsai/agent";
import { renderChat } from "@runappsai/agent/ui";                 // web pages
import { nodeFS, nodeStore, terminalUI } from "@runappsai/agent/node";   // Node
```

或者在一个页面中，没有构建步骤-核心和UI在一个脚本中 `window.RunAppsAgent`：

```html
<script src="https://www.runapps.ai/sdk/agent-latest.js"></script>
```

（`dist/agent-core.umd.js`,也 `@runappsai/agent/browser/core`，是核心。)

## 快速开始：五分钟内聊天

```html
<div id="assistant" style="height: 640px"></div>

<script src="https://www.runapps.ai/sdk/agent-latest.js"></script>
<script type="module">
  // With npm: import { openWorkspace, openAIProvider, defineTool } from "@runappsai/agent";
  //           import { renderChat } from "@runappsai/agent/ui";
  const { renderChat, openWorkspace, openAIProvider, defineTool } = RunAppsAgent;

  // 1. Where the model calls go. Keep API keys on your server: point at your own proxy.
  const provider = openAIProvider({ baseURL: "/api/llm", models: "fetch" });

  // 2. A tool of your app's (optional).
  const getTime = defineTool({
    name: "get_time",
    description: "The current date and time in the user's timezone.",
    execute: () => new Date().toString(),
  });

  // 3. The chat. Each conversation gets its own directory of files in IndexedDB.
  const chat = renderChat(document.getElementById("assistant"), {
    provider,
    model: "gpt-4.1",
    appName: "My app",
    instructions: "You are the assistant inside My app. Be brief.",
    tools: [getTime],
    workspace: (sessionId) => openWorkspace(provider, { id: sessionId }),
    suggestions: ["What time is it?", "Write a haiku about Mondays"],
  });
  await chat.ready;
</script>
```

这是一个完整的助手：流媒体Markdown回复，折叠工具调用，实时“正在做什么”状态，文件附件，文件面板，技能菜单，保存对话，斜杠命令，设置（模型，思维水平，限制），倒带，浅/暗主题。

与 [RunApps](https://www.runapps.ai/) 相反，用户登录并为自己的使用付费——不需要代理，也不需要密钥。

```html
<script src="https://www.runapps.ai/sdk/latest.js"></script>
<script src="https://www.runapps.ai/sdk/agent-latest.js"></script>
<script type="module">
  const client = new RunApps({ project: "my-app" });
  const chat = RunAppsAgent.renderChat(document.getElementById("assistant"), {
    client,
    workspace: (id) => RunAppsAgent.openWorkspace(client, { id }),
  });
</script>
```

## 快速入门：命令行代理

```js
import { createAgent, openAIProvider, openWorkspace } from "@runappsai/agent";
import { nodeFS, nodeStore, terminalUI } from "@runappsai/agent/node";

const provider = openAIProvider({ baseURL: process.env.OPENAI_BASE_URL, apiKey: process.env.OPENAI_API_KEY, models: "fetch" });
const workspace = await openWorkspace(provider, {
  id: "my-project",
  dir: nodeFS(process.cwd()),      // the agent works in this folder
  store: nodeStore(),              // sessions and skills in ~/.runapps-agent
});
const agent = createAgent(provider, { workspace, ui: terminalUI() });   // confirmations as y/N in the terminal

agent.on("text_delta", (e) => process.stdout.write(e.delta));
await agent.prompt(process.argv.slice(2).join(" "));
```

`examples/cli.mjs` 是一个完整的终端聊天：流，工具调用，确认，会话可以恢复，Ctrl+C停止。看到 [节点和命令行](https://npmcn.com/package/%40runappsai/agent/docs/node.md).

## 快速入门：一个没有任何UI的代理

```js
import { createAgent, defineTool, openAIProvider } from "@runappsai/agent";

const provider = openAIProvider({ baseURL: "https://api.deepseek.com/v1", apiKey: process.env.DEEPSEEK_KEY });

const addTodo = defineTool({
  name: "add_todo",
  description: "Add an item to the user's todo list.",
  parameters: {
    type: "object",
    properties: { text: { type: "string" }, due: { type: "string", description: "YYYY-MM-DD" } },
    required: ["text"],
    additionalProperties: false,
  },
  execute: async ({ text, due }) => { await db.todos.add({ text, due }); return `Added "${text}".`; },
});

const agent = createAgent(provider, {
  model: "deepseek-chat",
  instructions: "You manage the user's todo list.",
  tools: [addTodo],
  sandbox: false,        // no run_js
  askUser: false,        // no questions back to a user
});

agent.on("text_delta", (e) => process.stdout.write(e.delta));
const result = await agent.prompt("Add 'ship v2' for next Friday");
console.log(result.reason, result.usage);
```

## 文档

| 指南 | 里面有什么？ |
| --- | --- |
| [供应商](https://npmcn.com/package/%40runappsai/agent/docs/providers.md) | 连接模型API： `openAIProvider`， `runappsProvider`，编写自己的，错误和重试 |
| [代理](https://npmcn.com/package/%40runappsai/agent/docs/agent.md) | 运行，转向和排队，停止和继续，事件，权限和对话框，会话，压缩，所有选项 |
| [工具](https://npmcn.com/package/%40runappsai/agent/docs/tools.md) | `defineTool`、模式、结果、确认、进度、无处可去的调用、MCP服务器、内置工具 |
| [工作区和文件](https://npmcn.com/package/%40runappsai/agent/docs/workspace.md) | 虚拟目录，安装你的应用程序的数据，一个真实的文件夹，内存和项目笔记，提示模板，pdf文件，更改事件 |
| [技能](https://npmcn.com/package/%40runappsai/agent/docs/skills.md) | 技能文件夹和压缩，应用程序的技能，懒惰技能，用户的技能，写作描述 |
| [聊天界面](https://npmcn.com/package/%40runappsai/agent/docs/chat-ui.md) | `renderChat` 选项和句柄，UI做什么，命令，单对话模式，主题化，下拉框，调试 |
| [节点和命令行](https://npmcn.com/package/%40runappsai/agent/docs/node.md) | 一个文件夹作为工作空间，存储在磁盘上，终端对话框，pdf， CLI的例子 |
| [API参考](https://npmcn.com/package/%40runappsai/agent/docs/reference.md) | 所有出口都集中在一个地方 |

`examples/chat/index.html` 完整的页面是否使用了所有内容(服务于包根并打开？ `/examples/chat/index.html`); `examples/cli.mjs` 终端版本。

## 开发

```sh
npm install
npm run build     # dist/*.js (ESM), dist/{index,ui,node}.cjs, dist/agent.umd.js + agent-core.umd.js (browser)
npm test          # node:test on the built output, model calls mocked
```

## 许可证

麻省理工学院

## 常见问题

### @runappsai/agent 是什么？

Agent harness：有工作区、技能、会话、压缩、沙盒和聊天UI的模型↔工具循环。带来任何兼容openai的模型提供商（包括RunApps）；没有运行时依赖项。

### 如何安装 @runappsai/agent？

在项目目录运行 npm install @runappsai/agent，或使用 pnpm add / yarn add / bun add。

### @runappsai/agent 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @runappsai/agent 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @runappsai/agent 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @runappsai/agent 可以商用吗？

@runappsai/agent 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @runappsai/agent 还在维护吗？

最新版本 0\.1\.4 发布于 2026/11/02（1 天前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/11/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。