96 lines
2.5 KiB
Markdown
96 lines
2.5 KiB
Markdown
|
# 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 | 使用说明 | 功能变更时 |
|