# STAR

**Repository Path**: HengYangDS/star

## Basic Information

- **Project Name**: STAR
- **Description**: S(ense)-T(hink)-A(ct)-R(efine)
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-21
- **Last Updated**: 2025-11-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Machine-learning, AI, Yaml, Python

## README

# STAR Framework

> 🤖 企业级 AI Agent 开发框架 | Knowledge Graph + RAG + Multi-Agent System  
> 通用智能循环（STAR: Sensing-Thinking-Acting-Reflecting）| 生产就绪的智能应用构建平台

[![Version](https://img.shields.io/badge/version-2.0.0-blue)]()
[![Python](https://img.shields.io/badge/python-3.12%2B-brightgreen)]()
[![License](https://img.shields.io/badge/license-MIT-green)]()
[![Gitee Stars](https://gitee.com/HengYangDS/star/badge/star.svg?theme=dark)](https://gitee.com/HengYangDS/star/stargazers)
[![Gitee Forks](https://gitee.com/HengYangDS/star/badge/fork.svg?theme=dark)](https://gitee.com/HengYangDS/star/members)
[![CI Status](https://img.shields.io/badge/CI-passing-brightgreen)](https://gitee.com/HengYangDS/star)
[![Test Coverage](https://img.shields.io/badge/coverage-95.43%25-success)]()
[![Code Quality](https://img.shields.io/badge/code%20quality-ruff-blue)]()

**核心能力**: AI Agent 编排 | 知识图谱推理 | 检索增强生成 (RAG) | 多智能体协作 | 生产级部署

---

## 🎓 新手入门

**👉 [完整学习路径 - Getting Started Guide](docs/GETTING_STARTED.md)**

从零到生产，2-3小时快速掌握 STAR Framework：
- ✅ **安装配置** (5分钟)
- ✅ **快速开始** (10分钟) 
- ✅ **核心概念** (30分钟)
- ✅ **示例项目** (1-2小时) - star_docqa 或 service_demo
- ✅ **进阶学习** - 插件系统、知识图谱、生产部署

---

## ✨ 核心特性

### 🎯 企业级基础设施
- **响应式编程**: 流式数据处理，支持背压和错误恢复
- **依赖注入**: 完整的IoC容器，生命周期管理
- **AOP支持**: 日志、性能监控、重试机制
- **事件驱动**: 发布/订阅模式，异步事件总线
- **配置管理**: YAML配置，环境变量支持

### 🧠 AI智能引擎
- **知识图谱**: Neo4j集成，语义推理
- **多智能体系统**: 协作引擎，任务分配
- **推理引擎**: 因果推理、逻辑推理
- **学习引擎**: 元学习、强化学习
- **预测引擎**: 时序预测、异常检测

### 🔧 生产就绪
- **集群支持**: 故障转移、数据复制、灰度发布
- **监控告警**: Prometheus集成，Grafana仪表板
- **插件系统**: 
  - **热重载**: 文件监控、自动重载、零停机更新
  - **Schema验证**: JSON Schema标准化、版本兼容性检查
  - **优先级管理**: 依赖解析、拓扑排序、循环依赖检测
  - **健康检查**: 全面诊断（状态、配置、依赖、性能、资源）
  - **生产级插件**: PostgreSQL异步（psycopg3）、Redis性能监控
- **安全性**: 认证授权、审计日志、漏洞扫描（pip-audit集成）
- **文档完善**: API文档、示例代码、最佳实践

### 🚀 开发体验
- **Python 3.12+兼容**: 完整验证、424个依赖锁定、安全漏洞修复
- **类型安全**: 完整的类型提示和验证
- **测试覆盖**: 96.5%覆盖率（1744/1793测试通过）
- **性能基准**: 66个基准测试（Redis 5000+ QPS, PostgreSQL 500+ QPS, Neo4j 100+ QPS）
- **CI/CD**: 自动化流水线，质量门禁
- **代码质量**: Ruff格式化，Pylint检查
- **快速上手**: 5分钟示例，详细文档

## 🚀 快速开始

### 从Gitee安装

```bash
# 通过HTTPS从Gitee安装
pip install git+https://gitee.com/HengYangDS/star.git

# 或通过SSH安装
pip install git+ssh://git@gitee.com/HengYangDS/star.git

# 或从本地开发安装
git clone https://gitee.com/HengYangDS/star.git
cd star
pip install -e .
```

## 💡 5分钟上手

```python
from star.infra.pipeline import Pipeline

# 创建并配置Pipeline（链式API）
pipeline = Pipeline(workers=4, mode="thread")

# 处理数据流
results = (
    pipeline
    .map(lambda x: x * 2)  # 翻倍
    .filter(lambda x: x > 10)  # 过滤
    .map(lambda x: x + 10)  # 加10
    .process(range(1, 10))  # 处理数据
)

print(f'Results: {results}')  # Output: Results: [22, 24, 26, 28]
```

### 使用AOP装饰器

```python
from star.infra.aop import log_phase
import logging

logging.basicConfig(level=logging.INFO)


@log_phase("数据处理")
def process_data(data):
    return data * 2


result = process_data(10)  # 自动记录日志
```

### 使用依赖注入

```python
from star.infra.di import DIContainer, ComponentRegistry

# 创建容器
registry = ComponentRegistry()
container = DIContainer(registry)


# 注册服务
class DataService:
    def get_data(self):
        return [1, 2, 3, 4, 5]


registry.register('data_service', DataService)

# 解析服务
container = DIContainer(registry)
service = container.resolve('data_service')
data = service.get_data()
```

## 📦 核心模块

### Infrastructure (基础设施)

- **aop.py**: 面向切面编程 - 日志、性能监控、重试机制
- **di.py / di_framework.py**: 依赖注入 - 组件管理、生命周期控制
- **reactive.py**: 响应式编程 - 流式数据处理
- **functional.py / functional_advanced.py**: 函数式编程 - compose, pipe, curry, 高级组合
- **pipeline.py**: 管道处理 - 数据流水线
- **event_bus.py**: 事件总线 - 发布/订阅模式
- **config.py / config_framework.py**: 配置管理 - YAML配置支持
- **logging.py**: 日志框架 - 结构化日志
- **models.py**: 基础数据模型

### Intelligence (智能层)

#### 引擎模块

- **kg_service.py / kg_driver.py**: 知识图谱服务 - Neo4j集成
- **agents_engine.py**: 智能体引擎 - 多智能体系统
- **collaboration_engine.py**: 协作引擎 - 多智能体协作
- **reasoning_engine.py**: 推理引擎 - 因果推理和逻辑推理
- **learning_engine.py**: 学习引擎 - 元学习和强化学习
- **prediction_engine.py / predictive_engine.py**: 预测引擎 - 预测智能
- **evolution_engine.py**: 进化引擎 - 自适应优化
- **value_engine.py**: 价值引擎 - 价值评估

#### 数据模型

- **models_agents.py**: 智能体数据模型
- **models_collaboration.py**: 协作数据模型
- **models_reasoning.py**: 推理数据模型
- **models_learning.py**: 学习数据模型
- **models_prediction.py / models_predictive.py**: 预测数据模型
- **models_evolution.py**: 进化数据模型
- **models_kg.py**: 知识图谱数据模型
- **models_value.py**: 价值数据模型

### Services (服务层)

- **api_server.py**: REST API 服务器 - FastAPI实现
- **cli.py**: 命令行接口 - CLI工具
- **mcp_server.py**: MCP 服务器 - Model Context Protocol
- **monitoring.py**: 监控服务 - 系统健康监控

### Core (核心接口)

- **interface.py**: 核心接口定义 - STAR循环抽象

### Integration (集成层)

- **star.py**: 统一门面 - STAR类提供统一访问接口

### Adapters (适配器)

- **adapter.py**: 外部系统适配
- **runtime.py**: 运行时环境

## 🏗️ 架构设计

```
star/
├── infra/           # 基础设施层（响应式、AOP、DI、配置、事件总线）
├── intelligence/    # 智能层（知识图谱、推理、学习、协作、预测）
├── services/        # 服务层（API服务器、CLI、MCP服务器、监控）
├── core/            # 核心接口层（STAR循环抽象）
├── integration/     # 集成层（统一门面）
├── adapters/        # 适配器层（外部集成）
└── utils/           # 工具模块
```

## 📚 文档导航

### 用户文档

**完整文档导航**: [docs/INDEX.md](docs/INDEX.md) - 17个用户文档统一入口

**快速链接**：
- [入门教程](docs/GETTING_STARTED_TUTORIAL.md) - 30-60分钟完整教程（⭐ 新手必读）
- [快速参考](docs/QUICK_REFERENCE.md) - 单页速查卡，常用命令和API
- [运维手册](docs/OPERATIONS_MANUAL.md) - 日常运维、监控、日志、备份
- [生产部署指南](docs/PRODUCTION_DEPLOYMENT_GUIDE.md) - Docker部署和高可用架构
- [性能调优指南](docs/PERFORMANCE_TUNING_GUIDE.md) - 性能优化策略
- [插件开发指南](docs/plugin_development_guide.md) - 创建自定义插件

**按角色导航**：
- **新手开发者** → [入门教程](docs/GETTING_STARTED_TUTORIAL.md) + [快速参考](docs/QUICK_REFERENCE.md)
- **运维工程师** → [运维手册](docs/OPERATIONS_MANUAL.md) + [应急响应指南](docs/EMERGENCY_RESPONSE_GUIDE.md)
- **架构师** → [生产部署指南](docs/PRODUCTION_DEPLOYMENT_GUIDE.md) + [SLA定义](docs/SLA_DEFINITION.md)
- **插件开发者** → [插件系统文档](docs/INDEX.md#-插件系统文档)（5个完整文档）

**代码示例**：
- [examples/](examples/) - 完整可运行示例

### 项目知识库（.memex）

STAR项目的战略分析、架构设计、规划文档集中存放在`.memex/`目录：

| 分类           | 描述             | 快速访问                                                              |
|--------------|----------------|-------------------------------------------------------------------|
| 🎯 **战略分析**  | 层级定位、愿景规划、关系分析 | [4_history/strategic/](.memex/4_history/strategic/)               |
| 🏗️ **架构设计** | 整体架构、迁移策略      | [2_foundations/architecture/](.memex/2_foundations/architecture/) |
| 📋 **规划文档**  | 重构计划、优化方案      | [4_history/planning/](.memex/4_history/planning/)                 |
| 📖 **实践指南**  | 使用手册、最佳实践      | [3_knowledge/guides/](.memex/3_knowledge/guides/)                 |
| 📦 **历史档案**  | 决策记录、演进历史      | [archives/](.memex/archives/)                                     |

**主索引**: [.memex/readme.md](.memex/readme.md) - 完整文档导航  
**快速索引**: [.memex/index.md](.memex/index.md) - 按分类和关键词查找

### 推荐阅读

**新人入门**:

1. [开始这里 - 文档系统入口](.memex/1_essentials/quickstart.md)
2. [整体架构设计](.memex/2_foundations/architecture/architecture.md)
3. [STAR + Junie 实践指南](.memex/3_knowledge/guides/star_junie_practical_guide.md)

**架构师**:

- [整体架构设计](.memex/2_foundations/architecture/architecture.md)
- [环境配置说明](.memex/2_foundations/environment/readme.md)
- [战略分析文档](.memex/4_history/strategic/)

### 方法论与规范

- [.junie/guidelines.md](.junie/guidelines.md) - 跨项目方法论和编码规范
- [.junie/intelligence/](.junie/intelligence/) - AI协作框架和认知增强

### 📁 文档组织规范

**重要原则**：项目顶层目录应保持简洁，仅保留核心文件。

#### 顶层目录（仅限核心文件）

- ✅ `README.md` - 项目主文档
- ✅ `README_DEV.md` - 开发者文档
- ✅ `pyproject.toml`, `setup.py` - 包配置
- ✅ `requirements.txt`, `Makefile` - 构建配置
- ✅ `ruff.toml` - 代码质量配置
- ✅ `docker/` - Docker 配置（Dockerfile, docker-compose.yml）

#### 项目特定文档（必须放在 .memex/）

- 📋 **快速入门** → `.memex/1_essentials/`
- 📋 **架构设计** → `.memex/2_foundations/architecture/`
- 📋 **技术分析** → `.memex/3_knowledge/analysis/`
- 📋 **历史报告** → `.memex/4_history/reports/`
- 📋 **工具脚本** → `.memex/5_operations/tools/`

#### 命名规范

- ✅ 使用小写字母和下划线：`phase1_completion_report.md`
- ❌ 避免大写字母：~~`PHASE1_COMPLETION_REPORT.md`~~
- ✅ 日期格式：`YYYYMMDD` 如 `20251122`

**详细说明**：参见 [.memex/readme.md](.memex/readme.md)

## 🧪 运行测试

```bash
# 安装开发依赖
pip install -e .[dev]

# 运行所有测试
pytest tests/ -v

# 运行特定测试
pytest tests/test_star_aop.py -v

# 生成覆盖率报告
pytest tests/ --cov=star --cov-report=html
```

## 🛠️ 开发

**👉 [完整开发者指南 - docs/guides/develop.md](docs/guides/develop.md)** - 开发环境设置、代码规范、测试指南、CI/CD流程

### 快速开始

```bash
# 克隆仓库
git clone https://gitee.com/HengYangDS/star.git
cd star

# 安装开发环境
pip install -e .[dev]

# 代码格式化
black star/

# 类型检查
mypy star/

# 代码质量检查
pylint star/
```

## 🔄 CI/CD 流水线

本项目配置了完整的 Gitee Go 自动化流水线，确保代码质量和测试覆盖率。

### 流水线触发条件

- **Push** 到 `master` 或 `develop` 分支
- **Pull Request** 到 `master` 或 `develop` 分支

### 流水线阶段

| 阶段 | 检查内容 | 要求 | 运行时间 |
|------|----------|------|----------|
| **Lint** | Ruff 代码检查和格式验证 | 必须通过 | ~30秒 |
| **Security** | Safety + Bandit 安全扫描 | 必须通过 | ~1分钟 |
| **Test** | Pytest 单元测试 + 覆盖率 | 覆盖率 ≥80% | ~2-3分钟 |
| **Docs** | Sphinx 文档构建 | 仅 Push 触发 | ~1-2分钟 |

### 本地预检查

推送代码前，建议运行以下命令：

```bash
# 1. 代码质量和格式检查
ruff check star/ tests/
ruff format star/ tests/ --check

# 2. 安全扫描
safety check --file requirements.txt
bandit -r star/

# 3. 运行测试（覆盖率 ≥80%）
pytest tests/ --cov=star --cov-fail-under=80

# 4. 构建文档（可选）
cd docs && make html
```

### 查看流水线结果

1. 访问 [Gitee Actions](https://gitee.com/HengYangDS/star/actions)
2. 查看最新的工作流运行记录
3. 下载 Artifacts（覆盖率报告、安全报告、文档）

**详细说明**：参见 [.workflow/README.md](.workflow/README.md)

## 📋 依赖

- **Python**: >=3.12
- **pyyaml**: >=6.0 - YAML配置支持
- **neo4j**: >=5.0 - 知识图谱数据库

### 开发依赖

- pytest>=7.0 - 测试框架
- pytest-cov>=4.0 - 覆盖率报告
- black>=23.0 - 代码格式化
- pylint>=3.0 - 代码质量
- mypy>=1.0 - 类型检查

## 🤝 贡献

我们欢迎各种形式的贡献！

### 如何贡献
1. **报告Bug**: [提交Issue](https://gitee.com/HengYangDS/star/issues)
2. **建议功能**: [功能请求](https://gitee.com/HengYangDS/star/issues/new?template=feature_request)
3. **提交代码**: 查看 [CONTRIBUTING.md](docs/guides/CONTRIBUTING.md) 了解详情
4. **改进文档**: 文档PR随时欢迎

### 贡献者指南
- [行为准则](docs/project/CODE_OF_CONDUCT.md) - 社区规范
- [安全政策](docs/guides/SECURITY.md) - 漏洞报告流程
- [开发指南](DEVELOP.md) - 开发环境配置

## 📄 许可

本项目采用 MIT License - 详见 [LICENSE](LICENSE) 文件

## 🔗 相关资源

### 项目链接
- **Gitee仓库**: https://gitee.com/HengYangDS/star
- **Issue跟踪**: https://gitee.com/HengYangDS/star/issues
- **Pull Requests**: https://gitee.com/HengYangDS/star/pulls

### 文档资源
- [快速开始](docs/guides/QUICKSTART.md) - 5分钟快速上手指南
- [示例代码](examples/) - 完整使用示例
- [用户文档导航](docs/INDEX.md) - 用户友好文档索引（指南、运维、插件）
- [开发者知识库](.memex/INDEX.md) - 开发者完整知识库索引（架构、战略、实现）
- [部署指南](docs/guides/deployment_guide.md) - 生产环境部署
- [故障排查](docs/guides/troubleshooting_guide.md) - 常见问题解决

### 相关项目
- Junie AI协作方法论库（敬请期待）

## 📮 联系方式

- **问题反馈**: [提交Issue](https://gitee.com/HengYangDS/star/issues)
- **功能建议**: [功能请求](https://gitee.com/HengYangDS/star/issues/new)
- **安全漏洞**: 请查看 [SECURITY.md](docs/guides/SECURITY.md)
- **Gitee**: https://gitee.com/HengYangDS/star

---

**版本**: 2.0.0  
**状态**: Beta - 稳定开发中  
**最后更新**: 2025-11-22