88 lines
4.4 KiB
Markdown
88 lines
4.4 KiB
Markdown
# Karpathy原则
|
|
|
|
## 先理解再修改
|
|
|
|
- 检查实际实现、调用链和现有约束，不凭名称猜测行为。
|
|
- 明确必要假设；遇到会显著改变结果的歧义时先说明。
|
|
|
|
## 保持简单
|
|
|
|
- 使用满足当前需求的最小方案。
|
|
- 不增加推测性功能、无必要抽象或配置。
|
|
|
|
## 精确修改
|
|
|
|
- 只触碰与当前任务直接相关的代码，保留既有风格和无关改动。
|
|
- 清理由本次修改产生的废弃代码，不顺便清理原有无关代码。
|
|
|
|
## 面向验证
|
|
|
|
- 修改前明确可观察的成功标准，修改后运行相关检查。
|
|
- 如实报告警告、限制和未验证项。
|
|
|
|
# MyParking项目规则
|
|
|
|
## 项目定位与事实来源
|
|
|
|
- `MyParking`是当前正式开发的停车机器人项目，结论优先依据本目录中的当前代码和实际运行配置。
|
|
- 工作区中的旧版停车机器人、MDCS源码和轨迹规划项目只能作为辅助参考，不能覆盖当前实现所表达的事实。
|
|
- 不能从代码、配置或用户提供资料确认的信息统一标记为“待确认”，不得自行补全或编造。
|
|
- 修改代码后检查实际diff，并运行与改动风险相匹配的最相关编译或测试；不主动修改任务范围之外的代码。
|
|
|
|
## 代码边界
|
|
|
|
- `CommonUsage-MultiVehicleSync`是独立的通用底盘库，不反向依赖`Shared`、M层或C层。
|
|
- `Shared`只包含M/C共享的数据模型、数学方法和底盘适配代码。
|
|
- `MedullaAdapter`负责M层硬件通信、IO和底盘命令。
|
|
- `MultiWheelC`负责C层动作、控制、实验和数据记录。
|
|
|
|
## 代码规范
|
|
|
|
- 新增或修改的类、结构体和方法使用一句话的`/// <summary>`说明业务用途。
|
|
- 单位、坐标系或正负方向不明确时补充说明，不复述代码字面内容。
|
|
- Shared统一使用SI单位：m、m/s、rad、rad/s。
|
|
- 车体坐标系为X向前、Y向左、逆时针为正；旧接口单位只在边界处转换。
|
|
- 角度归一化、最短角差和度弧度转换统一使用`Shared/Mathematics/AngleMath.cs`，不重复手写。
|
|
- 弧度归一化范围为`[-π, π)`，度归一化范围为`[-180°, 180°)`。
|
|
- 车辆航向可用圆周最短角差；受`[-120°, 120°]`限制的机械舵角误差必须直接使用目标值减实际值。
|
|
|
|
## 控制安全
|
|
|
|
- 未经明确要求，不改变速度或舵角符号、CAN ID、遥控器映射、机械限位和模式切换策略。
|
|
- 修改底盘命令、模式切换或四轮解算时，说明对实际运动的影响。
|
|
- 实车测试采用低速、短距离，并确保可以立即停车。
|
|
|
|
## 构建验证
|
|
|
|
- 修改`CommonUsage-MultiVehicleSync`、`Shared`、`MedullaAdapter`或`MultiWheelC`后，在`MyParking`目录运行：
|
|
|
|
```powershell
|
|
powershell -NoProfile -ExecutionPolicy Bypass -File .\build-and-package.ps1
|
|
```
|
|
|
|
- Release构建在命令末尾追加`-Configuration Release`。
|
|
- 报告各项目的警告和错误，并确认M/C部署包使用同一份`CommonUsage.dll`。
|
|
- 不直接编辑`bin`、`obj`、`build`和`output`中的产物。
|
|
- 不手工覆盖`ref/CommonUsage.dll`，由构建脚本统一更新。
|
|
|
|
# 项目知识库规则
|
|
|
|
## 按需读取
|
|
|
|
- 默认只读取`docs/INDEX.md`，再根据当前任务选择最相关的知识文档。
|
|
- 严禁在每个任务开始时读取整个`docs/`；初始只读取与任务直接相关的1～2个文档，信息不足时再扩大范围。
|
|
- 当前任务不依赖项目背景或长期知识时，可以不读取`INDEX.md`之外的文档。
|
|
- 同一会话中已经读取且没有变化的知识文档不要重复读取。
|
|
- 除非任务确实涉及旧版实现或MDCS底层，不读取工作区中的参考项目。
|
|
- 优先使用关键词、类名、方法名和文件路径定位代码，不进行无目的的全库扫描。
|
|
- 不扫描`.git`、`bin`、`obj`、`build`、`output`、日志、缓存、编译产物和第三方依赖。
|
|
|
|
## 增量更新
|
|
|
|
- 只有产生了已经确认、长期有效的新知识时，才更新对应文档。
|
|
- 普通代码修改、临时调试、失败尝试和一般问答不需要更新知识库。
|
|
- 每次只读取和更新与当前任务直接相关的文档，采用局部增量修改，不重写无关内容。
|
|
- 不把大段源码、日志、终端输出或聊天记录复制到知识库；使用路径、类型名、方法名和精炼结论。
|
|
- 单纯进度变化只更新`docs/progress.md`中的对应小段。
|
|
- 没有值得长期保存的信息时，不为了形式要求强行更新文档。
|