wyofalcon/sciurus

# Sciurus! — AI 驱动的知识捕获工具 **Sciurus**（拉丁语：*squirrel*）——亦意为*影子*与*尾巴*。 由一位多动症（ADHD）患者构建，旨在提供一种在任务进行中暂存知识的方式，而不会丢失思路。就像一只松鼠在奔向下一棵树之前埋下橡果，Sciurus 让你只需一个快速动作就能捕获屏幕上的内容——截图、笔记、完成——然后相信 AI 会帮你整理。影子与尾巴的含义也很贴切：每个想法都会投下你希望再次找到的影子，而这个工具就是跟随你思路的尾巴，让你不必担心遗忘。 ### 为使用 AI 构建应用的开发者而生 当你使用 AI 辅助编码工具进行调试和开发时，经常会快速连续遇到多个问题——这里一个布局崩坏，那里一个 API 调用失败，还有一个边缘情况等你修复第一个问题时就忘了。Sciurus 正是为此而构建的。发现问题时截图，添加快速笔记，然后继续。AI 在后台整理一切，让你之后可以带着清晰的列表回顾，而不是模糊的记忆。当你使用单屏幕笔记本电脑工作时尤其有用，因为你无法在应用、终端和笔记文档之间进行上下文切换。 ## 工作原理 1. 使用 **Windows 截图工具**（`Ctrl+Win+S`）截图——或任何复制到剪贴板的工具 2. Sciurus 通过剪贴板监视器**自动检测**新截图（1 秒轮询） 3. 捕获弹出窗口显示截图预览 4. **窗口上下文自动捕获**——在弹出窗口打开前获取活动窗口标题和进程名称 5. 输入快速笔记，可选择选择分类和项目 6. **规则引擎优先运行**——通过仓库路径和窗口标题自动匹配项目 7. **AI 备用方案**——如果规则未能分类，Gemini 2.5 Flash 会分析截图和笔记 8. 在标签页笔记查看器中浏览、搜索和管理剪贴内容 ## 功能特性 - **剪贴板监视器**——自动检测新截图（1 秒轮询） - **窗口元数据捕获**——通过 Win32 API（Windows）或 xdotool/gdbus（Linux）获取活动窗口标题和进程名称 - **基于规则的分类**——通过仓库路径、自定义模式规则（带优先级）自动分配项目 - **Gemini 视觉 AI**——分析截图和笔记以进行智能分类（可选） - **标记颜色语义**——红色 = 错误，绿色 = 已批准，粉色 = 问题（AI 读取你的注释） - **AI 搜索**——跨所有剪贴内容的自然语言搜索 - **一键项目摘要**——为侧边面板中的所有项目笔记生成可操作的 AI 修复提示，并支持一键复制全部 - **摘要追踪**——笔记在每次被包含在摘要中时会逐渐变暗，计数器徽章显示被摘要的次数 - **内联 AI 提示**——AI 生成的修复提示和摘要直接显示在剪贴卡片上，支持一键复制到剪贴板 - **单剪贴 AI 重新触发**——手动对任何剪贴内容重新运行 AI 分类 - **完成/回收站系统**——将笔记标记为完成（保持可见或移至回收站），支持从回收站恢复 - **标签管理**——为每个剪贴内容添加/移除标签（从现有标签中选择或创建新标签），在侧边栏按标签筛选 - **排序**——按最新、最旧或标签 A-Z 排序笔记 - **双数据库后端**——PostgreSQL（Docker）面向高级用户，SQLite（内置）面向零配置用户 - **磁盘图像存储**——截图保存到文件系统，不会膨胀数据库 - **项目组织**——按项目分组剪贴内容，提供专用视图 - **通用笔记 + 项目标签页**——标签页界面实现有序浏览 - **系统托盘**——在后台静默运行 - ** threaded 评论**——为任何剪贴内容添加后续笔记 - **设置向导**——三步首次运行流程：数据库、AI 配置、启动 - **设置面板**——在应用内配置捕获、AI 和应用行为 - **跨平台**——Windows、Linux（AppImage、deb）、macOS（开发支持） - **Lite 模式**——可切换的简化 UI，用于活跃开发期间的快速迭代（见下文） - **浮动注释工具栏**——在捕获前用红色/绿色/粉色在屏幕上绘制和添加文本 - **AI 提示生成**——带注释的截图生成带有项目上下文的可操作编码提示 - **IDE 中活跃项目追踪**——标记哪些项目当前在 IDE 中打开 - **工作流上下文桥接**——AI 提示包含当前分支、最近提交和项目 `.ai-workflow/` 目录中的审计发现 ## Lite 模式 Lite 模式将 Sciurus 简化为一个专注快速迭代的工具。与其捕获笔记供以后回顾，你在屏幕上注释，输入需要更改的内容，然后获得可以直接粘贴到 AI 编码工具中的 AI 生成提示。 ### 激活 右键点击 Sciurus 托盘图标 → **切换到 Lite 模式**。以相同方式切换回来。 ### 工作原理 1. 在侧边栏**选择你的活跃项目**（所有捕获都发送到此项目） 2. 从托盘菜单打开**工具栏**——一个带有颜色点和文本工具的浮动栏 3. **在屏幕上注释**——用红色（移除）、绿色（添加）或粉色（参考）绘制或输入 4. **截取片段**或按 `Ctrl+Shift+Q` 5. 出现一个最小的捕获弹出窗口——输入需要更改的内容，然后点击**保存并生成提示** 6. AI 根据你的注释 + 笔记 + 项目上下文生成可操作的编码提示 7. 复制提示并粘贴到 Claude Code、Copilot 或任何 AI 编码工具中 ### 与完整模式的区别 | | 完整模式 | Lite 模式 | |---|---|---| | **标签页** | 通用笔记、项目、工作流、设置、帮助 | 仅项目 | | **项目选择** | 可选——剪贴内容可以未分配 | 必需——一次一个活跃项目 | | **捕获弹出窗口** | 分类选择器、项目选择器、标签 | 笔记字段 + 保存按钮 | | **AI 输出** | 分类、标签、摘要、URL、修复提示 | 摘要 + 专注编码提示 | | **剪贴筛选** | 所有剪贴内容可见 | 仅活跃项目的 lite 模式剪贴内容 | ### 注释颜色 AI 理解你的颜色编码注释： - **红色**——移除、删除或修复标记的内容 - **绿色**——在此位置添加或创建内容 - **粉色**——参考点（识别需要上下文的某些内容，可能需要或不需要更改） 当注释冲突时，**你输入的笔记优先于注释**。 ### 工具栏快捷键（绘制模式下） | 按键 | 操作 | |---|---| | `1` / `2` / `3` | 切换到红色 / 绿色 / 粉色 | | `T` | 切换文本模式（点击放置，输入，回车提交） | | `S` | 截取片段（区域选择） | | `右键点击` | 退出绘制模式 | | `Escape` | 退出绘制模式 | ## 前置条件 | 要求 | 版本 | 备注 | |---|---|---| | **Node.js** | 18+（推荐 22） | [nodejs.org](https://nodejs.org) 或使用 `nvm` / `fnm` | | **npm** | 9+ | 随 Node.js 一起提供 | | **Git** | 2.x | [git-scm.com](https://git-scm.com) | | **Docker** | 20+（可选） | 仅在使用 PostgreSQL 后端时需要 | | **Python** | 3.x（可选） | 在某些系统上需要 `node-gyp` 来编译原生模块 | ### 平台特定要求

