V codeAgents in V

V codeAgents in V (vaiv) 是一个用V语言编写的终端程序，帮助程序员编写V语言代码。它通过云端或本地大模型（LLM）提供智能编程辅助，并内置V语言语法高亮、代码补全、代码执行、对话压缩等功能。

项目原名 vaiv (V program Assistant in V)，v0.2.0 起更名为 V Agent In Vlang，v0.3.0 起更名为 V codeAgents in V。命令行可执行文件仍为 vaiv。

所有后端均使用V标准库 json 模块进行可靠的JSON编码/解码，正确处理特殊字符和转义序列。

LM Studio 与 OpenAI 后端共用 /v1/chat/completions 端点（OpenAI兼容API），默认URL为 http://127.0.0.1:1234。

LLM 客户端具备网络健壮性：HTTP 请求使用配置的超时（默认120秒）和 max_retries=2 重试，网络错误返回带 URL 的友好提示，非 2xx 响应返回状态码与响应体片段，JSON 解析失败时返回后端名 + 响应体前200字符片段，避免因异常 HTML 响应让用户困惑。

• 自动维护对话上下文
• LLM能记住之前的对话内容
• 支持可配置的对话历史长度（默认20轮）
• 自动注入V语言规则到系统提示词

• 自动压缩：当历史消息超过阈值时，自动调用LLM将早期对话摘要为一条system消息
• 手动压缩：/compress 命令随时触发
• 保留系统提示词和最近N条消息（默认保留最近6条）
• 压缩失败自动回退，不影响正常对话
• 可配置压缩阈值、保留条数、压缩温度
• /tokens 命令查看当前对话历史的 token 估算（~4字符/token 启发式），并提示与压缩阈值的距离

• 基于SQLite的持久化记忆存储，跨会话保留用户保存的事实
• 数据库位于 ~/.config/vaiv/memories.db，启动时自动创建
• /remember <key> <content> — 保存/更新一条记忆（同 key 自动覆盖）
• /recall [key] — 列出全部记忆或查询单个 key
• /forget <key> — 删除一条记忆
• 记忆自动注入到 system prompt，LLM 在每次请求时都能看到

• 支持Ollama、OpenAI、llama.cpp、LM Studio的流式响应
• 逐token解析LLM输出

• ! 前缀直接执行V代码片段
• /run 命令执行V文件
• /check 命令调用V编译器检查语法

• /read 读取文件（带语法高亮）
• /write 写入文件
• /edit 编辑文件指定行
• /ls 列出目录中的文件

• /save 保存对话历史到JSON文件
• /load 加载之前的对话
• 使用标准JSON格式，兼容性好

• 自动读取项目文件（main.v, v.mod）作为上下文
• 列出项目中的V文件
• /context 刷新项目上下文

• Tab补全V关键字、内置函数、类型
• 支持55+个补全项
• / 前缀触发命令补全

• V关键字高亮（magenta）
• V类型高亮（cyan）
• 字符串高亮（green）
• 注释高亮（dim）
• 数字高亮（yellow）

• 所有配置变更自动保存到 ~/.config/vaiv/config.toml
• 配置验证与默认值回退
• /backend、/model、/url、/key、/temp 命令即时持久化

• V语言编译器 0.5.0+
• 一个可用的LLM后端（Ollama / OpenAI兼容API / llama.cpp / LM Studio）

# 克隆项目
git clone <repo-url>
cd vaiv

# 开发模式运行
v run .

# 构建生产版本
v -prod .

# 格式化代码
v fmt -w .

# 运行测试
v test .

# 直接运行
v run .

# 或运行编译后的二进制
./vaiv

# 查看版本
./vaiv version

# 查看配置
./vaiv config

vaiv> 写一个V语言的Hello World程序
assistant: module main

fn main() {
    println('Hello, World!')
}

vaiv> 给它添加命令行参数支持
assistant: module main

import os

fn main() {
    args := os.args
    if args.len > 1 {
        println('Hello, ${args[1]}!')
    } else {
        println('Hello, World!')
    }
}

直接输入 /model（无参数）会从当前后端拉取可用模型列表，进入交互选择：

vaiv> /model
Querying available models from lmstudio...
Current model: qwen2.5-coder-7b-instruct
Available models:
 *  1. qwen2.5-coder-7b-instruct
    2. llama-3.1-8b-instruct
    3. phi-3.5-mini-instruct

Enter number to select, or type a model name. Empty to cancel.
model> 2
Model switched to: llama-3.1-8b-instruct

后端支持：

