aif-normbase 0.1.19

Agent Information Field - Norm Repository

AIF (Agent Information Field)

对外产品称呼（暂定）：AIF — Agent 信息场平台（品牌确定后可调整；仓库与技术标识仍可保留 AIF）。

Interim customer-facing name (EN): AIF — Agent Information Field Platform.

基于组织符号学的 LLM Agent 协作治理基础设施。

项目状态

当前已包含可运行的 Normbase / EDA / MCP 适配层，并已提供发布形态：

• Python: aif-normbase（单包双入口：aif-mcp + aif-mcp-eda）
• Node wrapper: @langxai/aif-mcp（通过 npx -y @langxai/aif-mcp 调用）

架构定位

在 AIF 中，eda_agent 不只是一个普通业务 Agent，而是外部用户 Agent 的社会封装层：

• 外部 Agent 通过 MCP 接入后，会在鉴权与治理链路中映射到内部 agent_id。
• 内部 agent_id 进入 EDA 心理-规范模型（Belief / NormBinding / ValueWeight）后再执行检索、绑定与决策。
• 这使得“接入信息场”的外部 Agent，在系统内都以可审计、可治理的 EDA Agent 形态运行。
• Norms 为 Agent 定义“可预期行动空间（predictable action envelope）”：在空间内可预期、可解释、可审计；超出空间边界时，不确定性上升并需要治理回路介入。

Architecture Positioning (EN):

• eda_agent acts as a social-governance wrapper for external user agents.
• After MCP ingress, callers are mapped into internal agent identities and processed through the EDA model.
• This turns external agents into governable, auditable EDA agents within the information field runtime.
• Norms define a predictable action envelope: behavior inside the envelope is expected and auditable, while behavior outside it increases uncertainty and should trigger governance controls.

项目结构

aif/
├── aif_platform/             # 平台产品线（用户向：后端 server + 前端 web；与 security / dashboard 分工）
│   ├── server/               # Python 后端（api / services / models / db / schemas）
│   └── web/                  # 用户向前端（脚手架占位，见 aif_platform/web/README.md）
├── normbase/                 # 规范库核心模块
│   ├── api/                  # API 路由 (norms, retrieval, roles, fields, keys, compliance)
│   ├── services/             # 业务服务层 (norm/retrieval/role/field/key/compliance)
│   ├── models/               # 数据模型
│   ├── db/                   # 数据库 (schema.sql, connection)
│   └── schemas.py            # 统一请求/响应 Schema 入口
├── eda_agent/                # EDA Agent 模块
│   ├── api/                  # Agent API 路由
│   ├── services/             # 应用服务层 (agent/runtime/field/trace)
│   ├── infra/                # 基础设施适配 (llm, normbase_client)
│   ├── db/                   # EDA 持久化 schema/connection
│   ├── state.py              # EDA 状态管理 (Belief, NormBinding, ValueWeight)
│   └── engine.py             # 推理引擎 (E/D/A 组件)
├── integrations/mcp/         # MCP 适配层（Normbase-first, Stage 1）
├── integrations/mcp_eda/     # MCP 适配层（EDA-first, Stage 2）
├── dashboard/                # Web 管理界面
├── scenarios/                # 场景构建工具 + scenario_* JSON 数据
│   ├── build_seed.py         # 统一入口（支持 --init-scenario / --scenario-name）
│   ├── *_seed.py             # field / eda_agent / norm 落库脚本
│   └── scenario_*/           # 每个场景目录（README + field.json + eda_agent.json + norms.json）
├── ontology/                 # 领域本体与概念资产
├── docs/                     # 产品、部署、API 与治理文档
├── scripts/                  # 构建/发布/运维脚本
├── security/                 # 认证鉴权与安全相关模块
├── tests/                    # 测试用例
├── background/               # 规划与背景资料
├── docker-compose.yml        # 本地开发环境
├── pyproject.toml            # Python 包配置 (aif-normbase)
├── requirements.txt          # 依赖
└── README.md                 # 项目说明

模块说明

模块文档导航（建议先看）：

• aif_platform：aif_platform/README.md
• normbase：normbase/README.md
• eda_agent：eda_agent/README.md
• integrations：integrations/README.md
• integrations/mcp：integrations/mcp/README.md
• integrations/mcp_eda：integrations/mcp_eda/README.md
• integrations/openclaw：integrations/openclaw/README.md
• dashboard：dashboard/README.md
• scenarios：scenarios/README.md
• ontology：ontology/README.md
• security：security/README.md
• scripts：scripts/README.md
• tests：tests/README.md
• docs：docs/README.md

说明：

• README.md 关注项目总览与启动入口。
• 各模块 README.md 关注模块职责、接口与运行方式。
• 先阅读模块文档再进入 docs/ 深入运行手册，可减少上下文切换成本。

normbase

规范库核心，提供：

