# go-aicode-sdk

**Repository Path**: netbycom/go-aicode-sdk

## Basic Information

- **Project Name**: go-aicode-sdk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-17
- **Last Updated**: 2026-05-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# aicode-sdk

![aicode-sdk logo](assets/icon-128.png)

**aicode-sdk** 是一个通用 AI Agent SDK 框架，从 `go-aicode-helper` CLI agent 核心逻辑中提取重构而来。它提供了构建 AI 编码助手所需的基础设施：LLM 调用、工具系统、会话管理、记忆系统、文件操作、通知、任务跟踪等，开箱即用且高度可定制。

---

## 架构概览

```
┌──────────────────────────────────────────────────────────┐
│                    cmd/aicode-agent-demo                  │  ← 演示应用
├──────────────────────────────────────────────────────────┤
│                         cli                              │  ← 交互式 CLI
├──────────────────────────────────────────────────────────┤
│                    sdk (根包 - 组装器)                      │  ← Builder 模式
├──────────┬──────────┬──────────┬──────────┬──────────────┤
│  agent   │  tools   │  llm     │ session  │  config       │
│  (编排层)  │  (工具系统) │ (LLM抽象) │ (会话持久化)│ (配置管理)    │
├──────────┼──────────┼──────────┼──────────┼──────────────┤
│ memory   │  task    │  undo    │  skill   │  workflow     │
│ (记忆系统) │ (任务管理) │ (变更回滚) │ (技能匹配) │ (工作流匹配)   │
├──────────┼──────────┼──────────┼──────────┼──────────────┤
│ mcp      │  notification │ approval  │  events  │             │
│ (MCP注册) │ (通知系统)  │ (审批策略) │ (事件发布) │             │
├──────────┴──────────┴──────────┴──────────┴──────────────┤
│ extractor │ docwriter │ spreadsheet │ svgexport │ diffpreview │
│ (文档提取) │ (文档生成)  │ (表格操作)    │ (SVG导出)   │ (差异预览)    │
└──────────────────────────────────────────────────────────┘
```

### 分层说明

| 层 | 包 | 职责 |
|---|---|---|
| **集成层** | `cmd/aicode-agent-demo` | 演示应用入口 |
| **CLI 接口** | `cli` | 交互式 shell、命令解析、颜色输出 |
| **SDK 组装** | 根包 `sdk.go` | Builder 模式组装所有组件，提供 `With*` 注入方法 |
| **编排层** | `agent` | Agent 主循环、会话恢复、运行时状态、回滚、生命周期事件 |
| **工具层** | `tools` | 工具注册/执行中心，内置 18+ 个工具 |
| **LLM 层** | `llm` | Provider 抽象，内置 OpenAI 兼容传输（支持流式输出） |
| **存储层** | `session`, `memory`, `task`, `undo` | 文件存储实现 |
| **扩展层** | `skill`, `workflow`, `mcp` | 技能/工作流/MCP 注册与匹配 |
| **基础设施** | `config`, `notification`, `approval`, `events` | 配置、通知、审批策略、事件发布 |
| **工具库** | `extractor`, `docwriter`, `spreadsheet`, `svgexport`, `diffpreview` | 底层能力库 |

---

## 快速开始

### 1. 配置 API Key

```powershell
$env:OPENAI_API_KEY="<your-api-key>"
```

或编辑 `.aicode/config.json`：

```json
{
  "api_key": "sk-xxx",
  "base_url": "https://api.openai.com/v1",
  "model": "gpt-4o-mini"
}
```

### 2. 运行演示

```powershell
# 查看帮助
go run ./cmd/aicode-agent-demo help

# 查看配置
go run ./cmd/aicode-agent-demo config

# 列出内置工具
go run ./cmd/aicode-agent-demo tools

# 交互式聊天
go run ./cmd/aicode-agent-demo chat

# 单次执行
go run ./cmd/aicode-agent-demo run "create a hello.txt file"
```

### 3. 交互式命令

