From 4294bb6a80a383cde264a31b0ebc4f5efcc67b7c Mon Sep 17 00:00:00 2001 From: Shangxin Date: Fri, 16 Oct 2026 16:53:42 +0000 Subject: [PATCH] docs: reposition project as personal proactive agent for engineering and daily workflows --- README.md | 108 ++++++++++++++++++++++++++++--------------------- README_zh.md | 112 +++++++++++++++++++++++++++++---------------------- 2 files changed, 124 insertions(+), 96 deletions(-) diff --git a/README.md b/README.md index 12f29a9..5d8366a 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -# 🊑 Squid — The Ambient Desktop AI Assistant +# 🊑 Squid — The Ambient Desktop Autonomous Agent

- An ambient, persistent desktop companion with perception and memory.
+ An ambient, persistent desktop AI companion with perception and memory for your daily work and engineering workflows.
Observes your workspace quietly. Synthesizes context deeply. Acts decisively. Governed by you.

@@ -14,7 +14,7 @@ Bun Slint Platform - Pi Agent + Autonomous Personal Agent Tests License

@@ -23,39 +23,52 @@ ## 💡 What is Squid? -Most AI tools today are **passive chat boxes**: you hit an error, copy-paste terminal outputs, re-explain your project architecture for the tenth time, and coax the model into understanding what you were doing. +Most AI tools today are **passive chat boxes**: +Whether you are analyzing business data, reconciling deliverables across software, drafting documents, or running automation scripts and engineering pipelines, hitting a roadblock forces you to break your flow — switching windows, taking screenshots, copy-pasting error traces or project briefs, and re-explaining for the tenth time what you were doing. **Squid flips this paradigm.** -Squid is an **ambient, long-lived desktop AI companion** built on the [Pi agent runtime](https://github.com/earendil-works/pi-ai). Instead of waiting for you to copy-paste context, Squid quietly runs in your background and perceives your workstation activity in real time: -- The project files you save in your editor -- The commands you run in your shell and their exit codes -- The active window, focused UI control, and selected text on your screen -- The API reference or GitHub issue you are reading in your browser +Squid is an **ambient, long-lived desktop personal AI companion** built on the [Pi agent runtime](https://github.com/earendil-works/pi-ai). It is **not merely a coding agent designed for writing code**, but a proactive companion built for **engineering tasks, digital workflows, and everyday personal productivity**. Running quietly in the background with minimal resource overhead, Squid continuously perceives your desktop activity: +- **Work Documents & Project Assets**: Documents, spreadsheets, presentations, design assets, and configuration files you create or update; +- **Task Scripts & Automation Pipelines**: Data batch processing, Python scripts, backup jobs, and shell commands running in your background terminals; +- **Desktop Application & Interaction Context**: Active application windows, focused UI controls, and text you are reading or selecting on your screen; +- **Web Research & Business Portals**: Project management boards (Jira, Linear, Notion), technical specifications, industry references, and browser tabs you explore. -Squid continuously distills these observations into a coherent **episodic world state**. When things go wrong or when assistance is needed, Squid already knows the full story — stepping in with timely insights and actions, while remaining strictly under your control. +Squid continuously distills these observations into a coherent **episodic world state**. When workflows hit an error, information needs cross-referencing between applications, or proactive execution is warranted, Squid already knows the full story — stepping in with timely insights, root-cause diagnosis, or workflow assistance, while remaining strictly governed by your explicit control. --- ## 🌟 A Day with Squid: Real-World Scenarios -### 1. ⚡ Terminal Errors? No More Copy-Pasting Stacks -You run a test suite or deployment command in your terminal (`cargo test`, `pytest`, `npm run build`) and hit a compiler error or assertion failure. -> **Without Squid**: You select text in the terminal, switch windows to a browser or chat window, paste the trace, and type *"why did this fail?"*. +### 1. 🔍 Cross-App Workflow Synthesis: From Web Briefs to Local Documents +You examine customer requirements, project tickets, or an industry whitepaper in your browser, then switch to a local spreadsheet, proposal draft, or configuration document to organize deliverables. +> **Without Squid**: You repeatedly switch between browser tabs and desktop apps, copy-pasting requirements into an AI chat window and prompting *"please summarize this against my open file"*. > -> **With Squid**: Squid hooks terminal completions. It already knows the command, the failure exit code, and the files you edited right before running it. It synthesizes the root cause immediately without you copying a single line. +> **With Squid**: Squid connects the dots between the reference page you just browsed and the local file you are editing. When you request a summary, consistency check, or proposal draft, it leverages the full context automatically without manual copying. -### 2. 🔍 Cross-Window Context: It Connects the Dots -You browse an open-source documentation site in Chrome, then switch back to VS Code to implement a function. -> **With Squid**: Squid notices the active browser tab URL and the code you are saving. When asked for suggestions or generating completions, it pulls context from the exact documentation page you were just looking at. +### 2. ⚡ Engineering & Script Failures: Instant Root-Cause Without Copy-Pasting +You run a data-cleaning pipeline, automated report generator, file conversion script, or deployment CLI command in the background, and it fails with an unexpected exit code or stack trace. +> **Without Squid**: You scroll back through noisy terminal output, find the error lines, paste them into a chat assistant, and explain what inputs or files you modified prior to running it. +> +> **With Squid**: Squid hooks command completions in real time. It already knows the failing command, the non-zero exit code, and the specific files or data you touched right before running it. It pinpoints the root cause immediately and can propose an automated fix or retry plan. + +### 3. 🧠 Interruption Recovery: Seamless Multitasking Context Memory +In the middle of cross-referencing complex data across multiple spreadsheets, an urgent phone call or impromptu meeting pulls you away. Thirty minutes later you sit back down at your desk: *"Where was I?"* +> **Without Squid**: You search through a dozen open windows, browser tabs, and folders trying to reconstruct your train of thought. +> +> **With Squid**: Squid maintains structured episodic memory. A quick glance at the panel gives you a concise recap of your immediate context prior to the interruption — e.g. *"You were comparing metrics between Sheet A and the Q3 Portal, working on section 2 of the summary document"*. -### 3. 🔕 Zero Distraction & Smart Notifications -Nobody likes an AI that interrupts every three seconds like an over-eager assistant. -> **With Squid**: Squid operates under an explicit *permission to do nothing* philosophy. It only triggers a desktop toast notification (Linux `notify-send`, Windows `Shell_NotifyIcon`, macOS `osascript`) **when it has actually executed a real action or file change**. If it is merely reading, thinking, or deciding no action is required, it stays 100% quiet. +### 4. 🗂 Proactive Personal Assist: File Triage & Repetitive Task Relief +You frequently download batches of invoices, research reports, or data exports into your Downloads folder, requiring recurring cleanup and organization. +> **Without Squid**: You periodically spend 20 minutes manually creating folders, renaming files, and dragging them into archives. +> +> **With Squid**: Squid observes incoming file patterns in your watched workspace. It can proactively suggest clean naming conventions and folder structures, and upon your confirmation, organize or process them automatically. -### 4. 🛡 Automatic Privacy Shields -You open your password manager or banking portal to grab an API token or verify a billing detail. -> **With Squid**: Squid detects the foreground application (`1Password`, `Bitwarden`, `KeePassXC`, or custom exclusions via `SQUID_EXCLUDE`). Screen and window capture immediately suspend until you switch back. Secrets, passwords, and tokens are scrubbed at the ingress before ever touching the database. +### 5. 🛡 Absolute Discretion & Automatic Privacy Shields +Nobody wants an overeager chatbot interrupting their focus every three seconds. +> **With Squid**: +> - **Permission to Do Nothing**: Squid follows an explicit zero-distraction philosophy. It triggers a desktop notification (Linux `notify-send`, Windows `Shell_NotifyIcon`, macOS `osascript`) **only when it has executed a concrete action or file change**. If it is merely observing, reading, or deciding no intervention is needed, it remains 100% silent. +> - **Automatic Privacy Shields**: The moment you switch to a password manager (`1Password`, `Bitwarden`, `KeePassXC`), online banking portal, or personal chat, screen and window capture immediately suspend. Secrets, tokens, and credentials are scrubbed at the ingress before reaching storage. --- @@ -68,13 +81,13 @@ Get started in under 60 seconds with no compilers or complex dependencies requir 1. Download the latest release zip for your OS from [GitHub Releases](https://github.com/salmonloop/squid/releases): - **Linux**: `squid-x86_64-unknown-linux-gnu.zip` - **Windows**: `squid-x86_64-pc-windows-msvc.zip` -2. Extract the archive. You will see two companion binaries: - - `squid-ui`: The high-performance desktop panel (double-click to open). +2. Extract the archive. You will find two companion binaries: + - `squid-ui`: The native desktop control panel (double-click to open). - `squid`: The background sensory engine (supervised automatically by `squid-ui`). 3. Launch `squid-ui`: - - It will open the sleek Fluent desktop panel and dock an icon in your system tray. - - On first launch, navigate to **SETTINGS** to connect your favorite LLM provider: - - **Cloud Providers**: OpenAI, Anthropic, DeepSeek, OpenRouter, etc. + - It opens the native Fluent desktop panel and docks an icon in your system tray. + - On first launch, navigate to **SETTINGS** to connect your preferred LLM provider: + - **Cloud Providers**: OpenAI, Anthropic Claude, DeepSeek, OpenRouter, etc. - **Local & Private Models**: [Ollama](https://ollama.ai/), vLLM, LM Studio, or any OpenAI-compatible `/v1` endpoint. --- @@ -98,7 +111,7 @@ cargo build --release --manifest-path ui/Cargo.toml bun run start ``` -`bun run start` runs `src/squid-app.ts`: it defaults your home directory as the watch root, sets up the platform domain socket or Windows named pipe, launches the release panel binary, and connects the ambient sensory loop. +`bun run start` executes `src/squid-app.ts`: it sets your home directory as the watch root, configures the platform domain socket or Windows named pipe, launches the release panel binary, and connects the ambient sensory loop. --- @@ -110,12 +123,13 @@ Squid delivers a native desktop UI built in **Rust with Slint 1.17** that is lig ┌─────────────────────────────────────────────────────────────┐ │ 🊑 SQUID [_] [□] [✕] │ ├────────────────────────────────────────────────────────────── -│ STATUS: Active · Watching /home/user/projects │ +│ STATUS: Active · Watching /home/alex/workspace │ │ Agent: Idle (Observed 14 events across 2 episodes) │ ├────────────────────────────────────────────────────────────── │ [ACTIVITY EVIDENCE] │ -│ • VS Code: saved src/api-client.ts (2m ago) │ -│ • Terminal: `bun test` exited with code 0 (1m ago) │ +│ • Browser: Reviewing "Q3 Operations & Architecture Plan" │ +│ • Document: Updated project-roadmap.xlsx (1m ago) │ +│ • Terminal: Script `sync-data.py` finished with code 0 │ │ │ │ [TRIGGER LEDGER] │ │ Triggered: 3 | Duplicate: 8 | Excluded: 1 | Coalesced: 4│ @@ -142,7 +156,7 @@ Squid can be configured via the **SETTINGS** tab in the desktop UI, through JSON ### General & Runtime | Environment Variable | Config Key | Default | Description | |---|---|---|---| -| `SQUID_WATCH_ROOT` | `watchRoot` | `$HOME` | Directory watched by the filesystem sensor. | +| `SQUID_WATCH_ROOT` | `watchRoot` | `$HOME` | Directory watched by the filesystem sensor (workspace, documents, or project root). | | `SQUID_PANEL_SOCKET` | `panelEndpoint` | Auto | IPC endpoint (`/tmp/squid-panel.sock` or `\\.\pipe\squid-panel`). | | `SQUID_NOTIFY` | `notify` | `desktop` | Notification mode (`desktop` or `off`). Only alerts when the agent acts. | @@ -161,29 +175,29 @@ Squid can be configured via the **SETTINGS** tab in the desktop UI, through JSON |---|---|---|---| | `SQUID_SCREEN_READER` | `screenReaderBackend` | Host native | Screen reader backend: UI Automation (Windows), `xdotool` (Linux), `synthetic` (test). | | `SQUID_SCREEN_POLL_MS` | `screenPollIntervalMs` | `1000` | Screen text polling frequency in milliseconds. | -| `SQUID_TERMINAL` | `terminalSource` | `off` | Enable terminal shell integration (`fifo`). | +| `SQUID_TERMINAL` | `terminalSource` | `off` | Enable terminal shell & automation task integration (`fifo`). | | `SQUID_TERMINAL_FIFO` | `terminalSourcePath` | — | Path to terminal FIFO or Windows Named Pipe (`\\.\pipe\squid-term`). | -| `SQUID_EDITOR_SAVES` | `editorSaveSource` | `off` | Enable editor save tracking (`fifo`). | +| `SQUID_EDITOR_SAVES` | `editorSaveSource` | `off` | Enable editor and document save tracking (`fifo`). | | `SQUID_EDITOR_FIFO` | `editorSavePath` | — | Path to editor save FIFO or Windows Named Pipe (`\\.\pipe\squid-editor`). | | `SQUID_BROWSER` | `browserSource` | `off` | Enable browser active tab tracking (`darwin` on macOS, or `synthetic`). | | `SQUID_CONTROL` | `captureGateBackend` | `off` | Enable pause/resume gate (`fifo`). | | `SQUID_CONTROL_FIFO` | `captureGatePath` | — | Path to pause gate FIFO or Windows Named Pipe (`\\.\pipe\squid-control`). | -| `SQUID_EXCLUDE` | `excludeApplications` | — | Comma-separated list of application names to exclude (e.g. `1Password,Vault`). | +| `SQUID_EXCLUDE` | `excludeApplications` | — | Comma-separated list of application names to exclude (e.g. `1Password,Bitwarden`). | | `SQUID_RETENTION_HOURS`| `retentionHours` | `off` | Hours of activity events retained in SQLite at startup. | --- ## 🛠 Under the Hood: Architecture & Philosophy -For engineers, contributors, and curious hackers, Squid is built with rigorous local-first and deterministic engineering principles. +For engineers, contributors, and curious hackers, Squid is built with rigorous local-first and deterministic engineering principles: ``` ┌────────────────────────────────────────────────────────────────────────┐ │ Sensory Ingress Adapters │ -│ Filesystem Screen Text Terminal Hook Editor Saves │ -└───────┬──────────────┬───────────────┬─────────────────┬───────────────┘ - │ │ │ │ - â–Œ â–Œ â–Œ â–Œ +│ Filesystem Screen / UI Text Terminal & Scripts Document Saves│ +└───────┬──────────────┬───────────────┬──────────────────┬──────────────┘ + │ │ │ │ + â–Œ â–Œ â–Œ â–Œ ┌────────────────────────────────────────────────────────────────────────┐ │ Capture Policy (Exclusion & Credential Redaction) │ └──────────────────────────────────┬─────────────────────────────────────┘ @@ -217,20 +231,20 @@ For engineers, contributors, and curious hackers, Squid is built with rigorous l ``` ### 1. Ingress Boundary & Credential Redaction -All events enter via [`src/capture-policy.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/capture-policy.ts). `RedactingCapturePolicy` deterministically scrubs API keys, AWS tokens, GitHub credentials, PEM blocks, and passwords before anything touches SQLite or memory. `ExcludingCapturePolicy` halts observation whenever blacklisted apps take the foreground. +All events enter via [`src/capture-policy.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/capture-policy.ts). `RedactingCapturePolicy` deterministically scrubs API keys, AWS tokens, GitHub credentials, PEM blocks, and passwords before anything touches SQLite or memory. `ExcludingCapturePolicy` halts observation whenever blacklisted apps take the foreground. ### 2. Append-Only SQLite Event Store & Stable Ordering -Events are stored in SQLite using WAL mode with `synchronous = NORMAL` ([`src/sqlite-event-store.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/sqlite-event-store.ts)). Events have canonical monotonic ordering ([`src/chronicle-ordering.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/chronicle-ordering.ts)), making offline replay, crash recovery, and state reconstruction 100% deterministic. +Events are stored in SQLite using WAL mode with `synchronous = NORMAL` ([`src/sqlite-event-store.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/sqlite-event-store.ts)). Events have canonical monotonic ordering ([`src/chronicle-ordering.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/chronicle-ordering.ts)), making offline replay, crash recovery, and state reconstruction 100% deterministic. ### 3. Episodic World State -Time gaps between bursts of activity delineate discrete episodes ([`src/episode.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/episode.ts)). Raw events are reduced into a compact `WorldState` snapshot ([`src/world-state.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/world-state.ts)). The agent inspects this world state rather than querying raw event logs. +Time gaps between bursts of activity delineate discrete episodes ([`src/episode.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/episode.ts)). Raw events are reduced into a compact `WorldState` snapshot ([`src/world-state.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/world-state.ts)). The agent inspects this world state rather than querying raw event logs. ### 4. Attention Sliding Window & Fast Decision Curation -- **Attention Window** ([`src/attention-window-extension.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/attention-window-extension.ts)): Before each turn, observations older than `attentionWindowMinutes` (default 15m) are trimmed from the working context, preventing context exhaustion over days of uptime. -- **Decision Curator** ([`src/decision-curator-extension.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/decision-curator-extension.ts)): Uses a lightweight classifier (`/v1/systemone` via Jev or Kev) to filter non-essential turns. Fails open on timeout or network error so the agent never hangs. +- **Attention Window** ([`src/attention-window-extension.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/attention-window-extension.ts)): Before each turn, observations older than `attentionWindowMinutes` (default 15m) are trimmed from the working context, preventing context exhaustion over days of uptime. +- **Decision Curator** ([`src/decision-curator-extension.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/decision-curator-extension.ts)): Uses a lightweight classifier (`/v1/systemone` via Jev or Kev) to filter non-essential turns. Fails open on timeout or network error so the agent never hangs. ### 5. Unified Cross-Platform Transport -[`src/endpoint-transport.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/endpoint-transport.ts) provides a uniform abstraction across operating systems: +[`src/endpoint-transport.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/endpoint-transport.ts) provides a uniform abstraction across operating systems: - **Unix**: Domain sockets for IPC, FIFOs (`mkfifo`) for shell and editor hooks. - **Windows**: Full support for Named Pipes (`\\.\pipe\squid-panel`, `\\.\pipe\squid-control`), powered by `Bun.listen({ unix })`. diff --git a/README_zh.md b/README_zh.md index b87cdd4..e1496c7 100644 --- a/README_zh.md +++ b/README_zh.md @@ -1,8 +1,8 @@ -# 🊑 Squid — 党倩候桌面级自䞻 AI 智胜䜓 +# 🊑 Squid — 桌面级党倩候䞪人自䞻 AI 智胜䜓

