STdomain

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

STdomain / SiDMGF Reproduction — Codex Project Instructions

0. Purpose

本项目是 SiDMGF 论文的自动化科研复现项目。

Codex 在本项目中的职责不是只提供建议、计划、伪代码或示例，而是：

• 实际读取论文和代码；
• 实际检查本地数据；
• 实际检查和配置运行环境；
• 实际运行作者代码；
• 实际实现或修正论文描述方法；
• 实际训练模型；
• 实际计算 ARI / NMI / F1 / SC / DB；
• 实际进行有记录的参数适配；
• 实际生成日志、配置、模型、预测、图表和复现报告。

每次进入本项目后，必须首先完整读取：

REPRODUCTION_TASK.md

REPRODUCTION_TASK.md 是本项目完整的目标、执行规范和质量验收标准。

不得在只输出计划后停止。

1. Fixed Project Root

本项目唯一合法工作根目录：

C:\Users\吴浪\Desktop\STdomain

主要目录：

项目根目录：

C:\Users\吴浪\Desktop\STdomain

用户原始数据：

C:\Users\吴浪\Desktop\STdomain\data

论文：

C:\Users\吴浪\Desktop\STdomain\paper

作者代码：

C:\Users\吴浪\Desktop\STdomain\vendor\SIDMGF

配置：

C:\Users\吴浪\Desktop\STdomain\configs

代码：

C:\Users\吴浪\Desktop\STdomain\src

实验：

C:\Users\吴浪\Desktop\STdomain\runs

报告：

C:\Users\吴浪\Desktop\STdomain\reports

日志：

C:\Users\吴浪\Desktop\STdomain\logs

模型：

C:\Users\吴浪\Desktop\STdomain\models

状态：

C:\Users\吴浪\Desktop\STdomain\state

下载数据：

C:\Users\吴浪\Desktop\STdomain\data_downloads

数据暂存：

C:\Users\吴浪\Desktop\STdomain\data_staging

不得在未经用户明确批准的情况下：

• 删除项目根目录之外的文件；
• 修改项目根目录之外的科研数据；
• 删除或覆盖用户原始数据；
• 修改系统级软件环境；
• 删除已有 Conda 环境。

2. Windows / Unicode Path Rules

Windows 用户名包含中文字符：

吴浪

所有代码必须支持 Unicode 路径。

Python 中：

必须优先使用：

pathlib.Path

不得依赖纯 ASCII 路径假设。

PowerShell 中：

优先使用：

-LiteralPath

路径优先使用单引号：

'C:\Users\吴浪\Desktop\STdomain'

项目开始后必须执行 Unicode 路径读写 smoke test。

如果当前运行环境是 WSL，则对应路径为：

/mnt/c/Users/吴浪/Desktop/STdomain

不得在同一个实验中无记录地混用：

• Windows Python；
• WSL Python；
• Windows Conda；
• WSL Conda。

一旦选择运行平台，应在当前复现轨道中保持一致。

3. Existing Conda Environment

用户本机已有一个 Conda 环境：

sidmgf

这是本项目首选候选环境。

但不得假设它一定可用。

必须首先进行完整环境审计。

环境决策顺序：

1. 检查 sidmgf 是否真实存在；
2. 检查 Python；
3. 检查 PyTorch；
4. 检查 CUDA；
5. 检查 Scanpy；
6. 检查 Squidpy；
7. 检查 AnnData；
8. 检查 sklearn；
9. 检查 igraph；
10. 检查 leidenalg；
11. 检查作者代码实际依赖；
12. 检查 R；
13. 检查 GSVA；
14. 运行最小环境 smoke test。

环境状态必须归类为：

READY

MINOR_FIX_REQUIRED

INCOMPATIBLE

BROKEN

READY

直接使用：

sidmgf

MINOR_FIX_REQUIRED

允许补充少量、安全、不会破坏核心依赖的包。

必须记录所有修改。

INCOMPATIBLE

如果：

• Python 主版本不兼容；
• PyTorch/CUDA 冲突；
• Scanpy/AnnData API 不兼容；
• 作者代码要求明显不同的旧版本；
• 需要大量降级/升级；
• 修复可能破坏用户已有环境；

不得大规模修改 sidmgf。

必须建立新的项目环境。

默认：

sidmgf_repro

BROKEN

如果 sidmgf 本身无法正常运行或环境损坏：

不得删除它。

直接记录问题并创建新的独立环境。

4. Forbidden Environment Operations

未经明确验证和必要性分析，不得执行：

conda env remove -n sidmgf

conda update --all

pip install -U torch

pip install --upgrade -r requirements.txt

不得为了方便而整体升级用户已有环境。

如果需要多个核心依赖发生版本变化：

优先创建：

sidmgf_repro

而不是破坏：

sidmgf

5. Active Environment

最终实际使用的环境必须写入：

state\active_environment.json

后续所有实验必须读取该文件。

不得在后续阶段无记录地改用：

• base；
• 系统 Python；
• 其他 Conda 环境。

推荐优先使用：

conda run -n python ...

从而避免 PowerShell 中 conda activate 未初始化的问题。

