Mino

轻量规格驱动的 Go Gin/GORM + React Ant Design 中后台脚手架。

create 初始化项目 · module 生成模块 · verify 验证链路 · skill 接入 Codex

Mino 面向国内中后台开发习惯，提供类似 RuoYi Pro 的项目初始化、模块生成、权限菜单、接口台账、OpenAPI、数据库迁移和 Codex Skill 闭环。它不追求重型 OpenSpec，而是把关键数据结构、接口、权限、对接规范和业务规则沉淀下来，让日常 CRUD 和模块开发可以快速生成、可验证、可回滚。

✨ 特性

| 能力 | 说明 | | --- | --- | | 🧱 开箱模板 | Go Gin/GORM 后端、React/Vite/Ant Design 管理端、PostgreSQL、Redis、Docker Compose。 | | 🔐 公共底座 | 登录鉴权、RBAC、用户、角色、菜单、部门、岗位、接口台账、权限、字典、配置、文件上传、操作日志。 | | 🪄 模块生成 | 按 JSON 规格或自然语言草稿生成 CRUD、页面、路由、权限、菜单、接口 seed、OpenAPI 和 SQL migration。 | | 🧩 业务形态 | 只读模块、CSV 导入导出、树表、主子表、轻量状态机、轻量审批流、小程序端 API 和页面起点。 | | 🛡️ 工程安全 | doctor 环境检查、dry-run 差异预览、apply 备份、rollback 回滚、verify 多层验证。 | | 🤖 Codex Skill | 安装 mino-module 后，让 Codex 根据原始需求直接生成模块规格和前后端代码。 | | 📚 轻量沉淀 | docs/ 存放架构和规范，specs/ 存放关键模块和变更；普通页面微调不强制沉淀。 |

🧰 环境支持

| 依赖 | 要求 | 用途 | | --- | --- | --- | | Node.js | >= 18 | 运行 CLI、管理端构建 | | Go | >= 1.21 | 后端编译和测试 | | Docker Compose | 可选 | 完整容器链路验证 | | PostgreSQL CLI | 可选 | 真实数据库 smoke test，需要 initdb、pg_ctl、createdb |

📦 安装

npm 仓库安装：

npm install -g @yixiaoping/mino
mino --help

安装 Codex Skill：

mino skill install mino-module

源码本地开发：

cd mino
npm link
mino --help

不注册全局命令时，也可以直接使用源码 CLI：

node bin/mino.mjs --help

从源码打包安装：

npm pack
npm install -g ./yixiaoping-mino-0.1.0.tgz
mino --help

🚀 快速上手

1. 创建项目

mino create demo-app --out /tmp --module example.com/demo-app
cd /tmp/demo-app
npm run doctor
npm run verify:quick

2. 验证容器链路

npm run verify:compose

3. 生成模块

自然语言需求 -> 模块 JSON -> validate -> dry-run -> apply -> verify

mino module draft-spec \
  --name insurance \
  --title 保险产品 \
  --from examples/insurance.requirement.md \
  --out /tmp/insurance.module.json

mino module validate --spec /tmp/insurance.module.json --cwd /tmp/demo-app
mino module dry-run --spec /tmp/insurance.module.json --cwd /tmp/demo-app
mino module apply --spec /tmp/insurance.module.json --cwd /tmp/demo-app
mino verify --cwd /tmp/demo-app

如果已经进入生成项目根目录，优先使用项目内脚本：

npm run mino -- module validate --spec /tmp/insurance.module.json --cwd .
npm run mino -- module dry-run --spec /tmp/insurance.module.json --cwd .
npm run mino -- module apply --spec /tmp/insurance.module.json --cwd .
npm run verify

🤖 在 Codex 中使用

安装随包 Skill：

mino skill install mino-module

之后可以在 Codex 中描述需求：

使用 mino-module，给当前 Mino 项目生成一个保险产品模块。
字段：名称、保额、价格、分类、状态、保障开始时间、保障结束时间。
列表展示：名称、价格、分类、状态。
需要新增、编辑、删除、导入、导出、启用、停用。

Skill 默认会按以下流程工作：

1. 读取项目 AGENTS.md、docs/README.md 和 specs/README.md。
2. 将自然语言需求整理为模块 JSON 规格。
3. 执行 module validate 和 module dry-run。
4. 确认后执行 module apply。
5. 运行 verify，必要时继续补业务逻辑或文档。

⌨️ 命令

🏗️ 项目初始化

mino create <project-name> [--out <dir>] [--module <go-module>]

常用参数：

• --module：Go module 名称。
• --service-name：服务显示名。
• --db-name、--db-user、--db-password：Docker Compose PostgreSQL 初始化参数。
• --token-secret：token 签名密钥；不传时自动生成随机值。
• --backend-port、--admin-port、--admin-dev-port：后端、管理端容器和管理端开发端口。
• --postgres-port、--redis-port：PostgreSQL 和 Redis 宿主机端口。

示例：

mino create demo-app \
  --out /tmp \
  --module example.com/demo-app \
  --db-name demo_app \
  --backend-port 9000 \
  --admin-port 9001

🧩 模块开发

mino module init-spec --name <name> --title <中文名> --out <file>
mino module draft-spec --name <name> --title <中文名> --text "<需求>" --out <file>
mino module draft-spec --name <name> --title <中文名> --from <requirement.md> --out <file>
mino module validate --spec <file> --cwd <project-root>
mino module dry-run --spec <file> --cwd <project-root>
mino module apply --spec <file> --cwd <project-root>
mino module rollback --backup <backup-dir> --cwd <project-root>

