内容
# 模块
本地MCP（模型上下文协议）服务器，提供 **bounce_idea** 工具 — 为您的编码代理提供独立的第二意见。它将您当前的解决方案发送到可配置的LLM批评者，进行架构审查、漏洞搜索和替代方法。
## 工作原理
```
[您的代理] ──bounce_idea──> [模块MCP服务器] ──prompt──> [您的LLM]
│ │
└───── 批评 ◄──────────────┘
```
模块实现了 **双层推理** 模式：您的主要代理执行实现，而独立配置的LLM扮演着无情的高级批评者的角色。这打破了局部最优解，并在问题到达生产环境之前捕获它们。
## 自带模型/自带密钥
模块是完全本地的。您可以选择批评者模型并提供自己的API密钥：
- **Gemini** （默认）— 快速、长上下文、廉价
- **OpenAI** — GPT-4.1-mini、GPT-5等
- **Ollama / vLLM / LM Studio** — 任何具有OpenAI兼容 `/v1/chat/completions` 端点的本地模型
## 快速入门
### Go安装
```bash
go install github.com/redstone-md/nodule/cmd/nodule@latest
```
### npm
```bash
npx @redstone-md/nodule
```
### 配置（环境变量）
| 变量 | 默认值 | 描述 |
|---|---|---|
| `NODULE_LLM_PROVIDER` | `gemini` | LLM提供者：`gemini` 或 `openai` |
| `NODULE_MODEL_NAME` | `gemini-2.5-flash` | 模型标识符 |
| `NODULE_API_KEY` | — | API密钥（备用：`GEMINI_API_KEY`、`GOOGLE_API_KEY`、`OPENAI_API_KEY`） |
| `NODULE_LLM_BASE_URL` | — | OpenAI兼容服务器的基准URL（例如 `http://localhost:11434/v1`） |
| `NODULE_TEMPERATURE` | `1.2` | 批评温度（越高 = 越有创意） |
| `NODULE_MAX_TOKENS` | `4096` | 最大输出令牌数 |
| `NODULE_SERVER_NAME` | `nodule` | MCP服务器名称 |
| `NODULE_SERVER_VERSION` | `0.4.1` | MCP服务器版本 |
### 示例
**Gemini（默认）：**
```bash
export NODULE_API_KEY="your-gemini-key"
export NODULE_MODEL_NAME="gemini-2.5-flash"
npx @redstone-md/nodule
```
**OpenAI：**
```bash
export NODULE_LLM_PROVIDER="openai"
export NODULE_API_KEY="sk-..."
export NODULE_MODEL_NAME="gpt-4.1-mini"
npx @redstone-md/nodule
```
**本地Ollama（无需API密钥）：**
```bash
export NODULE_LLM_PROVIDER="openai"
export NODULE_LLM_BASE_URL="http://localhost:11434/v1"
export NODULE_MODEL_NAME="qwen3:8b"
npx @redstone-md/nodule
```
## MCP工具：`bounce_idea`
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `context` | 字符串 | 是 | 当前代码库状态、函数签名、基准测试或错误日志 |
| `proposed_solution` | 字符串 | 是 | 代理计划应用的草稿想法或代码 |
| `focus` | 字符串 | 否 | 批评专业化：`performance`、`architecture`、`security`、`edge_cases`（默认：`performance`） |
### 焦点模式
- **`performance`** — 隐藏分配、O(N^2)路径、缓存未命中、锁竞争
- **`architecture`** — 封装泄漏、循环依赖、神对象、SRP违规
- **`security`** — 注入漏洞、不安全操作、输入验证间隙
- **`edge_cases`** — 竞争条件、死锁、nil/空输入、上下文取消
## MCP客户端配置
> **对于AI代理：** 一个分步、复制粘贴的安装指南，适用于LLM，位于 [`docs/INSTALL_FOR_LLM.md`](docs/INSTALL_FOR_LLM.md)。
### Claude Code
最快 — 一个命令（用户范围，在每个项目中可用）：
```bash
claude mcp add nodule --scope user \
-e NODULE_LLM_PROVIDER=gemini \
-e NODULE_API_KEY=your-key \
-e NODULE_MODEL_NAME=gemini-2.5-flash \
-- npx -y @redstone-md/nodule@latest
```
验证：`claude mcp list` 应该显示 `nodule … ✔ Connected`。
或手动编辑 `~/.claude.json` （顶级 `mcpServers`）：
```json
{
"mcpServers": {
"nodule": {
"command": "npx",
"args": ["-y", "@redstone-md/nodule@latest"],
"env": {
"NODULE_LLM_PROVIDER": "gemini",
"NODULE_API_KEY": "your-key",
"NODULE_MODEL_NAME": "gemini-2.5-flash"
}
}
}
}
```
### OpenCode (`~/.config/opencode/opencode.json`)
OpenCode使用单个 `command` 数组，而不是 `command` + `args`:
```json
{
"mcp": {
"nodule": {
"type": "local",
"command": ["npx", "-y", "@redstone-md/nodule@latest"],
"enabled": true,
"env": {
"NODULE_LLM_PROVIDER": "openai",
"NODULE_LLM_BASE_URL": "https://api.openai.com/v1",
"NODULE_API_KEY": "sk-...",
"NODULE_MODEL_NAME": "gpt-4.1-mini"
}
}
}
}
```
### Cursor / VS Code
```json
{
"mcp.servers": {
"nodule": {
"command": "npx",
"args": ["-y", "@redstone-md/nodule@latest"],
"env": {
"NODULE_LLM_PROVIDER": "openai",
"NODULE_API_KEY": "your-key",
"NODULE_MODEL_NAME": "gpt-4.1-mini"
}
}
}
}
```
### 首次运行注意（如果它“无法连接”）
`npx` 在首次启动时下载一个约16 MB的平台二进制文件。冷启动可能会超过MCP客户端的启动超时，而**陈旧的npx缓存**（来自旧版本的缓存）是最常见的故障。在终端中预热一次，然后（重新）启动客户端：
```bash
npm cache clean --force # 仅当以前的版本行为异常时
npx -y @redstone-md/nodule@latest # 等待“nodule: ready”，然后 Ctrl+C
```
## 技能（Claude Code）
一个捆绑的技能教会代理 *何时* 和 *如何* 良好地调用 `bounce_idea`。安装：
```bash
mkdir -p ~/.claude/skills/nodule
cp skills/nodule/SKILL.md ~/.claude/skills/nodule/SKILL.md
```
## 开发
```bash
# 构建
go build ./cmd/nodule/
# 测试
go test ./...
# 检查
go vet ./...
```
## 架构
```
cmd/nodule/main.go # 入口点：配置 → 提供者 → 服务器
internal/
config/config.go # 基于环境的BYOM/BYOK配置
llm/
client.go # llm.Client 接口（自带模型）
gemini.go # Gemini 提供者（google.golang.org/genai）
openai.go # OpenAI 兼容提供者（Ollama、vLLM等）
llmmock/mock.go # llm.Client 的测试替身
prompt/builder.go # 系统/用户提示程序，按焦点模式组装
mcpserver/server.go # MCP 服务器 + bounce_idea 工具处理程序
```
## 许可证
MIT
