# asa

**Repository Path**: ledao/asa

## Basic Information

- **Project Name**: asa
- **Description**: AI 编程工具，辅助代码编写。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-31
- **Last Updated**: 2026-07-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# ASAI

**AI 编程助手** — 通过自然语言完成代码编写、调试、优化等任务

[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
[![Go Version](https://img.shields.io/badge/Go-1.25%2B-00ADD8.svg)](https://go.dev)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)

</div>

## 简介

ASAI（Advanced Software AI）是一款 AI 编程助手，用 Go 编写，支持多种 LLM 供应商（智谱、OpenAI、MiniMax、OpenRouter、LM Studio、百炼等），提供终端 TUI、Web UI 和 Hub 控制台三种界面。支持交互式对话、命令行单次任务、分布式 Agent 协作、技能插件系统等。

## 功能特性

- **交互式编程** — 终端内直接对话式编程
- **命令行模式** — 支持单次任务和管道集成
- **Web 界面** — 浏览器图形化操作，支持多标签页、终端、Git 面板、文件管理
- **Hub 控制台** — 统一管理多个 Web 实例
- **多模型支持** — 智谱、OpenAI、MiniMax、OpenRouter、LM Studio、百炼等
- **分布式 Agent** — 多 Agent 协作，通过 Agent Center 统一调度
- **技能系统** — 可扩展的技能插件
- **MCP 支持** — 兼容 Model Context Protocol
- **安全沙箱** — 命令执行安全策略、文件操作保护、多层审批机制

## 安装

### 从源码构建

```bash
# 克隆项目
git clone https://gitee.com/ledao/asa.git
cd asa

# 构建（需要 Go 1.25+）
go build -ldflags="-s -w" -o asai

# 或者使用构建脚本
./build.sh
```

### 前端构建（可选）

如果需要修改 Web UI，需先构建前端：

```bash
cd internal/web/frontend-vue
npm install
npm run build
```

## 快速开始

### 首次配置

```bash
# 方式一：命令行配置（以智谱为例）
asai provider -p zhipu -k "YOUR_API_KEY" -m glm-4.7 -c 200k

# 方式二：交互式配置
asai
# 进入后输入 /model 按提示设置
```

### 支持的模型供应商

| 供应商 | 命令 | 说明 |
|--------|------|------|
| 智谱 | `-p zhipu` | 国内模型，性价比高 |
| OpenAI | `-p openai` | GPT 系列 |
| MiniMax | `-p minimax` | MoE 模型 |
| OpenRouter | `-p openrouter` | 聚合多种模型 |
| LM Studio | `-p lmstudio` | 本地部署 |
| AIEP | `-p aiep` | 企业级服务 |
| 百炼 | `-p bailian` | 阿里云百炼 |

### 启动方式

```bash
# 交互模式（默认）
asai

# 命令行单次任务
asai "分析这个项目的代码结构"

# 继续上次会话
asai -c "继续刚才的任务"

# 恢复指定会话
asai --resume abc123 "补充一个新功能"

# JSON 输出（适合管道）
asai --output-format json "查询某个文件的内容"
```

## 命令行选项

### 全局选项

| 选项 | 简写 | 说明 | 示例 |
|------|------|------|------|
| `--api-key` | `-k` | 指定 API Key，覆盖配置文件 | `-k "sk-xxx"` |
| `--model` | `-m` | 指定模型，覆盖配置文件 | `-m glm-4.7` |
| `--base-url` | `-b` | 指定 API 地址 | `-b "https://api.example.com"` |
| `--continue` | `-c` | 继续上次会话 | `-c "新任务"` |
| `--resume` | - | 恢复指定会话 | `--resume abc123 "任务"` |
| `--output-format` | - | 输出格式：text/json/stream-json | `--output-format json` |
| `--max-turns` | - | 最大对话轮数，默认 100 | `--max-turns 50` |
| `--version` | `-v` | 显示版本号 | `-v` |

### 子命令

#### provider - 模型供应商配置

```bash
# 配置智谱
asai provider -p zhipu -k "YOUR_KEY" -m glm-4.7 -c 200k

# 配置 OpenAI
asai provider -p openai -k "YOUR_KEY" -m gpt-4o -c 128k

# 配置 MiniMax
asai provider -p minimax -k "YOUR_KEY" -m MiniMax-M2.1 -c 200k

# 配置 OpenRouter（可访问多种模型）
asai provider -p openrouter -k "YOUR_KEY" -m anthropic/claude-3.5-sonnet -c 200k

# 配置本地 LM Studio（无需 API Key）
asai provider -p lmstudio -m "qwen2.5-coder:7b" -c 128k

# 配置阿里云百炼
asai provider -p bailian -k "YOUR_KEY" -m qwen3.5-plus -c 200k

# 清理无效的 API Key
asai provider --clean
```

参数说明：
- `-p, --provider`: 供应商名称
- `-k, --api-key`: API Key
- `-m, --model`: 模型名称
- `-c, --context-length`: 上下文长度（如 128k、200k、1m）
- `-t, --api-type`: API 类型（anthropic/openai）
- `-b, --base-url`: 自定义 API 地址
- `--clean`: 清理无效密钥

#### agent-center - 分布式 Agent 中心

用于启动一个中心节点，让多个 ASAI 实例可以协作工作。

```bash
# 启动（后台运行）
asai agent-center start

# 前台运行（调试用）
asai agent-center start -f

# 指定监听端口
asai agent-center start --addr :9000

# 查看状态
asai agent-center status

# 停止服务
asai agent-center stop

# 重启服务
asai agent-center restart
```

#### agent-attach - 连接到 Agent Center

将当前项目连接到分布式 Agent 中心。

```bash
# 查看当前连接状态
asai agent-attach

# 连接到 Agent Center
asai agent-attach --url http://localhost:8654

# 指定 Agent 名称（默认使用目录名）
asai agent-attach --url http://localhost:8654 --name my-agent
```

#### agent-detach - 断开连接

```bash
# 断开与 Agent Center 的连接
asai agent-detach
```

#### web - Web 服务

启动 Web 界面，可通过浏览器访问。

```bash
# 启动（后台运行）
asai web start

# 前台运行
asai web start -f

# 指定端口
asai web start --port 8080

# 停止服务
asai web stop

# 查看状态
asai web status
```

#### hub - Web 控制台

启动 ASAI Hub 控制台，统一管理所有 Web 实例（创建 / 打开 / 停止）。Hub 与各项目实例共用同一份 SPA，通过入口模式区分。

```bash
# 启动（默认端口 2999，自动打开浏览器）
asai hub

# 自定义端口
asai hub --port 2999

# 不自动打开浏览器（无桌面环境的服务器场景）
asai hub --no-open
```

默认监听 `0.0.0.0:2999`，端口被占用时会在 2999 → 2990 范围内自动回退。`asai hub` 会前台阻塞运行，需要常驻可配合 `nohup`、`tmux/screen` 或 systemd。

##### 在 Linux 服务器上使用

直接执行二进制即可启动服务，本机访问 `http://127.0.0.1:2999`：

```bash
# 服务器侧
asai hub --no-open
```

> ⚠ 安全提示：Hub 绑定 `0.0.0.0`，凡是能访问服务器 2999 端口的人都能进入控制台并创建 Web 实例。在公网或共享服务器上，建议通过防火墙/安全组限制端口，或使用 SSH 端口转发：
>
> ```bash
> # 本地终端
> ssh -L 2999:127.0.0.1:2999 user@server
> # 然后浏览器访问 http://127.0.0.1:2999
> ```

## 交互模式命令

进入 `asai` 后可使用以下命令：

### 斜杠命令

| 命令 | 说明 |
|------|------|
| `/help` | 显示帮助 |
| `/resume` | 恢复会话 |
| `/new` | 新建会话 |
| `/model` | 切换模型 |
| `/compress` | 压缩历史 |
| `/undo` | 撤销压缩 |
| `/stats` | 会话统计 |
| `/tools` | 显示工具 |
| `/skills` | 显示技能 |
| `/clear` | 清除历史 |
| `/exit` | 退出 |

### 快捷输入

| 格式 | 说明 | 示例 |
|------|------|------|
| `@文件` | 注入文件内容 | `@main.go` |
| `@目录/` | 注入目录内容 | `@src/` |
| `!命令` | 执行 shell 命令 | `!ls -la` |

### 快捷键

| 按键 | 说明 |
|------|------|
| `↑`/`↓` | 浏览输入历史 |
| `E` | 暂停后编辑（执行中） |
| `Enter` | 继续（暂停时） |
| `Esc` | 中止（执行中） |
| `Ctrl+J` | 换行 |
| `Ctrl+C` | 退出 |

## 配置文件

### 配置文件位置

- 全局配置：`~/.asai/config.yaml`
- 项目配置：`./.asai/config.yaml`

### 配置结构

```yaml
providers:
  zhipu:
    keys:
      - "your-api-key"
    active_key: "your-api-key"
    models:
      - name: glm-4.7
        context_length: 200000
    key_status:
      "your-api-key": valid

active_model: zhipu/glm-4.7
```

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `ASAI_HOME` | 配置目录 | `~/.asai` |

## 常见问题

### API Key 无效

```bash
# 清理无效密钥
asai provider --clean

# 重新配置
asai provider -p zhipu -k "新KEY" -m glm-4.7 -c 200k
```

### 模型无法加载

检查模型名称是否正确，以及 API Key 是否有权限访问该模型。

### 连接 Agent Center 失败

确认 Agent Center 已启动：`asai agent-center status`

检查 URL 是否正确。

## 输出格式

### text（默认）

```
> 分析代码
[AI response]
```

### json

```bash
asai --output-format json "你的问题"
```

输出 JSON 格式，适合程序解析。

### stream-json

```bash
asai --output-format stream-json "你的问题"
```

流式输出 JSON，逐字返回 AI 响应。

## 技术栈

- **后端** — Go 1.25+、Cobra（CLI）、Bubble Tea（TUI）、Gorilla WebSocket
- **前端** — Vue 3 + Vite + TailwindCSS v4
- **数据库** — SQLite（纯 Go 驱动 modernc.org/sqlite，无 CGo 依赖）
- **LLM 框架** — Eino（ReAct Agent 模式、工具接口）

## 参与贡献

欢迎提交 Issue 和 Pull Request！请阅读 [贡献指南](./CONTRIBUTING.md) 了解详情。

## 许可证

本项目基于 [Apache License 2.0](./LICENSE) 开源。