Pi Data Agent Extension

基于 Pi Extension API + DuckDB 的数据分析智能体扩展：让 Pi 具备加载数据、SQL 查询、可视化、生成报告的完整分析能力，并以数据字典、查询记忆、表卡片三层知识库沉淀分析资产。

当前版本：v0.23.0（2026-11-04）。v0.23 起 Dashboard 变成工作台：查询 Tab 直接跑只读 SQL 并可存口径/固定看板，定时任务与告警可在面板内管理；数据接入补齐多 Sheet / 编码 / 多文件 / zip·gz / JSON flatten。问题与建议请提 GitHub Issues。

功能概览

• 数据加载：CSV / Excel（.xlsx/.xls）上传自动建表，DuckDB 本地存储
• SQL 查询：自然语言 → SQL，带错误自修复（error-recovery）与查询记忆
• 知识库：数据字典（AI 推断 + 用户确认状态机）、表卡片、指标口径、查询记忆，按 L0 导航 / L1 按需 / L2 注入三层渐进披露；L2 在 query_data 结果前置语义附注（表卡片/指标口径/uncertain 警示，单次 ≤200 token、每轮 ≤2 表，可用 PI_DATA_AGENT_L2_INJECTION=off 关闭）
• PM 分析模板（v0.13）：run_analysis_template 一键跑漏斗 / 留存 cohort / A/B 检验——统计全部确定性计算（LLM 只解释不计算），uncertain 字段 fail-closed，结果自带"方法与局限"说明
• 可视化：matplotlib 静态图（bar/line/scatter/histogram/pie/box/heatmap），Python 失败时自动回退 CSV
• 报告：会话报告（HTML 单文件离线自包含）+ 正式分析报告（executive/detailed，证据覆盖度质量门）
• 真实数据接入（v0.23）：多 Sheet Excel（每 sheet 一张表）、CSV/TSV 编码探测（BOM / UTF-8 / GB18030）、多文件与 glob 合并 + append（列漂移拒绝）、.zip / .gz 解包（拒绝 ../ 路径穿越与超大成员）、JSON flatten（一层对象压成 a.b、单层标量数组展开成多行）；Excel 导出含 data / summary / chart data / _provenance 多 Sheet
• Dashboard + 面板对话（v0.19/v0.20）：npx -p pi-data-agent-extension pida 直启本地 Web 面板，按任务流分八个一级页：对话（流式问答 / 工具调用与思考折叠 / 图片附件 / 技能选择 / 写操作确认门）、看板（连接或加载数据后自动探索：AI 提议维度指标 → 确定性校验后生成 KPI / 趋势 / 分布 / 明细卡片，可编辑、单卡重算、删除；未通过校验的提议单独列出）、概览（项目状态快照 + 待办提醒）、数据（主从浏览：左表清单 / 右预览·体检·表卡片·关系）、知识（字段字典 / 指标口径 / 已验证口径）、产物（报告 / 图表 / 本地副本）、查询（只读 SQL 编辑器 + 结果分页/复制/导出 CSV/存为已验证口径/固定到看板）、自动化（定时任务与告警的创建/暂停/恢复/立即运行/事件历史）、SQL 历史；深浅双主题，暗色为默认。数据页「关系」子 Tab 用内置 Mermaid 渲染 ER 图（推断关系标注置信度，可确认/删除、可复制 Mermaid 文本）。对话消息在会话内存中保留，刷新不丢；多标签页仅最新一个可写，其余只读
• 外部数据库：MySQL 远程只读连接（v0.12），SQLite 本地文件；ATTACH 架构，远程表即普通 DuckDB 表，18 个工具可复用；MySQL 全链路已真机验收（v0.14.2），远程表物化见 materialize_remote_table
• 已验证口径（v0.15）：纠错/确认过的 Q→SQL 一键晋升为知识层资产（verify_query），同类问题自动沿用并标注「✓ 已验证口径」，表结构变更自动降级提示；记忆层自动沉淀纠错候选，晋升必经显式确认
• 定时报告（v0.15）：schedule_report 定义任务 + 系统 cron 调 headless run-report.js 周期跑数，离线 HTML 入报告库，静默期 + 连续失败自暂停，逐期对比；LLM 叙事可选（PI_DATA_AGENT_LLM_* 环境变量）

