Skip to content
@unnc-aim

AIM Robotics

宁波诺丁汉大学 AIM Robotics 战队仓库
README.md

欢迎回到 UNNC AIM Robotics 战队

本组织开放给所有 AIM 战队内成员使用，所有成员需遵守以下规范：

1. 仓库使用规范

1.1 仓库命名规范

本组织的仓库创建规范分为 3 种情况：

1.1.1. [2位数年份][比赛大写简写]_[机器人名(如有)]_[包名] - 针对 某年、某比赛、某机器人 的一次性仓库

样例：

  • 26RC_R2_ws - 2026年 Robocon 主赛 R2 机器人主 Workspace 仓库
  • 26RC_R2_kfs_tracker - 2026年 Robocon 主赛 R2 机器人 KFS 视觉跟踪仓库，注意如果是 ROS Package 的话，package.xml 中的 <name> 标签需要与仓库中包名部分保持一致，包名单词间也使用下划线 _ 分隔
  • 26RC_R1_arm_controller - 2026年 Robocon 主赛 R1 机械臂控制器仓库，包名同理
  • 26RC_interfaces - 2026年 Robocon 主赛通用接口仓库，如果是同场比赛跨机器人使用的仓库，命名可以省略机器人部分
  • 25RM_raw_rm_vision - 2025年 RoboMaster 联盟赛 RM 视觉主仓库，包名同理

1.1.2. aim-[4位学年名]-[包名] - 针对 AIM 战队内部的 非赛用、单学年/长期 仓库

样例：

  • aim-2526-py-coursework - 2025-2026 学年 AIM 战队 Python 国庆考核仓库，包名单词间分隔使用 dash -，注意与赛用仓库不同
  • aim-2526-navigation-final-assessment - 2025-2026 学年 AIM 导航组期末考核仓库，包名单词间分隔同理使用 dash -
  • aim-rookie-courses - Lectures designed for RM rookies & freshmen @ unnc-aim，主要用于存放新生课程资料，长期使用的仓库可以省略学年部分

1.1.3. BrandingRepo/package_name - 对外开放/万能/可复用的 完整项目/轮子仓库/lib

样例：

  • RoboMark - 单独包含 Branding 成分的仓库可以省略 aim-xxxx 前缀，直接使用仓库名即可
  • Camera2Topic - An ROS2 package that converts usb camera/realsense to topics
  • ros2_hik_camera - 海康相机 ROS2 驱动仓库

1.1.4. 赛用 Workspace 内组织子模块时去掉比赛前缀

比赛 Workspace 仓库（后缀 _ws，如 26RC_R2_ws）会把多个比赛仓库作为 git submodule 放在 src/ 下。当被添加的仓库带比赛前缀（26RC_ / 26RC_R2_ 等）时，子模块目录名要 去掉前缀——前缀在工作区名中已体现，无需重复：

# 在 26RC_R2_ws/ 内
git submodule add https://github.com/unnc-aim/26RC_R2_arm_controller.git src/arm_controller
# 而不是 src/26RC_R2_arm_controller
  • 去掉前缀后的目录名必须与 ROS 包 package.xml 中的 <name> 一致；比赛前缀只出现在 GitHub 仓库名里。
  • 无比赛前缀的可复用包（如 Camera2Topic、ros2_hik_camera）保持原名直接放入 src/。
  • 完整规则、示例表与已知反例见 skill：.agent/skills/aim-common-rules/references/workspace-organization.md。

仓库命名完整规范（三种模式、决策树、大小写 / 分隔符对照、已知反例）见 skill：.agent/skills/aim-common-rules/references/repo-naming.md。

1.2 仓库内容规范

  • 所有仓库内 不允许 出现任何编译文件，请妥善使用 .gitignore 文件来排除项目下所有潜在的编译文件
  • 所有仓库主分支统一命名为 main，禁止使用 master 命名主分支

1.3 仓库进度管理

所有已经处于稳态的仓库禁止直接向 main 分支直接提交修改，请创建分支并使用 Pull request 来提交修改。

分支命名规范需要符合以下要求：

  • 分支名统一使用小写字母，单词间使用 dash - 分隔
  • 如果是修复 bug 的分支，使用 fix/[小写负责人用户名]- 开头，，按照 bug 的名字命名，如 fix/hnrobert-target-tracking；如果有多人参与可以省略用户名，如 fix/arm-control-error
  • 新增功能按照功能的名字命名，使用 feature/[小写负责人用户名]- 开头，如 feature/gentle-lijie-lidar-mapping；如果有多人参与可以省略用户名，如 feature/arm-control 等
  • 其他的参考 commit message 规范，也按照修改部分的名字命名，如 refactor/gimbal-control、docs/chassis-control 等

保证所有功能稳定可靠的才可 merge 到 main 分支

阶段性成果标记使用 tag, tag 命名规范为三位数字，第一位为大版本号，第二位为小版本号，第三位为修订号，如 v1.0.0、v1.0.1、v1.1.0 等。

1.4 Git Message Regulation

  1. 推荐的 Git 提交信息格式

    基础格式：

    <type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

    示例：

    feat(user-auth): add login functionality

Implemented a login system with JWT authentication.
Updated the user model and added necessary endpoints.

