Imported from deathend110/SAR_Azimuth_Range_Upsample (AGENTS.md). Install upstream with npx skills add deathend110/SAR_Azimuth_Range_Upsample. Copyright stays with the author.

仓库协作规则

本文件用于约束 Codex 在本仓库中的默认协作方式。

代码编写规则

1. 在用户没有明确要求“写代码”“修改代码”“实现功能”“修复问题”之前，默认不主动编写或修改代码。
2. 当确实需要输出代码时，应尽量附带合理的中文注释。

注释要求

1. 中文注释应说明关键步骤、核心变量或不直观的设计意图。
2. 不添加无意义的逐行注释，避免注释噪声。
3. 新增或修改的代码，优先保持注释风格一致。

执行约定

1. 在开始代码修改前，先确认用户已明确提出代码编写或修改需求。
2. 如果当前任务主要是分析、解释、实验设计或结果讨论，则优先提供分析结论，而不是直接写代码。
3. 本仓库默认不使用 git worktree；所有修改直接在当前工作区内完成。
4. 每次完成代码或文档改动后，优先对应提交一次 git commit，并用明确的中文说明本次改动内容。

编码约定

1. 阅读文件用UTF-8编码

论文写作约定

1. 不要过分兜底，不要强调什么什么没做到，什么什么不能说，论文写作中我们阐述我们可以说的即可

已知问题与防回归规则

本节记录本工作区已经实际遇到的问题。新增实验或修改公共流程时，应优先检查这些位置，避免重复引入同类 bug。

1. Git 与工作区

1. 当前仓库默认只有主工作区，不创建额外 git worktree。修改前后均检查 git worktree list 和 git status。
2. 不覆盖或清理用户已有改动；提交时只包含本次任务涉及的文件。
3. 实验输出、checkpoint 和绘图结果不应因为代码提交而被误删。涉及删除时必须先确认精确路径和恢复方式。

2. MATLAB table 类型与行数

1. 表格累加器必须初始化为 table()，不能用 [] 与 table 纵向拼接。历史问题见提交 45580e0。
2. 表变量选择不要使用由 string 标量组成的元胞数组：
   • 正确：T(:, ["A", "B"])
   • 正确：T(:, {'A', 'B'})
   • 错误：T(:, {"A", "B"}) 历史问题见提交 d3ed49c。
3. 构造 table 时，各列必须具有相同行数。组名、参数和常量要按样本数使用 repmat 展开，不能只提供组数长度。历史问题见提交 f66bb98。
4. 数值和 string 混合组表时，优先分别预分配有类型的列后调用 table，或明确使用 cell2table，不要直接拼接异构数组。历史问题见提交 6e257eb。
5. 写出 CSV/MAT 前检查 height、变量名、样本数和非有限值；完成提示应放在所有文件成功保存之后。

3. 数组方向、字符串与绘图

1. 配对指标、掩膜和索引进入统计函数前统一为相同方向，优先显式使用 (:) 或转置。历史上行向量与列向量混用曾导致 Wilcoxon 索引越界，见提交 7d30889。
2. string 或分类标量扩展使用 repmat，不要使用“标量乘 ones”；绘图坐标显式构造为 1×N 或 N×1，避免隐式维度不匹配。历史问题见提交 b714847、f426a0e、8adf8aa。
3. cell 中存放 string 标量时，先统一转换为 string 数组，再用 == 比较；不要混用 strcmp、char cell 和 string cell。
4. 对可能为空的筛选结果，赋值或绘图前先用 any(mask) 或 isempty 检查。
5. 循环绘图前先汇总数据，再一次性创建曲线和图例，避免重复 legend 条目和重复计算。
6. sprintf、title 和多行标题之间不要混合不兼容的 char/string/cell 形状；复杂标题应由独立小函数构造。历史问题见提交 9e70998。

4. 统计检验

1. MATLAB signrank 的第一个返回值是 p-value。需要 p-value 时使用 p = signrank(...)，不要写成 [~, p] = signrank(...)。历史问题见提交 acb12fc。
2. 配对检验前必须断言两组数据使用相同样本清单、顺序和长度。
3. 参数选择只使用校准集；测试集不得参与阈值参数搜索。若需要在多个分配中选“最佳组”，应明确记录选择发生在哪个数据集上，避免把选择偏差误当成显著性。