工具清单

PM 分析模板（v0.13）

run_analysis_template 提供三种模板：

• funnel（状态漏斗）：2–8 个条件步 + 去重键（user_key），可选时间窗口（time_column + window_days，窗口 = 数据最新时间往前 N 天）。第 k 步 = 满足前 k 步条件合取的 distinct user_key（用户级条件叠加，不含步序时间约束）。状态互斥型数据（每行一个 status）不适用——请用分组对比或 cohort。
• cohort（留存分群）：user_key + activity_time + period（week/month）+ 可选 activity_condition（排除噪声行为）+ lookback（默认 12，上限 24）。长期格式输出各群 × 期偏移的留存率与简单平均。
• ab_test（A/B 双比例检验）：variant_column（恰好 2 个非空取值）+ success_condition + unit（去重粒度）+ 可选 segment_columns（≤3，辛普森扫描）+ alpha（默认 0.05）。双侧两比例 z 检验（合并比例），p 值由 TypeScript 确定性正态 CDF 计算（Zelen–Severo 近似，误差 < 1e-7）。内置四项护栏：样本量不足（n<100 或期望计数 <5）、辛普森悖论扫描（段内方向 vs 总体方向）、边缘显著提示（p ∈ (0.01, 0.2)）、效应量（绝对差 + 相对 lift）。

两条统一约束：统计数值全部由确定性代码计算，模型只按返回的 method_notes 解释、不得改写或自行计算；映射列触及 uncertain 状态字段时拒绝执行（fail-closed）。golden 数据集（src/eval/fixtures/funnel-known.csv、cohort-known.csv）保证统计口径有精确已知答案回归。

安装与加载

# 方式一：作为 Pi 包从 npm 安装（推荐）
pi install npm:pi-data-agent-extension

# 方式二：本地目录安装（开发/未发布场景）
pi install /path/to/pi-data-agent-extension

# 方式三：开发模式显式加载
npm install
npm run build
pi -e /path/to/pi-data-agent-extension/dist/index.js

面板直启（v0.19，推荐日常使用）：

# 不安装直接跑（注意带 -p 指定包名：npm 上已有同名包 pida）
npx -p pi-data-agent-extension pida

# 或全局安装后直接 pida
npm install -g pi-data-agent-extension
pida

在项目目录执行即可直接打开本地面板，不进入 TUI。常用参数 pida --help（--port、--no-open、--session、--cwd、--model）；Ctrl+C 退出时会关闭 DuckDB 连接并释放文件锁。TUI 里的 /dashboard 行为不变。

Python 绘图依赖见 requirements.txt（matplotlib / pandas / seaborn / numpy / scipy），安装：pip install -r requirements.txt。测试继承调用方 PATH，不再注入个人虚拟环境；缺依赖时相关用例会明确 skip 并打印安装命令（不再伪装成测试失败）。历史依赖版本矩阵冲突仍见 ../specs/BACKLOG.md，本次未验证全新安装。

测试

npm test            # 全量（vitest；2026-10-11 实测 58 文件 / 420 用例：419 passed | 1 skipped，skip 项为缺 Python 绘图依赖时的明确提示）
npm run test:watch  # watch 模式
npm run test:coverage

v0.11 起测试统一到 vitest（含 DuckDB 单连接串行约束，singleFork）。

数据库连接（v0.12）

connect_database 支持两类目标：

# SQLite 本地文件
connect_database(db_type="sqlite", file_path="/path/to/data.db")

# MySQL 远程（只读）
connect_database(db_type="mysql", host="db.internal", port=3306, user="analyst", database="sales")

MySQL 只读语义与配置：