• Ollama：GET /api/tags
• OpenAI / LM Studio：GET /v1/models
• llama.cpp：无标准列表端点，提示用 /model <name> 手动切换

网络错误或后端不可达时，会回退到提示手动切换。/model <name> 形式仍可直接切换，无需经过交互。

• ? - 代码助手模式（专注于代码生成和解释）
• ! - 直接执行V代码

vaiv> ?explain how error handling works in V
vaiv> !println('hello')

输入部分关键字后按Tab键补全：

vaiv> pr[TAB]    # 补全为 println
vaiv> fn[TAB]    # 补全为 fn
vaiv> in[TAB]    # 补全为 int, i8, i16, i64...
vaiv> /[TAB]     # 显示所有命令

配置文件位于 ~/.config/vaiv/config.toml

# V codeAgents in V configuration
# Backend options: ollama, openai, llamacpp, lmstudio
backend = "ollama"
api_key = ""
base_url = "http://localhost:11434"
model = "codellama"
temperature = 0.7
history_size = 1000
max_history = 20
compress_threshold = 12
keep_recent = 6
compress_temp = 0.3

所有通过命令（/backend、/model、/url、/key、/temp）修改的配置会自动保存到配置文件。

vaiv/
├── v.mod                    # V模块定义
├── main.v                   # 入口点
├── config.v                 # 配置处理（加载/保存/验证）
├── repl.v                   # REPL循环和命令处理
├── repl_test.v              # REPL测试（系统提示词、压缩、记忆）
├── llm/
│   ├── client.v            # LLM客户端（支持多后端，含超时重试）
│   └── client_test.v       # LLM客户端测试
├── memory/
│   ├── memory.v            # 跨会话记忆持久化（SQLite）
│   └── readme.txt          # 模块说明
├── completion/
│   ├── keywords.v          # V关键字、内置函数、类型
│   ├── matcher.v           # 补全匹配逻辑
│   └── matcher_test.v      # 补全匹配测试
├── display/
│   ├── colors.v            # 终端颜色
│   ├── syntax.v            # V语法高亮
│   └── syntax_test.v       # 语法高亮测试
├── vlang-fullstack-development-skills/  # V语言参考文档
├── AGENTS.md               # AI助手指南
├── README.md               # 项目说明
├── CHANGELOG.md            # 更新日志
└── plan.txt                # 项目目标

使用vaiv时，LLM会遵循以下V语言规则：

1. 变量默认不可变，使用 mut 声明可变变量
2. := 声明，= 赋值
3. in 是关键字，不要用作变量名（使用 inlet）
4. int * float 非法，必须转换：f64(x)
5. int 始终是32位
6. 使用 snake_case 命名函数/变量，PascalCase 命名类型
7. 错误传播：fn foo() !T，用 or {} 处理
8. 不允许变量遮蔽
9. veb端点需要 pub 关键字

# 安装Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 下载模型
ollama pull codellama

# 启动vaiv
v run .

v run .
/backend openai
/key sk-your-api-key
/model gpt-4

# 启动llama.cpp服务器
./server -m models/codellama-7b.bin --port 8080

# 启动vaiv
v run .
/backend llamacpp
/url http://localhost:8080

# 1. 启动 LM Studio
# 2. 在 Local Server 标签页加载模型（如 qwen2.5-coder-7b-instruct）
# 3. 点击 Start Server（默认端口 1234）

# 启动vaiv
v run .
/backend lmstudio
/model qwen2.5-coder-7b-instruct

LM Studio 使用 OpenAI 兼容 API（/v1/chat/completions），无需 API 密钥。

v run .                    # 开发模式运行
v -prod .                  # 构建生产版本
v fmt -w .                 # 格式化代码
v test .                   # 运行测试

• 使用 snake_case 命名变量和函数
• 使用 PascalCase 命名类型和结构体
• 错误处理使用 ! 和 or {}
• 不允许变量遮蔽
• 提交前运行 v fmt -w . 格式化代码

项目包含以下测试：

• repl_test.v - REPL命令测试（系统提示词、压缩边界计算、记忆增删查改与上下文注入、is_all_digits 辅助函数）
• completion/matcher_test.v - 补全匹配逻辑测试
• display/syntax_test.v - 语法高亮测试
• llm/client_test.v - LLM客户端测试（客户端配置、模型列表 JSON 解析、ModelInfo 结构体）

v test .                   # 运行所有测试

MIT License

欢迎贡献代码！请遵循以下步骤：

1. Fork项目
2. 创建特性分支
3. 运行 v fmt -w . 格式化代码
4. 运行 v test . 确保测试通过
5. 提交更改
6. 推送到分支
7. 创建Pull Request