TestGraph

实验性 AI 原生体验图谱，用于在 AI 助手之间共享、可验证的记忆。

状态： 正在积极推进的预发布研究系统。该架构和 MCP 工作流已在多个 AI 客户端上进行过测试，但该项目尚未作为稳定的生产服务或 API 呈现。

TestGraph 将人工评审和 AI 推导出的结构存储为持久化的知识图谱，同时将证据、出处和服务器可验证的执行与模型的断言相分离。它的设计目标在于让不同 AI 系统能够在无需预先指定完整领域 schema 的情况下，对同一份知识做出贡献并复用。

项目目标

1. Schema 涌现： 为几个 AI 提供不熟悉的体验，无须预先设计类别即可获得有价值的结构。

2. 受控异议： 相互矛盾的分类通过证据、置信度和服务器用户认可收敛，而非来回摇摆。

3. 真实执行： 除非服务端确实认可，否则模型不能声称某个发现、扩增或合并已经发生。

4. 调用方 AI 能力： TestGraph 有目的地将调用方 AI 作为其语义与发现引擎。调用方 AI 应将其推理、检索和工具能力用于陌生主题，并推导出有用的结构和关联，回退到 TestGraph 为其定义的领域特定形式之。在 TestGraph 提供稳定的图谱原语、持久化和服务器端验证的同时，调用方 AI 提供开放式智能。

这些目标是针对 TestGraph 架构和测试的验收标准，而非仅仅提供给单一 AI 客户端的指南。

Related MCP server: Graph-Mem MCP

标准词汇表

评审被存储在稳定的 subject_type_id 值上，而非 DNS 风格路径。灵活的输入通过规范化规则的主题类型、规范术语和全局唯一别名来解析；大小写、标点、所有格和寻常复数均经由规则进行归一化。请在字典未命中和启用 CLI 参数之后允许。

不存在于词典 中的类型可允许创建为临时条目。

分类是一个独立的元数据层。例如，ferry belongs_to transportation 改进了广泛运输搜索，但未更改 ferry 评审在何地存储。review 是记录类型，而非词汇节点。可重用的结构化字段拥有自身的稳定 ID 和别名，并可附加至多个主题类型。

自迁移 0009_flat_standard_vocabulary 起，仍保留原有的 v2 概念/评审数据，但又将用户、 OAuth 状态、功能凭据及其他身份验证数据完整入手。

本地设置

1. 创建 Python 3.11+ 虚拟环境。

2. 安装依赖项：

pip install -r requirements.txt

3. 将 .env.example 复制为 .env，并使用私有值替换每一个占位符机密。

4. 执行迁移：

alembic upgrade head

5. 加载 schema 和演示身份：

python -m scripts.seed

6. 启动应用：

python run.py

打开 http://127.0.0.1:8000 和 http://127.0.0.1:8000/docs。

请勿在本地开发环境之外重新使用示例或开发凭据。密钥、 API 调用凭据、 OAuth 连接代码和所有者标识符绝不能提交到代码仓库中。

MCP 与 OAuth

TestGraph 预防一个仅工具模式的 MCP 程序。当前多模型集成可在 /v2 环境下获得体验。生产系统连接使用 OAuth 2.1 Authorization Code + PKCE。连接成功的 AI 会获取一个短期作用域的；它不会获得连接代码、 API 密钥或 TestGraph 所有者 ID。

MCP 支援评审搜索/获取/保存操作，以及多模型实现所用到的更新类型图/一致性功能。由于该实验界面仍在演化，请以部署的 MCP schema 为权威内容。

在任何部署之前，请配置一个长且随机的 OAUTH_CONNECTION_CODE、设置合适的 OAUTH_OWNER_USER_ID，并确保生产机密仅存在于部署环境之中。

导入开放 UCI 食谱评价

在完成迁移并运行 python -m scripts.seed 后，请执行：

python -m scripts.import_uci_recipe_reviews --representative-reviews 100 --load

这将下载 CC BY 4.0 UCI 数据集，并从 100 个食谱中为每个食谱选择一个证据丰富的评论。它会把转换后的记录写入 data/uci_recipe_reviews_100.json，然后载入到已经配置好的数据库中。重新运行是安全的；稳定的源 ID 可防止重复。

原始评论文本、评星（0–5 星）、时间戳、投票数、状态、记录 ID、许可证和署名信息都会保留在出处中。导入器会标记关于风味、粘度、时间、食材可用性、难度、重复意愿及修改的命名描述。每个推导出的信息都配有验证来源的话语；没有明说，则保留为 null。

无需重新下载和重新生成，可直接加载已压缩的包：