1. 连接强制 READ_ONLY（客户端约束）。服务端账号请使用 GRANT SELECT ONLY——客户端 READ_ONLY 不是安全边界。写入远程库不支持，此类请求应拒绝。
2. 白名单前置：只有 dbAllowedHosts 白名单内的 host 才允许连接，默认空 = 拒绝一切远程。配置方式（二选一）：
   • env：PI_DATA_AGENT_DB_ALLOWED_HOSTS="db.internal:3306;10.0.0.5"（分号分隔，支持 host 与 host:port 两种格式；localhost 与 127.0.0.1 视为不同目标）
   • config.json（.pi-data-agent/config.json）：{ "dbAllowedHosts": ["db.internal:3306"] }
3. 凭据三种配置方式（密码永不作为工具参数——工具参数会整体进入模型上下文）：
   • env PI_DATA_AGENT_MYSQL_PWD（项目命名空间，优先）
   • env MYSQL_PWD（DuckDB mysql 扩展原生识别）
   • 交互模式下弹出密码输入框（结果仅存入 temporary secret，不落盘）
4. 查询超时：dbQueryTimeoutMs（默认 300000，夹紧 5s~10min），传给 mysql_query_timeout_max_ms。超时设置在创建凭据与连接之前，设置失败即拒绝连接；慢查询是否被可靠中断仍需真机验证（见 ../specs/v0.12-EXECUTION_SPEC.md §12）。
5. 离线环境：首次连接需下载 mysql/sqlite 扩展（约 10MB）。注意引擎把 home_directory 指向项目目录，DuckDB 因此从 <项目>/.pi-data-agent/.duckdb/extensions/<duckdb版本>/<os>_<arch>/ 找扩展，~/.duckdb/extensions 下的缓存不会被命中（此时 INSTALL 会重新联网，受限网络下直接失败）。离线预置二选一：把缓存复制到上述项目路径，或 SET extension_directory 指向已含扩展的目录。连接失败时返回的指引会打印当前引擎实际查找的目录。
6. 已知精度坑：MySQL DECIMAL(p>38) 列落地为 DOUBLE（DuckDB 上限 DECIMAL(38)）；mysql_query() 表函数因 issue #65 禁用，统一走 ATTACH。

远程表物化（v0.14）

materialize_remote_table 把已 ATTACH 的远程表只读复制到本地 DuckDB（不修改远程数据）：

materialize_remote_table(alias="sales", table="orders")            # 默认本地表名 sales_orders
materialize_remote_table(alias="sales", table="orders", row_limit=100000)

• 何时该物化：大表要反复分析（避免每次跨网查询）、给生产库减压、离线场景。偶尔看几行用 SELECT * FROM alias.table LIMIT 10 即可，不需要物化。
• 行数熔断：先 COUNT(*)（下推远端执行），超过 dbMaxMaterializeRows（默认 500000，env PI_DATA_AGENT_DB_MAX_MATERIALIZE_ROWS）直接 block（不是确认）。三条出路：设 row_limit、调大阈值、先在远端 WHERE 过滤再物化子集。
• 确认门：本地写操作走 S-1 fail-closed 确认门——交互模式弹窗（文案含预估行数/目标表/是否替换现有表）；headless 无 PI_DATA_AGENT_AUTO_CONFIRM_WRITE=true 即拒绝。
• 原子替换：tmp → rename 单事务交换；任一步失败自动 ROLLBACK + 清理临时表，已有目标表不受影响、可立即重试。
• 精度坑：源表 DECIMAL(p>38) 落地为 DOUBLE，返回摘要会显式提示（同上 MySQL 精度坑）。
• 物化后：自动生成数据字典（ai-guessed，用 confirm_dictionary 校正）；返回摘要含行数/列数/耗时/endpoint（无凭据）/本地 .duckdb 体积变化。

目录结构

