pingpong (Ajaxdude)

⚠️ 失望：搬到 脑路由器

备注：该项目现在是 脑路由器。所有新的开发、功能和错误修复都在那里进行。

Pingpong是一个MCP服务器 哦，我的皮 这为您的AI代理提供了一个本地代码审查器。工作完成后，代理人打电话 request_review.Pangpong将git diff、PRD和任务上下文发送到本地LLM（llama.cpp），LLM审查工作并返回结构化反馈——所有这些都在同一个工具调用中。代理在一个高级云请求内进行修改和重试。基于浏览器的升级UI处理本地LLM无法解决的情况。

可选地，模型路由器为每个任务选择最便宜的足够模型，通过LiteLLM代理进行路由。

______________________________________________________________________

快速开始

哦，我的pi（推荐）

curl -sSL https://raw.githubusercontent.com/ajaxdude/pingpong/master/install.sh | bash

安装程序：

• 将此仓库克隆到 ~/.omp/skills/pingpong/
• 构建TypeScript
• 安装 node_modules 进入技能文件夹
• 写 ~/.omp/agent/mcp.json 指着 ~/.omp/skills/pingpong/dist/mcp.js
• 注入 templates/APPEND_SYSTEM.md 和 templates/LLAMACPP.md 进入您的代理配置

安装后，创建 pingpong.config.json 在每个需要评审的项目中（请参见 配置).

手册

git clone https://github.com/ajaxdude/pingpong.git
cd pingpong
npm install && npm run build

添加到MCP配置中：

{
  "mcpServers": {
    "pingpong": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/pingpong/dist/mcp.js"]
    }
  }
}

______________________________________________________________________

运作原理

1. 您的代理完成任务并呼叫 request_review.
2. 乒乓球会创建一个会话并阻止，直到审核结束。
3. 乒乓球读当地 pingpong.config.json，收集git diff、PRD和任何 AGENTS.md.
4. 本地LLM（llama.cpp）审查上下文，并以JSON判决作出响应：

{ "status": "approved" | "needs_revision" | "escalated", "feedback": "..." }

1. 开 needs_revision：将反馈添加到会话历史记录中，循环继续（最多到 maxIterations).
2. 开 approved: request_review 立即将判决返回给代理人。
3. 开 escalated 或LLM失败：浏览器UI在以下位置打开 http://localhost:3458/review-requests 供人类审查。

代理人收到 最终解决状态 从 request_review --从来没有 pending 需要轮询的响应。

______________________________________________________________________

MCP工具

request_review

提交已完成的工作以供自动审查。阻止，直到审查达到最终状态。

输入：

返回：

{
  "status": "approved",
  "feedback": "Looks good. Error handling is solid.",
  "sessionId": "abc123",
  "iterationCount": 2,
  "reviewerType": "llm"
}

status 总是终端： approved, needs_revision，或 escalated代理人应该治疗 needs_revision 作为修复和重新提交的指令。

审核内容：

• Git diff （git diff HEAD)
• PRD项目（自动检测自 ./docs/PRD.md, ./PRD.md，或 ./README.md)
• AGENTS.md 如存在
• 内置标准：正确性、安全性、性能、可维护性、测试覆盖率、文档

______________________________________________________________________

get_session_list

返回所有会话（用于调试或仪表板）。

{
  "sessions": [
    { "id": "abc123", "taskId": "feature-20260314-001", "status": "approved", "summary": "..." }
  ]
}

______________________________________________________________________

get_session_details

返回会话的完整详细信息。

输入： sessionId （字符串，必填）

退货包括： status, llmFeedback, humanFeedback, escalationReason, iterationCount, reviewerType

______________________________________________________________________

resolve_session

手动解析会话。用于web UI和测试。

输入： sessionId （字符串）， feedback （字符串）

______________________________________________________________________

模型路由（可选）

这 select_model 该工具在重要的LLM调用之前选择最便宜的足够模型。

select_model

输入： prompt （字符串，必填）， context （字符串，可选）

返回：

{ "model": "claude-sonnet-4", "cached": false, "latencyMs": 42 }

路由如何工作：

1. 提示的前500个字符被散列以进行缓存查找（200个条目LRU）。
2. 缓存未命中：分类器（您的本地llama.cpp）从LiteLLM获取的实时模型列表中选取。
3. 选择层次：本地/小型→ 快速云→ 前沿→ 推理模型。
4. 任何路由失败都会悄无声息地回落到 router.fallbackModel.

需要运行LiteLLM代理(router.litellmBaseUrl).禁用 router.enabled: false.

______________________________________________________________________

配置

创建 pingpong.config.json 在你的 项目根目录 （不是pingpong安装目录）。乒乓球读它从 process.cwd() 启动时——每个项目一个配置。

{
  "llm": {
    "endpoint": "http://127.0.0.1:8080/v1/chat/completions",
    "model": "default",
    "temperature": 0.2,
    "maxTokens": 4096,
    "timeout": 1800
  },
  "prd": {
    "autoDetect": true,
    "paths": ["./docs/PRD.md", "./PRD.md", "./README.md"],
    "fallbackPath": null
  },
  "review": {
    "maxIterations": 5,
    "retryOnLlmError": true
  },
  "escalation": {
    "enabled": true,
    "port": 3458,
    "autoOpenBrowser": true
  },
  "gitDiff": {
    "enabled": true,
    "maxSizeBytes": 102400
  },
  "router": {
    "enabled": false,
    "litellmBaseUrl": "http://localhost:4000",
    "litellmApiKey": "sk-1234",
    "classifierUrl": "http://127.0.0.1:8080/v1/chat/completions",
    "fallbackModel": "best",
    "modelListRefreshSeconds": 60,
    "cacheMaxEntries": 200
  }
}

