Xfeatures Athenaeum

连接 Xfeatures 应用、人员与 AI 代理的安全知识层。

一个为组织内每个应用、人员和 AI 代理提供统一认证的知识与检索服务。精确事实存于 D1，文档存于 R2，语义检索通过 Cloudflare AI Search 完成——而没有任何调用方直接接触这些组件。

调用方通过 REST、Workers RPC 或 MCP 进行通信。Athenaeum 在每次调用时解析调用者身份及其可见权限，并在返回结果前对每个结果与实时数据库进行重新校验。

Caller ──▶ REST / RPC / MCP ──▶ authenticate ▸ authorize ▸ audit ──▶ D1 · R2 · AI Search

源码可获取——专有软件，非开源。 您可以在 Xfeatures 专有源码许可 下阅读、克隆并私下评估此代码。将其作为生产服务运行、进行商业运营或重新分发修改副本，需要另行获得书面许可。参见下方 许可。

为什么存在

如果给每个代理各自独立的数据库、文档副本和手写 RAG 流水线，最终会得到每个代理一套知识库——各自以不同方式过时，且均无访问控制。Athenaeum 是另一种方案：一个语料库、一套权限模型、一条审计轨迹，以及按代理切分的视图。

Related MCP server: Volterra Knowledge Engine

它保证什么

• 身份绝不由客户端声明。 调用方出示凭证；权限来自 Athenaeum 自身数据库，以验证后的身份为键。修改令牌的作用域不会获得任何额外权限。

• 每次调用都强制分类与领域。 一个被授权访问 support 领域 INTERNAL 级别的支持代理，无法看到同一领域下标记为 RESTRICTED 的文档——甚至不会知道其存在。

• 搜索索引并非权威。 每个检索到的分块在返回前都会与实时数据库行重新校验，因此过期或被篡改的索引无法泄露内容，被取代的版本也无法以当前版本的身份被提供。

• 检索到的知识是证据，而非指令。 Athenaeum 从不调用 LLM。它返回带引用的段落；调用方代理负责综合答案，并应将内容视为不可信。

• 发布需要人工参与。 代理可以起草文档并提交审核。没有任何传输方式暴露发布功能。

• 没有手动删除。 文档移入回收站，72 小时内可恢复，由定时任务清除——绝无按钮直接删除。

两类知识

Athenaeum 以不同方式存储精确事实和语义知识，因为它们的失败模式不同。

需要价格的代理绝不应通过搜索获取。必须正确的数字是事实查找；供人阅读的段落是文档。从相似性搜索中得到一个看似合理但错误的数字，正是这种拆分要防止的失败。

每个存储的用途

• D1 是权威。事实、文档元数据、目录、代理、角色、权限、配额和审计轨迹。所有访问决策都基于 D1，绝不基于缓存或索引。

• R2 保存规范文档内容，每个版本一个不可变对象。键由服务器生成，并嵌入分类和领域以便人工浏览——它们明确不是安全边界，因为存储桶从不公开可达。

• AI Search 是 R2 之上的索引，仅此而已。它是关于去哪查找的提示。它绝不是调用方可查看内容的权威。

Athenaeum 所处位置

flowchart LR
    people["People"] --> hq["Xfeatures HQ<br/>control plane"]
    agents["AI agents<br/>and applications"] --> ath
    hq -- "machine credential,<br/>authorized like anyone else" --> ath["Xfeatures Athenaeum"]
    ath -- "token introspection" --> acc["Xfeatures Account<br/>identity"]
    hq --> acc
    ath --> stores[("D1 · R2 · AI Search")]

• Xfeatures Account 是 Xfeatures 生态系统的身份平台。它只回答谁在调用，别无其他：Athenaeum 获取内省后的身份，并从自身数据库解析权限。Account 令牌可以证明你是谁，但在这里可能仍然一无所获。（Account 是独立的私有系统；本仓库记录其公开契约——RFC 7662 内省——而非其实现。）

• Xfeatures HQ 是控制平面，人员在此管理文档、审核并发布，以及管理访问。HQ 在 Athenaeum 内部没有特殊地位——它使用自己的机器凭证进行认证，并在每次调用时被授权。撤销 HQ 的主体即可切断其访问，而无需触碰其 Account 身份。

安全模型

五个属性，均在代码中强制实施，而非依赖约定：

1. 身份是解析出来的，而非接受的。 每次调用，权限都来自基于已验证身份的全新 D1 读取。调用方发送的任何内容都无法扩大其可见范围。

2. 每次读取都有两道独立门禁。 作用域权限（documents.read.<domain>）和分类权限（knowledge.classification.<TIER>）。只持有其一则拒绝。

3. 来源被记录，而非推断。 每个文档都携带其来源类型和引用，每个版本都记录谁写的以及为什么，每次经过认证的调用——无论允许还是拒绝——都会写入审计事件。

4. 版本不可变。 编辑会追加版本；绝不重写。回滚会将早期版本作为新版本重新发布。历史是证据，因此不会被覆盖。

