ShenjiCore 神机核

轻量、规范、AI 可循的 FastAPI 开发约定层，为 Web 应用、AI 交互流 （SSE / WebSocket）、算法服务与设备接入等后端场景提供统一底座。

适用场景

核心原则：无论上层是 Web 应用、算法服务还是设备终端，后端代码结构 只有一套约定——action → domain → dao 单向分层、统一响应信封、集中错误码、 自动路由注册。开发者与 AI 按同一套规范编码，业务形态再多也不失控。

为什么是"约定"而非"魔法"

团队后端代码一致性低、AI 生成的代码风格不可控。ShenjiCore 通过约定约束代码：

• 统一分层：action → domain → dao → schema → common，单向依赖
• 统一响应：所有接口（含错误）同一种信封 {code, message, data}
• 统一异常：集中错误码 + ErrorSpec 常量，杜绝魔法数字
• 统一路由：action 目录自动注册，新增接口不改 main.py
• 统一插件：核心之外的业务能力一律插件化（PLUGINS= 配置即开关）
• 统一脚手架：shenjicore init 生成标准骨架，AI 按 docs/CONVENTIONS.md 编码

核心保持极简，无重型第三方依赖，只保留 FastAPI 生态，核心依赖 5 个： fastapi + uvicorn + pydantic + pydantic-settings + python-dotenv （后两者为配置读取所必需）。

核心 + 插件：核心只做骨架（应用组装、统一响应/异常、自动路由、脚手架）， 数据库、认证、AI 交互流、视觉算法、设备接入等业务能力一律以插件形式加载 （shenjicore/plugins/*，可选安装、配置即开关）。装插件不会污染核心：

# .env —— 启用插件（导入路径列表）
PLUGINS=[
  "shenjicore.plugins.mysql",
  "shenjicore.plugins.auth",
]

# main.py —— 或显式传入插件（不配 PLUGINS= 时）
from shenjicore import run
from shenjicore.plugins.mysql import MysqlPlugin

if __name__ == "__main__":
    run(plugins=[MysqlPlugin()])

pip install "shenjicore[mysql]"     # 安装 MySQL 插件依赖（aiomysql），不装不影响核心
pip install "shenjicore[auth]"   # 安装 Auth 插件依赖（PyJWT），不装不影响核心
pip install "shenjicore[redis]"  # 安装 Redis 插件依赖（redis），不装不影响核心
pip install "shenjicore[minio]"  # 安装 MinIO 插件依赖（minio），不装不影响核心
pip install "shenjicore[hikvision]"  # 安装海康插件依赖（httpx + opencv），不装不影响核心
pip install "shenjicore[file]"    # 安装文件插件依赖（openpyxl 可选：Excel 导出），不装不影响核心
pip install "shenjicore[scheduler]"  # 安装定时任务插件依赖（croniter：cron 表达式），不装不影响核心
pip install "shenjicore[httpclient]"  # 安装 HTTP 客户端插件依赖（httpx），不装不影响核心
pip install "shenjicore[yolo_vision]"  # 安装 YOLO 视觉插件依赖（ultralytics + opencv + imageio-ffmpeg）
pip install "shenjicore[tasks]"   # 任务平台插件无额外依赖（队列复用 redis、归档复用 mysql 各自 extra）

快速开始

pip install shenjicore         # 核心依赖（fastapi/uvicorn/pydantic）自动带上，无需再装
shenjicore init --name my_service --port 9140
cd my_service
cp .env.example .env           # 端口等值由 .env 提供；不复制则回落默认 8000
python main.py

三步起服务（init → cp .env → python main.py）。打开 http://127.0.0.1:9140/api/docs 查看文档，GET /api/hello/greet 验证分层示例。 main.py 只需两行：

from shenjicore import run

if __name__ == "__main__":
    run()      # 自动发现 common/config.py 的 Settings、action/ 路由目录、.env

目录结构

shenjicore/
├── shenjicore/               # 框架包本体（核心，5 个依赖）
│   ├── core/               # 核心：app 工厂 / 错误 / 响应 / 配置 / 日志 / 中间件
│   │   ├── app.py          # create_app（CORS、异常处理、健康检查、路由、插件注册）
│   │   ├── errors.py       # ErrorSpec + ShenError + 公共错误码
│   │   ├── response.py     # ok() / page() 统一响应
│   │   ├── config.py       # ShenSettings（pydantic-settings 基类，多环境分层）
│   │   ├── log.py          # 日志（标准库，文本/JSON 双模式，自动带 request_id）
│   │   ├── middleware.py   # 请求 ID + 访问日志 + 安全响应头（OWASP 基线）
│   │   ├── request_id.py   # request_id ContextVar（日志串联的上下文）
│   │   └── time.py         # 统一时间（北京时间，全框架含插件唯一入口）
│   ├── plugin.py           # ★ 插件机制：ShenPlugin 基类 + register_plugins
│   ├── plugins/            # 官方插件（可选安装）：mysql / auth / rbac / audit / redis /
│   │                       #   minio / hikvision / file / httpclient / scheduler /
│   │                       #   tasks / yolo_vision 全部已实现
│   ├── router.py           # action 目录自动注册（ENABLE_ROUTER / URL_PREFIX）
│   └── cli.py              # shenjicore init 脚手架
├── docs/
│   ├── CONVENTIONS.md      # ★ 开发规范（分层/接口/错误码/命名/插件/AI 约定）
│   ├── USER_GUIDE.md       # ★ 使用说明书（全部已实现功能的完整用法）
│   ├── ROADMAP.md          # 后续规划
│   └── PUBLISHING.md       # 发布指南（版本 / 发版流程 / 质量门槛）
├── CHANGELOG.md            # 版本变更记录（Keep a Changelog 风格）
├── LICENSE                 # MIT 许可正文（随包分发）
├── .github/workflows/ci.yml  # CI 模板（lint + 全量测试 + MySQL service）
└── tests/                  # 框架测试（1295 收集：1273 通过 + 22 跳过）
                            #   覆盖 core 与全部已实现插件（mysql/auth/rbac/audit/redis/
                            #   minio/hikvision/file/httpclient/scheduler/tasks）
                            #   各插件测试数随时增删，`pytest --collect-only -q` 可复算

开发

pip install -e ".[dev]"
ruff check .        # 代码检查
pytest              # 测试

路线图

见 docs/ROADMAP.md：已完成 MySQL 插件（连接池/DAO/事务/多表查询/死锁重试）、 Auth 插件（scrypt/JWT/API Key）、Redis 插件（缓存/分布式锁/限流/信号量）、MinIO 插件、 海康插件、文件插件（分片/直传/Excel 导入导出）、任务平台、调度器、HTTP 客户端、 RBAC 与审计。下一步：AI 交互流（SSE/WebSocket，需先验证中间件对流式响应的 缓冲问题）、Device 插件（具身智能设备接入与遥测）、代码生成器、模板项目仓库。

注：Vision 插件经裁决（2026-08-31）不单独建立——帧级识别走海康 stream.on_frame 回调，推理服务调用归 HTTP 客户端插件；yolo_vision 插件（推理引擎封装）已实现。

文档

• docs/USER_GUIDE.md — 使用说明书：所有已实现功能的完整用法 （配置 / 响应与错误码 / 日志 / 时间 / 路由 / 插件 / DB / Auth / API Key / Redis / 完整示例）
• docs/CONVENTIONS.md — 开发规范（分层 / 接口 / 错误码 / 命名 / AI 约定，唯一规范来源）
• docs/ROADMAP.md — 路线图