# codeaha

**Repository Path**: halberd/codeaha

## Basic Information

- **Project Name**: codeaha
- **Description**: Codeaha（码悟）：本地优先、国产大模型友好的 AI 编程 Agent。 基于 GoFrame + Eino + mark3labs/mcp-go + GF sqlite 驱动（glebarez/go-sqlite，纯 Go 无 CGO）构建。
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-30
- **Last Updated**: 2026-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Codeaha｜码悟

> Code + Aha，看见代码的顿悟时刻

![logo](./docs/brand/png/codeaha-app-icon-64.png)

本地优先、国产大模型友好的 AI 编程 Agent。
基于 GoFrame + Eino + mark3labs/mcp-go + GF sqlite 驱动（glebarez/go-sqlite，纯 Go 无 CGO）构建。

## 核心特性

- **本地优先** — 会话、消息与代码变更全部落盘本地 SQLite，代码数据不出本机
- **Agent 推理** — 基于 Eino Graph 实现 ReAct 自主规划，拆解复杂编码任务；支持 `plan` / `build` 双模式（`plan` 不暴露写侧工具）
- **内置工具集** — `read` / `write` / `edit` / `glob` / `grep` / `bash` / `list` / `webfetch` / `websearch` / `todowrite` / `todoread` / `memoryread` / `memorywrite` / `question` / `skill`，读写修改工程、执行调试
- **工具权限管控** — 工作目录白名单、Shell 命令黑名单、执行超时、输出大小限制；敏感操作弹确认卡，可"本会话总是允许"
- **MCP 驱动** — 对接 `stdio` / `http` / `sse` 三种传输的 MCP 服务，转换为 Eino Tool 与内置工具同权同链
- **Web 可视化** — 直观查看 Agent 思考链路、MCP 调用记录、代码 Diff 变更预览与确认
- **原生国产模型支持** — DeepSeek、Kimi、豆包（ark）、通义（qwen），同时兼容 Ollama 等 OpenAI 兼容端点
- **IDE 兼容** — HTTP 接口可供 VSCode 等插件调用
- **技能系统** — 磁盘 `SKILL.md` 发现（实例级 + 项目级），前端面板可视化调用
- **模块化架构** — 分层解耦，适合二次开发与学习 Go + MCP + Agent

不同于 TUI 优先的同类项目，降低 Agent 调试门槛，面向国内开发者环境。

## 技术栈

| 层级 | 组件 | 说明 |
|------|------|------|
| Web/API | GoFrame | HTTP 接口、Web 页面、配置、请求转发，Agent 逻辑禁止耦合进 Controller |
| Agent 编排 | Eino (CloudWeGo) | ReAct、Graph 图编排 |
| MCP 协议 | mark3labs/mcp-go | 适配器在 `internal/mcp`（自研，Eino 无原生 MCP 支持；MCP 工具实现本仓 `tool.Tool` 接口，与内置工具同权同链） |
| 数据库 | GF gdb + glebarez/go-sqlite | `github.com/gogf/gf/contrib/drivers/sqlite/v2`，纯 Go 无 CGO，会话持久化 |
| 上下文 | Eino + 自研压缩 | 基于 token 估算的上下文窗口感知与自动压缩 |

## 能力

1. 读取本地工程源码，理解项目结构（文件工具）
2. Agent 自主规划任务：多文件修改、Bug 修复、单元测试编写
3. Web 页面可视化：Agent 思考链路、MCP 入参出参、代码 Diff 预览确认后写入磁盘
4. MCP 工具调用：文件、Git、Shell 编译测试调试
5. 原生适配 DeepSeek / Kimi / 豆包 / 通义 / Ollama，OpenAI 兼容接口
6. HTTP 接口对外提供能力，供 IDE 插件调用
7. SQLite 持久会话历史，关闭可恢复会话
8. 模块化，支持二次开发学习

## 快速开始

### 环境要求

