turbo-agent-store 0.1.0.dev1__tar.gz

turbo_agent_store-0.1.0.dev1/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: turbo-agent-store
+Version: 0.1.0.dev1
+Summary: 存储模块的技术实现层，提供 Memory/YAML/Git 三种技术路线的实现
+Author: Turbo-Agent
+Requires-Python: >=3.10
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: loguru<0.8.0,>=0.7.3
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: turbo-agent-core>=1.0.0
+Provides-Extra: gitpython
+Requires-Dist: GitPython>=3.1.0; extra == "gitpython"
+Provides-Extra: all
+Requires-Dist: GitPython>=3.1.0; extra == "all"

turbo_agent_store-0.1.0.dev1/README.md

@@ -0,0 +1,320 @@
+# Turbo Agent Store
+
+存储模块的技术实现层，面向四个不同层次的需求提供实现。
+
+## 设计哲学
+
+> **重要说明**：四个技术路线面向不同层次的需求，**不是并行的存储后端选择**。
+
+### 1. Memory - 内存缓存
+
+**用途**：运行时缓存、临时数据存储
+
+**实现**：
+- `InMemoryCacheStore` - BaseCacheStore 的内存实现
+- `InMemoryExecutionStore` - BaseExecutionStore 的内存降级实现
+- `MemoryQueueEventBroker` - BaseEventBroker 的内存队列实现
+
+**特点**：
+- 不持久化，进程重启后数据丢失
+- 用于单元测试、本地调试、临时缓存降级
+- 保证接口可用与最小幂等（以 id 做覆盖/更新）
+
+**不是**：持久化存储方案
+
+### 2. YAML - 结构化数据导出
+
+**用途**：基于 core schema 的结构化导出/导入
+
+**实现**：
+- `YAMLConfigStore` - BaseConfigStore 的 YAML 文件实现
+
+**特点**：
+- 保持与 core schema 的一致性
+- 用于配置备份、跨环境数据迁移
+- 版本控制友好（文本格式、可读性强）
+- 实现数据在不同业务线产品间的流转
+
+**不是**：持久化存储后端，而是**数据流转格式**
+
+### 3. Resource - 文件资源管理
+
+**用途**：KnowledgeResource 文件存储（上传资源、解析结果）
+
+**实现**：
+- `LocalResourceStore` - 本地文件系统实现
+- `MinIOResourceStore` (cloud 模块) - MinIO 对象存储实现
+
+**存储路径**：
+```
+{user_id}/{context_id}/{resource_id}/
+├── original/{filename}     # 原始上传文件
+├── parsed/                  # 解析结果（预留）
+└── chunks/                  # 分块数据（预留）
+```
+
+**Context 类型**：
+- `session_{id}` - 对话临时文件
+- `project_{id}` - 项目文件
+- `temp_{id}` - 临时目录
+
+**特点**：
+- Worker 只读访问
+- Server 可写
+- 用于上传文档、图片、数据文件等
+
+### 4. Workspace - 工作区版本管理
+
+**用途**：代码/文件的 Git 版本管理
+
+**实现**：
+- `LocalGitWorkspaceStore` - 本地 Git 实现
+- `RemoteGitWorkspaceStore` (cloud 模块，规划中) - 远程 Git 服务器
+
+**场景**：
+- 用户上传工作区（zip 包）
+- 在线编辑代码文件
+- Agent 生成代码/配置文件
+- 开发 Tool/Character 的代码逻辑
+
+**目录结构**：
+```
+{base_path}/{user_id}/{workspace_id}/
+├── .git/                       # Git 版本控制
+├── files/                      # 工作文件（Git 跟踪）
+│   ├── main.py
+│   └── config.yaml
+└── .meta/                      # 元数据索引
+    └── manifest.json
+```
+
+**特点**：
+- 完整 Git 版本控制
+- Worker 可读写
+- 支持历史追溯、版本回退、分支标签
+
+---
+
+## 架构关系
+
+```
+turbo-agent-core (纯抽象)
+    │
+    ├── BaseConfigStore ──┬──> [cloud] PrismaConfigStore (持久化)
+    │                     └──> [store] YAMLConfigStore (导出)
+    │
+    ├── BaseFileStore ────┬──> [cloud] 对象存储实现
+    │                     └──> [store] GitFileStore (旧版工作空间)
+    │
+    ├── BaseCacheStore ───┬──> [cloud] RedisCacheStore
+    │                     └──> [store] InMemoryCacheStore (降级)
+    │
+    ├── BaseExecutionStore ──> [store] InMemoryExecutionStore (降级)
+    │
+    ├── ResourceStore ────┬──> [cloud] MinIOResourceStore (生产)
+    │                     └──> [store] LocalResourceStore (开发)
+    │
+    └── WorkspaceStore ───┬──> [cloud] RemoteGitWorkspaceStore (规划)
+                          └──> [store] LocalGitWorkspaceStore (本地)
+```
+
+**依赖规则**：
+- `turbo-agent-store` 只依赖 `turbo-agent-core`
+- 具体业务 DTOs 由各产品线自行定义
+- 持久化存储由各场景模块自行实现（如 cloud 模块的 Prisma/MinIO 实现）
+
+---
+
+## Worker 环境管理
+
+### 使用场景
+
+Worker 执行任务前需要准备执行环境：
+1. 下载 KnowledgeResource 文件（只读）
+2. 检出 Workspace 文件（可读写）
+3. 生成环境配置
+
+### 环境目录结构
+
+```
+/tmp/worker_{task_id}/
+├── resources/           # KnowledgeResource 文件（只读）
+│   └── {resource_id}/
+│       └── {filename}
+├── workspace/           # Workspace 文件（可读写）
+│   ├── .git/
+│   └── files/
+│       ├── main.py
+│       └── config.yaml
+├── output/              # 输出目录
+├── manifest.json        # 环境清单
+└── .env                 # 环境变量
+```
+
+### 使用示例
+
+```python
+from turbo_agent_store import (
+    LocalResourceStore,
+    LocalGitWorkspaceStore,
+    WorkerEnvironmentBuilder,
+    ResourceRef,
+    WorkspaceRef,
+)
+
+# 创建 Builder
+builder = WorkerEnvironmentBuilder(
+    resource_store=LocalResourceStore("/data/resources"),
+    workspace_store_factory=lambda wid, uid: LocalGitWorkspaceStore(wid, uid, "/data/workspaces")
+)
+
+# 准备环境
+env = await builder.prepare(
+    task_id="task_001",
+    resource_refs=[
+        ResourceRef(
+            resource_id="res_123",
+            user_id="user_001",
+            context_id="session_abc",
+            filename="document.pdf",
+            path="user_001/session_abc/res_123/original/document.pdf"
+        )
+    ],
+    workspace_ref=WorkspaceRef(
+        workspace_id="ws_001",
+        user_id="user_001",
+        ref="HEAD",
+        files=["main.py", "config.yaml"]  # 或 None 表示全部
+    )
+)
+
+# 使用环境
+print(f"Resources: {env.resources_path}")
+print(f"Workspace: {env.workspace_path}")
+
+# CharacterRuntime 使用
+runtime = CharacterRuntime(
+    resources_path=env.resources_path,
+    workspace_path=env.workspace_path
+)
+result = await runtime.execute(task)
+
+# 归档输出
+await builder.archive_output(env, workspace_store)
+
+# 清理环境
+await builder.cleanup(env)
+```
+
+### 上下文管理器
+
+```python
+# 使用 async with 自动管理生命周期
+async with WorkerEnvironmentContext(
+    builder=builder,
+    task_id="task_001",
+    resource_refs=[...],
+    workspace_ref=WorkspaceRef(...)
+) as env:
+    # 环境已准备好
+    result = await runtime.execute(env)
+    # 自动清理
+```
+
+---
+
+## Git 服务器
+
+本地运行时可启动 Git 服务器供远程访问。
+
+### 使用示例
+
+```python
+from turbo_agent_store import GitServer, GitServerConfig, GitWorkspaceSync
+
+# 配置 Git 服务器
+config = GitServerConfig(
+    base_path="/data/git_server",
+    enable_daemon=True,
+    daemon_port=9418
+)
+
+# 创建服务器
+server = GitServer(config)
+
+# 创建裸仓库
+repo_path = server.create_bare_repository("user_123", "workspace_001")
+
+# 启动 daemon
+server.start_daemon()
+
+# 获取 Git URL
+url = server.get_git_url("user_123", "workspace_001", protocol="git")
+# 返回: git://0.0.0.0:9418/user_123/workspace_001.git
+
+# 同步本地工作区到服务器
+sync = GitWorkspaceSync(server)
+sync.push_to_server("user_123", "workspace_001")
+
+# 停止 daemon
+server.stop_daemon()
+```
+
+---
+
+## 安装
+
+```bash
+# 基础安装
+pip install turbo-agent-store
+
+# 包含 Git 支持
+pip install turbo-agent-store[git]
+
+# 包含所有依赖
+pip install turbo-agent-store[all]
+```
+
+---
+
+## CLI 使用
+
+```bash
+# 验证 Zip 包
+ta-store verify package.zip
+
+# 格式转换
+ta-store convert input.yaml output.json --format json
+
+# 打包配置
+ta-store pack create ./configs --output export.zip
+
+# 解压配置
+ta-store pack extract export.zip --output-dir ./extracted
+```
+
+**注意**：数据库相关的命令（如 `init-db`, `export agent`）已移动到 `turbo-agent-cloud` 模块。
+
+---
+
+## 与其他模块的关系
+
+| 模块 | 职责 | 依赖 |
+|------|------|------|
+| `turbo-agent-core` | 纯抽象定义、Schema | 无 |
+| `turbo-agent-store` | 技术实现层（Memory/YAML/Git/Resource/Workspace） | core |
+| `turbo-agent-cloud` | 云场景持久化实现（Prisma/MinIO/RemoteGit） | core + store |
+| `turbo-agent-server` | HTTP API 服务 | cloud + store |
+| `turbo-agent-job` | 任务调度与执行 | core + store + runtime |
+
+---
+
+## 迁移指南
+
+从旧版本迁移：
+
+1. **Prisma 相关功能** → 使用 `turbo-agent-cloud`
+2. **YAML 导出/导入** → 继续使用 `turbo-agent-store`
+3. **文件上传下载** → 使用新的 `ResourceStore` 接口
+4. **工作区版本管理** → 使用新的 `WorkspaceStore` 接口
+5. **GitFileStore** → 继续使用（旧版），或迁移到 `LocalGitWorkspaceStore`（新版）

