# MGR

**Repository Path**: NelsonLong/mgr

## Basic Information

- **Project Name**: MGR
- **Description**: MGR - 综合性数据管理平台
CLI-First 的本地综合数据管理平台，管理客户信息、密钥凭据、项目进度和财务记录。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: https://gitee.com/NelsonLong/mgr
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 2
- **Created**: 2026-04-21
- **Last Updated**: 2026-04-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MGR — AI 原生的一人公司数据中枢

> 🧠 让 AI 智能体帮你管理客户、项目、密钥、设备和财务

[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/License-AGPL--3.0%20%2B%20Commercial-blue.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-v0.1.0-orange.svg)](pyproject.toml)

---

## 🤖 为什么叫「AI 原生」？

MGR 从第一天起就为 AI 智能体协作而设计：

- **CLI-First 架构** — 每个操作都是一条命令，AI 助手可以直接调用，无需 GUI 操作
- **结构化输出** — 所有命令支持 `--json` 输出，AI 解析零障碍
- **Claude Skill 配套** — 内置项目技能文件，AI 加载后即懂全部命令和数据约定
- **自然语言驱动** — 对 AI 说"帮我查一下张三的尾款"，它自动执行 `mgr search "张三"` → `mgr payment list --project-id`

```bash
# 你对 AI 说的话 → AI 自动执行的命令
"新增客户李四，电话13900001111"     → mgr contact add --name "李四" --phone "13900001111"
"本月在做的项目有哪些"              → mgr project list --status "进行中" --json
"王总还欠多少钱"                    → mgr stats finance --period month
"服务器密码是什么"                  → mgr secret get 5
```

**MGR 不只是一个数据库工具 — 它是你 AI 助手的「业务知识库」。**

---

## ✨ 核心功能

| 模块 | 能力 | 亮点 |
|------|------|------|
| 🧑‍💼 联系人管理 | CRUD + 搜索 + 标签 | 多维度筛选、个人档案、备注记忆、关联关系、财务汇总 |
| 🖥️ 设备管理 | 机器/云主机清单 | IP、配置、在线状态、客户关联 |
| 🔐 密钥保险箱 | 加密凭据存储 | AES-256-GCM、6种分类、解密导出 |
| 📋 项目看板 | 项目全生命周期 | 报价→进行中→完工、进度百分比 |
| 💰 财务追踪 | 收支记录+报表 | 定金/尾款、按月/季汇总、佣金管理 |
| 🎯 线索管理 | 潜在客户跟踪 | 线索来源、状态流转、转化漏斗 |
| 🔗 关系图谱 | 实体关联管理 | 多对多关系、Mermaid 可视化 |
| 📝 审计追踪 | 变更记录+对比 | 字段级 diff、时间线视图、操作回溯 |
| 📔 日记模块 | 文件式日记+索引 | Markdown 编辑、标签、分页、全文搜索 |
| 🌐 Web 界面 | 可视化仪表盘 | 单页应用、实时数据、收入趋势图、Token 认证 |

**延伸功能：** 全局搜索 · 数据统计 · 标签管理 · 批量导入导出 · Docker 部署 · 多 Profile 支持 · Hermes 智能体集成

---

## 📊 项目进度

### MVP（已完成 ✅）

| # | 功能 | 状态 |
|---|------|------|
| 1 | 数据库设计 + SQLite 初始化 | ✅ |
| 2 | AES-256-GCM 加密模块 | ✅ |
| 3 | 客户 CRUD + CLI | ✅ |
| 4 | 设备 CRUD + CLI | ✅ |
| 5 | 密钥 CRUD + 加密存储 | ✅ |
| 6 | 项目 CRUD + 进度管理 | ✅ |
| 7 | 支付记录 + 汇总 | ✅ |
| 8 | 备份恢复 | ✅ |
| 9 | Web 服务器 + REST API (26端点) | ✅ |
| 10 | 前端单页应用 | ✅ |
| 11 | CLI 命令整合 (typer) | ✅ |
| 12 | README + 文档 | ✅ |
| 13 | uv 包管理迁移 | ✅ |
| 14 | Claude Skill 指南 | ✅ |

### 延伸功能（已完成 ✅）

| # | 功能 | 状态 |
|---|------|------|
| E1 | CSV/JSON 批量导入导出 | ✅ |
| E2 | 全局模糊搜索 | ✅ |
| E3 | 数据统计与财务报表 | ✅ |
| E4 | 标签管理 + 批量操作 | ✅ |
| E5 | 操作日志审计 + 变更对比 | ✅ |
| E6 | 批量操作命令 | ✅ |
| E7 | 快捷操作 + 数据模板 | ✅ |
| E8 | Web 界面增强（收入趋势图、仪表盘告警） | ✅ |
| E9 | 数据关系图 (Mermaid) | ✅ |
| E10 | 多 Profile 支持（个人/公司多场景） | ✅ |

