harness 与 hermes-agent 运行原理和核心流程

Harness 的运行流程

Harness 的主程序入口在：

text 复制代码

harness/cmd/gitness/main.go

启动主线是：

text 复制代码

gitness server .local.env
        |
cli/operations/server/server.go
        |
加载 env -> LoadConfig -> SetupLogger -> SetupProfiler
        |
cmd/gitness/wire.go / wire_gen.go 组装依赖
        |
bootstrap 初始化系统 service、pipeline service、gitspace service、admin 用户
        |
启动 HTTP server、metric server、job scheduler、SSH server
        |
app/router/web.go 提供 API、Swagger、OpenAPI、前端 UI

Harness 的请求处理原理

典型 Web/API 请求链路：

text 复制代码

浏览器 / CLI / curl
      |
HTTP server
      |
router + middleware
      |
app/api/controller/*
      |
app/services/*
      |
store / git / registry / job / pubsub
      |
数据库、文件系统、Git 仓库、Docker、Redis

前端通过 OpenAPI 生成的 TypeScript client 调用后端接口。后端负责认证、授权、业务校验和持久化。

Harness 前端嵌入原理

Harness 的前端不是纯独立服务。它有两种形态：

开发时，web 可以独立启动 webpack dev server
构建时，web/dist 会被 Go embed 机制打进二进制

关键文件：

text 复制代码

harness/web/dist.go
harness/app/router/web.go

所以最终 gitness 二进制可以直接提供 UI。

Hermes Agent 的运行流程

Hermes Agent 的主要入口来自 pyproject.toml：

text 复制代码

hermes = hermes_cli.main:main
hermes-agent = run_agent:main
hermes-acp = acp_adapter.entry:main

典型 CLI 对话链路：

text 复制代码

hermes
  |
hermes_cli/main.py
  |
加载 profile / config / env / CLI 参数
  |
run_agent.AIAgent
  |
构造模型 client + system prompt + tool definitions
  |
调用 LLM
  |
模型返回文本或 tool_calls
  |
model_tools.handle_function_call / tools.registry dispatch
  |
工具结果写回 messages
  |
继续调用 LLM，直到完成或达到预算
  |
持久化 session/messages 到 hermes_state.py 管理的 SQLite

Hermes Agent 的工具调用原理

核心机制：

每个工具文件通过 tools.registry.register() 自注册
tools/registry.py 保存 schema、handler、check_fn、toolset 信息
model_tools.py 负责 discovery、schema 输出、函数调用分发
toolsets.py 定义工具集合和组合关系
run_agent.py 在模型返回 tool_calls 后执行工具

简化流程：

text 复制代码

工具模块 import
      |
registry.register(name, schema, handler)
      |
get_tool_definitions()
      |
LLM 看到可用工具 schema
      |
LLM 返回 tool_calls
      |
AIAgent 执行工具
      |
工具输出进入下一轮 messages

Hermes Agent 的 Gateway 原理

Gateway 在：

text 复制代码

hermes-agent/gateway/run.py

它把多种消息平台统一成 agent 会话入口：

Telegram
Discord
Slack
WhatsApp
Signal
Matrix
Email
Webhook
其他平台 adapter

典型链路：

text 复制代码

用户在消息平台发消息
      |
平台 adapter 收到事件
      |
gateway session 管理和权限/配对判断
      |
取出或创建 AIAgent
      |
调用 run_conversation
      |
把回复发回对应平台

运行原理对比

维度	Harness	Hermes Agent
主循环	HTTP/SSH/Job server 常驻	Agent 对话循环 + Gateway 常驻
输入	API 请求、Git 请求、Webhook、UI 操作	用户消息、CLI 输入、cron、ACP 请求
输出	页面、API 响应、Git/Registry 协议响应、日志	文本回复、工具结果、文件修改、消息投递
状态推进	业务服务更新数据库和 Git/Registry 状态	LLM 多轮推理 + 工具结果推进会话
后台任务	job scheduler、metric collector、cleanup	cron scheduler、gateway watcher、session/cache eviction
失败处理	返回错误码、事务回滚、优雅关闭	retry、fallback、压缩、错误分类、工具防护