pi-data-agent-extension/
├── src/
│   ├── index.ts            # Extension 入口（生命周期 + 18 工具注册）
│   ├── config.ts           # 配置加载（env > 项目配置 > 默认值）
│   ├── security.ts         # SQL 安全检查（确认门 fail-closed、路径白名单）
│   ├── persistence.ts      # 配置/字典/记忆持久化
│   ├── error-recovery.ts   # 错误自修复
│   ├── engine/             # DuckDB 引擎 + Python 无状态调用
│   ├── tools/              # 18 个工具实现
│   ├── dashboard/          # 本地 Web Dashboard（server/routes/services/middleware）
│   ├── hooks/              # 数据字典、查询记忆、主动反问
│   ├── navigation/         # L0 导航上下文渲染
│   ├── metrics/            # 指标口径定义
│   ├── report/             # 分析报告生成管线
│   ├── table-cards/        # 表卡片存储
│   ├── llm/                # LLM 调用收敛层
│   └── eval/               # 全部测试（vitest）+ fixtures
├── scripts/                # generate_chart.py / check_python_env.py
└── dist/                   # 构建产物（pi -e 加载入口）

安全模型

一句话：写操作确认门 fail-closed（无 UI 环境不静默放行）、SQL 内嵌路径白名单 + 危险操作拦截、模型侧 ATTACH/DETACH 一律拦截（远程连接只允许走 connect_database 工具实现层）、远程目标白名单 fail-closed（默认拒绝一切远程）、凭据不进工具参数/错误文本/审计日志（redactCredentials 兜底）、Dashboard 仅绑定本地回环并叠 Origin 校验 / 速率限制 / 安全响应头 / 写令牌四层中间件。

版本历史

• v0.23：工作台化（查询 Tab / 定时任务与告警管理面）、真实数据接入（多 Sheet/编码/多文件/zip·gz/JSON flatten）、Excel 多 Sheet 导出。

各版本执行规范与交付评审见 ../specs/ 与本目录 v0.*-REVIEW-REPORT.md / v0.*-DELIVERY-REPORT.md；跨版本欠账统一收录在 ../specs/BACKLOG.md。

Dashboard 信息架构（v0.17）

六个一级页按任务流分组，而不是按功能名堆 Tab：

设计取舍（v0.23 更新）：早期定位为「只读控制台 + 轻量编辑」，v0.23 起查询、已验证口径、定时任务/告警、看板卡片都可在面板内显式编辑；写入仍全部经写令牌 + 只读/单语句/路径安全链，落盘统一走 revisioned store（写前读盘 + revision 校验），前端与 Agent 共写同一 JSON 不会互相覆盖。物化副本仍只走对话工具。完整设计见 ../pi-design/pi-dashboard-product-ia.md。

/api/overview 单块失败降级为 null 不影响整体；/api/scheduled-tasks 额外读取 scheduler/runs/{taskId}.json 提供上次运行明细；告警任务还会读取 alerts/state.json 与 alerts/events.jsonl。

项目制（v0.18）

一个项目 = 一个数据源（一个 MySQL 库 / 一个 SQLite 文件 / 一批本地文件表）。侧栏顶部可切换项目，切换后整个界面（数据、知识、产物、自动化）都指向该项目目录下的资产。设计见 ../specs/v0.18-EXECUTION_SPEC.md。

请求级作用域：所有 /api 请求带 X-Project-Id，服务端解析为 projectDir + engine；未带则回落为 Pi 会话当前项目。

engine 池与 DuckDB 锁（实测约束：DuckDB 文件跨进程不可并发打开，read_only 同样被拒）：

• 活跃项目（Pi 会话所在）复用运行时 engine，不新建
• 其它项目用独立 engine 独占打开，同一时刻最多 1 个，空闲 10 分钟或切回活跃项目时释放
• 打开失败（被另一个 Pi 会话占用）→ 返回 503 PROJECT_ENGINE_UNAVAILABLE，页面顶部横幅说明原因；读 JSON 的能力（报告/字典/指标/口径/SQL 历史/定时任务）仍正常

对话错位提示：切换浏览项目不改变 Pi 会话所在项目，因此当两者不一致时侧栏常驻警示，明确告知「对话仍在 X」，避免误以为对话已切过去。

密码落盘开关：PI_DATA_AGENT_STORE_DB_PASSWORD=off 关闭落盘，退回「只存连接信息、密码每次输入」。