### 架构升级（已完成 ✅）

| # | 功能 | 状态 |
|---|------|------|
| A1 | SQLAlchemy ORM 模型 + Pydantic v2 校验 | ✅ |
| A2 | Alembic 数据库迁移 | ✅ |
| A3 | Service 业务逻辑层（CLI/API 共用） | ✅ |
| A4 | FastAPI REST API 层（30+ 端点） | ✅ |
| A5 | CLI 命令全面 `--json` 支持 | ✅ |
| A6 | 智能体专用命令（inspect/context/status） | ✅ |
| A7 | API Pydantic 校验 + Session 回滚安全 | ✅ |
| A8 | Web UI 重设计（商务网络管理平台） | ✅ |
| A9 | 联系人个人档案 + Memo 备忘录 | ✅ |
| A10 | 日记模块（ORM/Service/CLI/API/前端） | ✅ |
| A11 | Hermes 智能体插件集成（51 工具） | ✅ |
| A12 | 单元测试 + 集成测试 + 多阶段 Dockerfile | ✅ |

### 规划中 🔮

- [ ] 移动端响应式适配
- [ ] AI 自然语言接口（对话式操作）
- [ ] 多平台消息集成（微信/飞书/Telegram）

---

## 🚀 快速开始

```bash
# 克隆
git clone git@gitee.com:NelsonLong/mgr.git
cd mgr

# 安装依赖
uv sync

# 初始化（生成加密密钥 + 创建数据库）
uv run mgr init

# 启动 Web 界面
uv run mgr web --port 8080
```

### Docker 部署

```bash
docker compose up -d
# 访问 http://localhost:8228/?token=<your-token>
```

---

## 🛠️ 技术栈

| 组件 | 选择 | 理由 |
|------|------|------|
| CLI | typer + rich | 类型安全 + 美化输出 |
| 数据库 | SQLite3 | 零配置、单文件、够快 |
| 加密 | AES-256-GCM | 银行级安全标准 |
| Web 前端 | Alpine.js + Tailwind | 无构建工具、CDN 直引 |
| Web 后端 | FastAPI + uvicorn | 异步高性能、自动 API 文档 |
| ORM | SQLAlchemy + Alembic | 类型安全、自动迁移 |
| 数据校验 | Pydantic v2 | 请求校验、序列化 |
| 包管理 | uv | 极速安装、确定性锁 |
| 容器 | Docker + Alpine | 50MB 镜像、秒级启动 |

---

## 🤝 协同开发

MGR 是一个**开源探索项目**，欢迎各路开发者参与共建！

### 我们需要这样的你

- 🎨 **前端开发者** — 优化 Web 界面体验，移动端适配
- 🔧 **后端开发者** — API 增强、性能优化、新功能开发
- 🤖 **AI/LLM 爱好者** — 自然语言接口、智能分析、Agent 集成
- 📝 **文档/设计** — 用户体验优化、文档完善、Logo 设计
- 🌍 **用户体验** — 一人公司/自由职业者视角的功能建议

### 如何参与

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'feat: add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 提交 Pull Request

### Commit 规范

```
feat: 新功能
fix: 修复 Bug
docs: 文档更新
refactor: 代码重构
test: 测试相关
chore: 构建/工具变更
```

---

## 📬 联系方式

- **微信：** Nelson_LX1024
- **邮箱：** 1169207670@qq.com
- **Gitee：** [@NelsonLong](https://gitee.com/NelsonLong)

> 💬 欢迎加微信交流 — 无论是技术讨论、功能建议、还是单纯聊聊一人公司的生存之道。

---

## 👥 贡献者

感谢所有为 MGR 做出贡献的开发者：

| 贡献者 | 角色 | 微信 |
|--------|------|------|
| [龙翔](https://gitee.com/NelsonLong) | 🏗️ 创建者 & 核心开发 | Nelson_LX1024 |

> 🌟 **成为第一个贡献者！** Fork → 修改 → PR，你的名字就会出现在这里。

---

## 📄 许可证

**双许可：AGPL-3.0 + 商业许可**

- ✅ 个人学习、研究、非商业项目 — 自由使用和修改（遵循 AGPL-3.0）
- ✅ 修改后开源 — 欢迎提交 PR 贡献代码
- ❌ 商业用途（销售、商业产品集成、SaaS 托管等）— 需获取商业授权

详见 [LICENSE](LICENSE)。如需商业授权，请通过上述联系方式洽谈。

---

<p align="center">
  <b>每个超级个体都值得拥有一个自己的「数字大脑」</b><br>
  MGR — 让 AI 帮你管好生意的每一个细节 🧠
</p>