# Muggles

**Repository Path**: sinall/muggles

## Basic Information

- **Project Name**: Muggles
- **Description**: 专为固定价格 (Fixed Price) 外包打造的 AI Agent 技能库。拒绝不可控的“魔法”，只做严守合同范围、确保确定性交付的务实工匠。

- **Primary Language**: Shell
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-04-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Muggles · 麻瓜

[English](README.en.md) | 中文

**麻瓜**（Muggles）——专为固定价格 (Fixed Price) 外包项目打造的 AI Agent 技能库。配合 [OpenCode](https://opencode.ai) 使用，一句话自动完成需求评估、管理表生成、文档编写等重复工作。

## 为什么需要 Muggles？

FP 外包项目有大量重复性文档工作：评估工作量、生成管理表、编写设计文档、制作测试用例……这些工作格式固定、依赖模板，但手动操作耗时且容易出错。

麻瓜把这些重复工作封装为 **可复用的 AI 技能**，每个技能都是确定性的——相同的输入，永远得到相同的输出。不多不少，与合同承诺完全一致。

## 技能矩阵

按项目交付流程，Muggles 规划了以下技能：

| 阶段 | 技能名称 | 功能 | 状态 |
|------|---------|------|------|
| 需求 | [workload-estimation](./skills/workload-estimation/SKILL.md) | 处理需求列表 Excel，自动计算规模、人天、人月等指标 | ✅ 已完成 |
| 管理 | [project-management-excel](./skills/project-management-excel/SKILL.md) | 从需求列表生成项目综合管理表（基于模板填充） | ✅ 已完成 |
| 设计 | [module-design](./skills/module-design/SKILL.md) | 从需求列表生成模块设计文档（基于模板填充） | ✅ 已完成 |
| 测试 | test-design | 测试设计（脑图） | 📋 规划中 |
| 测试 | test-case-generator | 测试用例生成 | 📋 规划中 |
| 测试 | test-report | 测试报告生成 | 📋 规划中 |
| 交付 | acceptance-document | 验收文档生成 | 📋 规划中 |

## 典型场景

以一个 FP 项目为例，Muggles 可以这样帮你：

1. **收到需求列表 Excel** → 使用 `workload-estimation` 自动计算规模、人天、人月，生成带公式的工作效率表
2. **需要综合管理表** → 使用 `project-management-excel` 基于模板自动生成管理表，将需求数据批量填入
3. **需要模块设计文档** → 使用 `module-design` 从需求列表自动生成每个需求的模块设计 Markdown 文档
4. **后续（规划中）** → 测试用例、验收文档……逐步覆盖整个交付流程

## 安装

### 前置条件

- [OpenCode](https://opencode.ai) 已安装
- Git 已安装

### 快速安装

告诉 OpenCode：

```
Fetch and follow instructions from https://gitee.com/sinall/muggles/raw/master/.opencode/INSTALL.md
```

### 手动安装

```bash
# 1. 克隆仓库
mkdir -p ~/.config/opencode/muggles
git clone https://gitee.com/sinall/muggles.git ~/.config/opencode/muggles

# 2. 注册插件
mkdir -p ~/.config/opencode/plugin
ln -sf ~/.config/opencode/muggles/.opencode/plugin/muggles.js ~/.config/opencode/plugin/muggles.js

# 3. 重启 OpenCode

# 4. 验证（在 OpenCode 中执行 find_muggles_skills，应看到技能列表）
```

详细安装说明请参阅 [.opencode/INSTALL.md](.opencode/INSTALL.md)。

## 使用方法

### 项目目录结构

每个 FP 项目遵循统一的目录约定：

```
项目一/                        ← 项目工作目录
├── SoW/                       ← Statement of Work，需求列表
│   └── XXX项目_需求列表.xlsx
└── 项目管理/                   ← skill 输出（自动创建）
    ├── XXX项目_需求列表_工作量评估.xlsx
    ├── XXX项目综合管理.xlsx
    └── ...
```

### 快速开始

```bash
# 1. 创建项目目录
mkdir -p 项目一/SoW

# 2. 放入需求列表
cp /path/to/需求列表.xlsx 项目一/SoW/

# 3. 进入项目目录，启动 OpenCode
cd 项目一
opencode

# 4. 在 OpenCode 中使用 skill
"帮我评估工作量"              → 自动生成 项目管理/XXX_工作量评估.xlsx
"帮我生成综合管理表"           → 自动生成 项目管理/XXX综合管理.xlsx
```

详细使用说明请参阅 [安装指南](.opencode/INSTALL.md)。

### 手动工具

- **`find_muggles_skills`** — 列出所有可用技能
- **`use_muggles_skill`** — 加载指定技能（参数：`skill_name`）

### 版本固定与更新

```bash
# 固定版本
git clone --branch v1.0.0 https://gitee.com/sinall/muggles.git ~/.config/opencode/muggles

# 更新
cd ~/.config/opencode/muggles && git pull
```

## 开发指南

详见 [AGENTS.md](AGENTS.md)。简要流程：

1. 在 `skills/` 下创建目录，编写 `SKILL.md`
2. 测试技能（含验证清单）
3. 提交 Pull Request

## 文档

- [AGENTS.md](AGENTS.md) — AI Agent 开发指南（技能模板、代码规范、测试要求）
- [项目总览](docs/project-overview.md) — 技能体系、开发原则
- [模板体系设计](docs/template-system.md) — 多层级模板架构
- [协作指南](docs/collaboration-guide.md) — Git 工作流、PR 流程
- [技能开发规范](docs/skill-development.md) — 开发流程与规范
- [测试指南](docs/testing-guide.md) — 本地测试各 skill 的方法
- [模板使用说明](templates/README.md) — 模板查找与占位符
- [变更日志](CHANGELOG.md) — 版本历史

## 资源

- [OpenCode 文档](https://opencode.ai/docs/) — 平台文档
- [Superpowers 框架](https://github.com/obra/superpowers) — 开发方法论

## 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

---

*麻瓜——拒绝魔法，拥抱确定性。*