RepoImmune 将仓库中已解决的 bug 转化为代码原生、有证据支撑的检查项，供人类和编码代理查询。
输入 | 处理 | 输出 |
一个 GitHub 仓库或 PR 差异 | 检索历史 issue → 修复 → 测试 → AST 证据 | 精确的回归位置、源码链接、受保护的测试，以及历史修复方案 |
git clone https://github.com/Alex0AI/RepoImmune.git
cd RepoImmune
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
python -m pip install -e .
repoimmune init .
repoimmune check --diff examples/reintroduce-astropy-12907.diff --memory examples/memory
repoimmune replay astropy-12907 --memory examples/memory
repoimmune report --format html该演示离线运行、无需密钥、运行时零依赖。检查项有意以退出码 2 结束，因为它发现了一个来自 Astropy PR #12907 的真实历史回归。
Related MCP server: mcp-software-engineering-challenge
行为卡（Behavior Card）不是聊天摘要。它将一个不变式绑定到修复前/后的代码、AST 形式、精确符号、回归测试、提交、源码 URL、许可证、证据类别，以及一个可选的回放胶囊。当证据链不完整时，RepoImmune 拒绝提升挖掘出的候选结果。
flowchart LR
I[Issue / report] --> B[Buggy commit]
B --> F[Failing behavior]
F --> P[Fix PR / commit]
P --> T[Regression test]
T --> S[AST + symbol change]
S --> V[Repository invariant]
V --> C[Patch immunity check]内置的垂直切片能检测到这一精确的还原：
- cright[-right.shape[0]:, -right.shape[1]:] = right
+ cright[-right.shape[0]:, -right.shape[1]:] = 1它会报告精确的行号，解释为什么全 1 代码块在历史上是错误的，链接到 issue/PR/合并提交，并指出随修复一起添加的 pytest 用例。
repoimmune init .
repoimmune mine --repo owner/project
repoimmune check --diff HEAD~1
repoimmune recall "pagination returns duplicate rows"
repoimmune explain <behavior-card-id>
repoimmune replay <capsule-id>
repoimmune report --format html
repoimmune validate <card.json>check 输出 Markdown、JSON 或 SARIF 格式。mine 仅保存保守的候选结果；它从不调用 LLM，也不会仅凭标题就声称生成了行为卡。
复合 GitHub Action 以只读方式分析拉取请求差异，并上传 SARIF/Markdown 证据。
stdio MCP 服务器暴露六个结构化的只读工具：search_past_failures、explain_code_history、check_patch_against_memory、list_invariants_for_file、get_regression_test 和 replay_behavior_case。
开放的 Agent Skill 要求代理在风险编辑之前回忆历史，并在声称完成之前再次回忆。它不授予任何提交、推送、合并或绕过测试的权限。
静态演示无需登录或 API 密钥即可运行。
每个结果都明确属于以下类别之一：
verified：已直接回放或通过主要代码/测试证据进行机械佐证。
externally_reported：受信任的上游或基准执行记录，未在此复现。
heuristic：有用的候选或相似性信号，并非证明。
inconclusive：证据冲突或不完整。
相似度分数永远不会被当作证明。发现结果始终显示匹配的代码和来源证据。
代理/聊天记忆： 记住对话或仓库事实；RepoImmune 挖掘代码历史并创建超越任何代理会话存续期的机械检查。
SWE-bench： 评估代理能否修复 issue；RepoImmune 将已解决的 issue 转化为持久的预防资产。
静态分析： 从通用规则出发；RepoImmune 从该仓库的真实失败中学习仓库特定的不变式。
测试生成： 可能创建测试；RepoImmune 保留报告、缺陷/修复代码、测试和不变式之间的因果链。
git blame： 说明谁改的、何时改的；RepoImmune 解释为什么行为必须存续，并能对其进行检查。
参见 research-landscape.md 获取有证据支撑的对比。
Issue 文本、PR 评论、代码、补丁和仓库元数据均为不可信数据。RepoImmune 从不将它们作为指令来执行。挖掘使用有界 HTTPS 响应；引用和仓库名称经过验证；胶囊运行使用固定 argv 且不经过 shell，拒绝绝对路径和符号链接，并设有超时。默认情况下，从不运行未知仓库的安装脚本或测试。参见 SECURITY.md 和 docs/threat-model.md。
alpha 版本深度支持 Python AST 和 pytest 证据。TypeScript/TSX 有一个可选的固定版本 tree-sitter 适配器，用于规范化结构和调用提取；JavaScript 使用确定性 token 结构，Jest/Vitest 可被记录为测试证据。全程序过程间可达性分析、自动上游环境重建以及广泛的语言支持属于路线图项目。数据集规模的卡片在回放之前均为 externally_reported；捆绑的 Astropy 垂直切片是 v0.1.0 中唯一在本地验证的行为胶囊。
python scripts/build_research_snapshot.py --limit 500 --cards 120
python scripts/run_experiments.py
pytest
coverage run -m pytest && coverage report
ruff check . && mypy src/repoimmune所有已发布的数据都会重新生成到 research/results.json 中；分类和局限会被保留，包括失败或不确定的案例。数据来源记录在 DATA_SOURCES.md、THIRD_PARTY.md 和 research/data-card.md 中。
已提交的 v0.1 快照包含 500 个候选、120 张行为卡、12 个仓库和 30 个轻量级结构胶囊。在确定性变异上，它检测到了 120/120 个精确的历史还原和 120/120 个受保护的断言删除；同符号固定形式的重构产生了 9/120 个误报（7.5%）。基于标题的检索达到了 Recall@5/MRR 1.0/1.0，但这明确是一个同源管道测试。独立的挖掘精度和受控的 Agent A/B 测试仍无定论。
在提出新的挖掘器或证据来源之前，请阅读 CONTRIBUTING.md、路线图 和行为卡模式。采用 Apache-2.0 许可证。
中文说明：README.zh-CN.md
check patch against memory
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It only restates the tool name and gives no indication of side effects, return behavior, input expectations, or what 'memory' refers to.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is minimal but not meaningfully concise; it is under-specified. It provides no front-loaded useful content and reads as a placeholder rather than a structured tool definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no parameters and no output schema, the tool still needs context such as what 'patch' and 'memory' refer to and what the result indicates. The description is completely inadequate for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. There is no parameter information missing or requiring compensation from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'check patch against memory' is a verbatim restatement of the tool name, providing no additional information about what the tool actually does. It is a tautology that fails to distinguish itself from the sibling tools such as search_past_failures or explain_code_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance whatsoever about when to use this tool versus alternatives. The description offers no context, prerequisites, or exclusions, leaving an agent to guess when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
explain code history
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description adds zero behavioral information. It does not disclose whether this is a read-only operation, how it retrieves history, what output format to expect, or any side effects. The description carries the full burden for behavioral disclosure and fails entirely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief, but brevity here is under-specification rather than efficient conciseness. A single phrase that repeats the tool name without elaboration does not earn credit for structure; it fails to convey any substantive information while appearing to be a complete definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, no annotations, and a descriptor that is a tautology. Given its sibling tools perform distinct historical/diagnostic functions, an agent cannot determine what inputs are needed, what results to expect, or how this differs from related operations. The definition is completely inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool accepts 0 parameters, so there is nothing for the description to clarify about argument meanings. Per the baseline for 0-parameter tools, this dimension is not penalized for missing parameter documentation. The description's lack of context does not affect this score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'explain code history' is essentially a restatement of the tool name with a verb and resource, but it provides no actual explanation of what 'explain' means in this context or what 'code history' refers to. It is a tautology, not a clear statement of function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus its siblings like search_past_failures or replay_behavior_case. No context, prerequisites, or situational cues are provided. The agent is left to guess which scenario would call for explaining code history.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get regression test
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden, but it reveals nothing about behavior, side effects, return values, or error cases. It is purely a label, not a behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The text is extremely short, but this is under-specification rather than useful conciseness. It says nothing beyond the tool name and provides no structured or front-loaded information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is entirely inadequate. It does not explain what a regression test is, what the tool returns, or how it relates to the listed sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool declares zero parameters, so the baseline is 4; the description adds no parameter meaning, but there are no parameters for it to explain. The permissive additionalProperties: true schema is not clarified, but that is a minor gap with no required inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'get regression test' merely restates the tool name and adds no verb-resource detail beyond it. It does not distinguish this tool from siblings like search_past_failures or replay_behavior_case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool or when to prefer a sibling. No context, conditions, or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list invariants for file
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, but it only repeats the action 'list' and the resource 'file'. It does not mention side effects (likely read-only), error conditions, ordering, filtering, or what data is actually returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence is concise, but this is under-specification rather than efficient brevity. The description omits essential details that an agent needs, so it does not earn credit for structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description must provide nearly all context. It fails to state how the file is selected, what invariants look like, or what a successful call returns, leaving the agent with only the tool name as guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero declared parameters, so the description cannot add parameter-level detail beyond the schema. The 100% schema coverage and empty parameter list make the missing specification less harmful, though the description does not explain how 'file' is supplied.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'list invariants for file' is a near-verbatim restatement of the tool name. It identifies the action and resource but does not clarify what 'invariants' means in this context or how it differs from the sibling tools, making it tautological rather than informative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance about when to use this tool instead of alternatives such as search_past_failures or check_patch_against_memory. There is no context, prerequisite, or exclusion information, leaving the agent to guess.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
replay behavior case
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It fails to state side effects, permissions, return values, or any observable behavior beyond the vague verb 'replay'. There is nothing here to inform an agent about what will happen when the tool is invoked.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three words is technically concise, but this is under-specification rather than effective structure. The description has no front-loaded action statement, no scoping, and no differentiation—it reads as a placeholder, not a deliberate, minimal definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, no parameter details, and only sibling tool names for context, the description is the sole source of guidance and it provides none. An agent cannot understand what a 'behavior case' is, what replaying entails, or what result to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the description has no parameter details to explain, and the baseline is 4. However, the schema allows additionalProperties: true, meaning arbitrary input could be passed, and the description offers no hint about what properties might be relevant. This is a minor gap given no defined parameters exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is literally the tool name: 'replay behavior case'. It restates the name without defining the action, the resource, or the domain meaning of 'behavior case'. An agent cannot distinguish it from siblings like search_past_failures or get_regression_test.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives, no context, and no examples. The description contains only a phrase with no actionable direction, so an agent receives zero assistance in selecting it correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search past failures
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It does not state whether this is a read-only query, what data it covers, what it returns, or any side effects or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short but not appropriately concise; it is under-specified. It consists only of a tautological phrase that adds no actionable information for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and no usage guidance, the description is completely inadequate for an agent to decide when to invoke this tool or what behavior to expect. The tool cannot be used correctly based on the provided definition alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters for the agent to interprethysics, which matches the baseline of 4. No parameter documentation is necessary since the input schema is effectively unrestricted and empty.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'search past failures' merely restates the tool name, providing no meaningful elaboration on what constitutes a 'past failure' or what the search returns. It also offers no differentiation from sibling tools like get_regression_test or replay_behavior_case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus the sibling alternatives. There is no mention of intended scenarios, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0check_patch_against_memoryexplain_code_historyget_regression_testlist_invariants_for_filereplay_behavior_casesearch_past_failuresScored across 6 tools
Each tool targets a distinct action and resource, but some functional overlap exists: 'search_past_failures' and 'get_regression_test' both relate to historical failures, and 'explain_code_history' and 'check_patch_against_memory' both deal with stored repository memory. The descriptions are terse but generally enough to guide selection.
All tool names follow a consistent lowercase snake_case verb-first pattern: search_, explain_, check_, list_, get_, replay_. The naming style is uniform and predictable across the entire set.
Six tools is well-scoped for a specialized repository memory/invariant server. Each tool has a clear purpose, and the count feels neither thin nor bloated for the apparent domain.
The surface covers the main read/replay workflow: searching failures, explaining history, checking patches, listing invariants, and replaying test cases. The only notable gap is the lack of any tool to record or update memory/invariants, but this may be intentional if ingestion happens outside the server.
A read-only verified record of agent-operable GTM tools: search, fetch, compare, track changes.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Read-only AI coding tools for change verification, release readiness, capacity, and guidance.
Never let your agent repeat a bug or linger on a known issue. Search 385+ failure lessons to skip known errors instantly.