module apply 会接入：

• 🧠 后端 model、repository、handler、router。
• 🖥️ 管理端 API client、页面和生成路由。
• 🗄️ SQL schema、权限 seed、菜单 seed、接口台账 seed。
• 📘 OpenAPI 片段和汇总文件。
• 📝 specs/modules、specs/changes 和 .mino/modules.json。
• ↩️ .mino/backups 回滚备份。

✅ 验证

mino doctor --cwd <project-root>
mino verify --cwd <project-root>
mino verify --cwd <project-root> --runtime
mino verify --cwd <project-root> --dev
mino verify --cwd <project-root> --db
mino verify --cwd <project-root> --compose

说明：

• 🩺 doctor：检查 Node、Go、Docker Compose、PostgreSQL 工具、项目结构、脚本和端口。
• 🔎 verify：检查模板配置、OpenAPI、生成产物一致性、后端测试、管理端构建和 npm audit。
• 🚦 --runtime：启动后端做接口 smoke test。
• 🔗 --dev：启动本地 Go 后端和 Vite 管理端做联调验证。
• 🗄️ --db：启动临时 PostgreSQL，验证系统 seed、模块表迁移和 CRUD。
• 🐳 --compose：构建并启动 Docker Compose，验证 PostgreSQL、Redis、后端、管理端和 Nginx /api 代理。

🔌 第三方对接

mino integration init --name payment-gateway --title 支付网关 --cwd <project-root>

生成文件位于 docs/integrations/<name>.md，用于沉淀外部系统地址、鉴权签名、接口清单、回调幂等、字段映射、错误码和验收清单。

🧪 Skill 与自检

mino skill list
mino skill install mino-module
mino self-test --quick
npm run self-test
npm pack --dry-run

self-test --quick 用于快速逻辑回归。npm run self-test 会覆盖发布包安装、Skill 安装、模块生成、runtime/dev/db smoke test 和 rollback，发布前建议执行。

📐 模块规格

最小模块规格：

{
  "name": "insurance",
  "model": "Insurance",
  "title": "保险产品",
  "api": "insurances",
  "route": "insurances",
  "permission": "insurance",
  "fields": [
    {
      "name": "name",
      "label": "名称",
      "type": "string",
      "required": true,
      "list": true,
      "search": true,
      "form": true
    },
    {
      "name": "price",
      "label": "价格",
      "type": "money",
      "list": true,
      "search": true,
      "form": true
    }
  ]
}

常用字段类型：

string, int, uint, int64, float64, bool, time, money, image, file, richtext, dict, enum, dateRange

常用模块类型：

• 📄 type: "readonly"：只读模块，适合审计日志、同步记录、外部数据查询。
• 🌳 type: "tree"：树表模块，适合分类、部门、菜单等层级数据。
• 🧾 type: "master-detail"：主子表模块，适合订单和明细、单据和行项目。

常用功能开关：

{
  "features": {
    "create": true,
    "update": true,
    "delete": true,
    "export": true,
    "import": true
  }
}

更多示例见：

• 🧪 examples/insurance.module.json
• 📄 examples/audit-log-readonly.module.json
• 🌳 examples/category-tree.module.json
• 🧾 examples/purchase-order-master-detail.module.json

🗂️ 生成项目结构

backend/                  Go Gin/GORM 后端
admin/                    React/Vite/Ant Design 管理端
miniapp/                  小程序端占位和可选生成目录
docker-compose.yml        PostgreSQL、Redis、后端、管理端容器编排
docs/                     架构、接口、数据库、权限、部署、排障、对接规范
specs/                    模块规格和关键变更记录
openapi/                  OpenAPI 汇总与模块片段
.mino/modules.json        已接入模块清单
scripts/mino.mjs          项目内 Mino CLI 代理
AGENTS.md                 Agent 工作规则

生成项目根目录会包含轻量 package.json，常用入口：

npm run doctor
npm run verify
npm run verify:quick
npm run verify:runtime
npm run verify:dev
npm run verify:db
npm run verify:compose
npm run backend:dev
npm run admin:dev
npm run compose:up
npm run compose:down

📚 文档体系

入口文档：

• 🧭 文档系统设计.md
• 🗺️ docs/文档索引.md
• 🚧 docs/路线图.md

生成项目中的文档分工：

• docs/：长期稳定的技术规范，例如架构、接口、数据库、权限、前端、后端、部署、排障、第三方对接。
• specs/：关键业务规格和变更记录，例如模块字段、接口、权限、状态流转、数据规则。

沉淀边界：

• ✅ 数据结构、接口、权限、状态流转、第三方对接、关键业务规则需要沉淀。
• ➖ 普通页面微调、一次性样式调整、低风险 vibe coding 不强制沉淀。

🛠️ 开发

脚手架源码自检：

node --check bin/mino.mjs
node --check scripts/generate-module.mjs
node bin/mino.mjs self-test --quick
npm run self-test
npm pack --dry-run

当前最终验收链路已经通过：

mino create final-run-app --out /tmp --module example.com/final-run-app
mino module apply --spec examples/insurance.module.json --cwd /tmp/final-run-app
mino module apply --spec examples/purchase-order-master-detail.module.json --cwd /tmp/final-run-app
mino verify --cwd /tmp/final-run-app --db
mino verify --cwd /tmp/final-run-app --compose

📄 许可证

当前仓库尚未声明许可证。发布到 npm 或开源前，建议先补充 LICENSE 和 package.json 的 license 字段。