/architecture-overview

name: architecture-overview
description: Use when asked about harness9 architecture, module design, or how components interact — explains the system design
trigger: architecture, design, how does, module, component, structure

harness9 架构概览

核心设计原则

| 原则 | 说明 | |------|------| | **简洁** | 最小化抽象层，极少的直接依赖 | | **完备** | 覆盖 Agent 运行所需的全部核心模块 | | **生产可用** | 错误恢复、超时控制、路径沙箱、并发安全 |

标准 ReAct 循环

Turn N:
  LLM(messages + tools) → 推理 + 工具调用决策
  → 并发执行所有工具调用 → Observation 注入 context
  → Turn N+1

自然终止：模型不再发起工具调用 → 输出最终回复

三重终止保障： 1. **自然终止**：`len(responseMsg.ToolCalls) == 0` 2. **MaxTurns**：默认 50，可通过 `WithMaxTurns` 配置 3. **Context 取消**：外部 `cancel()` 或超时

模块依赖关系

cmd/harness9 (入口)
    ├── internal/context (System Prompt 组装)
    │       └── internal/skills (Skills 解析 + 索引)
    ├── internal/engine (ReAct 主循环)
    │       ├── internal/provider (LLM 调用)
    │       ├── internal/tools (工具注册 + 执行)
    │       └── internal/schema (数据类型)
    └── internal/env (配置加载)

**关键设计决策：接口定义在使用者侧**

• `tools.Registry` 接口定义在 `tools` 包，`engine` 包依赖它
• `engine.PromptBuilder` 接口定义在 `engine` 包，`context` 包实现它
• `skills.UseSkillTool` 通过 Go 结构类型满足 `tools.BaseTool` 接口，不需要 import `tools` 包（避免循环依赖）

关键数据流

TUI 模式

用户输入 → RunTUI → eng.RunStream(ctx, prompt)
    → engine.Event stream → 逐 token 追加到对话视图
    → ToolCalls → Spinner 动画 + 耗时计数
    → EventDone → 最终回复渲染到屏幕

CLI 模式（管道 / CI）

用户输入 → RunCLI → eng.Run(ctx, prompt)
    → runLoop → LLM Generate
    → ToolCalls → 并发执行 → ToolResults → 继续循环
    → 最终回复打印到 stdout

System Prompt 组装

`DefaultPromptBuilder.Build()` 按顺序组装：

1. **基础 Prompt**：角色定义 + workDir 2. **AGENTS.md**：项目级规范（文件不存在时跳过） 3. **Skills 索引**：`- name: description` 列表（为空时跳过）

完整内容示例：

You are harness9, an expert coding assistant...

## Project Guidelines (AGENTS.md)
{AGENTS.md 全文}

## Available Skills
Use the `use_skill` tool to load full content of any skill when needed.
- go-coding-standards: Use when writing or reviewing Go code...
- debugging-guide: Use when debugging Go errors...

Provider 抽象

type LLMProvider interface {
    Generate(ctx, messages, tools) (Message, error)
    GenerateStream(ctx, messages, tools) (<-chan StreamChunk, error)
}

当前实现：

• `OpenAIProvider`：兼容所有 OpenAI Chat Completions API（包括 OpenRouter、Azure）
• `AnthropicProvider`：Anthropic Messages API

**Anthropic 约束**：user/assistant 消息必须严格交替，禁止连续 assistant 消息。

工具系统

type BaseTool interface {
    Name() string
    Definition() schema.ToolDefinition  // JSON Schema，传给 LLM
    Execute(ctx context.Context, args json.RawMessage) (string, error)
}

内置工具：

| 工具 | 说明 | |------|------| | `bash` | Shell 命令执行，workDir 为 CWD | | `read_file` | 文件读取，4096 字节截断 | | `write_file` | 文件写入，自动 mkdir | | `edit_file` | 字符串替换编辑，多级模糊匹配 | | `use_skill` | 按需加载 Skill 全文 |

所有文件工具通过 `safePath()` 校验路径，防止 Path Traversal 攻击。