6. Data Safety

用户已经将候选数据放在：

C:\Users\吴浪\Desktop\STdomain\data

用户数据必须视为只读原始输入。

不得：

• 删除；
• 覆盖；
• 静默修改；
• 静默重命名；
• 无记录移动。

Codex 必须先检查这些数据。

只有发生以下情况时才允许下载：

• 数据不存在；
• 文件损坏；
• 样本明显不对；
• 数据维度明显不匹配；
• 缺少必要空间坐标；
• 缺少必要 annotation；
• 文件无法正常读取；
• 数据来源无法确认；
• 作者代码明确要求另一版本。

下载数据只能保存到：

data_downloads

解压、转换、中间数据保存到：

data_staging

不得覆盖用户原始数据。

7. Data Validation First

不得仅凭文件名判断数据正确。

必须实际检查：

• 文件可读性；
• SHA-256；
• 表达矩阵维度；
• spot/cell 数；
• gene 数；
• barcode；
• spatial coordinate；
• annotation；
• 标签类别；
• NaN；
• Inf；
• 全零 cell；
• 全零 gene；
• 重复 barcode；
• 坐标和表达矩阵顺序；
• 标签和表达矩阵顺序；
• 样本 ID；
• 平台；
• 物种；
• 组织。

必须生成：

provenance\data_manifest.tsv

provenance\data_checksums.sha256

provenance\dataset_difference_report.tsv

reports\02_local_data_audit.md

8. Paper and Repository

目标论文：

Signal-based spatial domain identification of spatially resolved transcriptomics with multigraph fusion

方法：

SiDMGF

作者仓库：

https://github.com/xkmaxidian/SIDMGF

作者仓库默认保存位置：

vendor\SIDMGF

不得覆盖已有 repository。

如果目录已存在，必须先检查：

• remote；
• branch；
• commit；
• dirty status。

9. Three Reproduction Tracks

必须严格区分三个复现轨道。

Track A — repo_default

严格按照作者开源仓库实际默认实现运行。

包括：

• 作者默认预处理；
• 作者默认图构建；
• 作者默认聚类；
• 作者默认参数；
• 作者默认评价。

输出：

runs\repo_default

Track B — paper_description

按照论文正文和补充材料描述实现。

输出：

runs\paper_description

Track C — paper_target

分析：

• 数据差异；
• 实现差异；
• 聚类差异；
• 图构建差异；
• 软件版本差异；

之后允许进行有限、有记录的数据适配和参数调整。

目标：

尽量达到论文报告指标。

输出：

runs\paper_target

10. Primary Evaluation Principle

有可靠人工标签的数据：

主指标：

ARI

辅助：

NMI

F1

有标签数据的最终复现判定以 ARI 为主。

无可靠人工标签的数据：

不得构造伪 ARI。

主要使用：

SC

DB

其中：

SC 越高越好。

DB 越低越好。

辅助使用：

• 空间连续性；
• 解剖结构；
• marker gene；
• 区域边界；
• isolated node 比例。

11. Label Leakage Prohibition

真实标签不得进入：

• 模型输入；
• GNN；
• 图构建；
• GSVA；
• embedding 学习；
• attention；
• decoder；
• loss；
• gradient；
• optimizer。

可以使用 ARI 评价不同参数。

但如果利用 ARI 选择参数，必须标记：

ARI-guided target matching

不得把这种结果描述成完全盲测性能。

12. Parameter Search Rules

所有参数实验必须保存。

不得只保留最佳结果。

必须记录到：

runs\parameter_search_history.csv

不得：

• 只报告最佳 seed；
• 删除失败实验；
• 删除难聚类 cell；
• 修改 ground truth；
• 缩小评价集合；
• 静默改变标签；
• 用标签参与训练。

13. Implementation Differences

论文和作者仓库可能在以下方面不同：

• clustering；
• Leiden；
• KMeans；
• graph construction；
• K；
• r；
• self loop；
• graph symmetry；
• similarity；
• Scanpy；
• Squidpy；
• GSVA；
• KEGG；
• normalization；
• HVG；
• decoder；
• network dimension；
• lambda；
• seed；
• metric implementation。

必须建立：

provenance\paper_repo_discrepancy.tsv

不得静默忽略差异。

14. Automatic Execution

AUTO_CONTINUE = true

没有阻塞问题时自动进入下一阶段。

不得每一步都询问用户。

普通问题应自行解决，例如：

• pip 依赖；
• conda 依赖；
• import error；
• API 变更；
• Windows 路径；
• 文件名不一致；
• 作者代码相对路径；
• package version；
• deprecated function。

15. When to Stop and Ask

只有出现以下情况才应暂停：

1. 需要删除用户原始数据；
2. 需要覆盖用户原始数据；
3. 需要管理员权限；
4. 需要密码；
5. 需要 API key；
6. 需要付费账户；
7. 出现两个无法根据证据判断的关键数据版本；
8. 数据下载超过资源预算；
9. 训练资源明显超过当前硬件；
10. 科研歧义可能显著改变最终结论。

16. Checkpointing

必须维护：

