tsaagan

align="center"> <img src="docs/hero.png" alt="Tsaagan — 为 AI 代理提供类似人类的浏览器控制" width="100%"> </p> <p align="center"> <em>由 Michael Olmos 创建 · MIT 许可<br><br> <img alt="许可：MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"> <img alt="节点 20+" src="https://img.shields.io/badge/node-20%2Bc873a.svg"> <img alt="MCP 服务器" src="https://img.shields.io/badge/M-8b5cf6.svg"> <img引擎：Playwright + 原生" src="https://img.shields.io/badge/engine-Playwright%20%2B%20native-b5532a.svg"> <img alt="平台" src="https://img.shields.io/badge/macOS%20%C2%B7%20Linux%20%C2%B7%20Windows-lightgrey.svg"> </p> # 🦖 Tsaagan > **Tsaagan 为您的 AI 代理提供真正的网络操作能力** — 让它可以完成您需要亲自处理浏览器任务、点击、填写表单、从提取数据），您授权的任务。（完整[使命）见下 **为 AI 代理提供类似人控制。** Tsaagan 让 AI 像人类一样操作浏览器 —页面、点击、输入、导航、处理登录窗口、iframe、下载 — 并且关键是每个操作确实有效继续。 > **：您的代理是大脑，Tsaagan 是** 无论 驱动它（、Codex/ CLI、Cursor 或）提供意图和Tsaagan**感知 → 验证 → 记忆决定*什么Tsaagan 可*如何*，并证明其有效。 agan 执行经过验证的多步骤任务](docs) ## 使命 **Tsaagan 为您的 AI 代理提供真正的网络操作能力。** 它让代理可以自主完成目前您介入的 — 登录、点击表单、从登录 — 并将归还给您一句话总结：* Tsaagan 是您代理工作流中实际驱动浏览器的一部分 — 可靠地，像人类一样，**在您授权的任务范围内**。 ### 思维模型 — Tsaagan 是双手；您的代理是大脑 您可以用代理*思考*、*编写*、*编码* — 但当任务需要**（“在这里登录，点击那里，获取这个，”）时，代理就会停滞，您就成了双手。Tsaagan 弥补了这一差距（Claude、Codex、小型开放模型）提供意图和判断；Tsaagan的**感知 → 操作 → 验证 → 记忆有三个理念使其成功： 1. **它会悬停，然后点击。** 像鸟一样耐心感知，然后精确移动。它读取页面的无，选择正确的元素，执行操作，然后*证明*点击后就认为成功。验证步骤是“大多数情况下有效的自动化”和您可以放心使用的自动化之间的区别。 2. **能完成任务的最轻量级工具。** 如果网站有 API，就使用 API。如果没有，就像人类一样使用真正的浏览器（受信任的输入）。仅在大多数网站的中间部分才使用原始自动化。 3. **它会记住并改进。** 它保留了它所访问网站的可检查、基于文件的内存 — 学习到的选择器、上次失败的原因 — 因此它在您的重复任务中表现更好。 ### 为用户提供什么 - 将“每周我登录 X，点击并复制 Y”转换为“我的代理执行并验证后报告结果”。 - 在**真实、已登录的网站**上工作 — 仪表板、门户、没有 API 的工具 — 而爬虫或 `WebFetch` 无法访问。 - **让您保持控制：** 它在 CAPTCHA 处停止并交回控制权，并在涉及后果的操作（购买、发送、删除）时发出警告。赋予权力，而不是自动驾驶。 ### Tsaagan 刻意不具备的功能 Tsaagan **不是** 用于破坏安全、解决 CAPTCHA、规避禁令或违反网站服务条款的工具。它适用于希望其代理**完成他们已经授权的工作**的构建者和创作者 — 并且对自己的限制保持诚实，而不是夸大其词。只有自动化**您拥有或被授权访问**的帐户和系统。当遇到 CAPTCHA 或反滥用墙时，它**停止并将控制权交回给您。** 请参阅[可接受使用政策](ACCEPTABLE_USE.md)和[免责声明](#负责使用和免责声明) — **您对如何使用它承担全部责任。** ## 哲学 — 为什么我创建了 Tsaagan 我在自己的代理工作流中不断遇到同样的障碍：您可以*推理*、*编写*、*编码*与代理 — 但当任务需要**浏览器**（登录、点击、拉取、文件）时，代理就会停滞，人类不得不接管。交接是时间流失的地方。 **Tsaagan 的存在就是为了给您的 AI 代理提供真正的网络操作能力** — 让它们可以自主完成网页工作，并将时间归还给您。它适用于**希望其代理真正完成工作**的构建者和创作者，而不仅仅是规划。 并且它是基于一个道德准则：**赋予权力，而不是滥用。** Tsaagan 刻意不具备破坏 CAPTCHA 的**对重要操作进行人为确认**，将机密仅存储在您的**操作系统密钥链**中，保持所有内容**本地化**，并**尊重网站服务条款**。它旨在扩展您可以构建的内容 — 而不是制造风险。该道德准则在 [SOUL.md](SOUL.md) 中 [AGENTSAGENTS.md) 中强制执行。 >在您授权的任务中使用它。** Tsaagan 用于自动化*您自己的*帐户和授权工作 — 而不是用于未经授权的访问避安全。请阅读[可接受使用政策CEPTABLE_USE.md)和[免责声明](#负责使用和免责声明)。 *—mos，创作者* ## 功能层次 —完成任务的最轻量级工具  1. **API 层** — 如果网站有官方 API，Tsaagan 直接使用它，密钥存储在您的**密钥链**中（最快、最可靠）。浏览器层甚至可以为您设置密钥。→ [docs/API.md](docs/API.md) 2. **真实** — `（任何操作系统）/ `native`（macOS）：驱动您的真实 Chrome 浏览器，使用信任的输入，无端口** — 适用于忽略合成输入的网站。→ [docs/EXTENSION.md](docs/.md) 3.P 层** — Playwright 在真实 二进制文件上的大多数部分一个**代理层**（身份 + 内存 Tsaagan一个自我改进的代理，而不仅仅是一个工具。docs/AGENT.md](docs/AG) ## 可学习的内存（一个真正的循环，而不仅仅是存储）  --- 大多数浏览器代理堆栈因两个相同的原因而失败：它们基于*短暂的元素 ID* 来确定操作，这会在页面更改时它们*信任模型的猜测*，即操作成功。Tsaagan 解决了这两个问题： **稳定、自我修复的定位。** 元素通过无障碍树引用进行寻址；如果引用过期，Tsaagan 会重新快照并通过角色 + 名称自动重新定位相同的元素。 - **结构验证。** 在每个操作后，Tsaagan 返回一个`verify`块，该块由真实页面状态构建 — URL 增量、预期文本、新控制台错误、失败的网络请求 — 因此代理*知道* 操作是否成功。 它是三项合一： 1. 一个 **CLI + 守护，您（或编码代理）可以通过个命令驱动。 2. 一个带有自主规划器 → 导航器 → 验证器循环的**库**（`agent.js`）。 3. 一个**独立服务器**，您可以通过 HTTP 向它下达目标 — 无需代理框架。 --- ## 为什么选择 Tsaagan | | Tsaagan | |---|---| | 感知 | 无障碍树（主要）+ **视觉 Set-of-Marks** 备用方案，用于 canvas/视觉 UI | | 定位 | 稳定引用 → **自我修复** 引用过期。永不使用原始坐标，永不使用脆弱的 XPath 作为主要引用。 | | 验证 | **每个操作的结构化后条件** 文本台 / 网络） | | 难点 | iframe、影子 DOM、、cookie 横幅、文件上传/下载、多标签页 | | 内存 | **学习每个站点**每个域的持久化选择器，跨会话重放 | | 认证 | 克隆/真实 Chrome 配置文件，一次性 `login`，TOTP 2FA（RFC 6238） | | 受信任的输入 | `isTrusted=true` 点击/按键事件，通过原生（macOS）/ 扩展模式 — 适用于忽略合成输入的网站 | | 自主性 | 规划器 → 导航器 → **验证器** 循环；无头或作为 HTTP 目标服务器运行 | --- ## Tsaagan 与其他工具的比较 浏览器代理空间竞争激烈 — 而 Tsaagan 是一个新的、小型的项目。它并不试图超越[浏览器使用](https://github.com/browser-use/browser-use) 或微软的 [playwright-mcp](https://github.com/microsoft/playwright-mcp)。它在不同的轴上胜出：**您可以审计的。其他工具缺乏的一个 每个操作的证明 — 是 的核心。 | 功能 | Tsaagan | browser-use | stagehand | playwright-mcp | skyvern | |---|:---:|:---:|:---:|:---:|:---: **先验证**（每个操作的后条件 ✅ 核心 | ❌ | ❌ | 视觉 | | **层**（如果网站有 API，则） | ✅ | | ❌ | ❌ | | 自我修复无障碍引用 | ⚠️ | | ⚠️ | | | OS链保险库 +/2FA | ❌ | ❌ | ❌ | ⚠️ 云 | | 跨会话站点内存（语义回忆） | ✅ | ❌ | ⚠️ | ❌ | ❌ | | MCP 服务器 | ✅ | ❌ | ✅ | ✅ | ❌ | | 受信任的输入，无 CDP 调试端口（原生 + MV3） | ✅ | ❌ | ❌ | ❌ | ❌ | | 视觉备用（Set-of-Marks） | ✅ | ✅ | ✅ | ❌ | ✅ | | 本地/离线能力 | ✅ | ✅ | ❌ | ✅ | ❌ | | 模型无关（带上您自己的 LLM） | ✅ | ✅ | ✅ | ✅ | ⚠️ | | 语言 | Node.js | TypeScript | TypeScript | Python | | 许可 | MIT | MIT | MIT | Apache-2.0 | AGPL-3.0 | | 已发布的 WebVoyager 分数 | ⚠️ 进行中 | ✅ ~89%⚠️ | ❌ | ✅ ~86% | | GitHub 星级（2026 年 6 月） | 早期 | ~99k | ~23k | ~34k | ~22k | | 云/托管选项 | ❌ 自托管 | ⚠️ | ❌ Browserbase | ❌ | ✅ | ✅ 支持 · ⚠️ 部分/变通方法 · ❌ 不支持 > **诚实的笔记。** Tsaagan 很年轻 — 拥有较少的星星和没有托管选项，其基准测试分数仍在运行中（跨工具发布的分数使用不同的 WebVoyager 任务子集，不直接可比较）。它独特地提供：每个操作的成功证明、API 优先的快速路径、本地凭证保险库和使用不需要调试端口的受信任输入模式。 --- ## 它如何工作 — 工具、技能还是代理？  Tsaagan 是一个**您可以以多种方式驱动的引擎**: - **工具** — 一个 CLI（`tsaagan.js`）与后台**守护进程**，持有单个持久的 Playwright 页面。这是引擎；其他所有内容都围绕它。 - **作为技能** — 一个简短的指令文件，教您的 AI *如何* 驱动工具（观察 → 操作 → 验证循环）。“使用 Tsaagan 技能” → AI 读取它并一步一步驱动 T。（为 Claude Code 提供了现成的技能/代理。） - **作为代理** — 一个可调度的 worker，它捆绑了技能 + 工具，因此您可以向它提供一个目标，它可以独立运行循环。 - **作为 MCP 服务器或 SDK** — `tsaagan mcp` 向 Claude Desktop / Claude Code / Cursor 公开优先的动词，JS 和 Python SDK 直接调用同一个守护进程。（参见[从 Claude/Cursor 使用（MCP）](#从claude-desktop-claude-code-或cursor-mcp)和[从您自己的代码使用](#从您自己的代码-js--python-sdk)） **谁是“大脑”？** 任何驱动它的程序： | 您用… 驱动它 | 大脑 | 需要 API 密钥 | |---|---|---| | Claude Code（技能/代理） | 您的 Claude 会话 | 无 — 您的 Claude 计划 | | Codex / ChatGPT CLI，Cursor 等 | 该工具的模型 | 该工具的 | | `tsaagan run` / `tsaagan serve`（自主） | **任何** OpenAI 兼容的 LLM — Groq · OpenRouter · OpenAI · Google Gemini · Anthropic · xAI Grok · 本地 | 您选择的提供商的密钥 | Tsaagan 本身在代理驱动时**不进行 LLM 调用** — 它是纯粹的密钥 + 操作 + 验证。仅自主层调用 LLM，它是**您的选择**：Groq（默认，快速OpenRouter** 用于开源模型（Llama、Qwen、DeepSeek、Mistral）、企业供应商 — **OpenAI、Google Gemini、Anthropic、xAI Grok**通过其 OpenAI的端点）— 或任何 OpenAI 兼容的端点（Together、vLLM、**Ollama** 用于完全本地）通过`TSG_LLM_BASE。用`TSG_LLM_PROVIDER=groq|openrouter|opengoogle|anthropic|xai`选择一个。参见 [docs/AGENT.md](docs/AGENT.md#brain-provider)。 ## 与任何编码代理一起使用 Tsaagan 只是一个终端程序，因此任何可以运行 shell 命令的代理都可以驱动它。告诉您的代理类似这样的话： > “使用 Tsaagannode tsa`）登录 并下载我的发票。快照，引用操作，并检查每次操作后的 `verify` 块。” 它将运行 `tsaagan start`、`tsaagan snapshot`、`tsaagan click ref=…`，读取 JSON 结果，然后继续。对于 Claude Code，捆绑的技能/代理使这成为自动化。 --- ## 安装 ```bash git clone https://github.com/michaelolmos/tsaagan.git && cd tsaagan npm install npx playwright install chromium chromium-headless-shell ``` ## 快速亲自驱动） ```bash node tsaagan.js start # 启动浏览器（全新的隔离配置文件） node tsaagan.js goto url=https://example.com expectText="Example" node tsaagan.js snapshot # 无障碍树，带有 [ref=eN] node tsaagan.js click ref=e6 expectText="IANA" node tsaagan.js type ref=e="hello" submit=true node.js stop ``` 添加别名：`alias tsaagan="node $PWD/tsaagan.js"`。 ## 从 Claude Desktop、Claude Code 或 Cursor（MCP）使用 Tsaagan 配备了一个内置的 **MCP 服务器**，因此任何 [Model Context Protocol://modelcontextprotocol.io) 主机都可以直接驱动浏览器。 与其他浏览器 MCP 服务器不同，**每个变更工具都返回 Tsaagan 的 `verify` 块** （URL 更改？控制台错误？预期文本？）— 操作成功的证明，以相同的响应返回，无需额外的快照往返。 **克劳德代码：** ```bash claude mcp add tsaagan -- node /path/to/tsaagan/tsaagan.js mcp # 或，如果您已全局安装 `tsaagan` 二进制文件：claude mcp add tsaagan -- tsaagan mcp ``` **克劳德桌面** (`claude_desktop_config.json`) 或 **Cursor** (`~/.cursor/mcp.json`)： ```json { "mcpServers": { "tsaagan":command": "node", "args":path/to/tsaagan/tsaagan.js", "mcp"] } ``` 服务器在首次使用时**自动启动一个无头守护进程**。它公开了 21 个具有验证优先级的工具 — `tsaagan_navigate`、`tsaagan_snapshot`、`tsaagan_click`、`tsaagan_fill_form`、`tsaagan_extract`、`tsaagan_network`（发现站点的自身数据 API）等。设置 `TSAAGAN_HEADLESS=0` 以观察其工作，或设置 `TSG_TOKEN` 以锁定共享机器上的控制平面。参见 [docs/PROTOCOL.md](docs/PROTOCOL.md)。 ## 从您自己的代码使用（JS 和 Python SDK） 更喜欢以编程方式调用 Tsaagan？两个客户端在**每次**调用时都返回一个 `verify` 块 — 数据 *和* 证明，一起（其他工具使您自己断言）。 **JavaScript / TypeScript** (`sdk/`，零依赖）： ```js import { createTsaagan } from 'tsaagan/sdk'; // 或 '/path/to/tsaagan/sdk/index.mjs' const k = await createTsaagan(); // 自动启动一个无头守护进程 await k.goto('https://example.com', { expectText: 'Example Domain' }); const r = await k.extract('the page heading'); console.log(r.data, r.verify); // 数据 + { urlChanged, expectTextFound, newConsoleErrors, ... } await k.stop(); ``` **Python** (`pip install tsaagan`，零依赖）： ```python from tsaagan import Tsaagan Tsaagan() # 自动启动一个守护进程 k.goto("https://example.com", expect_text="Example Domain") r = k.extract("the page heading") print(r.data, r.verify) k.stop() ``` Python需要 Node进程可访问 — 设置 `TSA_JS=/path/toagan.js将 `tsaagan` 二进制文件放在 PATH 中。参见 [clients/python/](clients/python/)。 ## 自主模式 ```bash export GROQ_API_KEY=... # 自主大脑（默认快速） ``` …或任意其他提供商 — 请命名并提供该提供商的密钥： ROUTER_API_KEY=... TSG_LLM_PROVIDER=openrouter # 开源模型 export OPENAI_API_KEY=... TSG_LLM_PROVIDER=openai # GPT-4o / o 系列 export_API_KEY=... TSG_LLM_PROVIDER=google # Gemini export ANTHROPIC_API_KEY=... TSG_LLM_PROVIDER=anthropic # Claude export XAI_API_KEY=... TSG_LLM_PROVIDER=xai # Grok export TSG_LLM_BASE_URL=http://localhost:11434/v1/chat/completions # Ollama，完全本地 node tsaagan.js run goal="前往 news.ycombinator.com 并报告 #1 故事标题 tsaagan.js journal # 它之前的操作记录（持久记忆） ## 按角色划分的模型覆盖 按角色划分的模型覆盖适用于任何提供商：`TSG_PLANNER_MODEL`、`TSG_NAV_MODEL`、`TSG_VALIDATOR（例如，将规划器指向更强大的模型以进行推理，同时快速模型处理导航）。 ## 独立服务器（无代理框架） ```bash node tsaagan.js serve port=39820 curl -s localhost:39820/goal -H 'content-type: application/json' -d '{"goal":"...","max":16}' ``` ## 基准测试 ```bash node tsaagan.js bench # 自主任务套件 + 确定性能力矩阵 ``` 最新运行（Groq Brain，4 任务套件）： | 指标 | 结果 | |---|---| | 任务成功率 | 3/4 (75%) | | **自我修复** （从过时引用中恢复） | ✅ 通过 | | **视觉标记集** | ✅ 通过 | | **结构验证** （后条件） | ✅ 通过 | 直接可比较的 WebVoyager 分数正在进行中 — 请参阅 [bench/METHODOLOGY.md](bench/METHODOLOGY.md) 以了解其运行和报告方式（主页启动，无后验判断覆盖，发布的任务集）。 ## 命令参考 | 命令 | 描述 | |---|---| | `start [mode=fresh\|clone\|live] [headless=true] [port=]` | 启动 / 附加浏览器 | | `status` · `stop` | 状态 · 关闭 | | `snapshot [full=true]` · `snapshot mode=vision` | a11y 树及其引用 · 编号视觉叠加层 | | `goto url=..Text=..]` | 导航 + 验证 | | ref=eN\|som=N\|selector=..\|text [key=..] [expectText=..]Gone=..] [expectUrl=..]` | 点击 + 验证 + 自我修复 | | `type ref=eN text=".." [key=..] [submit=true] [expectText=..]` | 清除 + 输入 | | `select` · `press keys=".." [expectText=..]` · `scroll [direction=\|to_text=]` · `wait_for [..]` | 交互 | | `upload_file ref=\|selector= path=a,b` · `handle_dialog accept=true` ·_overlays` · `downloads` | 困难情况 | | `extract [query=..]` · `screenshot [path=] [fullPage=true]` | 读取页面 | | `tabs` · `switch_tab` · `new_tab url=..` · `close_tab` · `back` · `forward` | 标签页 / 历史记录 | | `remember key=.. selector=.. [note=..]` · `recall` · `forget` | 学习站点（按域名记忆） | | `login=.. passSelector=.. [submitSelector=..] [totpSelector=.. totpSecret= | 一次性登录 + 2FA | |p secret=$TSG_TOTP_SECRET` · `detect_captcha` | 2FA 代码 · 检测 CAPTCHA/反滥用墙 → 移交给人类 | | `paste text=".." [ref=\|selector=] [submit=true]` · `type_human` · `key_human keys="return"` | **OS 级macOS）** — 受（`isTrusted=true`）按键 / 粘贴，适用于忽略合成输入的站点 | | `pace set=human\|slow\|fast` · `click_xy x= y=` · `keychain service= account=` | 节奏控制器 · 坐标点击 · macOS 密钥链秘密 | | `record_start name=..` · `record_stop [path=..]` · `replay path=..` · `report [format=json\|md]` | 记录/重放已验证的序列 · 导出审计报告 | | `doctor` · `protocol` | 本地诊断 · JSON 模式 / TypeScript 操作协议路径 | | `run goal=".." [max=16]` · `serve [port=]` · [n=]` · `bench` | 自主性 | | `network [filter=] [limit=]` | 捕获的 XHR/fetch + 响应（发现站点的内部 API） | | `cookies [set=<json>]` | 导出 / 导入 cookie（会话重用） | | `pdf [path=]` · `assert=] [url=selectorVisible=]`页面 PDF · 验证检查 | | `=".."` · `console_log [limit=]` | 出口 · 调试 | 还包括 `proxyuser:pass@host:port` （例如， corp 代理），`channel=chrome\|chromium`，`pace=fast\|slow\|human` （礼貌），`timezone=`。 ### 层和代理命令 | 命令 | 描述 | |---|---| | `vault set service=.. secret=.. [account=..]` · `vault get/list/delete` | 密钥链加密密钥存储（密钥从不触及磁盘） | | `api service=.. path=/.. [method=] [body=]` · `api detect=<url>` · `api providers` | 使用存储的密钥调用官方 API（第 1 层） | | `ext-setup [profile=fresh\|clone] [browser=chrome]` | **零步骤扩展模式**：使用伴侣扩展启动 Chrome for Testing + 自动加载并启动 `mode=extension`。（`browser= 指向您命名的 Chrome — 需要一次性手动加载，因为 Chrome 137+ 阻止 `--load-extension`。） | | `brain` · `brain recall query=..` · `brain advise domain=..` · `brain synthesize domain=..` | 演化 SQLite 内存：统计 · 语义回忆 · 它所知道的 · 压缩课程→规则 | | `advise [domain=..] [query=..]` | Tsaagan 关于站点的学习内容（也自动显示在每个 `snapshot.memory` 中） | | `journal [n=]` | 最近的自主运行历史记录 | ### 记录、重放和报告 ```bash tsaagan record_start name=weekly-report tsaagan goto url=https://example.com expectText="Example" tsaagan click ref=e6 expectText="IANA" tsaagan record_stop # 写入 ~/.tsaagan/records/*.json tsaagan replay path=/Users/me/.tsaords/... tsaagan report format=md # 写入 ~/.tsaagan/reports/*.md ``` 记录捕获成功的动作，并附有结构化 `verify` 证据，并存储稳定的角色/名称目标，当步骤最初由 a11y `ref` 地址时，因此重放较少地依赖于一个瞬时的浏览器快照。报告总结动作、失败、验证块、失败请求和人工交接时刻以供审计或调试。 ### 诊断和协议 ```bash tsaagan doctor # 本地安装/配置健康检查 tsaagan protocol # protocol/actions.schema.json + protocol/tsaagan.d.ts 的路径 ``` `doctor` 不会启动浏览器；它会检查本地先决条件、扩展文件、保险库后端可用性、守护进程可达性和共享主机令牌姿势。 ### 接地优先级 `ref`（来自全新快照）→ `selector`（稳定 CSS）→ `text` → `som视觉）。永不坐标。 ### 模式 - **fresh** （默认）— 隔离的真实 Chrome（`channel: chrome`）及其自己的配置文件。CDP。 - **clone** / ** — 通过 `--remote-debugging-port=9222` 启动的 Chrome 连接到 CDP。 - **native** （macOS）— 真实的 Chrome，**无 CDP** （AppleScript + OS 级输入）。适用于站点忽略合成输入的场合。参见上面的“可靠性”。 - **extension** （任意操作系统）— 通过伴侣扩展（`chrome.debugger` 输入 → **isTrusted=true，视口坐标，无调试端口，无坐标数学**）使用 Chrome。一步（`ext-setup`），零手动步骤；E2E 验证 — 页面监听 `event.isTrusted === true`。在忽略合成输入的站点上最可靠。参见 [docs/EXTENSION.md](docs/EXTENSION.md)。 ### 环境 **大脑（自主模式，选择一个）：** 提供者密钥 — `GROQ_API_KEY` · `OPENROUTER_API_KEY` · `OPENAI_API_KEY` · `GEMINI_API_KEY`/`GOOGLE_API_KEY` · `ANTHROPIC_API_KEY` · `XAI_API_KEY`/`GROK_API_KEY` — 或 `TSG_LLM_BASE_URL`（+ `TSG_API_KEY`）适用于任何 OpenAI 兼容端点 · `TSG_LLM_PROVIDER=groq|openrouter|openai|google|anthropic|xai` 以命名一个 · 模型覆盖 `TSG_PLANNER_MODEL` / `TSG_NAV_MODEL` / `TSG_VALIDATOR_MODEL`（旧版 `GROQ_*_MODEL` 仍受支持）。 **其他：** `TSG_USER` / `TSG_PASS` / `TSG_TOTP_SECRET` （登录）· `TSG_PORT` （守护进程端口）· `TSG_EMBED_URL` （语义召回的嵌入端点）。状态存活在 `~/.tsaagan/` 中。 ## 架构 ``` tsaagan.js ── 薄 CLI ──▶ daemon.js （一个持久的 Playwright 页面；HTTP 控制平面） │ 感知 · 接地 · 动作 · 验证 · 自我修复 agent.js ── 规划器→导航器→验证器循环（通过 lib/llm.js 实现与 LLM 无关）+ 任务内存 run.js ── 一次性自主运行 server.js ── 独立 HTTP 目标服务器 bench.js ── 能力基准测试守护进程持有单个长期页面，以便 a11y 树引用在离散 CLI 调用中保持有效，并且验证/自我修复在服务器端运行，具有完整的页面状态。 ## 输入模式 — 以及为什么受信任的输入很重要 Tsaagan 有三种方法来驱动浏览器。之所以有多种方法，纯粹是出于**正确性**：DOM 事件有一个 `isTrusted` 标志，只有在真正的用户输入时才为 `true`，而一些构建良好的站点会忽略合成点击/按键以确保其自身的完整性 — 因此您的*授权*自动化会默默地无所作为。本地和扩展模式提供 `isTrusted=true` 输入，以便您的代理的操作实际生效。 **CDP 模式（默认）** — Playwright 驱动 Chrome。快速、功能齐全、并行，适用于 **绝大多数网页** （仪表板、SaaS、内部工具）。使用真正的 Chrome 二进制文件。这里的输入为 `isTrusted=false`，因此很少有严格的站点会忽略它 — 这就是为什么需要其他两种模式。 **本地模式（macOS）** — `tsaagan start mode=native`。驱动您的 **真实 Chrome，无调试端口**：通过 AppleScript 进行感知，通过真正的 OS 级鼠标/键盘（`cliclick`）进行 `isTrusted=true`。权衡：仅限 macOS · 较慢 · 单个前窗口坐标/视觉接地。需要 `brew install clic + Chrome ▸ 视图 ▸ 开发者 ▸ “允许 JavaScript 访问 Apple 事件”。 **扩展模式（任意操作系统）** — `tsa-setup`。伴侣扩展通过 `chrome.debugger `is` 点击，位于视口坐标 — 最干净的输入路径。参见 [docs/EXTENSION.md](docs/EXTENSION.md)。 ```bash brew install cliclick # 一次性 tsaagan start mode=native # 驱动您当前的最前面的 Chrome tsaagan snapshot # AppleScript 感知（元素 + 屏幕坐标） tsaagan click i=5 # 真实的 OS 级受信任点击 tsaagan paste text="..." submit=true 剪贴板 + 真实 ⌘V + 回车 ``` ## 自我学习和记忆 Tsaagan 在 `~/.tsa 下保持一个小型本地内存： -内存** (`memory/<domain>.json`)选择器和笔记。 Tsaagan **自动捕获** 选择器，当操作成功时（无需手动您也可以通过 `remember` / `recall`forget` 显式教导它。 - **自动学习课程** — 如果站点显示反滥APTCHA/“异常活动”墙saagan **自动** 编写站点备注并为 `pace: "human"`，以便未来运行减慢并更喜欢 OS 级输入 **任务日志** (`agent/journal.jsonl`) — 每个自主运行都被记录； `tsaagan journal` 显示最近的历史记录。`agent/learnings.json` 包含提炼的笔记。 这是一个刻意为 **狭窄、透明、基于文件** 的内存，您可以读取和编辑 — 不是一个不透明的自我重写代理。推理/智能仍然存在于驱动它的任何 AI 中。 ## 安全性和局限性（请阅读本节） ### 合理使用和免责声明 Tsaagan 是一个 **生产力工具** — 它允许您的 AI像 *您* 一样在浏览器中操作，执行您有权使用的任务和帐户，这样您可以将工作流程中的重复部分移交给代理。 它 **不** 用于破坏安全、解决 CAPTCHA、规避封禁、大量抓取或任何服务条款的行为。 当 Tsaagan 遇到 CAPTCHA 或反滥用墙时，它会 **停止并将控制权交还给您**。 请在授权、归属并在每个站点的条款内使用。 > **免责声明。** Tsaagan 按照原样提供，不附带任何保证（参见 [LICENSE](LICENSE)）。 **您对如何使用它以及遵守所有适用法律和您操作的每个站点的条款** 承担全部责任。 仅自动执行 **您拥有或有权访问** 的帐户和系统。 作者 **不承担滥** 。 请在开始前阅读 [可接受使用政策](AC_USE.md)。 Tsaagan 驱动一个 **具有真实权限的真实浏览器** 。 请谨慎： - **它可以采取真实操作** （发送、购买、删除指向登录配置文件时。 默认使用隔离的 `fresh` 配置文件；需要对重要逆步骤进行人工确认。 - **提示是真实的。** 网页不受信任尝试劫持驱动模型。 将页面内容视为数据；不要遵循页面上的指令。 - **服务条款和反滥用。** 自动化站点可能会违反其服务条款并触发反机器人防御 — 这可能会 **限制速率、标记或禁止您的真实帐户** 。 合理使用，在您有权自动化的站点/帐户上使用。 Tsaagan 检测滥用墙并移交给人类；它 **不** 解决 CAPTCHA。 - **类似人类 ≠ 不可见。** 像真实用户一样行为可以提高可靠性，但复杂系统仍然可以检测到它是自动化。 它不是绕过禁令的方法，也不是为了实现这一点 — 请在授权并在每个站点的条款内使用。 - **自主模式将页面文本发送到您选择的 LLM 提供商** （Groq / OpenRouter / 自定义 — 第三方除非您自行托管）。 代理驱动模式在您的 AI 会话中保留页面内容。 - **`eval` 运行任意 JS** 在页面中，克隆配置文件在磁盘上保存真实 cookie。 请谨慎处理两者。 **切勿提交凭证** — 使用 env 或密钥链。 - **OS 级输入（`paste`/`type_human`）仅限 macOS** ，需要一个有标题的、位于前面的浏览器。 Tsaagan 在 MIT 许可下作为-is 提供的，不附带。 您对如何使用它负责。 ## 文档 | 文档 |---|---| | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 深入探讨：守护进程、感知、接地、验证、自我修复、内存、引擎、本地模式 | | [docs/RE.md](docs/RELIABILITY.md) | 输入模式和为什么受信任的输入对于可靠、正确的自动化很重要 | | [docs/EXTENSION.md](docs/EXTENSION.md) | 扩展模式：受信任的、跨平台的、无坐标数学的浏览器控制 | | [docs/API.md](docs/API.md) | API 层：密钥链保险库 + 身份验证调用 + 浏览器启动密钥设置 | | [docs/AGENT.md](docs/AGENT.md) | 代理层：SOUL/AGENTS/HEARTBEAT 身份 + SQLite 大脑内存和演化 | | [docs/PROTOCOL.md](docs/PROTOCOL.md) | JSON 操作协议、模式和 TypeScript 声明 | | [docs/RECIPES.md](docs/RECIPES.md) | 复制粘贴配方：登录 + 2FA、仪表板、API 发现、站点拒绝天真自动化 | | [docs/BUILD_JOUR](docs/BUILD_JOURNAL.md) | Tsaagan 的构建过程 —决策和每个功能波 | | [ROADMAP.md](ROADMAP.md) | 下一步计划 | | [CHANGELOG.md](CHANGELOG.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md) | 版本 · · 安全策略 | ## 致谢 由 **Michael Olmos** 创建。贡献欢迎 — 参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可 MIT — 参见 [LICENSE](LICENSE)。