| 命令 | 说明 |
|---|---|
| `new` | 新建会话 |
| `clear` | 清除当前会话历史 |
| `undo` / `rollback` | 回滚上一次文件变更 |
| `continue` | 继续未完成的任务 |
| `/model [name]` | 查看或切换模型 |
| `sessions` | 列出会话 |
| `skills` | 列出技能 |
| `workflows` | 列出工作流 |
| `tools` | 列出工具 |

---

## 服务模式

除了交互式 chat 外，SDK 还提供了三种服务化运行模式：

### serve — HTTP API 服务 + 自动桥接

启动本地 HTTP API 服务，同时自动注册为远程 Aicode Server 的客户端。

```powershell
go run ./cmd/aicode-agent-demo serve
```

当配置了 `bridge_url` 时，会自动通过 WebSocket 连接到远程 Aicode Server：

```
Starting agent service on 127.0.0.1:43210
Auth: disabled
Bridge client: enabled -> ws://127.0.0.1:8280/v1/terminal/local
Bridge client registered: device_id=my-agent device_name=My Agent
```

#### REST API 端点

| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/healthz` | 健康检查 |
| `GET` | `/v1/info` | 服务信息（模型、工具列表等） |
| `GET` | `/v1/sessions` | 列出会话 |
| `GET` | `/v1/sessions/:id` | 查看会话详情 |
| `POST` | `/v1/sessions/:id/undo` | 回滚会话 |
| `POST` | `/v1/sessions/:id/clear` | 清空会话 |
| `GET` | `/v1/runs` | 列出运行记录 |
| `POST` | `/v1/runs` | 创建运行（提交任务） |
| `GET` | `/v1/runs/:id` | 查看运行状态 |
| `GET` | `/v1/runs/:id/events` | SSE 事件流 |

### connect — 远程桥接客户端

仅作为 WebSocket 客户端连接到远程 Aicode Server，不启动本地 HTTP API：

```powershell
go run ./cmd/aicode-agent-demo connect
```

### run — 单次执行

```powershell
go run ./cmd/aicode-agent-demo run "分析当前目录的代码结构"
```

---

## 桥接通信（WebSocket）

### 通信流程

```
Agent (aicode serve/connect)         远程 Aicode Server
  │                                                │
  │── WebSocket 连接 (URL?device_id=&device_name=&token=) ──→│
  │                                                │
  │── register 消息 ──────────────────────────────→│
  │   {type:"register", device_id:"...", data:"..."}│
  │                                                │
  │← 等待 input 消息 ───────────────────────────────│
  │   {type:"input", session:"...", data:"任务\n"}  │
  │                                                │
  │── output_delta 消息 ──────────────────────────→│  流式增量
  │   {type:"output_delta", session:"...",          │
  │    data:"base64...", encoding:"base64"}          │
  │                                                │
  │── output 消息（最终结果）───────────────────────→│  完整输出
  │                                                │
  │── history 消息（首次连接时）───────────────────→│  历史对话
  │   {type:"history", session:"...",               │
  │    messages:[{role,content},...]}               │