python -m scripts.import_uci_recipe_reviews --load-bundle data/uci_recipe_reviews_100.json

开发数据重置

在 /development/reset 中，有读取保护的重置页面。它默认处于隐藏状态并返回 404，除非显式开启：

ENABLE_DEVELOPMENT_RESET=true

该页面会删除 v1/v2 review 和知识数据，同时保留用户、 schemas 、OAuth 连接以及能力凭据和反馈。**** 同时**.

在公共环境中，必须保持禁用。

测试

pytest -q

除非完整测试套件针对发布提交运行通过，且部署就绪检查成功，否则不可进行公开发布。参见 RELEASE_CHECKLIST.md。

Railway 部署

1. 将仓库推送到 GitHub。

2. 从 GitHub 仓库创建 Railway 项目。

3. 添加 PostgreSQL。

4. 引用 Postgres 服务中可得的 DATABASE_URL；请勿把预估的 Railway 引用作为明文字符串粘贴。

5. 配置所有生产环境变量，所有值需配置唯一且随机的随机数：

ENVIRONMENT=production
APP_SECRET=<random secret>
DEVELOPMENT_API_KEY=<long random key; development/admin use only>
CLIENT_API_KEYS={}
OAUTH_OWNER_USER_ID=<owner UUID>
OAUTH_CONNECTION_CODE=<long random connection code>
PUBLIC_BASE_URL=https://<your-domain>
ALLOWED_HOSTS=["<your-domain>","<railway-domain>"]
CORS_ORIGINS=["https://<your-domain>"]
ENABLE_DEVELOPMENT_RESET=false

railway.json 配置部署前迁移、利用 Railway 的 $PORT 启动 Uvicorn，以及服务就绪检查。

本项目在生产中通过 Railway 使用 postgresql:// URL 转换为 SQLAlchemy 的 postgresql+psycopg:// 形式，前提是可接受前端基于 Psycopg 1。若无法程序集选择一个某，必须能够识别出自己的问题。一个无法解析 PostgreSQL 的生产环境部署必须不启用 SQLite 的回退。

已实现架构

• 调用方 AI 能力作为开放的语义与发现引擎，服务器可作为验证和持久化层

• 稳定的扁平 subject_type_id，上下紧密度与引用一起

• 规范术语和别名

• 可编辑的类型关系，用于搜索而非存储地址

• 版本化 schema 注册表

• 自定义的，领域特定的 JSON/JSONB Pydantic 错误

• 草稿优先发布，并支持批准

• 作用域的客户端凭据

• 集中式读取策略

• 规范主题解析与版本校验的草稿编辑

• OAuth 2.1 认证与 PKCE、动态客户端注册、刷新 — token 轮换和作用域访问令牌

• MCP 端点，供经过持有令牌的 AI 访问

• 幂等性键

• 来源、同意、所有权与可见性

• 分别的 reviewers–reader 阅读相关，以及阅读器特定的相关

• 审计日志和软删除

• 请求 ID、一致的 JSON 错误、请求大小限制以及支持分页的端点

• Alembic 迁移

• 本地使用 SQLite ；生产返回 PostgreSQL

• 跨模型调节以及服务端成果记录的具体进展

安全读取和编辑规则

• 公开列表只输出 published 且状态为 public 的评审。

• 通过精确 ID 也可以获取一已发布但标记为 unlisted 的评审。

• 草稿和 private 的记录要求有相应的读取凭据。

• 标记为 aggregate_only 的节点永不作为单独评论返回。

• 在编辑或附加结构化知识之前，应先解析主题。

• 版本检查可保护并发草稿的编辑。

• 可选项客户端凭据必须使用唯一的、可撤销的机密，并就作用域范围最小化。

许可证

TestGraph 采用 GNU Affero General Public License v3.0（AGPL-3.0） 协议授权。相关细节见 LICENSE。

AGPL-3.0 允许本在续篇条款授权下自由、免费地使用、修改和处分，包括其网络使用权和“蕴涵”服务提供者依照 AGPL 发布修改所提供的职责。

如果 AGPL-3.0 无法满足您的需求，备选授权或更专注的 LICENSE 允许协商。要建立定制协议，请联系 testgraph@21dle.co.uk。

建议提交者阅读 CONTRIBUTING.md。任何贡献只可以在满足以下前提下被接受，确保项目能够保留自己可继续推出私有授权选项的能力。

将仓库公开之前

请先阅读 RELEASE_CHECKLIST.md 与 SECURITY.md。火出时分，执行秘密历史检查，确认公共数据边界，实现完整测试套件的通过，并确保在精确的发布提交状态上完成了一次干净的代码部署。