Ontexus v0.2.1

Ontexus v0.2.1

在 v0.2 基础上的稳定性 / 修复版本，重点是首次配置模型和 Agent Runtime 的可靠性。

关键修复

• 模型 API Key 跨容器解密失败 — docker-compose.v2.yml 下 API 服务（backend）与实际调用模型的 worker（agent_worker）是两个独立容器；此前 ENCRYPTION_KEY 留空时每个容器各自生成随机密钥，导致用户在前端配置模型、测试成功后，Agent 实际调用时必然解密失败且报错难以定位。现在 .env.example 提供统一的默认密钥，所有容器共享同一份 .env，加解密天然一致；生产环境仍强制要求替换为真实密钥，行为与 SECRET_KEY 一致。
• 图谱授权（Neo4j）验证 — 复核了运行时工具的授权拒绝路径，修复了一个导致测试失真的过期 fixture（缺少 Task 20 新鲜度标记），确认真实授权逻辑本身没有问题。
• 长期记忆（Chroma） — 修复了一个从未真正生效的 mock 测试（此前 patch 了一个代码实际不会调用的函数），确认 Chroma 集成本身没有产品代码缺陷。
• PostgreSQL/MySQL 双方言 schema 可移植性 — 修复 governed_turn_plans.decided_by_user_id 缺失 VARCHAR 长度、两处 JSON 列在 MySQL 下非法字面量默认值的问题；补全了跨方言集成测试的 fixture（此前因缺表而从未真正跑通）。
• 测试基础设施 — 修复两处因 SQLAlchemy 2.0 默认遮罩连接串密码（str(url) → ***）而从未真正执行过的真实数据库测试。

自 v0.2 以来的新增能力

• Agent 思考过程动态展示 — 回答生成中的实时流式输出与工具调用状态提示,取代静态的"思考中"占位。
• 可配置的 Tool Round Limit — 每个 Agent 版本可在前端配置最大工具调用轮数（1-20，默认 5），并提示最大支持轮数。
• 本体关系多跳遍历工具 — 新增可配置遍历深度的实体关系查询工具。
• 外部工具绑定 UI 统一 + Skill 上传/扫描 + browser_use 适配器。
• 前端国际化 — Pipelines、Ontologies 等页面补全中英双语。
• Legacy Logic/Action 数据向 v2 表的镜像修复。

快速开始（不变）

git clone https://github.com/jingw2/ontexus.git
cd ontexus
git checkout v0.2.1
cp .env.example .env
docker compose -f docker-compose.v2.yml up --build

---

Ontexus v0.2（原始发布说明）

License updated (2026-09-10): Ontexus is now licensed under PolyForm Noncommercial 1.0.0 — free for personal, research, education, and nonprofit/government use; commercial use requires a separate license from the copyright holder. Previous references to "MIT" in this repo were incorrect (no LICENSE file existed until now).

nano-ontoprompt 正式更名为 Ontexus。 Ontexus = Ontology + Nexus —— 以 Ontology 为核心，把企业的数据、关系、上下文、逻辑、Action 和 Agent 连接起来的语义枢纽（Data / Knowledge → Ontology → Context → Logic / Actions → Agent）。详见 README.md 的品牌说明。

自 v0.1 以来累计 570+ 次提交，新增了一个完整的 Agent Runtime 执行层，并对治理、安全与数据集成能力做了大量强化。

---

核心新增：Agent Runtime（Agent 执行引擎）

v0.1 的 Ontology 构建能力之上，现在可以让 Agent 基于已发布的 Ontology 真正执行任务：

• 会话式 Agent 应用 — 持久会话、可靠 SSE 流式回复（断线重连/事件重放）、澄清追问、动作审批流程；会话标题根据首条提问自动生成
• 治理化工具网关（Tool Gateway） — Agent 对 Ontology 的每一次读取都经过发布索引、run/data 授权校验，产出可观测的引用溯源（不暴露思维链）
• 外部工具绑定 — 治理化 Web Search 适配器（SSRF 安全防护、跨域重定向脱敏、响应体硬上限）、URL 与标题净化
• Agent 记忆 — 短期/长期记忆抽取与向量化召回，按 Agent 独立配置
• 执行调和（Reconciliation） — 当一次工具/动作执行结果未知（丢失结果、丢失 fence、结果不确定）时，由管理员基于证据确认外部副作用为成功/未执行/需重试；系统绝不自动重放。详见 Agent Reconciliation Guide
• 心跳保活 — 长时间运行的真实模型调用期间，后台心跳线程持续续约；主 session 不可用时用新 session 兜底标记失败，避免任务永久卡在 running

Business Journeys：真实模型治理验收

新增一套面向企业客户的端到端验收框架，覆盖供应链、财务、信贷三大业务域：