```

### 消息类型

| 类型 | 方向 | 说明 |
|---|---|---|
| `register` | Agent → Server | 注册设备信息 |
| `input` | Server → Agent | 用户提交的任务 |
| `output_delta` | Agent → Server | AI 回复流式增量 |
| `output` | Agent → Server | 最终完整输出 |
| `history` | Agent → Server | 已持久化的会话历史 |
| `heartbeat` | 双向 | 心跳保活 |

### 前端集成

前端通过 WebSocket 连接到 `/v1/terminal/ws`，选择在线设备后即可收发消息。

前端收到 `output_delta` 时追加到当前 AI 回复消息实现流式效果，收到 `output` 时标记回复完成。连接时通过 `history` 消息加载历史对话。

---

## 配置

### 加载顺序

1. **默认值**
2. **JSON 配置文件** — `~/.aicode/config.json`（全局）→ `./.aicode/config.json`（项目）
3. **`AICODE_CONFIG` 环境变量指定配置文件**
4. **环境变量覆盖**

### 完整配置项

| JSON 字段 | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
| `api_key` | `OPENAI_API_KEY` / `AICODE_API_KEY` | `""` | API 密钥 |
| `base_url` | `AICODE_BASE_URL` | `https://api.openai.com/v1` | API 地址 |
| `model` | `AICODE_MODEL` | `gpt-4o-mini` | 模型名称 |
| `api_mode` | `AICODE_API_MODE` | `openai` | API 模式（`openai` / `legacy`） |
| `workspace` | `AICODE_WORKSPACE` | 当前目录 | 工作目录 |
| `data_dir` | `AICODE_DATA_DIR` | `~/.aicode-sdk` | 数据存储目录 |
| `skills_dir` | `AICODE_SKILLS_DIR` | `.aicode/skills` | 技能目录 |
| `workflows_dir` | `AICODE_WORKFLOWS_DIR` | `.aicode/workflows` | 工作流目录 |
| `mcp_config` | `AICODE_MCP_CONFIG` | `.aicode/mcp.json` | MCP 配置路径 |
| `session_pointer` | — | `.aicode-session` | 会话指针文件名 |
| `system_prompt` | `AICODE_SYSTEM_PROMPT` | 内置默认提示词 | 系统提示词 |
| `language` | `AICODE_LANG` / `AICODE_LANGUAGE` | `en` | 界面语言（`en` / `zh-CN`） |
| `no_progress_limit` | `AICODE_NO_PROGRESS_LIMIT` / `AICODE_MAX_TURNS` | 3 | 无进展终止阈值 |
| `tool_output_limit` | `AICODE_TOOL_OUTPUT_LIMIT` | 12000 | 工具输出截断长度 |
| `timeout_seconds` | `AICODE_TIMEOUT_SECONDS` | 90 | HTTP 请求超时 |
| `bridge_url` | `AICODE_BRIDGE_URL` | `""` | 远程桥接服务器地址 |
| `bridge_token` | `AICODE_BRIDGE_TOKEN` | `""` | 桥接认证 Token（JWT 或 API Key） |
| `bridge_client_id` | `AICODE_BRIDGE_CLIENT_ID` | 主机名 | 客户端设备 ID |
| `bridge_client_name` | `AICODE_BRIDGE_CLIENT_NAME` | 同 client_id | 客户端设备名称 |
| `service_listen` | `AICODE_SERVICE_LISTEN` | `127.0.0.1:43210` | HTTP 服务监听地址 |
| `service_token` | `AICODE_SERVICE_TOKEN` | `""` | HTTP 服务认证 Token |

### 完整配置示例

```json
{
  "api_key": "",
  "api_key_env": "OPENAI_API_KEY",
  "base_url": "https://api.openai.com/v1",
  "model": "gpt-4o-mini",
  "api_mode": "openai",
  "workspace": ".",
  "data_dir": ".aicode/data",
  "skills_dir": ".aicode/skills",
  "workflows_dir": ".aicode/workflows",
  "mcp_config": ".aicode/mcp.json",
  "session_pointer": ".aicode-session",
  "language": "zh-CN",
  "system_prompt": "You are a pragmatic AI coding agent...",
  "no_progress_limit": 3,
  "tool_output_limit": 12000,
  "timeout_seconds": 90,
  "bridge_url": "ws://127.0.0.1:8280",
  "bridge_token": "ak_xxx",
  "bridge_client_id": "my-agent-1",
  "bridge_client_name": "本地Agent",
  "service_listen": "127.0.0.1:43210",
  "service_token": ""
}
```

### 使用自定义配置文件

```powershell
$env:AICODE_CONFIG="$PWD\configs\agent.json"
go run ./cmd/aicode-agent-demo config
```

> `no_progress_limit` 不是总轮数上限。它只在 agent 重复执行无进展步骤达到阈值时终止，防止无限循环。

---

## 内置工具（18 个）

