内容
# 梅尼斯克
[](https://github.com/itsjawreal/menisik/actions/workflows/ci.yml)
> 一个学习项目：一个 GitHub 贡献引擎，扫描仓库，起草专注的补丁，运行质量检查，并将提交决策留给人类。
梅尼斯克是一个个人学习项目，探索 AI 引擎是否可以找到并准备狭窄的开源贡献。它 **不是** 一个生产就绪的自主贡献者 - 参见下面的[诚实状态](#诚实状态)。
## 为什么取这个名字？
*梅尼斯克* 是印尼语中缝补的意思：用小而谨慎、几乎看不见的针脚修补织物。这就是这个引擎的哲学 - 它不会重新设计衣服，而是找到一个小洞并仔细地缝补，一次一个针脚（一个狭窄的补丁）。
该项目以前名为 **rover**。`rover`、`rover-engine`、`rover-mcp` 和 `rover-daemon` 命令作为已弃用的别名保留在 `0.1.x` 版本中（参见[弃用策略](#弃用策略)）。
## 功能
- 发现值得贡献的活跃开源仓库。
- 在本地扫描代码以寻找贡献机会。
- 在花费 AI 调用之前评估机会。
- 使用 AI 后端起草专注的补丁和 PR 正文：Codex 或 Claude CLI，或 OpenAI 兼容的 API（OpenRouter 等）- 可通过 `.env` 中的 `AI_BACKEND` 配置。
- 可以通过 GitHub CLI 提交 PR（最好与 `--dry-run` / 人工审查一起使用）。
- 在 SQLite 中跟踪 PR 生命周期、维护者反馈、拒绝、队列状态和运行摘要。
- 根据过去的结果调整仓库评分和冷却时间。
## 诚实状态
本 README 旨在描述引擎实际执行的操作，而不是其期望的功能：
- ✅ 质量门户可靠地 **拒绝** 不安全、改变行为或过于广泛的补丁。
- ⚠️ 通过门户的补丁 **不保证** 修复真正的错误。门户检查安全性、范围和行为保护 - 它们无法验证底层问题是真实的，因此引擎可以产生看似合理但推测性的补丁。
- ⚠️ 它 **不** 可靠地在无人值守的情况下生成可合并的 PR。请将其视为一个起草助手：阅读每个差异并确认错误是真实的，然后再提交。
- “从结果中学习”意味着简单的仓库评分和冷却时间，而不是复杂的学习。
目标是贡献质量而不是数量 - 像一个谨慎的贡献者一样表现，而不是一个 PR 垃圾邮件机器人。那是一个标准；持续达到它仍然是一个进行中的工作。
## 主要命令
```bash
menisik # 状态仪表盘
menisik doctor # 检查设置
menisik check # 轮询开放的 PR 状态
menisik list-prs # 所有提交的 PR
menisik list-prs open # 按状态过滤
menisik report # 运行历史 + 拒绝分析
menisik inspect owner/repo # 分析仓库而不提交
menisik owner/repo # 目标特定仓库
```
通过 `python -m app.builder` 进行高级/低级标志：
```bash
python -m app.builder --contrib --1
python -m app.builder --contrib owner/repo --goal feature_upgrade --1
python -m app.builder --contrib owner/repo --goal dep_update --1
python -m app.builder --contrib --goal bugfix --first-pr --1
python -m app.builder --contrib owner/repo --1 --human-approval
python -m app.builder --doctor
```
`run.py` 是一个薄的调度任务包装器，它从 `.env` 读取 `CONTRIB_AUTORUN_ARGS` 并转发到 `python -m app.builder`。将其用于 cron 作业。
兼容性注意：
- `rover`、`rover-engine`、`rover-mcp` 和 `rover-daemon` 仍然作为已弃用的别名存在于预重命名时代
- 优先使用 `menisik ...` 或 `python -m app.builder ...` 进行新用法
## 弃用策略
仅当兼容层仍然保护活动操作员工作流时，才会保留兼容层。
当前策略：
- 项目从 **rover** 重命名为 **menisik**。`rover`、`rover-engine`、`rover-mcp` 和 `rover-daemon` 是 `menisik*` 入口点的已弃用别名。
- `--pr`、`--pr-check` 和 `--pr-respond` 现在已弃用；请优先使用 `--contrib`、`--contrib-check` 和 `--contrib-respond`。
- 警告期：所有 `0.1.x` 版本。
- 计划移除目标：`0.2.0` 或下一个故意破坏 CLI 版本。
仍然支持的兼容层：
- 在 `github-contribution-engine` 下的 OpenClaw 兼容性技能路径仅作为别名。
- MCP 服务器仍然注册为 `rover`，安装程序仍然写入 `rover` 命名的集成路径（`mcp.servers.rover`，技能/包装路径）；将这些更改为 `menisik` 将在 `0.2.0` 版本中破坏现有的 MCP 客户端配置，因此它们会迁移到 `menisik`。
这些层仍然存在，因为它们仍然保护真正的集成，而不是仅仅旧的命令肌肉记忆。
## 引擎设计
核心模块：
- `src/contrib/contribution_engine.py`：运行编排、节奏、操作员报告。
- `src/contrib/contribution_store.py`：SQLite 模式和持久性。
- `src/contrib/opportunity_engine.py`：本地模式扫描器和资格政策。
- `src/analysis/repo_intelligence.py`：从内存中调整仓库评分。
- `src/contrib/pr_generator.py`：GitHub 目标搜索、AI 补丁执行、PR 跟踪和反馈处理。
- `src/github/fork.py`：通过 `gh` 进行分叉、分支、推送和 PR 创建。
模块布局注意：
- 活动代码现在位于 `src/core/*`、`src/contrib/*`、`src/github/*`、`src/platform/*` 和 `src/analysis/*` 下
- 新代码应直接导入这些域文件夹
主要状态单元是 `机会`，而不是仓库。机会通过 `SCAN`、`QUALIFY`、`EXECUTE`、`VERIFY`、`READY`、`SUBMIT` 和 `REJECT` 等状态移动。
行为政策主要在 [skill.md](skill.md) 中定义，仓库特定的操作指南在 [AGENTS.md](AGENTS.md) 中。
## 质量政策
引擎倾向于小型、可测试的 PR：
- 需要具体的故障模式
- 优先使用一个明确的目标文件
- 拒绝广泛的重构
- 拒绝投机性的“更安全/更干净”的更改
- 每个仓库一次一个开放的 PR
- 队列机会保留以供以后调整节奏
每个提出的补丁都应从具体的故障模式和足够的本地证据开始，以无需空口说辞的方式解释其价值。
贡献目标：
- `bugfix`：默认模式，源自本地扫描器证据
- `dep_update`：当安全版本升级和本地验证路径可用时，更新固定的依赖项
- `feature_upgrade`：仅当代码中已经包含明确的维护者 TODO/FIXME 意图时，才进行狭窄的增强工作
- `feature_add`：更严格的增强模式，需要问题支持的维护者意图和狭窄的目标文件匹配
- `--first-pr`：搜索模式操作员标志，偏爱具有较小、活跃、测试支持的仓库用于第一个真正的 PR
- `--human-approval`：在提交前暂停，以便操作员可以提交、排队或拒绝生成的补丁
人类审批决策记录在 `repo_events` 审计跟踪中。示例事件详情：
```json
{
"event_type": "human_approval_queue",
"repo_full_name": "owner/repo",
"details_json": {
"actor": "nadira",
"decision": "queue",
"reason": "test failed locally",
"opportunity_id": 42,
"title": "fix: handle missing response field",
"improvement_type": "bug_fix",
"files": ["src/client.py", "tests/test_client.py"],
"risk": "narrow patch with test coverage signal",
"risk_level": "medium"
}
}
```
当配置通知凭证时，队列/拒绝决定也会发送简短的操作员通知：
```text
PR queued: owner/repo - fix: handle missing response field (Reason: Waiting for test fix)
PR rejected: owner/repo - feat: add broad dashboard mode (Reason: Too broad for maintainer review)
```
后台 MCP 运行也可以在工作仍在进行时推送进度更新。配置直接的 Telegram 交付或 OpenClaw 中继交付：
```text
ROVER_NOTIFY_TRANSPORT=openclaw
OPENCLAW_NOTIFY_CHANNEL=telegram
OPENCLAW_NOTIFY_TARGET=-1001234567890
ROVER_NOTIFY_PROGRESS=false
ROVER_NOTIFY_INTERVAL_SECONDS=60
ROVER_NOTIFY_STALL_SECONDS=300
ROVER_NOTIFY_ONLY_ON_CHANGE=true
ROVER_NOTIFY_ON_EVENT_TYPES=started,repo_selected,stage,patch_generated,pr_submitted,completed,failed,stalled
```
模式类（按优先级）：
| 模式 | 优先级 |
|---|---|
| `missing_timeout` | 10 |
| `missing_input_validation` | 9 |
| `unsafe_subprocess` | 9 |
| `unchecked_response_shape` | 8 |
| `resource_cleanup_gap` | 7 |
| `missing_retry_backoff` | 7 |
| `overbroad_exception_handling` | 6 |
| `unsafe_file_write_or_path` | 6 |
| `temp_file_cleanup_gap` | 6 |
| `flaky_time_dependent_test` | 5 |
| `missing_regression_test_for_obvious_bugfix` | 4 |
| `feature_upgrade_todo` | 3 |
## 安装
在 Linux VPS 上引导：
```bash
bash scripts/install_vps.sh
```
在重新测试设置流程之前重置本地 Menisik 安装：
```bash
bash scripts/uninstall_vps.sh
```
在 Windows PowerShell 上引导本地设置：
```powershell
powershell -ExecutionPolicy Bypass -File scripts/install_windows.ps1
```
在重新测试设置流程之前重置本地 Windows 安装：
```powershell
powershell -ExecutionPolicy Bypass -File scripts/uninstall_windows.ps1
```
从全新服务器一键引导：
```bash
curl -fsSL https://raw.githubusercontent.com/itsjawreal/menisik/master/scripts/bootstrap.sh | bash
```
引导设置还可以安装原生 OpenClaw 技能 + 包装器在一个流程中：
- `~/.openclaw/workspace/skills/rover/SKILL.md` 当 OpenClaw 工作区存在时
- 备用路径：`~/.openclaw/skills/rover/SKILL.md`
- `~/.openclaw/tools/rover.py`
- `~/.openclaw/openclaw.json` 包含 `mcp.servers.rover`
引导脚本执行的操作：
- 在可能的情况下安装常见的系统依赖项（`git`、`python3`、`python3-venv`、`curl`、`gh`）
- 在可能的情况下安装 `uv`
- 创建 `.venv`
- 将此仓库安装到虚拟环境中
- 在缺少时从 `.env.example` 创建 `.env`
- 可以提示输入 `GITHUB_TOKEN` 并将其保存到 `.env`
- 可以自动运行 `gh auth login`，然后继续到下一步，验证成功后
- 呈现一个后端设置向导，提供以下选择：
- `Codex CLI`
- `Claude CLI`
- `LLM API key only`
- `Skip for now`
- 仅询问所选后端的相关问题
- 可以根据所选设置路径提示输入 `OPENAI_API_KEY`、`ANTHROPIC_API_KEY` 或 `OPENROUTER_API_KEY`
- 可以在用户选择交互式 Codex 路径时运行 `codex --login`
- 运行 `rover --doctor`
- 打印剩余的手动步骤，例如 `gh auth login` 和 AI CLI 设置
安装依赖项：
```bash
python -m pip install -r requirements.txt
```
验证 GitHub CLI：
```bash
gh auth login
gh auth status
```
关键 `.env` 值：
```env
# Required
GITHUB_TOKEN=
GITHUB_OWNER=
# AI backend: claude | codex
AI_BACKEND=claude
CLAUDE_CMD=claude
CLAUDE_ARGS=-p -
CODEX_CMD=codex
CODEX_ARGS=exec --skip-git-repo-check -s read-only -
# Notifications (optional)
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=
ROVER_NOTIFY_TRANSPORT=openclaw
OPENCLAW_NOTIFY_CHANNEL=telegram
OPENCLAW_NOTIFY_TARGET=
OPENCLAW_NOTIFY_ACCOUNT=
OPENCLAW_NOTIFY_THREAD_ID=
ROVER_NOTIFY_PROGRESS=false
ROVER_NOTIFY_INTERVAL_SECONDS=60
ROVER_NOTIFY_STALL_SECONDS=300
ROVER_NOTIFY_ONLY_ON_CHANGE=true
ROVER_NOTIFY_ON_EVENT_TYPES=started,repo_selected,stage,patch_generated,pr_submitted,completed,failed,stalled
# Contribution targeting
CONTRIB_AUTORUN_ARGS=--contrib --1
CONTRIB_LANE=general
CONTRIB_TOPIC_KEYWORDS=
CONTRIB_SEARCH_QUERIES=
# Repo filters
PR_MIN_STARS=300
PR_MAX_STARS=6000
PR_COUNT=1
PR_TARGETED_MAX_TOTAL_FILES=500
PR_TARGETED_MAX_PY_FILES=300
PR_TARGETED_ALLOW_BROAD=false
```
注意：
- `AI_BACKEND=claude` 使用 Claude CLI；`AI_BACKEND=codex` 使用 Codex CLI。引擎自动回落到 Claude 如果 Codex 失败。
- `CONTRIB_AUTORUN_ARGS` 控制 `python run.py` 和调度任务默认执行的操作。
- `CONTRIB_LANE` 支持内置预设： `general`、`crypto`、`devtools`、`frontend`、`data`、`infra`、`ml`、`docs`。
- `CONTRIB_TOPIC_KEYWORDS` 和 `CONTRIB_SEARCH_QUERIES` 覆盖预设时，您需要自定义目标。
- `PR_TARGETED_MAX_TOTAL_FILES` 和 `PR_TARGETED_MAX_PY_FILES` 仅影响固定/目标仓库运行。
- `PR_TARGETED_ALLOW_BROAD=true` 完全禁用目标仓库宽松限制；仅当您故意想要处理大仓库时使用。
- `CONTRIB_FIRST_PR_MODE=true` 使得搜索模式更喜欢具有测试和新鲜活动的小仓库用于第一个生产 PR 尝试。
- 您应该将机密仅保存在 `.env` 中，而不是在文档或脚本中。
示例：
```env
# General-purpose developer tooling
CONTRIB_LANE=devtools
# Frontend ecosystem targeting
CONTRIB_LANE=frontend
# Custom niche override
CONTRIB_LANE=general
CONTRIB_TOPIC_KEYWORDS=observability,otel,tracing,metrics
CONTRIB_SEARCH_QUERIES=python:python observability library,typescript:typescript tracing sdk
```
## 可移植性
在打开此项目更广泛的用户之前，请运行：
```bash
python -| 工具列表
# 工具列表
## 工具列表
## 设置
在 Linux VPS 上引导：
```bash
bash scripts/install_vps.sh
```
在重新测试设置流程之前重置本地 Menisik 安装：
```bash
bash scripts/uninstall_vps.sh
```
在 Windows PowerShell 上引导本地设置：
```powershell
powershell -ExecutionPolicy Bypass -File scripts/install_windows.ps1
```
在重新测试设置流程之前重置本地 Windows 安装：
```powershell
powershell -ExecutionPolicy Bypass -File scripts/uninstall_windows.ps1
```
从全新的服务器上一键引导：
```bash
curl -fsSL https://raw.githubusercontent.com/itsjawreal/menisik/master/scripts/bootstrap.sh | bash
```
引导设置还可以安装原生 OpenClaw 技能 + 包装器在一个流程中：
- `~/.openclaw/workspace/skills/rover/SKILL.md` 当 OpenClaw 工作区存在时
- 备用路径：`~/.openclaw/skills/rover/SKILL.md`
- `~/.openclaw/tools/rover.py`
- `~/.openclaw/openclaw.json` 包含 `mcp.servers.rover`
引导脚本执行的操作：
## 验证
```bash
python -m py_compile app/builder.py src/ai.py src/config.py src/contribution_engine.py \
src/contribution_store.py src/fork.py src/notify.py src/opportunity_engine.py \
src/pr_engine.py src/pr_generator.py src/repo_intelligence.py src/validator.py \
src/scraper.py src/security.py src/state.py src/contribution_mcp/server.py \
src/core/ai.py src/core/config.py src/core/doctor.py src/core/github_auth.py \
src/contrib/contribution_engine.py src/contrib/contribution_store.py src/contrib/opportunity_engine.py \
src/contrib/pr_engine.py src/contrib/pr_generator.py src/github/fork.py src/github/scraper.py \
src/analysis/repo_intelligence.py src/platform/mcp_install.py src/platform/openclaw_install.py
python -m unittest discover -s tests -v
```
## 活跃文档
- [skill.md](skill.md)：贡献引擎行为的真实来源
- [AGENTS.md](AGENTS.md)：仓库使命、架构和验证规则
- [.agent.md](.agent.md)：本地代理执行角色
- [CONTRIBUTION_FLOW.md](CONTRIBUTION_FLOW.md)：简洁的端到端贡献流程
- [ROADMAP_v0.1.2.md](ROADMAP_v0.1.2.md)：活跃的开发路线图
- [docs/agents/README.md](docs/agents/README.md)：特定提供商的操作员说明
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器