AIC-segmentation

Imported from zsyyywm/AIC-segmentation (AGENTS.md). Install upstream with npx skills add zsyyywm/AIC-segmentation. Copyright stays with the author.

AIC 项目约束与协作约定

本文件供全部成员及Codex任务遵循，只维护底线与协作规则。项目导航见根 README.md；公共环境与实验后处理操作见 docs/setup.md；各版本训练命令见对应 version_notes.md；模型见 docs/model.md；数据见 docs/data_spec.md；成员开发与版本关系见 docs/development.md。

1. 项目与事实依据

• 本地唯一根目录：%USERPROFILE%/Desktop/junior1nd/AIC（Windows用户目录下的固定项目位置，执行前核对实际绝对路径），不得使用Documents/ChatGPT下的同名目录。
• 服务器标准根目录：/root/autodl-tmp/AIC，实际run路径以服务器输出为准。
• 官方基准：材料/无人机低空航拍图像语义分割-2.pdf。聊天、说明与官方依据冲突时立即报告，不自行放宽规则。
• 信息优先级：官方通知/赛题规则 → 官方数据及Label.txt → 项目实测证据 → 实际配置与日志 → 团队未验证方案 → 外部经验。
• 新官方通知须保留来源与日期；无法核验的事实标记“待确认”。

2. 需求澄清底线

在不清楚用户真实想法、工作范围或预期结果时，必须先询问并澄清，不得擅自修改代码和文件。已经明确且获认可的范围可以直接执行，无需对每次修改重复询问。

• 需求不清时报告当前理解、拟调整内容、影响范围和待决定问题。
• 实施中遇到范围变化或新的重要歧义，先停在该边界并询问。
• 不借整理文档、改名或排错擅自改变模型、预算、数据、入口或删除历史成果。
• 纯读取、审查、方案分析不需要逐项许可。

3. 赛事硬边界

• 训练只使用赛事官方数据；可微调公开学术预训练模型，禁止外部训练数据、商业闭源模型与API。
• 最终预测来自一个模型，禁止多模型集成。
• 项目保守采用公开分类主干预训练，不加载ADE20K等外部语义分割checkpoint。
• 官方测试集仅推理提交，不训练、生成训练伪标签、自训练、拟合阈值或自行标注。改变此约束必须有官方书面允许依据。
• 禁止泄露、传播赛事数据、非赛事商业使用、测试泄漏及抄袭。
• 必须能仅使用官方数据复现性能；后续按官方要求交付代码、环境/Docker、复现说明与技术方案。
• 当前PDF未给出具体初赛基线门槛；虽说明mIoU>0，官方仍可认定低于其公布基线的提交无效。不得把用户提供的榜单情报当官方门槛。
• 推理大小和时间虽无明确数值硬限，仍须合理；每项策略以赛题及最新通知为准。

4. 数据与评测不可变项

• 官方Ignore ID0必须排除；当前内部编号0..7对应官方1..8，Ignore转换255。不能把Ignore当背景。
• mIoU口径、类别顺序和标签映射改变前必须核验依据并做逐像素小样本验证。具体规范只维护在 docs/data_spec.md。
• 固定验证集不得参与该开发实验训练，不能仅靠训练loss推算验证精度。
• data中的图片为只读，当前硬链接不得覆盖、重新编码或改写。
• 提交前自动检查数量、同名对应、1024尺寸、uint8灰度PNG、color type及官方标签范围；不能仅凭ZIP生成成功认为合规。

5. 代码版本与成员协作

• code/baseline_v1 保留原始历史基线；v0数据增强与损失阶段已结束，code/v0 归档 v02—v05 的四组独立实验；当前进入v1结构改进阶段，code/v1 保留v04等价控制（U0），候选实现分别在 code/v1_m0_mask2former、code/v1_up_uper_proto、code/v1_mp_mask2former_proto。后续新模型改进在独立版本目录中进行，不覆盖历史和控制单元。
• 每版维护 version_notes.md，只记录该版本情况、配置、改动与结果；创建目录、开发步骤和提交方式统一维护在 docs/development.md。
• 共享 code/mmsegmentation、data和根目录tools，不重复复制或任意修改官方框架。
• 项目自编文档只允许根目录一个README；版本文件夹使用version_notes，专题文档按职责命名。第三方框架原始README/LICENSE保持原样。
• 不同任务不要并发修改同一文件。开始前读当前内容及可用Git状态；没有项目Git记录时不得虚构提交号。
• 保留其他成员修改，不能擅自回滚、格式化、清空或删除产物。
• 具体分工由用户决定，不在项目文档预设固定三人角色。成员开发独立版本并提交分支，由用户选择审核、是否合并及最终训练。

