ttychart-mcp/agents.md

agents.md - AI 编码规范声明

项目信息

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

编码规范

1. 代码注释要求

• 所有代码必须使用中文注释
• 包含函数注释、类型注释、类注释等
• 注释必须详细说明功能、参数、返回值
• 示例:

  // 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	使用说明	功能变更时