75 lines
1.7 KiB
Markdown
75 lines
1.7 KiB
Markdown
|
# 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 次未解决，强制自动退出
|
|||
|
|
- 交由用户操作
|