# Pize 插件说明文档 > Pize 是一款面向科学计算与统计分析的 AI 编程助手。它可在 Pize Code 和 Positron 中运行，也以 SDK 形式提供。 Pize 是面向科学计算与统计分析的 AI 编程助手。它运行在 Pize Code 和 Positron 中，也提供 SDK，并把精力集中在最容易出错、也最容易被忽视的一环：统计数据的识别与读取。只有正确理解数据，后续的计算、检验与推断才可能正确。 ## 先说明 Pize 做什么，再说明它不做什么 大多数编程代理着重于编写更多代码。但统计与科研中的错误通常发生得更早：一旦数据读取有误，之后的每项检验、模型和推断都会悄然继承这个错误。Pize 将重点放在这一环——先让模型准确了解数据的形状、类型和缺失情况，再在你已经使用的 R / Python 会话中编写并运行代码、查看图表和修正结果。 它也是一个完整的编程代理：支持跨文件编辑、终端操作、规划与执行、项目规则、多种模型选择，并可通过 MCP 连接实验室或内部系统中已有的工具。可在 Pize Code、Positron、CLI 中使用，或通过 SDK 嵌入你自己的程序。 - **它是什么。** 针对数学计算与统计分析优化的编程代理。数据读取、计算和检验均在当前运行的会话中完成，结果可以复算。 - **它不是什么。** 它不是通用代码补全工具的换皮，也不是代替 Cursor 去做各类通用编程的产品。重点不在代码补全，而在正确读取数据并准确完成计算。 - **它在哪里运行。** Pize Code、Positron、CLI 和 SDK。 - **模型会获得什么。** 数据结构、类型、缺失情况和摘要，而不是将整张表塞入上下文。原始观测数据保留在会话中。 ### 三种入口，同一个代理 在编辑器中，它是侧边栏插件；在你自己的工具中，它以 SDK 形式嵌入；连接数据库、仪器软件或内部知识库时，则使用 MCP。三种入口都调用相同的数据读取逻辑、计算能力和审批边界。 ## Pize 在哪里运行、模型用量如何付费、操作由谁批准 同一套编程代理可以读取文件、编写代码、运行命令并操控浏览器。每次写入和命令都需你的批准。可在 Pize Code、Positron、CLI 和 SDK 中使用。 ### 当前可用入口 - **Pize Code.** 编辑器中的侧边栏插件，支持跨文件编辑、终端、计划与执行，以及可审阅的 diff。 - **Positron.** 同一套代理，并可桥接到你当前聚焦的 R 或 Python 会话。 - **SDK.** 把同一套代理嵌入你已在运行的程序，并可通过 CLI 使用。 ### 模型用量如何付费 自助使用采用预付积分。1 积分等于 1 美分。在定价页购买积分包，由 Stripe 收款。企业条款需联系商议。 ### 企业 实验室和定制条款没有公开价格，需联系商议。 ### 它同时是一个完整的编程代理 数据读取与会话桥接是 Pize 增加的一层能力。接下来列出的是它同时具备的完整编程代理能力——缺少这些能力，统计工作闭环同样无法运转。 - **跨文件修改** 一次处理相关文件，并用 diff 展示修改，方便你逐项检查或撤销。 - **运行命令并返回结果** 在集成终端运行命令，把输出、报错和测试结果带回会话。 - **先计划，再执行** 先查看数据与代码，说明准备怎么做；你确认后，再开始修改或运行分析。 - **准确指定上下文** 用 @file、@folder、@problems 和 @url 指定内容，也可以结合截图与日志定位浏览器问题。 - **沿用项目规则** 把统计口径、绘图规范和目录约定写入项目规则，后续任务继续参考。 - **连接模型与外部工具** 根据任务选择已经配置的模型，也可以通过 MCP 连接外部工具与数据源。 ## SDK 是供其他程序调用的工具包，不是另一个网站 SDK（Software Development Kit，软件开发工具包）将 API、类型声明和示例封装在一起，让其他程序可以直接调用相应能力，而不必重新实现一遍。 没有 SDK 时，每项集成都可能自行编写 HTTP 调用并猜测字段含义。有了 SDK，调用方可以获得稳定的函数名、类型，以及能够实际运行的示例。将模型嵌入实验室采集软件或内部分析平台，依靠的就是这一层。 - **它提供什么。** 可调用的接口、类型，以及能够运行的最小示例。调用方不必重新实现数据读取和会话连接。 - **它不提供什么。** 它不会取代你的产品界面，也不会替模型选择统计方法。所用方法仍由模型提出并经你确认。 - **它与插件的区别。** 插件在编辑器中打开。SDK 则将同一代理嵌入你已经使用的程序，无需再打开一个侧边栏。 ### Pize 的 SDK 做什么？ Pize 将数据读取、会话桥接和编程代理封装成可嵌入的工具包。实验室工具或内部程序无需另开编辑器窗口，也能让模型基于真实数据计算，并在你确认后进行修改。 ## MCP 是连接机制，不是另一个模型 MCP（Model Context Protocol，模型上下文协议）是一种开放协议：它让模型在运行时连接外部工具、数据和提示，无需为每个数据源分别开发专用连接。 模型本身只负责推理；它无法直接查看你的数据库，也无法操作仪器软件中的参数。MCP 定义了三类对象：工具（可调用的操作）、资源（可读取的数据）和提示（可复用的指令）。任何实现这套约定的系统，模型都能以同一种方式使用。 - **它解决什么问题。** 模型与外部系统无需再各自开发专用连接。数据库、知识库和内部网关都可以通过同一协议访问。 - **它不是什么。** 它不是模型，也不是 SDK。它不决定如何将代理嵌入你的程序，只规定运行中的代理如何连接外部能力。 - **在 Pize 中。** Pize 作为客户端连接其他 MCP 服务器。安全边界仍由你审批：默认只读，执行操作前需获得你的确认。 ### 不要将 MCP 与 SDK 混淆 SDK 回答“如何将 Pize 嵌入我的程序？”，MCP 回答“运行中的代理如何连接我已有的工具和数据？”。前者负责嵌入，后者负责外部连接。 ## 模型负责推理，SDK 负责嵌入，MCP 负责连接 要让 AI 系统在科研中得出正确结果，缺少的往往不是“更大的模型”，而是模型能否看到真实数据、操作真实工具，并融入你已经使用的软件。 Pize 将这三层明确分开，同时让它们协同工作。模型选择方法并编写代码；SDK 将代理嵌入你的工具；MCP 让代理在运行时连接软件库、仪器软件和内部系统。数据读取始终在最前面：如果读取有误，后两层只会让错误传播得更远。 | 层级 | 作用 | 在 Pize 里 | | --- | --- | --- | | 模型 | 推理、选择方法、编写代码 | 你接入的任意提供商模型或本地模型 | | SDK | 将代理嵌入已有程序 | 与编辑器插件使用相同的数据读取、计算和审批机制 | | MCP | 在运行时连接外部工具和数据 | 作为客户端连接；默认只读；操作需经你确认 | 顺序不会改变：先正确读取数据，再完成嵌入，最后连接外部能力。任一层次颠倒，后续结果都不再可信。 ## 为什么“读得对”是统计能力的前提？ 统计计算的错误很少以报错的形式出现。分隔符判错，列会整体错位；首行被当成表头，第一条观测就凭空消失；NA、NULL 被当成 0，均值与方差立刻偏移；数值列被判成字符，回归模型转头把它当因子处理。这些都不会中断程序，只会安静地给你一个看起来很合理的错数字——而错误发生在读取阶段，后面所有的检验、建模与推断都继承了它。 所以 Pize 的优化重点不是让模型写出更多代码，而是先让它确切知道数据的形状、每列的类型、缺失值数量和大致行数，再编写计算与建模代码，并在你的真实会话中运行，让你看到结果。 ## 统计数据的识别与读取 格式识别依据文件内容，而不是文件扩展名——研究数据中的 .txt 常常装着表格，.csv 却可能只有三行配置。下面每一项判定都会直接影响后续计算结果。 - **分隔符判定。** 在制表符、逗号、分号和管道符（|）中选择一种；各行的列数必须稳定，字段也必须像真正的单元格，以免把每句都含逗号的散文误判为两列表。 - **表头还是数据。** 若首行在数值列的位置上仍然是数字，就判定它是观测而不是列名——把第一条观测吃成表头，是样本量凭空少一的经典来源。 - **缺失值不参与类型推断。** 空串、NA、NaN、NULL 被单独识别；否则一整列空值会被判成数值列，诱使模型对不存在的数做统计。 - **逐列类型推断。** 数值 / 文本 / 空列逐列标注，这一步直接决定某列能不能进均值、方差与回归。 - **注释与元数据剥离。** 以 #、! 或 @XX 开头的前导块先行剥离；VCF 把列名藏在最后一行注释里，也会被恢复，那些列因此有名字可用。 - **压缩表格透明读取。** .gz 自动解压，体积按解压后的长度判断——1 MB 的压缩包里可能是 20 MB 的表。 - **行数估算。** 按已读前缀的字节比例估算总行数，并明确标注这是估算值，不会被当成事实报出去。 - **超限文件给数据卡，而不是报错。** 超出上下文预算时返回体积、分隔符、估算行数、列名及其推断类型与开头两行，模型据此写出正确的读取代码，上下文不会被一张百万行的表吃光。 ### 统计与科研常用的二进制容器 统计数据常常不是纯文本。附上 Parquet、Feather、Arrow、RDS、RData、h5ad、Loom、HDF5、NumPy、SPSS（.sav）、Stata（.dta）、SQLite 或 DuckDB 文件时，Pize 不再回一句“无法读取二进制文件”，而是报出格式名与对应的打开方式（例如 readRDS、anndata.read_h5ad），让模型直接写出正确的读取代码；PDF、DOCX、XLSX 与 Notebook 走文本抽取，同样可读。 ## 算在真实数据上，而不是算在猜想上 读对之后才是算。Pize 不替你发明统计方法，它保证模型面对的是你真实的数据，并且每一步的结果你都看得见。 - **基于真实分布选方法。** 模型能拿到行数、列数、列类型、每列缺失计数与摘要统计，据此判断用参数还是非参数方法、要不要变换、缺失如何处理。 - **写完就跑。** 生成的 R 或 Python 代码在你确认后于当前会话执行，返回的是真实输出，而不是模型对结果的想象。 - **看图诊断。** 可取回最近一张图形——QQ 图、残差图、分布图这类只能靠看的诊断，模型也能参与判断。 - **迭代闭环。** 执行、读结果、修正，都在同一个会话里完成，中间变量不会因为换个进程而丢失。 - **只给聚合，不给原始行。** 表摘要返回结构与统计量，原始观测始终留在会话里。 ## Positron 运行时桥接 分析的真相不在文件里，而在内存里。桥接层通过 Positron 公开的扩展 API 读取你当前聚焦的 R 或 Python 会话，它从不创建或切换运行时，只使用你已经在用的那个。 ### 读取、汇总、执行、取图 | 工具 | 作用 | 审批级别 | | --- | --- | --- | | `get_session_context` | 读取会话语言、状态与变量清单（仅元数据） | 读取类 | | `inspect_variables` | 按名查看变量结构与截断预览 | 读取类 | | `summarize_table` | 获取数据框的行列数、列类型、缺失值计数与摘要统计 | 读取类 | | `execute_code` | 你确认后在当前会话执行统计代码 | 命令类，默认关闭 | | `get_current_plot` | 取回最近一张图供模型查看 | 命令类，默认关闭 | 安全边界是设计的一部分：每次调用都重新校验会话仍在前台，你切走了就直接拒绝；输出总量、变量条数、预览长度、图片体积均有硬上限；原始数据行、控制台历史与密钥永不返回。在普通 Pize Code 中，这五个工具自动消失。 ### 附件取自编辑器缓冲区 输入框下方的附件标签读的是编辑器缓冲区，而不是磁盘上的旧版本——你刚改完还没保存的那份脚本或数据，正是模型看到的那一份。同一份内容重复附带时按哈希去重。 ## 读取逻辑是被验证过的，不是被相信的 - **用生成语料做防回归测试。** 针对 31 类文件形态生成带标注样本，每批一万条送入检测器：首轮有 458 条失败，暴露出四类缺陷，随后逐一修复。随机种子固定，因此可用同一批输入验证已修复的问题不会再次出现。 - **接线处有绊线测试。** 与上游代码的每个接点都有测试。若合并时漏掉一行接线，测试会立即失败，而不会让功能静默失效却仍显示全部通过。 - **每次合并跑完整清单。** 上千个单元测试、两套类型检查、全仓 lint，打包后还要拆开产物核对功能确实在里面。 - **一键自检。** 命令面板里的桥接检查会真的读一次会话，通过即证明工具拿到了真实数据。 - **与官方版共存。** 使用独立扩展标识发布，可与上游插件同时安装、互不覆盖。 架构上还有一条贯穿始终的规则：新行为一律写进新文件，只在必要的调用点改动上游文件。因此，一次涵盖十个上游提交的合并，冲突也可能只落在一行上——它可以长期跟进上游，而不是发布一次便停滞不前。 ## 先回答这七个问题 ### Pize 是什么？ Pize 是一款面向科学计算与统计分析的 AI 编程助手。它可在 Pize Code 和 Positron 中运行，也以 SDK 形式提供。 ### 什么是 SDK？Pize 有没有？ SDK 是一组可调用的接口、类型和示例，用于将能力嵌入另一个程序。Pize 提供 SDK：同样的数据读取能力和同一个代理不再局限于编辑器中。 ### 什么是 MCP？Pize 是否支持？ MCP 是让模型连接外部工具和数据的开放协议。Pize 作为客户端连接 MCP 服务器；可通过它访问数据库和内部网关，且默认为只读。 ### Pize SDK 和 MCP 如何与 AI 模型协作？ 模型负责推理，SDK 将代理嵌入你的产品，MCP 让代理在运行时连接真实工具和数据。Pize 将三层结合起来，并把数据读取置于它们之前。 ### Pize 跑在哪里？ Pize Code、Positron、CLI 和 SDK。 ### Pize 是 Cursor 的替代品吗？ 不是。Pize 面向数学计算与统计分析，重点是正确读取数据并在当前运行的会话中完成计算，而不是成为适用于所有编程任务的通用工具。 ### Pize 能读哪些数据？ Pize 可根据内容识别分隔符、表头、缺失值和列类型。除文本表格外，它还会说明如何打开 Parquet、RDS、h5ad、SPSS 和 Stata 等容器格式。超过上下文预算的文件会生成数据卡，而不会将整张表塞入上下文。 ## 四步开始，从一份数据算到一个结论 装好插件、接上模型、把数据交给它，剩下的是一轮轮“写代码—跑结果—读图修正”的迭代。 1. **安装插件** 在 Pize Code 或 Positron 中安装扩展包，侧边栏出现 Pize 图标。 2. **接入模型** 填入任一提供商的 API Key，或连接本地模型与自托管端点。 3. **把数据交给它** 附上当前数据文件，或在 Positron 里聚焦一个已载入数据的会话。 4. **先计划，再执行** 用计划模式对齐分析方案，确认后让它写代码、跑结果、读图修正。 Positron 工具仅在 Positron 宿主中出现，且默认只读；代码执行与取图属于命令类审批，需要你显式开启。行数为估算值、摘要统计来自运行时，二者都会在结果中标明来源。