• 真实 DeepSeek 模型调用（非 mock）+ 真实浏览器驱动的 Agent 创建与对话流程
• 完整证据链：Preparation → 三次真实模型调用（ontology / agent_initial / agent_final）→ 高风险动作审批（approved / rejected / expired 三分支，均含真实哈希与回执）→ 只读验证
• 专用网关身份（gate identity）强制隔离：仅限配置的专用账号可写入/读取准备证据，普通用户即使猜中 run_id 也无法读取他人证据（本轮修复的一个真实越权问题）
• 一键跑通：bash scripts/run_business_journey_gate.sh（需要 DEEPSEEK_API_KEY）

治理与安全强化

• Ontology 发布生命周期 — draft → created → published 三态流转，发布产出不可变 release；已发布本体支持"发布新版本"
• 数据保留与法定保全（Retention & Legal Hold） — 按策略版本 + CAS 并发控制自动清理，法定保全期内的数据强制豁免；保全范围覆盖 session/turn 及其脱敏/删除步骤，而非仅 Turn 本身
• 账号与会话安全 — 账号吊销、浏览器 refresh token 家族轮换、API 安全响应头加固
• Ontology 写路径收口 — 所有本体写操作切至治理化路径，直接 SQLAlchemy 写入入口全部关闭
• 原始 Logic/Action 定义编辑 — 支持直接 PATCH 修改规则与动作定义

数据集成增强

• 增量刷新管道 — 独立的调度/轮询/事件/重放四类 Celery worker，签名 webhook、幂等收件箱、可取消安全点
• 跨数据集关系推断增强 — 备用键匹配（如文档中提到的公司名直接连到 Supplier 实体）、EntityInstance 概念/实例分离（Entity 表仅存概念元数据，关系在概念级连接，行级实例单独建模）

技术栈更新

新增: Celery 多队列 worker 拓扑（agent / refresh / housekeeping 等独立 profile）
      OAuth 2.0 + PKCE（Agent 委托凭证）
沿用: FastAPI + SQLAlchemy + Alembic · PostgreSQL + MinIO + Neo4j + ChromaDB
      React + Vite + Tailwind CSS + Cytoscape.js

所有新增外部依赖（Neo4j/MinIO/ChromaDB/Redis）继续保持可选、优雅降级。

Ontexus v0.2

License updated (2026-09-10): Ontexus is now licensed under PolyForm Noncommercial 1.0.0 — free for personal, research, education, and nonprofit/government use; commercial use requires a separate license from the copyright holder. Previous references to "MIT" in this repo were incorrect (no LICENSE file existed until now).

Ontexus v0.2

nano-ontoprompt 正式更名为 Ontexus。 Ontexus = Ontology + Nexus —— 以 Ontology 为核心，把企业的数据、关系、上下文、逻辑、Action 和 Agent 连接起来的语义枢纽（Data / Knowledge → Ontology → Context → Logic / Actions → Agent）。详见 README.md 的品牌说明。

自 v0.1 以来累计 570+ 次提交，新增了一个完整的 Agent Runtime 执行层，并对治理、安全与数据集成能力做了大量强化。

---

核心新增：Agent Runtime（Agent 执行引擎）

v0.1 的 Ontology 构建能力之上，现在可以让 Agent 基于已发布的 Ontology 真正执行任务：

• 会话式 Agent 应用 — 持久会话、可靠 SSE 流式回复（断线重连/事件重放）、澄清追问、动作审批流程；会话标题根据首条提问自动生成
• 治理化工具网关（Tool Gateway） — Agent 对 Ontology 的每一次读取都经过发布索引、run/data 授权校验，产出可观测的引用溯源（不暴露思维链）
• 外部工具绑定 — 治理化 Web Search 适配器（SSRF 安全防护、跨域重定向脱敏、响应体硬上限）、URL 与标题净化
• Agent 记忆 — 短期/长期记忆抽取与向量化召回，按 Agent 独立配置
• 执行调和（Reconciliation） — 当一次工具/动作执行结果未知（丢失结果、丢失 fence、结果不确定）时，由管理员基于证据确认外部副作用为成功/未执行/需重试；系统绝不自动重放。详见 Agent Reconciliation Guide
• 心跳保活 — 长时间运行的真实模型调用期间，后台心跳线程持续续约；主 session 不可用时用新 session 兜底标记失败，避免任务永久卡在 running

Business Journeys：真实模型治理验收

新增一套面向企业客户的端到端验收框架，覆盖供应链、财务、信贷三大业务域：

• 真实 DeepSeek 模型调用（非 mock）+ 真实浏览器驱动的 Agent 创建与对话流程
• 完整证据链：Preparation → 三次真实模型调用（ontology / agent_initial / agent_final）→ 高风险动作审批（approved / rejected / expired 三分支，均含真实哈希与回执）→ 只读验证
• 专用网关身份（gate identity）强制隔离：仅限配置的专用账号可写入/读取准备证据，普通用户即使猜中 run_id 也无法读取他人证据（本轮修复的一个真实越权问题）
• 一键跑通：bash scripts/run_business_journey_gate.sh（需要 DEEPSEEK_API_KEY）

治理与安全强化

