# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

GoLoom is an **AI Agent Scaffold** — a Go HTTP server for building and orchestrating multi-agent LLM workflows. It supports OpenAI-compatible APIs (DeepSeek, Tongyi Qianwen, etc.), four agent orchestration patterns (LLM, Sequential, Parallel, Loop), synchronous and SSE streaming chat, and tool calling via OpenAI function calling. A Next.js frontend is documented but not yet committed.

**Module name:** `ai-agent-scaffold-go`
**Language:** Go 1.26
**Documentation language:** Chinese (docs/ directory)

## Build and Run

```bash
# First-time setup
go mod init ai-agent-scaffold-go
go mod tidy

# Build
go build ./...

# Run (requires .env and configs/application.yaml — see docs/build-from-scratch.md)
go run ./cmd/server

# Dependencies
go get github.com/gin-gonic/gin
go get go.uber.org/zap
go get gopkg.in/yaml.v3
go get github.com/joho/godotenv
```

No Makefile, test suite, or linting configuration exists yet. The CI file at `.gitea/workflows/go-loom.yaml` is a placeholder.

## Architecture

**Three-layer design: Handler → Service → Model/LLM**

```
cmd/server/main.go              — Entry point: .env → config → bootstrap → Gin server
internal/handler/handler.go     — Presentation: Gin routes, request/response, SSE
internal/service/               — Business: ChatService, Agent impls, Runner, Assembler
internal/model/                 — Domain: config structs, core interfaces (Agent, ChatModel, Tool, Runner)
internal/config/                — Config loading: YAML parsing + ${VAR} env expansion
internal/llm/                   — OpenAI-compatible HTTP client + ChatModel adapter
pkg/types/                      — Error codes (codes.go) and AppError type (errors.go)
configs/                        — application.yaml + agent/*.yaml definitions
```

**Dependency direction:** handler → service → model/llm. `model` imports nothing internal.

## Core Interfaces (internal/model/types.go)

- **Tool** — `Name()`, `Description()`, `Call(ctx, input string) (string, error)`. Uses single `query` parameter.
- **ChatModel** — `Generate()` (sync) and `Stream()` (async via channels). Holds tool list for function calling.
- **Agent** — `Name()`, `Run(ctx, ChatContent) (string, error)`, `Stream(ctx, ChatContent, chan<- string) error`
- **Runner** — session ID generation + delegates to Agent for sync/stream execution

## Agent Types (internal/service/agent.go)

1. **LLMAgent** — single LLM call with tool-call loop (max 4 rounds)
2. **SequentialAgent** — runs sub-agents in order; output injected via `{outputKey}` template vars
3. **ParallelAgent** — runs all sub-agents concurrently, concatenates results
4. **LoopAgent** — repeats sub-agents up to `maxIterations` times

## Configuration System

Three-layer config: `.env` (secrets) → `configs/application.yaml` (server settings) → `configs/agent/*.yaml` (agent definitions). Agent YAML supports `${VAR}` and `${VAR:-default}` env var expansion at load time.

## HTTP API (base path /api/v1, default port 8091)

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/healthz` | Health check (no envelope) |
| GET | `/api/v1/query_ai_agent_config_list` | List registered agents |
| POST | `/api/v1/create_session` | Create session (JSON body) |
| GET | `/api/v1/create_session` | Create session (query params) |
| POST | `/api/v1/chat` | Synchronous chat |
| POST | `/api/v1/chat_stream` | SSE streaming chat |

Unified response envelope: `{ "code": "0000", "info": "success", "data": {} }`

Typical flow: list agents → create session → chat with sessionId.

## Key Design Notes

- LLM client is hand-rolled HTTP (not an SDK) — OpenAI-compatible endpoints only
- Tool calling uses single `query` parameter model, not arbitrary function signatures
- In-memory storage (sync.RWMutex + Map) for agent registry and sessions
- SSE streaming uses goroutine + channel pattern
- Assembler (`internal/service/assembler.go`) reads YAML configs and wires up the full agent/runner/chatmodel chain in one function

## Development Conventions

- **Git 提交粒度**：每完成一个功能函数即 commit 一次；接口与结构体等定义可完成一个整体部分后再提交
- **提交格式**：`<type>(<scope>): <description>`
  - type：`feat` / `fix` / `refactor` / `docs` / `style` / `test` / `chore`
  - scope：模块名（如 `config`、`llm`、`agent`、`handler`、`service`、`types`）
  - description：中文或英文简述
  - 示例：`feat(config): 实现 YAML 配置加载与环境变量展开`、`feat(llm): 添加 OpenAI 兼容 HTTP 客户端`
- **进度追踪**：每进入下一个功能代码块前，检查 `docs/plan.md` 中的完成情况；每完成一个功能，将对应条目在 plan.md 中标记为已完成

## Documentation

All detailed docs are in `docs/` (Chinese):
- `docs/architecture.md` — architecture design and design decisions
- `docs/api-reference.md` — HTTP API spec with curl examples
- `docs/build-from-scratch.md` — complete Go backend source code and build guide
- `docs/frontend-build-from-scratch.md` — complete Next.js frontend source code
- `docs/testing-guide.md` — testing conventions (standard `testing` + optional `testify`, no external mock frameworks)
- `docs/logging-guide.md` — zap logging levels, required log points, and structured field conventions