# ThinkLoop

**Repository Path**: xwb602625136/ThinkLoop

## Basic Information

- **Project Name**: ThinkLoop
- **Description**: 一个提升LLM回复质量的工具。
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-18
- **Last Updated**: 2026-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<img width="1187" height="267" alt="image" src="https://github.com/user-attachments/assets/3fc5b28a-92a3-4537-8a9d-4819502d22da" />


# ThinkLoop · 多功能 AI 工具箱

## 设计动机：

### 多模型对话
> 单个 LLM 的回答常带幻觉、过时信息或推理跳跃。让执行模型与审核模型角色分离，能显著降低事实错误并提升内容完整度。

### 翻译
> 苦于某度翻译各种广告、非 VIP 限制图文翻译次数等，于是创建了 **翻译** 功能，借助视觉模型实现翻译自由。

### 提示词管理
> 提示词每次都需要重新编辑，于是做了一个提示词模版管理工具，支持维护模版、支持直接编辑不保存复制功能，这样每次就在模版上填入本次任务内容即可复制使用。

基于以上，一个集 **审核-反思对话**、**AI 翻译**、**提示词管理** 于一体的多功能 AI 工具箱就诞生了。所有功能均通过可配置的 OpenAI-compatible API 驱动，支持任意兼容的 LLM 后端。

---

## 功能概览

| 功能 | 说明 | 核心技术 |
|------|------|---------|
| **审核-反思对话** | 双模型互审，执行端与审核端角色分离，自动循环反思改进 | WebSocket 流式渲染、结构化审核协议 |
| **AI 翻译** | 文本翻译 + 图片翻译，支持文件上传，多语言方向选择 | 独立 API 配置、AES-GCM 加密存储 |
| **提示词管理** | 管理可复用的提示词片段，支持创建、编辑、复制、删除 | 持久化 JSON 文件、搜索过滤 |

---

## 功能一：审核-反思对话

<img width="1847" height="956" alt="image" src="https://github.com/user-attachments/assets/6055ce18-c2b7-4341-b9a1-308930f5d0cb" />


### 核心流程

当一个模型回答得不够好时，由另一个模型来挑刺、给修改建议，再让第一个模型基于审核意见重新作答 —— 循环若干轮，输出经过相互校验的最终回答。

```
用户提问 → [执行模型] 生成回答 → [审核模型] 评估
  → verdict=pass → 直接输出
  → needs_improvement → 执行模型反思改进 → 再次审核（循环）
  → 达到 maxCycles 次后输出最终结果
```

### 主要特性

- **多模型互审**：通过 `models.json` 配置任意 OpenAI-compatible 模型作为「执行模型」与「审核模型」
- **可配置反思轮数**：默认 2 轮，1-5 可调；审核通过时自动短路
- **结构化审核报告**：每轮输出 issues / overall_score / verdict 三段式结果
- **多窗口并行对话**：侧边栏多开会话，互不干扰，每会话可独立指定模型
- **模版系统**：保存「执行提示词 + 审核提示词」组合，一键复用
- **流式渲染**：基于 WebSocket 的事件驱动，逐阶段推送 + Markdown 代码高亮
- **反思模式可关**：关闭后等同普通单轮问答

### 使用方式

1. 点击侧边栏 **+** 新建会话
2. 选择模版（提供执行提示词 + 审核提示词预设）
3. 可选择执行端 / 审核端模型，不修改则沿用全局设置
4. 输入消息后发送，系统自动执行审核-反思循环
5. 每条回复下方可展开「审核报告」查看每轮评分与问题详情

### 设置面板
<img width="820" height="325" alt="image" src="https://github.com/user-attachments/assets/3c9698d7-9335-4a5c-acae-fb05a131cb87" />

<img width="825" height="646" alt="image" src="https://github.com/user-attachments/assets/58ebeff4-9d46-4437-b103-39e9ab708164" />

侧边栏底部入口：

- **循环次数**：审核/反思闭环运行次数（1-5）
- **模型角色**：全局执行端 / 审核端模型选择
- **LLM 配置**：新增、编辑、删除模型配置（API Key 服务端遮蔽）
- **模版管理**：新增、编辑、删除审核模版

---

## 功能二：AI 翻译
<img width="1852" height="955" alt="image" src="https://github.com/user-attachments/assets/4bd88771-b7a9-41cc-b70f-0c98019e79a9" />

### 主要特性

