# minicode

**Repository Path**: yanfanVIP/minicode

## Basic Information

- **Project Name**: minicode
- **Description**: 一个基于web的本地运行的智能编码工作台 — 上下文工程、Plan 并行交付、知识图谱记忆
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-26
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MiniCode

**本地运行的智能编码工作台 — 上下文工程、Plan 并行交付、知识图谱记忆**

单个 Go 二进制 + 内嵌 Web UI，代码留在本机。支持 Claude、GPT、OpenRouter、Ollama 及 20+ 国内模型提供商，可在设置中随时切换。

<p align="center">
  <img src="documents/img/主agent.png" alt="Agent 编码助手" width="720">
</p>

<p align="center"><em>Agent 模式：流式对话、工具调用、Token 用量实时可见</em></p>

---

## 快速开始

```bash
# 构建（Node.js 18+ 构建前端，Go 1.26+ 编译后端）
(cd web && npm install && npm run build) && go build -o minicode .

# 启动（默认 http://localhost:9595）
./minicode serve --port 9595
```

Windows（PowerShell）：

```powershell
cd web; npm install; npm run build; cd ..
go build -o minicode.exe .
.\minicode.exe serve --port 9595
```

开发时可直接运行：

```bash
go run . serve --port 9595 --webroot /app/minicode
```

首次启动若无已配置的模型提供商，会进入**引导向导**完成 API Key 配置与校验。浏览器打开 **http://localhost:9595** 即可使用。

---

## 界面预览

### Agent 编码助手

Chat / Agent 双模式切换，支持多会话历史、实时 Token 统计与工具执行审批。移动端自适应布局。

<table>
  <tr>
    <td width="65%"><img src="documents/img/主agent.png" alt="桌面端 Agent" /></td>
    <td width="35%"><img src="documents/img/mobile_agent.png" alt="移动端 Agent" /></td>
  </tr>
  <tr>
    <td align="center">桌面端</td>
    <td align="center">移动端</td>
  </tr>
</table>

### Plan 并行交付

在 **Plan** 页面描述目标，与规划 Agent 讨论方案后锁定计划；系统自动拆解任务并在 Kanban 看板上并行执行，完成后自动 commit、push 并创建 PR。

<p align="center">
  <img src="documents/img/计划看板.png" alt="Plan 计划看板" width="720">
</p>

### 调用图

函数级调用关系可视化，支持包/类型筛选、节点详情与源码跳转。大型项目可展示上千节点。

<table>
  <tr>
    <td width="65%"><img src="documents/img/调用图.png" alt="桌面端调用图" /></td>
    <td width="35%"><img src="documents/img/mobile_调用图.png" alt="移动端调用图" /></td>
  </tr>
  <tr>
    <td align="center">桌面端 · 1010 节点交互画布</td>
    <td align="center">移动端</td>
  </tr>
</table>

### 文件浏览器

内置 Monaco 编辑器，左侧目录树 + 右侧 Markdown/代码预览，Agent 可直接读写工作区文件。

<table>
  <tr>
    <td width="65%"><img src="documents/img/文件浏览.png" alt="桌面端文件浏览" /></td>
    <td width="35%"><img src="documents/img/mobile_文件浏览.png" alt="移动端文件浏览" /></td>
  </tr>
  <tr>
    <td align="center">桌面端</td>
    <td align="center">移动端</td>
  </tr>
</table>

### 缓存与 Token 监控

KV Cache 命中率、Token 用量、上下文压缩事件按会话/模型统计，便于评估上下文工程效果。

<table>
  <tr>
    <td width="65%"><img src="documents/img/缓存监控.png" alt="桌面端缓存监控" /></td>
    <td width="35%"><img src="documents/img/mobile_缓存监控.png" alt="移动端缓存监控" /></td>
  </tr>
  <tr>
    <td align="center">桌面端 · 命中率 / 用量 / 压缩事件</td>
    <td align="center">移动端</td>
  </tr>
