PremAgentic

PremAgentic

面向本地部署，服务于 Agent：名称已说明一切。受管控的知识检索完全在客户自己的网络内运行。指定一个包含 Markdown、文本、PDF、Word 或 Excel 文件的文件夹（后三种格式通过管理员允许的第一方扩展支持），写明哪些人可以读取哪些文件夹，员工和 Agent 就能从中获得带引用的答案，并且在检索任何内容之前就会执行这些规则。

PremAgentic 决定模型可以了解什么。每个答案都是带引用的段落，并标注其可信度、作者和时效性。

the customer's folders of documents -> connector -> chunk -> embed (locally)
-> plain PostgreSQL -> access, lifecycle, trust and freshness gates
-> lexical search in PostgreSQL + exact vector search in process, fused
-> cited answers
-> a golden set that proves it works on THIS corpus

运行时，使用默认的本地嵌入提供程序时，PremAgentic 不会进行任何出站调用，不需要第三方 API 密钥，也不会主动将任何文档发送到任何地方。运行在托管模型上的助手确实会收到每次搜索返回的段落：PremAgentic 会询问每个 Agent 的模型运行在哪里，在每条审计记录中写明答案，并且可以将某个文件夹限制为仅供每个已登记使用该文件夹的 Agent 访问（参见连接助手）。除非管理员选择可选的 openai 嵌入提供程序，或安装并允许会进行此类调用的扩展，否则 PremAgentic 不会连接其他任何服务；会发送邮件的提醒接收端只是示例，并非内置功能。使用由证书颁发机构签发的 HTTPS 证书时，运行时的 TLS 堆栈也可能多次获取证书的吊销状态（OCSP）和缺失的中间证书；默认情况下，自签名证书设置不会请求任何此类地址。

关于如何测试这一声明，以及安装时需要从互联网获取什么，请参阅什么是 PremAgentic。

它读取什么

内置读取器可读取 Markdown 和纯文本文件。PDF、Word（.docx）和 Excel（.xlsx 和 .xlsb）文件由此仓库中的三个第一方扩展读取：extensions/pdf-reader、extensions/docx-reader 和 extensions/xlsx-reader。这些扩展会随解决方案一同构建，并且与任何扩展一样，只有在管理员将各自的构建输出放入扩展文件夹并使用 prem extensions allow 允许后才会加载。三者都只读取文本，不做其他操作：不会跟随或运行文档中的链接、脚本、宏或嵌入文件；超出限制的文件会报告其超出的限制，不会只读取其中一部分。PDF 段落的引用会标注页码，Word 段落的引用会标注文档自身的标题，Excel 段落的引用会标注工作表。读取器能够识别但不会编入索引的文件，会连同原因一并计数，例如 .pdf (no text layer)、.doc (legacy .doc) 或 .docm (macro-enabled)；没有任何读取器声明支持的文件则按扩展名计数，因此包含这类文件的文件夹不会显得像是一次空运行。任何读取器查看文件之前，运行最多只会读取其中的 256 MB；即使有一个文件无法存入索引，也不会中断运行。

tests/Premagentic.Benchmark 会在合成索引上测量搜索路径的耗时，任何人都可以在一次性数据库上重新运行它；它打印的每张表都会注明运行所用的机器，以及运行的两种模式之一（自行测量）。

它不会做什么

• 它不会写入源文件。
• 它不会生成文案。
• 它不会识别图片或扫描页面中的文字。

前两点在它不会做什么中有说明；它读取的内容如上所述。通过公司目录登录的功能将在面向团队的 PremAgentic中推出。

快速开始

# 1. Local stock PostgreSQL 17, on 5434 to stay clear of any PostgreSQL already on 5432 or 5433
docker compose up -d

# 2. Use the local development database for this shell. PremAgentic connects to
#    nothing unless told where; this switch names the compose instance.
$env:PREM_DEV_DATABASE = "1"    # Linux or macOS: export PREM_DEV_DATABASE=1

# 3. One time: fetch the local embedding model (all-MiniLM-L6-v2 ONNX, ~90 MB)
./scripts/download-model.ps1          # Windows; on Linux or macOS: ./scripts/download-model.sh

# 4. Create the two groups the sample corpus and golden set name
dotnet run --project src/Premagentic.Cli -- groups add hr
dotnet run --project src/Premagentic.Cli -- groups add engineering

# 5. Ingest the sample corpus. Each folder gets its own rule, so the two go in
#    separately with different audiences.
dotnet run --project src/Premagentic.Cli -- ingest ./sample-docs/open --public --prefix open
dotnet run --project src/Premagentic.Cli -- ingest ./sample-docs/hr --principals group:hr --prefix hr

# 6. Ask it something
dotnet run --project src/Premagentic.Cli -- search "how long do I have to file an expense claim" --as group:engineering

# 7. Prove the gate. HR reaches the salary bands; engineering does not.
dotnet run --project src/Premagentic.Cli -- search "band four compensation review" --as group:hr
dotnet run --project src/Premagentic.Cli -- search "band four compensation review" --as group:engineering

