开发与协作规则

1. 基本规范

1.1 语言要求

  • 请保持对话语言为中文
  • 所有代码注释和文档也应使用中文

1.2 平台要求

  • 主要开发系统为Windows 11平台
  • 支持跨平台开发，包括Linux和macOS
  • 代码和脚本应在所有目标平台上正常运行
  • 平台特定代码应明确标记并提供替代方案

2. 代码注释规范

2.1 功能函数注释

  • 每新增一个功能函数，都需要在代码中添加注释
  • 注释中需要包含函数的功能、参数、返回值等信息
  • 跨平台函数应注明平台兼容性

2.2 类注释

  • 每新增一个类，都需要在代码中添加注释
  • 注释中需要包含类的功能、属性、方法等信息
  • 跨平台类应注明平台兼容性

2.3 文件头注释

  • 每新增一个文件，都需要在文件头添加注释
  • 注释中需要包含文件的功能、作者、日期等信息
  • 具体格式参考"9. 版权信息规范"
  • 跨平台文件应注明支持的平台

2.4 模块注释

  • 每新增一个模块，都需要在代码中添加注释
  • 注释中需要包含模块的功能、属性、方法等信息
  • 跨平台模块应注明平台兼容性

2.5 变量注释

  • 关键变量和复杂逻辑变量需要添加注释
  • 注释中需要包含变量的功能、类型、默认值等信息
  • 自解释的变量名称可不添加注释

2.6 常量注释

  • 关键常量和特殊值需要添加注释
  • 注释中需要包含常量的功能、类型、值等信息
  • 自解释的常量名称可不添加注释

2.7 枚举注释

  • 枚举需要添加注释，说明其用途和使用场景
  • 注释中需要包含枚举的功能、成员说明等信息
  • 重要枚举值需要单独注释说明

2.8 接口注释

  • 每新增一个接口，都需要在代码中添加注释
  • 注释中需要包含接口的功能、方法等信息
  • 跨平台接口应注明平台兼容性

3. 代码修改原则

3.1 保持代码逻辑

  • 在修复已存在的代码时，尽量不要破坏已有的代码逻辑
  • 只修复必要的问题，除非有强烈的理由需要改变已有的代码逻辑

3.2 代码可读性

  • 在新增或修改代码时，要注意代码的可读性和可维护性
  • 避免使用复杂的逻辑和嵌套的条件语句

3.3 冲突处理

  • 如果新增或修改的代码与已有的代码存在冲突，要及时通知并协调解决

3.4 代码理解

  • 在修改代码时，要先尽量去理解已有的代码逻辑
  • 避免引入新的问题

4. 代码风格规范

4.1 缩进与空格

  • 使用4个空格进行缩进，避免使用制表符
  • 运算符两侧添加空格
  • 逗号后添加空格
  • 大括号使用K&R风格（左大括号在行尾，右大括号单独一行）

4.2 命名约定

  • 遵循各编程语言的主流命名约定
  • JavaScript/TypeScript：变量和函数使用camelCase，类名使用PascalCase，常量使用UPPER_CASE
  • Python：变量和函数使用snake_case，类名使用PascalCase，常量使用UPPER_CASE
  • 其他语言：遵循该语言的PEP或官方指南
  • 文件名：使用小写字母和下划线，避免使用空格和特殊字符
  • 平台特定代码：使用平台前缀（如win_、linux_、mac_）

4.3 代码长度

  • 每行代码长度不超过120个字符
  • 过长的代码应适当换行，保持可读性
  • URL、文件路径等特殊内容可适度超出限制

4.4 跨平台编码注意事项

  • 路径处理：使用相对路径或跨平台路径库，避免硬编码路径分隔符
  • 系统调用：使用跨平台库或提供平台特定实现
  • 文件编码：统一使用UTF-8编码
  • 行尾符：统一使用LF（Unix风格）行尾符
  • 环境变量：使用跨平台方式获取环境变量

5. 测试与质量保证

5.1 测试要求

  • 新增功能必须编写相应的测试用例
  • 修复bug后必须添加回归测试
  • 测试覆盖率目标：核心功能≥80%
  • 跨平台功能必须在所有目标平台上进行测试

