diff --git a/.vscode/launch.json b/.vscode/launch.json
new file mode 100644
index 0000000..1ffade3
--- /dev/null
+++ b/.vscode/launch.json
@@ -0,0 +1,26 @@
+{
+    // VSCode 调试配置。前提：本地环境已 `pip install -e .`（见 README/CLAUDE.md），
+    // 且右下角解释器已选 ars-opd 环境。cwd 固定为仓库根：脚本里的相对路径
+    // （data/...、outputs/...）都以仓库根为基准。
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "调试当前文件",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal",
+            "cwd": "${workspaceFolder}",
+            "justMyCode": false
+        },
+        {
+            "name": "teacher 批量生成（1k 子集）",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${workspaceFolder}/scripts/generate_teacher_completions.py",
+            "console": "integratedTerminal",
+            "cwd": "${workspaceFolder}",
+            "justMyCode": false
+        }
+    ]
+}
diff --git a/CLAUDE.md b/CLAUDE.md
index d53e995..935028c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -34,6 +34,7 @@
 ```bash
 conda activate ars-opd && pytest tests/ -x -q     # 单元测试（本地 CPU）
 conda activate ars-opd && ruff check ars_opd/ --fix && ruff format ars_opd/
+pip install -e . --no-build-isolation --no-deps   # 新环境一次性：注册 ars_opd 包（否则脚本 import 报错）
 ```
 
 ## 5. 本地-远程规则
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..56d0bb4
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,15 @@
+# 最小打包配置：只为让 `pip install -e .` 把 ars_opd 注册进环境，
+# 使脚本/调试器/远程从任意目录都能 import ars_opd（不再依赖 cwd 恰好是仓库根）。
+# 依赖不在这里声明——统一走 requirements*.txt，避免两处清单漂移。
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ars-opd"
+version = "0.1.0"
+description = "OmniOPD (arXiv:2606.01476v2) 分层重构实现"
+requires-python = ">=3.11"
+
+[tool.setuptools]
+packages = ["ars_opd"]
diff --git a/scripts/setup_remote.sh b/scripts/setup_remote.sh
index 33ef494..0a173e1 100755
--- a/scripts/setup_remote.sh
+++ b/scripts/setup_remote.sh
@@ -33,6 +33,8 @@ fi
 # ---- 3. 依赖 ----
 # 直接调环境内 pip：conda run 会整体缓冲子命令输出（违反"日志实时可查"规矩），弃用
 "$ENV_PATH/bin/pip" install -r "$REPO_DIR/requirements.txt" -r "$REPO_DIR/requirements-remote.txt"
+# ars_opd 以 editable 方式注册进环境：脚本从任意目录都能 import，不依赖 cwd
+"$ENV_PATH/bin/pip" install -e "$REPO_DIR" --no-build-isolation --no-deps
 
 # ---- 4. 环境变量持久化（写入 ~/.bashrc，幂等）----
 if ! grep -q "ars-opd-rebuild env" ~/.bashrc; then