</table>

### 设置中心

**常规**：Agent 记忆、调用图指令、Web 搜索等工作区级开关。

<p align="center">
  <img src="documents/img/设置1.png" alt="通用设置" width="640">
</p>

**模型**：内置 20+ 国内提供商预设（阿里云百炼、小米 MiMo、智谱、阶跃星辰等），支持 OpenAI 兼容自定义端点，保存后热重载。

<table>
  <tr>
    <td width="50%"><img src="documents/img/模型提供商.png" alt="模型提供商列表" /></td>
    <td width="50%"><img src="documents/img/模型设置.png" alt="添加模型提供商" /></td>
  </tr>
  <tr>
    <td align="center">内置提供商预设</td>
    <td align="center">端点与 API Key 配置</td>
  </tr>
</table>

**MCP**：与 Cursor 格式兼容，支持本地 stdio 与远程 SSE/HTTP，可视化编辑器 + 高级 JSON 双模式。

<p align="center">
  <img src="documents/img/mcp工具.png" alt="MCP 工具配置" width="640">
</p>

---

## 功能概览

| 能力 | 说明 |
| ---- | ---- |
| **Chat / Agent 双模式** | 首页与会话页提供 **Chat**（只读，可查阅代码库）与 **Agent**（完整读写与执行）。Plan 不在编码会话中切换，见 [Plan 模式](#plan-模式)。 |
| **Plan 模式** | 在 Web UI 的 **Plan** 页面（`/plan`）描述目标、锁定计划、拆解任务并在 Kanban 上并行执行，自动提交并创建 PR。 |
| **上下文工程** | 通过知识图谱 `memory_recall`、调用图按需召回、历史压缩等方式，长会话显著降低 Token 消耗并提高相关性。 |
| **Agent 记忆** | Topic → Concept → Fact 层级 + 向量检索，跨会话保留代码库与决策上下文（在 **设置 → 通用 → Agent 记忆** 中启用）。 |
| **调用图 / 文档索引** | 函数级调用关系可视化；支持 30+ 种源码/文本文件的语义索引与 `codebase_map` 导航。 |
| **缓存监控** | KV Cache 命中率、Token 用量、压缩事件可视化，按会话与模型维度统计。 |
| **多模型提供商** | Anthropic、OpenAI、OpenRouter、Ollama 及国内主流云厂商；支持自定义 OpenAI 兼容接口，保存后**热重载**无需重启。 |
| **MCP 工具扩展** | 通过 `mcp.json` 接入外部 MCP 服务器，工具名格式 `服务器ID__工具名`。 |
| **权限与安全** | 写文件、编辑、bash 等危险操作需逐项批准；只读工具自动放行。 |
| **单二进制自托管** | 内嵌 SolidJS 前端，无额外服务端依赖；支持 Docker 与 `--data-dir` 统一数据目录。 |

---

## 系统要求

| 项目 | 要求 |
| ---- | ---- |
| 操作系统 | macOS、Linux、Windows |
| Go | 1.26+（仅源码构建时需要） |
| Node.js | 18+（仅源码构建前端时需要） |
| Git | 2.34+（Plan 模式 worktree 需要） |
| 内存 | 建议 ≥ 512 MB 可用 |
| LLM | 至少一个 API Key，或本地 Ollama |

---

## 命令行参数

### 命令总览

```
minicode [命令] [选项]
```

| 命令 | 说明 |
| ---- | ---- |
| `serve` | 启动 MiniCode 服务（默认命令） |

Agent 对话、Plan 规划、任务执行、文档索引等能力均在 **Web UI** 中操作；CLI 仅用于启动服务。

### `minicode serve`

启动 Web 服务，默认监听 `http://localhost:9595`。

```bash
minicode serve [选项]
```

| 选项 | 短写 | 默认值 | 说明 |
| ---- | ---- | ------ | ---- |
| `--port` | `-p` | `9595` | TCP 监听端口（`--type=sockets` 时忽略） |
| `--data-dir` | `-D` | `<cwd>/.global` | 全局配置与缓存目录（见 [全局数据目录](#全局数据目录-data-dir)） |
| `--type` | | `tcp` | 监听方式：`tcp`（HTTP）或 `sockets`（Unix 域套接字） |
| `--socket-path` | | `<data-dir>/minicode.sock` | Unix 套接字文件路径（仅 `--type=sockets` 时生效） |
| `--webroot` | | 空 | Web UI 与 API 的路径前缀（如 `/app/minicode`） |

```bash
# 默认启动（TCP，http://localhost:9595）
minicode serve

# 指定端口
minicode serve -p 3000

# 指定数据目录
minicode serve --data-dir /var/lib/minicode

# Unix 域套接字模式
minicode serve --type sockets
minicode serve --type sockets --socket-path /run/minicode/minicode.sock

# 挂载到路径前缀（适合反向代理子路径部署）
minicode serve --webroot /app/minicode
```

文档索引请在 Web UI 的**文档索引**页面触发；Agent 可通过 `codebase_map` 按主题浏览项目结构。

### 环境变量

#### LLM 提供商

| 变量 | 提供商 |
| ---- | ------ |
| `ANTHROPIC_API_KEY` | Anthropic（Claude） |
| `OPENAI_API_KEY` | OpenAI（GPT） |
| `OPENAI_BASE_URL` | OpenAI 自定义兼容接口地址 |
| `OPENROUTER_API_KEY` | OpenRouter |
| `OLLAMA_BASE_URL` | Ollama（如 `http://localhost:11434/v1`） |
| `OLLAMA_API_KEY` | Ollama API Key（可选） |
| `OPENAI_COMPAT_API_KEY` | 自定义 OpenAI 兼容接口 Key（见 Web UI **设置 → 模型**） |
| `OPENAI_COMPAT_BASE_URL` | 自定义 OpenAI 兼容接口 Base URL |

#### 数据目录

| 变量 | 说明 |
| ---- | ---- |
| `MINICODE_DATA_DIR` | 统一数据目录（等同于 `--data-dir`） |
| `MINICODE_SOCKET_PATH` | Unix 套接字文件路径（等同于 `--socket-path`，仅 socket 模式） |
| `MINICODE_EMBED_MODEL_DIR` | 覆盖内置 Embedding 模型缓存目录 |
| `MINICODE_EMBED_MODEL` | 覆盖远程 Embedding 模型名称（如 `text-embedding-3-large`） |
| `MINICODE_MEMORY_DB_PATH` | 覆盖 Agent 记忆数据库路径（默认 `~/.minicode/memory.db`） |

#### 日志

| 变量 | 说明 |
| ---- | ---- |
| `MINICODE_LOG_LEVEL` | `debug` / `info` / `warn` / `error` |
| `MINICODE_LOG_FORMAT` | `json` 或文本 |

#### 网页搜索（可选）

启用后 Agent 可调用 `web_search`（**每条用户消息限 1 次**）：检索最多 20 条结果、按相关度排序，并自动抓取最相关的 3 个页面。

| 变量 | 说明 |
| ---- | ---- |
| `MINICODE_SEARCH_ENABLED` | `true` 启用 Web 搜索（等同 **设置 → 通用 → 启用 Web 搜索**） |

在 **设置 → 通用** 中打开开关即可。详见 [网页搜索配置](#网页搜索可选)。

#### MCP（Model Context Protocol，可选）

通过 MCP 协议接入外部工具服务器，扩展 Agent 工具集。配置格式与 **Cursor** 相同，支持**多台 MCP 服务器**；推荐在 Web **设置 → MCP** 中编辑，或直接编辑 JSON 文件。

| 配置文件 | 说明 |
| -------- | ---- |
| `<global-root>/mcp.json` | 全局 MCP 配置（默认 `<cwd>/.global/mcp.json`） |

Agent 中工具名格式为 `服务器ID__工具名`（如 `bing-search__bing_search`）。

> 内置 **Web 搜索**（`web_search`，每条用户消息 1 次）由 **设置 → 通用** 单独管理，与下方 MCP 示例无关。

跨平台推荐配置（Linux / macOS / Windows 通用）：

```json
{
  "mcpServers": {
    "bing-search": {
      "command": "npx",
      "args": ["-y", "bing-cn-mcp"]
    },
    "remote-api": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}
```

也可在 **设置 → MCP** 中使用可视化编辑器配置本地（stdio）与远程（SSE/HTTP）服务器，无需手写 JSON。

Windows 上若 `npx` 不在 PATH 中，可使用 `cmd /c` 包装（与 Cursor 一致）：

```json
{
  "mcpServers": {
    "bing-search": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "bing-cn-mcp"]
    }
  }
}
```

首次连接 `npx` 包时可能需要下载依赖（最多等待 90s）。若报 `transport closed`，请在终端先执行一次 `npx -y bing-cn-mcp` 完成缓存，并确认 Node.js 在启动 `minicode serve` 时的 PATH 中可用。MCP 在首次使用时按需连接，不会在启动时阻塞服务。

以下为**旧版环境变量**兜底（无已启用的 `mcp.json` 服务器时生效）：

| 变量 | 说明 |
| ---- | ---- |
| `MINICODE_MCP_ENABLED` | `true` 启用 MCP 工具桥接 |
| `MINICODE_MCP_COMMAND` | MCP 服务器命令（默认 `ogden`） |
| `MINICODE_MCP_ARGS` | MCP 服务器参数，空格分隔（默认 `mcp`） |
| `MINICODE_MCP_ENV` | 额外环境变量，空格分隔（如 `KEY1=val1 KEY2=val2`） |

---

## 配置

MiniCode 从环境变量与 Web **设置 → 模型** 读取提供商配置；Key 保存后立即生效（热重载）。

### Agent 记忆

在 **设置 → 通用 → Agent 记忆** 中启用，并选择 Embedding 提供商（内置 / OpenAI / OpenRouter / Ollama 等）。内置模型首次使用时约下载 90MB 权重。

切换 Embedding 提供商或模型后会自动重建向量索引。

### 网页搜索（可选）

在 **设置 → 通用 → 启用 Web 搜索** 中打开开关，或设置环境变量 `MINICODE_SEARCH_ENABLED=true`。

在 **设置 → 通用** 打开 Web 搜索后，Agent 可调用 `web_search`（**每条用户消息 1 次**）。一次调用会：并发检索百度/搜狗/Bing，合并去重后按相关度排序返回 **20 条**结果，并并行抓取 **最相关的 3 个**页面正文。

页面抓取优先使用 [Lightpanda](https://lightpanda.io/)（支持 JS 渲染，无需 Chromium）。若系统未安装，MiniCode 会**自动下载**到 data-dir（`lightpanda/` 目录，约 60–130 MB）；下载失败或未支持的平台（如 Windows 原生）则**降级为 HTTP** 抓取静态 HTML。

| 变量 | 说明 |
| ---- | ---- |
| `MINICODE_LIGHTPANDA_PATH` | 指定已安装的 Lightpanda 可执行文件（优先于自动下载） |
| `MINICODE_LIGHTPANDA_DIR` | 覆盖 Lightpanda 缓存目录（默认 `<data-dir>/lightpanda`） |
| `MINICODE_LIGHTPANDA_WAIT_MS` | 页面加载等待毫秒数（默认 `2000`） |

---

## 使用方式

### Chat 与 Agent

在首页或 `/session/:id` 的输入框旁切换模式：

- **Chat** — 对话问答，可读代码库（read / glob / grep / codebase_map 等），不可写入或执行 shell。
- **Agent** — 完整编码 Agent，可读写文件、运行命令、调用全部工具。

### Plan 模式

1. 打开 **Plan**（`/plan`），新建计划并描述目标。
2. 与规划 Agent 讨论方案，满意后**锁定计划**。
3. 系统自动拆解为带依赖与工作量（S/M/L/XL）的任务，展示在 Kanban 看板。
4. 并行或按依赖执行任务；完成后自动 commit、push 并创建 GitHub PR。
5. 已归档计划保存在 `<项目>/.minicode/archives/`。

并行任务遵循**文件归属**规则：不并行修改同一文件，链式任务共享分支以减少冲突。

---

## 全局数据目录（`--data-dir`）

全局配置与共享缓存默认保存在**启动目录下的 `.global/`**（可用 `--data-dir` 或 `MINICODE_DATA_DIR` 覆盖）。**项目数据**（会话、Call Graph、笔记、Agent 记忆等）始终保存在各知识库的 `<项目>/.minicode/` 下。

### 用法

```bash
# 默认：全局数据在 ./.global/，项目数据在当前目录/.minicode/
minicode serve

# 自定义全局目录
minicode serve --data-dir /var/lib/minicode/global

export MINICODE_DATA_DIR=/var/lib/minicode/global
minicode serve
```

### 目录结构

**全局（`<cwd>/.global/` 或 `--data-dir`）**

```
.global/
  config.db         # 全局配置（Provider API Key、模型开关、Memory/Search 设置等）
  mcp.json          # MCP 服务器配置（全局）
  embed-model/      # 本地 Embedding 模型缓存
  lightpanda/       # Lightpanda 浏览器缓存
  minicode.sock     # Unix socket 模式下的套接字
```

**按项目（`<workspace>/.minicode/`）**

```
<workspace>/.minicode/
  minicode.db       # 会话、Call Graph、Doc Index、Notes、Plan、Task
  memory.db           # Agent 记忆知识图谱
  notes/              # 笔记 Markdown
  archives/           # 已归档计划
  worktrees/          # Plan 模式 Git worktree
  chain-merges/       # 链式合并临时 worktree
```

单进程可通过 `?workspace=` 切换多个知识库；全局设置与 MCP 对所有 workspace 生效，业务数据各自隔离。

### Embedding 配置

启动时**不会**预下载 ONNX 模型。在 **设置 → 通用 → Agent 记忆** 中选择 Embedding 提供商：

- 远程提供商需在 **设置 → 模型** 中配置 API Key（与聊天模型共用）
- 内置模型（bge-small-zh-v1.5）仅在首次使用时下载约 90MB 权重
- 可通过 `MINICODE_EMBED_MODEL_DIR` 环境变量覆盖内置模型缓存目录

---

## 编译构建

依赖：**Node.js 18+**（前端）、**Go 1.26+**（后端）。

### 一键打包（全部平台）

```bash
# Linux / macOS / Git Bash
./build.sh

# Windows（CMD / PowerShell）
build.bat
```

产物输出到 `dist/`（6 个平台，见下表）。32 位 Linux（`arm`/`386`）因 hugot 嵌入模型依赖暂不支持交叉编译。

### 本机单平台

```bash
cd web && npm install && npm run build && cd ..
go build -o minicode .
```

Windows：

```powershell
cd web; npm install; npm run build; cd ..
go build -o minicode.exe .
```

### 手动交叉编译

先构建前端，再逐平台执行（`CGO_ENABLED=0`）：

```bash
cd web && npm install && npm run build && cd ..
mkdir -p dist

GOOS=linux   GOARCH=amd64 CGO_ENABLED=0 go build -o dist/minicode-linux-amd64 .
GOOS=linux   GOARCH=arm64 CGO_ENABLED=0 go build -o dist/minicode-linux-arm64 .
GOOS=darwin  GOARCH=amd64 CGO_ENABLED=0 go build -o dist/minicode-darwin-amd64 .
GOOS=darwin  GOARCH=arm64 CGO_ENABLED=0 go build -o dist/minicode-darwin-arm64 .
GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -o dist/minicode-windows-amd64.exe .
GOOS=windows GOARCH=arm64 CGO_ENABLED=0 go build -o dist/minicode-windows-arm64.exe .
```

| GOOS | GOARCH | 输出文件 |
| ---- | ------ | -------- |
| linux | amd64 | `dist/minicode-linux-amd64` |
| linux | arm64 | `dist/minicode-linux-arm64` |
| darwin | amd64 | `dist/minicode-darwin-amd64` |
| darwin | arm64 | `dist/minicode-darwin-arm64` |
| windows | amd64 | `dist/minicode-windows-amd64.exe` |
| windows | arm64 | `dist/minicode-windows-arm64.exe` |

> 前端 `web/dist` 必须存在，否则 Go 无法嵌入 UI。交叉编译无需 C 工具链。

---

## 开发调试

### 后端开发

```bash
go run . serve --port 9595
```

### 前端开发

```bash
cd web && npm run dev
```

前端开发服务器启动后，需要后端同时运行。前端默认代理 API 请求到 `localhost:9595`。

### 运行测试

```bash
go test ./...
```

### 调试技巧

```bash
# 开启 debug 日志
MINICODE_LOG_LEVEL=debug minicode serve

# JSON 格式日志（便于日志聚合工具解析）
MINICODE_LOG_FORMAT=json MINICODE_LOG_LEVEL=debug minicode serve

# 使用 .env 文件（自动加载）
echo "ANTHROPIC_API_KEY=sk-xxx" > .env
minicode serve
```

### 清理构建产物

```bash
rm -f minicode minicode.exe
rm -rf web/dist dist
```

---

## 架构概览

```
┌─────────────┐     REST + SSE      ┌──────────────┐
│  Web UI     │ ◄────────────────► │  Go Server   │
│  (SolidJS)  │                    │  (port 9595) │
└─────────────┘                    └──────┬───────┘
                                          │
                    ┌─────────────────────┼─────────────────────┐
                    ▼                     ▼                     ▼
            ┌─────────────┐    ┌─────────────┐    ┌──────────────┐
            │ Agent Loop  │    │  SQLite DB  │    │ LLM Provider │
            └─────────────┘    └─────────────┘    └──────────────┘
                    │
        ┌───────────┼───────────┐
        ▼           ▼           ▼
  Knowledge    Call Graph   Search Bridge
    Graph      (代码关系)    (网页搜索)
```

| 组件 | 职责 |
| ---- | ---- |
| Agent Loop | 流式对话 + 工具执行（bash、read、write、edit、memory_recall、callgraph、web_search 等） |
| Session Store | 会话、Plan、任务、权限等 SQLite 持久化 |
| Git Worktrees | Plan 任务隔离分支，支持并行与自动 PR |
| Knowledge Graph | Agent 记忆与向量检索 |
| Call Graph | 函数级调用关系 |
| Search | 内置 web_search（每条用户消息 1 次，20 条 + Top3 页面） |

---

## 富文本输出

Agent 可在对话中渲染：

| 格式 | 用途 |
| ---- | ---- |
| Mermaid | 流程图、架构图、时序图 |
| LaTeX | 数学公式 |
| Plotly | 交互图表 |
| HTML/CSS/JS | 沙箱 iframe 内的交互内容 |

---

## 相关文档

更详细的设计与实现说明见 [`documents/`](documents/) 目录，例如：

- [Agent / Plan 优化](documents/AgentPlan_Optimization_20260708.md)
- [Token 优化策略](documents/TokenOptimization_20260708.md)
- [KV Cache 与上下文压缩](documents/ContextCompaction_KVCache_20260703.md)
- [缓存监控指南](documents/Cache_Monitoring_Guide.md)

---

## 许可证

[MIT License](LICENSE)