# web2agent

**Repository Path**: jinfupeng/web2agent

## Basic Information

- **Project Name**: web2agent
- **Description**: 把网页版的豆包、deepseek等聊天功能转成本地agent
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-10
- **Last Updated**: 2026-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WebAI

WebAI 将各大平台网页对话能力本地化为可编程Agent，兼容DeepSeek、豆包、通义千问，支持本地文件读写、终端命令执行、云端历史会话复用，通过斜杠命令实时切换模型功能开关，面向开发者打造本地开发自动化助手。

## ✨ 核心功能
- 多模型源支持：DeepSeek / 豆包 / 通义千问，启动交互式选择，也支持命令行参数直接指定
- 云端会话加载：读取历史云端对话，或新建独立会话；支持会话删除管理
- 本地Agent工具集：文件创建/读取/追加/精准替换、目录扫描、终端命令执行、本地文件上传解析
- 自动识别系统标准目录：桌面、下载、文稿目录，支持绝对路径与自定义工作区
- 模型能力开关：深度思考、联网搜索一键切换
- 豆包双运行模式：浏览器交互模式 / 纯终端HTTP模式，互相独立
- 终端斜杠命令自动补全：输入 `/` 唤起交互式命令菜单，实时筛选匹配指令
- 文件上传能力：支持上传本地文档、图片交付模型解析
- 跨平台兼容：macOS / Windows / Linux / Termux(Android)

## 📋 环境要求
- Python 3.10+
- 豆包浏览器交互模式：本地安装Google Chrome
- 扫码登录依赖：
  - DeepSeek：微信扫码
  - 豆包：豆包App扫码
- 二维码显示：可选择独立图片窗口，或启动仅监听 `127.0.0.1` 的临时服务并在浏览器显示；不再向终端绘制二维码
  - PC桌面系统：`zxing-cpp`
  - Termux：预编译ZBar

### 依赖安装
基础终端版本（无浏览器组件）
```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
```

如需豆包浏览器交互模式，安装浏览器可选依赖
```bash
python -m pip install -r requirements-browser.txt
```

#### Termux Android 专用安装流程
Termux不支持Playwright，同时缺少预编译zxing-cpp、jiter包，使用ZBar解码二维码：
```bash
pkg update
pkg upgrade
pkg install python zbar dbus rust clang nodejs
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-termux.txt
```
> 常见故障：Node.js OpenSSL版本冲突
```bash
pkg reinstall openssl nodejs
```

#### Windows PowerShell 虚拟环境激活
```powershell
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-browser.txt
```

## 🚀 快速启动
先配置环境：
```bash
python check.py
```
`check.py` 是 Windows、macOS、Linux 和 Termux 共用的唯一环境配置入口。
它会安装缺失的二维码工具、创建或复用 Python 环境，并在 Termux 自动选择
`requirements-termux.txt`。脚本只负责配置环境，不会启动程序。
已自行准备系统包时，可先设置 `SKIP_SYSTEM_PACKAGES=1` 再运行。

环境准备完成后，由用户启动：

```bash
python main.py
```

Windows PowerShell 和 CMD 也统一运行 `python check.py`，不需要选择
PowerShell、CMD 或 Shell 专用脚本。

启动流程：
```

## 🔌 为其他程序提供 AI 能力

需要让 `tx_kaihu` 等程序调用 DeepSeek、豆包或通义千问时，运行：

```bash
python main.py
```

在模型来源菜单中选择“仅启动 AI 服务”。也可直接执行
`python -m webai_gateway`，用于自动化部署。

主菜单中的“AI/MCP 服务帮助”会显示启动方法、鉴权方式、模型发现、
任务上传与执行接口及 Python SDK 示例。当前对外提供的是本机 HTTP JSON
Gateway；标准 MCP Server 传输协议尚未开放。

默认监听 `http://127.0.0.1:8765`，首次启动会生成权限为 `0600` 的访问
令牌 `~/.config/webai/gateway_token`。网关提供来源枚举、任务创建、材料
上传、执行、状态查询和清理接口。扫码、账号登录、Cookie、Playwright
浏览器验证及各平台协议全部由 `web2agent` 维护。

Python 调用方可使用同仓库的轻量 SDK：

```python
from webai_client import WebAIClient

result = WebAIClient().analyze(
    provider="qwen",
    source="/path/to/materials",
    prompt="请分析材料并返回结构化结果",
    output_schema={"type": "object"},
)
```

网关默认仅允许本机访问；跨机器使用时应通过 SSH 隧道或 HTTPS 反向代理，
不要把监听地址和令牌直接暴露到公网。
请选择模型来源
1. DeepSeek
2. 豆包
3. 通义千问
4. 仅启动 AI 服务
5. AI/MCP 服务帮助
```

选择豆包后，先选择登录方式，再选择运行模式：
```
来源：豆包

登录阶段
1. 使用本地登录凭证（默认）
2. 豆包 App 扫码重新登录

请选择豆包运行方式
1. 浏览器交互方式
2. 终端方式
0. 返回登录方式
```
随后选择云端历史会话或新建会话，即可开始对话。

会话快捷操作：输入会话序号快速切换；支持 `d 1` / `d1` 删除对应序号会话，删除后会话列表自动刷新。

## ⌨️ 命令行启动参数
```bash
# 指定工作目录
python main.py --workspace /path/to/project

# 直接指定模型源
python main.py --source deepseek
python main.py --source doubao
python main.py --source qwen

# 指定豆包运行模式
python main.py --source doubao --doubao-version browser
python main.py --source doubao --doubao-version terminal

# 强制重新扫码登录
python main.py --source deepseek --login
python main.py --source doubao --doubao-login

# 单次任务执行，执行完成自动退出
python main.py --source doubao --doubao-version terminal "查看当前目录结构"