5.2 跨平台测试策略

  • Windows：在本地Windows 11环境测试
  • Linux：通过SSH远程测试或使用容器
  • macOS：在实际macOS环境测试
  • 自动化测试：优先使用可在多平台运行的测试框架

5.3 代码审查

  • 所有代码修改必须经过代码审查
  • 代码审查重点：功能正确性、代码风格、性能影响、安全性、跨平台兼容性

5.4 性能与安全性

  • 考虑代码的性能影响，避免不必要的计算和资源消耗
  • 注意安全编码实践，避免常见的安全漏洞
  • 敏感信息不得硬编码在代码中

6. 版本控制规范

6.1 提交消息格式

  • 提交消息应简洁明了，描述具体变更
  • 格式：[类型] 简短描述
  • 类型包括：feat（新功能）、fix（修复）、docs（文档）、style（样式）、refactor（重构）、test（测试）、chore（构建/依赖）
  • 跨平台相关变更：使用[cross-platform]标签

6.2 分支管理

  • 主分支：main（稳定版本）
  • 开发分支：dev（开发中版本）
  • 特性分支：feature/功能名称
  • 修复分支：fix/问题描述
  • 平台特定分支：platform/平台名称（仅在必要时使用）

6.3 代码审查流程

  • 提交Pull Request前进行自我审查
  • 至少需要1名其他开发者批准才能合并
  • 合并前确保所有测试通过，包括跨平台测试

7. 文档管理规则

7.1 COLLABORATION_GUIDELINES.md

  • 记录协同规则和最佳实践的更新
  • 包含代码规范、开发流程、团队协作等内容

7.2 README.md

  • 记录项目版本更新和功能变更
  • 包含项目简介、安装说明、使用方法、常见问题等
  • 明确说明支持的平台和平台特定要求
  • 同步生成规范英文版README_EN.md

7.3 PROJECT_PLAN.md

  • 记录项目规划和重要变更
  • 包含项目目标、里程碑、任务分配等
  • 记录跨平台开发的具体计划和测试策略

7.4 PROMPT_HISTORY.md

  • 记录重要的用户需求、设计决策和技术决策
  • 记录关键对话和需求变更的上下文
  • 作为项目需求的重要参考文档，用于追溯项目演进
  • 定期整理，避免冗余重复内容

7.5 文档更新频率

  • 每次代码修改后更新相关文档
  • 每次对话后立及更新PROMPT_HISTORY.md
  • 项目重要变更时更新所有相关文档

8. 开发流程规范

8.1 流程顺序

  • 重大功能开发前先更新PROJECT_PLAN.md，明确开发目标和计划
  • 重要需求变更或设计决策后更新PROMPT_HISTORY.md
  • 小改动和bug修复可直接进行，无需强制更新文档
  • 项目阶段完成后总结COLLABORATION_GUIDELINES.md，沉淀知识

8.2 任务执行步骤

  1. 分析需求，更新PROJECT_PLAN.md
  2. 编写或修改代码，添加必要的注释
  3. 编写测试用例，确保功能正常
  4. 在所有目标平台上运行测试，验证跨平台兼容性
  5. 提交代码，编写规范的提交消息
  6. 更新相关文档（README.md等）
  7. 进行代码审查
  8. 合并代码，完成任务

8.3 问题处理流程

  1. 识别问题，记录在PROJECT_PLAN.md中
  2. 分析问题原因，制定解决方案
  3. 实施修复，添加注释说明
  4. 编写测试用例验证修复效果
  5. 在所有目标平台上验证修复
  6. 更新相关文档，记录问题和解决方案
  7. 提交代码，完成修复

9. 版权信息规范

9.1 统一的版权信息格式

所有文档和代码文件必须包含以下版权信息头部，根据不同编程语言使用对应的注释符号：

9.1.1 Markdown文档 (.md)