turbo_agent_store-0.1.0.dev1/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "turbo-agent-store"
+version = "0.1.0.dev1"
+description = "存储模块的技术实现层，提供 Memory/YAML/Git 三种技术路线的实现"
+authors = [ { name = "Turbo-Agent" } ]
+requires-python = ">=3.10"
+dependencies = [
+  "typer>=0.9.0",
+  "rich>=13.0.0",
+  "python-dotenv>=1.0.0",
+  "loguru>=0.7.3,<0.8.0",
+  "pyyaml>=6.0.1",
+  "turbo-agent-core>=1.0.0"
+]
+
+[project.optional-dependencies]
+# Git 文件存储支持
+GitPython = ["GitPython>=3.1.0"]
+# 完整功能
+all = ["GitPython>=3.1.0"]
+
+[project.scripts]
+ta-store = "turbo_agent_store.cli:app"
+
+[tool.uv]
+package = true
+
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"

turbo_agent_store-0.1.0.dev1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

turbo_agent_store-0.1.0.dev1/src/turbo_agent_store/__init__.py

@@ -0,0 +1,127 @@
+"""turbo-agent-store
+
+存储模块的技术实现层，面向不同需求提供实现：
+
+1. **Cache** - 内存缓存实现
+   - 用途：运行时缓存、临时数据存储
+   - 实现：InMemoryCacheStore, InMemoryExecutionStore
+
+2. **Config** - 结构化数据导出
+   - 用途：基于 core schema 的结构化导出
+   - 实现：YAMLConfigStore
+
+3. **Git** - 工作空间文件版本管理
+   - 用途：Agent 工作空间文件的版本管理
+   - 实现：GitFileStore, LocalGitWorkspaceStore
+
+4. **Resource** - 知识资源文件管理
+   - 用途：KnowledgeResource 文件存储、解析
+   - 实现：KnowledgeResourceManager, AnalysisWorker
+
+5. **Workspace** - 工作区文件管理
+   - 用途：Workset/Workspace Git 操作
+   - 实现：LocalGitWorkspaceStore
+
+6. **Worker** - 执行环境管理
+   - 用途：Worker 环境准备与清理
+   - 实现：WorkerEnvironmentBuilder, WorkerEnvironment
+
+7. **GitServer** - Git 服务器管理
+   - 用途：本地 Git 服务器初始化与管理
+   - 实现：GitServer, GitWorkspaceSync
+
+注意：
+- 纯抽象定义在 turbo_agent_core.store 中
+- 持久化存储由 cloud 模块实现（MinIO, Prisma）
+"""
+
+from turbo_agent_core.store import (
+    BaseFileStore,
+    BaseExecutionStore,
+    BaseCacheStore,
+    BaseEventBroker,
+    BaseAssembler,
+    # 新增文件存储抽象
+    ResourceStore,
+    ResourceInfo,
+    WorkspaceStore,
+    FileInfo,
+    CommitInfo,
+    TagInfo,
+)
+
+# Data 存储能力
+from .data.cache.cache import InMemoryCacheStore
+from .data.cache.execution import InMemoryExecutionStore
+from .data.cache.event_broker import MemoryQueueEventBroker
+
+# Files 存储能力
+from .files.git.file import GitFileStore
+from .files.resource import (
+    KnowledgeType,
+    FileType,
+    ResourceStatus,
+    AnalysisStatus,
+    AnalysisJob,
+    ResourceMetadata,
+    KnowledgeResourceUploadRequest,
+    KnowledgeResourceManager,
+    AnalysisWorker,
+    process_knowledge_resource_analysis,
+)
+from .files.workspace import LocalGitWorkspaceStore
+
+# Runtime 执行环境能力
+from .runtime.worker import (
+    WorkerEnvironment,
+    WorkerEnvironmentBuilder,
+    WorkerEnvironmentContext,
+    ResourceRef,
+    WorkspaceRef,
+)
+from .runtime.git_server import GitServer, GitServerConfig, GitWorkspaceSync
+
+__all__ = [
+    # 纯抽象 (from core)
+    "BaseFileStore",
+    "BaseExecutionStore",
+    "BaseCacheStore",
+    "BaseEventBroker",
+    "BaseAssembler",
+    # 新增抽象
+    "ResourceStore",
+    "ResourceInfo",
+    "WorkspaceStore",
+    "FileInfo",
+    "CommitInfo",
+    "TagInfo",
+    # Cache 实现
+    "InMemoryCacheStore",
+    "InMemoryExecutionStore",
+    "MemoryQueueEventBroker",
+    # Git 实现（旧版）
+    "GitFileStore",
+    # Resource 知识资源管理
+    "KnowledgeType",
+    "FileType",
+    "ResourceStatus",
+    "AnalysisStatus",
+    "AnalysisJob",
+    "ResourceMetadata",
+    "KnowledgeResourceUploadRequest",
+    "KnowledgeResourceManager",
+    "AnalysisWorker",
+    "process_knowledge_resource_analysis",
+    # Workspace
+    "LocalGitWorkspaceStore",
+    # Worker 环境管理
+    "WorkerEnvironment",
+    "WorkerEnvironmentBuilder",
+    "WorkerEnvironmentContext",
+    "ResourceRef",
+    "WorkspaceRef",
+    # Git 服务器管理
+    "GitServer",
+    "GitServerConfig",
+    "GitWorkspaceSync",
+]

