lzm-space 0.3.0

以空间为概念的统一存储、检索、编排引擎 - 像管理文件夹一样管理数据

lzm-space — Agent System 空间引擎基座

编码：utf8 | 作者：Lzm | 日期：2026-07-17

以"空间"为概念的统一数据编排基座——像管理文件夹一样管理数据，像仓库台账一样追踪出入库。

lzm-space 定位为 Agent System 开发基座库，不替代 ORM，而是提供一个比 ORM 更上层的抽象：空间（Space）。

一个 create_space() 即可获得：

• 信息柜（Cabinet） — 结构化数据，自动 Schema 演进
• 仓库（Warehouse） — 文件/对象存储（S3/MinIO/OSS）
• 知识库（Knowledge Base） — 文档切片 + 向量化 + 多策略搜索（RAG）
• 台账（Ledger） — 操作审计流水，不可篡改
• 权限（Permissions） — 空间级访问控制
• 清单（Inventory） — 空间资产实时盘点

---

核心理念

传统开发：为每个模块 建表 → CRUD → 配权限 → 接文件 → 加审计 → 搞缓存
          → 模块多了 → 每个都来一遍 → 管理爆炸

lzm-space：定义一个 Space → 自动获得 Cabinet + 仓库 + 知识库 + 台账 + 权限
           → 业务代码只需关心 put/get/search
           → 其他都是基建自动化的

概念	类比	后端	用途
空间（Space）	Linux 目录 / K8s Namespace	—	数据归属 + 权限边界
信息柜（Cabinet）	Excel 工作表	PostgreSQL（SQLAlchemy）	结构化 CRUD，自动 DDL
仓库（Warehouse）	S3 存储桶	MinIO / S3 / OSS	文件/大块数据存取
知识库（KB / RAG）	搜索引擎	Elasticsearch	语义搜索 / 向量检索
台账（Ledger）	银行流水	PostgreSQL（SQLAlchemy）	审计追踪 / 事件溯源
清单（Inventory）	库存盘点	Cabinet 数据实时聚合	空间资产统计
关联图（Graph）	知识图谱	远期规划	跨数据关联查询

---

技术架构

┌─ SpaceClient ──────────────────────────────────────────┐
│                                                        │
│   create_space() → 获得 Space 实例                      │
│     ├─ space.cabinet("users")  → 信息柜（自动 DDL）     │
│     ├─ space.upload("doc.pdf") → 仓库（S3/MinIO）       │
│     ├─ space.archive("文档")   → 知识库（ES + RAG）     │
│     ├─ space.search("查询")    → 多策略搜索             │
│     ├─ space.get_ledger()      → 台账审计               │
│     └─ space.inventory()       → 清单盘点（v0.3.0+）   │
│                                                        │
│   复杂查询走穿透：space.raw_sql("SELECT ... JOIN ...")  │
│                                                        │
├────────────────────────────────────────────────────────┤
│   SQLAlchemy 底座 (v0.3.0+)                            │
│   ├─ SQLAlchemy Core — 统一连接池/事务/方言             │
│   ├─ SchemaManager — 自动 DDL（lzm-space 独有）        │
│   ├─ CabinetBackend — 信息柜包装器                      │
│   └─ raw_sql() — 复杂查询穿透通道                      │
├────────────────────────────────────────────────────────┤
│   多后端适配器                                          │
│   ├─ PostgreSQL (asyncpg) — 信息柜 + 台账               │
│   ├─ Elasticsearch — 知识库/向量检索                    │
│   ├─ MinIO / S3 / OSS — 文件/对象存储                  │
│   ├─ Redis — 缓存/热数据                                │
│   └─ lzm-edsm — 事件驱动台账编排                       │
└────────────────────────────────────────────────────────┘

---

快速开始

安装

# 核心（零外部依赖）
pip install lzm-space

# 全部后端
pip install lzm-space[all]

# 指定后端
pip install lzm-space[s3,es,sql]

# + 插件系统（切片/向量化/提取/重排）
pip install lzm-space[all] lzm-plugin[all]

基础用法

import asyncio
from lzm.space import SpaceClient

client = SpaceClient()

async def main():
    # 1. 创建空间 = 创建一个完整的数据资源组
    space = await client.create_space("my-project")
    print(f"空间创建成功: {space.space_id}")

    # 2. 信息柜 — 结构化数据存取
    users = await space.register_cabinet("users", sql_backend)
    await users.put({"name": "Alice", "role": "admin", "dept": "eng"})
    # → 自动建列，无需预定义表结构

    result = await users.query() \
        .filter("role = 'admin'") \
        .group_by("dept") \
        .agg(cnt="count(*)") \
        .to_list()
    print(f"管理员分布: {result}")

    # 3. 仓库 — 文件存储
    await space.upload("设计稿.zip", file_data)

    # 4. 知识库 — RAG（需要 lzm-plugin）
    result = await space.archive_knowledge("文档内容...", extract_events=True)
    hits = await space.search("关于XX", strategy="hybrid")

    # 5. 台账 — 审计查询
    ledger = await space.get_ledger(limit=10)
    for entry in ledger:
        print(f"  [{entry.operation}] by {entry.actor}")

    # 6. 清单 — 资产盘点（v0.3.0+）
    inv = await space.inventory()
    print(f"信息柜分布: {inv}")

    # 7. 复杂查询 — 穿透到 SQLAlchemy
    results = await space.raw_sql(
        "SELECT * FROM cabinet_data WHERE _c_role = 'admin'"
    )

asyncio.run(main())

权限外套 — 快速集成到已有业务

