# 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-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Muggles · 麻瓜 [English](README.en.md) | 中文 **麻瓜**（Muggles）是面向 FP 项目的 AI 交付与研发 Harness。它保留需求评估、工作量、管理表和设计文档等可复用 Skills，并为 OpenCode、Codex、Claude Code 提供统一规则、工作区初始化、持久项目上下文和确定性验证。 ## 为什么需要 Muggles？ FP 外包项目有大量重复性文档工作：评估工作量、生成管理表、编写设计文档、制作测试用例……这些工作格式固定、依赖模板，但手动操作耗时且容易出错。 麻瓜把这些重复工作封装为 **可复用的 AI 技能**，每个技能都是确定性的——相同的输入，永远得到相同的输出。不多不少，与合同承诺完全一致。 AI Agent CLI 对话是 Muggles 的主要用户入口。Muggles 优先提供自然语言提示词，用户通过提示词调用 Skill；Skill 负责收集输入、预览变更、取得确认、调用确定性内部执行器并解释结果。命令和脚本是确定性内部执行器和手工故障兜底，不是普通用户的首要操作方式。 ## 从交付件到开发 Muggles 将 FP 前期和研发实施连接为一条可审查的链路： ```text SoW / 需求清单 → 项目评估、工作量和管理表 → 需求与设计交付件 → 人工确认的开发输入 → 有效项目上下文与 Coding Agent → 编码、构建、测试和验证 → 测试及最终交付件 ``` 设计类 Skill 生成的文档是后续开发的重要输入，但不会自动成为“已经实现”的事实；当前源码、真实构建和测试结果仍用于最终验证。 ## 技能矩阵 ### 项目交付技能 按项目交付流程合并为一张技能矩阵；表内分为编排技能和原子技能两组： #### 编排技能（一键生成全套交付件） [deliverable-suite](./skills/deliverable-suite/SKILL.md)：编排所有原子技能，基于 SoW 生成完整项目交付件包。 #### 原子技能（可独立使用）
阶段技能名称功能类型状态
评估evaluating-projects基于 SoW/RFP 生成项目评估、风险分析、AI 参与分析和答疑问题报告项目级 ×1🧪 已引入
需求workload-estimation处理需求列表 Excel，自动计算规模、人天、人月等指标项目级 ×1✅ 已完成
管理project-management-excel从需求列表生成项目综合管理表（基于模板填充）项目级 ×1✅ 已完成
设计module-design从需求列表生成模块设计文档（基于模板填充）按需求 ×N✅ 已完成
设计interface-design接口描述文档生成按需求 ×N📋 规划中
测试test-design测试设计文档生成按需求 ×N📋 规划中
测试test-case-generator测试用例生成按需求 ×N📋 规划中
测试test-report测试报告生成项目级 ×1📋 规划中
质量quality-plan质量策划报告生成项目级 ×1📋 规划中
### 研发支撑技能 这些 Skill 服务于源码开发流程，不直接生成项目交付件：
阶段技能名称功能类型状态
开发前configuring-muggles初始化和显示有效项目上下文研发支撑✅ 已完成
开发前checking-design-readiness检查需求设计文档是否满足开发门禁研发支撑✅ 已完成
需求开发developing-consumer-requirements协调需求分析、OpenSpec、实施和验证研发支撑✅ 已完成
开发后code-review审查代码变更的正确性、回归和范围合规性研发支撑✅ 已完成
开发后verification执行构建、测试、差异和结果验证研发支撑✅ 已完成
## 应用场景 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 建立可追踪的需求基线： 设计文档硬门禁先于所有开发活动：必须在客户项目目录找到与需求编号对应、内容完整且可读取的设计文档，并由人明确确认它是当前有效版本。门禁失败时停止，不开展需求分析、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；OpenSpec 不可用、初始化失败或 proposal 创建失败时停止，不降级到直接开发。代码阅读优先用 CodeGraph 缩小源码和调用链范围，CodeGraph 不可用时允许降级到 `rg`、Git 和直接源码阅读，并记录降级原因。 #### 既有实现迭代：多轮协作流程 既有实现迭代同样先通过设计文档硬门禁。在不改变需求基线的前提下，问题修复、实现优化、测试补充和文档完善采用三轮协作，不强制为每次调整新建 OpenSpec change： ```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` 开发通道。团队试用稳定后再发布带版本标签的正式版。 ### 在 AI Agent CLI 中安装（推荐） 在目标 Agent 的新会话中直接发送提示词，让 Agent 调用对应的原生插件管理器： ```text 请使用当前 AI Agent CLI 的原生插件管理器安装 Muggles： https://gitee.com/sinall/muggles.git#master ``` Agent 应先确认当前 CLI 和插件管理器，再展示将要执行的安装动作并取得确认。安装完成后重启 当前 Agent 会话。命令行安装方式保留为手工排障和恢复入口。 ### 命令行安装（手工/恢复） 以下命令适用于无法使用 Agent 对话安装，或需要手工排障和恢复的情况。
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/delivery/projects PROJECT_NAME=OpenHarmony开源合作共建项目 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/delivery/projects， 项目名是 OpenHarmony开源合作共建项目， OpenHarmony 源码工作区是 /path/to/openharmony。 产品名是 ipcamera_hispark_taurus， 已确认的构建命令是 ./build.sh --product-name ipcamera_hispark_taurus --ccache。 请从 Repo manifest 中列出仓库并让我选择，先预览完整配置和 CodeGraph 动作，待我确认后再写入并初始化缺失的 CodeGraph。 ``` Agent 会通过 `repo list` 读取 manifest 中的仓库名，询问本项目允许操作哪些仓库，并展示 完整 JSON。产品名和构建命令没有经过项目确认时可以省略；提供时必须成对配置。 确认后，Muggles 才会创建 `~/.muggles/config.json`、初始化项目 OpenSpec 和缺失的 CodeGraph；OpenSpec 产物默认要求使用中文，CodeGraph 失败不会回滚有效配置。 #### 3. 验证项目上下文 ```text 使用 configuring-muggles 显示当前有效项目上下文，并检查各仓库及 CodeGraph 状态。 ``` 确认输出中的项目、交付目录、源码目录和仓库范围正确后，再开始交付或开发工作。 #### 4. 可选：初始化源码工作区规则 如果希望在 OpenHarmony 根目录写入公共 Agent 规则，可以发送： ```text 使用 Muggles 初始化当前 OpenHarmony 源码工作区规则，先预览将要写入的规则，待我确认后再应用。 ``` 该操作与创建 `~/.muggles/config.json` 无关，可以跳过。Agent 会解析已安装的 Muggles 插件位置，预览公共规则和 OpenHarmony 通用规则的写入计划；已有不同文件不会被静默覆盖。 ##### 手工兜底 仅当 Agent 无法执行源码工作区初始化时，才在 OpenHarmony 根目录手工运行： ```bash python3 "/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/delivery/projects/OpenHarmony开源合作共建项目 codex ``` #### OpenHarmony 源码目录启动 适合编码、构建和测试，可以从 OpenHarmony 根目录或 Repo 子仓库启动： ```bash cd /path/to/openharmony codex ``` 进入会话后先发送： ```text 使用 configuring-muggles 显示当前有效项目上下文。 ``` 当前目录不能确定客户项目时使用唯一的 `default_project`，也可以在会话中明确指定其他 项目。Muggles 不内置具体产品、子系统或仓库组合。 ### 交付工作区 一个交付工作区可以管理多个客户项目。通常一次只进入其中一个项目开展工作；其他项目保留为独立目录： ```text / ← 交付工作区 ├── / ← 当前客户项目 │ ├── SoW/ ← 客户输入 │ │ ├── XXX项目-工作任务书.docx │ │ └── XXX项目-工作任务书.xlsx │ ├── openspec/ ← 首版需求基线和变更记录 │ ├── 需求与设计/ ← 已确认的需求和设计输入 │ ├── 项目管理/ ← 内部管理文档（Skill 输出） │ └── 交付件/ ← 客户交付文档 └── / ← 其他客户项目 ``` 交付工作区保存项目资料和交付件，不等同于源码工作区。当前配置模型使用一个交付工作区和一个 OpenHarmony 源码工作区；多个客户项目可以复用同一个源码工作区，并各自限定允许操作的 Repo 仓库。 ### 持久项目上下文 Muggles 将本机唯一的运行时配置保存在 `~/.muggles/config.json`。首次配置应使用快速开始中的 `configuring-muggles` 流程；必要时也可以手动编辑： ```json { "schema_version": 1, "default_project": "OpenHarmony开源合作共建项目", "delivery_workspace": { "root": "/path/to/delivery/projects" }, "source_workspace": { "root": "/path/to/openharmony" }, "projects": { "OpenHarmony开源合作共建项目": { "repositories": [ "repository-a", "repository-b" ], "product_name": "ipcamera_hispark_taurus", "commands": { "build": { "cwd": "source_workspace", "command": "./build.sh --product-name ipcamera_hispark_taurus --ccache" } } } } } ``` 项目名同时是交付工作区下的直接子目录名，因此 `OpenHarmony开源合作共建项目` 固定对应 `/path/to/delivery/projects/OpenHarmony开源合作共建项目`，无需重复配置项目路径。 `repositories` 使用当前有效 Repo manifest 的 `project.name`。Muggles 通过 `repo list` 解析实际检出路径，不在配置中重复保存仓库路径。CodeGraph 遵循 convention：数据库固定 查找 `/.codegraph/codegraph.db`；不存在时降级到 `rg`、Git 和直接源码阅读。 `product_name` 与 `commands` 是可选的项目级构建上下文，必须同时存在；当前支持 `build` 和 `test` 命令，工作目录使用 `source_workspace`。构建命令按单行字符串保存，便于用户 直接编辑；Muggles 使用 `shlex.split()` 校验并生成参数列表，不通过 Shell 执行，也不会在 读取配置时自动运行命令。 ## 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)。 --- *麻瓜——拒绝魔法，拥抱确定性。*