- Go 1.25+

### 安装与启动

```bash
git clone https://gitee.com/LeapSunrise/codeaha.git
cd codeaha
go mod tidy
make build              # 走 gf build 打包，产物在 bin/v1.0.0/codeaha(.exe)
# （也可直接 go build . 从源码编译，资源走磁盘读取；make build 仅多一步资源打包）

# 启动 Web 服务（或直接 make run：构建 + 启动 + 健康检查一条龙）
./bin/v1.0.0/codeaha serve
```

启动后访问 `http://localhost:28084` 进入 Web 面板。

### 配置模型

Codeaha 的模型凭据**只存本地数据库**（`setting` 表），不写配置文件、不落日志。

- **Web 面板（推荐）**：进入 设置 / 模型配置，新增档案（填写 `base_url` / `api_key` / `model` / `max_tokens`），支持 DeepSeek、Kimi、豆包（ark）、通义（qwen）及 Ollama 等 OpenAI 兼容端点，并设为默认。
- **命令行**：`codeaha config profile list` 查看已配置档案；`codeaha config profile default <id|名称>` 设默认档案。

> 未配置模型前，可先开 `codeaha config mock on` 体验交互流程（不发真实请求）。

## 命令行

```bash
codeaha                           # 启动 Web 服务（默认命令）
codeaha serve                     # 启动 Web 服务
codeaha chat -p "你的问题"         # one-shot 提问；-s 复用会话、-C 指定工作目录、--mode plan|build、--skill 激活技能
codeaha mcp list                  # 查看已加载 MCP 集成列表
codeaha mcp add --key <id> --transport stdio --command npx --arg -y --arg <server>
codeaha skill list                # 列出当前可见技能（实例级 + 项目级）
codeaha config profile default <id>   # 设置默认模型档案
codeaha config mock on|off            # 开关 mock 模式
codeaha config iterations <n>         # 设置单轮最大迭代数
```

## 项目结构

采用 GoFrame 推荐的标准目录结构，核心包如下：

```
codeaha/
├── main.go                       # 程序入口
├── go.mod / go.sum
├── Makefile                      # 构建、运行、测试命令
├── api/                          # API 路由/协议声明（chat/diff/filesystem/llm/mcp/memory/project/session/skill/tool）
├── hack/                         # 构建工具配置（config.yaml 等）
├── internal/
│   ├── cmd/                      # CLI 命令（serve / chat / mcp / skill / tool / config）
│   ├── consts/                   # 常量：版本、表名、part 类型、事件类型、setting key
│   ├── controller/               # GoFrame 层：路由、handler、SSE 流式输出、参数校验
│   ├── service/                  # 业务编排层：agent 调用、mcp 桥接、dao 组合、上下文重建
│   ├── agent/                    # Eino 核心：模型解析、ReAct Agent、上下文压缩、Diff
│   ├── tool/                     # 内置工具 + 权限系统（零依赖叶子包）
│   ├── mcp/                      # MCP 桥接层：stdio/http/sse 适配、schema 转换、超时/断线
│   ├── skill/                    # 技能发现（磁盘 SKILL.md 扫描）
│   ├── dao/                      # 数据访问层：GF gdb + sqlite，会话/消息/part 等 CRUD
│   ├── model/                    # 数据模型（do / entity）
│   └── packed/                   # 资源打包入口
├── manifest/                     # 配置、部署、i18n 等资源
├── resource/                     # 静态资源（HTML/CSS/JS 模板与图片）
└── utility/                      # 公共工具库
```

## 注意事项

- 本项目**仅用于学习与研究**，不提供任何明示或暗示的担保。
- 使用本项目所产生的**商业风险**（包括但不限于数据丢失、服务中断、合规问题）均由使用者自行承担。
- 调用大模型会产生 **Token 费用**，相关费用由使用者自行承担；请合理配置模型与额度，避免产生不必要的开销。

## License

MIT