docs(agents): update agent guidelines and remove memorix references

This commit is contained in:
2026-03-30 16:50:30 +08:00
parent a809803979
commit e544a7e84f
2 changed files with 7 additions and 43 deletions

89
AGENTS.md Normal file
View File

@@ -0,0 +1,89 @@
# Project Spec & Rules
## 代码规范
### Google风格代码
详细参阅https://raw.githubusercontent.com/shendeguize/GooglePythonStyleGuideCN/refs/heads/master/README.md
### 代码编写原则
- 简洁,清晰易懂,最小闭环实现
- 条件或循环分支不能超过三层提前Return以减少分支的出现
- 变量说明注释、条件或循环分支注释完全
- 无需向后兼容,避免添加过多功能
- 非用户要求,不能编写测试代码
- 英文注释,中文文档
- 完成代码编写后在文档的框架不变的情况下更新文档如CLAUDE.md
### 测试编写原则
- 精简、干净、快速
- 核心关键逻辑或算法必须测试
- 需要加载transformer模型进行验证的测试与无需加载模型的测试分离
### 文档更新说明
仅在工程目录变化时,更新此文档的目录说明部分。
如需修改其他部分,请先询问,在进行修改。
## 工程说明
使用UV管理整个工程pytest用于测试justfile用于快捷命令jujutsu用于版本管理。
### 目录说明
**核心模块**
- mini-nav/main.py — CLI 入口 (Typer)
- mini-nav/database.py — LanceDB 单例管理,用于向量存储与检索
- mini-nav/feature_retrieval.py — DINOv2 图像特征提取与检索
**源代码目录 (mini-nav/)**
- mini-nav/configs/ — 配置管理 (Pydantic + YAML)
- mini-nav/commands/ — CLI 命令 (train, benchmark, visualize, generate)
- mini-nav/compressors/ — 特征压缩算法
- hash_compressor.py — 哈希压缩器与训练loss
- pipeline.py — 压缩流水线(整合 DINO 特征提取)
- train.py — 压缩器训练脚本
- mini-nav/data_loading/ — 数据加载与合成
- loader.py — 数据加载器
- insdet_scenes.py — InsDet场景数据集加载
- synthesizer.py — 场景合成器
- mini-nav/utils/ — 工具函数
- feature_extractor.py — 特征提取工具
- sam.py — SAM 2.1 分割工具
- mini-nav/tests/ — pytest 测试集
- mini-nav/benchmarks/ — 基准测试 (recall@k)
- tasks/
- multi_object_retrieval.py — 多目标检索基准任务
- mini-nav/visualizer/ — Dash + Plotly 可视化应用
**数据目录**
- datasets/ — 数据集目录
- outputs/ — 默认输出目录 (数据库、模型权重等)
### Python库
详细可查询pyproject.toml或使用`uv pip list`获取详细的库信息,请基于目前的库实现功能。
如需添加新库,请先询问,用户确认后才能使用`uv add <package>`新增库。
## 版本管理
本项目使用 Jujutsu (jj) 进行版本控制。
- 技能调用: 必须使用 jujutsu 相关工具技能来执行分支、提交、修改describe等操作禁止直接通过 Shell 执行冗长的 Git 兼容指令。
- 描述规范 (jj desc):
- 执行 jj desc 时,首行必须是精简的变更标题。
- 空一行后,仅记录改动的核心业务点。
- 语言使用英文进行描述
- 禁忌: 禁止在 jj 描述中堆砌复杂的算法逻辑或长篇的设计决策。
### 描述示例
```text
refactor(compressors): Simplify module by removing SAM/DINO separation code
- Remove dino_compressor.py and segament_compressor.py
- Rewrite pipeline.py to inline DINO into HashPipeline
- Maintain backward compatibility: SAMHashPipeline alias
- Update tests and benchmark.py
```
### 提交步骤
- 执行`jj diff --no-pager`获取当前所有更改
- 根据更改内容与openspec生成的相关文档进行总结重点在于更改内容及其决策逻辑
- 调用记忆功能如Memorix记忆先前总结的内容
- 遵循描述规范使用jj进行更改的描述
- 执行`jj new`开启一个新的更改