From 308fea39fced53f3e59d3826160694f7a6b634b1 Mon Sep 17 00:00:00 2001 From: hhs <386998068@qq.com> Date: Wed, 10 Jun 2026 10:40:09 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A7=84=E8=8C=83=E6=8F=90=E4=BA=A4?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 3 +- CLAUDE.md | 111 ----------------------------------------------------- 2 files changed, 2 insertions(+), 112 deletions(-) delete mode 100644 CLAUDE.md diff --git a/.gitignore b/.gitignore index 96c0ecc..5f71c31 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ -docs/ \ No newline at end of file +docs/ +CLAUDE.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 5c0a7ea..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,111 +0,0 @@ -# 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：`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