Codeaha｜码悟

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

本地优先、国产大模型友好的 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 调试门槛，面向国内开发者环境。

技术栈

能力

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+

安装与启动

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 体验交互流程（不发真实请求）。

命令行

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