• ✅ 规范 CRUD 操作 (obligation/prohibition/permission)
• ✅ 检索：agent_role + field_ids 双通道 (RRF融合)
• ✅ 向量语义检索 (Qdrant)
• ✅ 版本管理 (norm_versions)
• ✅ 规范关系 (norm_relations)
• ✅ Redis 检索结果缓存（retrieve_cache_* + CacheService；见 normbase/services/retrieval_service.py）
• ✅ 规范萃取流水线（MVP：/api/v1/extraction 文本与批次文档萃取、过程 JSON；Dashboard Extraction 页草稿审核与激活）
• ⬜ 萃取扩展（设计 §9 阶段 4 进行中）：✅ 长文分块 + LLM 单次字符预算、✅ PDF 文本（PyMuPDF）、✅ 后台萃取（queued + ?background=true）；⬜ Word/Docling、⬜ 独立队列/多 worker、⬜ 分块合并策略增强
• ✅ MCP 适配（通过 integrations/mcp 暴露工具）

Schema 组织约定：

• 统一使用 normbase/schemas.py 作为请求/响应 Schema 入口。
• api 层不定义业务 Schema；仅引用 normbase.schemas。

详细说明见：normbase/README.md

eda_agent

EDA Agent 运行时 (Phase 6 完成)：

• ✅ E（认识论）信念管理 (Belief)
• ✅ D（义务论）规范绑定 (NormBinding)
• ✅ A（价值论）权重推理 (ValueWeight)
• ✅ 合规校验基础
• ⬜ 完整推理流程

详细说明见：eda_agent/README.md

技术栈

• FastAPI + PostgreSQL 16 + JSONB
• SQLAlchemy 2.0 (async)
• Qdrant (向量检索)
• Redis (缓存 - 集成中)
• LLM: OpenAI / Anthropic 等（共享包 llm；扁平环境变量 LLM_PROVIDER、LLM_API_KEY、LLM_MODEL 等，见 .env.example）

快速开始

# 创建并激活 conda 虚拟环境（首次）
conda create -n aif python=3.11 -y
conda activate aif

# （可选）使用 venv 而不是 conda
# python -m venv .venv
# .venv\Scripts\activate

# 启动本地开发环境 (PostgreSQL + Qdrant + Redis)
docker-compose up -d

# 安装依赖
pip install -r requirements.txt

MCP（本地开发）

# 直接启动 MCP 适配器（stdio）
python -m integrations.mcp.server --transport stdio

# EDA-first MCP（运行时入口）
python -m integrations.mcp_eda.server --transport stdio

MCP（分发调用）

# Python 入口（Normbase-first）
uvx --from aif-normbase aif-mcp --transport stdio

# Python 入口（EDA-first）
uvx --from aif-normbase aif-mcp-eda --transport stdio

# Node 包装入口
npx -y @langxai/aif-mcp

说明：

• 当前 aif-mcp 为稳定入口（Normbase-first）。
• 当前 aif-mcp-eda 已提供 EDA runtime 工具入口（perceive / bind_norms / decide / execute / get_traces），并通过 API key 绑定到对应 eda_agent。

MCP 探针（Dashboard MCP Info）

默认推荐给 MCP 客户端使用 stdio 模式；如果需要让 Dashboard 的 MCP Info 显示实时状态，建议额外启动一个 streamable-http 的探针进程：

# 探针进程（HTTP）
python -m integrations.mcp.server --transport streamable-http

并将 Dashboard 的 MCP_BASE_URL 指向该进程（示例）：

MCP_BASE_URL=http://127.0.0.1:8000

验证方式：

• 打开 Dashboard 的 MCP Info 页面，live=true 且可列出 tools。
• 或调用 GET /api/mcp/info 查看实时探针结果。

启动 API Server

# Normbase API 端口 8001
python -m normbase.main

API 文档：http://localhost:8001/docs

启动 EDA Agent Server

# EDA Agent API 端口 8002
python -m eda_agent.main

EDA API 文档：http://localhost:8002/docs

启动 Web 管理界面（Dashboard）

# AIF Technical Dashboard（默认端口 8010）
python -m dashboard.main

管理界面：http://localhost:8010

开发计划

详见 background/plan.md

阶段进度

Phase	内容	状态
Phase 1	基础骨架 + CRUD + 管理UI	✅
Phase 2	检索核心 + 向量库 + 缓存	✅
Phase 3	萃取流水线 + 审核UI	✅
Phase 4	MCP集成 + API鉴权	✅
Phase 5	打磨验证 + Demo	⬜
Phase 6	EDA状态管理 + 持久化	✅
Phase 7	EDA推理引擎核心	⬜
Phase 8	价值排序 + 合规校验	⬜
Phase 9	EDA端到端集成	⬜

说明：Phase 3 指「萃取 API + 过程 JSON + Dashboard 审核」的 MVP；与 docs/norm-extraction-design.zh.md §9 阶段 4（解析管道、异步、长文/LLM 上下文）是后续增量，不在本表 Phase 3 范围内。

API 端点

• GET / - 健康检查
• GET /api/v1/norms - 规范列表
• POST /api/v1/norms - 创建规范
• GET /api/v1/norms/{id} - 规范详情
• PUT /api/v1/norms/{id} - 更新规范
• DELETE /api/v1/norms/{id} - 删除规范
• GET /api/v1/retrieve - 规范检索

测试数据

测试种子脚本位于 scripts/dev/:

• seed_norms_api.py - EU AI Act 测试规范（API 写入，支持外部种子文件）
• seed_norms_db.py - EU AI Act 测试规范（直写数据库）