# opencode-plugin-doomloop

**Repository Path**: ulong9464/opencode-plugin-doomloop

## Basic Information

- **Project Name**: opencode-plugin-doomloop
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-25
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# opencode-plugin-doomloop

检测并打破 AI 编码助手中的死循环行为。当 AI 重复调用相同工具或陷入重复思考时，自动注入系统提醒强制 AI 换思路。

适用于 [OpenCode](https://opencode.ai) 编码助手，特别针对 qwen3.6plus 等容易陷入循环的模型优化。

## 问题场景

使用 AI 编码助手时，你是否遇到过：
- AI 连续 3+ 次调用同一个工具（如反复 `read` 同一个文件）
- AI 的思考内容不断重复，陷入"分析-分析-分析"的死循环
- AI 卡在某个问题上不断重试，不尝试新方法

这个插件会在检测到重复行为时，自动给 AI 发送警告，强制它改变策略。

## 安装

### 方式一：让 AI 帮你安装（推荐）

**复制以下提示词发给你的 AI 助手：**

```
请帮我安装 opencode-plugin-doomloop 插件。

步骤：
1. 克隆插件代码：
   git clone https://gitee.com/ulong9464/opencode-plugin-doomloop.git ~/.opencode/plugins/doomloop

2. 获取插件的绝对路径：
   - Linux/macOS: 运行 realpath ~/.opencode/plugins/doomloop
   - Windows: 运行 cd %USERPROFILE%\.opencode\plugins\doomloop && cd

3. 打开我的 opencode 配置文件：
   - Linux/macOS: ~/.config/opencode/opencode.json
   - Windows: %USERPROFILE%\.config\opencode\opencode.json

4. 在 "plugin" 数组中添加（使用 file:// 前缀 + 第 2 步获取的绝对路径）：
   "file://第2步获取的绝对路径"
   
   例如：
   - Linux/macOS: "file:///home/用户名/.opencode/plugins/doomloop"
   - Windows: "file:///C:/Users/用户名/.opencode/plugins/doomloop"

5. 如果 plugin 数组不存在，创建它
6. 确认 JSON 格式正确，没有语法错误
```

### 方式二：手动安装

<details>
<summary><b>Linux / macOS</b></summary>

```bash
# 1. 克隆插件
mkdir -p ~/.opencode/plugins
git clone https://gitee.com/ulong9464/opencode-plugin-doomloop.git ~/.opencode/plugins/doomloop

# 2. 编辑配置文件
nano ~/.config/opencode/opencode.json

# 3. 添加配置（见下方）

# 4. 重启 opencode
```

</details>

<details>
<summary><b>Windows (PowerShell)</b></summary>

```powershell
# 1. 克隆插件
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.opencode\plugins"
git clone https://gitee.com/ulong9464/opencode-plugin-doomloop.git "$env:USERPROFILE\.opencode\plugins\doomloop"

# 2. 编辑配置文件
notepad "$env:USERPROFILE\.config\opencode\opencode.json"

# 3. 添加配置（见下方）

# 4. 重启 opencode
```

</details>

### 方式三：源码编译安装

适用于需要修改插件源码或使用最新开发版本的场景。

**前置要求：** 已安装 [Bun](https://bun.sh/)

<details>
<summary><b>Linux / macOS</b></summary>

```bash
# 1. 克隆源码
mkdir -p ~/.opencode/plugins
git clone https://gitee.com/ulong9464/opencode-plugin-doomloop.git ~/.opencode/plugins/doomloop
cd ~/.opencode/plugins/doomloop

# 2. 编译插件
bun build src/index.ts --outdir=dist --target=node --format=esm

# 3. 验证编译产物
ls -la dist/index.js  # 应输出约 28KB 的文件

# 4. 编辑配置文件
nano ~/.config/opencode/opencode.json

# 5. 在 plugin 数组中添加（带可选配置）：
#    ["file:///home/你的用户名/.opencode/plugins/doomloop", { "debug": true }]

# 6. 重启 opencode
```

</details>

<details>
<summary><b>Windows (PowerShell)</b></summary>

```powershell
# 1. 克隆源码
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.opencode\plugins"
git clone https://gitee.com/ulong9464/opencode-plugin-doomloop.git "$env:USERPROFILE\.opencode\plugins\doomloop"
cd "$env:USERPROFILE\.opencode\plugins\doomloop"

# 2. 编译插件
bun build src/index.ts --outdir=dist --target=node --format=esm

# 3. 验证编译产物
dir dist\index.js  # 应输出约 28KB 的文件

# 4. 编辑配置文件
notepad "$env:USERPROFILE\.config\opencode\opencode.json"

# 5. 在 plugin 数组中添加（带可选配置）：
#    ["file:///C:/Users/你的用户名/.opencode/plugins/doomloop", { "debug": true }]

# 6. 重启 opencode
```

</details>

> **提示：** 修改 `src/index.ts` 后需要重新运行 `bun build` 命令编译。

### 配置

在 `opencode.json` 的 `plugin` 数组中添加：

**Linux / macOS:**
```json
{
  "plugin": [
    "file:///home/你的用户名/.opencode/plugins/doomloop"
  ]
}
```

**Windows:**
```json
{
  "plugin": [
    "file:///C:/Users/你的用户名/.opencode/plugins/doomloop"
  ]
}
```

> 注意：Windows 路径使用正斜杠 `/`，不要用反斜杠 `\`

### 可选配置

```json
{
  "plugin": [
    ["file:///home/你的用户名/.opencode/plugins/doomloop", { 
      "toolThreshold": 5,
      "reasoningThreshold": 4,
      "contextThreshold": 3,
      "debug": true
    }]
  ]
}
```

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `toolThreshold` | `3` | 连续多少次相同工具调用触发警告 (1-100) |
| `reasoningThreshold` | `3` | 连续多少次相似思考内容触发警告 (1-100) |
| `contextThreshold` | `2` | 上下文块重复多少次触发警告 (1-100) |
| `maxHistory` | `50` | 历史记录最大长度 (1-100) |
| `maxSessions` | `100` | 最大会话缓存数量 (1-100) |
| `debug` | `false` | 启用调试日志输出 |

## 工作原理

```
┌─────────────────────────────────────────────────┐
│  AI 每次准备调用工具前                            │
│         ↓                                       │
│  插件检查历史：                                  │
│  - 是否连续 N 次调用相同工具+相同参数？           │
│  - 是否连续 N 次思考内容高度相似？                │
│         ↓                                       │
│  检测到循环 → 在消息中注入警告：                  │
│  <system-reminder>                              │
│  DOOM LOOP DETECTED: ...                        │
│  STOP and try a DIFFERENT approach              │
│  </system-reminder>                             │
│         ↓                                       │
│  AI 收到警告，被迫换思路                          │
└─────────────────────────────────────────────────┘
```

### 检测能力

插件支持 **9 种**循环模式的检测：

| 类型 | 检测逻辑 | 示例 |
|------|----------|------|
| 连续重复 | 连续 N 次相同工具+相同参数 | `read(file) → read(file) → read(file)` |
| 周期循环 | A→B→C→A→B→C 模式 | `read → edit → read → edit` |
| 工具类型循环 | 忽略参数，检测工具类型循环 | `read(file1) → read(file2) → read(file3)` |
| 往返模式 | A→B→A→B 交替循环 | `read → edit → read → edit` |
| 带间隔循环 | A→B→X→A→B 允许中间干扰 | `read → edit → bash → read → edit` |
| 失败重试循环 | 工具失败后反复重试 | `execute(失败) → execute(失败) → execute(失败)` |
| 文件探索循环 | 同一文件被多种工具反复访问 | `read(a.ts) → lsp(a.ts) → grep → read(a.ts)` |
| **卡住行为检测** | AI 反复说"让我再试一次" | `"let me try again"` 重复出现 |
| **Token 膨胀检测** | 大量文字输出但无进度 | 15k+ tokens 但少于 2 个新文件 |
| 思考内容循环 | 相似 reasoning 内容重复 | 同样的分析过程重复出现 |
| 上下文重复 | 系统提示块重复注入 | 相同的 system-reminder 重复 |

### 警告级别

插件使用递增警告级别，强制 AI 停止循环：

| 警告次数 | 级别 | 标签 | 内容 |
|---------|------|------|------|
| 1 次 | NOTICE | `<system-reminder>` | 建议换方法 |
| 2 次 | WARNING | `<system-reminder>` | 强烈建议停止 |
| 3+ 次 | **CRITICAL** | **`<system-directive>`** | **强制系统指令**：明确列出必须执行的操作，禁止继续循环 |

> **指令升级机制**：当同一循环模式连续触发 3 次警告后，插件会从软提醒 `<system-reminder>` 升级为强制指令 `<system-directive>`，使用更强烈的停止命令，明确告知 AI 这是 MANDATORY SYSTEM DIRECTIVE 而非建议。

### 警告类型

| 类型 | 标识 | 说明 |
|------|------|------|
| DOOM LOOP | 工具调用循环 | 重复的工具调用模式 |
| EXPLORATION LOOP | 文件探索循环 | 同一文件被反复探索 |
| FAILURE LOOP | 失败重试循环 | 工具反复失败后继续重试 |
| **STUCK BEHAVIOR** | 卡住行为 | AI 反复说"再试一次"但无进展 |
| **TOKEN BLOAT** | Token 膨胀 | 大量输出但无实际进度 |
| THINKING LOOP | 思考循环 | 相同的分析过程重复出现 |
| CONTEXT REPETITION | 上下文重复 | 系统提示块重复注入 |

### 特性

- **9 种检测模式**：
  - 连续重复检测 (A,A,A)
  - 周期循环检测 (A→B→C→A→B→C)
  - 工具类型循环检测 (忽略参数差异)
  - 往返模式检测 (A→B→A→B)
  - 带间隔循环检测 (A→B→X→A→B)
  - 失败重试循环检测
  - 文件探索循环检测 (同一文件多种工具)
  - 卡住行为检测 (AI 反复说"再试一次")
  - Token 膨胀检测 (大量输出无进度)
- **增量处理**：只处理新消息，不重复遍历历史，长 session 也不卡
- **自动重置**：AI 换思路后警告自动消失，再次循环继续警告
- **内存安全**：LRU 淘汰机制，最多缓存 100 个 session，历史记录有界
- **配置验证**：自动验证配置参数，无效值使用默认值并输出警告
- **调试模式**：启用 `debug: true` 可查看详细检测日志
- **压缩感知**：消息压缩后自动修正计数，不会误判
- **上下文去重**：自动检测并去重重复注入的系统提示块
- **指令升级机制**：连续 3 次软提醒后升级为 `<system-directive>` 强制指令，使用更强烈的停止命令

## 许可证

MIT