- **文本翻译**：支持中文 / 英文双向翻译，自动检测源语言
- **图片翻译**：上传或拖放图片，利用多模态模型提取并翻译图中文字
- **文件上传**：支持 .txt、.md、.json、.html、.xml、.csv 等文本格式导入
- **独立 API 配置**：翻译功能拥有独立的 LLM 配置（不与对话共享），API Key 经 AES-GCM 加密后存储在 localStorage
- **粘贴/拖放**：图片区域支持粘贴板粘贴和拖放上传

### 使用方式

1. 通过顶部导航切换到翻译模式
2. 选择源语言和目标语言（中文 / 英文）
3. 在文本模式下输入或粘贴要翻译的内容（或上传文件）
4. 在图片模式下拖放/粘贴/点击上传图片
5. 点击翻译按钮执行，结果展示在右侧面板
6. 可点击复制按钮一键复制翻译结果

### 安全说明

翻译 API Key 使用 Web Crypto API (AES-GCM) 加密后存入 `localStorage`，密钥不落盘。每次读/写都经过加密/解密操作。

---

## 功能三：提示词管理
<img width="1845" height="748" alt="image" src="https://github.com/user-attachments/assets/34fe877d-b420-4a08-bcda-2ac722be3844" />

### 主要特性

- **提示词管理**：集中的提示词编辑器，支持创建、编辑、删除
- **搜索过滤**：按名称实时搜索过滤
- **一键复制**：快速复制提示词内容
- **复制副本**：基于现有提示词快速创建变体
- **持久化存储**：所有提示词保存在 `prompts.json`，重启后保留

### 使用方式

1. 通过顶部导航切换到提示词管理
2. 左侧列表展示所有提示词，支持搜索
3. 点击 **+** 新建提示词，自动在列表中创建并选中
4. 右侧编辑区域可修改名称和内容
5. 每项提示词的 **⋯** 菜单支持复制副本和删除操作
6. 编辑后点击「保存」更新

---

## 快速开始

### 1. 安装

```bash
npm install
```

### 2. 配置模型

在项目根目录创建 `models.json`（已加入 `.gitignore`，不会被提交到仓库）：

```json
[
  {
    "id": "my-executor",
    "name": "GPT-4o",
    "baseURL": "https://api.openai.com/v1",
    "apiKey": "sk-xxx",
    "model": "gpt-4o"
  },
  {
    "id": "my-auditor",
    "name": "Claude Sonnet",
    "baseURL": "https://api.anthropic.com/v1",
    "apiKey": "sk-xxx",
    "model": "claude-sonnet-4"
  }
]
```

每个模型配置对应一个 OpenAI-compatible API（`POST /v1/chat/completions`）。至少配置 1 个模型即可运行对话功能。翻译功能有独立的 API 配置，在翻译页中设置。

支持任意兼容 OpenAI 接口的服务：OpenAI、Anthropic、Google、本地部署的 llama.cpp / Ollama / vLLM / LM Studio 等。

### 3. 启动

```bash
npm run dev
```

并发启动后端（`localhost:3001`）和前端（`localhost:5173`）。

### 4. 单独运行 / 停止

```bash
npm run dev:backend   # 仅后端（tsx watch）
npm run dev:frontend  # 仅前端 (vite)
npm run build         # 构建生产版本
npm run stop          # 关闭 dev 启动的进程
```

---

## 项目结构

```
chat_agent/
├── models.json                     # [安全] 模型配置（对话用）
├── templates.json                  # 运行时持久化的用户模版
├── prompts.json                    # 运行时持久化的提示词
├── src/
│   ├── shared/
│   │   └── types.ts                # 前后端共享 WebSocket / 业务类型
│   ├── backend/
│   │   ├── index.ts                # 后端入口
│   │   ├── server.ts               # Express + WebSocketServer 路由
│   │   ├── api-provider.ts         # OpenAI-compatible API 客户端抽象
│   │   ├── session/
│   │   │   ├── session-manager.ts  # 纯内存会话管理
│   │   │   └── types.ts
│   │   ├── cycle/
│   │   │   ├── cycle-orchestrator.ts # 审核-反思状态机（AsyncGenerator）
│   │   │   └── retry.ts            # API 调用自动重试
│   │   ├── audit/
│   │   │   └── audit-protocol.ts   # 审核提示词模板 + 报告解析器
│   │   ├── prompt/
│   │   │   └── prompt-manager.ts   # 提示词持久化管理
│   │   ├── template/
│   │   │   └── template-manager.ts # 模版持久化（templates.json）
│   │   └── __tests__/
│   ├── frontend/
│   │   ├── main.tsx
│   │   ├── App.tsx                 # 顶层状态 + WS 事件 + 路由
│   │   ├── Sidebar.tsx             # 会话列表 + 搜索
│   │   ├── ChatWindow.tsx          # 对话消息流 + 输入工具栏
│   │   ├── SettingsPanel.tsx       # 全局设置模态框
│   │   ├── NewDialogModal.tsx      # 新建对话弹窗
│   │   ├── ProgressIndicator.tsx   # Cycle 阶段进度
│   │   ├── AuditReportPanel.tsx    # 单轮审核报告 UI
│   │   ├── TranslationTab.tsx      # 【翻译】文本 + 图片翻译
│   │   ├── PromptTools.tsx         # 【提示词】编辑器
│   │   ├── TemplateManager.tsx     # 独立模版管理
│   │   ├── useWebSocket.ts         # WebSocket Hook（自动重连）
│   │   ├── crypto-storage.ts       # AES-GCM 加密存储
│   │   ├── index.css               # 全局样式
│   │   └── __tests__/
├── docs/
│   ├── adr/                        # 架构决策记录
│   └── agents/                     # 项目内部约定
├── package.json
├── vite.config.ts
├── tsconfig.json / tsconfig.backend.json
├── CONTEXT.md
└── README.md
```

