# loop-deepseek

**Repository Path**: perrylink/loop-deepseek

## Basic Information

- **Project Name**: loop-deepseek
- **Description**: Self-built ReAct loop for DeepSeek. First to round-trip reasoning_content as core design (40-60% token savings). Zero-framework TS+Bun binary. Part of the Loop Engineering family.
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-22
- **Last Updated**: 2026-08-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# loop-deepseek
[![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/loop-deepseek)

[![Version](https://img.shields.io/badge/version-0.1.0-blue)](https://github.com/PerryLink/loop-deepseek)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)

> Self-built ReAct agent loop engine with `reasoning_content` full round-trip caching, directly connecting to the DeepSeek V4 API — $0.14/M tokens, 1M context, thinking mode fully managed.<br>
> 首个将 `reasoning_content` round-trip 回传作为核心设计的 agent loop 引擎——$0.14/M tokens 起，1M context，thinking 模式全托管。

**[English](#english) | [中文](#chinese)**

---

<a id="english"></a>

## English

**loop-deepseek** is an alternative to LangChain / AutoGPT / CrewAI agent frameworks, specifically optimized for DeepSeek V4's `reasoning_content` round-trip caching. It uses a zero-dependency, self-built ReAct loop compiled to a single Bun binary.

### Features

- **Self-built ReAct loop** — Thought → Action → Observation → Thought cycle, zero framework dependencies.
- **`reasoning_content` round-trip caching** — the only agent engine that preserves `reasoning_content` across turns, avoiding redundant reasoning costs.
- **Three reasoning strategies** — `FULL_RETENTION` (primary), `CACHE_INJECTION` (compaction recovery), `THINKING_DISABLED` (fallback).
- **6 built-in tools** — `bash` (sandboxed), `read`, `write`, `edit`, `glob`, `grep` — no MCP or external tool servers needed.
- **Guard layer** — pure-function `banned_behaviors` engine with L0 / L1 / L2 severity levels, compiled into the binary, bypass-proof.
- **Token budget tracker** — separate reasoning / completion / prompt token counters; 90% compaction threshold, 98% hard stop.
- **Cost control** — `--budget-limit` hard cap with real-time estimation and reasoning cache hit-rate statistics.

### Quick Start

```bash
# Clone and install
git clone https://github.com/PerryLink/loop-deepseek.git
cd loop-deepseek
bun install
bun run src/index.ts

# Or build a standalone binary
bun build --compile --target=bun src/index.ts --outfile loop-deepseek

# Run with a goal and budget
./loop-deepseek --goal "Build a Python CLI weather tool" --budget-limit 5.00

# Set your API key
export DEEPSEEK_API_KEY="sk-..."
```

**Requirements:** Bun >= 1.0.0, DeepSeek API key ([platform.deepseek.com](https://platform.deepseek.com)).

### FAQ

**Q: What makes `reasoning_content` round-trip special?**

Every other agent framework discards the model's internal reasoning after each tool call — the next turn starts with a blank reasoning slate. This forces the model to re-reason from scratch, wasting tokens. DeepSeek V4 exposes `reasoning_content` in its API response. loop-deepseek is the first agent engine to cache and re-inject it, so the model picks up where it left off — slashing reasoning token costs by 40–60 % on multi-turn tasks.

**Q: Can I use this with OpenAI-compatible endpoints?**

Yes. loop-deepseek supports both the native DeepSeek API endpoint (primary, for `reasoning_content` access) and an OpenAI-compatible fallback endpoint. Set `--endpoint openai-compat` to use compatibility mode. Note that `reasoning_content` is only available on the native endpoint.

**Q: What happens when I hit the budget limit?**

The loop stops gracefully at the next tool-call boundary. It logs the current state, partial artifacts, and a cost summary to `state.json`. You can increase the budget and resume with `--state-file state.json`.

**Q: How do I run tests?**

```bash
bun test                # run all tests
bun test --coverage     # with coverage report
bun run lint            # ESLint check
bun run format:check    # Prettier check
```

---

<a id="chinese"></a>

## 中文文档 / Chinese Docs

**loop-deepseek** 是 LangChain / AutoGPT / CrewAI agent 框架的替代方案，专为 DeepSeek V4 的 `reasoning_content` round-trip 缓存优化。零依赖、自建 ReAct 循环，编译为单个 Bun 二进制文件。

### 功能特性

- 🔄 **自建 ReAct 循环** — Thought → Action → Observation → Thought 循环，零框架依赖。
- 🧠 **`reasoning_content` round-trip 缓存** — 唯一跨轮保留 `reasoning_content` 的 agent 引擎，避免重复推理成本。
- 🎯 **三种推理策略** — `FULL_RETENTION`（主策略）、`CACHE_INJECTION`（压缩恢复）、`THINKING_DISABLED`（回退）。
- 🛠️ **6 个内置工具** — `bash`（沙箱）、`read`、`write`、`edit`、`glob`、`grep` — 无需 MCP 或外部工具服务器。
- 🛡️ **Guard 层** — 纯函数 `banned_behaviors` 引擎，L0 / L1 / L2 三级拦截，编译进二进制，不可绕过。
- 💰 **Token 预算追踪** — 独立的 reasoning / completion / prompt token 计数器；90% 压缩阈值，98% 硬停止。
- 💵 **成本控制** — `--budget-limit` 硬上限，带实时估算和 reasoning 缓存命中率统计。

### 快速开始

```bash
# 克隆并安装
git clone https://github.com/PerryLink/loop-deepseek.git
cd loop-deepseek
bun install
bun run src/index.ts

# 或编译独立二进制文件
bun build --compile --target=bun src/index.ts --outfile loop-deepseek

# 带目标和预算运行
./loop-deepseek --goal "用 Python 构建 CLI 天气工具" --budget-limit 5.00

# 设置 API 密钥
export DEEPSEEK_API_KEY="sk-..."
```

**环境要求：** Bun >= 1.0.0，DeepSeek API 密钥（[platform.deepseek.com](https://platform.deepseek.com)）。

### 常见问题

**Q: `reasoning_content` round-trip 有什么特别之处？**

所有其他 agent 框架在每次工具调用后都会丢弃模型的内部推理——下一轮从空白的推理状态开始。这迫使模型从头重新推理，浪费了大量 token。DeepSeek V4 在其 API 响应中暴露了 `reasoning_content`。loop-deepseek 是首个将其缓存并重新注入的 agent 引擎，让模型从上次中断处继续——在多轮任务中可节省 40–60% 的推理 token 成本。

**Q: 能否用于 OpenAI 兼容端点？**

可以。loop-deepseek 同时支持原生 DeepSeek API 端点（主模式，用于访问 `reasoning_content`）和 OpenAI 兼容回退端点。使用 `--endpoint openai-compat` 启用兼容模式。注意：`reasoning_content` 仅在原生端点上可用。

**Q: 达到预算上限会发生什么？**

循环会在下一个工具调用边界优雅停止，将当前状态、部分产物和成本摘要记录到 `state.json`。您可以增加预算，然后通过 `--state-file state.json` 恢复运行。

**Q: 如何运行测试？**

```bash
bun test                # 运行所有测试
bun test --coverage     # 带覆盖率报告
bun run lint            # ESLint 检查
bun run format:check    # Prettier 检查
```

---

## Related Projects / 相关项目

| Project | Description / 描述 |
|---|---|
| [loop-superpowers](https://github.com/PerryLink/loop-superpowers) | Pure Skill mini-loops for Claude Code / Claude Code 纯 Skill 迷你循环 |
| [loop-opencode](https://github.com/PerryLink/loop-opencode) | Closed-loop driver for OpenCode CLI / OpenCode CLI 闭环驱动 |
| [loop-codex](https://github.com/PerryLink/loop-codex) | Dual-channel (JSON-RPC + CDP) driver for Codex Desktop / Codex Desktop 双通道驱动 |
| [loop-copilot](https://github.com/PerryLink/loop-copilot) | Closed-loop driver for GitHub Copilot SDK / GitHub Copilot SDK 闭环驱动 |
| [loop-cursor](https://github.com/PerryLink/loop-cursor) | Closed-loop driver for Cursor IDE SDK / Cursor IDE SDK 闭环驱动 |
| [loop-ollama](https://github.com/PerryLink/loop-ollama) | Self-built ReAct agent loop for local Ollama models / 本地 Ollama 模型自建 ReAct 循环 |
| [loop-antigravity](https://github.com/PerryLink/loop-antigravity) | Closed-loop driver for Google Antigravity / Gemini / Google Antigravity / Gemini 闭环驱动 |
| [loop-openclaw](https://github.com/PerryLink/loop-openclaw) | Multi-agent loop config generator for OpenClaw Gateway / OpenClaw Gateway 多 agent 循环配置生成器 |

---

## License

Apache License 2.0 — see [LICENSE](./LICENSE) for full text.

Copyright 2026 Perry Link