# agents.md - AI 编码规范声明

## 项目信息

| 项目 | 内容 |
|------|------|
| 项目名称 | ttychart-mcp |
| 项目描述 | 终端图表 MCP 服务 |
| 仓库地址 | hub.gaomia.site/titor/ttychart-mcp |

## 编码规范

### 1. 代码注释要求

- **所有代码必须使用中文注释**
- 包含函数注释、类型注释、类注释等
- 注释必须详细说明功能、参数、返回值
- 示例:
  ```go
  // NewLineChart 创建新的折线图
  //
  // 参数:
  //   - width: 图表宽度（0 表示自动计算）
  //   - height: 图表高度（0 表示自动计算）
  //
  // 返回值:
  //   - *LineChart: 折线图实例
  func NewLineChart(width, height int) *LineChart {
      return &LineChart{
          Width:  width,
          Height: height,
      }
  }
  ```

### 2. 变量和函数命名

- **变量命名**: 使用小写_格式 (snake_case)，语义化
  - ✅ `chartWidth`, `dataPoints`, `colorStyle`
  - ❌ `w`, `dp`, `c`
- **函数命名**: 使用驼峰命名 (camelCase)，语义化
  - ✅ `SetData()`, `RenderChart()`, `ParseData()`
  - ❌ `set()`, `render()`, `parse()`

### 3. 包和模块设计

- **OOP + 设计模式**: 使用面向对象和设计模式
- **高内聚低耦合**: 模块之间尽量减少依赖
- **单一职责**: 每个函数/类型只负责一件事

### 4. 测试要求

- **单元测试**: 每个函数必须有对应的单元测试
- **集成测试**: 模块之间必须进行集成测试
- 测试文件命名: `xxx_test.go`
- 测试函数命名: `TestXxx`

### 5. 构建产物

- **二进制文件**: 存放在项目根目录
- **不允许**: 存放在其他目录 (如 bin/, dist/)
- **编译命令**: `go build -o ttychart-mcp .`

### 6. 发布流程

- 发布 Git 前必须:
  1. 保存讨论记录到 taolun.md
  2. 保存版本更新到 changelog.md
  3. 运行测试确保通过
  4. 构建确认无错误

### 7. 问题处理

- **重复问题**: 同一个问题尝试三次无结果，强制退出
- **强制退出**: 由用户接手处理
- **错误处理**: 详细的错误日志记录

## 语言要求

- **所有交谈**: 必须使用中文
- **所有注释**: 必须使用中文
- **所有文档**: 必须使用中文

## 版本管理

- 使用语义化版本号 (SemVer): MAJOR.MINOR.PATCH
- 格式: v0.1.0

## 文档维护

| 文档 | 用途 | 更新时机 |
|------|------|--------|
| agents.md | AI 声明 | 项目创建时 |
| changelog.md | 版本记录 | 每次版本更新 |
| taolun.md | 会话记录 | 每次会话开始/结束 |
| README.md | 使用说明 | 功能变更时 |