jorpalord/amatista

Amatista

(历史文件夹名：universal-agent-studio；实际产品名、Electron 的 productName 以及整个 docs/_arch/ 中使用的名称是 Amatista)

Amatista 源于一个实际问题——耗尽我的 AI 账户额度——以及一个更古老的梦想：拥有我自己的 Jarvis。凭借仅仅几个月的编程和 AI 经验，以及在多年因 ADHD 无法坚持这类项目之后，这是我进入社区的方式，尽管贡献很小。完整故事见 ORIGEN.md。

Amatista 有 3 个面板并行连接到不同的提供商（Claude、Codex、Antigravity），每个面板都有其真实的品牌颜色

v0.13.0 — 桌面代理工作室（Windows、Electron + React + TypeScript），具有多个可互换的模型提供商、并行聊天面板、一套真实的工具集（文件系统、LSP、本地 git、终端、多面板编排、文档、图像、网络、Windows 系统、可选的桌面控制、嵌入式浏览器）以及本地持久化——没有针对任何提供商的网络自动化或抓取。

本 README 描述当前状态。每个阶段/修复的完整历史，包含真实验证和证据，位于 docs/_arch/HISTORY.md。当前生效的接口/类型/不变量契约位于 docs/_arch/CONTRACT.md。仍然开放或明确弃用的内容位于 docs/_arch/PENDING.md。

提供商与认证

8 种真实连接类型（ProviderType），外加 DeepSeek（使用 DeepSeek 官方发布的、兼容 Anthropic Messages API 的自有端点——或通过其原生 OpenAI 兼容 API，如同任何 openai-compatible 连接）：

| 提供商 | 认证 | 运行时 |
|---|---|---|
| OpenAI / Codex (ChatGPT) | 订阅（已认证的 codex CLI） | codex-subscription |
| OpenAI（直接 API）/ OpenAI 兼容 | API key，端点可编辑 | openai-chat (Chat Completions) |
| Anthropic (Claude) | 订阅（claude CLI）或 API key | claude-cli / anthropic-api |
| Google (Gemini) | API key | gemini-api（直接 HTTP——独立的 gemini-cli 已退役，Google 已对个人账户停止支持） |
| Antigravity (Google) | 订阅或 API key（同一个 agy 二进制文件） | antigravity-cli |
| Microsoft Foundry | API key | foundry (Azure OpenAI Responses API) |
| OpenRouter | API key，端点可编辑 | openai-chat (Chat Completions) |
| DeepSeek | API key——两条真实路径：DeepSeek 官方发布的、兼容 Anthropic Messages API 的端点（/anthropic，专为 Claude Code 类集成设计），或通过通用 openai-compatible 连接使用其原生 OpenAI 兼容 API（与 OpenRouter 相同的机制） | anthropic-api（兼容端点）/ openai-chat（原生 API） |
在 chatgpt.com/claude.ai/gemini.google.com 上没有 Web 自动化或抓取——策略始终是在存在官方 CLI/会话或 API 流程时复用它们。

界面——最多 4 个并行面板

- 最多 4 个同时存在的 ，每个都有自己的聊天/工作区/提供商/模型，彼此独立。
- 子聊天树（parentChatId），带嵌套侧边栏。
- 简单预设（人设 + 首选提供商/模型）。
- “计划模式”（轻量版，以及带真实只读沙箱的强化变体）。
- 按连接的沙箱：read-only / workspace-write / danger-full-access。
- 可按轮次配置的努力/推理级别。
- 装饰性 Q 吉祥物（Three.js），可在整个窗口中拖动——没有业务逻辑，只是视觉点缀（光环颜色取决于当前活动的提供商）。

多面板编排

- list_windows / send_to_window：一个面板可以向另一个面板发送完整的一轮并等待结果。
- parallel_ask：真正的 fan-out/fan-in——在已连接的 idle 面板之间分配子任务（绝不打开新面板），在不同面板之间真正并行运行，在同一面板内按顺序运行；完整的身份守卫（聊天/工作区/提供商/模型）会在派发每个子任务之前立即重新验证，这样在人工审批期间发生的重新连接就不会把它派发到与已批准目标不同的目的地。
- 按订阅编排：send_to_window/parallel_ask 也可作为来自通过 CLI 连接的面板（Claude Code CLI/Antigravity CLI）的 ORIGEN 使用，而不仅仅是作为目标——通过同一个已向这些运行时暴露 LSP 的自有 MCP 服务器，并且“主面板”门禁始终在 main 侧重验证，绝不信任 CLI 子进程所声明的内容。

代理工具

46 个真实工具（已由代码确认，tool-registry.ts），按功能分组：