<!--
File: 文件名
Project: 项目名称
File Created: 创建时间 (格式: YYYY-MM-DD HH:MM:SS am/pm)
Author: wcs (cs@jsait.com)
-----
Last Modified: 修改时间 (格式: YYYY-MM-DD HH:MM:SS am/pm)
Modified By: wcs (cs@jsait.com)
-----
Copyright (c) 创建年份 JS@
-->

9.1.2 Bash脚本 (.sh)

#!/bin/bash

# File: 文件名
# Project: 项目名称
# File Created: 创建时间 (格式: YYYY-MM-DD HH:MM:SS am/pm)
# Author: wcs (cs@jsait.com)
# -----
# Last Modified: 修改时间 (格式: YYYY-MM-DD HH:MM:SS am/pm)
# Modified By: wcs (cs@jsait.com)
# -----
# Copyright (c) 创建年份 JS@

9.1.3 批处理脚本 (.bat)

@echo off
SETLOCAL

REM File: 文件名
REM Project: 项目名称
REM File Created: 创建时间 (格式: YYYY-MM-DD HH:MM:SS am/pm)
REM Author: wcs (cs@jsait.com)
REM -----
REM Last Modified: 修改时间 (格式: YYYY-MM-DD HH:MM:SS am/pm)
REM Modified By: wcs (cs@jsait.com)
REM -----
REM Copyright (c) 创建年份 JS@

9.1.4 Python脚本 (.py)

#!/usr/bin/env python3

# File: 文件名
# Project: 项目名称
# File Created: 创建时间 (格式: YYYY-MM-DD HH:MM:SS am/pm)
# Author: wcs (cs@jsait.com)
# -----
# Last Modified: 修改时间 (格式: YYYY-MM-DD HH:MM:SS am/pm)
# Modified By: wcs (cs@jsait.com)
# -----
# Copyright (c) 创建年份 JS@

9.1.5 JavaScript文件 (.js)


// File: 文件名
// Project: 项目名称
// File Created: 创建时间 (格式: YYYY-MM-DD HH:MM:SS am/pm)
// Author: wcs (cs@jsait.com)
// -----
// Last Modified: 修改时间 (格式: YYYY-MM-DD HH:MM:SS am/pm)
// Modified By: wcs (cs@jsait.com)
// -----
// Copyright (c) 创建年份 JS@

9.2 应用规则

  • 强制要求：所有新创建或修改的文件都必须遵循此规范
  • 版权年份：使用文档或文件的实际创建年份
  • 时间格式：使用12小时制，格式为"YYYY-MM-DD HH:MM:SS am/pm"
  • 文件名：使用文件的实际名称
  • 项目名称：使用项目的完整名称
  • 注释符号：根据不同编程语言使用对应的注释符号，确保语法正确
  • 不破坏功能：添加版权信息时不得破坏文件的现有功能

10. 跨平台开发工具与实践

10.1 推荐工具

  • 版本控制：Git（跨平台）
  • 编辑器/IDE：VS Code（跨平台）
  • 构建工具：CMake、Make、npm等（跨平台）
  • 容器：Docker（用于一致的Linux测试环境）
  • 远程开发：VS Code Remote SSH（用于Linux开发）

10.2 项目结构最佳实践

  • 统一的项目结构，适应所有目标平台
  • 平台特定代码分离到独立目录或模块
  • 使用配置文件管理平台特定设置
  • 提供平台特定的构建和运行脚本

10.3 依赖管理

  • 使用跨平台包管理器（如pip、npm、 Cargo等）
  • 明确指定依赖版本，避免版本冲突
  • 平台特定依赖应在文档中明确说明
  • 使用依赖锁定文件确保构建一致性

11. 执行与监督

11.1 规则执行

  • 所有开发者必须严格遵守上述规则
  • 每次代码提交前应自我检查是否符合规则要求
  • 代码审查时应将规则遵守情况作为审查重点

11.2 监督机制

  • 定期对项目代码和文档进行规则遵守情况检查
  • 发现违反规则的情况应及时提醒并纠正
  • 严重违反规则的情况应在团队会议中讨论并制定改进措施

11.3 持续改进

  • 定期评估规则的有效性和适用性
  • 根据实际情况对规则进行必要的调整和完善

  • 收集团队成员的反馈，不断优化规则体系