- 具有党倩候感知䞎持续记忆的自䞻桌面䌎䟣
- 静默感知工䜜区 · 深床理解䞊䞋文 · 关键时刻自䞻决断 · 䞀切党由䜠掌控 + 具有党局感知䞎持续情境记忆的䞪人自䞻桌面䌎䟣
+ 静默感知工䜜流 · 深床理解跚应甚䞊䞋文 · 关键时刻䞻劚补䜍 · 䞥守隐私尜圚掌控

@@ -14,7 +14,7 @@ Bun Slint Platform - Pi Agent + 䞪人自䞻智胜䜓 Tests License

@@ -23,40 +23,52 @@ ## 💡 䞺什么需芁 Squid -现圚的绝倧倚数 AI 猖皋䞎桌面助手郜是**被劚的对话框** -䜠圚终端跑测试遇到报错必须手劚选䞭倍制错误堆栈切到浏览噚或聊倩蜯件第十次向它解释项目架构再小心翌翌地提瀺它“垮我看看这是䞺什么”。 +现圚的绝倧倚数 AI 工具本莚䞊䟝然是**被劚的聊倩框** +无论䜠是圚分析䞚务数据、跚蜯件栞对亀付物、倄理办公文档还是运行自劚化脚本和工皋流氎线每圓需芁 AI 协助时䜠郜䞍埗䞍打断圓前的心流——圚䞍同应甚窗口闎来回切屏、截囟、手劚倍制堆栈日志或需求背景反倍向对话框解释“我刚才圚做什么”。 -**Squid 圻底打砎了这种割裂的䜓验。** +**Squid 圻底打砎了这种被劚䞎割裂的䜓验。** -Squid 是䞀䞪**长驻本地、具倇自䞻感知胜力的桌面 AI 䌎䟣**基于 [Pi Agent 运行时](https://github.com/earendil-works/pi-ai) 构建。它䞍再被劚等埅䜠喂送䞊䞋文而是圚后台静默、蜻量地感知䜠的日垞匀发工䜜 -- 䜠圚猖蟑噚䞭保存的项目代码文件 -- 䜠圚终端里执行的各种呜什䞎其退出状态码 -- 圓前桌面前台的掻跃窗口、聚焊控件䞎选䞭文本 -- 䜠圚浏览噚里正圚查阅的 API 文档或 GitHub Issue 讚论。 +Squid 是䞀䞪**长驻本地、具倇党局感知䞎持续情境记忆的䞪人䞻劚桌面智胜䜓Personal Autonomous Desktop Agent**基于 [Pi Agent 运行时](https://github.com/earendil-works/pi-ai) 构建。它**䞍是䞀䞪局限于写代码的 coding agent**而是䞀䞪面向**通甚工皋任务、日垞数字化工䜜䞎䞪人生掻**的随行助手。它圚后台以极蜻的资源匀销静默感知䜠的电脑掻劚 +- **工䜜文档䞎资料沉淀**䜠圚本地工䜜区创建、敎理或保存的各类文档、报衚、方案方案、讟计玠材䞎配眮文件 +- **任务脚本䞎工皋流氎线**䜠圚终端或后台运行的数据批倄理、自劚化脚本、数据同步䞎日垞工具呜什及其执行状态 +- **桌面应甚䞎亀互䞊䞋文**圓前桌面前台的掻跃应甚窗口、焊点控件䞎蟓入状态以及屏幕䞊正圚查阅的关键内容 +- **眑络调研䞎䞚务系统**䜠圚浏览噚里查阅的项目看板Jira、Linear、飞乊、Notion 等、行䞚资料、规范文档或䞚务后台。 -Squid 将这些持续的感官信号聚合䞺**连莯的场景化䞖界状态Episodic World State**。圓遇到错误或需芁垮助时Squid 已经知晓来韙去脉无需䜠做任䜕倍制粘莎即可自䞻给出诊断或蟅助执行 —— 并䞔党过皋䞥栌受䜠掌控。 +Squid 将这些持续的感官信号自劚汇聚䞺**连莯的情境化䞖界状态Episodic World State**。圓任务遇到匂垞、需芁跚蜯件比对信息、或者有繁琐的倚步骀任务需芁掚进时Squid 已经理解来韙去脉圚关键时刻䞻劚提䟛诊断掞察、资料䞲联或蟅助执行——并䞔所有产生实际圱响的操䜜郜䞥栌由䜠授权掌控。 --- ## 🌟 日垞䜿甚场景A Day with Squid -### 1. ⚡ 终端报错告别手劚倍制长篇堆栈 -䜠圚终端运行 `cargo test`、`pytest` 或 `npm run build`测试倱莥并抛出倧量报错。 -> **䌠统做法**圚终端里长按錠标选䞭、倍制、切窗口粘莎给 AI、敲键盘问“䞺什么挂了”。 +### 1. 🔍 跚应甚工䜜流穿透需求调研䞎本地方案的无猝呌应 +䜠圚浏览噚䞭查阅客户需求规范、项目管理工单或行䞚调研癜皮乊随后切换到本地办公蜯件劂电子衚栌、Markdown、技术方案草案或配眮文件䞭着手敎理䞎蟓出。 +> **䌠统做法**圚浏览噚䞎本地蜯件之闎反倍切屏手劚截取眑页段萜粘莎给 AI 聊倩框反倍叮嘱“请根据刚才的需求垮我修改这仜本地文件”。 > -> **Squid 䜓验**Squid 通过终端钩子实时感知到该呜什倱莥及非零退出码并自劚关联䜠刚刚圚猖蟑噚䞭修改的文件。圓䜠需芁时它已理枅根本原因甚至盎接准倇奜修改补䞁。 +> **Squid 䜓验**Squid 自劚捕获䜠刚阅读的眑页背景䞎正圚猖蟑的本地文件。圓䜠需芁梳理芁点、亀叉比对数据䞀臎性或起草方案时它已党面掌握党局䞊䞋文无需重倍喂送信息。 -### 2. 🔍 跚窗口联劚掞悉䜠的真实䞊䞋文 -䜠圚浏览噚里查阅䞀仜匀源框架的最新接口文档切回 VS Code 匀始实现具䜓功胜并保存。 -> **Squid 䜓验**Squid 胜同时捕获䜠刚看的文档眑页 URL 和保存的代码。圚提䟛代码建议或解答疑隟时它盎接结合䜠查阅的参考资料进行回答䞍再盲目瞎猜。 +### 2. ⚡ 工皋䞎自劚化脚本故障告别手劚翻扟日志䞎长篇堆栈 +䜠圚终端或后台运行数据枅掗管道、Python 自劚化脚本、文件栌匏批量蜬换工具或工皋亀付呜什呜什突然报错䞭断。 +> **䌠统做法**手劚滚劚终端屏幕、肉県搜寻报错行、倍制冗长的匂垞堆栈给 AI再莹力解释“运行前我改劚了什么文件”。 +> +> **Squid 䜓验**Squid 实时感知呜什行执行䞎非零退出状态码并自劚关联䜠圚运行前改劚的文件䞎蟓入数据。它胜立即理枅根本原因甚至盎接准倇奜排查建议或修倍重试方案。 + +### 3. 🧠 状态无猝扟回被打断后的倚任务情境记忆 +日垞工䜜䞭䞎时插入的玧急电话、䌚议或倚任务切换垞垞打砎䜠的思路。半小时后回到电脑前脑海䞭䞀片空癜“我刚才做到哪䞀步了” +> **䌠统做法**圚䞃八䞪打匀的应甚窗口、几十䞪浏览噚标筟页䞎文件倹里艰隟翻扟回忆刚才的进床。 +> +> **Squid 䜓验**Squid 具倇情境时序记忆Episodic Memory。只需看䞀県面板或随时询问它䟿胜䞺䜠梳理犻匀前的操䜜脉络“犻匀前䜠圚对比䞀仜采莭枅单的数据差匂并停留圚差匂分析文档的第二节”助䜠瞬闎扟回心流。 -### 3. 🔕 绝䞍打扰智胜静默通知 -谁郜䞍想芁䞀䞪每隔䞉秒就跳出来刷存圚感的话痚助手。 -> **Squid 䜓验**Squid 拥有明确的“无事䞍扰”哲孊。它通过系统通知䞭心Linux `notify-send`、Windows `Shell_NotifyIcon` 气泡、macOS `osascript`提醒䜠䞔**仅圓智胜䜓实际执行了产生圱响的操䜜劂修改了文件或执行了修倍呜什时才䌚匹出桌面通知**。若它只是圚阅读、思考或刀定无需干预系统保持 100% 静默。 +### 4. 🗂 䞻劚匏䞪人蟅助资料園档䞎重倍性劳劚减莟 +日垞从各类䞚务系统䞋蜜了倧量报衚、材料附件或富出的数据散萜圚䞋蜜或䞎时文件倹䞭或者经垞有呚期性的文件園类䞎栌匏蜬换需求。 +> **䌠统做法**定期花半小时手劚新建文件倹、重呜名文件、搬移園档。 +> +> **Squid 䜓验**Squid 胜䞻劚识别到特定工䜜目圕䞋新萜地的数据流䞎文件劚态结合䜠的历史工䜜习惯䞻劚建议规范分类、園档敎理方案并圚获埗䜠确讀后自劚执行将䜠从枯燥的杂务䞭解攟出来。 -### 4. 🛡 智胜隐私遮眩遇到密码自劚“闭県” -䜠需芁切到密码管理噚查扟数据库密钥或者打匀眑银查看莊单。 -> **Squid 䜓验**Squid 自劚检测圓前前台窗口。䞀旊进入敏感蜯件劂 `1Password`、`Bitwarden`、`KeePassXC` 或自定义黑名单屏幕䞎文字采集立即自劚挂起。各类密码、API Token 圚进入数据库前就已被底层正则衚蟟匏圻底枅掗绝䞍萜盘。 +### 5. 🛡 绝对克制䞎隐私守闚人“无事䞍扰”䞎敏感场景自劚遮眩 +谁郜䞍想芁䞀䞪每隔䞉秒就跳出来刷存圚感、打乱思考的吵闹助手。 +> **Squid 䜓验** +> - **无事䞍扰Permission to do nothing**Squid 只有圚**真正执行了实莚性改劚劂曎新了文件或执行了确讀后的修倍劚䜜**时才䌚通过系统通知䞭心Linux `notify-send`、Windows `Shell_NotifyIcon`、macOS `osascript`蜻量提醒。日垞阅读、感知䞎思考保持 100% 静默。 +> - **智胜隐私防技**䞀旊切换到密码管理噚劂 `1Password`、`Bitwarden`、`KeePassXC`、眑银页面或私密通讯蜯件屏幕䞎文字感知瞬闎挂起敏感 Token 䞎密码圚进入存傚前被底层圻底脱敏枅掗绝䞍萜盘。 --- @@ -111,12 +123,13 @@ Squid 采甹 **Rust + Slint 1.17** 打造原生桌面客户端秒级冷启 ┌─────────────────────────────────────────────────────────────┐ │ 🊑 SQUID [_] [□] [✕] │ ├────────────────────────────────────────────────────────────── -│ STATUS: Active · 正圚监听 /home/user/projects │ +│ STATUS: Active · 正圚感知 /home/alex/workspace │ │ 智胜䜓状态: 空闲 (圚 2 䞪时闎段内环计感知 14 䞪事件) │ ├────────────────────────────────────────────────────────────── -│ [掻劚证据 (EVIDENCE)] │ -│ • VS Code: 保存了 src/api-client.ts (2分钟前) │ -│ • 终端: `bun test` 执行完毕状态码 0 (1分钟前) │ +│ [掻劚证据 (ACTIVITY EVIDENCE)] │ +│ • 浏览噚: 正圚查阅《Q3 䞚务规划䞎系统架构讟计》 (2分钟前) │ +│ • 办公文档: 曎新了 project-roadmap.xlsx (1分钟前) │ +│ • 终端: 自劚化脚本 `sync-data.py` 执行完毕退出码 0 (30秒前)│ │ │ │ [觊发莊本 (TRIGGER LEDGER)] │ │ 觊发思考: 3 | 去重応略: 8 | 隐私排陀: 1 | 防抖合并: 4 │ @@ -143,7 +156,7 @@ Squid 采甹 **Rust + Slint 1.17** 打造原生桌面客户端秒级冷启 ### 运行时基础配眮 | 环境变量 | 配眮键名 | 默讀倌 | 诎明 | |---|---|---|---| -| `SQUID_WATCH_ROOT` | `watchRoot` | `$HOME` | 文件系统感知噚监听的根目圕绝对路埄。 | +| `SQUID_WATCH_ROOT` | `watchRoot` | `$HOME` | 文件系统感知噚监听的根目圕绝对路埄工䜜区或工皋根目圕。 | | `SQUID_PANEL_SOCKET` | `panelEndpoint` | 自劚匹配 | IPC 通信端点Linux 䞺 `/tmp/squid-panel.sock`Windows 䞺 `\\.\pipe\squid-panel`。 | | `SQUID_NOTIFY` | `notify` | `desktop` | 桌面通知通道`desktop` 或 `off`。仅圚智胜䜓实际劚䜜时匹出。 | @@ -162,9 +175,9 @@ Squid 采甹 **Rust + Slint 1.17** 打造原生桌面客户端秒级冷启 |---|---|---|---| | `SQUID_SCREEN_READER` | `screenReaderBackend` | 系统原生 | 屏幕捕获后端原生Windows UIA / Linux `xdotool`或测试合成 `synthetic`。 | | `SQUID_SCREEN_POLL_MS` | `screenPollIntervalMs` | `1000` | 屏幕状态蜮询采样呚期毫秒。 | -| `SQUID_TERMINAL` | `terminalSource` | `off` | 终端呜什感知匀关`fifo`。 | +| `SQUID_TERMINAL` | `terminalSource` | `off` | 终端呜什行䞎任务感知匀关`fifo`。 | | `SQUID_TERMINAL_FIFO` | `terminalSourcePath` | — | 终端钩子写入路埄Unix 䞺 FIFOWindows 䞺呜名管道劂 `\\.\pipe\squid-term`。 | -| `SQUID_EDITOR_SAVES` | `editorSaveSource` | `off` | 猖蟑噚保存感知匀关`fifo`。 | +| `SQUID_EDITOR_SAVES` | `editorSaveSource` | `off` | 猖蟑噚䞎文档保存感知匀关`fifo`。 | | `SQUID_EDITOR_FIFO` | `editorSavePath` | — | 猖蟑噚保存钩子写入路埄或 Windows 呜名管道 `\\.\pipe\squid-editor`。 | | `SQUID_BROWSER` | `browserSource` | `off` | 浏览噚标筟感知匀关macOS 䞋䞺 `darwin`其他平台䞺 `synthetic`。 | | `SQUID_CONTROL` | `captureGateBackend` | `off` | 捕获闚控匀关`fifo`支持通过管道发送 pause/resume 呜什。 | @@ -176,15 +189,15 @@ Squid 采甹 **Rust + Slint 1.17** 打造原生桌面客户端秒级冷启 ## 🛠 深床架构䞎实现细节Under the Hood -针对匀发者䞎系统莡献者Squid 遵埪䞥谚的本地䌘先、确定性䞎高可靠性架构 +针对系统匀发者䞎架构莡献者Squid 遵埪䞥谚的本地䌘先、确定性䞎高可靠性讟计 ``` ┌────────────────────────────────────────────────────────────────────────┐ -│ 倚绎床感官接入层 │ -│ 文件系统监听 屏幕/无障碍文字 终端执行钩子 猖蟑噚保存通知 │ -└───────┬──────────────┬───────────────┬─────────────────┬───────────────┘ - │ │ │ │ - â–Œ â–Œ â–Œ â–Œ +│ 倚绎床党倩候感官接入层 │ +│ 文件系统监听 屏幕/无障碍文字 终端䞎脚本执行 文档䞎文件保存 │ +└───────┬──────────────┬───────────────┬──────────────────┬──────────────┘ + │ │ │ │ + â–Œ â–Œ â–Œ â–Œ ┌────────────────────────────────────────────────────────────────────────┐ │ 捕获安党策略 (应甚屏蔜䞎凭据脱敏枅掗) │ └──────────────────────────────────┬─────────────────────────────────────┘ @@ -196,7 +209,7 @@ Squid 采甹 **Rust + Slint 1.17** 打造原生桌面客户端秒级冷启 │ â–Œ ┌────────────────────────────────────────────────────────────────────────┐ -│ 确定性场景时序切片䞎䞖界状态聚合投圱 │ +│ 确定性场景时序切片䞎䞖界状态園纊投圱 │ └──────────────────────────────────┬─────────────────────────────────────┘ │ â–Œ @@ -213,31 +226,31 @@ Squid 采甹 **Rust + Slint 1.17** 打造原生桌面客户端秒级冷启 â–Œ â–Œ â–Œ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ 系统桌面通知 │ │ 操䜜确讀对话框│ │ Slint 原生界面│ -│(执行变曎时觊发)│ │ (高风险劚䜜) │ │ 䞎系统垞驻托盘│ +│(执行变曎时觊发)│ │ (高风险劚䜜) │ │ 䞎系统垞驻托盘│ └───────────────┘ └───────────────┘ └───────────────┘ ``` ### 1. 入口级敏感凭据枅掗䞎应甚过滀 -所有事件统䞀进入 [`src/capture-policy.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/capture-policy.ts)。`RedactingCapturePolicy` 圚数据接觊存傚前确定性抹陀 API Key、AWS 访问凭证、GitHub 什牌、PEM 私钥及密码。`ExcludingCapturePolicy` 圚黑名单应甚倄于前台时瞬闎熔断所有捕获。 +所有事件统䞀进入 [`src/capture-policy.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/capture-policy.ts)。`RedactingCapturePolicy` 圚数据接觊存傚前确定性抹陀 API Key、AWS 访问凭证、GitHub 什牌、PEM 私钥及密码。`ExcludingCapturePolicy` 圚黑名单应甚倄于前台时瞬闎熔断所有捕获。 ### 2. 远加匏 SQLite WAL 事件存傚䞎回攟顺序 -事件通过 WAL 暡匏的 SQLite 存傚`synchronous = NORMAL`见 [`src/sqlite-event-store.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/sqlite-event-store.ts)。通过规范化排序契纊[`src/chronicle-ordering.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/chronicle-ordering.ts)犻线重攟、厩溃恢倍䞎状态还原具有 100% 确定性。 +事件通过 WAL 暡匏的 SQLite 存傚`synchronous = NORMAL`见 [`src/sqlite-event-store.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/sqlite-event-store.ts)。通过规范化排序契纊[`src/chronicle-ordering.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/chronicle-ordering.ts)犻线重攟、厩溃恢倍䞎状态还原具有 100% 确定性。 ### 3. 场景化䞖界状态園纊 (Episodic World State) -䟝据掻劚事件的时闎停顿自劚切分独立场景Episode见 [`src/episode.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/episode.ts)。原始时序事件由无副䜜甚的園纊噚聚合䞺宏观的 `WorldState` 快照[`src/world-state.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/world-state.ts)。智胜䜓每次决策只需审阅宏观䞖界状态避免遍历海量日志。 +䟝据掻劚事件的时闎停顿自劚切分独立场景Episode见 [`src/episode.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/episode.ts)。原始时序事件由无副䜜甚的園纊噚聚合䞺宏观的 `WorldState` 快照[`src/world-state.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/world-state.ts)。智胜䜓每次决策只需审阅宏观䞖界状态避免遍历海量日志。 ### 4. 泚意力滑劚窗口䞎亚秒级决策埮暡型 -- **泚意力滑劚窗口**[`src/attention-window-extension.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/attention-window-extension.ts)每次调甚暡型前自劚枅理超过时效默讀 15 分钟的旧观测蜚迹杜绝 Token 无限增长。 -- **决策裁剪埮暡型**[`src/decision-curator-extension.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/decision-curator-extension.ts)利甚 `/v1/systemone` 接口Jev / Kev毫秒级过滀无效蜮次。遇眑络错误自劚攟行Fail-Open䞍阻断䞻流皋。 +- **泚意力滑劚窗口**[`src/attention-window-extension.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/attention-window-extension.ts)每次调甚暡型前自劚枅理超过时效默讀 15 分钟的旧观测蜚迹杜绝 Token 无限增长。 +- **决策裁剪埮暡型**[`src/decision-curator-extension.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/decision-curator-extension.ts)利甚 `/v1/systemone` 接口Jev / Kev毫秒级过滀无效蜮次。遇眑络错误自劚攟行Fail-Open䞍䞭断䞻流氎线。 ### 5. 跚平台统䞀䌠蟓适配 -[`src/endpoint-transport.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-cf8f03cb/src/endpoint-transport.ts) 统䞀了操䜜系统闎的管道差匂 +[`src/endpoint-transport.ts`](file:///home/ubuntu/.t3/worktrees/squid/t3-b6252c25/src/endpoint-transport.ts) 统䞀了操䜜系统闎的管道差匂 - **Unix 系统**䜿甚文件域套接字进行 IPC䜿甚标准 FIFO`mkfifo`接入 Shell 䞎猖蟑噚钩子。 - **Windows 系统**原生支持呜名管道`\\.\pipe\squid-panel`、`\\.\pipe\squid-control`底层由 `Bun.listen({ unix })` 驱劚。 ### 6. 䞥谚的关机䞎泚销时序 `stop()` 䞥栌䟝䟝赖反序退出 -1. 停止各类感官源防止卞蜜过皋䞭产生残䜙事件 +1. 停止各类感官源防止卞蜜过皋䞭产生残留事件 2. 等埅并排干正圚执行䞭的智胜䜓蜮次 3. 泚销长驻智胜䜓䌚话并释攟资源 4. 关闭 SQLite 存傚并保存最终状态。 @@ -275,7 +288,8 @@ bun run ui:smoke 1. **栞心铟路完党犻线可测**事件收集、时序存傚、䞖界状态園纊以及 810+ 测试甚䟋党郚纯本地犻线执行无任䜕未经允讞的倖连请求。 2. **倚层敏感凭据脱敏枅掗**所有进入系统的窗口标题、代码片段䞎终端呜什必须通过 `RedactingCapturePolicy` 正则过滀杜绝各类密码、Token 䞎密钥被写入磁盘。 3. **应甚激掻隐私熔断**配眮黑名单应甚劂密码管理噚、眑银等倄于前台时Squid 立即阻断䞀切屏幕采集。 -4. **透明受控的暂停机制**无论是通过面板界面的“暂停记圕”按钮还是通过呜什向管道写入指什随时可圻底切断倖郚感知。 +4. **透明受控的暂停机制**无论通过面板界面的“暂停感知记圕”按钮还是通过呜什行向管道写入指什随时可圻底切断倖郚感知。 +5. **人圚回路Human in the loop**产生实际改劚的关键操䜜需经由人工亀互确讀框批准后方可执行。 ---