gHarness

一个以 工程化 Harness Engine 为目标的 Go 项目。
项目核心目标不是“做一个能跑的 demo”，而是持续打造一个：

1. 高可用（High Availability）
2. 逻辑严谨（Strict Logic）
3. 架构可扩展（Strong Architecture）

的 Agent Runtime。

---

项目定位

gHarness 当前以 HKU 的 OpenHarness 作为主要参考对象，但采用“参考 + 演进”的路线：

1. 对齐 OpenHarness 的核心思想（Tool Runtime、Loop、Context）
2. 保留本项目的工程取舍与架构演进空间
3. 在循环机制上加入自定义增强（见下方“特色 Loop 机制”）

gHarness 不是简单聊天壳，而是一个可执行、可迭代的 Agent Runtime：

1. 使用 Ollama 进行流式推理（支持 thinking 输出）
2. 暴露结构化工具给模型调用（JSON Schema）
3. 在 engine loop 中执行工具并把结果回灌上下文
4. 按轮次控制任务推进，最后给出汇总回答

---

核心目标

1) 高可用

1. 稳定的流式请求处理与错误回传
2. 明确的回合控制（max_turns）避免失控循环
3. 工具执行与模型推理解耦，降低单点故障影响

2) 逻辑严谨

1. ReAct 闭环：Thought -> Action -> Observation -> Continue
2. 工具调用结构化建模（Tool Schema + Arguments）
3. 上下文可追踪（请求历史、工具输出、最终总结）

3) 工程架构强

1. 分层清晰：app -> engine -> llm -> tools -> types/config
2. provider 与工具抽象接口化，便于替换与扩展
3. 保持可测试与可维护（单测 + 明确模块边界）

---

特色 Loop 机制（项目自定义）

在参考 OpenHarness 的基础上，当前实现加入了自己的多阶段循环策略：

1. Init 阶段：使用初始化系统提示做任务拆解
2. Loop 阶段：按回合推进，持续请求模型并执行工具
3. Final 阶段：最后统一总结，输出清晰结果

该机制强调“先规划、再迭代、后收敛”，目标是提升复杂任务的稳定性与可解释性。

---

当前能力

已实现

1. Ollama 流式对话
2. thinking / content 双流输出
3. Tool Runtime（基础工具）
   1. bash
   2. cat（文件读取）
   3. write_file
   4. grep
4. 工具注册中心 + JSON Schema 下发
5. loop 内工具执行与上下文回灌
6. 多阶段循环（Init / Loop / Final）提示词机制
7. 可配置 model / max_turns / think / cwd

进行中

1. 多 provider 统一（当前 CLI 实际启用 ollama）
2. 权限分级（default/plan/full-auto）
3. 更完整的工具集与命令系统
4. 会话持久化与压缩

---

快速开始

1) 环境要求

1. Go 1.26.2+
2. 已安装并启动 Ollama
3. 本地拉取模型（默认推荐 gemma4:e4b）

ollama pull gemma4:e4b

2) 运行

cd /Users/kregonia/codespace/go/gHarness
go run ./cmd/gharness --provider ollama --model gemma4:e4b --think on

启动后输入问题，输入 exit 退出。

---

配置项

环境变量

1. GHARNESS_PROVIDER：ollama / openai（当前 CLI 仅启用 ollama）
2. OLLAMA_BASE_URL：默认 http://localhost:11434
3. GHARNESS_MODEL：默认 gemma4:e4b
4. GHARNESS_MAX_TURNS：默认 8
5. GHARNESS_THINK：true/false
6. OPENAI_API_KEY：为后续 OpenAI 路径保留

CLI 参数

1. --provider
2. --model
3. --think on|off
4. --cwd

---

工具列表

工具名	用途	输入字段
bash	执行 shell 命令	command
cat	读取文本文件	path
write_file	写入文本文件	path, content
grep	正则搜索文件内容	pattern, path?, max_results?

说明：

1. 文件工具带有工作目录约束，防止路径逃逸
2. grep 默认最多返回 200 条匹配

---

架构总览

User Input
   |
   v
app.Run (CLI loop)
   |
   v
engine.Session.SubmitInternal
   |
   +--> Init Prompt Phase
   +--> Loop Prompt Phase (N turns)
   +--> Final Prompt Phase
   |
   +--> llm.Client.Request (Ollama stream)
   |       |
   |       +--> stream events (thinking/content)
   |
   +--> parse tool calls
   +--> tools.Registry.Execute
   +--> append tool result to context
   |
   v
next turn / final answer

代码目录

cmd/gharness/main.go       # 程序入口
internal/app/              # CLI 入口和交互循环
internal/engine/           # loop 调度、工具执行主流程
internal/llm/              # Ollama 客户端、上下文、流事件
internal/tools/            # 工具实现与注册中心
internal/config/           # 配置加载（env + default）
internal/inc/prompt.go     # 各阶段 system prompt
internal/types/            # 通用消息结构

---

开发与测试

编译

go build ./...

测试

go test ./... -v

单测示例：

go test ./internal/llm -run TestOllamaChat -v

---

路线图（建议）

1. 补齐 OpenAI/Anthropic provider 实现并统一接口
2. 引入 Permission Checker 与 plan mode
3. 增加 edit_file, todo_write, glob 等核心工具
4. 增加 slash command（/plan, /model, /permissions）
5. 会话落盘、恢复、压缩
6. 逐步对齐 OpenHarness 的 MCP / plugin / hook 机制

---

说明

本项目定位为“学习驱动的工程化 Agent 内核建设”，重点在于：

1. 以真实工程标准做架构，而不是一次性脚本
2. 以可运行能力验证设计，而不是只写概念文档
3. 在参考 OpenHarness 的同时发展自己的 Loop 与 Runtime 设计

欢迎 issue / PR，一起把 Go 版 Harness Engine 打磨成高可用、严谨、可扩展的基础设施。