labpaths 0.4.0

Cross-project / cross-machine path resolution: sync the code, keep outputs local, zero path edits.

labpaths

跨项目 / 跨机器的统一路径解析。代码靠同步统一，产出靠不同步的机器配置区分， 两者正交，换机器不用改任何地址参数。

为什么

同一个项目在多台机器（如 Mac 写代码、Windows 跑）之间，绝对路径各不相同。 把地址写死在每个脚本顶部，换机就要改 N 个文件、迟早出错。labpaths 把 “逻辑”和“每台机器/每个项目的具体值”彻底分开：

• 结构路径（原始数据、产出根）：从 __file__ 自动派生，跨机零改动。
• 机器专属值（产出盘、项目外数据）：只写在一个不随项目同步的机器配置里。
• 可变构件（多个候选权重/先验）：resolve() 让用户灵活自定义，绝对/相对都通。

安装（每台机器一次）

git clone <this-repo> ~/lab-tools/labpaths
pip install -e ~/lab-tools/labpaths

装好后任意项目、任意脚本里 from labpaths import load 直接可用，无需再往 sys.path 塞路径。

两层配置

机器层 ~/labpaths.json（每台机器一份，所有项目共用，不随项目同步）：

{
  "output_base": "C:/2026H",
  "extras": { "spectra_lib": "C:/Users/you/usgs_v7" }
}

首次运行自动生成模板；也可 python -m labpaths --init。

项目层 projectroot.json（放项目根，随项目同步，只含名字、无绝对路径）：

{ "name": "myproj", "raw_dir": "60_data", "out": "SHIYAN_DATA" }

脚本里怎么用

from labpaths import load
P = load(__file__)

raw   = P.data / "rasters" / "x.tif"       # 原始数据（随项目）
out   = P.out  / "runs" / "expA"           # 产出（本地，不同步）
usgs  = P.extra("spectra_lib") / "lib"     # 项目外数据（机器 extras）
ckpt  = P.resolve(user_value, base=P.out)  # 灵活权重：绝对原样/相对挂产出根/空->None
P.ensure(out)                              # 写入前建目录

铁律（配合同步）

同步区里只写“名字”（P.out/P.data/SHIYAN_DATA 这种），真实盘符只写进不同步的 ~/labpaths.json。 于是同一份代码在 Mac / Windows 各自解析成各自的绝对路径。

新项目上手

1. 项目根跑 python -m labpaths --init-project：生成 projectroot.json + AGENTS.md（给其他 agent 的路径说明）。
2. pip install -e 本包（若该机器还没装）。
3. 脚本里 from labpaths import load; P = load(__file__)，路径全走 P.*。
4. 跑 tests/test_no_abs_paths.py 守住“禁绝对路径”。

配套的 setup-paths skill 可把 2~4 步在新项目里自动做掉。