元枢把分散在数据库、业务文档、规则、函数和系统接口中的知识，组织为统一的业务语义。对象与关系描述业务结构，数据绑定连接业务事实，Logic 和 Action 提供计算与执行能力，发布版本则为应用与 Agent 提供可追踪的业务上下文。

你可以从文档或数据资产开始，让 AI 提取候选对象、属性与关系，再经过映射、人工审核和真实数据验证，形成可发布的本体；也可以手工建模或导入已有模型。

适合需要统一业务语义、构建基于业务数据的 Agent，或复用企业规则与执行能力的团队。AI 构建与对话运行需要配置可用模型服务；手工建模、版本管理和本地数据接入可先独立体验。

数据连接器包括 SQLite、MySQL、PostgreSQL、SQL Server、Oracle、S3 / MinIO、FTP / SFTP、REST API 和 Kafka。Kafka 当前用于连接探测、主题元数据与有限消息采样。模型交换支持 OWL / RDF、Turtle、JSON 和 Excel，具体入口与格式见使用指南。

以下页面来自当前源码运行的独立设备运维演示环境。Agent 和技能示例展示草稿配置，对话调试需配置实际模型凭证。

把设备、传感器、检修工单和人员组织为可浏览的对象与关系。

页面入口与操作顺序见使用指南，截图场景与更新方式见截图说明。

flowchart LR
    Sources["数据库 / 文档 / API"] --> Build["AI 辅助构建 / 手工建模"]
    Build --> Ontology["对象 / 属性 / 关系"]
    Sources --> Grounding["数据绑定 / 映射 / 质量"]
    Grounding --> Ontology
    Ontology --> Runtime["Logic / Action Runtime"]
    Ontology --> Services["REST API / MCP / SDK"]
    Runtime --> Services
    Services --> Apps["Agent / 流程 / 业务应用"]
    Governance["权限 / 版本 / 审批 / 审计"] -.-> Ontology
    Governance -.-> Runtime
    Governance -.-> Services

前端使用 Vue 3、TypeScript、Vite、Pinia 和 Ant Design Vue；图谱与流程使用 d3-force 和 Vue Flow。后端使用 FastAPI、SQLAlchemy 与 Pydantic，元数据默认存储在 SQLite，也可配置 MySQL。代码工作区集成 code-server。

AI 负责理解与生成候选结果，程序负责结构校验、权限检查和执行，用户在审核发布与行动授权时确认关键业务决策。

• Python 3.11+。
• Node.js 22.13+（22.x）或 24+，npm。当前锁定依赖也支持 Node.js 20.19+（20.x）；版本要求同时考虑 Vite 8 与 ESLint 10。
• 完整启动脚本使用 code-server。Linux / macOS 未安装时脚本会尝试联网安装；Windows 需提前安装并确保命令在 PATH 中。
• Linux / macOS 启动脚本还需 curl、lsof。导入旧版 .doc / .xls / .ppt 文件时另需 LibreOffice soffice。

本地体验可以使用 SQLite，无需先部署 Redis、Neo4j 或对象存储。外部数据库、存储与 AI 能力使用时再配置对应服务。

Linux / macOS：

git clone https://github.com/fuyuxiang/ontology.git
cd ontology

python3 -m venv backend/venv
backend/venv/bin/python -m pip install -r backend/requirements.txt

npm --prefix frontend ci
cp backend/.env.example .env

Windows PowerShell：

git clone https://github.com/fuyuxiang/ontology.git
cd ontology

py -3 -m venv backend\venv
.\backend\venv\Scripts\python.exe -m pip install -r backend\requirements.txt

npm --prefix frontend ci
Copy-Item backend\.env.example .env

修改刚复制的 .env，至少设置以下内容：

DATABASE_URL=sqlite:///./ontology.db

# 使用随机生成的密钥
SECRET_KEY=replace-with-a-random-secret

# 首次创建 admin 必填：至少 8 位，包含大写、小写字母和数字
ADMIN_INITIAL_PASSWORD=replace-with-your-own-password

CORS_ORIGINS=http://localhost:5177,http://127.0.0.1:5177

# 使用 AI 构建与对话时填写
LLM_BASE_URL=https://your-llm-endpoint/v1
LLM_API_KEY=
LLM_MODEL=your-model-name

管理员用户名为 admin，密码为你设置的 ADMIN_INITIAL_PASSWORD。系统没有默认管理员密码，启动配置也不会重置已有账号的密码。

完整变量模板见 backend/.env.example。工作区与本地 SQLite 数据源目录默认使用仓库下的 workspace/ 和 local-data/。需要保存外部连接凭据时，建议设置稳定的 CREDENTIAL_ENCRYPTION_KEY，详见使用指南。

Linux / macOS：

./start.sh

Windows：

.\start.bat

首次启动自动建表、迁移和创建管理员。编辑器密码由 CODE_SERVER_PASSWORD 指定，或保存到首次启动生成的 .code-server-password 文件。

端口可在根目录 .env 中通过 BACKEND_PORT、FRONTEND_PORT、CODE_SERVER_PORT 修改。启动日志为 backend.log、frontend.log 和 code-server.log。停止服务使用 ./stop.sh，Windows 使用 .\stop.bat。

启动脚本用于本地开发与体验。已有依赖可设置 SKIP_DEPENDENCY_INSTALL=1 跳过安装；部署配置和服务访问范围见使用指南。

1. 登录后进入「数据接入」，配置业务数据源；在「资产目录」登记表或文档。
2. 在「本体列表」创建本体，选择手动、模板、文档或资产构建。
3. 按「对象定义 → 数据映射 → 最终审核 → 验证发布」完成建模，检查主键、字段映射与关系。
4. 添加业务函数和行动，将计算与操作绑定到业务对象。
5. 在「业务技能」编写操作指引、选择依赖并测试，发布可复用的技能版本。
6. 在「智能体应用」固定已发布本体与技能版本，配置对象范围和模型；调试通过后发布，再通过 API 接入应用。

Agent 行动默认模拟执行。确认模式下，业务写入需要有权限的登录用户授权；公开 Agent 接口不能代替登录用户确认写操作。详细行为见发布与执行规则。

仅运行 API 与前端时，可以分别启动，不必先启动代码编辑器。先完成上述依赖安装与 .env 配置。

# 终端 1：后端
cd backend
venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8001 --reload

# 终端 2：前端
cd frontend
npm run dev

Windows 将 Python 命令替换为 venv\Scripts\python.exe。前端代理、页面路由与目录见前端开发指南。

提交前按改动范围运行：

# 后端回归：使用独立数据库、工作区和本地协议测试数据
cd backend
venv/bin/python -m pip install -r requirements-dev.txt
venv/bin/python -m pytest -q

# 前端状态回归、类型检查、构建及静态检查
cd ../frontend
npm run test:ui-state
npm run build
npm run lint

欢迎通过 Issues 报告问题、讨论设计，通过 Pull Requests 提交改进。PR 请说明问题、行为变化与验证结果；涉及新能力时同步更新文档，两种语言保持一致。

本项目原创代码采用 PolyForm Noncommercial License 1.0.0，允许许可证规定的非商业用途。超出许可范围的商业用途需事先取得另行授权，请联系仓库维护者。

第三方组件保留各自的许可证。此前已按其他许可证授予的权利不受本次更新影响。