terminal-chart-server/agents.md

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. 响应格式

{
  "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 次未解决，强制自动退出
• 交由用户操作