| 分类 | 工具 | 说明 |
|---|---|---|
| 📂 **文件** | `read_file` | 读取文本文件，支持行范围截取 |
| | `write_file` | 创建/覆盖文件，自动记录 undo 和 diff 预览 |
| | `patch_file` | 替换文件中匹配的文本片段，自动记录 undo 和 diff 预览 |
| | `delete_file` | 删除文件或空目录 |
| 📁 **目录** | `list_dir` | 列出目录内容，支持递归模式 |
| ⚡ **命令** | `run_command` | 在工作区执行 shell 命令（Windows 用 PowerShell，其余用 sh） |
| 📄 **文档** | `read_document` | 提取 PDF/DOCX/XLSX 等结构化文档的文本 |
| | `write_document` | 创建 DOCX/TXT/MD/HTML 文档 |
| 📊 **表格** | `update_spreadsheet` | 创建或更新 XLSX 表格，支持表头、行替换、追加、单元格更新 |
| 🎨 **SVG** | `export_svg_assets` | 将 SVG 渲染为 PNG 和/或 Windows ICO 文件 |
| 📋 **任务** | `create_task` | 创建任务 |
| | `add_task_item` | 添加子任务项 |
| | `update_task` | 更新子任务状态 |
| | `list_tasks` | 列出所有任务及进度 |
| | `show_task` | 查看任务详情及所有子项 |
| 🧠 **记忆** | `remember_memory` | 存储持久化记忆（带标签） |
| | `search_memory` | 搜索记忆系统中的记录 |
| 🔔 **通知** | `list_notification_channels` | 列出已配置的通知通道 |
| | `send_notification` | 通过指定通道发送通知，支持 dry-run |

---

## SDK 编程使用

```go
package main

import (
    "context"
    "fmt"
    "os"

    sdk "github.com/go-aicode-sdk"
    "github.com/go-aicode-sdk/cli"
)

func main() {
    // 使用默认配置创建 SDK（自动加载 .aicode/config.json + 环境变量）
    sdk, err := sdk.New()
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
    defer sdk.Close()

    app := cli.NewApp(sdk)
    if err := app.Execute(context.Background(), os.Args[1:]); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}
```

### 自定义组装

```go
sdk, err := sdk.New(
    sdk.WithAPIKey("sk-xxx"),
    sdk.WithBaseURL("https://api.openai.com/v1"),
    sdk.WithModel("gpt-4o"),
    sdk.WithWorkspace("/path/to/project"),
    sdk.WithLLMProvider(customProvider),       // 注入自定义 LLM Provider
    sdk.WithTool(customTool),                   // 注入自定义工具
    sdk.WithMemoryStore(customStore),           // 注入自定义记忆存储
    sdk.WithApprovalPolicy(myPolicy),           // 注入自定义审批策略
    sdk.WithSessionStore(mySessionStore),       // 注入自定义会话存储
)
```

---

## 核心模块详解

### agent — AI Agent 编排引擎

`agent.Service` 是核心入口，负责：
- 会话创建/恢复（自动从 `.aicode-session` 指针文件恢复上次会话）
- System Prompt 构建（自动注入匹配的 workflow、skill、MCP 信息）
- 多轮 Tool Calling 循环
- 流式输出（当后端支持 SSE 时）
- 运行时状态持久化（会话消息 + 运行时状态 + undo 状态）
- 无进展检测（`no_progress_limit`）
- 事件发布（task.started, tool.executed, task.completed, task.failed, task.blocked）

### tools — 工具系统

- `Tool` 接口 + `Registry` 线程安全注册中心
- `FuncTool` 便捷适配器
- `Runtime` 延迟注入运行时上下文（workspace、memory、task、approval 等）
- 内置工具全部自动注册 undo/change 追踪

### memory — 记忆系统

- `Store` 接口（支持 `Add` / `Search` / `List` / `ReplaceAll` / `Delete`）
- `FileStore`：JSON 文件存储（紧凑格式）
- `CompactingStore`：**AI 自动压缩**装饰器
  - 条目超过 500 条时触发
  - 调用 LLM 分析哪些条目重要、可合并、可丢弃
  - 支持同步/异步两种压缩模式

```go
// 启用 AI 压缩记忆存储
cs := memory.NewCompactingStore(
    memory.NewFileStore("memory.json"),
    memory.NewAICompactor(llmProvider, "deepseek-chat"),
)
cs.MaxEntries = 500
```

