# 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 等模型，可在设置中随时切换。

---

## 在线演示

访问地址：**http://localhost:9595**

启动服务后，在浏览器中打开上述地址即可使用 MiniCode。

---

## 本地开发

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

## 快速开始

```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
```

首次启动若无已配置的模型提供商，会进入**引导向导**完成 API Key 配置与校验。

---

## 功能概览


| 能力                   | 说明                                                                             |
| -------------------- | ------------------------------------------------------------------------------ |
| **Chat / Agent 双模式** | 首页与会话页提供 **Chat**（只读，可查阅代码库）与 **Agent**（完整读写与执行）。Plan 不在编码会话中切换，见下方 Plan 模式。   |
| **Plan 模式**          | 在 Web UI 的 **Plan** 页面（`/plan`）描述目标、锁定计划、拆解任务并在 Kanban 上并行执行，自动提交并创建 PR。       |
| **上下文工程**            | 通过知识图谱 `memory_recall`、调用图按需召回、历史压缩等方式，长会话显著降低 Token 消耗并提高相关性。                 |
| **Agent 记忆**         | Topic → Concept → Fact 层级 + 向量检索，跨会话保留代码库与决策上下文（在 **设置 → 通用 → Agent 记忆** 中启用）。 |
| **调用图 / 文档索引**       | 函数级调用关系可视化；支持 30+ 种源码/文本文件的语义索引与 `codebase_map` 导航。                         |
| **多模型提供商**           | Anthropic、OpenAI、OpenRouter、Ollama；支持自定义 OpenAI 兼容接口，保存后**热重载**无需重启。           |
| **权限与安全**            | 写文件、编辑、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 服务（默认命令）               |
| `index` | 扫描工作区源码/文本并建立语义索引               |
| `run`   | 非交互式一次性执行 Agent prompt（输出到 stdout） |




### `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 域套接字模式（不监听 TCP 端口）
# 默认套接字路径：<global-root>/minicode.sock（即 ./.global/minicode.sock）
minicode serve --type sockets

# 指定套接字文件路径
minicode serve --type sockets --socket-path /run/minicode/minicode.sock
# 或通过环境变量
export MINICODE_SOCKET_PATH=/run/minicode/minicode.sock
minicode serve --type sockets

# 挂载到路径前缀（适合反向代理子路径部署）
# 访问地址示例：http://localhost:9595/app/minicode
minicode serve --webroot /app/minicode
```



### `minicode run`

非交互式执行单次 Agent prompt，结果输出到 stdout，适用于脚本和 CI 管道。

```bash
minicode run [选项] [prompt]
```


| 选项                | 短写   | 默认值     | 说明                              |
| ----------------- | ---- | ------- | ------------------------------- |
| `--agent`         | `-a` | `build` | Agent 类型：`build` 或 `plan`       |
| `--output-format` | `-o` | `text`  | 输出格式：`text` 或 `json`            |
| `--max-turns`     |      | `100`   | Agent 循环最大迭代次数                  |
| `--model`         |      | 空       | 模型 ID 覆盖（如 `claude-sonnet-4-5`） |
| `--data-dir`      | `-D` | 空       | 统一数据目录                          |


```bash
# 基本用法
minicode run "解释这个仓库的目录结构"

# 指定模型和输出格式
minicode run --model claude-sonnet-4-5 --output-format json "列出所有 API 路由"

# 通过管道输入
echo "审查最近的改动" | minicode run
git diff | minicode run --agent plan "审查这些变更"
```



### `minicode index`

扫描工作区源码与文本文件，使用 LLM 建立语义索引。

```bash
minicode index [选项]
```


| 选项           | 说明                     |
| ------------ | ---------------------- |
| `--model`    | 指定索引使用的模型（默认使用提供商默认模型） |
| `--data-dir` | 统一数据目录                 |


```bash
# 使用默认模型索引
minicode index

# 指定模型
minicode index --model gpt-4o-mini
```

索引结果可在 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 示例无关。

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

Windows 上若命令不在 PATH 中，请使用完整路径（如 `C:\\tools\\ogden.exe`），或通过 `npx -y @package/name` 运行 npm 包。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`） |


```bash
# 环境变量方式（单服务器，兼容旧配置）
MINICODE_MCP_ENABLED=true minicode serve

MINICODE_MCP_ENABLED=true MINICODE_MCP_COMMAND=my-tool MINICODE_MCP_ARGS="serve --port 8080" minicode serve
```

---



## 配置

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

# 其他子命令同样支持
minicode run "explain this repo"
minicode index
```

### 目录结构

**全局（`<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 内的交互内容 |


---



## 许可证

[MIT License](LICENSE)