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 约定 skill （见下节），人写的代码与 AI 生成的代码遵循同一套规范

核心保持极简，无重型第三方依赖，只保留 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）

快速开始

已发布到 PyPI：https://pypi.org/project/shenjicore/（Python ≥ 3.11）

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

AI 约定：约定落在项目里，AI 才会遵守

"AI 可循"不是靠提示词，而是靠把约定做成 Claude Code skill 随项目交付。 shenjicore init 已把它一并装进新项目：

my_service/.claude/skills/shenjicore/
├── SKILL.md                  # 核心规则：一资源=一文件=一命名空间类、
│                             #   导入只到类名、依赖单向、action 只做薄壳…
├── references/               # CONVENTIONS（完整规范）/ layering / plugins 速查
└── examples/your_project/    # 完整分层示例（可跑，含守护测试）

为什么是 skill 而不是只写文档：AI 不会主动去翻 docs/，但会主动读项目内 的 skill。约定只有落在业务项目里，人写的代码和 AI 生成的代码才会遵循同一套规范。

• 不想装：shenjicore init --no-skill；
• 建议把 .claude/ 随项目提交，团队与 AI 共享同一份约定；
• 已存在的项目手动复制：cp -r <shenjicore 路径>/.claude/skills/shenjicore <项目>/.claude/skills/。

docs/CONVENTIONS.md 是唯一规范来源（人与 AI 的共同依据），skill 内的 references/CONVENTIONS.md 是它的镜像副本（有测试保证两者不漂移）——改规范改 docs/，再同步镜像。

目录结构

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）
│   ├── run.py              # run()：组装应用并启动 uvicorn（约定优于配置）
│   └── cli.py              # shenjicore init 脚手架（含 skill 安装）
├── .claude/skills/shenjicore/  # ★ AI 约定 skill（唯一真源；构建时映射进包内
│   │                           #   _skill/，由 init 复制到新项目）
│   ├── SKILL.md            #   核心规则
│   ├── references/         #   CONVENTIONS（docs/ 的镜像）/ layering / plugins
│   └── examples/your_project/  # 完整分层示例（可跑）
├── examples/your_project/  # 分层示例（与 skill 内示例同源）
├── 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/Redis/MinIO service）
└── tests/                  # 框架测试（覆盖 core 与全部已实现插件）

sdist 打包的是完整仓库形态（除 shenjicore/ 包体外，还含 docs/、 tests/、examples/、.claude/ skill）——因为分工是：pip install 拿运行库， sdist 拿规范、示例与 skill。wheel 只含运行库 + skill（init 用）。

开发

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 约定，唯一规范来源）
• .claude/skills/shenjicore/ — AI 约定 skill：上面两份的 AI 入口形态 + 可跑示例
• docs/ROADMAP.md — 路线图
• CHANGELOG.md — 版本变更记录