# 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**: 1 - **Forks**: 1 - **Created**: 2026-03-19 - **Last Updated**: 2026-09-30 ## 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 生成人力模型 Excel、HTML 项目评估、风险/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📋 规划中
### FP 人力招聘技能 [招聘 Skill 使用指南：从简历提取到跟踪表维护](./skills/openharmony-recruiting/README.md)。 [openharmony-recruiting](./skills/openharmony-recruiting/SKILL.md)：管理 OpenHarmony C/C++、ArkTS 招聘 JD 与典型画像，依据简历填写高/中/低匹配度及判断口径，并生成保留人工记录的新版本跟踪表。 HR 仅提供简历时，可直接获得文本形式的候选人资料、匹配度和判断依据，无需明细表。 招聘资料保存在招聘工作目录，无需先配置源码工作区；团队默认 JD 与规则随 Skill 维护。 ```text 请使用 openharmony-recruiting Skill，按当前 JD 评估简历，排除归档候选人， 填写匹配度（AI）和判断口径（AI），在原目录生成新的 V 版 Excel。 ``` ### 研发支撑技能 这些 Skill 服务于源码开发流程，不直接生成项目交付件：
阶段技能名称功能类型状态
开发前configuring-muggles初始化和显示有效项目上下文研发支撑✅ 已完成
开发前checking-design-readiness检查需求设计文档是否满足开发门禁研发支撑✅ 已完成
需求开发developing-consumer-requirements协调需求分析、OpenSpec、实施和验证研发支撑✅ 已完成
开发后code-check执行变更行范围内的确定性格式和编码规范检查研发支撑🧪 初版
开发后code-review审查代码变更的正确性、回归和范围合规性研发支撑✅ 已完成
开发后verification执行构建、测试、差异和结果验证研发支撑✅ 已完成
## 项目专用技能 以下 Skill 随 Muggles 提供，包含特定项目的验收要求和流程约定。 仅在对应项目内使用，不作为所有项目的通用开发流程。 | 技能分组 | 适用项目 | 内容 | |---|---|---| | [三方库质量加固相关 Skills](./docs/third-party-quality-hardening-skills.md) | 开源三方库鸿蒙化开发与质量加固 | 三方库质量加固实施、PR 检视与团队检查清单 | ## 应用场景 Muggles 支持 FP 项目交付、研发实施和人力招聘： | 场景 | 项目阶段 | 主要产出 | |---|---|---| | FP 人力招聘 | 团队建设与人员补充 | 招聘 JD、初筛依据和面试跟踪表 | | FP 交付件生成 | 项目前期与交付准备 | 项目评估、工作量、管理表、设计文档 | | 客户项目需求开发 | 研发实施 | OpenSpec 需求基线、代码实现、构建测试与验证结论 | 前一场景产生的需求和设计交付件经过人工确认后，可以作为后一场景的开发输入。 ### 场景一：FP 交付件生成 以一个 FP 项目为例，Muggles 可以这样帮你： **方式一：一键生成全套交付件（推荐）** 1. **准备好 SoW**（工作任务书 Word + Excel 需求清单） 2. **使用 `deliverable-suite`** → 自动按顺序调用所有原子技能，生成完整交付件包 3. **AI 自动填充** → 模块设计、测试设计等需要智能生成的部分由 AI 逐个完成 **方式二：按需生成单个交付件** 1. **收到 SoW/RFP，需要项目前期评估** → 使用 `evaluating-projects` 生成 HTML 项目评估报告和可编辑的人力模型 Excel，包含风险清单与答疑问题 2. **收到需求列表 Excel** → 使用 `workload-estimation` 自动计算规模、人天、人月，生成带公式的工作效率表 3. **需要综合管理表** → 使用 `project-management-excel` 基于模板自动生成管理表，将需求数据批量填入 4. **需要模块设计文档** → 使用 `module-design` 从需求列表自动生成每个需求的模块设计 Markdown 文档 5. **后续（规划中）** → 测试用例、验收文档……逐步覆盖整个交付流程 > 注：`evaluating-projects` 暂不依赖 `workload-estimation` 的人月结果；HTML 与人力模型采用同一评估口径，工作量和人员结构结论仍需基于 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 的新会话中发送一句话： ```text 请按 https://gitee.com/sinall/muggles/blob/master/INSTALL.md 的安装说明安装 Muggles 插件。 ``` Agent 会读取文档并按对应平台的步骤完成安装。安装完成后新建会话生效。 如果 Agent 无法读取文档，可按下方对应平台的命令手工安装。 ### 命令行安装（手工/恢复） #### 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 ``` 或使用 `--marketplace` 临时指定来源（不永久注册 marketplace）： ```bash claude plugin install muggles --marketplace https://gitee.com/sinall/muggles.git ``` ### 升级 Muggles 需要升级时，在当前 Agent 中直接说： ```text 请用当前 AI Agent CLI 的插件管理器更新 Muggles 插件到最新版本。 ``` Agent 应使用原生插件命令更新，不要手动克隆或替换文件。完成后新建会话生效。 **Claude Code**：由于 marketplace 目录不会自动同步远程，更新前需先重新添加 marketplace 刷新目录，再更新插件： ```bash claude plugin marketplace add https://gitee.com/sinall/muggles.git claude plugin update muggles@muggles ``` ## 开始使用 Muggles ### 快速开始：首次配置 以下流程从 Muggles 插件安装完成后的新 Agent 会话开始。开始前请确认： - 已安装 OpenCode、Codex 或 Claude Code 中至少一种 AI Agent CLI，并按上文安装 Muggles。 - 已确定项目名称、项目资料根目录以及需要关联的源码目录；纯资料项目可不关联源码。 - 如使用 OpenHarmony Repo，源码应已检出；Muggles 不负责下载源码。 插件安装或升级不会创建 `~/.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 初始化项目配置。 项目名是 OpenHarmony开源合作共建项目， 项目资料根目录是 /path/to/delivery/projects/OpenHarmony开源合作共建项目， 源码位于 /path/to/openharmony。 产品名是 ipcamera_hispark_taurus， 已确认的构建命令是 ./build.sh --product-name ipcamera_hispark_taurus --ccache。 请从 Repo manifest 中列出仓库并让我选择，先预览完整配置，待我确认后再写入；此次不初始化工具。 ``` Agent 会通过 `repo list` 读取 manifest 中的仓库名，询问本项目允许操作哪些仓库，并展示 完整 JSON；普通源码目录可直接按绝对路径关联。产品名和构建命令没有经过项目确认时省略。 确认后，Muggles 才会创建 `~/.muggles/config.json`。配置操作不会初始化 OpenSpec、 创建交付件目录或索引源码；如需初始化缺失的 CodeGraph 或 OpenSpec，应单独预览并确认。 #### 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 显示当前有效项目上下文。 ``` 可以直接说“本会话切到项目 A，开始 RM.048”“清除当前需求”或“显示当前项目和需求”。 Muggles 按真实会话 ID 保存项目及可选需求：明确指定 > 已保存会话项目 > 首次绑定时的 `active_project`。当前目录不覆盖选择；切换项目清空旧需求，其他会话修改全局默认不会影响本会话。 “把全局默认项目改成 B”只影响后续首次绑定。 Claude Code 可通过“使用 configuring-muggles，在状态栏显示当前项目和需求”启用原生显示： 启动时未绑定的会话自动采用 `active_project`；恢复已有会话则保留其项目和需求。 ```text Muggles · 项目A · RM.048 ``` Codex/OpenCode 可读写同一会话状态，并在对话中显示；本版尚未接入它们的自定义常驻栏。 获取不到真实会话 ID 时会明确提示，不能把全局默认冒充会话项目。 详见[会话上下文与状态显示](skills/configuring-muggles/references/session-context.md)。 ### 交付工作区 每个项目有独立的资料根目录；它们可以集中存放，也可以分散在不同位置。以下仅为集中存放示例： ```text / ← 交付工作区 ├── / ← 当前客户项目 │ ├── SoW/ ← 客户输入 │ │ ├── XXX项目-工作任务书.docx │ │ └── XXX项目-工作任务书.xlsx │ ├── openspec/ ← 首版需求基线和变更记录 │ ├── 需求与设计/ ← 已确认的需求和设计输入 │ ├── 项目管理/ ← 内部管理文档（Skill 输出） │ └── 交付件/ ← 客户交付文档 └── / ← 其他客户项目 ``` 项目资料根目录保存 SoW、需求与设计、项目管理资料和交付件，源码通过独立绝对路径关联。 SoW 和参考资料目录名不强制；`交付件/`、`openspec/` 的位置固定在各项目根目录下。 ### 持久项目上下文 Muggles 将本机项目配置保存在 `~/.muggles/config.json`。首次配置应使用快速开始中的 `configuring-muggles` 流程；必要时也可以手动编辑： ```json { "schema_version": 2, "active_project": "OpenHarmony开源合作共建项目", "projects": { "OpenHarmony开源合作共建项目": { "root": "/path/to/delivery/projects/OpenHarmony开源合作共建项目", "source": [ "/path/to/openharmony/components/repository-a", "/path/to/openharmony/components/repository-b" ], "product_name": "ipcamera_hispark_taurus", "commands": { "build": { "cwd": "/path/to/openharmony", "command": "./build.sh --product-name ipcamera_hispark_taurus --ccache" } } }, "资料整理": { "root": "/another/location/project-materials", "source": [] } } } ``` 项目名称独立于磁盘路径；每个项目有一个资料 `root` 和零到多个绝对路径 `source`。 源码目录可以是普通文件夹；不会递归把子仓库自动加入范围。项目之间无需共享父目录。 SoW 和参考资料在项目根目录内按现有习惯组织；`root/交付件` 固定用于交付输出， 仅在需要生成交付件时创建；`root/openspec` 用于需求规格与变更。无需另设“主要目录”。 旧版 schema v1 仍可读取。通过 `configuring-muggles` 预览并迁移为 v2，保留 `config.json.bak`；旧项目目录和已选仓库转换为绝对路径，不移动实际文件。 执行器应用迁移时携带预览的配置摘要；期间配置发生变化则重新预览，避免覆盖其他会话的修改。 升级 Muggles 时即使插件提交未变化也检查配置迁移，迁移在托管规则同步之前进行。 多个 `source` 目录不代表多个 OpenHarmony 工作区，规则只同步到已有托管或明确确认的根目录。 CodeGraph 遵循 convention：查找 `/.codegraph/codegraph.db`； 不存在时降级到 `rg`、Git 和直接源码阅读。 `product_name` 与 `commands` 是互相独立、可选的项目级构建上下文。当前支持 `build` 和 `test`， 每条命令显式声明绝对路径 `cwd`。迁移保留旧源码工作区作为命令工作目录， 即使它是已选仓库的父目录，也不扩大允许修改的源码范围。 构建命令按单行字符串保存；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)。 --- *麻瓜——拒绝魔法，拥抱确定性。*