AI Native System
面向企业业务的 AI 原生框架,用于构建可审批、可验证、可恢复的 Agent 工作流。应用声明业务对象、关系、规则和动作,Agent 根据获准的事实和知识提出建议。涉及业务写入时,可信执行服务核对审批、OpenWorkProof 授权和源系统版本,再执行条件写入并核验签名回执。
六层架构 · 快速开始 · 接入应用 · 已实现与待完成清单
六层架构
| 层 | 负责什么 |
|---|---|
| 1. 基础设施 | PostgreSQL 持久化业务状态、发布、审计与检查点。采用行级租户隔离,并提供部署、观测和恢复演练入口 |
| 2. 数据 | Ontology 声明对象和关系。事实同步记录来源、版本、冲突与历史。文档经 LlamaIndex 分段,在 PostgreSQL 和 pgvector 中进行权限内的中文混合检索 |
| 3. 模型 | LiteLLM 路由生成和 embedding,记录调用用量与成本,并通过 Langfuse 上报脱敏观测数据 |
| 4. AI 中台核心 | Agent Runtime 和 LangGraph 编排阶段、审批与恢复。OpenWorkProof 绑定动作授权,可信执行服务通过 MCP 或 HTTP 执行并对账 |
| 5. AI 应用 | Python SDK、应用 API 和浏览器运行台承载问答、事实核查、审批、任务和证据 |
| 6. 企业业务应用 | 通过连接器读取业务系统的权威对象、关系和版本。获准的业务动作以条件写入、源端签名回执和可核验终态闭环 |
Agent 进程只持模型侧凭据,从可信服务收到按权限裁剪的上下文。业务凭据由执行服务持有。已批准动作在派发前复核当前事实、资源权限与签名,源端结果不确定时按原操作 ID 查询回执。 可编辑架构图 · Agent 隔离及恢复演练
快速开始
本地演示
在仓库根目录使用 Python 3.11–3.15。命令使用内置模型和合成配置,在临时 SQLite 数据库中运行,无需下载模型或提供密钥。
ai_native_tmp=$(mktemp -d)
python3 -B -m ai_native_system --db "$ai_native_tmp/framework.sqlite" demo
| 演示 | 可观察结果 |
|---|---|
single |
单 Agent 读取对象、引用规则提出建议。模拟审批后,对象 asset-1 由 pending 变为 verified |
collaboration |
两个 Agent 阶段通过结构化记录交接。模拟审批后,artifact-1 按关联对象状态由 draft 变为 published |
输出包含阶段状态、审批、事件和动作回执。日常 CLI 帮助可用 python3 -m ai_native_system --help 查看。
PostgreSQL 和 pgvector 集成验证
准备 uv、可用的 Docker Engine 和 Docker Compose。以下脚本创建独立临时测试库。实测环境使用 Python 3.12、PostgreSQL 18.7 和 pgvector 0.8.7。
uv sync --locked --all-extras --python 3.12 --no-build
uv run --locked --all-extras --python 3.12 python -B deployment/local-postgres/verify.py
uv run --locked --all-extras --python 3.12 python -B deployment/local-postgres/verify_p7.py
uv run --locked --all-extras --python 3.12 python -B deployment/local-postgres/verify_p8.py --only applications
第一个验证脚本检查连接池、事务、角色和向量距离。P7 覆盖文档入库、索引与文档权限、中文混合检索、引用和记忆。P8 验证参考应用沿用权限、检索与可信执行。 环境与锁定依赖 · P7 验收 · P8 验收
接入应用
- 以 Registry 样例 为起点,声明类型、关系、动作、角色和 Agent 阶段,通过
--registry加载。 - 以 P8 应用目录 和 P8 Registry 登记权限内问答、指定范围依据摘编或版本约束的业务动作。应用使用相应发布、文档与工具权限。 应用接入与 SDK 用法
- 接真实对象时,按 Ontology 发布定义映射源 ID、权威字段、关系及业务版本。使用只读接口验证规则的满足、不满足与依据不足,再按已验收的审批和源条件决定写入范围。 Ontology 与规则验收 · 首个只读试点清单
- 接入业务写动作时,分开配置请求者、审批者和执行服务,绑定动作、目标、规则与源版本。使用稳定的请求键和操作 ID 保持重试幂等,按原操作核对签名回执。 OpenWorkProof 授权 · MCP 条件写入与签名回执
Python 发行包与 MCP 服务端
主框架的 wheel 可从 GitHub 发布页 下载。安装后用 ai-native-system --db demo.sqlite demo 运行本地演示。接入 PostgreSQL 的环境可安装 wheel 的 postgres 和 integrations 可选依赖。
python -m pip install 'ai-native-system[mcp] @ https://github.com/dengyier/AI-Native-System/releases/download/v0.1.1/ai_native_system-0.1.1-py3-none-any.whl'
用 MCP 客户端以 stdio 启动 ai-native-system-mcp,并提供部署端 API 地址 AI_NATIVE_API_URL 与访问令牌 AI_NATIVE_API_TOKEN。服务端提供 list_applications 和 get_task 两种只读工具,使用当前 API 身份的授权。远端 API 使用 HTTPS,本机回环允许 HTTP。
支持 MCPB 0.4 与 UV 的客户端可安装 AI Native System MCPB,并按提示填入 API 地址和令牌。 官方 MCP Registry 条目
主框架及 MCP 服务端适用根目录的非商业使用许可。独立 Python SDK 和企业动作接口定义采用 MIT。 主框架与 MCP 许可 · MIT SDK
使用自己的 PostgreSQL 测试库
数据库管理员先在独立测试库启用 public schema 下的 pgvector 扩展,并将 ai_native schema 的所有权交给迁移角色。通过环境或密钥服务提供 AI_NATIVE_POSTGRES_MIGRATION_DSN 和最小权限的 AI_NATIVE_POSTGRES_DSN。下面命令使用已安装集成依赖的 Python 环境,模型配置通过 model_config 指向本地文件。
python -m ai_native_system --postgres migrate
python -m ai_native_system --postgres --registry fixtures/p8-registry.json \
--models "$model_config" serve --application-catalog fixtures/p8-applications.json
完成企业身份、权限和发布配置后,在本机访问 http://127.0.0.1:8789/console/。实际连接信息和密钥通过部署环境提供。 主库与迁移 · 身份、委派和发布 · 模型配置样例
中文混合检索
为请求主体授予实际知识索引的 read / knowledge-index / 索引ID 权限及当前文档的读取权限。执行迁移后,拥有词法索引读取权限的服务可用 --method hybrid 查询。问答及摘编应用可在目录条目加入 "retrieval_method": "hybrid"。默认配置使用精确向量检索。
python -m ai_native_system --postgres --tenant "$tenant" --models "$model_config" \
p7 search '“保留审批记录”' --method hybrid --actor "$actor"
中文词组与向量候选在同一授权范围内融合,完整条款号和带引号的连续短语支持精确匹配,返回正文前复核权限与原文引用。 索引授权与启用步骤
需要稳定复跑时,在应用发布草稿中显式固定知识索引和检索方法。用 release select 切换发布或回到仍有效的旧发布,系统在移动指针前校验目标索引的文档覆盖和模型配置。 固定发布与回滚
关键契约
| 模块 | 作用 |
|---|---|
| Ontology · Registry | 声明领域类型、关系、规则、应用与动作 |
| Runtime · 图编排 | 管理 Agent 阶段、结构化交接、人工审批和持久恢复 |
| 知识检索 · 中文词法查询 | 在同一索引与权限范围内召回并复验原文 |
| OpenWorkProof 执行校验 · 动作与回执契约 | 绑定审批、事实、权限和源端证据 |
| 应用 API · Python SDK · 运行台 | 访问获准的应用、任务、事实、审批与证据 |
Python 客户端可独立安装,通过 from ai_native_sdk import Client 连接已部署的应用接口。下载包、用法和只读示例见 SDK 文档。
在本地手动推进一个任务
ai_native_tmp=$(mktemp -d)
ai_native_db="$ai_native_tmp/manual.sqlite"
python3 -m ai_native_system --db "$ai_native_db" init
task_id=$(python3 -m ai_native_system --db "$ai_native_db" \
submit single asset-1 --actor requester --request-key manual-1 |
python3 -c 'import json, sys; print(json.load(sys.stdin)["id"])')
python3 -m ai_native_system --db "$ai_native_db" advance "$task_id"
python3 -m ai_native_system --db "$ai_native_db" decide "$task_id" approve --actor reviewer
python3 -m ai_native_system --db "$ai_native_db" advance "$task_id"
python3 -m ai_native_system --db "$ai_native_db" inspect "$task_id"
在独立的演示任务上,执行阶段可使用 advance … --simulate-timeout before-commit 或 after-commit 分别模拟提交前超时与提交后确认丢失。后续使用同一任务 ID 推进或查看,核对对象版本与回执。
可选的本机模型接入
设置 AI_NATIVE_MODEL_BASE_URL、AI_NATIVE_MODEL_NAME 和服务需要的 AI_NATIVE_MODEL_API_KEY,为本地演示接入支持 Chat Completions JSON 输出的模型。若已有 GGUF 模型与 node-llama-cpp,可先启动本机回环桥接。
AI_NATIVE_LLAMA_RUNTIME_DIR="/path/to/runtime" \
AI_NATIVE_GGUF_MODEL_PATH="/path/to/model.gguf" \
node local_model.mjs
将模型 URL 设为 http://127.0.0.1:8798/v1,模型名使用 GGUF 文件去掉扩展名的名称。企业模型路由、费用预算、观测和回退配置见 P5 模型接入验收。
当前验证范围
- P0–P8 已完成本地验收,包括真实 PostgreSQL 上的企业身份与权限、事实同步、OpenWorkProof 执行、源签回执、模型路由、断点恢复、知识检索和参考应用。
- P9 已在本地验证 Agent 隔离、双执行副本在 PostgreSQL 主备切换后的恢复、备份恢复、Ontology 权威只读查询、独立规则预览授权和中文混合检索。索引与检索策略固定、切换及回滚已用 PostgreSQL 18.7 和 pgvector 0.8.7 验收,包括旧索引覆盖不足时拒绝回滚,以及补齐后带审计切回。 P9 验收与复跑
- 计划内后续工作包括真实中文语料的质量与性能评测,以及指定企业环境的业务对照和受控写入试点。 P9 依赖与验收标准
许可
Copyright © 2026 dengyier. 原创代码、文档及架构图的知识产权由 dengyier 持有。主框架采用 AI Native System 非商业使用许可 v1.3。
主框架的个人学习和非商业使用免费。将主框架用于企业生产、客户交付、收费托管等商业用途,须事先获得单独书面授权。GitHub 平台内的查看与 Fork 适用平台服务条款,对外分发和再许可依项目许可执行。 商业授权联系 dengyier
由 dengyier 上传到 PyPI 的安装包可依许可第 4 条原样免费分发和镜像。
独立 Python SDK 和接入示例,以及企业动作接口定义及配套说明,可按 MIT 许可使用。 SDK MIT 许可 · 接口定义 MIT 许可
第三方依赖适用各自的上游许可证。 依赖与许可证
Metadata
Release files for ai-native-system 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ai_native_system-0.1.1.tar.gz | 399.2 kB | With provenance | Details for ai_native_system-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ai_native_system-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for ai_native_system-0.1.1-py3-none-any.whl |
Total release size: 690.0 kB
Release files / ai_native_system-0.1.1.tar.gz
| Download URL | ai_native_system-0.1.1.tar.gz |
|---|---|
| Size | 399.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e29a3437c1a0af16c33363fdeedb59849652df790d87a9cd0894f3b809a1cd90
|
|
BLAKE2b-256 checksum How to use checksums |
9b3843b23c2157e4323f136f827238c99eaf8ed31b28a37f835da9cad8fbb0d2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / ai_native_system-0.1.1-py3-none-any.whl
| Download URL | ai_native_system-0.1.1-py3-none-any.whl |
|---|---|
| Size | 290.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0e3249481b19a0247b53fa71463d34c74271b0d3b46de28fe5bc6928578b3e87
|
|
BLAKE2b-256 checksum How to use checksums |
970ddc35e3b0ced2e070e34d050b443d64f15ec5b922ac416eaf17b4148a50db
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for ai-native-system 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ai_native_system-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.