# agents.md

## AI 行为规范

### 1. 代码规范

- 使用 OOP 风格 + 设计模式
- 遵循 Go 编码规范（fmt, vet, lint）
- 所有公共函数/类型必须有注释
- 错误处理：返回有意义错误，使用 errors.Wrap

### 2. 文件结构

```
picoclaw-chart/
├── cmd/server/          # 入口点
├── internal/
│   ├── handler/          # HTTP 处理层
│   ├── service/          # 业务逻辑层
│   ├── renderer/         # 渲染器（策略模式）
│   │   ├── renderer.go   # 接口定义
│   │   ├── svg.go        # SVG 渲染
│   │   ├── png.go        # PNG 渲染
│   │   ├── ansi.go       # ANSI 彩色渲染
│   │   └── text.go       # 纯文本渲染
│   └── types/            # 数据结构
├── .env.example          # 环境变量示例
├── Dockerfile
├── docker-compose.yml
└── go.mod
```

### 3. API 设计

- 路由前缀：`/api/v1`
- POST `/chart` - 创建图表
- GET `/chart/:id` - 获取图表
- GET `/chart/:id.png` - 下载 PNG
- GET `/health` - 健康检查

### 4. 响应格式

```json
{
  "chart_id": "string",
  "text": "string",
  "ansi": "string",
  "svg": "string",
  "png_url": "string",
  "markdown": "string"
}
```

### 5. 错误处理

- HTTP 4xx: 客户端错误（参数错误等）
- HTTP 5xx: 服务端错误
- 错误响应格式：`{"error": "message"}`

### 6. 配置管理

- 使用 `.env` 文件
- 支持环境变量覆盖
- 配置结构：`internal/config/config.go`

### 7. 测试策略

- 单元测试覆盖核心渲染器
- 集成测试覆盖 API 端点

### 8. 调试策略

- 一个问题循环 3 次未解决，强制自动退出
- 交由用户操作