5. SAR 成像与阈值流程

1. 距离、方位和双向上采样结果必须使用同一套 GT、ROI 和归一化协议。历史上各分支独立 min-max 处理曾造成能量尺度不一致和错误结论。
2. Speckle 不是普通加性白噪声；分析和实现时区分复回波、幅度图和强度图。
3. RT/SFT 阈值的距离和方位方向必须明确：
   • 距离频率作用于 fast-time 列向坐标；
   • 方位频率作用于 slow-time 行向坐标；
   • 二维阈值采用两方向相位相加后取复指数，不能把两个复阈值直接相加。
4. 1-bit 量化前后检查信号与阈值尺寸完全一致，并保持实部、虚部符号规则一致。
5. 结构保持不能只看 PSNR/SSIM，还应检查亮散射点、边缘和细纹理是否出现明显损伤。

6. 小数倍率与浮点精度

1. 小数倍率上采样后的尺寸使用 round(q * N)。后续采样率、时间轴、裁剪尺寸和 checkpoint 签名必须使用同一倍率定义。

2. 对理论上应为整数的表达式进行近整数吸附。例如 p = sqrt(3) 或 sqrt(8) 时，p^2 会得到 2.9999999999999996 或 8.0000000000000018。应使用：

   p2 = p ^ 2;
   if abs(p2 - round(p2)) < 1e-12
       p2 = round(p2);
   end

3. 小数倍率不能直接用于 %d 构造唯一文件名。checkpoint 和组结果应使用稳定的 ASCII FileKey，数值倍率作为签名字段保存。

4. 显示名称、CSV 中的倍率、实际成像倍率和 checkpoint 签名必须一致，不能只把标签四舍五入而保留不同的内部语义。

7. Checkpoint 与长时间实验

1. 长时间搜索必须按样本或组保存 checkpoint，并支持从 completed_samples + 1 恢复。
2. checkpoint 签名至少包含：实验名、随机种子、样本 ID、倍率、参数网格、初相位、距离/方位带宽和测试索引。
3. 恢复时必须使用 isequaln 核验完整签名。配置不一致时直接报错，不能静默复用旧结果。
4. 参数搜索完成后再锁定最优参数评价测试集；不得从未完成的搜索 cube 中选最优值。
5. 命令超时不代表 MATLAB 子进程已经退出。中止实验后应检查进程命令行，只关闭本次启动的 matlab -batch PID，保留用户原有 MATLAB 会话。
6. Parallel Computing Toolbox 许可证可能签出失败。允许在明确提示后将 parfor 的 worker 数设为 0 串行运行，搜索协议和 checkpoint 签名不得随并行度改变。
7. 未经用户明确要求，不主动启动完整耗时搜索；代码完成后默认只做静态检查和必要的轻量验证。
8. 实验代码的“实现授权”与“运行授权”相互独立。用户要求编写、修改或完善实验代码， 不代表授权 Codex 启动 MATLAB 完整实验；只有用户明确要求“由 Codex 运行/启动实验” 时才可启动。否则只执行静态检查和必要的轻量测试。
9. 若 Codex 启动的 MATLAB 实验需要停止，必须通过命令行和父子进程关系精确识别本次 进程树，只终止 Codex 本次启动的进程，保留用户已有 MATLAB 会话和语言服务器。

8. 输出目录与文档

1. 保存 CSV、MAT、PNG、PDF 或 metadata 前，先显式创建输出目录。历史上曾出现输出目录未创建导致保存失败。
2. metadata 应记录脚本名、关键配置、样本划分和参数选择规则，便于结果追溯。
3. 中文 MATLAB、Markdown 和 LaTeX 文件统一按 UTF-8 读取和修改。
4. 中文 LaTeX 文稿应使用与中文字体配置兼容的编译链；不要在未确认环境时替换编译引擎或字体设置。

9. 提交前最小检查

1. MATLAB 文件至少运行 checkcode 或等价静态检查；用户明确要求不运行测试时，不启动实验或完整测试套件。
2. 检查是否再次出现 table string-cell 索引、混合类型拼表、行列方向不一致和错误的 signrank 返回值接收方式。
3. 执行 git diff --check，确认没有意外文件、编码问题和无关改动。
4. 完成代码或文档修改后，按任务粒度创建中文 Git commit。