# 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-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Muggles · 麻瓜

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

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

## 为什么需要 Muggles？

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

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

## 技能矩阵

### 编排技能（一键生成全套交付件）

| 技能名称 | 功能 | 状态 |
|---------|------|------|
| [deliverable-suite](./skills/deliverable-suite/SKILL.md) | 编排所有原子技能，基于 SoW 生成完整项目交付件包 | ✅ 已设计 |

### 原子技能（可独立使用）

按项目交付流程的技能矩阵：

| 阶段 | 技能名称 | 功能 | 交付件类型 | 状态 |
|------|---------|------|-----------|------|
| 需求 | [workload-estimation](./skills/workload-estimation/SKILL.md) | 处理需求列表 Excel，自动计算规模、人天、人月等指标 | 项目级 ×1 | ✅ 已完成 |
| 管理 | [project-management-excel](./skills/project-management-excel/SKILL.md) | 从需求列表生成项目综合管理表（基于模板填充） | 项目级 ×1 | ✅ 已完成 |
| 设计 | [module-design](./skills/module-design/SKILL.md) | 从需求列表生成模块设计文档（基于模板填充） | 按需求 ×N | ✅ 已完成 |
| 设计 | interface-design | 接口描述文档生成 | 按需求 ×N | 📋 规划中 |
| 测试 | test-design | 测试设计文档生成 | 按需求 ×N | 📋 规划中 |
| 测试 | test-case-generator | 测试用例生成 | 按需求 ×N | 📋 规划中 |
| 测试 | test-report | 测试报告生成 | 项目级 ×1 | 📋 规划中 |
| 质量 | quality-plan | 质量策划报告生成 | 项目级 ×1 | 📋 规划中 |

## 典型场景

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

**方式一：一键生成全套交付件（推荐）**
1. **准备好 SoW**（工作任务书 Word + Excel 需求清单）
2. **使用 `deliverable-suite`** → 自动按顺序调用所有原子技能，生成完整交付件包
3. **AI 自动填充** → 模块设计、测试设计等需要智能生成的部分由 AI 逐个完成

**方式二：按需生成单个交付件**
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项目-工作任务书.docx  ← Word 版 SoW（含背景、范围、目标）
│   └── XXX项目-工作任务书.xlsx  ← Excel 需求清单
├── 项目管理/                   ← 内部管理文档（skill 输出）
│   ├── XXX项目_工作量评估.xlsx
│   └── XXX项目综合管理.xlsx
└── 交付件/                     ← 客户交付文档（skill 输出）
    ├── 01 开发设计文档/         ← 模块设计、接口设计（按需求 ×N）
    ├── 02 测试设计文档/         ← 测试设计（按需求 ×N）
    ├── 03 测试用例/            ← 测试用例（按需求 ×N）
    ├── 04 测试报告/            ← 测试报告（项目级 ×1）
    └── 05 质量策划/            ← 质量策划报告（项目级 ×1）
```

### 快速开始

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

# 2. 放入 SoW 文件
cp /path/to/工作任务书.docx 项目一/SoW/
cp /path/to/工作任务书.xlsx 项目一/SoW/

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

# 4. 在 OpenCode 中使用 skill
"生成所有交付件"               → 使用 deliverable-suite 编排生成全套
"帮我评估工作量"              → 自动生成 项目管理/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) 文件

---

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