AirSaiga/Precis

**本地优先的可视化数据质量工具 / Local-First Visual Data Quality Tool**
可视化建模 · 全链路校验 · 数据不出本机
中文 · English
> **Beta** — 核心功能稳定，V2 配置格式与 CLI/API 契约已冻结（只增不减）。生产关键数据建议保留备份。
> 欢迎通过 Issues、Discussions 与 Pull Request 参与贡献，贡献方式见 CONTRIBUTING.md。
>
> Beta stage. Core features are stable; the V2 config format and CLI/API contracts are frozen (additive changes only). Keep backups for production-critical data.
> Contributions are welcome via Issues, Discussions, and Pull Requests — see CONTRIBUTING.md to get started.
---
项目简介
Precis 是一款针对 Excel / CSV / TSV 表格数据的质量校验工具。校验流程在可视化画布上以节点和连线的方式编排——从数据接入、清洗转换到多维度质量检查，全程无需编写代码。所有数据均在本地处理，不上传至任何外部服务。
提供三种使用方式，按需选择：
- **桌面应用**（推荐）：图形界面，开箱即用
- **命令行**：适合批量执行，或交由 AI 编程助手（Kimi Code / Claude Code 等）调用
- **HTTP 接口**：用于集成到自有系统
功能特性
- **可视化编排** — 在画布上拖拽节点、连接流程，即可完成校验建模
- **AI 助手** — 接入国内外大模型或本地 Ollama，在对话中用自然语言推断 Schema、生成约束，确认后自动写入并同步画布；CLI 同样可用（ai chat / ai generate）
- **10 种检查规则** — 必填校验、唯一性、引用完整性、允许值清单、数值范围、条件判断、自定义脚本、字符集、日期逻辑、多规则组合
- **22 种数据转换** — 字符串拆分、模式提取、数学计算、分组聚合、过滤、排序等
- **大文件支持** — 超大文件自动分块处理
- **本地运行** — 数据不出本机；中英文双语界面；桌面应用内置运行环境，安装即可使用
快速开始
环境要求
| 工具 | 版本 | 说明 |
|------|------|------|
| Node.js | ^20.19.0 \|\| >=22.12.0 | 含 npm |
| Python | >=3.12,
如何确认本机版本
若系统默认 python3 低于 3.12（macOS 自带 3.9），可通过 Homebrew 安装：
安装
一键脚本将依次完成：Python 环境检测、虚拟环境创建、依赖安装、前端与桌面应用构建。
> 无需图形界面、仅需在命令行或 AI 助手中执行校验，可直接 pip install precis-cli 获取 precis 命令；接入 AI 编程助手的方式见 integrations/。
开发者手动安装（含测试工具）
> **注意**：凡调用 python 的 npm 脚本（dev / backend:dev / cli / electron:dev），执行前须先运行 source backend/.venv/bin/activate，否则将使用系统自带的低版本 Python。
启动
> 更多启动方式与脚本说明见 scripts/README.md 与 tui-rust/README.md。
验证安装
正常输出校验结果即表示环境就绪。
AI 助手（对话式建模）
除手动编排外，还可以让 AI 代劳。在应用设置中接入大模型——内置 OpenAI、Anthropic、Gemini、DeepSeek、通义千问、智谱、Kimi、MiniMax、小米 MiMo 等服务商预设，也支持本地 Ollama——之后即可在对话中描述需求：
- AI 推断数据结构，生成 Schema 与约束草稿
- 每次写盘前列出变更清单，确认后应用到项目并同步到画布
- 命令行同样可用：precis 交互式 shell 中先以 provider 配置服务商，再执行 ai chat（Agent 模式）或 ai generate data.xlsx 从数据文件直接生成配置
> AI 功能为可选：不配置任何服务商时，校验与其他功能不受影响，全部校验仍在本地执行。为外部 AI 编程助手接入的方式见下一节 MCP Server。
MCP Server（AI 助手直连）
本仓库实现了一个 Model Context Protocol (MCP) server（stdio 传输，基于官方 MCP Python SDK）。支持 MCP 的 AI 编程助手（Claude Code、Cursor、Kimi Code 等）配置后可直接调用校验引擎。
在 MCP 客户端中配置（mcpServers 格式，Claude Code / Cursor 等通用）：
提供 4 个工具：
| 工具 | 作用 |
|------|------|
| validate_data | 执行校验，返回结构化错误报告（与 CLI --format json 同一契约） |
| check_config | 检查项目配置加载情况 |
| describe_constraints | 列出全部约束类型与参数说明 |
| infer_schema | 从数据文件推断 schema 草稿 |
更多 AI 助手接入方式（skill、插件包等）见 integrations/。
项目结构
更多文档
- **开发者**：开发命令与打包说明见 CONTRIBUTING.md；架构细节见 AGENTS.md 与 docs/ARCHITECTURE.md
- CHANGELOG.md — 变更日志
- SECURITY.md — 安全说明
- 各子项目详情：backend · frontend · electron · tui-rust · scripts · e2e
许可证
Apache-2.0 — 详见 LICENSE_NOTICE.md。
---
Overview
Precis is a data quality tool for Excel / CSV / TSV tabular data. Validation workflows are composed on a visual canvas using nodes and connections — from data ingestion and transformation to multi-dimensional quality checks, without writing any code. All data is processed locally and never uploaded to any external service.
Three usage modes, choose as needed:
- **Desktop app** (recommended): graphical interface, ready out of the box
- **Command line**: suitable for batch execution, or for invocation by AI coding assistants (Kimi Code / Claude Code, etc.)
- **HTTP API**: for integration into your own systems
Features
- **Visual composition** — build validation workflows by arranging nodes and connections on a canvas
- **AI assistant** — connect a cloud model or a local Ollama instance, then infer schemas and generate constraints from natural-language descriptions; confirmed changes are applied to the project and synced to the canvas; also available in the CLI (ai chat / ai generate)