基于 Mirobody 进行开发

贡献指南

如何反馈问题、提出需求，以及把一个改动落进 Mirobody Python 引擎。

Mirobody 是一个 Python 项目，欢迎贡献。本页依据的是仓库自带的 CONTRIBUTING.md；两者有出入时，以仓库里的那份文件为准。

三个贡献方向

贡献是按引擎那三个步骤组织的，而它们的体量差别极大。想让第一个 PR 顺利落地，就从 ② 开始。

方向	贡献什么	典型体量
① 采集	一个新的设备 provider：在一个 `mirobody_<slug>/` 目录里实现 `BasePullProvider`，平台在启动时就会发现它。`mirobody_pgsql/` 是最小的参照，`mirobody_whoop/` 是走 OAuth2 的那个。或者给解析器加一种新文件格式。见开发一个 Provider。	中等
② 标准化	让一个词能解析。找一个解析回来是错的或空的词（用 `mirobody resolve "<term>"` 查一下），然后往 `resolver_overrides.tsv` 加一行，往 `test_engine_coverage.py` 加一例。任何语言都行。另外还有：单位映射、分类体系修正。	很小
③ 问答	一个 Agent Skill（一个装 `SKILL.md` 的目录，照抄 `lab-report-walkthrough` 即可）、一个 MCP 工具、一份图表 schema。见 Agent Skills 与添加自定义工具。	中等

解析错误的化验单，或者解析不出来的指标名，都是很好的 issue 素材，请附上去标识后的样本。

反馈一个 Bug

在 GitHub 上开一个 issue，写清标题和描述、复现步骤，以及你的环境信息（操作系统、Docker 版本、Python 版本）。

提出一个需求

先开一个 issue 把想法讨论清楚，再动手实现。这样你的时间花得值，功能也和项目的方向对得上。

Fork 并克隆

git clone https://github.com/YOUR_USERNAME/mirobody.git
cd mirobody

建一个分支

git checkout -b feature/my-new-feature
# 或者
git checkout -b fix/bug-fix-name

改你要改的

跟着周边代码的风格走。凡是用户可扩展的部分（工具、agent、skill、provider）都是运行期从配置好的目录里发现的，所以加一项能力就是加一个文件，而不是去改一张注册表。

测一下

pip install -e '.[agents,test]'

pytest                # 整个套件；测试就放在代码旁边
lint-imports          # 引擎 / agent 边界，机器校验

只装 '.[test]' 就够改引擎那部分：agent 层的测试会在收集阶段被跳过，而不是让整轮直接崩掉。lint-imports 要对着仓库源码运行。细节见开发环境搭建。

推上去并发起 Pull Request

git push origin feature/my-new-feature

然后对着上游仓库的 main 分支开一个 PR。

Python：遵循 PEP 8，并与你正在改的那个文件的既有习惯保持一致。
文档：只要你改变了某项行为，就更新 README（或者你代码旁边那个模块的 README）。
提交：message 要说明白；一个 commit 只做一件事。
配置键：用 safe_read_cfg("YOUR_KEY") 读，不要直接伸手去拿环境变量，这样覆盖和自动加密才继续有效。凡是键名里含 _KEY、_PASSWORD、_PASS、_PWD、_SECRET、_SK 或 _TOKEN 的，都会加密存放。
新增的可选依赖要放进 pyproject.toml 的某个 extra（server、agents、cn、test、indicator-build），而不是基础依赖清单：一个没人开启的功能，不应该破坏 pip install -e .。
绝不要在 agent/ 或 server/ 之外 import agent 框架。 lint-imports 会因此让构建失败，函数内的局部 import 也算。引擎必须能在只有 numpy 一个第三方包的环境里 import 成功。

标题

对这个改动的一句简短概述。历史里有一部分用了 conventional 前缀（feat:、fix:、docs:、chore:）；项目要求的只是这句话说清改了什么。

描述

Checklist

贡献即表示你同意：你的贡献按项目的 LICENSE 授权。

Bug 反馈与功能请求

直接的技术支持

感谢你的贡献！