# 8. Run the golden set, which asserts both of those outcomes. It is the starter
#    profile's own file, so the questions are the ones the profile applies.
dotnet run --project src/Premagentic.Cli -- eval samples/profiles/starter/golden-set.json eval/report.md

# Tests (unit plus a Testcontainers end-to-end slice; Docker required)
dotnet test

同一套配置就是一个配置档案。在全新的数据库上，运行 prem profile apply ./samples/profiles/starter 即可一步创建两个组、按规则注册两个来源并设置黄金集；再次应用时不会做任何更改，并会说明这一点。详见配置档案。

未配置数据库时，命令行会自行说明用法：

prem --help                  every command, with every option explained
prem <command> --help        one command's part
prem --version               the version, with the commit it was built from
prem reminders run [--plan]  what each source owner is reminded of: stale documents and the review queue

完整列表见「prem 命令」，该文档由程序生成。

连接助手

Agent 通过同一进程中的 /mcp 使用自己的令牌连接 MCP。 它们可以使用两个只读工具 search_knowledge 和 get_document_section，没有任何可写入、存储或记住信息的工具。 对于只支持 stdio 的 Agent，Premagentic.McpServer 可充当桥接工具。连接方法见：连接助手。

个人可以在 /portal/connect 连接自己的助手：由此创建的 Agent 仅以该个人的身份行事，不会做更多事；其令牌只会在所用助手的配置旁显示一次，也可以在此撤销。 管理员可通过 agents.self_service_max 限制每个人可拥有的 Agent 数量（设为 0 可关闭此功能），并可通过 connect.snippets 修改任何配置的措辞。管理员可以用 prem settings set mcp.instructions "<text>" 为每个助手提供部署专属指令：客户端若会读取服务端在连接时发送的内容，就会收到这些指令；它们会作为资源 premagentic://instructions 提供，连接页面也会显示这些指令，供用户粘贴到 AGENTS.md、CLAUDE.md 或客户端自己的指令中。

看看效果

文件夹规则决定谁可以读取哪些内容。第一个匹配调用者的条目决定结果，没有匹配项则拒绝访问。

针对任意人员和任意文档询问原因，PremAgentic 会显示规则及每一道关卡。这里，一名承包商无法查看温室笔记。

每个 Agent 都会记录其模型的运行位置。将其切换到托管模型后，下次调用时，禁止托管模型 Agent 访问的文件夹也会对它关闭。

审计记录会显示谁发起了请求、适用哪项策略、模型在哪里运行，以及提供的每段内容；此处筛选的是发送给托管模型 Agent 的内容。

文档

• 入门： PremAgentic 是什么、快速开始、连接助手
• 决策方式： 访问权限、生命周期、信任与时效性、管理
• 运行： 安装、运行、升级与移除、配置、存储、完全本地化的技术栈
• 扩展： 来源、读取器与分块器、扩展、编写扩展、连接器、配置文件、调优与黄金集
• 参考： 使用界面、prem 命令、已知状态、路线图

所有文档的索引及各自涵盖的内容见 docs/README.md。

参与贡献

如需贡献，请参阅 CONTRIBUTING.md；首次提交拉取请求时，你需要签署一次贡献者许可协议。问题和想法请发布到仓库的 Discussions；首次更改请从标记为 good first issue 的议题开始；后续计划请查看路线图。

支持

Agave Information Solutions, LLC 提供 PremAgentic for Teams 支持服务，包括安装和升级协助、硬件规格建议、将组织的目录和权限映射到 PremAgentic，以及维护人员答疑。请发送邮件至 [email protected]。

问题请发布到仓库的 Discussions，错误请提交到 Issues，维护人员会阅读并分类处理。安全报告总会得到回复；请参阅 SECURITY.md。

许可证

PremAgentic 是基于 GNU Affero 通用公共许可证第 3 版（仅此版本，AGPL-3.0-only）发布的自由软件。请参阅 LICENSE 和 NOTICE。依赖项和模型的许可证列于 THIRD-PARTY-NOTICES.md。

Agave Information Solutions, LLC 也提供 PremAgentic 商业许可证，可用于将其集成到闭源产品中，或运行修改后的副本供用户使用，而不向他们提供源代码。请发送邮件至 [email protected]。

PremAgentic for Teams 是组织为让多人使用 PremAgentic 而添加的产品。它提供目录组映射、审计记录保留和导出功能。后续计划包括：通过 Microsoft、Google 或其他 OIDC 提供商登录并同步组；可读取来源自身权限的连接器，支持 SharePoint、OneDrive 和 Windows 文件共享；管理 API；以及签名安装程序。该产品包含支持服务。

此附加组件作为一个扩展安装在同一扩展主机上，像其他扩展一样通过哈希值授权；部署用户不超过 10 人时可免费使用。客户可以查看该附加组件的源代码。

PremAgentic 名称归 Agave Information Solutions, LLC 所有，不随代码一同授权。

如需报告漏洞，请参阅 SECURITY.md；如需贡献，请参阅 CONTRIBUTING.md。

网站： https://premagentic.com

项目页面与源代码： https://github.com/premagentic/premagentic

由位于亚利桑那州斯科茨代尔的 AgaveIS 构建并维护。