5.1 可摘取版本契约

• 目标协作场景是：同一台服务器已预先放置标准AIC根目录、官方数据、共享MMSeg和根公共工具；不同成员分时使用该服务器训练各自版本。成员交付或更新实验时，只需要上传自己负责的 code/<版本名>/，不能要求同时覆盖根目录或其他版本。
• code/<版本名>/ 必须是可摘取的版本单元：将整个目录放入服务器标准AIC项目的 code/ 下后，可以使用该目录自己的配置、组件、依赖声明、训练入口和底层预测入口，不依赖另一个实验版本的文件。
• code/v0 的四个历史配置各自保留实验名、损失组合和run身份；code/v1 不从v0继承配置或导入其组件。两阶段虽使用同名 aicseg 包，也必须在不同Python进程中加载。
• “可摘取”不等于脱离标准服务器项目独立运行。允许且仅允许依赖：同级 code/mmsegmentation、根 data/、根公共 tools/ 以及文档声明的Python环境；版本说明必须写清这些前提。
• 每个可训练版本至少保留 configs/、aicseg/、tools/、requirements.txt 和 version_notes.md。配置继承所需文件必须在同一版本目录内，不能跨版本继承。
• 算法训练与底层推理不能暗中依赖未随版本目录交付的本地脚本、绝对路径、其他成员工作区、另一个版本目录或服务器临时文件。新依赖写入本版本 requirements.txt，新组件及注册代码放入本版本 aicseg/。
• 普通模型改进不得修改共享 code/mmsegmentation、根工具、根文档或数据才能运行。确有不可避免的共享接口改动时，先停止在该边界并报告，由用户决定是否作为单独的全局变更；此时不能声称仍然“只需上传版本文件夹”。
• 各版本必须使用独立且明确的 experiment_name 和run目录，不能复用或覆盖其他成员的run。不同成员虽分时使用GPU，启动前仍须检查GPU、tmux和目标run状态，防止前一任务尚未结束就启动下一任务。
• 每个训练进程只加载当前版本的同名 aicseg 包；不得在同一Python进程混用多个版本目录，避免注册表和模块缓存串版本。
• 摘取或交付版本目录时不包含 runs/、权重、预测图、提交ZIP、缓存、数据或重复的MMSeg框架；这些属于实验产物或共享资源。
• code/postprocess_* 属于独立后处理组件，不冒充模型版本。它必须通过显式的run、checkpoint和解析配置接入最终候选，默认不改变各模型原有推理行为。

6. 实验执行与证据

• 长训练前报告命令、GPU、预算、显存设置、预计时长与输出目录；未经明确授权不得启动超过300iter或预计2小时的训练。
• smoke通过后才开始正式训练，不从smoke自动续成正式基线。
• 一次改变一个主要因素；跨模型比较以曝光量、更新次数和评测规则为准，不机械对齐iter。
• 每次新训练有独立run，保留配置快照、命令、种子、预训练、环境、日志、每类IoU、耗时与权重。
• result记录按日期追加，不覆盖同版本不同预算、种子或重复训练的历史。
• 平台分数须绑定实际run、checkpoint、配置、ZIP及哈希；只有文件名时不能反推完整配置。
• 区分“代码已实现”“合成/单元测试通过”“服务器链路已验证”“正式成绩已产生”。未执行不得宣称无错误或性能保证。
• 外部数据集指标不直接等同本赛题分数；单次本地提升不等于统计显著或官方测试提升。

7. 汇报与维护

完成任务简要汇报：改了什么文件、对应run/命令、关键结果、验证证据、未解决问题和需要统筹决定的事项。

