Holdog / 狗助

中文说明

Holdog 是一个轻量级个人工作助手，把聊天、文件处理、联网调研、浏览器自动化和本机工具操作收进同一个工作台。它采用 DeepSeek-only 运行时：本地文件、审批、任务历史、记忆和索引保存在用户电脑上，模型推理、任务拆解和屏幕分析通过 DeepSeek 完成。

当前版本聚焦一条实用主流程：

• 在 Holdog 工作台里直接发起任务和多轮对话。
• 让 DeepSeek 规划步骤，并把写作、编码、检索、总结和屏幕分析分派给不同能力。
• 在允许目录内搜索、读取、写入和打开本地文件。
• 读取和生成轻量 .txt、.docx、.xlsx、.pptx 文件。
• 建立本地 SQLite 文件索引，支持按内容查找资料。
• 图片输入和图库索引目前在主界面中暂缓开放，等图片 API 就绪后再进入正式流程。
• 支持联网搜索和可审批的 Playwright 浏览器会话。
• 对写文件、执行命令、截屏、浏览器自动化、打开应用等高风险动作保留审批机制。
• 在设置页配置 DeepSeek、允许目录、助手指令和每个工具的权限。

English Overview

Holdog is a lightweight personal work assistant that brings chat, file work, web research, browser automation, and local tool actions into one workspace. It uses a DeepSeek-only runtime: local files, approvals, task history, memories, and indexes stay on the user's machine, while planning, worker generation, and screen analysis are handled through DeepSeek.

This build focuses on a practical daily workflow:

• Start tasks and multi-turn conversations from the Holdog workbench.
• Let DeepSeek plan steps and delegate writing, coding, research, summaries, and screen analysis.
• Search, read, write, and open files inside approved local roots.
• Read and create lightweight .txt, .docx, .xlsx, and .pptx files.
• Build a local SQLite document index for content search.
• Image input and gallery indexing are currently deferred in the primary UI until the image API is ready.
• Keep image inputs and gallery indexing out of the guided release flow until the image API is ready.
• Use web search and approval-gated Playwright browser sessions.
• Keep risky actions such as file writes, shell commands, screen capture, browser automation, and app launching behind approval controls.
• Configure DeepSeek settings, allowed roots, assistant instructions, and per-tool permissions from Settings.

Quick Start

copy .env.example .env
python -m unittest discover -s tests
python -m holdog.server

Open http://127.0.0.1:8765.

Cloud Sync Entry

The online entry is only for account login, static UI delivery, and chat snapshot sync. File reads/writes, shell commands, app opening, browser automation, and screen analysis still run on the user's own local agent.

Cloud server:

npm run cloud

Local agent used with the hosted page:

set HOLDOG_PUBLIC_ORIGIN=https://example.com
npm run dev

Open https://example.com/holdog/. The hosted page talks to the cloud server at /holdog/api/... for login/sync/model quota and to http://127.0.0.1:8765 for local task execution.

For non-developer users, the hosted page shows a one-command local deployment panel when it cannot reach the local agent:

powershell -NoProfile -ExecutionPolicy Bypass -Command "Invoke-RestMethod 'https://example.com/holdog/install.ps1' | Invoke-Expression"

That script downloads the local package, writes the trusted cloud origin into .env, starts the local agent, and reopens the hosted page.

中文部署说明见 LOCAL_DEPLOY.md。面向普通用户时有三种路径：

1. 推荐：在网页复制一键命令，PowerShell 运行后自动安装并启动本地 Agent。
2. 备用：下载 install-holdog-local.ps1，用 powershell -ExecutionPolicy Bypass -File .\install-holdog-local.ps1 运行。
3. 手动：下载 holdog-local.zip，解压后复制 .env.example 为 .env，写入 HOLDOG_PUBLIC_ORIGIN=https://example.com 和 HOLDOG_ALLOWED_ROOTS，再运行 python -m holdog.server 或 scripts\start-holdog-local.ps1。

In hosted release mode, users do not need their own DeepSeek key. After login, the page binds the local agent to the cloud model proxy. The cloud server keeps the owner DeepSeek key on the server, enforces a default daily promotion quota of 500,000 tokens per account, and exposes quota status in the TOKEN panel.

Put your API key in .env or deepseek-api.txt:

DEEPSEEK_API_KEY=<your-deepseek-api-key>
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-v4-flash
DEEPSEEK_PRO_MODEL=deepseek-v4-pro

Architecture

Holdog follows the smaller DogA/LightDesk shape while keeping the Holdog UI:

• holdog.config loads DeepSeek and workspace settings.
• holdog.models.ModelGateway is the DeepSeek gateway for planner, worker, and screen analysis.
• holdog.agent.Agent owns tool execution, approval flow, follow-up actions, recovery, memories, and traces.
• holdog.tool_registry declares tool schemas, risk level, and agent role ownership in one place.
• holdog.server exposes a small standard-library HTTP API and serves the web UI.
• web/ contains the existing Holdog workbench UI.

Model routing is DeepSeek-only. The runtime has no fallback model server, separate vision endpoint, model-weight metadata reader, or model startup script.

Safety Model

Allowed roots define the filesystem boundary. By default, Holdog allows the project directory plus common user folders. Narrow this in .env or Settings before testing against important directories.

The local HTTP API is intended for the bundled UI on this machine. It now rejects untrusted Origin and Host headers, reflects CORS only for trusted local/Tauri origins, and caps JSON request bodies with HOLDOG_MAX_JSON_BODY_BYTES. Keep HOLDOG_HOST=127.0.0.1 unless you have a specific local network reason to expose it. Low-risk http_get/web_search requests are restricted to public HTTP(S) targets; browser automation for arbitrary sites remains an approval-gated action.

Low-risk actions run immediately unless you change their policy:

• list_dir
• search_files
• index_files
• search_file_contents
• read_file
• web_search
• http_get
• deepseek_task

High-risk actions require approval by default:

• write_file
• run_shell
• analyze_screen
• browser_task
• open_app
• open_path

Image-specific tools are still present in the backend for future work and internal compatibility tests, but the current guided release flow hides image inputs and returns a short deferred response for primary image requests.

Browser Automation

The one-click Windows installer prepares the browser runtime automatically: it installs a portable Node.js runtime under the Holdog install directory when the machine has no node, then installs the lightweight Playwright JS driver.

For manual source installs, run:

npm run browser:install

This installs the lightweight Playwright JS driver only. Holdog will use the system Microsoft Edge or Chrome executable when one is available, so the app package does not need to carry a Chromium browser. If a machine has no compatible browser, either install Edge/Chrome, set HOLDOG_BROWSER_EXECUTABLE to the browser path, or run:

npm run browser:install:chromium

Example prompts:

浏览器搜索 DeepSeek 工具调用
打开网页 https://example.com
继续浏览器提取当前页面
继续浏览器点击 Documentation

Browser tasks use a session_id such as default or research-1, so follow-up prompts can resume an existing Playwright session instead of starting from scratch.

Project Layout

holdog/
  agent.py       Agent orchestration and tool execution
  config.py      DeepSeek and path configuration
  models.py      DeepSeek model gateway
  safety.py      Risk classification and path guards
  server.py      Standard-library HTTP server
  storage.py     SQLite task and approval store
  tool_registry.py Structured tool catalog
web/
  index.html     Holdog workbench UI
  app.js         Browser-side interaction logic
  styles.css     Product UI styling
tests/
  test_*.py      Unit and API tests