neuratile/Tessera

## 产品简介 Tessera 是一款桌面 IDE，可对代码库执行**纯静态**分析，并使用 LLM 生成结构化的 QA 产物 —— 包括测试计划、测试用例、缺陷报告和 Bug 报告。所有操作均在您的本地机器上运行（本地 LLM、本地 SQLite、本地 AST 解析），因此它完全适用于闭源、受监管以及离线的代码库。 打开一个文件夹 → Tessera 会使用 Tree-sitter 对其进行解析，通过配置的 embedding provider（默认为本地 Ollama；可选 OpenAI、Google Gemini 或 Hugging Face Inference）对代码块进行 embedding，并将其索引到 SQLite (`sqlite-vec`) 中。点击某个产物按钮 → 活跃的 LLM provider 将在 RAG 检索到的上下文中运行版本化且受 JSON-Schema 约束的 prompt。输出结果会根据 Zod schema 进行验证，随后您可以批准、拒绝、根据反馈重新生成，或导出为 Markdown。**在使用默认的 Ollama provider 时，源代码绝不会离开本地机器。**如果选择云端 embedding provider，则会将代码片段发送至该 provider 进行 embedding —— 设置界面中已对此做出了明确提示。 ### 独特优势 | 工具 | 生成代码？ | 生成 QA 文档？ | 静态分析？ | 适用于闭源？ | |------|:---:|:---:|:---:|:---:| | Cursor / Copilot | 是 | 否 | 部分 | 是 | | Mabl / TestRigor | 否 | 有限 | 仅限运行时 | 否 | | SonarQube | 否 | 否 | 基于规则 | 是 | | **Tessera** | **否（设计使然）** | **是** | **Tree-sitter + RAG** | **是（依赖本地 LLM）** | 三大核心保证：**感知架构**（RAG 可检索整个项目中的符号，而不仅限于当前打开的文件） · **默认纯静态**（分析过程绝不执行您的代码；一个*可选的*本地 Docker 沙箱可运行**生成的**测试，需手动开启，默认关闭且无网络连接 —— 对生产环境 / 受监管的代码库绝对安全） · **高度结构化**（每个产物都是经过验证的 JSON，可完美导出至 JIRA / Notion / GitHub Issues）。 ## 产物类型 | 类型 | 输出内容 | |------|--------| | **Context** | 架构摘要 —— 作为后续生成产物的项目记忆库 | | **Test Plan** | 范围、目标、策略、环境、风险矩阵、准入/准出标准 | | **Test Cases** | 测试步骤、预期结果、优先级，以及可追溯到源码符号的映射关系 | | **Defect Report** | 静态分析发现：严重程度、类别、位置、修复建议、置信度 | | **Bug Report** | 潜在的运行时问题，格式化为适配工单追踪系统的样式 | 每个产物都会进行版本控制；根据审查者的反馈重新生成时，版本号会递增并链接到其父级版本。 ### 运行生成的测试（可选） 需手动开启，默认关闭。如果在设置中启用了沙箱且系统中存在 Docker，点击 Test Cases 产物上的 **Run** 即可在经过严格安全加固的无网 Docker 容器中执行生成的 JS/TS 测试，并将测试通过/失败状态及代码行覆盖率标记到 Monaco 编辑器的边距上（绿色 = 已覆盖，琥珀色 = 未覆盖）。代码绝不会离开本地机器：容器始终以 `--network none` 模式运行，丢弃所有 capabilities，在只读的 rootfs 上以非 root 用户身份执行，并严格受限于 cpu/内存/pids/文件大小上限，遇到超时或点击 Stop 时会被立刻终止。除非明确确认开启，否则后端将拒绝任何运行请求。详情请参阅 [`plan/versions/v1/SANDBOX_TEST_RUNNER.md`](./plan/versions/v1/SANDBOX_TEST_RUNNER.md) 和 [ADR-0004](./apps/desktop/src-tauri/docs/adr/0004-sandbox-test-runner.md)。 ## 架构 ``` ┌────────────────────────────────────────────────────────────────┐ │ Tessera Desktop (Tauri) │ │ │ │ React 19 + TS + Tailwind + shadcn/ui ◀── Renderer │ │ │ typed IPC (Zod-validated, kebab-case wire) │ │ ▼ │ │ Rust commands ─▶ services ─▶ repositories ─▶ SQLite + vec0 │ │ ├─▶ Tree-sitter (JS / TS / Python) │ │ ├─▶ Ollama embeddings (nomic-embed-text) │ │ ├─▶ LLM provider trait (Ollama / OpenAI / │ │ │ OpenRouter / Anthropic / Gemini) │ │ └─▶ TestRunner trait (opt-in Docker sandbox, │ │ JS/TS + Python) │ └────────────────────────────────────────────────────────────────┘ ``` 采用分层后端设计（参见 [`rules/rules.md`](./rules/rules.md) §4.2）：**commands** 属于轻量级的 Tauri IPC，**services** 负责统筹 RAG + prompts + 校验逻辑，**repositories** 是唯一直接操作 SQL 的层，而 **providers** 则是隐藏在 trait 之后的 LLM/embedding 具体实现。静态存储中的 API keys 使用由 `JWT_SECRET` 派生的密钥，通过 AES-256-GCM 进行加密。 ## 技术栈与 Providers | 层级 | 选型 | |-------|--------| | 外壳 / 后端 | Tauri 2.0 · Rust 1.81+ (Tokio, sqlx, reqwest/rustls) | | 存储 | SQLite 3 + `sqlite-vec` (内嵌式，无需 daemon) | | AST | `tree-sitter` — 支持 JS / TS / Python（更多语言已列入路线图） | | 前端 | React 19 + TypeScript + Vite + Tailwind v4 + shadcn/ui + Monaco | | 可观测性 | `tracing` 日志 · Sentry (可选开启，前后端双向支持) | | 测试沙箱 | Docker (可选开启，默认关闭) — 在经过安全加固的容器内运行 `vitest` + istanbul (JS/TS) 以及 `pytest` + coverage.py (Python) | | LLM provider | 认证方式 | 本地运行 | 备注 | |----------|------|:-----:|-------| | **Ollama Local** | 无 | ✅ | 默认选项 —— 内置 `qwen2.5-coder:7b` + `nomic-embed-text` | | Ollama Cloud | API key | ❌ | 相同的通信格式，托管于云端 | | OpenAI | API key | ❌ | 支持自定义 base URL (Azure / 代理) | | OpenRouter | API key | ❌ | 连接多种模型的网关 | | Anthropic | API key | ❌ | Claude 系列模型 | | Google Gemini | API key | ❌ | Google AI Studio key；兼容 OpenAI 的 endpoint | embeddings 支持热插拔；默认使用的 `nomic-embed-text` (768维，Apache-2.0 协议) 随 Ollama 一并分发。 ## 快速开始 | 工具 | 版本 | 备注 | |------|---------|-------| | Rust | 1.81+ | [rustup.rs](https://rustup.rs/) + `clippy` + `rustfmt` | | Node.js | 20+ | LTS | | pnpm | 10+ | `corepack enable` | | Ollama | 最新版 | [ollama.com](https://ollama.com/) — 仅作为本地 provider | ``` git clone https://github.com/Rajveerx11/Tessera.git tessera cd tessera corepack enable && corepack pnpm install cp .env.example .env pnpm bootstrap:ollama # starts Ollama, pulls chat + embedding models pnpm --filter @testing-ide/desktop run dev # boots Vite + Tauri; the desktop window opens ``` - **macOS** — `xcode-select --install`。 - **Linux** — 安装 Tauri 的系统依赖：`libwebkit2gtk-4.1-dev libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev build-essential curl wget file`。 - **可选的共享技术栈** — 通过 [`docker-compose.yml`](./docker-compose.yml) 运行 `pnpm services:up` / `services:down` 来管理 Ollama。 ## 配置说明 桌面应用会读取 `apps/desktop/.env`（可从 [`apps/desktop/.env.example`](./apps/desktop/.env.example) 复制）；根目录下的 [`.env.example`](./.env.example) 包含了可选的 Docker 技术栈配置。核心环境变量如下： - `OLLAMA_BASE_URL` — Ollama endpoint，默认为 `http://localhost:11434` - `JWT_SECRET` — 认证流程必填；同时用于派生存储 API keys 的 AES 密钥 - `LOG_LEVEL` — `tracing` 过滤器 (`info`, `debug`, `tessera=trace`) - `SENTRY_DSN` / `VITE_SENTRY_DSN` — 错误报告（未设置时关闭） ## 测试 ``` pnpm test # frontend Vitest + Rust unit tests pnpm typecheck # TypeScript across the monorepo pnpm lint # ESLint + clippy in CI pnpm --filter @testing-ide/desktop run test:integration # live Ollama suite pnpm --filter @testing-ide/desktop run test:e2e # Playwright desktop flow ``` 代码在 `-W clippy::pedantic` 下运行 Clippy 检查且无任何告警；通过 `tauri-action` 确保 release 构建在 Windows、macOS 和 Linux 上均能顺利通过。 ## 仓库布局 ``` apps/desktop/ Tauri shell — React frontend (src/) + Rust backend (src-tauri/) packages/ shared/ Zod schemas + inferred TS types (the FE/BE contract) eslint-config/ base + React presets tsconfig/ base + desktop presets rules/ engineering rulebook (rules.md) docs/ workflow + process docs tools/scripts/ deploy + release automation .github/workflows/ CI + release pipelines ``` 架构决策记录（ADR）存放于 [`apps/desktop/src-tauri/docs/adr/`](./apps/desktop/src-tauri/docs/adr/) 目录中。 ## 文档 随时了解项目的最新进展： | 文档 | 内容说明 | |----------|------------------| | [`CHANGELOG.md`](./CHANGELOG.md) | 版本历史 —— 记录每一次变更，按发布版本分组 | | [`docs/PROJECT_STATUS.md`](./docs/PROJECT_STATUS.md) | 实时项目上下文 —— 涵盖架构、状态、路线图和质量评级 | | [`docs/FEATURE_REVIEW.md`](./docs/FEATURE_REVIEW.md) | 功能评测表 —— 为 22 项功能评分，并列出差距与优先级 | | [`docs/AGENT_WORKFLOW.md`](./docs/AGENT_WORKFLOW.md) | 面向人类与 AI agents 的变更管理契约 | | [`plan/ROADMAP.md`](./plan/ROADMAP.md) | 功能路线图与已知局限性 | | [`rules/rules.md`](./rules/rules.md) | 工程规范（分层、IPC、安全与测试要求） | ## 路线图 **v0.1（已发布）** — 功能完整：支持 5 种产物类型、5 种 LLM provider、RAG pipeline、流式生成、首次运行向导以及跨平台的签名发布版本。 **沙箱测试运行器（已发布，支持 JS/TS + Python）** — 选择性启用的 Docker 沙箱可运行生成的测试用例，并在编辑器中覆盖显示通过/失败状态及代码行覆盖率，从而形成“生成 → 运行 → 度量”的闭环（[ADR-0004](./apps/desktop/src-tauri/docs/adr/0004-sandbox-test-runner.md)）。Python 部分（`docker_py`：包含 pytest + coverage.py 以及仅依赖标准库的镜像）已整合至相同的 `TestRunner` trait 中，并将 Docker 安全加固逻辑抽取到了共享测试工具中 —— 未来增加对 Java/Go 的支持只需添加一个 `docker_.rs` 和一个 Dockerfile 即可（[计划]( 本地构建。本地运行。本地审查。
**Tessera** —— 拼凑出您软件质量的马赛克。