官方规则、数据/划分/映射、主线、入口或成绩发生变化时，更新其唯一责任文档和必要引用。规则在本文件，公共环境及实验后处理操作在setup，各版本训练命令与版本差异在version_notes，逐次指标在result；不复制多个相互冲突的教程。

7.1 文档职责

• 根 docs/setup.md 是全局复现与训练后操作文档，只维护所有版本共用的数据核验、环境复现、run分析、实验比较、测试推理、格式检查和打包命令；不得放置任一版本的smoke、正式训练、恢复训练或训练监控命令。
• 每个版本的 version_notes.md 是该版本训练信息的唯一入口，集中记录版本来源、改动、配置、预算、变量、smoke、正式训练、恢复、监控、验证状态和结果摘要。
• 根 tools/ 提供面向已完成run的通用分析、比较、测试和打包入口；版本 tools/ 提供该版本的训练和底层推理实现。公共工具不能靠硬编码版本名工作。
• 根 README.md 只承担项目导航和当前进度快照，不复制setup、version_notes或result的详细内容。

7.2 GitHub发布

• 日常本地修改不要求反复改README。用户明确准备上传、推送或发布GitHub版本时，发布前必须重新读取实际代码、文档、run和Git状态，更新根 README.md 的当前版本、完成程度、验证状态和推荐入口；用户会在发布时提醒，不得自行推送。
• README中的“已实现”“smoke通过”“正式训练完成”“平台成绩”必须分别有对应证据，不能把计划、代码完成或本地合成测试写成已取得实验结果。
• 发布前检查暂存内容，禁止上传赛事数据、权重、run、预测图、提交包、账号密钥、缓存和机器私有路径；确认嵌套仓库或子模块策略后再处理 code/mmsegmentation，不得无声删除其Git信息或生成不可克隆的假子模块。
• 没有根Git记录时不得虚构分支、提交号或远端状态。首次建仓、选择远端、处理MMSeg子模块及实际push均由用户决定或明确授权。

8. 本地与服务器结果协作

• 服务器run是已执行实验的事实来源。Codex连接服务器后默认只读检查现有run、日志、解析配置、环境记录、指标、权重和哈希；未经明确请求不移动、覆盖、删除或续训服务器产物。
• 读取服务器结果时使用实际绝对run路径，不按文件名或当前默认配置反推历史实验。先同步或读取manifest、summary、配置和日志，只有分析、推理或归档确实需要时才传输大权重。
• 本地 result.md 只根据服务器或平台的可核验证据追加；记录服务器run、checkpoint、配置、提交ZIP及哈希之间的绑定，保留服务器原始文件不变。
• 本地代码与服务器run对应关系不清、服务器存在未同步修改或同名目录含多个实验时，先停止归因并报告差异，不能强行把成绩绑定到某个版本。
• v02—v05 的本地历史产物归档在被Git忽略的 runs/archives/v0/；原解析配置、manifest、日志及其中旧绝对路径保持原样。v03诊断保留在 runs/diagnostics/20260930_barren/。目录迁移不生成新实验成绩，也不能把v03真实混淆矩阵当成v04结果。

8.1 从GitHub更新服务器

• GitHub仓库建立后，以用户指定的远端分支作为服务器代码更新来源。服务器旧代码允许被新版替换，但更新动作必须由用户明确发起，不能因为本地完成修改就自动同步服务器。
• 全量更新服务器时永久保留且不得覆盖：/root/autodl-tmp/AIC/data/ 与 code/baseline_v1/runs/。用户已明确其余旧版本代码和产物可以删除或替换；执行前仍须检查并停止相关训练、tmux和推理进程。
• 更新前先解析并核对服务器绝对路径，确认保留目录真实存在，记录baseline_v1 run清单与关键权重哈希；不得对未核验路径执行递归删除、移动或覆盖。
• 推荐使用“保留目录移出工作区或创建可恢复备份 → 部署干净仓库 → 恢复data与baseline_v1 runs → 执行完整性检查”的流程，不能用一次未经校验的递归覆盖赌保留目录不会受影响。
• 更新后依次检查MMSeg子模块、版本依赖、数据完整性、自定义模块导入和baseline_v1 run可读性；未通过前不启动smoke或正式训练。