---

## 技术栈

| 层 | 技术 |
|----|------|
| 前端 | React 19 + Vite 6 + TypeScript 5 |
| 渲染 | react-markdown + rehype-highlight + remark-gfm |
| 后端 | Node.js + Express + ws (WebSocket) |
| 模型调用 | OpenAI-compatible API（`POST /v1/chat/completions`）|
| 持久化 | localStorage（会话/翻译配置）+ JSON 文件（模版/提示词） |
| 加密 | Web Crypto API (AES-GCM) |
| 测试 | Vitest + @testing-library/react + jsdom |

---

## 安全性

### API Key 保护
- **服务端遮蔽** — 下发的 API Key 自动替换为 `********`，前端无法直接读取
- **加密存储** — 翻译 API Key 使用 AES-GCM 加密后存入 localStorage
- **一次性输入** — 密码类型输入框，聚焦自动清空遮蔽值

---

## WebSocket 协议（对话功能）

### 客户端 → 服务端

| type | 说明 |
|------|------|
| `ping` | 心跳 |
| `session:list` | 拉取服务端会话列表 |
| `session:create` | 新建会话 |
| `session:close` | 关闭会话 |
| `chat:message` | 发送消息（含上下文恢复） |
| `config:update` | 更新全局配置 |
| `config:save-models` | 保存模型配置到文件 |
| `template:create / update / delete / list` | 模版 CRUD |
| `prompt:create / update / delete / list` | 提示词 CRUD |

### 服务端 → 客户端

| type | 说明 |
|------|------|
| `config:updated` | 当前全局配置（含模型列表） |
| `session:*` | 会话生命周期事件 |
| `template:*` / `prompt:*` | 模版/提示词变更通知 |
| `cycle:start` | Cycle 开始 |
| `executor:*` | 执行端各阶段（generating / streaming / response / complete） |
| `audit:*` | 审核端进度与结果 |
| `reflection:*` | 反思阶段 |
| `cycle:complete` | Cycle 结束，含最终答案和所有轮次详情 |
| `cycle:error` | 错误通知 |

### Audit Report 结构

```json
{
  "issues": [
    {
      "severity": "high",
      "description": "事实错误：XX",
      "suggestion": "应改为 YY"
    }
  ],
  "overall_score": 7,
  "verdict": "needs_improvement"
}
```

---

## 测试

```bash
npm test              # 一次性运行
npm run test:watch    # 监听模式
```

---

## 常见问题

**Q: 三个功能共用同一套 API Key 吗？**
A: 对话功能和翻译功能使用独立的 API 配置。对话模型在 `models.json` 中配置，翻译模型在翻译页的设置面板中配置（Key 经加密存储）。

**Q: 重启服务后对话历史还在吗？**
A: 会话历史通过 `conversationHistory` 注入，重启后前端发送消息时会带上历史，模型可继续上下文。

**Q: 翻译功能支持哪些模型？**
A: 支持任意 OpenAI-compatible 的文本模型和视觉多模态模型（图片翻译需要支持多模态的模型，如 GPT-4o、Claude 3.5 Sonnet 等）。

**Q: 提示词和模版有什么区别？**
A: 模版用于对话功能，包含「执行提示词 + 审核提示词」一对组合。提示词是独立的文本片段，用于任何需要快速插入预设内容的场景，两者相互独立。

**Q: 为什么有时候反思轮数没跑满就结束了？**
A: 审核 `verdict=pass` 时短路，这是设计行为——内容已达标则跳过剩余反思以节省算力。

---

## License

MIT