DataFlow Guard
Pandas 数据 Schema 静态校验与数据预览的 VS Code 插件（MVP）。
100% 本地化处理，零数据上传——在按下运行键之前拦截错误并提供数据预览。
设计文档：docs/design.md；实施计划：docs/superpowers/plans/2026-11-13-dataguard-mvp.md。
功能（MVP：CSV 单文件闭环）
pd.read_csv(...) 前 100 行有界抽样，构建轻量 Schema 库（mtime 缓存，不重复采样）- 实时诊断（红线）：列不存在（含 did-you-mean 拼写建议）、CSV 读文件失败
▶ Preview Data (50 rows) CodeLens：在白名单识别的数据节点（read_csv / 掩码 / groupby / 聚合链）上，基于抽样数据本地重放并展示前 50 行- 用户代码永不被 exec；全部计算在本机 Python 子进程完成
开发环境准备
依赖：Node ≥20（本机 v23）、Python ≥3.10（本机 3.13）。
# 1. 后端 venv + 依赖
python -m venv backend\.venv
backend\.venv\Scripts\python -m pip install -e "backend[dev]"
# 2. 前端依赖 + 编译
npm install
npm run compile
调试验收（F5）
- VS Code 打开
DataGuard/ 根目录，按 F5（无 .vscode/launch.json 时新建 Extension Development Host 配置，或直接用默认 Run Extension）
- 新窗口中
File → Open Folder 打开 sample-workspace/，并在设置里指定解释器：
{ "dataflow-guard.pythonPath": "backend/.venv/Scripts/python.exe 的绝对路径" }
（Extension Development Host 的设置需指向绝对路径）
- 打开
demo.py，逐项确认：
- [ ]
df["acctt_id"] 下方画红线，提示"是否想用「acct_id」？"
- [ ]
df["region"] 画红线（无相近列，无建议）
- [ ]
df["profit"]（新建列）不报红线
- [ ]
df = pd.read_csv("sales.csv")、stats = …groupby…sum()、north = df[df["region"] == "north"] 三处上方出现 ▶ Preview Data (50 rows) · df
- [ ] 点击三处 CodeLens 分别弹出 Webview 表格；stats 那处展示按城市聚合的三行结果（北京/广州/深圳）；north 那处展示"⚠ 预览失败"错误框（region 列不存在 → pandas KeyError 被折叠为错误信息）
- [ ] 手工把
sales.csv 改名后保存 demo.py → read_csv 行出现黄色警告"文件不存在"；把文件名改回后再次保存 demo.py，警告消失（诊断随文档事件重新发布）
- 测试回归：
backend\.venv\Scripts\python -m pytest backend/tests -q（28 个用例，含 LSP stdio 端到端）
架构速览
VS Code ──stdio JSON-RPC── python -m dataguard.server (pygls)
│ ├─ analyzer.py ast 解析（白名单链提取）
│ ├─ schema.py nrows=100 抽样 + 缓存
│ ├─ rules.py 诊断规则
│ ├─ preview.py 白名单链重放
│ └─ license.py License 桩（W3 接真实校验）
└─ CodeLens / Webview（enableScripts:false + CSP）
已知边界（MVP）
- 仅支持
pd.read_csv；read_parquet / polars / SQL / merge 类型校验 / ipynb 列 W2-W3
- 仅校验直接绑定
read_csv 的变量；派生变量（df2 = df...）不参与列校验（引用收集会跳过）
- 列引用检测范围：
df["col"]、df[["a","b"]]、掩码内下标、groupby/sort_values/drop/value_counts 首个字符串参数；df.col 属性访问不检测（避免与 pandas 方法名混淆）
| |