5. 当前版本一致性校验。 仅当分块的源对象是文档的当前版本且实时行仍显示其处于活动状态且仍带有调用方可查看的分类时，搜索命中才会被提供。过期索引无法以当前版本的身份释放被取代的版本，也无法释放刚刚被归档、重新分类或移入回收站的内容。

检索到的内容是数据，而非指令——Athenaeum 从不调用 LLM。参见 THREAT-MODEL.md 了解这些保证的基础，以及 SECURITY-ASSUMPTIONS.md 了解其边界。

快速开始

TOKEN=$(curl -s https://auth.xfeatures.net/oauth/token \
  -d grant_type=client_credentials \
  -d "client_id=$CLIENT_ID" -d "client_secret=$CLIENT_SECRET" | jq -r .access_token)

curl -s https://athenaeum.xfeatures.net/v1/knowledge/search \
  -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"query": "what is the refund window", "domain": "support"}'

完整指南：REST · MCP

文档

连接方式

本仓库是服务本身。面向开发者的接口位于各自独立仓库，因此每个都有独立的 README、示例和发布节奏：

MCP 服务器实现保留在此处，位于 src/mcp/，因为它与 REST 和 Workers RPC 共享同一条 认证 → 授权 → 审计 流水线。MCP 仓库是面向客户端的一半：如何连接以及工具做什么。REST 同样在此实现——SDK 是其客户端，因此无需单独维护 REST 服务器仓库。

请求如何被决策

flowchart LR
    req["REST · RPC · MCP"] --> authn["authenticate<br/>introspect or RPC key"]
    authn --> princ["resolve principal<br/>fresh from D1"]
    princ --> authz["authorize<br/>permission + classification + domain"]
    authz --> svc["knowledge services"]
    svc --> live["re-check every result<br/>against the live row"]
    live --> audit["audit the decision"]
    audit --> resp["response"]

三种传输方式运行相同的代码。MCP 或“内部”调用方没有更宽松的 ACL。

文档生命周期

文档在版本级别不可变。编辑会写入新版本；绝不重写历史。回滚会将早期版本作为新版本重新发布。

stateDiagram-v2
    [*] --> draft: upload
    draft --> pending_review: submit for review
    pending_review --> active: approved
    pending_review --> draft: rejected
    draft --> active: publish
    active --> deprecated: supersede
    deprecated --> active: republish
    active --> archived: archive
    draft --> trashed: move to trash
    active --> trashed: move to trash
    archived --> trashed: move to trash
    trashed --> draft: restore
    trashed --> active: restore
    trashed --> [*]: scheduled purge after 72h

回收站不是带延迟的删除按钮。被移入回收站的文档会立即从所有检索面消失——HQ、REST、MCP——任何针对它的 AI Search 命中都会被实时数据库检查拒绝。72 小时后，定时任务清除规范内容及其历史对象，而审计轨迹保留。

开发

npm install
npm run typecheck && npm run lint && npm test

测试通过 @cloudflare/vitest-pool-workers 在真实 Workers 运行时中运行。集成测试每次运行都会将真实迁移应用到基于 Miniflare 的 D1，并且一组源码检查测试会在构建失败时触发，例如，如果添加了没有权限门禁的新管理路由。

要在本地运行服务，请参见 LOCAL-DEVELOPMENT.md。

安全

请勿为安全问题创建公开 issue——请参见 SECURITY.md 了解私下报告方式。

核心主张是，一个完全被攻破的低权限代理，即使拥有有效凭证，仍然无法读取、修改或销毁其权限范围之外的任何内容，也无法提升至更强的身份权限。威胁模型说明了这一点的依据；安全假设则说明了其边界所在。

该代码库已经过内部对抗性审查，每项发现都配有回归测试，并验证了这些测试在存在漏洞的代码上确实会失败。但这并不能替代独立渗透测试，也不代表该系统完全没有缺陷。

未实现的功能

明确说明边界，而非暗示超出实际的能力：

• PDF 解析。 未接入经安全验证的 Worker 内 PDF 文本提取功能；请在上游先将 PDF 转换为 Markdown 或纯文本。

• 临时角色与权限编辑。 角色已完整建模并预置，代理创建时会授予相应权限，但不存在事后编辑这些权限的管理界面。

• 管理列表视图，用于事实、产品、计划、服务和策略。创建和更新功能已具备；但分页式的“列出所有 X 类型”功能尚未实现。

• 缓存层。 有意不实现。AI 搜索自身的响应缓存已被禁用，因为其缓存键约定涉及按代理分类和领域过滤，而这一点没有文档说明——缺少该文档，就无法证明“一个代理的缓存结果绝不会被另一个不同权限范围的代理获取”。

• 批量操作。 不支持批量发布、批量删除或批量清理。

许可证

源码可用——专有软件，非开源软件。

本仓库采用 Xfeatures 专有软件许可证，而非 MIT、Apache、GPL 或任何 OSI 批准的开源许可证。简而言之：

完整条款，包括安全研究例外条款以及如何申请商业许可证，请参阅 LICENSE。