如果已有 SQLAlchemy Model，直接用 Cabinet 包装即可获得权限管理 + 台账审计：

from lzm.space.cabinet import Cabinet, CabinetPermissionManager

# 已有业务模型
class Task(Base):
    __tablename__ = "tasks"
    id = Column(Integer, primary_key=True)
    space_id = Column(String(36))  # 只需添加 space_id 列
    title = Column(String(256))
    status = Column(String(32))

perm_mgr = CabinetPermissionManager()

# 1. 定义角色
await perm_mgr.define_role(session, "project-alpha", "manager", {
    "tasks": "lrwxdmau",   # 全部权限
})
await perm_mgr.define_role(session, "project-alpha", "viewer", {
    "tasks": "lr------",   # 只读
})

# 2. 分配角色
await perm_mgr.assign_role(session, "project-alpha", "alice", "manager")
await perm_mgr.assign_role(session, "project-alpha", "bob", "viewer")

# 3. 使用 Cabinet 查询（自动鉴权 + 空间过滤 + 台账）
cab = Cabinet(Task)

# alice（manager）— 正常读取
tasks = await cab.query(session, "alice", "project-alpha") \
    .where(Task.status == "active") \
    .to_list()

# bob（viewer）— 尝试写入 → CabinetPermissionDenied
# await cab.insert(session, "bob", {"title": "hack"}, "project-alpha")


---

## 项目状态

- **版本**：0.3.0
- **当前阶段**：v0.3.0 已完成（Cabinet 权限外套）
- **测试**：246+ 用例 ✅
- **v0.3.0 变更**：
  - **Cabinet 权限外套** — Cabinet 从存储适配器重构为权限包装器，对已有 SQLAlchemy Model 进行权限管理
  - **双层权限模型** — `space_roles`（角色权限模板）+ `space_members`（用户角色赋值），细粒度表级别控制
  - **自动台账** — 每次 Cabinet 操作自动记录 `cabinet_ledger`，支持审计追踪
  - **权限字系统** — 8 位权限字（l/r/w/x/d/m/a/u），灵活配置
  - **自动空间过滤** — query/update/delete 操作自动追加 `WHERE space_id = ?`
  - **链式查询** — `where()`/`order_by()`/`limit()`/`offset()`/`to_list()`/`first()`/`count()`
  - 新增 `cabinet/` 子模块，含 models/cabinet/permission/__init__

---

## 技术栈

| 层 | 技术 | 版本 |
|----|------|------|
| 语言 | Python | >=3.11 |
| 底座 ORM | SQLAlchemy (v0.3.0+) | >=2.0 |
| 编排引擎 | lzm-edsm | >=0.2 |
| S3 存储 | minio | >=7.0（可选） |
| ES 存储 | elasticsearch | >=8.0（可选） |
| Redis | redis-py | >=5.0（可选） |
| PG 驱动 | asyncpg | >=0.29（可选） |
| 插件系统 | lzm-plugin | >=0.2（可选） |

---

## 目录结构

lzm-space/ ├── README.md # 总纲 ├── pyproject.toml # 包配置 ├── src/lzm/space/ │ ├── init.py # 包入口 │ ├── core/ │ │ ├── node.py # SpaceNode, SpaceType │ │ ├── permissions.py # SpacePermissions, AllowEntry │ │ ├── path.py # 路径解析 │ │ ├── models.py # 数据模型 │ │ └── client.py # SpaceClient 统一入口 │ ├── cabinet/ # 权限外套（v0.3.0+） │ │ ├── init.py # 模块导出 │ │ ├── models.py # space_roles / space_members / cabinet_ledger │ │ ├── cabinet.py # Cabinet + CabinetQuery │ │ └── permission.py # CabinetPermissionManager + 鉴权逻辑 │ ├── manager/ │ │ ├── init.py │ │ └── space_manager.py # 空间 CRUD + 后端路由 │ ├── backends/ │ │ ├── init.py │ │ ├── base.py # StorageBackend ABC + DataDescriptor │ │ ├── es_backend.py # Elasticsearch 后端 │ │ ├── schema_manager.py # 列注册与动态列管理 │ │ ├── sql_backend.py # SQL 结构后端 — 列优先+JSONB │ │ ├── sql_dialect.py # PostgreSQL 方言封装 │ │ ├── sql_query.py # QueryBuilder + CrossSpaceQuery │ │ ├── redis_backend.py # Redis 后端 │ │ └── s3.py # MinIO/S3 后端 │ └── ledger/ │ ├── init.py │ ├── engine.py # LedgerEngine 双层台账引擎 │ ├── models.py # LedgerEntry 数据模型 │ ├── pg_store.py # PostgreSQL 台账持久化 │ ├── store.py # SQLite 台账 + 全局空间注册表 │ └── hooks.py # 外部回调注册表 ├── docs/ │ ├── timeline.md # 开发进度时间线 │ ├── common-errors.md # 常见错误归档 │ ├── coding-standards.md # 编码规范 │ ├── todo.md # TODO 管理 │ ├── plugin-integration-guide.md # 插件集成指南 │ └── logic-records/ # 设计文档 └── tests/ # 测试用例

---

## 相关文档

- [开发进度时间线](docs/timeline.md)
- [常见错误归档](docs/common-errors.md)
- [编码规范](docs/coding-standards.md)
- [TODO 管理](docs/todo.md)
- [Cabinet 权限外套设计文档](docs/logic-records/20260717-cabinet-permission-wrapper.md)
- [核心概念定义](docs/logic-records/20260717-space-concepts-definition.md)
- [插件集成指南](docs/plugin-integration-guide.md)
- [逻辑记录](docs/logic-records/)