# Muggles

**Repository Path**: sinall/muggles

## Basic Information

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

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-07-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Muggles · 麻瓜

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

**麻瓜**（Muggles）是面向 FP 项目的 AI 交付与研发 Harness。它保留需求评估、工作量、管理表和设计文档等可复用 Skills，并为 OpenCode、Codex、Claude Code 提供统一规则、工作区初始化、持久项目上下文和确定性验证。

## 为什么需要 Muggles？

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

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

## 从交付件到开发

Muggles 将 FP 前期和研发实施连接为一条可审查的链路：

```text
SoW / 需求清单
  → 项目评估、工作量和管理表
  → 需求与设计交付件
  → 人工确认的开发输入
  → 有效项目上下文与 Coding Agent
  → 编码、构建、测试和验证
  → 测试及最终交付件
```

设计类 Skill 生成的文档是后续开发的重要输入，但不会自动成为“已经实现”的事实；当前源码、真实构建和测试结果仍用于最终验证。

## 技能矩阵

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

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

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

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

| 阶段 | 技能名称 | 功能 | 交付件类型 | 状态 |
|------|---------|------|-----------|------|
| 评估 | [evaluating-projects](./skills/evaluating-projects/SKILL.md) | 基于 SoW/RFP 生成项目评估、风险分析、AI 参与分析和答疑问题报告 | 项目级 ×1 | 🧪 已引入 |
| 需求 | [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 | 📋 规划中 |

## 应用场景

Muggles 面向 FP 项目的两个连续阶段提供两类平级场景：

| 场景 | 项目阶段 | 主要产出 |
|---|---|---|
| FP 交付件生成 | 项目前期与交付准备 | 项目评估、工作量、管理表、设计文档 |
| 客户项目需求开发 | 研发实施 | OpenSpec 需求基线、代码实现、构建测试与验证结论 |

前一场景产生的需求和设计交付件经过人工确认后，可以作为后一场景的开发输入。

### 场景一：FP 交付件生成

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

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

**方式二：按需生成单个交付件**
1. **收到 SoW/RFP，需要项目前期评估** → 使用 `evaluating-projects` 生成项目评估报告、风险清单和答疑问题
2. **收到需求列表 Excel** → 使用 `workload-estimation` 自动计算规模、人天、人月，生成带公式的工作效率表
3. **需要综合管理表** → 使用 `project-management-excel` 基于模板自动生成管理表，将需求数据批量填入
4. **需要模块设计文档** → 使用 `module-design` 从需求列表自动生成每个需求的模块设计 Markdown 文档
5. **后续（规划中）** → 测试用例、验收文档……逐步覆盖整个交付流程

> 注：`evaluating-projects` 当前按“先引入，后完善”方式纳入项目。它暂不依赖 `workload-estimation` 的人月结果；工作量和人员结构结论仍需基于 SoW 内容人工复核。

### 场景二：客户项目需求开发

使用 Muggles 开发 OpenHarmony、FP 等客户项目的具体需求时，先判断当前属于需求首版开发，还是在已确认基线上的实现迭代。

#### 需求首版开发：OpenSpec 工作流

正式需求第一次开发时，使用 OpenSpec 建立可追踪的需求基线：

```mermaid
%%{init: {"flowchart": {"nodeSpacing": 48, "rankSpacing": 18}}}%%
flowchart LR
    S1["① 分析需求
• 阅读正式需求
• 分析参考实现
• 检查当前源码"]
    S2["② 建立需求基线
• Proposal / Spec 制品
• Design / Tasks 清单
• 明确验收条件"]
    S3["③ 确认并实施
• 人工确认范围
• Apply 实施任务
• 跟踪完成状态"]
    S4["④ 验证和归档
• OpenSpec 校验
• 构建测试验证
• 自审并归档"]
    S1 ---> S2 ---> S3 ---> S4

    style S1 text-align:left,text-anchor:start
    style S2 text-align:left,text-anchor:start
    style S3 text-align:left,text-anchor:start
    style S4 text-align:left,text-anchor:start
```

> 明确的人工确认点：进入“③ 确认并实施”前，由人确认需求理解、验收条件、仓库范围和实施计划。

OpenSpec 负责首版需求基线。先建立正式需求、设计、参考实现、源码和代码索引之间的证据链，再由人确认范围和计划并授权实施。

OpenSpec 和 CodeGraph 均采用“优先使用、允许降级”：首版实现优先用 OpenSpec 固化基线，代码阅读优先用 CodeGraph 缩小源码和调用链范围；工具不可用或开发人员不采用时，分别降级到普通需求分析/实施计划以及 `rg`/直接源码阅读，不阻断开发，也不作为 `just verify` 的硬门禁。

#### 既有实现迭代：多轮协作流程

在不改变需求基线的前提下，问题修复、实现优化、测试补充和文档完善采用三轮协作：

```mermaid
%%{init: {"flowchart": {"nodeSpacing": 56, "rankSpacing": 18}}}%%
flowchart LR
    R1["① 分析问题
• 复现和定位
• 评估影响范围
• 确定验证方法"]
    R2["② 确认计划并调整
• 人工确认范围
• 实施优化或修补
• 分阶段验证"]
    R3["③ 自审和收口
• 检查代码差异
• 构建测试验证
• 整理完成结论"]
    R1 ---> R2 ---> R3

    style R1 text-align:left,text-anchor:start
    style R2 text-align:left,text-anchor:start
    style R3 text-align:left,text-anchor:start
```

> 如果既有实现迭代改变了需求范围、接口、验收标准或架构决策，应停止当前调整，返回“需求首版开发”流程，更新或新建 OpenSpec change。

通用术语、参数化话术和多仓库边界参见 [客户项目需求开发指南](CONSUMER-PROJECT-REQUIREMENT-DEVELOPMENT.md)。

## 安装 Muggles 插件

### 前置条件

- Python 3.8+
- Git
- Linux 或 macOS 的 x86_64/aarch64 环境
- OpenCode、Codex、Claude Code 中至少一种 AI Agent CLI

Muggles 主要在 AI Agent CLI 内使用。每个 Agent 需要分别安装一次插件；普通使用者无需克隆
Muggles 仓库、创建 Skill 软链接或配置额外的 `PATH`。

当前尚未发布稳定版本，安装和升级均使用 `master` 开发通道。团队试用稳定后再发布带版本标签的正式版。

### OpenCode

使用 OpenCode 的原生插件命令安装，然后重启 OpenCode：

```bash
opencode plugin "muggles@git+https://gitee.com/sinall/muggles.git#master" --global
```

该命令会维护全局 `opencode.json`。等价配置如下，主要用于排障：

```json
{
  "plugin": [
    "muggles@git+https://gitee.com/sinall/muggles.git#master"
  ]
}
```

保留文件中已有的模型、Provider 和其他插件配置。详细迁移与排障说明参见
[OpenCode 安装指南](.opencode/INSTALL.md)。

### Codex

```bash
codex plugin marketplace add https://gitee.com/sinall/muggles.git --ref master
codex plugin add muggles@muggles
```

安装后启动 Codex 并新建会话。也可以在 Codex 的 `/plugins` 中查看、启用或卸载插件。

### Claude Code

```bash
claude plugin marketplace add https://gitee.com/sinall/muggles.git
claude plugin install muggles@muggles
```

### 升级 Muggles

需要升级时，在当前 Agent 中直接说：

```text
使用 updating-muggles Skill 将 Muggles 更新到最新 master。
```

升级只作用于当前 Agent，完成后新建会话生效。也可直接使用当前 Agent 的原生插件管理器更新。

## 开始使用 Muggles

### 快速开始：首次配置

以下流程从 Muggles 插件安装完成后的新 Agent 会话开始。开始前请确认：

- 已安装 OpenCode、Codex 或 Claude Code 中至少一种 AI Agent CLI，并按上文安装 Muggles。
- OpenHarmony 源码已通过 Repo 检出，源码根目录下存在有效的 `.repo/`；Muggles 不负责下载源码。
- 已确定交付工作区、客户项目名和 OpenHarmony 源码工作区。

插件安装或升级不会创建 `~/.muggles`；该目录只会在项目配置获得确认并正式写入时创建。

#### 1. 准备目录并启动 Agent

```bash
DELIVERY_WORKSPACE=/path/to/projects
PROJECT_NAME=project-1
SOURCE_WORKSPACE=/path/to/openharmony

mkdir -p "$DELIVERY_WORKSPACE/$PROJECT_NAME/SoW"
cp /path/to/工作任务书.docx "$DELIVERY_WORKSPACE/$PROJECT_NAME/SoW/"
cp /path/to/工作任务书.xlsx "$DELIVERY_WORKSPACE/$PROJECT_NAME/SoW/"
cd "$DELIVERY_WORKSPACE/$PROJECT_NAME"

# 选择一个已安装的 AI Agent CLI：opencode、codex 或 claude
CODING_AGENT=codex
"$CODING_AGENT"
```

`SOURCE_WORKSPACE` 用于确认源码位置，首次配置时把它告诉 Agent；无需在当前 Shell 中导出给
Muggles。

#### 2. 初始化项目配置

在新会话中发送：

```text
使用 configuring-muggles 初始化项目配置。

交付工作区是 /path/to/projects，
项目名是 project-1，
OpenHarmony 源码工作区是 /path/to/openharmony。

请从 Repo manifest 中列出仓库并让我选择，先预览完整配置，待我确认后再写入。
```

Agent 会通过 `repo list` 读取 manifest 中的仓库名，询问本项目允许操作哪些仓库，并展示
完整 JSON。确认写入后，Muggles 才会创建 `~/.muggles/config.json`。

#### 3. 验证项目上下文

```text
使用 configuring-muggles 显示当前有效项目上下文，并检查各仓库及 CodeGraph 状态。
```

确认输出中的项目、交付目录、源码目录和仓库范围正确后，再开始交付或开发工作。

#### 4. 可选：初始化源码工作区规则

如果希望在 OpenHarmony 根目录写入公共 Agent 规则，可以发送：

```text
使用 Muggles 初始化 /path/to/openharmony 源码工作区，先预览将要写入的规则，待我确认后再应用。
```

该操作与创建 `~/.muggles/config.json` 无关，可以跳过。Agent 会解析已安装的 Muggles
插件位置，预览公共规则和 OpenHarmony 通用规则的写入计划；已有不同文件不会被静默覆盖。

**手工兜底**

仅当 Agent 无法执行源码工作区初始化时，才在 OpenHarmony 根目录手工运行：

```bash
python3 "<MUGGLES_PLUGIN_ROOT>/bootstrap.py" workspace init \
  --workspace "$PWD" \
  --check
```

检查输出后移除 `--check` 再执行。

#### 5. 开始第一个任务

配置验证完成后，可以直接使用以下提示词：

- **生成全套交付件**：`使用 deliverable-suite 生成所有交付件。`
- **建立首版实现基线**：`使用 Muggles 分析 RM.001，并按 OpenSpec 建立首版实现基线。`
- **开始既有实现迭代**：`显示当前有效项目上下文，然后分析 RM.001，并给出实施计划。`

三种 CLI 使用同一批 Muggles Skills、Python 脚本和 `just` 命令。

### 日常启动

首次配置完成后，可以从交付目录或源码目录启动 Agent。

#### 客户项目目录启动

适合处理 SoW、需求、设计、项目管理和交付件：

```bash
cd /path/to/projects/project-1
codex
```

#### OpenHarmony 源码目录启动

适合编码、构建和测试，可以从 OpenHarmony 根目录或 Repo 子仓库启动：

```bash
cd /path/to/openharmony
codex
```

进入会话后先发送：

```text
使用 configuring-muggles 显示当前有效项目上下文。
```

当前目录不能确定客户项目时使用唯一的 `default_project`，也可以在会话中明确指定其他
项目。Muggles 不内置具体产品、子系统或仓库组合。

### 交付工作区

一个交付工作区可以管理多个客户项目。通常一次只进入其中一个项目开展工作；其他项目保留为独立目录：

```text
<delivery-workspace>/                       ← 交付工作区
├── <project-name-1>/                       ← 当前客户项目
│   ├── SoW/                                ← 客户输入
│   │   ├── XXX项目-工作任务书.docx
│   │   └── XXX项目-工作任务书.xlsx
│   ├── openspec/                           ← 首版需求基线和变更记录
│   ├── 需求与设计/                         ← 已确认的需求和设计输入
│   ├── 项目管理/                           ← 内部管理文档（Skill 输出）
│   └── 交付件/                             ← 客户交付文档
└── <project-name-2>/                       ← 其他客户项目
```

交付工作区保存项目资料和交付件，不等同于源码工作区。当前配置模型使用一个交付工作区和一个 OpenHarmony 源码工作区；多个客户项目可以复用同一个源码工作区，并各自限定允许操作的 Repo 仓库。

### 持久项目上下文

Muggles 将本机唯一的运行时配置保存在 `~/.muggles/config.json`。首次配置应使用快速开始中的
`configuring-muggles` 流程；必要时也可以手动编辑：

```json
{
  "schema_version": 1,
  "default_project": "project-1",
  "delivery_workspace": {
    "root": "/path/to/projects"
  },
  "source_workspace": {
    "root": "/path/to/openharmony"
  },
  "projects": {
    "project-1": {
      "repositories": [
        "repository-a",
        "repository-b"
      ]
    }
  }
}
```

项目名同时是交付工作区下的直接子目录名，因此 `project-1` 固定对应
`/path/to/projects/project-1`，无需重复配置项目路径。
`repositories` 使用当前有效 Repo manifest 的 `project.name`。Muggles 通过 `repo list`
解析实际检出路径，不在配置中重复保存仓库路径。CodeGraph 遵循 convention：数据库固定
查找 `<repository>/.codegraph/codegraph.db`；不存在时降级到 `rg`、Git 和直接源码阅读。

## Muggles 维护与开发

### 维护者环境

只有开发 Muggles 本身时才需要源码仓库：

```bash
git clone https://gitee.com/sinall/muggles.git
cd muggles
python3 bootstrap.py --check
python3 bootstrap.py --yes
export PATH="$HOME/.local/bin:$PATH"
just doctor
just verify
```

Harness 核心只使用 Python 标准库。FP Excel/Word Skills 需要的 `openpyxl`、`python-docx` 按具体
Skill 安装。

### 开发指南

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

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

完成修改前运行统一门禁：

```bash
just verify
```

## 文档

- [AGENTS.md](AGENTS.md) — AI Agent 开发指南（技能模板、代码规范、测试要求）
- [项目总览](docs/project-overview.md) — 技能体系、开发原则
- [团队使用指南](docs/team-guide.md) — FP 到研发的统一流程和边界
- [模板体系设计](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) — 开发方法论

## 许可证

Apache License 2.0，详见 [LICENSE](LICENSE)。整合前 Muggles 代码的 MIT 许可声明保存在 [LICENSES/MIT.txt](LICENSES/MIT.txt)。

---

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