# 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-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Muggles

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

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

## 简介

Muggles 是一个 AI Agent 技能库，专为固定价格 (FP) 外包项目设计。与通用 AI 工具不同，Muggles 的技能确保：

- **确定性交付** - 在合同范围内提供可预测的结果
- **合同合规** - 严格遵守商定的需求
- **务实方法** - 实用解决方案优于理论完美

## 核心理念

我们拒绝不可控的"魔法"，拥抱务实的工匠精神。每个技能都经过精心设计，确保交付的内容与承诺完全一致——不多不少。

## 安装

### 前置条件

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

### 快速安装

告诉 OpenCode：

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

### 手动安装

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

2. **注册插件**
   ```bash
   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
    应该看到 muggles 的技能列表
    ```

## 使用方法

安装后，在 OpenCode 中可以直接使用 muggles 技能，无需特定提示词：

### 自动匹配

当你提到 FP 项目、工作量评估等关键词时，AI 会自动检查并使用相关技能。例如：

```
"帮我评估这个 FP 项目的 Excel 需求"
```

AI 会自动调用 `use_muggles_skill` 加载 `workload-estimation` 技能。

### 手动工具

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

### 版本固定

安装特定版本：
```bash
git clone --branch v1.0.0 https://gitee.com/sinall/muggles.git ~/.config/opencode/muggles
```

### 更新

```bash
cd ~/.config/opencode/muggles
git pull
```

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

## 可用技能

技能位于 `./skills` 目录。每个技能包含一个 `SKILL.md` 文件，提供详细的使用说明。

| 技能名称 | 描述 |
|---------|------|
| [workload-estimation](./skills/workload-estimation/SKILL.md) | 项目工作量评估 - 处理需求列表 Excel，自动计算规模、人天、人月等指标 |

## 开发指南

### 创建新技能

1. 在 `skills/` 目录下创建新目录
2. 编写 `SKILL.md` 文件
3. 测试技能
4. 提交 Pull Request

详细的开发指南请参阅 [AGENTS.md](AGENTS.md)。

### SKILL.md 结构

每个技能应包含：

- **概述** - 技能的作用和原因
- **何时使用** - 触发条件
- **步骤** - 可执行的指令
- **验证清单** - 确认成功的方法
- **常见错误** - 问题和解决方案

## 参与贡献

1. Fork 本仓库
2. 新建 `feat/skill-name` 分支
3. 遵循 [AGENTS.md](AGENTS.md) 中的开发流程
4. 充分测试
5. 提交 Pull Request

确保您的技能：
- 遵循模板结构
- 有完整的验证清单
- 包含可工作的示例
- 在干净环境中测试过

## 文档

### 项目管理
- [项目总览](docs/project-overview.md) - 项目简介、技能体系、开发原则
- [模板体系设计](docs/template-system.md) - 多层级模板架构、部门模板管理
- [协作指南](docs/collaboration-guide.md) - Git 工作流、PR 流程、代码审查
- [技能开发规范](docs/skill-development.md) - 开发流程、代码规范、测试要求

### 其他
- [AGENTS.md](AGENTS.md) - AI Agent 开发指南
- [模板使用说明](templates/README.md) - 模板查找、占位符规范
- [.opencode/README.md](.opencode/README.md) - OpenCode 配置说明
- [变更日志](CHANGELOG.md) - 版本历史

## 资源

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

## 许可证

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

---

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