• Ontology 发布生命周期 — draft → created → published 三态流转，发布产出不可变 release；已发布本体支持"发布新版本"
• 数据保留与法定保全（Retention & Legal Hold） — 按策略版本 + CAS 并发控制自动清理，法定保全期内的数据强制豁免；保全范围覆盖 session/turn 及其脱敏/删除步骤，而非仅 Turn 本身
• 账号与会话安全 — 账号吊销、浏览器 refresh token 家族轮换、API 安全响应头加固
• Ontology 写路径收口 — 所有本体写操作切至治理化路径，直接 SQLAlchemy 写入入口全部关闭
• 原始 Logic/Action 定义编辑 — 支持直接 PATCH 修改规则与动作定义

数据集成增强

• 增量刷新管道 — 独立的调度/轮询/事件/重放四类 Celery worker，签名 webhook、幂等收件箱、可取消安全点
• 跨数据集关系推断增强 — 备用键匹配（如文档中提到的公司名直接连到 Supplier 实体）、EntityInstance 概念/实例分离（Entity 表仅存概念元数据，关系在概念级连接，行级实例单独建模）

技术栈更新

新增: Celery 多队列 worker 拓扑（agent / refresh / housekeeping 等独立 profile）
      OAuth 2.0 + PKCE（Agent 委托凭证）
沿用: FastAPI + SQLAlchemy + Alembic · PostgreSQL + MinIO + Neo4j + ChromaDB
      React + Vite + Tailwind CSS + Cytoscape.js

所有新增外部依赖（Neo4j/MinIO/ChromaDB/Redis）继续保持可选、优雅降级。

---

快速开始

git clone https://github.com/jingw2/ontexus.git
cd ontexus
cp .env.example .env
docker compose -f docker-compose.v2.yml up --build

详见 README.md / README_zh.md。

nano-ontoprompt v0.1

nano-ontoprompt v0.1

nano-ontoprompt 是一个受 Palantir Foundry 启发的本体工程平台，支持从多源异构数据自动构建结构化知识图谱（Ontology）。

---

核心功能

两条构建路径

路径	适用场景	结果
Pipeline Mapping	结构化/半结构化数据（CSV/XLSX/JSON/XML/PDF）	精准实体+关系图谱，支持 FK 推断
简易 LLM 提取	非结构化文档，快速验证	LLM 直接生成实体列表

三种 Transform 路由

• Route A — 结构化数据（CSV/XLSX）→ Schema 映射 → 实体/关系
• Route B — 半结构化（JSON/XML）→ 展开 → 实体/关系
• Route C — 非结构化文档（PDF/Markdown/Word）→ LLM 结构化提取 → 实体/关系；有 LLM 时自动调用，否则规则降级

跨数据集关系推断

• FK 推断：精确匹配、点号列名归一化（supplier.id → supplier_id）、值格式容错（SUP-001 ↔ SUP001）
• 备用键推断：基于高基数非主键列（如公司名称）跨数据集连线，无需显式外键
• 典型效果：供应链 8 文件 → 1 pipeline → 249 节点 128 边，物流/采购单→供应商四种链路汇聚

逻辑规则 & 动作自动发现

自动从 Mapping 结果提取 Logic（Validation/State/Mapping/Inference）和 Action（Automation），并生成人类可读公式（如"库存状态 ∈ {正常, 超储, 预警}"）

图谱可视化

• Cytoscape.js cose 布局，支持节点点击跳转详情
• 无 Neo4j 时自动回退 SQLite 图数据
• 图谱切换从 6.5–10s 优化至 1.1–1.4s（ChromaService/Neo4j 共享连接 + 60s 不可用缓存）

安全与工程

• Curated 审批强制管理员权限
• 上传白名单扩展名 + 最大文件限制（默认 200MB）
• Cypher 词边界安全校验 + 强制 ontology_id 隔离
• 关键词搜索 ChromaDB 不可用时自动回退 SQL

---

技术栈

后端: FastAPI + SQLAlchemy + Celery/Redis + Alembic
存储: PostgreSQL（元数据）+ MinIO（文件）+ Neo4j（图谱）+ ChromaDB（向量）
前端: React + Vite + Tailwind CSS + Cytoscape.js

Neo4j/MinIO/ChromaDB 均为可选；全部支持优雅降级，仅 PostgreSQL 为必需依赖。

---

快速开始

git clone https://github.com/jingw2/nano-ontoprompt
cd nano-ontoprompt/backend
cp .env.example .env  # 配置数据库连接
alembic upgrade head
uvicorn app.main:app --reload --port 8000

# 另一终端
cd frontend && npm install && npm run dev

详细说明见 README.md / README_zh.md

---

测试验证

• 后端 302 单测全绿
• UI 验收 9/9 通过（test_data/eval_ui_acceptance.py）
• 双路径 × 三业务域（供应链/财务/医疗）端到端测试通过（test_data/test_two_paths_per_domain.py）
• deepseek-v4 真实 LLM 测试通过（test_data/test_real_models.py）