内容
# OrangePro
**发现测试遗漏的行为。生成有实际依据的测试，确保其真正运行。**
`opro` 从本地代码仓库中构建知识图谱，映射代码中的每个行为，显示哪些行为已测试，哪些尚未测试，并生成基于真实符号的集成级测试 - 而非虚构的导入。运行为CLI和MCP服务器。架构遵循Karpathy的LLM知识库gist中描述的`引入 → 编译 → 检查`模式，应用于代码的行为验证。
```bash
npx @orangepro/mcp-server
cd /path/to/your/repo
opro
```
就这样。你会得到：
```
.orangepro/
├── behavior-coverage.html ← 打开此文件：交互式差距报告
├── rtm.md ← 需求追踪矩阵
└── evidence-pack.json ← 机器可读的元数据导出
```
<img width="895" height="960" alt="Screenshot 2026-07-08 at 1 18 01 AM" src="https://github.com/user-attachments/assets/73b8a812-2eab-43a1-8aed-4289545e630b" />
---
## 安装
```bash
# 无需安装（npx）
npx @orangepro/mcp-server
# 或全局安装
npm install -g @orangepro/orangepro-mcp
# 或从源码安装
git clone https://github.com/OrangeproAI/orangepro-mcp.git
cd orangepro-mcp && npm ci && npm run build && npm link
```
---
## 与编码代理一起使用
OrangePro 作为MCP服务器运行。任何MCP兼容的代理（Cursor，Claude Code，Codex，Copilot，OpenCode）都可以驱动它。
### 快速代理设置
如果你已经在PATH上安装了`opro`，请为你的客户端打印确切的配置：
```bash
opro agent --client codex
opro agent --client claude-code
opro agent --client cursor
opro agent --client opencode
opro agent --client generic
```
无需全局安装。这些命令使用已发布的软件包：
```bash
# Codex
npx -y @orangepro/mcp-server@latest agent --client codex
# Claude Code
npx -y @orangepro/mcp-server@latest agent --client claude-code
# Cursor
npx -y @orangepro/mcp-server@latest agent --client cursor
# OpenCode
npx -y @orangepro/mcp-server@latest agent --client opencode
# Generic MCP clients, including VS Code/Copilot-style MCP settings
npx -y @orangepro/mcp-server@latest agent --client generic
```
### 手动MCP配置
将以下内容添加到客户端的MCP配置中：
```json
{
"mcpServers": {
"orangepro-local": {
"command": "npx",
"args": ["-y", "@orangepro/mcp-server@latest", "mcp"]
}
}
}
```
| 客户端 | 配置位置 |
|--------|----------------|
| Claude Code | `.mcp.json` 或 `~/.claude.json` |
| Cursor | `~/.cursor/mcp.json` 或 设置 → MCP |
| Codex | 由 `opro agent --client codex` 或 `npx -y @orangepro/mcp-server@latest agent --client codex` 打印的配置 |
| VS Code / Copilot | MCP设置；如果客户端接受原始MCP服务器JSON，请使用`generic`配置 |
| OpenCode | 由 `opro agent --client opencode` 打印的配置 |
### 工作流程
告诉你的代理：
> "使用 `orangepro_start`，然后使用 `orangepro_generate_tests`，基准引用为main。将每个测试写入其建议的路径，运行它，并报告通过/失败。"
代理编写测试，运行它，调用`orangepro_prove`，行为变为动态证明。一个提示，完整循环。
### MCP工具（共18个）
| 工具 | 功能 |
|------|--------------|
| `orangepro_start` | 一键设置：分析 + 报告 + 下一步操作 |
| `orangepro_analyze_sources` | 构建/刷新证据图 |
| `orangepro_generate_tests` | 为间隙生成有根据的测试 |
| `orangepro_prove` | 在行为上运行突变杀死预言 |
| `orangepro_prove_loop` | 为一个行为设置命令 + 动态证明 + 报告刷新 |
| `orangepro_find_test_gaps` | 列出具有弱/缺失测试的行为，按风险排名 |
| `orangepro_graph_score` | 图表准备度分数（0–100） |
| `orangepro_status` | 工作区状态，无需生成任何内容 |
| `orangepro_doctor` | 推荐下一个证据以提高质量 |
| `orangepro_rtm` | 需求追踪矩阵 |
| `orangepro_stats` | 聚合统计数据 |
| `orangepro_changed_impact` | 差异影响的内容（需要git + 基准引用） |
| `orangepro_record_run` | 记录测试运行结果 |
| `orangepro_explain_test` | 解释为什么生成测试 |
| `orangepro_export_evidence_pack` | 导出元数据证据包 |
| `orangepro_update_graph` | 增量图更新 |
| `orangepro_ai_links` | 弱行为→符号建议（可选AI） |
| `orangepro_ai_flows` | 候选流程发现（可选AI） |
---
## CLI参考
```bash
opro # 分析 + 报告 + 代理下一步操作
opro start --base main # 相同，限定在分支差异
opro analyze # 构建证据图
opro score # 图表准备度（0–100）
opro gaps --limit 10 # 前10个未测试的行为
opro generate --base main # PR差异的测试
opro generate --single # 顶级间隙，整个仓库
opro prove # 突变杀死预言（使用generate返回的prove_run参数）
opro rtm # 追踪矩阵
opro export # 元数据证据包
opro mcp # 运行为MCP服务器（标准输入输出）
opro doctor # 下一个证据建议
opro coverage # 引入运行时覆盖
```
在任何读取命令上添加 `--json` 以获取机器输出。运行 `opro help` 以获取完整参考。
---
## PR工作流程
```bash
opro generate --base main # 当前分支更改的测试
opro generate --pr 1234 # 检出PR #1234 — 更改工作树；需要gh + 确认（优先使用 --base）
opro generate --changed # 当前分支差异 vs main
```
每个生成的测试包括：
- **依据** — 它引用的真实文件、符号和现有测试
- **运行提示** — 在哪里编写、如何运行
- **场景桶 + 技术** — 它针对的故障模式和如何实现
---
## 测试类别
生成有证据支持。仅当图谱具有支持证据时才会生成类别 - 绝不会用通用填充器填充。这些是公共本地生成桶。更广泛的关注分类法用于规划提示，不公开覆盖分类法，不更改报告层级。
| 类别 | 功能 |
|----------|-----------------|
| Happy path | 主要预期行为 |
| Validation error | 错误/无效输入处理 |
| Edge case | 边界、空/空值、并发、重试 |
| Integration flow | 跨服务的多步骤行为 |
| Security / privacy | 认证、注入、数据泄露 |
| Regression | 固定先前损坏的行为 |
---
## 证据层级
每个行为都有且仅有一个层级。没有任何行为是凭信仰标记为“已测试”的。
| 层级 | 含义 | 如何获取 |
|------|---------------|------------------|
| **动态证明** | 真实测试杀死该行为的目标突变 | `opro prove` 在编写/运行测试后 |
| **运行时覆盖** | 覆盖工具执行此代码 | `opro start --generate-coverage` |
| **静态链接** | 导入/名称/结构匹配链接测试到此代码 | 分析期间自动 |
| **无信号** | 尚未有测试此行为 | — |
> **“动态证明 0”在第一次运行时为正常状态。** 静态分析始终运行。动态证明需要针对目标突变运行测试。这是信任模型 - 除非真实测试杀死真实突变，否则没有任何行为是动态证明的。
---
## 语言支持
OrangePro 分离静态映射、生成的测试、运行时覆盖和动态证明。这些是不同的置信度指标。
| 语言 | 静态行为提取 | 生成测试 | 运行时覆盖 | 动态证明 |
|----------|:--------------------------:|:---------------:|:----------------:|:-------------:|
| TypeScript / JavaScript | ✓ | ✓ Jest / Vitest / Mocha / AVA-style drafts | ✓ lcov.info | ✓ Vitest / Jest / Mocha |
| Python | ✓ | ✓ pytest | ✓ coverage.py / pytest-cov XML | ✓ pytest |
| Go | ✓ | ✓ 同一包 `*_test.go` | ✓ coverprofile | ✓ `go test` |
| Java | ✓ | ✓ JUnit 4/5 | ✓ JaCoCo XML | ✓ Maven/JUnit |
| Kotlin, Rust, PHP, C#, Ruby, Swift, C, C++ | ✓ 静态行为提取 | 计划 | 计划在标准覆盖存在时 | 计划证明配置文件 |
静态映射通过tree-sitter和仓库元数据在许多语言中有效。动态证明故意较窄：每种语言都需要运行器、突变定位器、沙箱配置文件和假证明回归，然后才能铸造动态证明。
---
## 模型设置（BYOK）
分析、评分和证明不需要模型密钥。生成需要。
| 提供商 | 环境变量 |
|----------|---------------------|
| OpenAI兼容 | `OPENAI_API_KEY` （可选：`OPENAI_BASE_URL`，`OPENAI_MODEL`） |
| Anthropic | `ANTHROPIC_API_KEY` （可选：`ANTHROPIC_MODEL`） |
| Ollama（本地，无密钥） | `OLLAMA_BASE_URL` （可选：`OLLAMA_MODEL`） |
自动检测顺序：OpenAI → Ollama → Anthropic。覆盖 `--provider` 和 `--model`。
运行 `opro setup` 以交互方式配置。密钥保留在环境中 - 永远不会写入图表、配置或工件中。
---
## AI候选通道
使用提供商密钥，OrangePro可以搭建弱AI行为→符号链接和AI建议的候选流程。这些是准备好用于本地使用的审查/生成工作列表，但它们不是证据：
- AI链接显示为`AI-linked`建议。
- AI流程单独存储在确定性流程之外。
- 任一通道不会更改动态证明、运行时覆盖、静态链接、分母计数或证据层级。
在您希望代理更快地找到可能的服务边界流程时使用它们；如果您希望仅使用确定性报告，请忽略它们。
---
## 工作原理
OrangePro 将 **分析**（您的代码执行的操作）与 **证明**（测试实际验证它）分开。
```
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ 您的代码 │ ──► │ 知识图谱 │ ──► │ 证据层级 │
│ （任意语言） │ │ │ │ │
└─────────────┘ └──────────────┘ └─────────────┘
│
┌──────┴──────┐
▼ ▼
┌───────────┐ ┌──────────┐
│ 差距报告 │ │ 生成测试 │
│ + 风险 │ │ │
└───────────┘ └──────────┘
```
| 阶段 | 发生情况 | 需要模型密钥？ |
|-------|-------------|-------------------|
| **分析** | AST遍历 → 行为、流程、证据层级 | 否 |
| **评分** | 图表准备度分数（0–100）及原因 | 否 |
| **生成** | 为顶级间隙生成有根据的测试，按行为 | 是（BYOK） |
| **证明** | 突变杀死预言确认测试实际中断如果行为更改 | 否 |
---
## 隐私
- **无存储源码。** 读取代码在进程中。永不上传到OrangePro服务器。
- **无源码突变。** 永不编辑现有文件。写入元数据到 `.orangepro/`。
- **仅元数据导出。** 文件路径、名称、哈希、分数 - 不是原始源码。
- **您的密钥保留您所有。** 从环境中读取，在调用时，永不持久化。
---
## 主机平台上有
此仓库是免费的本地工具。[OrangePro平台](https://orangepro.ai)添加：
- 跨PR和仓库的持久化知识图谱
- 大规模的托管动态证明（更大的预算、CI工作者、服务设置配置文件）
- PR/CI策略门控动态证明、运行时覆盖和风险增量
- Jira / Confluence / TestRail / OpenAPI 丰富
- 跨仓库智能和循环流程内存
- 生产事件关联和回归目标
- 全测试生命周期管理和团队仪表盘
---
## 贡献
```bash
npm run build # 编译到dist/
npm test # vitest
npm run typecheck # 类型检查不发出
```
参见 [docs/local-proof-kit.md](docs/local-proof-kit.md) 以获取完整开发参考。
## 许可证
[MIT](LICENSE) © OrangePro
