primer

<div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/primerhq/primer/main/docs/assets/hero-dark.png"> <img alt="Primer - 协调小而精的智能代理" src="https://raw.githubusercontent.com/primerhq/primer/main/docs/assets/hero-light.png" width="760"> </picture> <br> **一个不受限制、功能全面的智能代理协调平台，基于一个核心假设：给一个小型模型提供干净、专用的上下文，它可以媲美一个更大的模型。** <br> [](https://github.com/primerhq/primer/blob/main/LICENSE) [](https://github.com/primerhq/primer/actions/workflows/release.yml) [](https://www.python.org/) [](https://github.com/primerhq/primer/blob/main/CONTRIBUTING.md) [](https://github.com/primerhq/primer/stargazers) [快速开始](#快速开始) · [功能](#你可以构建的功能) · [工作原理](#工作原理) · [文档](#文档) · [贡献](#贡献) </div> --- ## 为什么选择Primer 语言模型将注意力预算均匀分配到其上下文中的每个标记上。保持上下文紧凑，重要的标记会获得大部分注意力；如果上下文过于庞大，包含过多的历史信息、未使用的工具定义和无关的背景信息，那么信号就会变弱。Primer的核心假设是 **你通常不需要最大的模型，如果你给现有的模型提供它需要的一切，而不多也不少** - 这是任何模型，无论大小，都可以利用的杠杆。 因此，Primer允许你协调 **多个小而专注的智能代理**，每个代理都有干净的工作上下文，通过实用的部署原语连接：LLM提供商、工作空间、图、知识集合、通道、触发器和语义搜索 - 所有这些都集成在一起，可以在你自己的硬件上运行。 ## 你可以构建的功能 <table> <tr> <td width="33%" valign="top"> ⏸️ **延迟、事件驱动的智能代理** 智能代理在慢速工具或人工决策上暂停，当事件触发时恢复 - 在等待时释放计算资源。 </td> <td width="33%" valign="top"> 🔀 **有向图** 将智能代理编织成循环图（生产者-判断者循环、扇出/扇入、条件分支），作为结构化工作流运行。 </td> <td width="33%" valign="top"> 📁 **工作空间和会话** 物质化的沙盒（本地、容器或Kubernetes）为每个智能代理提供持久的文件系统和git支持的状态。 </td> </tr> <tr> <td width="33%" valign="top"> 🔎 **语义搜索** 将文档摄入向量集合；智能代理仅检索相关的片段，而不是整个语料库。 </td> <td width="33%" valign="top"> 💬 **通道** 将智能代理连接到Slack、Telegram和Discord - 提问、请求批准，并从消息中触发工作。 </td> <td width="33%" valign="top"> 🔌 **MCP服务器** 通过模型上下文协议公开整个平台工具表面，以便外部智能代理和MCP客户端可以使用它。 </td> </tr> <tr> <td width="33%" valign="top"> ✅ **人工审批** 在审批人员授予通道或控制台的批准之前，控制敏感的工具调用。 </td> <td width="33%" valign="top"> 📦 **套件** 将一组调优的智能代理、图和集合打包成一个git支持的、版本化的包，并一步部署到任何地方。 </td> <td width="33%" valign="top"> 🧭 **动态发现** 两个元工具允许智能代理在运行时搜索和调用任何工具或智能代理 - 而无需在其上下文中携带整个目录。 </td> </tr> </table> <!-- DEMO GIF: drop the ask_user -> channel reply -> resume capture here once recorded, e.g. <div align="center"><img alt="Park on a question, reply from a channel, resume" src="docs/assets/demo-park-resume.gif" width="760"></div> --> <!-- SCREENSHOTS: add a framed-console section here (Dashboard / Session control room / Approvals / Graph editor) once the captures are produced. --> ## 构建用于循环工程 循环工程是将逐轮提示智能代理转变为 **设计提示它的系统** - 一个循环，根据调度唤醒，朝着声明的目标工作，根据证据检查自己的输出，并在必要时升级到人工干预。杠杆从编写好的提示转变为设计好的循环。 循环需要一套特定的原语。Primer提供所有这些原语，集成和可自我托管： | 循环需要... | Primer提供 | |---|---| | **心跳** - 工作按节奏显示，而不是手动 | **触发器**，在cron调度、延迟或Webhook上启动新的会话或图运行（或恢复暂停的会话） | | **隔离** - 平行智能代理不会冲突 | **工作空间** - 每个智能代理的本地、容器或Kubernetes沙盒，拥有自己的持久的、git支持的文件系统 | | **持久内存** - 智能代理忘记，仓库不会 | git支持的工作空间 **状态** 加上 **知识集合**，智能代理从中检索知识，以便知识在运行中累积而不是重置为零 | | **制造者和检查者** - 让编写者远离评估者 | **有向循环图**，具有生产者-评估者循环、扇出/扇入和运行时智能代理/图调用 | | **连接器** - 到达真实的工具和真实的人 | 内置的 **MCP服务器** （和MCP客户端），加上 **Slack / Telegram / Discord** 通道 | | **人工门** - 批准风险较高的，让安全的操作运行 | **审批门** 和 **暂停和恢复**：智能代理在人工处等待数小时而不占用计算资源，当回复到达时继续 | Primer不会为您按下“开始”按钮 - 它为您提供构建循环和在需要时让人工介入的编排基础。相同的上下文规则使单个智能代理准确，也让循环在长时间运行而不会漂移：每个迭代都获得干净的、专用的上下文，而不是不断增长的记录。 ## 快速开始 选择适合您的安装方式。所有三种方式都可以在嵌入式SQLite数据库上零配置启动相同的服务器 - 非常适合初次体验。 **pipx** （隔离的CLI安装；需要Python 3.12+）： ```bash pipx install 'primer-ai[full]' # 功能全面的安装 primer api # API + 进程内工作器 ``` 裸`pipx install primer-ai`安装精简的核心（REST API、控制台、MCP、SQLite/Postgres存储和基于API的LLM/嵌入式提供程序）。 `[full]`额外添加可选的后端 - 本地HuggingFace嵌入、Docling摄入、LanceDB、Slack/Telegram/Discord通道和容器/Kubernetes工作空间后端 - 这些后端拉取更大的ML堆栈。你也可以选择单独安装：`primer-ai[huggingface]`、`[docling]`、`[lance]`、`[channels]`、`[docker]`、`[kubernetes]`。 **Docker** （无需Python工具链）： ```bash docker run --rm -p 8000:8000 ghcr.io/primerhq/primer:latest ``` **从源码** （适用于贡献者）： ```bash git clone https://github.com/primerhq/primer.git cd primer uv sync --all-extras uv run primer api ``` 然后验证并打开控制台： ```bash curl http://localhost:8000/v1/health # -> {"status":"ok"} ``` 操作员控制台位于 **http://localhost:8000/console/**。 ### 切换到Postgres（多进程、语义搜索、生产环境） 零配置SQLite是单进程的，不带向量存储。对于多进程、语义搜索或生产环境，请将Primer指向Postgres： ```bash docker compose up -d postgres # 或：podman compose up -d postgres cp config.example.yaml config.yaml # 设置db.config.password以匹配 uv run primer api --config config.yaml ``` `config.example.yaml`文档记录了每个字段。环境变量覆盖文件值：每个`AppConfig`字段映射到`PRIMER_<FIELD>`（嵌套字段使用`__`，例如`PRIMER_DB__CONFIG__PASSWORD`）。Docker镜像读取相同的变量 - 设置`PRIMER_DB_HOST`（和朋友）并自动呈现Postgres + pgvector配置；否则，它运行上述嵌入式SQLite路径。对于可以在容器重启后存活的SQLite数据库，请在`/app/data`处挂载卷。 ## 工作原理 Primer是一堆层，每层都让下一层保持整洁： - **上下文规则** - 工具选择、元工具和内部集合保持每个智能代理的提示简洁。 - **状态** - 工作空间为智能代理提供一个共享的、最小的表面来传递结果，而无需在上下文中携带历史。 - **排序** - 有向循环图将多步骤推理表示为结构，而不是一个巨大的提示。 - **时间** - 事件驱动的暂停和恢复在工作等待慢速工具或人工时释放计算资源。 - **共享** - 套件将工作配置打包成一个版本化的、git支持的包。 - **边缘** - 通道、网络搜索和审批门处理智能代理在平台外部的访问。 在运行时，请求从许多边缘到达（REST/控制台、MCP客户端、聊天通道、触发器），成为 **会话/聊天/图运行**，由工作池声明和驱动；每个回合调用LLM提供商、工具、工作空间和集合，并且可以在人工或事件处暂停，并在以后恢复 - 所有这些都由Postgres支持。 ## 文档 - **操作员文档** - 在服务器运行时，在`/docs`处提供。 - **智能代理使用文档** - [`docs/agents/`](https://github.com/primerhq/primer/tree/main/docs/agents) - 如何通过MCP驱动正在运行的Primer实例。 - **开发者文档** - [`docs/dev/`](https://github.com/primerhq/primer/tree/main/docs/dev) - 架构模式和子系统参考。从 [`docs/dev/README.md`](https://github.com/primerhq/primer/blob/main/docs/dev/README.md) 开始。 ## 贡献 首先阅读 [AGENTS.md](https://github.com/primerhq/primer/blob/main/AGENTS.md) - 它是权威的贡献者合同（项目布局、完成定义、如何运行套件以及硬规则）。 [CONTRIBUTING.md](https://github.com/primerhq/primer/blob/main/CONTRIBUTING.md) 是面向人类的总结。 ```bash uv sync --all-extras docker compose up -d postgres # 窄单元扫描（排除e2e/分布式/ui_e2e）： uv run pytest tests/ -q --ignore=tests/distributed --ignore=tests/ui_e2e \ --ignore=tests/e2e --ignore=tests/integration --ignore=tests/llm ``` 在 [`CODE_OF_CONDUCT.md`](https://github.com/primerhq/primer/blob/main/CODE_OF_CONDUCT.md) 中查看社区期望。 ## 安全 请私下报告漏洞 - 参见 [SECURITY.md](https://github.com/primerhq/primer/blob/main/SECURITY.md)。 ## 许可证 Primer在Apache License 2.0下许可。有关全文，请参见 [LICENSE](https://github.com/primerhq/primer/blob/main/LICENSE)。