turbo_agent_store-0.1.0.dev1/src/turbo_agent_store/cli.py

@@ -0,0 +1,183 @@
+"""
+Store 模块 CLI
+
+提供 YAML 格式的配置导出/导入功能。
+注意：数据库相关的命令已移动到 turbo-agent-cloud 模块。
+"""
+
+import os
+import typer
+import yaml
+import json
+import zipfile
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+from rich.console import Console
+from rich.table import Table
+from loguru import logger
+
+from turbo_agent_store.services.package_loader import PackageLoader
+
+app = typer.Typer()
+console = Console()
+
+
+# ===== Verify Command =====
+
+@app.command()
+def verify(
+    package_path: str = typer.Argument(..., help="Zip 包路径"),
+):
+    """
+    验证 Zip 包并尝试加载到内存。
+    检查包内 YAML 文件的格式和依赖关系。
+    """
+    if not os.path.exists(package_path):
+        console.print(f"[red]文件不存在: {package_path}[/red]")
+        raise typer.Exit(code=1)
+
+    try:
+        loader = PackageLoader()
+        entities = loader.load(package_path)
+        
+        table = Table(title=f"包内容: {os.path.basename(package_path)}")
+        table.add_column("Type", style="cyan")
+        table.add_column("ID", style="magenta")
+        table.add_column("Name")
+        table.add_column("Dependencies")
+        
+        for entity in entities:
+            deps = []
+            if hasattr(entity, 'model') and entity.model:
+                deps.append(f"Model:{entity.model.name}")
+            if hasattr(entity, 'tools') and entity.tools:
+                deps.append(f"Tools:{len(entity.tools)}")
+            
+            table.add_row(
+                entity.__class__.__name__,
+                entity.id,
+                entity.name,
+                ", ".join(deps)
+            )
+            
+        console.print(table)
+        console.print(f"[green]成功加载 {len(entities)} 个实体[/green]")
+        
+    except Exception as e:
+        console.print(f"[red]加载失败: {e}[/red]")
+        import traceback
+        traceback.print_exc()
+        raise typer.Exit(code=1)
+
+
+# ===== Convert Command =====
+
+@app.command()
+def convert(
+    input_path: str = typer.Argument(..., help="输入 YAML/JSON 文件路径"),
+    output_path: str = typer.Argument(..., help="输出文件路径"),
+    format: str = typer.Option("yaml", help="输出格式: yaml 或 json"),
+):
+    """
+    在不同格式间转换配置文件。
+    用于格式标准化和数据迁移。
+    """
+    input_file = Path(input_path)
+    if not input_file.exists():
+        console.print(f"[red]输入文件不存在: {input_path}[/red]")
+        raise typer.Exit(code=1)
+    
+    try:
+        # 读取输入
+        with open(input_file, 'r', encoding='utf-8') as f:
+            if input_path.endswith('.json'):
+                data = json.load(f)
+            else:
+                data = yaml.safe_load(f)
+        
+        # 写入输出
+        output_file = Path(output_path)
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+        
+        with open(output_file, 'w', encoding='utf-8') as f:
+            if format.lower() == 'json':
+                json.dump(data, f, indent=2, ensure_ascii=False)
+            else:
+                yaml.dump(data, f, allow_unicode=True, sort_keys=False)
+        
+        console.print(f"[green]已转换: {input_path} -> {output_path}[/green]")
+        
+    except Exception as e:
+        console.print(f"[red]转换失败: {e}[/red]")
+        raise typer.Exit(code=1)
+
+
+# ===== Package Command =====
+
+pack_app = typer.Typer()
+app.add_typer(pack_app, name="pack", help="打包/解包配置")
+
+
+@pack_app.command("create")
+def pack_create(
+    source_dir: str = typer.Argument(..., help="源目录路径（包含 YAML 文件）"),
+    output: str = typer.Option("export.zip", help="输出 Zip 文件路径"),
+):
+    """
+    将 YAML 配置目录打包为 Zip 包。
+    """
+    source_path = Path(source_dir)
+    if not source_path.exists():
+        console.print(f"[red]源目录不存在: {source_dir}[/red]")
+        raise typer.Exit(code=1)
+    
+    try:
+        output_file = Path(output)
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+        
+        with zipfile.ZipFile(output_file, 'w', zipfile.ZIP_DEFLATED) as zf:
+            yaml_files = list(source_path.rglob("*.yaml")) + list(source_path.rglob("*.yml"))
+            
+            for file_path in yaml_files:
+                rel_path = file_path.relative_to(source_path)
+                zf.write(file_path, arcname=str(rel_path))
+                console.print(f"  添加: {rel_path}")
+        
+        console.print(f"[green]已创建包: {output}[/green]")
+        console.print(f"  共 {len(yaml_files)} 个 YAML 文件")
+        
+    except Exception as e:
+        console.print(f"[red]打包失败: {e}[/red]")
+        raise typer.Exit(code=1)
+
+
+@pack_app.command("extract")
+def pack_extract(
+    package_path: str = typer.Argument(..., help="Zip 包路径"),
+    output_dir: str = typer.Option("./extracted", help="输出目录"),
+):
+    """
+    解压 Zip 包到目录。
+    """
+    package_file = Path(package_path)
+    if not package_file.exists():
+        console.print(f"[red]包文件不存在: {package_path}[/red]")
+        raise typer.Exit(code=1)
+    
+    try:
+        output_path = Path(output_dir)
+        output_path.mkdir(parents=True, exist_ok=True)
+        
+        with zipfile.ZipFile(package_file, 'r') as zf:
+            zf.extractall(output_path)
+        
+        console.print(f"[green]已解压到: {output_dir}[/green]")
+        
+    except Exception as e:
+        console.print(f"[red]解压失败: {e}[/red]")
+        raise typer.Exit(code=1)
+
+
+if __name__ == "__main__":
+    app()

turbo_agent_store-0.1.0.dev1/src/turbo_agent_store/data/cache/__init__.py

@@ -0,0 +1,19 @@
+"""
+Memory 实现层
+
+用于内存缓存和临时存储，不持久化。
+适用于：
+- 单元测试
+- 本地调试
+- 临时缓存降级
+"""
+
+from .cache import InMemoryCacheStore
+from .execution import InMemoryExecutionStore
+from .event_broker import MemoryQueueEventBroker
+
+__all__ = [
+    "InMemoryCacheStore",
+    "InMemoryExecutionStore",
+    "MemoryQueueEventBroker",
+]