### llm — LLM 抽象层

- `Provider` 接口：`Chat(ctx, Request) → Response`
- 内置 `OpenAICompatibleProvider`：支持任意 OpenAI 兼容 API
- 内置 `LegacyAPIProvider`：兼容旧版 Aicode 中继 API
- 支持流式输出（通过 `ChatStream` 方法，SSE 格式）

### session — 会话管理

- 三文件存储：`{id}.json`（消息历史）+ `{id}.runtime.json`（运行时状态）+ `{id}.undo.json`（回滚状态）
- 工作区指针文件 `.aicode-session` 记录最新会话 ID
- 支持按 ID 精确加载或前缀模糊匹配

### undo — 文件变更追踪

- `Entry`：文件路径、变更前后内容（支持 base64 编码）
- `Batch`：任务级别的变更批次
- `State`：当前批次 + 历史批次（最多 20 个）
- 支持逐批回滚，自动恢复文件到变更前状态

### skill / workflow — 扩展能力

- 技能匹配：根据用户输入匹配技能定义，自动注入 System Prompt
- 工作流匹配：预定义多步骤工作流，指导 Agent 按步骤执行

### bridgeclient — WebSocket 桥接客户端

- 自动连接到远程 Aicode Server
- 设备注册（device_id / device_name）
- 接收 `input` 任务消息 → 创建 Runner 执行 → 返回 `output_delta` / `output`
- 自动重连（3 秒间隔）
- 首次连接时自动推送会话历史（`history` 消息）

### serviceapi — HTTP API 服务

- RESTful 接口，支持任务提交、会话管理、运行状态查询
- 支持 SSE 事件流实时推送
- Bearer Token 或 X-Aicode-Token 鉴权
- 可配置监听地址和 Token

### approval — 审批策略

| 策略 | 说明 | 适用场景 |
|---|---|---|
| `InteractivePolicy` | 交互式审批，终端提示用户确认 | CLI 交互模式 |
| `StaticPolicy` | 静态策略，自动批准或拒绝 | 服务模式（serve/connect） |
| 自定义策略 | 实现 `Policy` 接口 | 集成到其他系统 |

`serve` 和 `connect` 模式下默认使用 `StaticPolicy` 自动批准所有命令，避免阻塞等待终端输入。

### events — 事件系统

- 发布者/订阅者模式
- 内置事件类型：

| 事件类型 | 触发时机 |
|---|---|
| `task.started` | 任务开始执行 |
| `task.plan` | 生成执行计划 |
| `tool.executed` | 工具执行完成 |
| `task.completed` | 任务成功完成 |
| `task.failed` | 任务失败 |
| `task.blocked` | 任务被阻塞 |
| `task.undo` | 任务回滚 |

---

## 依赖安装

```powershell
# 设置临时 Go 缓存（可选）
$env:GOCACHE="$PWD\.gocache"

# 下载依赖
go mod tidy

# 构建
go build ./...

# 测试
go test ./...
```

---

## 设计原则

- **组件化**：13 个独立包，每个职责单一，依赖单向
- **可替换**：所有核心组件通过接口抽象，可通过 Builder 模式注入自定义实现
- **默认可用**：合理的默认值，零配置即可启动
- **安全回滚**：所有文件变更自动记录，支持按批次撤销
- **智能记忆**：内置 AI 驱动的记忆压缩，自动保留重要信息

---

## 项目路线图

- [x] 核心 SDK 框架
- [x] 18 个内置工具
- [x] AI 记忆压缩
- [x] 文档处理（PDF/DOCX/XLSX）
- [x] SVG 导出
- [x] 流式输出
- [x] 无进展检测
- [x] HTTP API 服务（serve 模式）
- [x] WebSocket 桥接客户端（connect/桥接模式）
- [x] CLI 颜色输出（区分 AI 回复/工具调用/错误）
- [ ] 更多 LLM Provider（Claude, Gemini）
- [ ] 插件系统
- [ ] 向量记忆检索
- [ ] Web UI