- 文件：read_file、write_file、apply_patch、list_dir、search_files、explore——具有真正的 TOCTOU 保护（基于哈希的陈旧检测），防止并发写入，包括 parallel_ask 引入的真正并发。
- 文档：read_document——PDF/DOCX/XLSX/HTML，真正的分页，并对扫描页面提供视觉回退。
- 代码（LSP）：get_diagnostics、find_definition、find_references、list_symbols。
- 终端：run_command、terminal_exec（按会话的持久终端）、git_status/git_diff（只读快捷方式，等价于在项目真实 git 上运行 run_command，无审批对话框）。
- 隐藏的本地 VCS（按工作区，一个独立于用户项目真实 .git 的自有 git 仓库）：list_file_history、revert_file——每次 write_file/apply_patch 都会自动备份；按仓库的执行队列（一个完整的逻辑操作作为原子单元，而不是每条单独的 git 命令）+ 真正的超时。
- 编排：list_windows、send_to_window、parallel_ask。
- 多媒体：generate_image（Microsoft Foundry 或 Gemini/Nano Banana，取决于连接）。
- Web：web_search、web_fetch（通过 Tavily）。
- 生产力：todo_write、exit_plan_mode、load_skill（Agent Skills 格式，渐进式披露）。
- Windows 系统：notify、clipboard_get、clipboard_set、open_url、open_folder、open_app、list_processes、system_info、volume —— 外加 3 个破坏性工具（close_app、lock_screen、power），带有强化的一律守卫：它们始终要求明确批准，无一例外，无论激活的沙箱是什么（包括“完全访问”），也无论是否已为其他工具授予过会话信任。
- 桌面控制（screenshot、mouse_move、mouse_click、keyboard_type）以及嵌入式浏览器（browser_navigate、browser_click、browser_type、browser_screenshot）—— 参见下方 2 个专门章节。

所有 MCP 工具调用和 read_document 都有真实超时（guard/），并通过重复结果进行循环卫生处理。

桌面控制（computer use）

该项目风险最高、攻击面最大的功能——对运行 Amatista 的机器进行真实的鼠标/键盘控制和屏幕截图，这一点很重要，因为该应用是公开发布的。默认关闭，采用多层独立安全模型：

- 会话门控（computerUseActive）：在用户为该面板显式激活控制之前，这 4 个工具对模型甚至不存在——要求至少已在“设置”中确认过一次严厉警告。
- 2 层批准：除上述门控外，每次单独调用都要求无条件的人工批准（requestHardToolApproval()）——绝不跳过，即使沙箱处于“完全访问”激活状态，或已为其他工具授予过会话信任。
- 全屏视觉覆盖层，在真实操作进行期间可见（而不仅仅是在控制激活期间）。
- 全局紧急按键（Ctrl+Alt+Shift+Esc）——立即取消整个回合并停用控制，无论是由哪个面板触发的。
- 非协作式取消：每次鼠标移动或键入都是一系列微步骤，在每一步之间检查取消——紧急按键或“停止”按钮会在中途打断，绝不等待整个操作完成。
- 通过 UI Automation 而非坐标进行主解析：一个自有的 C#/.NET 辅助程序（FlaUI），打包为自包含二进制文件（不依赖用户安装 .NET 运行时），随应用一起分发，通过 Windows 控件的真实名称或类型来解析点击/键入——不受窗口在模型决定目标与操作执行之间发生移动的影响。坐标（x/y）作为显式回退保留，用于没有真实语义的内容（例如绘图画布）。

嵌入式浏览器
每个面板一个真实的 WebContentsView（不是已弃用的 BrowserView）——它位于聊天面板自身内部，通过其独立的 Chromium 沙箱隔离（启用 contextIsolation/sandbox，无 nodeIntegration），与用户真实的浏览器完全分离。主要通过 DOM/文本进行交互（通过可见文本或标签查找真实元素，绝不使用屏幕坐标——不受计算点击与执行点击之间滚动/缩放的影响）；坐标仅作为非语义内容的显式回退方案。与桌面控制相同的两层审批模型，拥有自己独立且互不干扰的会话标志（browserControlActive）。

真实 LSP —— 20 种语言

基于真实 LSP 服务器（非模拟）的实时诊断 + 符号导航（find_definition/find_references/list_symbols），配置驱动（LANGUAGE_SERVERS）：

TypeScript、JavaScript、Python、Rust、Go、C、C++、Java、YAML、Bash、Terraform、Lua、Dart、Gleam、Clojure、Typst、Zig、Svelte、Astro、Prisma，以及 Deno（通过 deno.json 进行真实的条件检测，以避免与同一工作区中的 TypeScript/JavaScript 冲突）。

Vue 按现状被排除（@vue/language-server 目前没有可行路径），Nix 也因没有可行路径而被排除——两者都记录在 PENDING.md 中，并非本 README 的待办事项。

MCP

- 面向 API 运行时的真实 MCP 客户端（读取 .mcp.json，将服务器的工具目录与自身的合并）。
- Amatista 自有的 MCP 服务器，用于向 3 个 CLI 运行时（claude-cli/antigravity-cli/codex-subscription）暴露 LSP，并对其 4 个工具进行预审批。

持久化

- 聊天记录本地持久化（SQLite），独立于当前活动的工作区。
- 每个工作区隐藏的本地 VCS——每次真实写入（write_file/apply_patch）都有历史记录和 revert_file 作为备份，不使用用户项目的真实 .git。
- 所有存储（数据、缓存、cookies）集中存放在一个自有数据文件夹下，可在安装程序中配置（带来源校验：数据文件夹不能是 $INSTDIR 或其子文件夹）。

视觉与图像

- 在 4 个 API 运行时和 2 个 CLI 运行时中提供真实视觉能力。
- 通过 Foundry 或 Gemini/Nano Banana 进行真实图像生成（generate_image），具体取决于当前活动的连接。

活文档

- docs/_arch/CONTRACT.md —— 当前生效的接口/类型/不变量契约，以及每个修复/功能的真实验证。
- docs/_arch/HISTORY.md —— 仅追加的日志，每个阶段/修复一条记录。
- docs/_arch/PENDING.md —— 仍然开放、被明确排除或已解决（附原因）的事项。

开发

npm install
npm run typecheck
npm run dev

构建 / 安装程序

npm run build   # typecheck + electron-vite build + bundle del servidor MCP de LSP
npm run dist    # build + instalador NSIS real (Windows)