# 查看全部参数说明
python main.py --help
```

### 凭证传入方式
- **豆包**：`--doubao-cookie` 参数 / 环境变量 `DOUBAO_COOKIE`
- **DeepSeek**：`--token` / `--cookie`，环境变量 `DEEPSEEK_TOKEN`、`DEEPSEEK_COOKIE`

### 通义千问登录选项
```
登录阶段
1. 使用本地登录凭证（默认）
2. 账号密码登录
```
凭证优先级：`~/.config/webai/qwen_credentials.json` > 项目目录 `chat.qwen.ai.har`
账号密码登录仅持久化短期Token，不会保存账号密码，凭证文件权限自动设置为 `0600`。

## 🧩 豆包两种运行模式对比
### 浏览器交互模式
- 基于受控本地Chrome页面通信，签名逻辑由网页原生执行
- 浏览器窗口可见，滑块验证可手动完成，程序自动等待重试
- 页面/窗口关闭后，需要重启交互模式

### 纯终端模式
- Python HTTP/SSE客户端直连接口，不启动浏览器、不依赖HAR文件
- 独立持久化终端设备标识，复用扫码Cookie收发消息
- 遇到风控、滑块验证会直接抛出错误，不会自动切换浏览器

> 两种模式共享登录凭证，通信实现完全隔离
> 终端设备配置持久化路径：`~/.config/webai/doubao_terminal.json`

## 🔐 登录与凭证存储
- 豆包扫码凭证：`~/.config/webai/doubao_cookie.json`，文件权限 `0600`
- DeepSeek：微信扫码 + SQLite凭证存储
> 重要提醒：Cookie、Token、HAR文件包含账号凭证，禁止提交Git、转发他人；凭证泄露请立即网页端下线账号并重新登录。

## ⚡ 斜杠内置命令
输入 `/` 唤起命令菜单，方向键选择回车补全；持续输入字符实时过滤。

### 豆包可用命令
```
/model          切换模式
/model normal   普通模式
/model expert   专家模式
/help           查看命令列表
/exit           退出程序
```

### DeepSeek / 通义千问可用命令
```
/model          打开能力配置
/thinking on|off 深度思考开关
/search on|off    联网搜索开关
/help           查看命令列表
/exit           退出程序
```

通用全局命令：
```
/upload_file /path/to/file   预上传本地文件，跟随下一条消息发送
/back                        返回会话选择界面，清空待上传附件队列
```
> 文件路径包含空格时，使用引号包裹路径；上传成功附件仅保留至下一条消息发送完成后自动清空。

## 🛠 Agent 可用本地工具
模型可自主调用以下工具执行自动化操作：
```
read_file        读取UTF-8文本文件
write_file       创建或完整覆盖文本文件
append_file      分段追加文本，规避长文本截断
replace_in_file  文件内精确替换唯一文本片段
list_files       Glob模式遍历目录文件
run_command      在指定工作区执行终端命令
upload_file      上传本地文件供模型解析（图片/文档）
```
Agent 启动时还会探测本机常用命令，并把实际可用情况提供给模型：
- `rg` 搜索文件内容，`fd`（部分Linux为 `fdfind`）搜索文件名
- `jq` 处理JSON，`git` 检查版本库，`bat` 和 `eza` 增强只读展示
- 未安装时自动改用内置文件工具或系统兼容命令，不会假定命令存在
- `fzf`、`lazygit`、`yazi` 属于交互式TUI，默认不在无人值守命令中调用

路径规则：
- 相对路径基于 `--workspace` 指定目录
- 用户指定桌面、下载、文稿、绝对路径时，优先使用目标路径，不强制重定向至项目目录
- 自动适配macOS/Windows/Linux系统用户目录规范

## 📎 文件上传限制
- DeepSeek、通义千问：使用网页原生STS/OSS上传，支持多类型文件
- 豆包当前限制：≤1MiB UTF-8文本、代码、JSON文件；图片、PDF、Office二进制文件原生上传暂未实现
- Agent长文件处理：推荐分段使用 `write_file` + `append_file`，防止单次调用载荷超限

## 📂 项目目录结构
```
main.py
webai_app/
  cli.py          交互流程、会话管理、命令行入口
  contracts.py    模型源扩展抽象协议
  agent.py        Agent本地工具调度、OpenAI兼容协议适配
  registry.py     模型源注册中心
  providers/
    deepseek.py   DeepSeek适配实现
    doubao.py     豆包双模式适配实现
    qwen.py       通义千问适配实现
deepseek_app/     DeepSeek网页协议、登录、凭证存储
doubao_app/
  client.py       豆包终端HTTP/SSE客户端
  login.py        扫码登录、Cookie持久化
  browser.py      浏览器交互运行时
qwen_app/         通义千问登录与客户端实现
tests/            单元测试用例
requirements*.txt 多平台依赖清单
```

## 🔌 新增模型源扩展指南
1. 在 `webai_app/providers/` 创建新模块
2. 实现 `contracts.Source`、`contracts.SourceFactory` 抽象接口
3. 在 `webai_app/registry.py` 注册Factory
> CLI交互、Agent工具循环、工作区能力完全复用，新模型源仅需实现认证、会话列表、消息生成、可选文件上传与模型参数配置。

## ⚠️ 常见错误说明
- 凭证失效：重新扫码登录
- 豆包 710022004：触发安全风控，优先尝试浏览器模式完成验证
- Agent工具JSON截断：提示模型拆分任务，长文件使用分段写入
- 浏览器交互模式异常关闭：重启交互模式
- Termux Node.js报错：执行pkg重装openssl与nodejs

## 📄 许可证
本项目仅供个人学习研究使用，请遵守各大模型服务商用户协议。