Windows

- **构建工具**——需要编译 `better-sqlite3`（原生模块）： # 选项 A：Visual Studio Build Tools（推荐） winget install Microsoft.VisualStudio.2022.BuildTools # 选项 B：通过 npm（自动安装） npm install --global windows-build-tools - **PowerShell**——预安装。用于活动窗口捕获（通过 P/Invoke 调用 Win32 API）。无需配置。 - **Docker Desktop**——如果使用 PostgreSQL，从 [docker.com](https://www.docker.com/products/docker-desktop/) 安装。

Linux（Ubuntuebian）

- **构建工具**——需要编译原生模块： sudo apt update sudo apt install build-essential python3 libsqlite3-dev - **窗口元数据捕获**——用于通过活动窗口自动分类： # X11 / WSLg（推荐） sudo apt install xdotool # Wayland + GNOME——通过 gdbus 自动工作（无需额外安装） 没有 `xdotool`，应用仍然可以工作——只是无法从窗口标题自动匹配项目。 - **Docker Engine**——如果使用 PostgreSQL，从 [docs.docker.com](https://docs.docker.com/engine/install/) 安装。

macOS

- **Xcode Command Line Tools**——需要编译原生模块： xcode-select --install - **Docker Desktop**——如果使用 PostgreSQL，从 [docker.com](https://www.docker.com/products/docker-desktop/) 安装。 - **注意：** macOS 上尚未实现窗口元数据捕获。应用完全可用，但无法通过窗口标题自动分类。

## 设置 ### 快速开始（新用户） ``` git clone https://github.com/wyofalcon/sciurus.git cd sciurus npm install npm start ``` **设置向导**在首次运行时自动启动，引导你完成： 1. 检测 Docker 或提供内置 SQLite 数据库（无需 Docker） 2. 帮助你设置 AI（可选——免费 Gemini API 密钥或 GCP Vertex AI） 3. 启动应用 ### 开发模式 ``` npm run dev ``` 这会设置 `SCIURUS_DEV=1`，在启动时自动打开 DevTools。 ## 数据库设置 ### 选项 A：SQLite（零配置） 无需 Docker，无需配置。在 `.env` 中设置或跳过 Docker——应用会自动回退： ``` DB_BACKEND=sqlite ``` 数据库文件存储在 `{userData}/sciurus.db`： - **Windows：** `%APPDATA%/sciurus/sciurus.db` - **Linux：** `~/.config/sciurus/sciurus.db` - **macOS：** `~/Library/Application Support/sciurus/sciurus.db` ### 选项 B：PostgreSQL（Docker） ``` docker compose up -d ``` 这会启动 Postgre 16 Alpine（`sciurus-db`）在 **端口 5433**（不是默认的 5432，以避免冲突）。数据保存在 Docker 卷中。 默认连接（无需更改 `.env`）： | 设置 | 值 | |---|---| | 主机 | `localhost` | | 端口 | `5433` | | 数据库 | `sciurus` | | 用户 | `sciurus` | | 密码 | `sciurus_dev` | 使用自定义密码： ``` # 在 .env 中或作为启动 Docker 前的环境变量 POSTGRES_PASSWORD=your_secure_password ``` `docker/init.sql` 脚本在首次容器启动时自动运行，创建所有表、索引、触发器和种子数据。 ## AI 设置（可选） AI 功能是可选的。规则引擎可以在没有 AI 的情况下处理大多数分类。 ### 选项 A：Gemini API 密钥（推荐——免费套餐） 1. 前往 [Google AI Studio](https://aistudio.google.com/apikey) 2. 创建 API 密钥 3. 添加到 `.env`： AI_AUTH_MODE=apikey GEMINI_API_KEY=AIzaSy... ### 选项 B：Vertex AI（GCP 服务账户） 1. 在 GCP 项目中启用 Vertex AI API 2. 创建具有"Vertex AI 用户"角色的服务账户 3. 下载 JSON 密钥并保存为项目根目录下的 `credentials.json` 4. 添加到 `.env`： AI_AUTH_MODE=vertex 应用使用原生 JWT 认证进行 Vertex AI——无需重型 Google SDK 依赖。 ## 环境变量 复制示例文件并进行自定义： ``` cp .env.example .env ``` | 变量 | 默认值 | 描述 | |---|---|---| | `DB_BACKEND` | `auto` | `pg`、`sqlite` 或 `auto`（先尝试 pg 然后 sqlite） | | `POSTGRES_HOST` | `localhost` | PostgreSQL 主机 | | `POSTGRES_PORT` | `5433` | PostgreSQL 端口 | | `POSTGRES_DB` | `sciurus` | PostgreSQL 数据库名 | | `POSTGRES_USER` | `sciurus` | PostgreSQL 用户 | | `POSTGRES_PASSWORD` | `sciurus_dev` | PostgreSQL 密码 | | `AI_AUTH_MODE` | `auto` | `apikey`、`vertex` 或 `auto` | | `GEMINI_API_KEY` | — | Gemini API 密钥（用于 `apikey` 模式） | | `HOTKEY_COMBO` | `ctrl+shift+q` | 手动捕获的备用快捷键（主要：剪贴板监视器） | | `SCIURUS_DEV` | — | 设置为 `1` 以在启动时打开 DevTools | ## 构建 ### Windows 安装程序（.exe） ``` npm run build:win ``` ### Linux（AppImage + .deb） ``` npm run build:linux ``` ### macOS（.dmg） ``` npm run build:mac ``` ### 所有平台 ``` npm run build ``` ### 无安装程序打包（用于测试） ``` npm run pack ``` 构建输出到 `dist/`。 ## 分类优先级链 当你保存剪贴内容时，Sciurus 按以下顺序尝试分类： 1. **你的手动选择**——始终优先 2. **仓库路径自动匹配**——如果窗口标题包含项目的仓库文件夹名称 3. **用户窗口规则**——对窗口标题或进程名称的自定义模式匹配 4. **进程映射**——内置的进程→分类查找（例如 `code` → 开发工具，`chrome` → 网页） 5. **标题关键词**——匹配窗口标题中的已知术语 6. **评论关键词**——匹配用户笔记中的已知术语 7. **AI 备用方案**——Gemini 分析截图 + 笔记 + 窗口上下文 大多数剪贴内容通过规则 2-6 立即分类，无需 AI 调用。 ## 项目结构 ``` sciurus/ ├── src/ │ ├── main.js # Electron main process — tray, hotkey, IPC, capture flow │ ├── preload.js # Context bridge for renderer (contextIsolation: true) │ ├── db.js # Database switcher (PostgreSQL or SQLite) │ ├── db-pg.js # PostgreSQL backend (pg) │ ├── db-sqlite.js # SQLite backend (better-sqlite3) │ ├── ai.js # Gemini AI — categorize, search, summarize, lite prompts (native JWT auth) │ ├── rules.js # Rule-based categorization engine with in-memory cache │ ├── window-info.js # Cross-platform active window capture (Win32/xdotool/gdbus) │ ├── images.js # Disk-based image storage + AI compression │ └── workflow-context.js # Reads SESSION.md/AUDIT_LOG.md from project repos ├── renderer/ │ ├── index.html/js/css # Main window — tabbed viewer (full + lite modes) │ ├── capture.html/js/css # Full capture popup — screenshot + note + category/project │ ├── lite-capture.html/js/css # Lite capture popup — screenshot + note + generate prompt │ ├── toolbar.html/js/css # Floating annotation toolbar (red/green/pink + text tool) │ ├── overlay.html/js/css # Fullscreen transparent draw/text overlay │ └── setup.html/js/css # First-run setup wizard ├── scripts/ │ ├── launch.js # Electron launcher (fixes ELECTRON_RUN_AS_NODE in VS Code shells) │ └── get-window.ps1 # Windows PowerShell window info script (auto-generated) ├── docker/ │ └── init.sql # PostgreSQL schema, indexes, triggers, seed data ├── assets/ # App icons (icon.ico, icon.png) ├── docker-compose.yml # PostgreSQL 16 Alpine container ├── .env.example # Example environment config ├── .env # Your config (git-ignored) ├── credentials.json # Google service account key (git-ignored) └── package.json ``` ## 架构 | 层级 | 技术 | 备注 | |---|---|---| | **运行时** | Electron 33 | 上下文隔离的渲染器，无 `nodeIntegration` | | **数据库** | PostgreSQL 16 或 SQLite | 自动检测；启动时运行迁移 | | **图像存储** | 文件系统 | `{userData}/images/{clipId}.png`；AI 调用时压缩为 JPEG | | **AI** | Gemini 2.5 Flash | API 密钥或 Vertex AI（原生 JWT，无 SDK 依赖） | | **规则** | 内存中 | 窗口标题 + 进程名称匹配，正则支持，5 分钟缓存 | | **窗口信息** | OS 原生 | Win32 P/Invoke、xdotool（X11）、gdbus（Wayland+GNOME） | | **构建** | electron-builder | NSIS（Windows）、AppImage + deb（Linux）、dmg（macOS） | ### 安全与健壮性 - **上下文隔离的渲染器**——`contextIsolation: true`，无 `nodeIntegration` - **输入清理**——`.env` 写入验证密钥格式并剥离换行符以防止注入 - **API 超时**——所有 Gemini API 调用设置 30 秒中止以防止挂起 - **安全的 JSON 解析**——数据库行解析包装在 try-catch 中，带有回退默认值 - **受保护的异步**——后台 AI 调用包含 `.catch()`，并发搜索请求去重 ## 故障排除 ### `npm install` 在 `better-sqlite3` 上失败 这是一个需要 C++ 编译的原生模块： - **Windows：** 安装 Visual Studio Build Tools（`winget install Microsoft.VisualStudio.2022.BuildTools`） - **Linux：** 运行 `sudo apt install build-essential python3` - **macOS：** 运行 `xcode-select --install` 然后重试 `npm install`。 ### 应用作为纯 Node.js 启动（无窗口） VS Code 和 Claude Code 终端会设置 `ELECTRON_RUN_AS_NODE=1`。启动脚本（`scripts/launch.js`）会自动取消设置此变量，但如果你直接运行 Electron： ``` # 改用启动脚本 npm start # 或手动取消设置 unset ELECTRON_RUN_AS_NODE && npx electron . ``` ### Docker 数据库无法连接 ``` # 检查容器是否正在运行 docker ps --filter name=sciurus-db # 检查健康状态 docker inspect sciurus-db --format "{{.State.Health.Status}}" # 查看日志 docker logs sciurus-db # 重启 docker compose down && docker compose up -d ``` 默认端口是 **5433**（不是 5432）。检查你的 `.env` 是否匹配。 ### 窗口捕获不工作（Linux） ``` # 为 X11 / WSLg 安装 xdotool sudo apt install xdotool # 验证其是否正常工作 xdotool getactivewindow getwindowname ``` 在 Wayland + GNOME 上，`gdbus` 会自动使用。其他 Wayland 合成器尚未支持。 ### AI 无法分类 1. 检查凭据是否已配置：在终端中查找 `[AI] Gemini API key ready` 或 `[AI] Vertex AI ready` 2. 验证 `.env` 包含 `AI_AUTH_MODE` 和 `GEMINI_API_KEY` 或 `credentials.json` 3. 主窗口中的 AI 栏显示分类状态 . AI 是可选的——规则引擎和手动分类可以在没有 AI 的情况下工作 ## 提示：轻松捕获 Sciurus 在捕获毫不费力时效果最佳——一键完成，无需思考。 按 `Ctrl+Win+S` 打开 Windows 截图工具，选择一个区域，Sciurus 会自动从剪贴板获取。或者使用内置的**工具栏**直接在屏幕上绘制注释并截取片段——无需外部工具。AI 读取你的颜色编码注释（红色 = 移除，绿色 = 添加，粉色 = 参考）并生成可操作的提示。在 **Lite 模式下**，整个流程都针对此进行了优化：注释 → 捕获 → 获取提示 → 粘贴到你的 AI 编码工具。 ## 许可证 私人项目。保留所有权利。

标签：ADHD友好, AI分类, Electron, Gemini, MITM代理, PostgreSQL, SQLite, 上下文感知, 云计算, 任务管理, 信息归档, 剪贴板监听, 威胁情报, 屏幕截图, 开发者工具, 截图工具, 效率工具, 数据可视化, 桌面应用, 测试用例, 知识捕获, 知识管理, 窗口检测, 笔记应用, 自动化整理, 自定义脚本, 规则引擎, 项目整理