内容
<div align="center">
<img src=".assets/logo.png" alt="Arivie chibi owl mascot" width="220" />
# Arivie
**一个您拥有的代理框架。分析是旗舰插件。**
[](https://www.npmjs.com/package/@arivie/core)
[](./LICENSE)
[](#status)
[](https://nodejs.org)
[](https://mastra.ai)
[](https://lobehub.com/mcp/asyncdotengineering-arivie)
</div>
> **Arivie** （发音为 *"ah-REE-vee"*，与 *trivia* 押韵）是一个优先采用 TypeScript、源代码开放、自主托管的**代理框架**。在名称中隐藏了泰米尔语根 *arivu* （அறிவு — *知识 / 智能*）。
Arivie 封装了 **Mastra** （代理运行时、内存、模型、流式处理、工具、MCP）并添加了**持久、可扩展的应用层**，这是通用代理工具包故意省略的：插件 SDK、持久会话/运行/事件、Webhook 分发队列、文件支持的上下文层和一流的诊断。**分析** — 在受控的语义层上将文本转换为 SQL — 是第一方旗舰**插件**，而不是框架本身。
> 不确定 Arivie 和 Mastra 之间的界限？请参阅 [docs/adr/0002 — Arivie vs Mastra ownership](./docs/adr/0002-arivie-vs-mastra-ownership.md)。有一条规则：**永远不要重建 Mastra 叶节点**（代理、内存、模型、流式处理、安全机制、工作流）；仅在 Arivie's 代码中投入持久/插件脊柱。
## 作为 MCP 服务器运行（零配置）
Arivie 附带了一个模型上下文协议服务器。任何 MCP 客户端（Claude Desktop、Cursor、ChatGPT）都可以指向它，或者独立运行 — 无需配置：
```bash
npx -y @arivie/mcp
```
它公开了 `ask`、`query`、`schema` 和 `memory` 工具，以及分析**提示**和语义层**资源**。设置 `DATABASE_URL` 以查询实际数据库，并设置 `ARIVIE_SEMANTIC_PATH` 以加载您自己的语义层；如果没有它们，它将提供一个内置的示例，以便服务器可以立即探索。使用 `@arivie/mcp` 中的 `makeMcpServer({ agent, semantic, db })` 从代码中构建一个完整的服务器。
## 一条命令即可获得流式答案
```bash
pnpm dlx @arivie/cli init my-agent && cd my-agent
# 将 OPENAI_API_KEY + DATABASE_URL 放入 .env（自动加载），然后：
pnpm exec arivie chat --config arivie.config.ts
```
`arivie chat` 在您的应用程序中打开一个终端聊天（Ink TUI）— 选择过去的对话或开始新的对话，提出一个问题，观察代理运行 SQL 并流式传输答案。无需网络服务器，无需 UI 连接，无需 DB 角色仪式即可*看到它工作*。这是快速通道；以下所有内容都是用于构建实际应用程序的。
## 应用程序 — `defineArivie`
```ts
// arivie.config.ts
import { defineArivie, defineAgent } from "@arivie/core";
import { analytics } from "@arivie/plugin-analytics";
import { postgresRuntime, postgresSource } from "@arivie/plugin-postgres";
import { openai } from "@ai-sdk/openai";
export const arivie = await defineArivie({
app: { id: "acme", name: "Acme" },
model: openai("gpt-4o-mini"),
storage: postgresRuntime({ url: process.env.DATABASE_URL! }), // 持久会话/运行/事件
plugins: [
analytics({
semanticPath: "./semantic",
compileMetric: true,
sources: {
postgres: postgresSource({ url: process.env.DATABASE_URL!, readOnlyRole: "arivie_reader" }),
},
}),
],
agents: {
analyst: defineAgent({
instructions: "用简洁、可审计的 SQL 支持的分析回答。",
capabilities: ["analytics.query", "analytics.compile_metric"],
}),
},
context: { root: "./semantic" },
resolveUser: async () => ({ userId: "you", permissions: ["analytics:read"], dbRole: "arivie_reader" }),
});
export default arivie;
```
运行单个提示到其答案 — 持久的一次性会话表面：
```ts
const text = await arivie.prompt({
agent: "analyst",
prompt: "What was last week's revenue per outlet?",
user: { userId: "you", permissions: ["analytics:read"], dbRole: "arivie_reader" },
});
```
对于流式传输或完全控制，请使用 `arivie.sessions.create(...)`（持久、可重放事件）。对于临时、非持久调用，请降级到 Mastra 的 `agent.generate()`。边界在 [ADR 0002](./docs/adr/0002-arivie-vs-mastra-ownership.md) 中有记录。
### 知识交付（默认导航）
分析使用**默认导航**：一个小的、字节稳定的**治理核心**（实体目录、连接骨架、词汇表）在系统中缓存；实体度量/维度/连接和知识概念通过工具**按需获取** — 而不是每个请求都预加载。请参阅 [ADR 0006](./docs/adr/0006-knowledge-delivery-navigation-default-okf.md)。
**知识层** (`@arivie/context`，根目录为 `./knowledge` 或您的 `context.root`) 是 OKF 形状的：具有 `type: playbook | reference | term` 的 Markdown 概念、`index.md` 目录和 `semantic:` 链接回 `./semantic` 中的类型化可执行层。
## 框架为您提供什么
- 🔌 **插件 SDK** — `definePlugin` 贡献工具、上下文模式、通道、计划、路由、功能和权限。分析只是第一个。
- 🧱 **持久运行时** — 会话、运行和**可重放事件日志**；`arivie info` 打印编译后的清单 + 诊断。
- 📡 **Webhook 分发** — 通道将事件发送到持久队列，具有**重复数据删除、重试、死信和租约**（多副本安全）。
- 🛡️ **安全机制** — 将 Mastra 处理器（`PIIDetector`、`PromptInjectionDetector`、`ModerationProcessor`）放到任意代理中，通过 `defineAgent({ inputProcessors })`。
- 💬 **网络聊天，零连接** — `POST /api/chat` 内置（Mastra 的 `@mastra/ai-sdk` 在后台），因此 `@arivie/react` 的 `ArivieChat` / Vercel `useChat` 对您的应用程序开箱即用。
- 🦉 **分析插件** — YAML 语义层（度量、维度、分段、连接、提示）编译为规范 SQL；`arivie_reader` 只读角色 + 只读 SQL 保护；SOP **技能**（版本 Markdown 攻略）。
- 🔗 **MCP 在两端** — Postgres + Mixpanel + 任意 MCP 服务器作为源，`arivie mcp` 将您的代理暴露给 MCP 客户端（Claude Desktop、Cursor）。
## 路线图（设计 + 已排程，但尚未发布）
请参阅 [ADR 0001 — 采用 Mastra 持久执行](./docs/adr/0001-adopt-mastra-durable-execution.md)：
- **工具审批 / HITL** — `requireApproval` 在危险工具上，作为 `ApprovalRequested` 事件发出，通过 Mastra 的工具暂停恢复。
- **持久工作流** — Mastra 工作流（空调度 `workflow` 目标连接到实际工作流）上的多步骤 + cron 调度分析，具有跨进程暂停/恢复。
> 当前 `schedules` 是单个提示 cron 配置 — 尚不是 Mastra 多步骤工作流。
## 示例
`examples/` — 所有 v2，均可运行：
| 示例 | 它展示了什么 |
|---|---|
| `with-pos-fnb` | **旗舰** — 生产 F&B 分析：17 实体语义层 + 通道、订阅、计划、连续性、API 服务器 |
| `kitchen-sink` | 可接近的功能之旅 |
| `woocommerce-…` | 商业领域分析 |
| `with-nextjs` | 最小 Next.js + `/api/chat` 上的 `ArivieChat` |
| `with-arivie-chat` | 完整可部署的网络聊天应用程序 |
## 状态
| | |
|---|---|
| 版本 | **`3.0.0`** — 默认导航知识交付；OKF 形状的上下文层 ([ADR 0006](./docs/adr/0006-knowledge-delivery-navigation-default-okf.md)) |
| 软件包 | **17** 已发布的 `@arivie/*` 软件包 |
| 测试 | 通过 `pnpm -r test` 完整的测试套件绿色 |
| 成熟度 | **alpha** — API 可能会更改；semver 纪律适用 |
| 运行时 | Node ≥20 LTS；Bun 在 `core`/`cli` 上受支持 |
| 许可证 | Apache-2.0 |
| 文档 | [arivie-docs.vercel.app](https://arivie-docs.vercel.app) · [`./docs/`](./docs/) |
## 架构决策
- [ADR 0001 — 采用 Mastra 持久执行](./docs/adr/0001-adopt-mastra-durable-execution.md)
- [ADR 0002 — Arivie vs Mastra 所有权](./docs/adr/0002-arivie-vs-mastra-ownership.md)
