first-agent

一个运行在 Windows 上的命令行 AI Agent。Go 编写的 REPL，通过 Ollama 调用大模型并执行工具调用循环：模型发起工具调用，程序执行（文件读写、命令执行），把结果回传给模型，循环直到模型返回纯文本。

环境要求

• Windows 操作系统
• Go 1.25+
• Ollama 服务（本地或局域网均可）

编译与运行

go run ./cmd/first-agent              # 直接运行
go build -o agent.exe ./cmd/first-agent   # 编译
agent.exe                      # 启动交互控制台
go vet ./...                          # 静态检查

配置

支持三种方式，优先级：命令行参数 > 环境变量 > 默认值。

命令行参数	环境变量	默认值	说明
-conversation	FIRST_AGENT_CONVERSATION	./conversation	会话记录目录
-ollama	FIRST_AGENT_OLLAMA_URL	http://localhost:11434/api/chat	Ollama 聊天接口地址
-model	FIRST_AGENT_MODEL	glm-4.7-flash:q4_K_M	模型名
-max-iterations	~	10	最大循环调用工具次数

示例：

# 命令行参数
agent.exe -ollama http://localhost:11434/api/chat -model qwen3:8b

# 环境变量（cmd）
set FIRST_AGENT_OLLAMA_URL=http://localhost:11434/api/chat
set FIRST_AGENT_MODEL=qwen3:8b

启动后控制台会打印当前生效的 Ollama 地址、模型与会话目录。

交互

启动后在 user > 提示符后输入需求，输入 quit 退出。行首 ^ 开始、行尾 ^ 结束为多行输入。例如：

Agent 交互控制台，输入 quit 退出
user > 帮我在 C:\Windows\Temp 下创建一个 hello.txt，内容写「你好」
user > 查一下本机的 IP 配置

每轮对话（用户输入、工具调用、工具返回、最终回答）以 JSONL 格式追加保存到会话目录，文件名为启动时间。

会话记录

会话记录相关命令行参数，执行后直接退出，不进入交互：

参数	说明
-list	列出全部会话（文件名、大小、修改时间，按时间倒序）
-show <name>	在终端输出指定会话内容（markdown 格式）
-export <name>	导出指定会话为 markdown 文件
-out <path>	配合 -export 指定输出路径，默认写在会话目录下

name 为会话文件名，可省略 .jsonl 后缀。示例：

agent.exe -list
agent.exe -show 2026-09-03_10_53_44
agent.exe -export 2026-09-03_10_53_44 -out D:\backup\chat.md

内置工具

工具在 internal/models/tools.go 的 BuildTools() 中声明，在 internal/agent/agent.go 的 toolRegistry 中注册执行。

工具名	作用	参数
write_string_file	写入文件，不存在则自动创建	path（必填）、content、append、wordWrap
read_file	读取文件内容	path（必填）
execute_command	执行 CMD / PowerShell 命令	command（必填）、mode（必填，run 等待返回输出 / spawn 后台运行返回 pid）、shell（填 powershell 走 PowerShell）
kill_process	按 pid 终止进程	pid（必填）

系统提示词已告知模型：运行在 Windows 上，命令已自带 cmd /c 前缀，不要重复添加；服务类命令（npm start 等）需用 spawn 模式后台启动。Windows 命令输出自动处理编码：UTF-8 BOM 剥离，合法 UTF-8 直通，否则按 GB18030 解码。

工作流程

一次用户输入的处理流程：

1. cmd/first-agent/main.go 解析参数，读取 stdin，追加 system 与 user 消息并持久化，调用 agent.Loop(cid, &messages)。
2. Loop 把完整消息历史 + 工具定义 POST 给 Ollama。
3. 若返回包含 tool_calls，按工具名分发执行，把 role:"tool" 的结果追加进历史并持久化，然后再次请求模型，最多循环 10 次。
4. 若模型不再调用工具（返回纯文本），打印最终回答并结束本轮。

项目结构

cmd/first-agent/main.go   # 入口：参数解析、交互控制台、会话记录命令
internal/agent/           # Agent 核心：HTTP 请求 Ollama + 工具调用分发循环
internal/models/          # Ollama 接口数据结构与 BuildTools() 工具声明
internal/session/         # 会话 JSONL 持久化、列表、查看、导出 markdown
internal/tool/            # 文件读写、命令执行（前台/后台）、编码解码、辅助函数
conversation/             # 运行时生成的会话记录（.jsonl / .md）

扩展工具

1. 在 internal/models/tools.go 的 BuildTools() 中新增工具声明（名称、描述、参数 Schema）。
2. 在 internal/agent/agent.go 中新增处理函数并注册到 toolRegistry。