state\progress.json

state\completed_steps.json

state\failed_steps.json

reports\progress.md

长任务必须支持：

• checkpoint；
• resume；
• retry；
• skip completed；
• independent logs。

不得让整个任务依赖一次 Codex 会话持续存在。

17. Git Rules

开始实质性修改前：

如果当前目录不是 Git repo：

初始化 Git。

不得提交：

data/

runs/

models/

checkpoints/

大文件

Conda environment

密钥

缓存

建议：

每个主要阶段完成后创建 checkpoint commit。

18. Required Final Outputs

最终至少必须存在：

README.md

REPRODUCTION_TASK.md

AGENTS.md

environment\environment.yml

environment\conda_explicit.txt

environment\requirements-lock.txt

environment\package_versions.txt

environment\selected_environment.txt

provenance\repository_commit.txt

provenance\data_manifest.tsv

provenance\data_checksums.sha256

provenance\download_manifest.tsv

provenance\dataset_difference_report.tsv

provenance\paper_repo_discrepancy.tsv

provenance\code_changes.tsv

runs\parameter_search_history.csv

metrics\repo_default_metrics.csv

metrics\paper_description_metrics.csv

metrics\paper_target_metrics.csv

metrics\seed_stability.csv

metrics\runtime_memory.csv

reports\reproduction_report.md

reports\quality_control_report.md

reports\progress.md

state\active_environment.json

state\progress.json

machine_readable_report.json

19. Mandatory Startup Sequence

每次首次开始完整任务时：

1. 阅读 AGENTS.md；
2. 阅读 REPRODUCTION_TASK.md；
3. 确认项目根目录；
4. 检查 Unicode 路径；
5. 检查 Conda；
6. 审计 sidmgf；
7. 决定是否使用 sidmgf 或新建 sidmgf_repro；
8. 写 active_environment.json；
9. 环境 smoke test；
10. 系统资源检查；
11. 本地数据审计；
12. 论文审计；
13. 作者仓库审计；
14. 开始 minimal reproduction。

不得只输出一份计划后停止。

APPNP Innovation Phase Addendum

本项目已经完成主要 SiDMGF 复现阶段，现在进入第二阶段：

Adaptive APPNP-SiDMGF Innovation。

每次开始本阶段工作时，除原有：

REPRODUCTION_TASK.md

外，还必须完整读取：

INNOVATION_APPNP_TASK.md

执行优先级：

1. AGENTS.md 中的数据安全、环境安全和复现审计规则；
2. REPRODUCTION_TASK.md 中已经建立的原始复现规则；
3. INNOVATION_APPNP_TASK.md 中的 APPNP 创新实验规则。

上一阶段复现结果属于冻结基线。

不得覆盖：

runs/repo_default

runs/paper_description

runs/paper_target

以及已经生成的原始 metrics 和 reports。

APPNP 创新实验必须写入独立的：

runs/innovation_appnp

metrics/innovation_appnp

reports/innovation_appnp

figures/innovation_appnp

models/innovation_appnp

configs/innovation_appnp

provenance/innovation_appnp

目录。

本阶段主要研究目标是：

将 SiDMGF 的 dual GCN encoders 替换为 APPNP-based encoders，并开发根据不同空间转录组数据自身的 measurement-quality、gene-coverage 和 graph-topology 特征自动选择传播参数的机制。

主要目标数据是：

具有可靠 Spot/cell-level ground truth、可以计算 ARI 的数据。

主要验收指标：

ARI。

“提高 1%”默认定义为：

absolute ARI gain >= 0.01

相对于上一阶段冻结的 validated SiDMGF baseline。

无标签数据不得用于主要 ARI optimization。

Stereo-seq 已知存在原 SiDMGF dense decoder 显存限制。本创新阶段不得因该问题阻塞主要 labeled-data APPNP 实验，也不得为了 APPNP encoder 创新同时大规模修改 decoder。

必须严格区分：

GCN baseline

fixed APPNP

oracle APPNP

label-free adaptive APPNP。

Oracle APPNP 可以使用 ARI 搜索参数，但只能作为诊断上界。

最终主创新结果必须：

在目标数据进行参数选择时不使用真实 labels。

所有 APPNP 参数搜索、失败实验、seed 和 held-out 结果必须完整保留。

禁止：

• 使用真实标签参与模型训练；
• 将 target ARI 直接作为 adaptive controller 的输入；
• 在 held-out 数据上反复看 ARI 修改 controller；
• 只报告最佳 seed；
• 删除 APPNP 失败的数据集；
• 调整评价 cell set 追求高 ARI；
• 把 clustering retuning 的收益冒充 encoder 收益；
• 把 Oracle APPNP 结果冒充自动自适应结果。

开始创新工作前必须：

1. 读取现有 reproduction report；
2. 锁定 validated GCN baselines；
3. 创建 innovation Git branch；
4. 检查 active Conda environment；
5. 保证原始复现结果不被覆盖；
6. 再开始 APPNP 实现。

没有 INNOVATION_APPNP_TASK.md 中规定的阻塞条件时：

自动继续执行，不要每一步询问用户。