Repository avatar
AI Tools
v0.1.1
active

ai-native-system

io.github.dengyier/ai-native-system

Read authorized applications and task status from an AI Native System deployment.

Documentation

AI Native System (AINS)

面向企业业务的 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. 企业业务应用通过连接器读取业务系统的权威对象、关系和版本。获准的业务动作以条件写入、源端签名回执和可核验终态闭环

AI Native System 六层架构、Agent 隔离与可信执行边界

Agent 进程只持模型侧凭据,从可信服务收到按权限裁剪的上下文。业务凭据由执行服务持有。已批准动作在派发前复核当前事实、资源权限与签名,源端结果不确定时按原操作 ID 查询回执。 可编辑架构图 · Agent 隔离及恢复演练

快速开始

PyPI 安装

python -m pip install ainsys
ains --help

AINS 短包 ainsys 安装同版本的 ai-native-system 主框架,并提供 ains 和 ains-mcp 命令。 AINS 短包 · 主框架安装包 · 短包源码

本地演示

在仓库根目录使用 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 验收

接入应用

  1. 以 Registry 样例 为起点,声明类型、关系、动作、角色和 Agent 阶段,通过 --registry 加载。
  2. 以 P8 应用目录 和 P8 Registry 登记权限内问答、指定范围依据摘编或版本约束的业务动作。应用使用相应发布、文档与工具权限。 应用接入与 SDK 用法
  3. 接真实对象时,按 Ontology 发布定义映射源 ID、权威字段、关系及业务版本。使用只读接口验证规则的满足、不满足与依据不足,再按已验收的审批和源条件决定写入范围。 Ontology 与规则验收 · 首个只读试点清单
  4. 接入业务写动作时,分开配置请求者、审批者和执行服务,绑定动作、目标、规则与源版本。使用稳定的请求键和操作 ID 保持重试幂等,按原操作核对签名回执。 OpenWorkProof 授权 · MCP 条件写入与签名回执

Python 发行包与 MCP 服务端

主框架的 wheel 可从 GitHub 发布页 下载。安装后用 ai-native-system --db demo.sqlite demo 运行本地演示。接入 PostgreSQL 的环境可安装 wheel 的 postgres 和 integrations 可选依赖。

python -m pip install "ainsys[mcp]"

用 MCP 客户端以 stdio 启动 ains-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 许可

第三方依赖适用各自的上游许可证。 依赖与许可证

MCPB
https://github.com/dengyier/AI-Native-System/releases/download/v0.1.1/ai-native-system-0.1.1.mcpb
Install Command
# mcpb: https://github.com/dengyier/AI-Native-System/releases/download/v0.1.1/ai-native-system-0.1.1.mcpb