BREAKING CHANGE: Updated the user model to include an additional "authToken" field.

  2. 格式详解

    1. <type> (提交类型)：
      • 用于标识提交的目的，常见类型包括：
        • feat：新增功能。
        • fix：修复 Bug。
        • docs：仅文档变更。
        • style：代码格式调整（不影响功能，例如空格、格式化）。
        • refactor：代码重构（不包括 Bug 修复或功能添加）。
        • test：添加或修改测试。
        • chore：其他杂项，例如更新构建工具、配置文件。
        • perf：性能优化。
        • ci：持续集成相关修改。
        • build：构建系统或外部依赖的变更。
    2. <scope> (影响范围)：
      • 可选，用于说明变更的模块或范围，例如：
        • user-auth
        • api
        • ui
      • 如果不需要特别说明，可以省略。
    3. <subject> (简短描述)：
      • 对提交的简要描述，不超过 50 字符。
      • 使用 祈使句（如“Add” 而不是“Added”）。
      • 第一个字母小写，结尾不要加标点。
    4. <body> (详细描述)：
      • 可选，用于解释提交的详细内容。
      • 换行适当控制在 72 字符以内，保持易读性。
      • 包含原因、实现方式、以及与上下文相关的信息。
    5. <footer> (备注信息)：
      • BREAKING CHANGE：如果变更会导致不兼容，说明影响范围和解决方案。
      • Issues：引用相关问题或任务编号，例如 Closes #123 或 Refs #456。

分支命名与 commit message 完整规范（字段说明、type 取值、PR 流程）见 skill：.agent/skills/aim-common-rules/references/git-workflow.md。

1.5 代码规范

请务必在提交代码前对代码进行格式化，具体规范请参考以下文档

1.6 Visual Studio Code 系插件推荐

战队推荐统一安装以下 VS Code 系插件（括号内为扩展 ID）：

  • ms-python.python # Python 主扩展（语言服务由 Pylance 提供）
  • ms-python.vscode-pylance # 类型检查 / 智能提示，配置见 python-formatting.md §6
  • ms-python.autopep8 # Python 格式化
  • isort 排序已内置于 Python 扩展的「Organize Imports」，无需单独安装
  • llvm-vs-code-extensions.vscode-clangd # C++ 语言服务，自动读取 .clang-format / .clang-tidy
  • streetsidesoftware.code-spell-checker # 拼写检查（美式英语）
  • editorconfig.editorconfig # 统一缩进 / 换行风格

代码、注释、commit message 一律使用美式英语（如 color / behavior / optimize，而非 colour / behaviour / optimise）。cSpell 报错的词先核对：若确属正确（战队 / 领域术语、缩写、专有名词，且为美式英语拼写），加入 .vscode/settings.json 的 cSpell.words 数组学习，不要直接忽略或放过真正的拼写错误。

现成模板见 skill：.agent/skills/aim-common-rules/assets/.vscode/extensions.json（插件推荐）与 .agent/skills/aim-common-rules/assets/.vscode/settings.json（含 cSpell.words、format-on-save、Pylance）——放到仓库根目录 .vscode/ 即可。

2. Agentic Skill (aim-common-rules)

上述全部规范已封装为一个 agentic skill：aim-common-rules，位于 unnc-aim/aim-common-agentic-skills 的 .agent/skills/aim-common-rules/。安装后，Agent 会在创建 / 命名仓库、核对 ROS2 包名、新建分支、撰写 commit message、格式化 Python / C++ 代码等场景自动调用本规范。

2.1 安装

用 skills CLI（npx skills，会自动识别并安装到你本地的所有 agent——Claude Code / Cursor / Codex 等），整个 skill 目录（SKILL.md + references/ + assets/）会一并装好：

npx skills add unnc-aim/aim-common-agentic-skills --skill aim-common-rules -g
  • -g 全局（所有项目，推荐）；不加 -g 则装到当前项目 .agents/skills/。
  • 不使用 AI 的成员：无需安装 skill，直接读 references/*.md、把 assets/ 里的规则文件拷到仓库根目录即可。

2.2 在 Claude Code 中使用

全局安装后无需任何额外配置：skill 会根据其描述在相关场景自动触发；也可在对话中手动调用 /aim-common-rules。

2.3 更新

规范更新后，执行 npx skills update 即可同步到最新版本。

2.4 在 Cursor / Cline 等其他工具中使用

npx skills add 会自动把 skill 装到这些工具（Cursor / Codex 等读取 .agents/skills/，Claude Code 走符号链接），无需额外配置。skill 自带的格式化规则文件（assets/ 下的 .clang-format / .clang-tidy / setup.cfg）需要拷到你的仓库根目录，编辑器 / clang-format / autopep8 / CI 才会自动读取；若仓库已有同名文件（如 ROS 的 setup.cfg），请手动合并而非覆盖。

规范全文也可直接在 GitHub 阅读：.agent/skills/aim-common-rules/references（仓库命名 / Git 流程 / Python / C++ 格式化）。

Pinned Loading

  1. aim-rookie-courses aim-rookie-courses Public

    Lectures designed for RM rookies & freshmen @ unnc-aim

    Jupyter Notebook 20 7

Repositories

Showing 10 of 41 repositories
View all repositories

Top languages

Loading…

Most used topics

Loading…