112 lines
5.4 KiB
Markdown
112 lines
5.4 KiB
Markdown
# 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
|