复制 pingpong.config.example.json 作为一个起点。

关键选项

环境变量覆盖

PINGPONG_LLM_ENDPOINT          # Override llm.endpoint
PINGPONG_LLM_MODEL             # Override llm.model
PINGPONG_LLM_TIMEOUT           # Override llm.timeout (integer seconds)
PINGPONG_PRD_PATH              # Set prd.fallbackPath
PINGPONG_ESCALATION_PORT       # Override escalation.port
PINGPONG_ROUTER_ENABLED        # "true" or "false"
PINGPONG_ROUTER_FALLBACK_MODEL # Override router.fallbackModel

______________________________________________________________________

Web用户界面和HTTP API

升级服务器在以下情况下自动启动 escalation.enabled 这是真的。中频端口 3458 Pingpong已经在使用中（例如之前的实例），它会记录一个警告，并在没有web UI的情况下继续运行——stdio工具调用仍然有效。

页面

HTTP API

GET  /api/health                    Health check
GET  /api/sessions                  All sessions with full fields
POST /api/sessions/:id/feedback     Submit human review feedback
DELETE /api/sessions/:id            Delete a session
GET  /api/routing-events            Recent routing decisions

提交反馈：

curl -X POST http://localhost:3458/api/sessions//feedback \
  -H 'Content-Type: application/json' \
  -d '{"feedback": "Approved — looks good."}'

ok, lgtm, approved, looks good，或 ship it （不区分大小写）按批准的方式解决会话。

______________________________________________________________________

会话存储

会话持续到 .pingpong/sessions/ 在你的 项目根目录 （代理运行的目录，而不是pingpong安装目录）。每个会话都是一个以nanoid命名的JSON文件。超过24小时的会话将由每小时一次的清理cron清除。

添加 .pingpong/ 到你的项目 .gitignore.

______________________________________________________________________

代理合同

安装后，有两个模板文件控制代理行为：

~/.omp/agent/APPEND_SYSTEM.md --注入代理系统提示：

• 代理 必须 呼叫 request_review 完成任何任务后
• 代理人不得声称未经批准的审查就完成了工作
• needs_revision 反馈是在同一会话中修复和重新提交的指令

~/.omp/agent/LLAMACPP.md --当地法学硕士评审员的背景：

• 六个评估类别及其标准
• 所需的JSON响应格式
• 编辑以调整审核严格性或添加项目特定规则

______________________________________________________________________

发展

构建和部署

npm run build              # Compile TypeScript to dist/
npm test                   # Run all tests
npm run test:unit          # Unit tests only
npm run test:integration   # Integration tests only

# Deploy to local OMP skill installation
./scripts/sync-to-skill.sh

sync-to-skill.sh 构建，然后同步 dist/ 和 templates/ 到 ~/.omp/skills/pingpong/。运行OMP后重新启动它。

项目布局

src/
├── mcp.ts                 # MCP entry point — tool handlers, stdio transport
├── config.ts              # Config loader, env overrides, validation
├── types.ts               # All TypeScript types
├── review-loop.ts         # Review iteration orchestrator
├── llm-client.ts          # LLM HTTP client and response parser
├── llm-prompt.ts          # Prompt assembler
├── context-gatherer.ts    # PRD, git diff, AGENTS.md loading
├── session-manager.ts     # Session CRUD, file persistence, cleanup cron
├── escalation-server.ts   # Express HTTP server, all routes
├── router.ts              # ModelRouter, LiteLLM integration, route events
└── tools/
    └── mcp_pingpong_select_model.ts

templates/
├── APPEND_SYSTEM.md       # Agent system prompt additions
├── LLAMACPP.md            # Local LLM reviewer instructions
├── escalation.html        # Human review session page
├── review-requests.html   # Session dashboard
├── routing-dashboard.html # Routing events dashboard
└── setup.html             # llama.cpp setup guide

scripts/
└── sync-to-skill.sh       # Build + deploy to ~/.omp/skills/pingpong/

______________________________________________________________________

故障排除

会话停留 pending 在仪表板中 MCP工具会阻止并返回最终状态——如果你看到 pending 它意味着来自先前（损坏）版本的旧会话。通过仪表板删除过时的会话或 DELETE /api/sessions/:id.

llama.cpp未连接

curl http://127.0.0.1:8080/v1/models   # verify it is running
llama-server -p 8080 -m /path/to/model.gguf

端口3458已在使用中 之前的乒乓球进程仍在运行。杀死它，或者设置一个不同的 escalation.port 在配置中。如果端口被占用，乒乓球将记录警告并在没有web UI的情况下运行。

未检测到PRD 确保文件存在于 ./docs/PRD.md, ./PRD.md，或 ./README.md 在您的项目根目录中，或设置 prd.fallbackPath 在 pingpong.config.json.

路由器总是后退 LiteLLM未在运行 router.litellmBaseUrl，或 router.enabled 是假的。检查 router.litellmBaseUrl 在配置中。

重启后MCP未出现在工具列表中 验证 ~/.omp/agent/mcp.json 指向 ~/.omp/skills/pingpong/dist/mcp.js 并且该文件存在。

______________________________________________________________________

许可证

麻省理工学院